Passing data to the process

Mapping form data to BPMN process variables

Integration of the request (form) with the BPMN process (the EximeeBPMS engine, in the case of the Eximee platform) requires mapping data from the request model to process variables. This allows the data entered by the user in the form to 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 session variables panel (available from the application configuration), 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 a given request. Absence of this variable (or setting it to false) will cause the form data not to be passed automatically to the BPMN process.

2. Configuring field mapping to process variables – 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 mappingsmust be created, 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, therefore, we provide the target variable key.

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

• the system will read the field values defined in the mapping from the data model,

• it will create process variables with the names given in the External ID,

• it will assign the corresponding values from the request to those variables.

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

The mapping configuration can be saved in the form definition in an XML block. Below is an example fragment of the request source code 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 a mapping in Data Model is not enough – you must also 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 a Request save point with a component of type EximeeRouter2, pointing to the appropriate BPMN process (parameter Process name = the 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 a generated one) – otherwise it will default to using the request number as the Business Key.

Synchronization of data between the request and the process

Thanks to the data model mapping mechanism, synchronization of data between the request and the process happens automatically at the 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 use-model-mapping = attached to the save point is activated. If the session variabletrue , Router2 starts the associated BPMN processpassing the data to it companyTaxId, . Values from the request are read according to the list of defined mappings and passed as process variables. As a result, the process starts with populated variables (e.g., nip firstName

3. etc.), which can be used within the process flow. Using data in the process:

4. 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 can determine the path chosen in a gateway (based on a condition), or be passed to an external service in a service task. At this stage, the data "lives" as part of the process state in the BPMN engine. User task forms (optional): If there are steps of typeUser Task in the BPMN process that require user interaction on a subsequent form (e.g. an employee verifies the request in the second stage), the Eximee platform allows another form to be displayed in the context of the ongoing process. How does synchronization happen? When the process reaches the User Task, that task can be handled by Eximee Dashboard – the user opens the task handling form, and the systemlinks it to the existing process instance . This way, the form "knows" in the context of which instance it operates. If we previously set model mapping in the starting request, then analogous mapping can be applied in the task handling form to load process variable values into the variables use-model-mappingof that form. This is done by defining the same model key and process variable name in the mapping (with active). For example, if the process contains a variable approvalDecision, and our task form has the fielddecision, , then configuring the mapping (Mid = decision active External ID = approvalDecision approvalDecision) will cause the variable value to be loaded into the field when the form is opened. The platform ensures synchronization – the Router2 mechanism reads the current values of the process variables and updates the values of the User Task form. The user can then change/add information and save the task form.

5. Updating variables when closing the User Task: When the user fills out the task form and saves it, 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 ensures that the process always has up-to-date data from the latest user actions.

6. Continuation and completion of the process: The BPMN process can go through subsequent stages (e.g. additional user tasks, service tasks). At the end, when the process is completed, the data accumulated in the process variables can be saved to target systems, etc., depending on the logic.

In the above data flow, it is crucial 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 flow 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, as long as the mapping and integration are 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 do not pass additional variables determining the flow, the section <variables> 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 be started correctly or linked to the data.

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

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

The above configuration passes the variable businessKey to the process, set to the current request number (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>

we 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 the 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, which enables automatic data mapping between the request 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 run within an EximeeBPMS process or

• The request will be used as a user task form within the process.

If the form is not linked to any process (e.g. it is a standalone form for collecting data without a workflow, or the integration with the process is done differently), then we do not set this flag.

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

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

= true use-model-mapping enables the data "bridge" between the request and the process. Without this bridge, the request and the process operate completely independently, and any transfer of information would require manual programming (e.g. through custom EximeeBPMS API calls). Therefore, it is worth remembering this variable in every form-to-process integration. Example data flow from form to process

Below we present a simplified step-by-step

data flow diagram from the request (form) through the data model to the BPMN process, illustrating the above issues: The user fills out the form

1. – e.g. enters first and last name in text fields on the request. Binding to the model

2. – the entered values go into the request data model under the mid keys personalData.firstName personalData.lastName and (according to the request mid configuration). Save and start the process

3. – the user clicks "Send". At the save point the BPMN process starts EximeeRouter2 (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.lastName),

   • lastName (process variable) = "Kowalski" (value from the request (according to the request mid configuration).),

   • and possibly other mapped variables. In addition, the businessKey process business key is passed, e.g. the request number "APP-1023" as the businessKey process business key.

4. Execution of the BPMN process – the process LoanProcess starts with the given variables. In 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 the data). Since the variables have been set, 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 the task handling formassigned to them in Eximee Dashboard, 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 model with them of the task handling form, provided the appropriate mappings have been configured.

   • For example, if the task handling form contains the field Decision associated with the key approvalDecision, and the process contains the variable decisionFlag set in an earlier step, then the mapping Mid=approvalDecision -> External=decisionFlag will cause the value of that variable to be loaded into the field.

6. Updating and returning data to the process – the employee fills out the field Decision (e.g. selects "Approve"). When the form is saved, thanks to the active use-model-mapping, this value is transferred from the task form model to the process variable decisionFlag. The user task is completed, and the process moves on, now with the 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 the data in external systems.

The above flow demonstrates that the 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 information flow and makes integration more transparent.