Websydian v6.1 online documentationOnline documentation - WebsydianExpress v3.5

Retrieving Process Parameters

Introduction

As a new feature, WebsydianExpress 2.0 offers the option to specify parameters for the developed business processes.

This document describes how it is possible to retrieve the parameter values for these parameters in the developed programs.

There are two different situations, where it is possible to specify values for the parameters:

  1. On menu services (links specified internally in the application).
  2. On links generated in external applications

In both cases, the parameter values will be specified as part of the URL generated for the link.

The major difference between the two cases are that in the first case, where the WebsydianExpress runtime generates the URL, it is possible to secure the parameter using a signature. This is not possible for the URLs generated by external applications.

Retrieve menu service parameters

The data are retrieved in the ProcessEntryPoint function by calling the GetProcessParm API once for each parameter field that can be specified on a menu service.

This API will return the values specified for one parameter field based on the name of the parameter. If the parameter has not been specified for the menu service, the API returns a blank value.

If the parameter signature (see below) has been removed from the URL, the API will return blank for all parameters.

The calls to the GetProcessParm API must be made before the PageGenerator is called.

Special Considerations

When the parameters are specified on a menu service, they are actually written to the web page as parameters for the URL generated for the menu service. This means that the end user will be able to see the parameter fields and their values in the generated web page. Unfortunately, this also means that user will be able to specify other values for parameters than the ones generated by the application.

It is not possible to prevent the user from changing the parameters - but when the runtime generates the link based on the menu service, it also generates a parameter signature that is based on all of the parameters specified for the menu service.

When the runtime receives the request based on the URL, a signature check is performed, ensuring that the parameters are unchanged.

If the values for the parameters are changed the signature check will result in an error - and an error page will be shown to the user instead of the first page of the business process.

As an example of the cases which this is meant to prevent, imagine a link where a customer id is part of the URL - the business process will show all orders for this customer. In almost all cases you must ensure that the user can't be shown the orders for another customer. The signature check ensures that if the customer number is changed, the business process will not be called and the data for the customer will not be shown.

It is possible for the user to remove the generated signature - this will mean that the signature check will not be performed by the runtime. In this case, the business process will be called, but all calls to the GetProcessParm API will return a blank value.

Retrieve parameters from external links

The data are retrieved in the ProcessEntryPoint by calling the GetInput API once for each parameter field that can be specified on an external link.

This API will return the  values specified for one parameter field based on the name of the parameter. If the parameter has not been specified for the external link, the API returns a blank value.

The calls to the GetInput API must be made before the PageGenerator is called.

Special Considerations

It is important to realize that the data received as parameters from external links are not in any way secured. The data must be handled as ordinary input fields in which a user can enter any value.

Even in cases where an external application generates the link based on information stored in the database of the external application, there is nothing that prevents anybody to change the values of the parameters and resubmit the changed URL - and there is no way to detect that such a change has been made.

This means that just as you need to validate data entered in an input field, you must also validate the data received as parameters on external links.

An example of what you should not use parameters from external links for would be to transfer the customer id - and then let the business process show all orders for the customer (or other customer related data).

If you do need to transfer data that must not be changed, you must work together with the developers of the external application to create a method to ensure the integrity of the parameters.

Related Information

2E GetProcessParm
2E reference documentation of the GetProcessParm API.
2E GetInput
2E reference documentation of the GetInput API.
RPG GetProcessParm
RPG reference documentation of the GetProcessParm API.
RPG GetInput
RPG reference documentation of the GetInput API.
Menu Service
General information about menu services.
External Link
General information about linking to WebsydianExpress business processes from external applications.