# Przekazywanie danych do procesu

## Mapowanie danych formularza na zmienne procesu BPMN

Integracja wniosku (formularza) z procesem BPMN (silnikiem EximeeBPMS, w przypadku platformy Eximee) wymaga odwzorowania danych z modelu wniosku na **zmienne procesu**. Dzięki temu dane wpisane przez użytkownika w formularzu mogą automatycznie zasilać proces workflow (np. wykorzystywane w bramkach decyzyjnych, zadaniach skryptowych czy przekazywane do usług).

Aby włączyć mechanizm mapowania danych **z wniosku do procesu**, należy wykonać dwa podstawowe kroki konfiguracyjne:

1. **Dodanie specjalnej zmiennej sesyjnej `use-model-mapping`** – w Eximee Designer, w panelu zmiennych sesyjnych wniosku (dostępnym z poziomu konfiguracji aplikacji), dodaj zmienną o nazwie `use-model-mapping` i ustaw jej domyślną wartość na `"true"`. Jest to flaga sterująca integracją danych; jej obecność informuje platformę, że dla danego wniosku ma być aktywne mapowanie modelu danych na proces. Brak tej zmiennej (lub ustawienie jej na false) spowoduje, że dane formularza **nie będą automatycznie przekazywane** do procesu BPMN.
2. **Konfiguracja mapowania pól na zmienne procesowe** – gdy mechanizm jest włączony, pojawia się możliwość zdefiniowania, które pola modelu danych mają odpowiadać którym zmiennym w procesie EximeeBPMS. W Eximee Designer dokonuje się tego w **zakładce Model danych** w sekcji mapowania (lub alternatywnie bezpośrednio w XML źródłowym formularza, w elemencie `<ecModelMapping>`). Należy utworzyć odpowiednie **mapowania (mapping)**, gdzie wskazujemy:
   * **Mid (Mapping ID)** – identyfikator pola źródłowego (wniosku). W praktyce jest to **identyfikator komponentu** powiązanego z komponentem, którego wartość chcemy przekazać. W interfejsie Designer kolumna ta może być oznaczona jako "Mid" i zwykle wypełnia się ją np. *biznesowym ID pola formularza*.
   * **External / UniFlow ID** – nazwa zmiennej w procesie BPMN, do której dana ma trafić. Jest to dokładnie nazwa zmiennej procesowej widoczna w definicji procesu (np. w EximeeBPMS Modeler). W kolumnie tej podajemy więc *docelowy klucz zmiennej*.

Po dodaniu wpisów mapowania, platforma automatycznie powiąże wskazane pola z odpowiednimi zmiennymi procesu. W praktyce oznacza to, że podczas uruchamiania procesu (startu instancji BPMN) lub wysyłania tokena do kolejnego kroku:

* system pobierze z modelu danych wartości pól zdefiniowanych w mapowaniu,
* utworzy zmienne procesu o nazwach podanych w External ID,
* przypisze tym zmiennym odpowiednie wartości z wniosku.

Przykładowo, jeżeli wniosek zawiera pole *NIP firmy* powiązane z modelem pod kluczem `nip`, a w procesie BPMN chcemy używać zmiennej o nazwie `companyTaxId`, to po ustawieniu mapowania **Mid** = `nip` oraz **External ID** = `companyTaxId`, silnik przy starcie procesu utworzy zmienną `companyTaxId` i przekaże do niej wartość z pola `nip` wniosku.

Konfiguracja mapowania może być zapisana w definicji formularza w bloku XML. Poniżej przykład fragmentu kodu źródłowego wniosku z włączonym mapowaniem modeli (ecModelMapping):

```xml
<saveActions> 
    <!-- ... konfiguracja EximeeRouter2 ... -->
</saveActions>
<ecModelMapping>
    <modelMappings>
        <processes/>
        <mappings>
            <!-- Mapowanie pola "telefon" z wniosku na zmienną "phoneNumber" w procesie -->
            <mapping mid="telefonKontaktowy" externalId="phoneNumber" dataType="" 
                     rewrittenFromNestedComponent="false"/>
            <!-- (kolejne mapowania w razie potrzeby) -->
        </mappings>
        <groups/>
    </modelMappings>
</ecModelMapping>
```

W powyższym przykładzie pole formularza o identyfikatorze (kluczu modelu) `telefonKontaktowy` zostanie zmapowane na zmienną procesu `phoneNumber`. Atrybut `dataType` pozostawiono pusty – silnik EximeeBPMS zwykle sam rozpoznaje typ prostej zmiennej (np. string, number) na podstawie wartości, ale można go użyć, jeśli konieczne jest jawne wskazanie typu.

