2 Składnia podstawowa

Po spotkaniu: zapiszesz w tok proces liniowy z poprawnymi identyfikatorami i etykietami · dobierzesz rodzaj zdarzenia i zadania do opisu kroku · uporządkujesz model poleceniem tok fmt i odczytasz komunikaty tok check · Czas: Nauka 40 min, Wyzwanie 50 min

2.1 Nauka

Budowa dokumentu

Dokument tok to zwykły plik tekstowy z rozszerzeniem .tok. Czyta się go wiersz po wierszu. Obowiązują cztery reguły:

Pierwsza instrukcja to nagłówek tok 0.1 "Tytuł". Liczba 0.1 to wersja języka, a tekst w cudzysłowie to tytuł modelu. Tytuł trafia do pliku BPMN jako nazwa całego modelu.
Jeden wiersz to jedna instrukcja. Instrukcja nie może przechodzić do następnego wiersza.
Każda instrukcja zaczyna się słowem kluczowym, np. start, user, flow. Słowo kluczowe mówi, co opisuje wiersz.
Kolejność instrukcji jest dowolna. Przepływ może wskazywać zadanie, które zadeklarowano niżej. Dla czytelności piszemy jednak najpierw elementy, a pod nimi przepływy.

Oto pełny model przyjęcia zamówienia na kopię cyfrową w bibliotece. To proces liniowy: jedna ścieżka od początku do końca.

# Przyjęcie zamówienia na kopię cyfrową w bibliotece
tok 0.1 "Przyjęcie zamówienia na kopię cyfrową"

start wplynelo "Zamówienie wpłynęło" message="Zamówienie kopii"
service rejestracja "Rejestracja zamówienia"
user weryfikacja "Weryfikacja praw autorskich"
manual pobranie "Pobranie oryginału z magazynu"
user skanowanie "Wykonanie skanu"
script oplata "Wyliczenie opłaty"
send wyslanie "Wysłanie kopii" message="Kopia cyfrowa"
end wyslano "Kopia wysłana"

flow wplynelo -> rejestracja -> weryfikacja -> pobranie -> skanowanie -> oplata -> wyslanie -> wyslano

Rysunek 2.1: Przyjęcie zamówienia na kopię cyfrową: proces liniowy z różnymi rodzajami zadań.

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

Pierwszy wiersz zaczyna się znakiem #, więc jest komentarzem. Komentarz to notatka dla człowieka, którą narzędzie pomija przy budowie modelu. Komentarz może zajmować cały wiersz albo stać na końcu instrukcji: manual wydanie "Wydanie akt" # w czytelni.

Instrukcja elementu

Każdy element procesu, czyli zdarzenie, zadanie albo bramka, ma tę samą budowę:

rodzaj  identyfikator  "Etykieta"  atrybuty
user    weryfikacja    "Weryfikacja praw autorskich"
send    wyslanie       "Wysłanie kopii"  message="Kopia cyfrowa"

Rodzaj to słowo kluczowe: start, end, task, user, send i inne.
Identyfikator to krótka nazwa elementu dla programu. Używasz jej w przepływach.
Etykieta to nazwa dla ludzi, widoczna na diagramie. Piszesz ją w cudzysłowie, w dowolnym języku, z polskimi znakami.
Atrybuty mają postać klucz=wartość i doprecyzowują element. Wartość z odstępami albo polskimi znakami bierzesz w cudzysłów.

Identyfikatory i etykiety

Identyfikator musi spełniać trzy warunki:

Warunek	Dobrze	Źle
zaczyna się literą (albo `_`)	`skan2`	`2skan`
zawiera tylko litery bez polskich znaków, cyfry, `-` i `_`	`zamowienie`, `kontrola-formalna`	`zamówienie`, `kontrola formalna`
jest jedyny w całym modelu	`start-1`, `start-2`	dwa razy `start`

Dlaczego bez polskich znaków? Identyfikator trafia do pliku BPMN jako atrybut id. Wiele programów, z którymi model może się spotkać (silniki, systemy raportowe), zakłada, że identyfikatory są w zwykłym alfabecie łacińskim. Polskie znaki zostają w etykietach.

