> 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 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 ``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): ```xml ``` 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 ``**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 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 ``): ```xml businessKey ${formInstanceNumber} ``` 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: ```xml nip ${nip} ``` 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. --- # 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, and the optional `goal` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/proces-biznesowy/przekazywanie-danych-do-procesu.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.