Passing data to the process

Mapping form data to BPMN process variables

Integrating the request (form) with the BPMN process (the EximeeBPMS engine, in the case of the Eximee platform) requires mapping the data from the request model to process variables. Thanks to this, the data entered by the user in the form can automatically feed the workflow process (e.g. used in decision gateways, script tasks, or passed to services).

To enable the data mapping mechanism from the request to the process, two basic configuration steps must be performed:

1. Adding a special session variable use-model-mapping – in Eximee Designer, in the request's session variables panel (available from the application configuration level), add a variable named use-model-mapping and set its default value to "true". This is a control flag for data integration; its presence informs the platform that model-to-process data mapping should be active for the given request. If this variable is missing (or set to false), the form data will not be automatically passed to the BPMN process.
2. Configuring field-to-process-variable mapping – when the mechanism is enabled, it becomes possible to define which data model fields should correspond to which variables in the EximeeBPMS process. In Eximee Designer, this is done in the Data Model tab in the mapping section (or alternatively directly in the form's source XML, in the <ecModelMapping>element). Appropriate mappings, where we indicate:

   • Mid (Mapping ID) – the identifier of the source field (request). In practice, this is the component identifier associated with the component whose value we want to pass. In the Designer interface, this column may be labeled "Mid" and is usually filled in with, for example, the business ID of the form field.
   • External / UniFlow ID – the name of the variable in the BPMN process to which the data should go. This is exactly the name of the process variable visible in the process definition (e.g. in EximeeBPMS Modeler). In this column, we therefore provide the target variable key.

After adding the mapping entries, the platform will automatically associate the indicated fields with the appropriate process variables. In practice, this means that when starting the process (starting a BPMN instance) or sending a token to the next step:

• the system will retrieve the values of the fields defined in the mapping from the data model,
• it will create process variables with the names given in External ID,
• it will assign the corresponding values from the request to those variables.

For example, if the request contains a field Company tax ID associated with the model under the key nip, and in the BPMN process we want to use a variable named companyTaxId, then after setting the mapping MID = nip and External ID = companyTaxId, the engine will create the variable companyTaxId and pass to it the value from the field nip of the application.

Mapping configuration can be saved in the form definition in an XML block. Below is an example of a request source-code fragment with model mapping enabled (ecModelMapping):

<saveActions> 
    <!-- ... EximeeRouter2 configuration ... -->
</saveActions>
<ecModelMapping>
    <modelMappings>
        <processes/>
        <mappings>
            <!-- Mapping the "phone" field from the request to the "phoneNumber" variable in the process -->
            <mapping mid="telefonKontaktowy" externalId="phoneNumber" dataType="" 
                     rewrittenFromNestedComponent="false"/>
            <!-- (additional mappings if needed) -->
        </mappings>
        <groups/>
    </modelMappings>
</ecModelMapping>

In the above example, the form field with the identifier (model key) telefonKontaktowy will be mapped to the process variable phoneNumber. The dataType attribute was left empty – the EximeeBPMS engine usually recognizes the type of a simple variable (e.g. string, number) on its own based on the value, but it can be used if an explicit type needs to be specified.

Note: Adding the mapping in Data model is not enough – you also need to make sure that the request actually starts the process. For this purpose, in the request definition (the Steps tab in Designer) there should be added Application save point with a component of type EximeeRouter2, indicating the appropriate BPMN process (parameter Process name = process definition key). Additionally, if we want to assign a Business Key to the process (a unique case/business identifier), it can be specified in the Router configuration (parameter Case number = e.g. a value from a form field or generated one) – otherwise it will default to the request number as the Business Key.

Synchronizing data between the request and the process

Thanks to the data model mapping mechanism, data synchronization between the request and the process happens automatically at moments of communication between them. A typical integration scenario looks as follows:

1. Filling out the form by the user: The user enters data into the fields on the request screen (form).
2. Saving and starting the process: When the user finishes filling out and saves the request (e.g. clicks "Send" or goes through the save step), the EximeeRouter2 component attached at the save point is activated. If the session variable use-model-mapping = true, Router2 initializes the associated BPMN process passing the data to it. The values from the request are retrieved according to the list of defined mappings and passed as process variables. As a result, the process starts with populated variables (e.g. companyTaxId, firstName, nip etc.), which can be used within the process flow.
3. Using data in the process: The BPMN process, already having assigned variables, can use them in decision gateways, scripts, service tasks, and user tasks. For example, a variable passed from the form may determine the choice of path in a gateway (based on a condition), or be passed to an external service in a service task. At this stage, the data "live" as part of the process state in the BPMN engine.
4. User task forms (optional): If the BPMN process has steps of type User Task, which require user interaction on the next form (e.g. an employee verifies the request at a second stage), the Eximee platform allows the next form to be displayed in the context of the ongoing process. How does synchronization happen? When the process reaches a User Task, this task can be handled by Eximee Dashboard – the user opens the task handling form, and the system binds it to the existing process instance. Thanks to this, the form "knows" which instance it operates in the context of. If we previously set model mapping in the initial request, the same mapping can be applied in the task handling form so that the process variable values are loaded into the variables of this form. This is done by defining the same model key and process variable name in the mapping (with the active use-model-mapping). For example, if the process contains a variable approvalDecision, and our task form has a field decision, then by configuring the mapping (Mid = decision, External ID = approvalDecision) we will cause the value of the variable approvalDecision to be filled into the field decision. The platform ensures synchronization – the Router2 mechanism reads the current values of the process variables and updates the User Task form values. The user can then change/add information and save the task form.
5. Updating variables when closing a User Task: When the user fills in the task form and saves it, then the mapping mechanism works again – this time saving changes from the form model back to the process variables and completing the user task (the process token moves on). This way, the process always has up-to-date data from the latest user actions.
6. Continuing and completing the process: The BPMN process can go through subsequent stages (e.g. further user tasks, service tasks). At the end, when the process is completed, the data collected in the process variables can be saved to target systems, etc., depending on the logic.

In the above data flow, it is key to understand that the request data model acts as an intermediary between the presentation layer (the form) and the process layer (the BPMN engine). Data flows from the form, through the model (application memory), to the process variables and possibly back again, if subsequent forms are part of the process. The user does not have to manually extract or pass these values – the platform mechanism does it for them, provided the mapping and integration have been configured correctly.

Note: For the data transfer mechanism to work, the request save-point configuration must contain a <variables>section. EximeeRouter2 uses it to pass variables to the process. Even if we are not passing additional variables that condition the flow, the <variables> section should be present (even if empty). In the case of data mapping, it usually contains at least an entry for the Business Key. If it is missing, the process may not start correctly or be associated with the data.

Example of a minimal variables section in the request definition (source in the Source request tab, inside the <saveActions>):

<variables>
    <entry>
       <key>businessKey</key>
       <value>${formInstanceNumber}</value>
    </entry>
</variables>

The above configuration passes the variable businessKey set to the number of the current request (which ensures a unique association of the process instance with a specific request). The value ${formInstanceNumber} is a predefined session variable containing the request number.

If we want to pass additional variables for synchronization or process resumption, we can add them here. For example, by adding:

<entry>
   <key>nip</key>
   <value>${nip}</value>
</entry>

it will cause the process to be started or resumed (if it was waiting) using the value nip from the request. The EximeeRouter2 mechanism can find a waiting process instance (e.g. waiting for a message/signal) and move it forward based on a variable value match.

Parameter use-model-mapping – what is it and when should it be used?

use-model-mapping is the name of a special session variable (flag) in the request configuration that enables automatic data mapping between the request's data model and BPMN process variables. By default, forms do not pass their data to processes – they operate independently. Setting use-model-mapping = true signals to the platform that the given request is integrated with the process and requires data transfer to the process.

When to use use-model-mapping? Always when:

• The request is to be started within an EximeeBPMS process or
• The request will be used as a user task form within the process.

If the form is not associated with any process (e.g. it is a standalone form for collecting data without workflow, or integration with the process happens in another way), then we do not set this flag.

In practice, in standard scenarios, if in Eximee Designer we add in Step Application save point the EximeeRouter2 element and specify the process name, you should immediately add the variable use-model-mapping = true and configure model mapping. Without this, the process will start, but it will not receive data from the request (process variables will remain empty or take default values, which most likely is not the intended effect).

The flag use-model-mapping can also be set conditionally – e.g. if the same form is sometimes to be launched with a process and sometimes without (depending on the scenario), you can control the value of this variable. Usually, however, it is a fixed configuration at the request level.

In summary: use-model-mapping = true enables the “bridge” for data between the request and the process. Without this bridge, the request and the process operate completely independently, and any information transfer would require manual programming (e.g. through custom EximeeBPMS API calls). Therefore, it is worth remembering this variable for every form-to-process integration.

Example data flow from the form to the process

Below we present, step by step, a simplified data flow diagram from the request (form) through the data model to the BPMN process, illustrating the above issues:

1. The user fills out the form – e.g. enters first and last name in text fields on the request.
2. Binding to the model – the entered values are stored in the request data model under the mid keys personalData.firstName and personalData.lastName (according to the request's mid configuration).
3. Save and start process – the user clicks "Send". At the save point EximeeRouter2 the BPMN process is started (e.g. LoanProcess). Thanks to use-model-mapping=true, the mechanism reads the field values from the model and creates process variables:

   • firstName (process variable) = "Jan" (value from the request personalData.firstName),
   • lastName (process variable) = "Kowalski" (value from the request personalData.lastName),
   • and possibly other mapped variables. Additionally, the business key is passed, e.g. request number "APP-1023" as the businessKey process businessKey business key.
4. Executing the BPMN process – the process LoanProcess starts with the given variables. At the first stage there may be, for example, an automatic creditworthiness check, where the condition in the decision gateway checks the value of the variable firstName or lastName (less often, but e.g. some flags based on data). Since the variables have been set, the business rules work according to the form data.
5. User task in the process – the process moves to a step where approval by an employee is required (User Task). When the employee opens their assigned task handling form, the system loads the form associated with that task. Upon opening:

   • Eximee retrieves the current values of the process variables (e.g. the result of the automatic verification or data from the previous step) and fills the form's data model of the task-handling form with them, provided the appropriate mappings have been configured.
   • For example, if the task-handling form has a field Decision associated with the key decision, and the process contains a variable decisionFlag set in the previous step, then the Mid=decision -> External=decisionFlag mapping will cause the value of that variable to be loaded into the field.
6. Updating and returning data to the process – the employee fills in the field Decision (e.g. chooses "Approve"). When the form is saved, thanks to the active use-model-mapping, this value is transferred from the task form model back to the process variable decisionFlag. The user task is completed, and the process moves on, now with updated data.
7. Process completion – at the end of the process, all collected information is in the process variables (in our example: first name, last name, decision, etc.). They can be used to generate a summary or to save data in external systems.

The above flow demonstrates that data "flows" along the path: form -> process variables -> (optional) next form -> ... -> process result. Each of these links is connected through configuration (mapping). This approach minimizes the need for manual coding of the information flow and makes the integration more transparent.