1 Model jako tekst

Po spotkaniu: wyjaśnisz, czym model tekstowy różni się od rysunku · przeczytasz prosty model tok · zainstalujesz narzędzie tok i zamienisz model na diagram BPMN · Czas: Nauka 40 min, Wyzwanie 50 min

1.1 Nauka

Dwa sposoby zapisu tego samego modelu

Diagram BPMN, który rysujesz w Camunda Modeler, jest zapisany w pliku .bpmn. To plik XML. Zawiera dwie warstwy: semantykę (jakie są zadania, zdarzenia, bramki i przepływy) oraz układ (gdzie leży każdy prostokąt i którędy biegnie każda strzałka). Model z kilkoma zadaniami zajmuje w takim pliku ponad sto wierszy, z czego duża część to współrzędne.

Ten sam model można zapisać inaczej: jako krótki tekst, w którym każdy wiersz opisuje jeden element. Układ nie jest wtedy zapisany wcale. Program obliczy go sam, kiedy będzie potrzebny rysunek. Na tym pomyśle opiera się język tok.

tok 0.1 "Wypożyczenie międzybiblioteczne"

pool biblioteka "Biblioteka uczelniana"
  lane czytelnik "Czytelnik"
    start potrzeba "Potrzeba książki"
    user zamowienie "Złożenie zamówienia"
  lane bibliotekarz "Bibliotekarz"
    user katalogi "Sprawdzenie katalogów"
    xor dostepna "Czy książka dostępna lokalnie?"
    user wskazanie "Wskazanie egzemplarza"
    user inna "Zamówienie w innej bibliotece"
    end wskazany "Egzemplarz wskazany"
    end zamowione "Zamówienie złożone"

flow potrzeba -> zamowienie -> katalogi -> dostepna
flow dostepna -> wskazanie "tak"
flow dostepna -> inna "nie"
flow wskazanie -> wskazany
flow inna -> zamowione
Diagram wygenerowany z modelu tok poleceniem tok svg.

Rysunek 1.1: Diagram wygenerowany z modelu tok poleceniem tok svg.

Pobierz model (.tok) Pobierz eksport BPMN (.bpmn)

To wypożyczenie międzybiblioteczne, które znasz z pierwszego spotkania kursu BPMN. Tekst ma 19 wierszy. Plik .bpmn z tym samym modelem i jego układem ma ich ponad 100.

Czytanie modelu wiersz po wierszu

Wiersz Znaczenie Element BPMN
tok 0.1 "Wypożyczenie międzybiblioteczne" nagłówek: wersja języka i tytuł modelu definitions
pool biblioteka "Biblioteka uczelniana" uczestnik procesu: basen (pool) o identyfikatorze biblioteka participant i process
lane czytelnik "Czytelnik" linia (lane) w basenie; wiersze wcięte pod nią należą do tej linii lane
start potrzeba "Potrzeba książki" zdarzenie początkowe startEvent
user zamowienie "Złożenie zamówienia" zadanie użytkownika, czyli człowiek pracujący w systemie userTask
xor dostepna "Czy książka dostępna lokalnie?" bramka wykluczająca exclusiveGateway
end wskazany "Egzemplarz wskazany" zdarzenie końcowe endEvent
flow potrzeba -> zamowienie -> katalogi -> dostepna trzy przepływy sekwencji zapisane łańcuchem 3 × sequenceFlow
flow dostepna -> wskazanie "tak" jeden przepływ z etykietą odpowiedzi sequenceFlow name="tak"

Trzy zasady wystarczą, żeby przeczytać każdy model tok:

  1. Każdy wiersz zaczyna się słowem kluczowym, które mówi, co opisuje: start, user, xor, flow, pool. Słowa kluczowe pochodzą z angielskich nazw elementów BPMN.
  2. Po słowie kluczowym stoi identyfikator, potem etykieta w cudzysłowie. Identyfikator (katalogi) to krótka nazwa dla programu, pisana bez polskich znaków i spacji. Etykieta ("Sprawdzenie katalogów") to nazwa dla ludzi, widoczna na diagramie.
  3. Wcięcie oznacza przynależność. Linia jest wcięta pod basenem, a zadania pod linią. Przepływy (flow) piszemy na końcu, bez wcięcia, bo łączą elementy z różnych linii.

Tekst jest modelem

W pracy z tok obowiązuje jedna zasada: tekst jest modelem, a wszystko inne to jego widoki. Rysunek SVG, plik BPMN dla Camunda Modeler, tabela decyzyjna DMN, formularze i wyniki symulacji powstają z tekstu. Zmieniasz zawsze tekst, a widoki generujesz od nowa.

model.tok  ──►  tok check   (czy model jest poprawny?)
           ──►  tok fmt     (porządkowanie zapisu)
           ──►  tok bpmn    (model.bpmn: Camunda Modeler, bpmn.io)
           ──►  tok svg     (model.svg: rysunek do dokumentu)
           ──►  tok export  (wszystkie pliki dla silnika Camunda 8)
           ──►  tok sim     (symulacja: czasy, obciążenie)

Ta zasada ma praktyczne skutki. Model tekstowy można trzymać w repozytorium razem z procedurą, którą opisuje. Zmianę w procedurze widać jako zmianę kilku wierszy tekstu. Dwie osoby mogą pracować nad jednym modelem i łączyć swoje zmiany tak jak przy wspólnej edycji dokumentu.

tok wśród innych notacji tekstowych