Narzędzie pilnuje tych reguł. Tak wygląda wynik tok check --lang pl dla modelu z dwoma błędami: identyfikatorem zamówienie i dwoma elementami o identyfikatorze s:

err.tok:3: błąd R004: identyfikator „zamówienie” może zawierać tylko litery ASCII, cyfry, „_” i „-”
err.tok:4: błąd R001: identyfikator „s” jest już użyty w wierszu 2

Każdy komunikat ma numer wiersza, poziom (błąd, ostrzeżenie, uwaga), kod i opis. Kody przydają się, gdy szukasz wyjaśnienia w dodatku B.

Dobre identyfikatory są krótkie, ale zrozumiałe: weryfikacja, oplata, wyslano. Nie numeruj ich bez potrzeby (t1, t2). Model czyta się wtedy jak szyfr. Etykieta może być pominięta, np. przy bramce złączenia, która na diagramie nie potrzebuje nazwy.

Zdarzenia

Na tym spotkaniu używasz dwóch rodzajów zdarzeń: początkowego start i końcowego end. Zdarzenie bez atrybutów to zdarzenie „zwykłe”, bez wyzwalacza. Wyzwalacz dodajesz atrybutem:

Atrybut	Wyzwalacz	Przykład
`message="…"`	wiadomość	`start wplynelo "Zamówienie wpłynęło" message="Zamówienie kopii"`
`timer=…`	czas	`start raport "Początek miesiąca" timer="R/2027-01-01T08:00/P1M"`
`signal="…"`	sygnał	`end ogloszenie "Ogłoszono zamknięcie" signal="Zamknięcie czytelni"`
`terminate`	natychmiastowe zakończenie całego procesu	`end przerwano "Proces przerwany" terminate`

Pozostałe wyzwalacze (błąd, eskalacja, warunek, łącznik, kompensacja) poznasz na spotkaniu 5. Jedno zdarzenie może mieć tylko jeden wyzwalacz. Dwa naraz to błąd R012.

Czas zapisuje się w formacie ISO 8601, tym samym, którego używa Camunda Modeler:

Zapis	Znaczenie
`P3D`	3 dni
`PT2H`	2 godziny (`T` oddziela część dni od części godzin)
`PT30M`	30 minut
`P1DT12H`	półtora dnia
`P2W`	2 tygodnie
`2027-01-15T09:00`	konkretna data i godzina
`R3/PT1H`	trzy razy co godzinę (cykl; w tok bierze się go w cudzysłów, gdy zawiera spacje)

Czynności

Rodzaj zadania wybierasz tak samo jak w Camunda Modeler. Decydują słowa z opisu kroku. Przypomnienie znajdziesz w rozdziale 3 kursu BPMN i w zasadach BPMN.

Słowo kluczowe	Element BPMN	Rozpoznasz po słowach
`task`	zadanie ogólne	nie wiadomo, jak praca jest wykonywana
`user`	zadanie użytkownika	człowiek pracuje w systemie: formularz, EZD, system biblioteczny
`manual`	zadanie ręczne	człowiek bez systemu: rozmowa, przeniesienie akt, telefon
`service`	zadanie usługowe	system robi to sam, „automatycznie”
`script`	zadanie skryptowe	wyliczenie według stałego wzoru
`rule`	zadanie reguły biznesowej	wynik wynika z tabeli reguł, „nikt nie ocenia”
`send`	zadanie wysyłania	wysłanie wiadomości do kogoś poza procesem
`receive`	zadanie odbioru	czekanie na wiadomość jako osobna praca
`call`	czynność wywołania	uruchomienie innego, osobno opisanego procesu

Zadania send i receive mogą wskazywać wiadomość atrybutem message="…". Dwa elementy z tą samą nazwą wiadomości odnoszą się do tej samej wiadomości w pliku BPMN.

Do zadań możesz dopisać flagi. To słowa bez wartości, stawiane po etykiecie:

Flaga	Znaczenie
`loop`	pętla: zadanie powtarza się, aż warunek zostanie spełniony
`parallel`	wiele instancji naraz, np. ocena każdej pozycji listy równolegle
`sequential`	wiele instancji po kolei

Przykład: user ocena "Ocena każdej recenzji" parallel.