> **Uwaga:** Samo dodanie mapowania w **Model danych** nie wystarczy – należy również upewnić się, że wniosek rzeczywiście **uruchamia proces**. W tym celu w definicji wniosku (zakładka **Kroki** w Designerze) powinien być dodany **Punkt zapisu wniosku** z komponentem typu **EximeeRouter2**, wskazującym na odpowiedni proces BPMN (parametr *Nazwa procesu* = klucz definicji procesu). Dodatkowo, jeśli chcemy nadać procesowi Business Key (unikalny identyfikator sprawy/biznesowy), można wskazać go w konfiguracji Routera (parametr *Numer sprawy* = np. wartość z pola formularza lub wygenerowana) – w przeciwnym razie domyślnie przyjmie on numer wniosku jako Business Key.

## Synchronizacja danych między wnioskiem a procesem

Dzięki mechanizmowi mapowania modelu danych, **synchronizacja danych pomiędzy wnioskiem a procesem** odbywa się automatycznie *w momentach komunikacji* między nimi. Typowy scenariusz integracji wygląda następująco:

1. **Wypełnianie formularza przez użytkownika:** Użytkownik wprowadza dane w polach na ekranie wniosku (formularza).
2. **Zapis i uruchomienie procesu:** W momencie gdy użytkownik kończy wypełnianie i zapisuje wniosek (np. klika "Wyślij" lub przechodzi przez krok zapisu), aktywowany zostaje komponent *EximeeRouter2* podpięty w punkcie zapisu. Jeśli zmienna sesyjna `use-model-mapping` = `true`, Router2 inicjuje powiązany proces BPMN **przekazując do niego dane**. Wartości z wniosku są pobierane zgodnie z listą zdefiniowanych mapowań i przekazywane jako zmienne procesu. W efekcie proces startuje z wypełnionymi zmiennymi (np. `companyTaxId`, `firstName`, `nip` itp.), które można wykorzystać wewnątrz przebiegu procesu.
3. **Wykorzystanie danych w procesie:** Proces BPMN, posiadając już przypisane zmienne, może używać ich w bramkach decyzyjnych, skryptach, zadaniach usługowych i użytkowników. Przykładowo, zmienna przekazana z formularza może zadecydować o wyborze ścieżki w gateway (na podstawie warunku), albo zostać przekazana do zewnętrznej usługi w zadaniu serwisowym. Na tym etapie dane "żyją" jako część stanu procesu w silniku BPMN.
4. **Formularze zadań użytkownika (opcjonalnie):** Jeżeli w procesie BPMN są kroki typu **User Task**, które wymagają interakcji użytkownika na kolejnym formularzu (np. pracownik weryfikuje wniosek w drugim etapie), platforma Eximee pozwala wyświetlić kolejny formularz w kontekście trwającego procesu. Jak następuje synchronizacja? Gdy proces dociera do User Task, zadanie to może być obsłużone przez **Eximee Dashboard** – użytkownik otwiera formularz obsługi zadania, a system **wiąże go z istniejącą instancją procesu** (m.in. przekazując identyfikator procesu `router_process_id` jako parametr wejściowy). Dzięki temu formularz "wie", w kontekście której instancji działa. Jeśli wcześniej w wniosku startowym ustawiliśmy mapowanie modeli, to analogiczne mapowanie można zastosować w formularzu obsługi zadania, aby **wczytać wartości zmiennych procesowych do zmiennych** tego formularza. Realizuje się to poprzez zdefiniowanie takiego samego klucza modelu i nazwy zmiennej procesowej w mapowaniu (przy aktywnym `use-model-mapping`). Przykładowo, jeśli w procesie istnieje zmienna `approvalDecision`, a nasz formularz zadania ma pole `decyzja`, to konfigurując mapowanie (`Mid = decyzja`, `External ID = approvalDecision`) sprawimy, że przy otwarciu formularza wartość zmiennej `approvalDecision` zostanie podstawiona do pola `decyzja`. Platforma zadba o synchronizację – mechanizm Router2 odczytuje bieżące wartości zmiennych procesu i aktualizuje wartości formularza User Task. Użytkownik może następnie zmienić/dodać informacje i zapisać formularz zadania.
5. **Aktualizacja zmiennych przy zamknięciu User Task:** Gdy użytkownik wypełni formularz zadania i go zapisze, wówczas ponownie mechanizm mapowania zadziała – tym razem **zapisując zmiany z modelu formularza z powrotem do zmiennych procesu** i kończąc zadanie użytkownika (token procesu przechodzi dalej). Dzięki temu proces ma zawsze aktualne dane z ostatnich działań użytkowników.
6. **Kontynuacja i zakończenie procesu:** Proces BPMN może przejść przez kolejne etapy (np. kolejne user taski, zadania serwisowe). Na końcu, gdy proces zostanie zakończony, dane zgromadzone w zmiennych procesowych mogą zostać zapisane do systemów docelowych itp., w zależności od logiki.