tok nie jest pierwszym językiem tekstowym do rysowania procesów. W dokumentacji projektów informatycznych popularne są Mermaid i PlantUML. Powstał też BPMN Sketch Miner, w którym proces opisuje się zdaniami. Te narzędzia tworzą jednak przede wszystkim rysunki. Ich diagramy wyglądają podobnie do BPMN, ale nie powstaje z nich plik BPMN 2.0, który otworzy Camunda Modeler albo wykona silnik procesów.

tok jest zbudowany odwrotnie. Jego podstawą jest metamodel BPMN 2.0: każda konstrukcja języka odpowiada elementowi ze specyfikacji OMG. Dlatego model tok:

  • eksportuje się do standardowego pliku BPMN 2.0 z układem diagramu;
  • przechodzi te same reguły poprawności co modele z Camunda Modeler (te same kody błędów, które znasz z bpmn.py);
  • da się odtworzyć z istniejącego pliku .bpmn poleceniem tok import.

Narzędzie tok

tok to program uruchamiany w terminalu. Wymaga Pythona 3.8 lub nowszego i nie potrzebuje żadnych dodatkowych bibliotek. Instaluje się go jednym poleceniem, które pobiera gotowy pakiet dla Twojego systemu z PyPI, katalogu pakietów Pythona:

System Instalacja Sprawdzenie
Windows (PowerShell) py -m pip install --upgrade tok-lang tok --version
macOS, Linux python3 -m pip install --upgrade tok-lang tok --version

Oczekiwany wynik: numer wersji narzędzia, np. tok 1.0.3. Jeśli system odpowiada, że nie zna polecenia tok, użyj formy py -m tok … (Windows) albo python3 -m tok … (macOS, Linux). Działa tak samo.

Na tym spotkaniu używasz czterech poleceń:

Polecenie Co robi
tok check model.tok --lang pl sprawdza model i wypisuje komunikaty po polsku, z numerem wiersza i kodem
tok fmt model.tok -w porządkuje zapis: wcięcia, kolejność, cudzysłowy
tok bpmn model.tok tworzy model.bpmn z układem diagramu
tok svg model.tok tworzy rysunek model.svg

Komunikat błędy 0, ostrzeżenia 0, uwagi 0 oznacza, że model jest poprawny w notacji BPMN. Nie oznacza, że jest zgodny z rzeczywistym procesem. Za to odpowiada autor modelu, tak samo jak w Camunda Modeler.

Edytor tekstu

Model tok piszesz w dowolnym edytorze zwykłego tekstu. Wygodny jest Visual Studio Code: pokazuje numery wierszy, które wskazuje tok check, i pilnuje wcięć. Zapisuj pliki z rozszerzeniem .tok i w kodowaniu UTF-8 (to ustawienie domyślne w VS Code). Do wcięć używaj spacji, nie tabulatora. VS Code wstawia spacje po naciśnięciu klawisza Tab, jeśli w prawym dolnym rogu okna widnieje „Spaces”.

1.2 Wyzwanie

Polecenie: zainstaluj tok, przepisz podany diagram na model tekstowy i sprawdź, czy narzędzie odtworzy z niego diagram w Camunda Modeler.

Kroki:

  1. Zainstaluj tok i sprawdź wersję.
  2. Pobierz model 01-wypozyczenie.tok z części Nauka. Uruchom na nim tok check --lang pl, tok bpmn i tok svg. Otwórz plik .bpmn w Camunda Modeler.
  3. Zmień w modelu jedną rzecz: dopisz przed końcem „Zamówienie złożone” zadanie użytkownika „Powiadomienie czytelnika” w linii bibliotekarza. Zmień odpowiedni przepływ, uruchom tok check i wygeneruj diagram ponownie.
  4. Przepisz na tok diagram „Zamówienie książki z magazynu” z rozdziału 3 kursu BPMN (diagram w książce kursu). Zachowaj linie, bramki i nazwy zakończeń.
  5. Uruchom tok check --lang pl i popraw błędy, aż komunikat pokaże 0 błędów. Potem tok fmt -w i tok bpmn. Porównaj swój diagram z oryginałem w Camunda Modeler.

Rezultat: pliki 01-wypozyczenie.tok (ze zmianą z kroku 3) i magazyn.tok z ich eksportem .bpmn. Nie oddajesz ich na Pegazie.

Praca: indywidualnie, z pomocą sąsiada przy instalacji.

Czas: 50 minut, w tym około 10 minut na instalację.

Na co zwrócić uwagę

  • Identyfikatory nie mogą zawierać polskich znaków ani spacji: zamowienie, sprawdzenie-katalogow. Polskie znaki są w etykietach w cudzysłowie.
  • Każdy identyfikator może wystąpić w modelu tylko raz jako deklaracja. W wierszach flow używasz identyfikatorów, nie etykiet.
  • Jeśli tok check wskazuje wiersz, którego nie widzisz w edytorze, włącz numerowanie wierszy (VS Code: domyślnie włączone).
  • Układ diagramu wygenerowanego z tok może różnić się od rysunku z Camunda Modeler. Model jest ten sam, bo semantyka się zgadza. Układ jest tylko widokiem.

1.3 Pytania sprawdzające

  1. Jakie dwie warstwy zawiera plik .bpmn? Której z nich nie zapisuje się w tok?
  2. Czym różni się identyfikator od etykiety? Gdzie każde z nich jest widoczne?
  3. Co znaczy zasada „tekst jest modelem”? Podaj dwa widoki modelu tok.
  4. Czym tok różni się od notacji Mermaid albo PlantUML?
  5. Co oznacza komunikat błędy 0 po poleceniu tok check, a czego nie oznacza?