Parameter Mappings

Outdated documentation page

This is an old version of the documentation for Flowable until version 3.13 and for the Angular-based Flowable Design 3.14/3.15. If you are running the latest version of Flowable please check out the current version of this page.

A service operation has zero or more input parameters and zero or more output parameters as part of its definition. These parameters define what kind of data the service expects when invoked and how the result looks like. For REST services there is an additional zero or more error output parameter mappings. This mapping is only applied if the request resource responded with a status code of 3xx, 4xx or 5xx. If an error occurs and an error output parameter mapping is defined, the output parameter mapping is ignored. However, it does not define how this data gets mapped into the process or case. As service definitions get reused between different models, this means that the same service can get and produce data in a different way depending on the parameter mapping.

The options for the parameter mapping are defined by the service definition and can be configured through the input parameters and output parameters attributes. This popup is automatically displaying the parameters defined in the service definition.

note

In older versions, the technical name is also displayed in this UI and the UI's below. This has been removed in later versions, as it added little value.

Suppose that the service operation has one input parameter, the popup would be as follows:

Similarly, for the output parameters:

When no parameters are defined, no mapping is needed.

Input parameters define what kind of data the service expects when it is invoked. Depending on the type of the parameter, the following values are supported in the value column of the input parameter popup:

note

In the list below, when an expression is mentioned, this expression has access to all variables of the current process instance or case instance. Also the uses of ${parent.var} and ${root.var} are supported. In addtion you can use ${scope.var} to reference the current instance (case or process). You can use ${scope.definition.attr} to access any attribute of the current instance definition.

• String

• A literal value that is passed as-is.

• An expression. This could be simply to concatenate variables (e.g., ${var1}-${var2}) or to call a bean (e.g., myBean.doSomething(someVariable)).

• Integer | Long | Double

• A literal value that is passed as-is (e.g., 123, 12.3, etc.).

• An expression that resolves to a numerical value.

• Boolean

• A literal 'true' or 'false'.

• An expression that resolves to a Boolean value.

• Date

• A literal ISO8601 formatted text string.

• An expression that resolves to a date (java.util.Date or a Joda-time LocalDate or LocalDatetime).

• JSON

• A literal JSON text string (e.g., { 'field': 'value' })

• An expression that resolves to a JsonNode instance.

• Array

• A literal JSON array string or a comma-separated list of text values.

• An expression that resolves to an ArrayNode instance.

In all cases, when a default value is provided as part of the service definition, the default value is used if no data is passed for that input parameter.

info

The input parameter mapping defines how process or case instance data is mapped to the input parameters of the service. In such a mapping, variable values (typically expressions) are referenced as the value for the parameter. The output parameter mapping, on the other hand, defines how the data produced by calling the service maps back into the process or case instance.

For an output mapping:

• If the Target Expression is a literal value, this is the name of the variable into which the output parameter value is stored.

• If the Target Expression is an expression, a writable variable is expected. For example, ${root.var} is such a variable.

In either case, type coercion (the same as described above for the input mapping) based on the type of the output parameter is applied.

Advanced Attributes

The service registry task has two advanced attributes:

• Save output variables as transient variable.

• Output variable name.

When the 'Save output variables as transient variable' is checked, all output variables are stored as transient (i.e., non-persisted) variables. This is useful when a service returns data that is not needed to be stored in the process or case instance (e.g., the data is only used in a calculation or as input for another service call).

When the 'Output variable name' is filled, no output parameter mapping is applied. The result of the service call is to be stored as-is under the given variable name. This attribute is important, when dealing with list values (arrays).