Przepływy i łańcuchy

Przepływ sekwencji zapisujesz instrukcją flow. Strzałka -> łączy identyfikatory:

flow wplynelo -> rejestracja
flow rejestracja -> weryfikacja

Kilka przepływów w jednym ciągu można zapisać łańcuchem:

flow wplynelo -> rejestracja -> weryfikacja -> pobranie

Ten wiersz tworzy trzy przepływy. Każdy dostaje identyfikator utworzony z nazw końców, np. f-wplynelo-rejestracja. Ten identyfikator zobaczysz w niektórych komunikatach.

Łańcuchy skracają model, ale mają jedno ograniczenie. Wiersz z etykietą przepływu (np. "tak") albo z atrybutem może zawierać tylko jedną strzałkę. Wrócimy do tego przy bramkach na spotkaniu 3.

Przepływ, który wskazuje nieistniejący element, to błąd R002:

err2.tok:6: błąd R002: nieznany element (element przepływu): „x”

Wcięcia

W procesie bez basenów, takim jak przykłady z tego spotkania, wszystkie instrukcje zaczynają się od początku wiersza. Wcięcia będą potrzebne na spotkaniu 4, gdy linie znajdą się w basenach, a zadania w liniach. Już teraz zapamiętaj jedną regułę: wcięcia robi się spacjami. Tabulator we wcięciu to błąd T002.

Forma kanoniczna

Ten sam model można zapisać na wiele sposobów: z różną liczbą spacji, z przepływami w osobnych wierszach albo w łańcuchu. Polecenie tok fmt porządkuje zapis do jednej, kanonicznej postaci. Oto plik przed porządkowaniem:

# Udostępnienie akt w czytelni archiwum
tok   0.1 "Udostępnienie akt"
start s "Wniosek złożony"
  # tu archiwista sprawdza sygnaturę
user sprawdzenie   "Sprawdzenie sygnatury"
manual wydanie "Wydanie akt"   # w czytelni
end e "Akta wydane"
flow s -> sprawdzenie
flow sprawdzenie -> wydanie
flow wydanie -> e

A tak wygląda wynik tok fmt:

# Udostępnienie akt w czytelni archiwum
tok 0.1 "Udostępnienie akt"

start s "Wniosek złożony"
# tu archiwista sprawdza sygnaturę
user sprawdzenie "Sprawdzenie sygnatury"
manual wydanie "Wydanie akt"  # w czytelni
end e "Akta wydane"

flow s -> sprawdzenie -> wydanie -> e

tok fmt:

usuwa zbędne spacje i dodaje puste wiersze między sekcjami;
łączy przepływy w łańcuchy, jeśli tworzą jedną ścieżkę;
ustawia atrybuty w stałej kolejności;
zachowuje komentarze i przypina je do instrukcji, nad którą stały.

Polecenie tok fmt plik.tok tylko wypisuje wynik. tok fmt plik.tok -w zapisuje go w pliku. Forma kanoniczna ma praktyczne znaczenie przy pracy zespołowej i z agentem AI. Dwie osoby, które zapiszą ten sam model, dostaną identyczny tekst, więc porównanie wersji pokazuje tylko prawdziwe zmiany w procesie.

Poziomy języka

Opcja --level ogranicza język do wybranego poziomu:

Poziom	Co jest dostępne
`basic`	zwykłe zdarzenia początkowe i końcowe, zadania `task`, `user`, `manual`, `service`, bramki `xor` i `and`, baseny, linie, przepływy komunikatów, dane, adnotacje
`analytic`	pełna notacja BPMN bez warstwy wykonywalnej (formularzy, decyzji, wyrażeń)
`full`	wszystko (domyślnie)

Poziom basic odpowiada modelom opisowym z pierwszych spotkań kursu BPMN. Przydaje się, gdy model ma czytać kierownictwo albo klient instytucji, a nie analityk. Sprawdzenie przykładu z tego rozdziału na poziomie basic daje:

02-rejestracja-zamowienia.tok:4: błąd R040: „start” nie jest dostępne na poziomie basic
02-rejestracja-zamowienia.tok:9: błąd R040: „script” nie jest dostępne na poziomie basic
02-rejestracja-zamowienia.tok:10: błąd R040: „send” nie jest dostępne na poziomie basic

