Skip to main content

REST Parameter

REST Input Parameters​

The input parameters of a REST-based service model operation are straightforward, as they define the inputs of the operations. The values of the input parameters are typically used in the URL (using the technical name such as ${myInputParameter}) or in the body of the request, when doing a POST request.

  • Label : This is the human-readable name for the input parameter.
  • Name : This is the technical name of the parameter, as used at runtime by the engine logic. It can be referenced in the URL using ${myInputParameter}.
  • Type : The type of the input.
  • Description : The description of the input parameter name for documentation purposes.
  • Required : Whether the input parameter is required.
  • Default Value : The default value to use in case the parameter has not been provided. Can be a fixed value or an expression. For example, if you want to initialize an empty string as default value for a String, you can use ${''}.
  • Query Parameter : Checking the box identifies the parameter as a query parameter.

An example of using input parameters in the URL part of the service operation configuration is shown in the following image:

06_01 advanced attributes

The parameters can, of course, be referenced anywhere in the URL string e.g. clients/${clientId}

REST Output Parameters​

The options for an output parameter are a bit more complex, as the configuration needs to be flexible enough to be able to process a variety of different JSON responses of calling REST API's:

  • Label: This is the human-readable name for the parameter.
  • Source: The source of the output parameter data.
    • Default: The response body is the source of data and output parameter are processed as usual.
    • Full Response body: The body as a whole will be used. The possible types are limited to JSON, Array or String.
    • All response headers: All response headers are stored in an array like [{key:'Content-Type',value: 'application/json'}].
    • Specific response header: A specific header is extracted from the response headers. The header name is case-insensitive.
    • Status code: The response status code.
  • Name: This is the technical name of the parameter, as used at runtime by the engine logic. If no other options are configured, this value is used to find in the JSON response a field with this specific name.
  • Type : The type of output parameter.
  • Body Location: Allows to map the output value to a more complex field with dots, like customer.name.
  • Excluded from body: Only relevant for input parameters.
  • Path: Uses JSON pointer syntax to allow navigation through nested JSON structures like /customers/0/name to indicate where the value can be found.
  • Mapping name: In certain exceptional situations, it could be that names overlap. For example, assume that a REST API returns { buyer: { name: 'a' }, seller: { name: 'b' }} as response. Both will map to the technical name and at runtime, the BPMN/CMMN service task will not be able to know which name value should be taken. To solve this, a different mapping name value should be given to allow the runtime to distinguish.
  • Map on error: The flag to mark the output parameter as error output parameter.