Procesy

Zarządzanie procesami przez zewnętrzne API pozwala integracji korzystającej z tokenu API obsługiwać ten sam cykl życia procesów, z którego administratorzy korzystają w Opero. Integracja może tworzyć procesy, edytować wersje robocze, publikować zmiany, uruchamiać procesy dla rekordów, wykonywać przejścia, odczytywać historię i zarządzać zadaniami procesu.

Używaj tych endpointów, gdy inny system jest źródłem konfiguracji procesu albo gdy integracja musi synchronizować procesy Opero z zewnętrznymi akceptacjami, obsługą dokumentów, rozliczeniami, onboardingiem lub inną pracą operacyjną.

Zanim zaczniesz

Utwórz token API i nadaj mu tylko te uprawnienia do procesów, których potrzebuje integracja. Przekazuj token w każdym zapytaniu:

Authorization: Bearer ek_...

Endpointy procesów w zewnętrznym API używają wersji v1. Definicje procesów są konfiguracją na poziomie organizacji i używają tokenów organizacji. Instancje procesów, historia runtime i zadania są danymi operacyjnymi i używają kontekstu przestrzeni firmy przeznaczonej dla integracji.

Token firmy powinien pracować tylko z danymi runtime swojej firmy. Raportowanie procesów między firmami należy do jawnych powierzchni raportowania organizacji, a nie do zwykłych ekranów zadań lub instancji runtime.

Używaj uprawnień definicji procesów do pracy konfiguracyjnej, uprawnień runtime do pracy z aktywnymi instancjami procesów oraz uprawnień zadań do kolejek zadań.

Uprawnienia

Wyszukiwanie kandydatów do przypisania jest dostępne dla tokenów, które mają dowolne z tych uprawnień: api.workflows.read, api.workflows.manage, api.workflows.runtime.execute albo api.workflows.tasks.manage.

Zarządzanie definicjami procesów

Proces ma edytowalne metadane oraz edytowalną wersję roboczą. Wersja robocza zawiera projekt procesu, w tym etapy i przejścia.

Gdy zapisujesz wersję roboczą przez PUT /v1/workflows/{workflowId}/draft, Opero zastępuje całą edytowalną definicję wersji roboczej treścią, którą wyślesz. Przekaż pełny zamierzony stan wersji roboczej, a nie tylko częściową zmianę przejścia albo etapu. Najpierw odczytaj bieżącą wersję roboczą, jeśli integracja ma zmienić tylko jeden fragment.

Podczas publikacji Opero waliduje wersję roboczą. Jeśli wersja robocza jest niepełna albo nieprawidłowa, zapytanie publikacji zwraca błąd konfliktu. Popraw wersję roboczą i opublikuj ją ponownie.

Opublikowane wersje są przechowywane jako publikacje procesu. Możesz je wyświetlić i utworzyć nową wersję roboczą z wcześniejszej publikacji, gdy trzeba odtworzyć poprzednią wersję.

Przepływ definicji

W typowej integracji zarządzającej definicją procesu:

1. Wyświetl szablony procesów albo istniejące procesy.
2. Utwórz proces bezpośrednio albo z szablonu.
3. Odczytaj edytowalną wersję roboczą.
4. Zapisz pełną wersję roboczą, w tym etapy i przejścia.
5. Opublikuj wersję roboczą.
6. Odczytaj proces albo listę publikacji, aby potwierdzić aktywną wersję.

Praca z instancjami runtime

Endpointy runtime służą do pracy z instancjami procesów. Instancja procesu to aktywny cykl życia procesu dla konkretnego rekordu.

Przed uruchomieniem procesu sprawdź stan procesu dla rekordu albo opcje tworzenia. Rekord może mieć tylko jedną aktywną instancję procesu. Jeśli aktywna instancja już istnieje, uruchomienie kolejnej instancji nie powiedzie się.

Po uruchomieniu instancji integracja może odczytywać instancję, dane odtworzenia i historię. Może wykonać przejście, gdy bieżący etap pozwala na wybrane przejście i wszystkie warunki przejścia są spełnione. Warunki przejść nadal obowiązują przy wywołaniach zewnętrznego API.

Jeśli przejście jest ograniczone do konkretnych ról dashboardu albo do bieżącej osoby przypisanej, sam token API nie spełnia warunków zależnych od użytkownika. Nadaj tokenowi api.workflows.runtime.override tylko wtedy, gdy integracja jest zaufana i może wykonywać takie ograniczone przejścia.

Ograniczenia tylko do odczytu i ograniczenia edycji etapu dla modyfikacji rekordów są obsługiwane osobno. Endpointy zapisu rekordów nadal używają api.workflows.bypassMutationGuard, gdy token ma edytować rekord chroniony przez bieżący etap procesu.

Przepływ runtime

W typowej integracji runtime:

1. Odczytaj opcje tworzenia albo stan procesu dla rekordu.
2. Uruchom instancję procesu dla rekordu.
3. Odczytaj instancję, dane odtworzenia albo historię na potrzeby synchronizacji.
4. Wykonaj dozwolone przejście, gdy zewnętrzny proces przejdzie do następnego kroku.
5. Ponownie odczytaj instancję albo historię, aby potwierdzić nowy etap.

Dla rekordu obiektu własnego zawsze dołączaj klucze modułu i obiektu, gdy targetType ma wartość DYNAMIC_OBJECT_RECORD:

GET /v1/workflows/runtime/targets/DYNAMIC_OBJECT_RECORD/rec_123?moduleKey=sales&objectKey=deal
Authorization: Bearer ek_...

Zadania i przypisanie

Endpointy zadań procesu pomagają integracjom budować kolejki zadań albo synchronizować przypisania.

Użyj api.workflows.tasks.read, aby wyświetlać listę i szczegóły zadań. Użyj api.workflows.tasks.manage, aby zmienić przypisanie otwartego zadania. Zmiana przypisania aktualizuje zadanie oraz przypisanie powiązanej instancji procesu, a zmiana pojawia się w historii procesu.

Przed przypisaniem albo zmianą przypisania użyj wyszukiwania kandydatów. Zwraca ono członków albo role, których można użyć w danym kontekście przypisania w procesie.

Audyt, historia i automatyzacja

Zewnętrzne działania na procesach są zapisywane jako działania tokenu API. Historia i wpisy audytu pokazują, że działanie wykonał token API, a nie użytkownik dashboardu.

Automatyzacja procesów może reagować na przejścia i zakończenia wywołane przez zewnętrzne API. Źródło zdarzenia identyfikuje token API, więc reguły i logi mogą odróżniać zmiany wykonane przez API od zmian wykonanych w dashboardzie.

Odczyt stanu procesu zależy od tego, kto go wykonuje. Zewnętrzne endpointy GET dla procesów celowo nie używają współdzielonego cache HTTP.

Rozwiązywanie problemów

Powiązane strony

• Tokeny API
• Bezpieczeństwo tokenów
• Uwierzytelnianie
• OpenAPI