Zdarzenie początkowe jest na tym poziomie dozwolone, ale bez wyzwalacza wiadomości. Zadania skryptowe i wysyłania należą już do modelu analitycznego.

2.2 Wyzwanie

Polecenie: zapisz w tok proces rejestracji pisma w kancelarii uczelni, sprawdź go, uporządkuj i otwórz eksport w Camunda Modeler.

Dane wejściowe:

Nr kroku	Nr kolejnego kroku	Nazwa kroku	Opis kroku	Kto wykonuje?
1	2	Pismo wpłynęło	Do kancelarii wpływa pismo przysłane pocztą przez osobę spoza uczelni.	—
2	3	Rejestracja pisma	Kancelistka wprowadza do systemu EZD nadawcę, datę wpływu i temat pisma.	Kancelistka
3	4	Nadanie numeru	System EZD sam, bez udziału człowieka, nadaje pismu numer kancelaryjny.	System EZD
4	5	Skanowanie pisma	Kancelistka skanuje pismo i dołącza skan do sprawy w EZD.	Kancelistka
5	6	Dekretacja	Kierownik kancelarii wskazuje w EZD jednostkę, która rozpatrzy pismo. Ma na to 2 dni robocze.	Kierownik kancelarii
6	7	Przekazanie oryginału	Kancelistka zanosi papierowy oryginał do archiwum zakładowego.	Kancelistka
7	8	Powiadomienie jednostki	System EZD automatycznie wysyła jednostce wiadomość o nowej sprawie.	System EZD
8	—	Koniec — pismo przekazane

Kroki:

Zapisz model w pliku kancelaria.tok. Na tym etapie nie ma jeszcze basenów ani linii. Rolę wykonawcy zapisz komentarzem nad zadaniem, np. # Kancelistka.
Dobierz rodzaje zdarzeń i zadań na podstawie opisu. Zastanów się, czy termin z kroku 5 wymaga już teraz elementu w modelu.
Uruchom tok check kancelaria.tok --lang pl i poprawiaj, aż model nie będzie miał błędów.
Uruchom tok fmt kancelaria.tok -w i porównaj wynik ze swoim zapisem.
Sprawdź model na poziomie basic. Zapisz, które elementy wykraczają poza ten poziom i dlaczego.
Uruchom tok bpmn kancelaria.tok i otwórz plik w Camunda Modeler. Kliknij kilka elementów i sprawdź w panelu właściwości ich typ.

Rezultat: plik kancelaria.tok w formie kanonicznej i kancelaria.bpmn. Krótka notatka (3–4 zdania) o tym, które rodzaje zadań były niejednoznaczne. Nie oddajesz ich na Pegazie.

Praca: indywidualnie, a w ostatnich 10 minutach porównanie modeli w parach.

Czas: 50 minut.

Na co zwrócić uwagę

„Wprowadza do systemu” oznacza zadanie użytkownika, a nie ręczne. „Zanosi oryginał” to praca bez systemu, czyli zadanie ręczne.
Termin 2 dni na dekretację to informacja o czasie, ale w procesie liniowym nic się po nim nie dzieje. Zdarzenie graniczne dodasz dopiero wtedy, gdy opis mówi, co następuje po upływie terminu (spotkanie 5).
Jeśli tok fmt przestawił Twoje wiersze albo połączył przepływy, nie zmienił modelu. Zmienił tylko zapis.
Nazwę wiadomości (message="…") dobierz tak, żeby opisywała treść, np. "Pismo", "Powiadomienie o sprawie".

2.3 Pytania sprawdzające

Z jakich części składa się instrukcja elementu? Która z nich trafia na diagram?
Dlaczego identyfikator nie może zawierać polskich znaków, a etykieta może?
Zapisz w tok zdarzenie początkowe „Początek kwartału”, które zachodzi co trzy miesiące od 1 stycznia 2027 r.
Ile przepływów tworzy wiersz flow a -> b -> c -> d? Jakie identyfikatory otrzymają?
Co zmienia tok fmt w modelu, a czego nie zmienia nigdy?