Passing data to the process

Mapping form data to BPMN process variables

Integration of the application (form) with the BPMN process (the EximeeBPMS engine, in the case of the Eximee platform) requires mapping data from the application 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 application to the process, perform two basic configuration steps:

1. Add a special session variable use-model-mapping – in Eximee Designer, in the application’s 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 flag controlling data integration; its presence informs the platform that for the given application, model-to-process data mapping should be active. The absence of this variable (or setting it to false) will cause form data not to be automatically passed to the BPMN process.

2. Configure field-to-process-variable mapping – when the mechanism is enabled, you can define which fields of the data model 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 element <ecModelMapping>). You should create appropriate mappings, where you specify:

   • Mid (Mapping ID) – the identifier of the source field (application). 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 with e.g. 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 mapping entries, the platform will automatically link the indicated fields with the appropriate process variables. In practice, this means that when starting the process (starting a BPMN instance) or sending the token to the next step:

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

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

• it will assign to these variables the appropriate values from the application.

For example, if the application contains the field Company NIP linked to 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 at process start companyTaxId and pass to it the value from the field nip application.

The mapping configuration can be saved in the form definition in an XML block. Below is an example fragment of the application’s source code with model mapping enabled (ecModelMapping):

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

In the example above, the form field with the identifier (model key) telefonKontaktowy will be mapped to the process variable phoneNumber. The attribute dataType is left empty – the EximeeBPMS engine usually recognizes the type of a simple variable itself (e.g., string, number) based on the value, but you can use it if it is necessary to explicitly indicate the type.

Note: Adding the mapping in the Data model is not enough – you also need to make sure that the application actually starts the process. To this end, in the application definition (the Steps tab in Designer) there should be a Application 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 (a unique case/business identifier) to the process, it can be specified in the Router configuration (parameter Application number = e.g., a value from a form field or a generated one) – otherwise, by default it will take the application number as the Business Key.

Data synchronization between the application and the process

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

1. Filling in the form by the user: The user enters data in the fields on the application (form) screen.

2. Save and start the process: When the user finishes filling in and saves the application (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 data to it. The values from the application 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., companyTaxId, firstName, nip etc.), which can be used inside the process flow.

3. Using the data in the process: The BPMN process, already having assigned variables, can use them in decision gateways, scripts, service and user tasks. For example, a variable passed from the form can determine the path choice 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 application in the second stage), the Eximee platform allows you to display the next form in the context of the running 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 (among others, passing the process identifier router_process_id as an input parameter). Thanks to this, the form "knows" in the context of which instance it operates. If we previously set up model mapping in the start application, then the same mapping can be applied in the task handling form to load process variable values into the variables of this form. This is done by defining the same model key and the process variable name in the mapping (with active use-model-mapping). For example, if the process has a variable approvalDecision, and our task form has a field decision, then configuring the mapping (Mid = decyzja, External ID = approvalDecision) will cause that upon opening the form the value of the variable approvalDecision will be inserted into the field decision. The platform will take care of 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 in the task form and saves it, the mapping mechanism will work 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 the process always has up-to-date data from the latest user actions.

6. Process continuation and completion: 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 crucial to understand that the application’s data model acts as an intermediary between the presentation layer (form) and the process layer (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’s mechanism does it, provided the mapping and integration are configured correctly.

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

Example of a minimal variables section in the application definition (source in the application's The number of page columns can be changed after creating the form by editing its definition. In the application edit mode go to the tab, inside <saveActions>):

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

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

If we want to pass additional variables for synchronization or to resume the process, 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 application. The EximeeRouter2 mechanism can look up a waiting process instance (e.g., waiting for a message/signal) and move it forward based on matching the variable value.

Parameter use-model-mapping – what is it and when to use it?

use-model-mapping is the name of a special session variable (flag) in the application configuration that enables automatic data mapping between the application’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 application is integrated with a process and requires transferring data to the process.

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

• The application is to be started within an EximeeBPMS process or

• The application will be used as a user task form inside the process.

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

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

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

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

Example data flow from form to process

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

1. The user fills out the form – e.g., enters first name and last name in the text fields in the application.

2. Binding to the model – the entered values go to the application’s data model under the mid keys daneOsobowe.imie and daneOsobowe.nazwisko (according to the application mid configuration).

3. Save and start the process – the user clicks "Send". At the save point EximeeRouter2 the BPMN process is started (e.g., CreditProcess). Thanks to the use-model-mapping=true, the mechanism reads the field values from the model and creates process variables:

   • firstName (process variable) = "Jan" (value from the application daneOsobowe.imie),

   • lastName (process variable) = "Kowalski" (value from the application daneOsobowe.nazwisko),

   • and possibly other mapped variables. Additionally, the businessKey of the process is passed, e.g., the application number "APP-1023" as the businessKey of the process.

4. Execution of the BPMN process – the process CreditProcess starts with the provided variables. In the first stage there may be, for example, an automatic creditworthiness check, where a 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 operate according to the data from the form.

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 in Eximee Dashboard their assigned task handling form, the system will load the form associated with this task. Upon opening:

   • Eximee retrieves the current values of the process variables (e.g., the result of automatic verification or data from the previous step) and fills the data model of the task-handling form with them, provided appropriate mappings are configured.

   • For example, if the task-handling form has a field Decision linked to the key decision, and the process has a variable decisionFlag set in a previous step, then the mapping Mid=decision -> External=decisionFlag will cause the value of this variable to be loaded into the field.

6. Updating and returning data to the process – the employee fills in the field Decision (e.g., selects "Accept"). 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 having 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 -> (optionally) next form -> ... -> process outcome. Each of these links is connected through configuration (mapping). This approach minimizes the need for manual coding of information flow and makes the integration more transparent.