W powyższym przepływie danych kluczowe jest zrozumienie, że **model danych wniosku pełni rolę pośrednika** między warstwą prezentacji (formularzem) a warstwą procesową (silnikiem BPMN). Dane **przepływają od formularza, przez model (pamięć aplikacji), do zmiennych procesu** i ewentualnie z powrotem, jeśli kolejne formularze są częścią procesu. Użytkownik nie musi ręcznie wyciągać ani przekazywać tych wartości – robi to za niego mechanizm platformy, o ile poprawnie skonfigurowano mapowanie i integrację.

> **Uwaga:** Aby mechanizm przekazania danych zadziałał, **konfiguracja punktu zapisu wniosku musi zawierać sekcję `<variables>`**. EximeeRouter2 wykorzystuje ją do przekazania zmiennych do procesu. Nawet jeśli nie przekazujemy dodatkowych zmiennych warunkujących przebieg, sekcja `<variables>` powinna być obecna (choćby pusta). W przypadku mapowania danych najczęściej zawiera ona przynajmniej wpis dla Business Key. Jeśli jej zabraknie, proces może nie zostać prawidłowo uruchomiony lub związany z danymi.

Przykład minimalnej sekcji zmiennych w definicji wniosku (źródło w zakładce **Źródło** wniosku, wewnątrz `<saveActions>`):

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

Powyższa konfiguracja przekazuje do procesu zmienną `businessKey` ustawioną na numer bieżącego wniosku (co zapewnia unikalne powiązanie instancji procesu z konkretnym wnioskiem). Wartość `${formInstanceNumber}` to predefiniowana zmienna sesyjna zawierająca numer wniosku.

Jeżeli chcemy przekazać dodatkowe zmienne w celu synchronizacji lub wznowienia procesu, można je tutaj dodać. Np. dodając:

```xml
<entry>
   <key>nip</key>
   <value>${nip}</value>
</entry>
```

spowodujemy, że proces zostanie wystartowany lub wznowiony (jeśli oczekiwał) z użyciem wartości `nip` z wniosku. Mechanizm EximeeRouter2 potrafi wyszukać oczekującą instancję procesu (np. czekającą na komunikat/sygnał) i przesunąć ją dalej na podstawie dopasowania wartości zmiennej.

## Parametr `use-model-mapping` – co to jest i kiedy go użyć?

**`use-model-mapping`** to nazwa specjalnej **zmiennej sesyjnej** (flagi) w konfiguracji wniosku, która włącza automatyczne mapowanie danych pomiędzy modelem danych wniosku a zmiennymi procesu BPMN. Domyślnie formularze nie przekazują swoich danych do procesów – działają samodzielnie. Ustawienie `use-model-mapping = true` sygnalizuje platformie, że dany wniosek jest **zintegrowany z procesem** i wymaga przenoszenia danych na proces.

**Kiedy użyć `use-model-mapping`?** Zawsze wtedy, gdy:

* Wniosek ma być uruchamiany w ramach procesu EximeeBPMS **lub**
* Wniosek będzie wykorzystywany jako formularz zadania użytkownika wewnątrz procesu.

Jeśli formularz nie jest powiązany z żadnym procesem (np. jest to samodzielny formularz do zbierania danych bez workflow, albo integracja z procesem odbywa się innym sposobem), to nie ustawiamy tej flagi.

W praktyce, w standardowych scenariuszach, jeżeli w Eximee Designer dodajemy w Kroku **Punkt zapisu wniosku** element EximeeRouter2 i wskazujemy nazwę procesu, **należy** od razu dodać zmienną `use-model-mapping = true` oraz skonfigurować mapowanie modeli. Bez tego proces wystartuje, ale nie otrzyma danych z wniosku (zmienne procesu pozostaną puste lub przyjmą wartości domyślne, co najpewniej nie jest zamierzonym efektem).

