> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/proces-biznesowy/przekazywanie-danych-do-procesu.md). # 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 data from the request model to **process variables**. This makes it possible for 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 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 data model mapping to the process should be active for a given request. If this variable is missing (or set to false), form data **will not be passed automatically** 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 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). Appropriate **mappings**must 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 be sent. This is exactly the process variable name visible in the process definition (e.g. in EximeeBPMS Modeler). In this column, therefore, we enter 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 values of the fields defined in the mapping from the data model, * it will create process variables with the names given in the External ID, * and assign the appropriate values from the request to those variables. For example, if the request contains a field *Company NIP* 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 **Mid** = `nip` and **External ID** = `companyTaxId`, the engine will create the variable `companyTaxId` at process start and pass the value from the field `nip` of the application. The mapping configuration can be stored in the form definition in an XML block. Below is an example of a request source code fragment with model mapping enabled (ecModelMapping): ```xml ``` In the example above, the form field with identifier (model key) `telefonKontaktowy` will be mapped to the process variable `phoneNumber`. The `dataType` attribute was left empty – the EximeeBPMS engine usually detects the type of a simple variable (e.g. string, number) based on the value itself, 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 a **Application Save Point** with a component of type **EximeeRouter2**, pointing to the appropriate BPMN process (parameter *Process name* = process definition key). In addition, 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) – otherwise it will default to 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 like this: 1. **User fills in the form:** The user enters data into the fields on the request (form) screen. 2. **Saving and starting the process:** When the user finishes filling in 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`is set, Router2 initializes the associated BPMN process **passing data to it**. The 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. `companyTaxId`, `firstName`, `nip` etc.), which can be used within the process flow. 3. **Using data in the process:** The BPMN process, once it already has 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 there are steps of type **User Task**in the BPMN process that require user interaction on another 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, that task can be handled by **Eximee Dashboard** – the user opens the task handling form, and the system **binds it to the existing process instance**. This way the form "knows" which instance it operates in the context of. If we previously set model mapping in the start request, then analogous 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 `use-model-mapping`active). For example, if the process contains a variable `approvalDecision`, and our task form has a field `decision`, then configuring the mapping (`Mid = decision`, `External ID = approvalDecision`) will cause the value of the variable to be loaded into the field when the form is opened. `approvalDecision` will be placed into the field `decision`. The platform takes care of synchronization – the Router2 mechanism reads the current process variable values 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 out the task form and saves it, the mapping mechanism works again – this time **writing 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 users’ latest actions. 6. **Continuing and ending the process:** The BPMN process can move through subsequent stages (e.g. more 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 data flow above, 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 **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, as long as the mapping and integration are configured correctly. > **Note:** For the mechanism of passing data to work, **the request save-point configuration must contain the ``**section. EximeeRouter2 uses it to pass variables to the process. Even if we are not passing additional variables that condition the flow, the `` section should be present (even if empty). In the case of data mapping, it usually contains at least an entry for Business Key. If it is missing, the process may not start correctly or may not be linked with the data. Example of a minimal variables section in the request definition (source in the **Source** request tab, inside ``): ```xml businessKey ${formInstanceNumber} ``` The above configuration passes the variable `businessKey` set to the current request number to the process (which ensures a unique link between the process instance and 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, they can be added here. For example, adding: ```xml nip ${nip} ``` 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 matching the variable value. ## 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 work 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 as part of 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 a workflow, or the 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, **we need to** 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 is most likely not the intended result). The flag `use-model-mapping` can also be set conditionally – for example, if the same form is sometimes to be launched with a process and sometimes without one (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** switches on 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 coding (e.g. through custom EximeeBPMS API calls). That is why it is worth remembering this variable in 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 issues above: 1. **User fills in the form** – e.g. enters first and last name in text fields on the request. 2. **Binding to the model** – entered values go into the request data model under the mid keys `daneOsobowe.imie` and `daneOsobowe.nazwisko` (according to the request’s mid configuration). 3. **Saving and process start** – the user clicks "Send". At the save point *EximeeRouter2* the BPMN process is launched (e.g. *ProcesKredytowy*). Thanks to `use-model-mapping=true`, the mechanism reads the field values from the model and creates process variables: * `imie` (process variable) = "Jan" (value from the request `daneOsobowe.imie`), * `nazwisko` (process variable) = "Kowalski" (value from the request `daneOsobowe.nazwisko`), * and possibly other mapped variables.\ Additionally, the *businessKey* process Business Key, e.g. request number "APP-1023" as the `businessKey` process. 4. **Execution of the BPMN process** – the process *ProcesKredytowy* 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 `imie` or `nazwisko` (less often, but e.g. some flags based on the data). Since the variables have been set, the business rules work 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 the assigned **task handling form**, the system loads the form associated with that task. When opening: * Eximee retrieves the current process variable values (e.g. the result of the automatic check or data from the previous step) and **fills the form’s data model** of the task-handling form with them, if the appropriate mappings were configured. * For example, if in the task-handling form there is a field *Decision* linked with the key `decision`decision `, and in the process there is a variable` set in an earlier step, then mapping Mid=`decision` -> External=`, and in the process there is a variable` 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. chooses "Accept"). When the form is saved, thanks to active `use-model-mapping`, this value is transferred from the task form model back to the process variable `, and in the process there is a variable`. The user task is completed, and the process continues 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.). It can be used to generate a summary or to save the data in external systems. The above flow demonstrates that data "flows" along the path: **form -> process variables -> (optionally) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/proces-biznesowy/przekazywanie-danych-do-procesu.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.