> 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/budowanie-aplikacji/proces-biznesowy/przekazywanie-danych-do-procesu.md). # 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 ``). 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 ``` 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**. 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ę ``**. EximeeRouter2 wykorzystuje ją do przekazania zmiennych do procesu. Nawet jeśli nie przekazujemy dodatkowych zmiennych warunkujących przebieg, sekcja `` 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 ``): ```xml businessKey ${formInstanceNumber} ``` 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 nip ${nip} ``` 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ą. --- # 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/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.