Passing data to the process

Mapping form data to BPMN process variables

Integrating an application (form) with a 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, you need to 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 level), 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 data model mapping to the process should be active for the given application. The absence of this variable (or setting it to false) will cause the form data not to be automatically passed to the BPMN process.

  2. Configuration of field mapping to process variables – when the mechanism is enabled, you can define which data model fields 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 is to be sent. 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 link 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 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 corresponding values from the application.

For example, if the application contains the field Company NIP (Tax ID) linked in 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, at process start the engine will create the variable companyTaxId and pass to it the value from the field nip of the 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 above example, the form field with the identifier (model key) telefonKontaktowy will be mapped to the process variable phoneNumber. The dataType attribute 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: Simply adding a mapping in the Data Model is not enough – you must also make sure that the application actually starts the process. To this end, in the application definition (the Steps tab in Designer) you should add 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 Case number = e.g., a value from a form field or a generated one) – otherwise it will by default 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 points between them. A typical integration scenario looks as follows:

  1. User fills out the form: The user enters data into 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 component is activated EximeeRouter2 attached at the save point. If the session variable use-model-mapping = true, Router2 initiates the associated BPMN process passing data to it. Values from the application are fetched 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. Use of 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 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.

  4. User task forms (optional): If the BPMN process has steps of type User Task, which require user interaction on a subsequent 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 ongoing process. How does synchronization occur? When the process reaches the 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 other things, by passing the process identifier router_process_id as an input parameter). Thanks to this, the form “knows” in the context of which instance it is operating. If we previously set model mapping in the start application, a similar 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 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 by configuring the mapping (Mid = decyzja, External ID = approvalDecision) we will cause the value of the variable approvalDecision to be inserted into the field upon opening the form decision. The platform will ensure synchronization – the Router2 mechanism reads the current values of the process variables and updates the values in the User Task form. The user can then change/add information and save the task form.

  5. Updating variables when closing a User Task: When the user fills out the task form and saves it, the mapping mechanism will act again – this time saving the changes from the task form model back to the process variables and completing the user task (the process token moves on). Thanks to this, the process always has the latest data from the users’ last actions.

  6. Continuation and completion of 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 crucial to understand that the application’s data model acts as an intermediary between the presentation layer (form) and the process layer (BPMN engine). The data flows from the form, through the model (application memory), to the process variables and possibly back, 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 for them, provided the mapping and integration are correctly configured.

Note: For the data transfer mechanism to work, the application save point configuration must contain the section <variables>. EximeeRouter2 uses it to pass variables to the process. Even if we do not pass additional variables that condition the flow, the section <variables> 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 correctly started or associated with the data.

An example of a minimal variables section in the application definition (source in the Source tab of the application, 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 for resuming the process, they can be added 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 find a waiting process instance (e.g., waiting for a message/signal) and move it forward based on matching the variable’s value.

The 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 within a process.

If the form is not associated with any process (e.g., it is a standalone data collection form without workflow, or the 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 it will not receive data from the application (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, it is a fixed configuration at the application level.

To sum up: use-model-mapping = true enables the data “bridge” 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 a step-by-step simplified data flow diagram from the application (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 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’s mid configuration).

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

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

    • nazwisko (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 ProcesKredytowy starts with the provided variables. In the first stage there may be, for example, an automatic creditworthiness check, where the condition in a decision gateway checks the value of the variable imie or nazwisko (less often, but e.g., some flags based on data). Because the variables have been set, business rules operate according to the data from the form.

  5. User task in the process – the process moves to a step where employee approval is required (User Task). When the employee opens in Eximee Dashboard the assigned task handling form, the system loads 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 in the task-handling form there is a field Decision linked to the key decision, and the process has a variable decisionFlag set in an earlier step, then the mapping Mid=decision -> External=decisionFlag will cause that variable’s value 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 saving the form, 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, already having 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 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.

PreviousBest practicesNextData model in the process

Last updated

Was this helpful?