Zrozumieć obsługę wartości zwracanych i wyjątków w regułach AMODIT

Aktualizacja6 grudnia 2025

Wprowadzenie

W tym artykule wyjaśniamy, jak działa mechanizm obsługi wartości zwracanych przez funkcje oraz obsługa wyjątków w regułach systemu AMODIT. Zrozumienie tych zasad jest kluczowe dla administratorów i zaawansowanych użytkowników, którzy projektują stabilne, odporne na błędy automatyzacje i integracje.

Problem lub kontekst biznesowy

W systemach workflow, takich jak AMODIT, reguły automatyzujące procesy często korzystają z funkcji, które komunikują się z zewnętrznymi usługami lub przetwarzają dane. Błędy w obsłudze wartości zwracanych przez te funkcje mogą prowadzić do „zawieszania się” spraw, utraty danych lub trudnych do wykrycia błędów biznesowych. Kluczowe jest więc nie tylko sprawdzanie, czy funkcja zwraca oczekiwany wynik, ale także odpowiednie reagowanie na wartości brzegowe (np. pusty ciąg, zero, null) oraz nieprzewidziane wyjątki.

Wyjaśnienie koncepcji (jak to działa?)

1. Wartości zwracane przez funkcje – nie tylko sukces!

Każda funkcja w regułach AMODIT zwraca jakąś wartość. Najczęściej jest to:

  • ciąg znaków (np. identyfikator dokumentu),
  • wartość logiczna (true/false),
  • liczba,
  • data.

Wartość oczekiwana to taka, która oznacza poprawne wykonanie operacji (np. niepusty identyfikator, true, liczba dodatnia).

Wartości brzegowe to takie, które mogą oznaczać błąd lub niepowodzenie (np. pusty ciąg, false, zero, wartość ujemna, null). Przykład: funkcja integrująca z zewnętrznym OCR powinna zwrócić identyfikator dokumentu – jeśli zwraca pusty ciąg, oznacza to, że dokument nie został zarejestrowany.

2. Obsługa wartości brzegowych w regułach

Pisząc reguły, należy zawsze sprawdzać, czy funkcja nie zwróciła wartości brzegowej. Typowe podejście:

  • Jeśli funkcja zwraca niepusty identyfikator – kontynuuj proces.
  • Jeśli funkcja zwraca pusty ciąg – zaloguj błąd, przerwij proces lub wyświetl komunikat użytkownikowi.

Do sprawdzania wartości zwracanych przez funkcje, w tym wartości brzegowych, służy konstrukcja if … else ….

Przykład kodu reguły wysyłającej dokument do AI OCR w celu odczytania jego zawartości:

try
{
   // ustawienie parametrów sterujących działaniem odczytu zawartości pliku przez AI OCR
   options.attachmentName = "FakturaPlik";
   options.model = "amodit-invoice";
   options.forceSend = true;
   options.ruleAfterFill = "aiocr";
   options.additionalFields = "NrZgloszenia (Numer zgłoszenia będzie w formacie: kilka cyfr/dwie ostatnie cyfry roku/1 2 lub 3/od jednej do pięciu cyfr. Zwróć numer dokładnie w takim formacie i formie jak jest to na dokumencie)";

     // wysyłka dokumentu do AI OCR, oczekiwany efekt - identyfikator dokumentu w AI OCR
     resId=AmoditSendAttachmentToOCREx(options);

     // obsługa wartości zwracanych przez funkcję AmoditSendAttachmentToOCREx()
   if(resId!="")
   {
        // wartość oczekiwana - niepusty ciąg znaków
      [ID OCR AI]=resId;
      WriteToSystemLog("CaseId: " + [CaseId] + ", dokument wysłany do AI OCR.")
      WriteToSystemLog("resID " + resId)
   }
   else
   {
        // wartość "brzegowa" - pusty ciąg znaków, funkcja wysyłki do AI OCR nie zadziałała poprawnie
      WriteToSystemLog("brak resID na sprawie " + [CaseId])
   }
}
catch
{
   // zarejestrowanie sytuacji wyjątkowej, nieprzewidzianej
   WriteToSystemLog(CaseId + " - Wystąpił błąd podczas wysyłki dokumentu do AI OCR: " + exception);
}

Brak takiej obsługi może prowadzić do „zawisania” spraw w systemie, bo kolejne etapy nie zostaną uruchomione.

3. Obsługa wyjątków (try-catch)

Nie wszystkie błędy można przewidzieć – np. awaria sieci, niedostępność zewnętrznego serwisu, nieoczekiwane dane wejściowe. W takich przypadkach funkcja może rzucić wyjątek. W AMODIT do obsługi takich sytuacji służy konstrukcja try{…} catch{…}:

  • try – kod, który może rzucić wyjątek.
  • catch – obsługa błędu, np. logowanie, powiadomienie użytkownika.

Kiedy używać try-catch?

  • Gdy wywołujesz funkcje integrujące z zewnętrznymi systemami (np. pobieranie danych z GUS, sprawdzanie rachunku bankowego).
  • Gdy nie masz pełnej kontroli nad danymi wejściowymi lub środowiskiem.

Nie należy nadużywać try-catch – najpierw warto sprawdzić, czy błąd nie wynika z nieprawidłowych danych wejściowych, które można obsłużyć warunkiem.

4. Praktyczne przykłady i dobre praktyki

  • Zawsze sprawdzaj, co funkcja może zwrócić (dokumentacja, help w systemie).
  • Jeśli dokumentacja nie opisuje wartości brzegowych – testuj funkcję i zgłaszaj braki do zespołu dokumentacji.
  • W regułach cyklicznych (np. masowe przetwarzanie faktur) obsługa wartości brzegowych i wyjątków jest kluczowa – błąd przy jednym elemencie nie powinien blokować całego procesu.
  • Warunkuj przejście na kolejny etap procesu od sukcesu funkcji (np. tylko jeśli identyfikator nie jest pusty).

Praktyczne implikacje

  • Stabilność procesów: Dobrze obsłużone wartości brzegowe i wyjątki zapobiegają „zawieszaniu się” spraw i utracie danych.
  • Łatwiejsza diagnostyka: Logowanie błędów i wyjątków pozwala szybciej zidentyfikować źródło problemu.
  • Bezpieczeństwo integracji: W przypadku awarii zewnętrznych serwisów system nie przerywa pracy całkowicie, a administrator otrzymuje jasny sygnał o problemie.
  • Oszczędność czasu: Aktualna dokumentacja i dobre praktyki pozwalają uniknąć powielania tych samych błędów przez różnych użytkowników.

Podsumowanie kluczowych zasad

  • Zawsze sprawdzaj wartości zwracane przez funkcje – nie zakładaj, że zawsze zwracają sukces.
  • Obsługuj wartości brzegowe (pusty ciąg, zero, null, false) – loguj je i reaguj odpowiednio w regule.
  • Stosuj try-catch do obsługi nieprzewidzianych wyjątków, zwłaszcza przy integracjach.
  • Dbaj o aktualność dokumentacji i zgłaszaj braki – to oszczędza czas całego zespołu.