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):

<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>):

<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:

<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ą.

PreviousDobre praktykiNextModel danych w procesie

Last updated

Was this helpful?