Flagę `use-model-mapping` można też ustawić warunkowo – np. jeśli ten sam formularz ma być czasem odpalany z procesem, a czasem bez (w zależności od scenariusza), można sterować wartością tej zmiennej. Zazwyczaj jednak jest to stała konfiguracja na poziomie wniosku.

Podsumowując: **`use-model-mapping` = true** włącza “most” danych między wnioskiem a procesem. Bez tego mostu wniosek i proces działają całkowicie niezależnie, a wszelkie przekazanie informacji wymagałoby ręcznego programowania (np. poprzez własne wywołania API EximeeBPMS). Dlatego warto pamiętać o tej zmiennej przy każdej integracji formularza z procesem.

## Przykładowy przepływ danych od formularza do procesu

Poniżej przedstawiamy krok po kroku uproszczony **schemat przepływu danych** z wniosku (formularza) przez model danych do procesu BPMN, ilustrujący powyższe zagadnienia:

1. **Użytkownik wypełnia formularz** – np. wpisuje imię i nazwisko w polach tekstowych na wniosku.
2. **Binding do modelu** – wpisane wartości trafiają do modelu danych wniosku pod kluczami mid `daneOsobowe.imie` oraz `daneOsobowe.nazwisko` (zgodnie z konfiguracją mid wniosku).
3. **Zapis i start procesu** – użytkownik klika "Wyślij". Na punkcie zapisu *EximeeRouter2* następuje uruchomienie procesu BPMN (np. *ProcesKredytowy*). Dzięki `use-model-mapping=true`, mechanizm odczytuje z modelu wartości pól i tworzy zmienne procesu:
   * `imie` (zmienna procesu) = "Jan" (wartość z wniosku `daneOsobowe.imie`),
   * `nazwisko` (zmienna procesu) = "Kowalski" (wartość z wniosku `daneOsobowe.nazwisko`),
   * oraz ewentualnie inne zmapowane zmienne.\
     Dodatkowo przekazywany jest *businessKey* procesu, np. numer wniosku "APP-1023" jako `businessKey` procesu.
4. **Wykonanie procesu BPMN** – proces *ProcesKredytowy* rozpoczyna się z podanymi zmiennymi. Na pierwszym etapie może być np. automatyczna weryfikacja zdolności kredytowej, gdzie warunek w bramce decyzyjnej sprawdza wartość zmiennej `imie` lub `nazwisko` (rzadziej, ale np. jakieś flagi na podstawie danych). Ponieważ zmienne zostały ustawione, reguły biznesowe działają zgodnie z danymi z formularza.
5. **Zadanie użytkownika w procesie** – proces przechodzi do kroku, gdzie wymagane jest zatwierdzenie przez pracownika (User Task). Gdy pracownik otworzy w Eximee Dashboard przypisany mu **formularz obsługi zadania**, system załaduje formularz powiązany z tym zadaniem. Przy otwarciu:
   * Eximee pobiera aktualne wartości zmiennych procesu (np. wynik automatycznej weryfikacji lub dane z poprzedniego kroku) i **uzupełnia nimi model danych** formularza obsługującego zadanie, o ile skonfigurowano odpowiednie mapowania.
   * Przykładowo, jeśli w formularzu obsługi zadania istnieje pole *Decyzja* powiązane z kluczem `decyzja`, a w procesie istnieje zmienna `decisionFlag` ustawiona we wcześniejszym kroku, to mapowanie Mid=`decyzja` -> External=`decisionFlag` spowoduje wczytanie wartości tej zmiennej do pola.
6. **Aktualizacja i powrót danych do procesu** – pracownik wypełnia pole *Decyzja* (np. wybiera "Zaakceptuj"). W momencie zapisu formularza, dzięki aktywnemu `use-model-mapping`, wartość ta zostaje przeniesiona z modelu formularza zadania do zmiennej procesu `decisionFlag`. Zadanie użytkownika zostaje zakończone, a proces przechodzi dalej, posiadając już zaktualizowane dane.
7. **Zakończenie procesu** – na koniec procesu wszystkie zgromadzone informacje są w zmiennych procesu (w naszym przykładzie imię, nazwisko, decyzja itp.). Można je wykorzystać do wygenerowania podsumowania lub do zapisania danych w systemach zewnętrznych.

Powyższy przepływ demonstruje, że dane "płyną" wzdłuż ścieżki: **formularz ->zmienne procesu -> (opcjonalnie) kolejny formularz -> ... -> wynik procesu**. Każde z tych ogniw jest połączone poprzez konfigurację (mapowanie). Takie podejście minimalizuje potrzebę ręcznego kodowania przepływu informacji i czyni integrację bardziej przejrzystą.