Errors

Concept

Tijdens de uitvoering van het proces door de workflow engine kunnen zich fouten of errors voordoen. Grosso modo maken we een onderscheid tussen volgende errortypes, afhankelijk van hun aard of van het niveau waarop ze zich voordoen.

• Interne configuratie errors in de workflow engine ten gevolge van foute configuratie (voorbeelden: je spreekt een niet-bestaande service aan, je hebt de uitgaande paden van een gateway fout geconfigureerd, je verwijst naar een procesvariabele die niet voorhanden is of je hebt een fout gemaakt tijdens het opstellen van een inline script). Dit zijn errors die frequent voorkomen tijdens het iteratief configureren en testen van je workflows binnen de preview omgeving van je applicatie.

• Externe technische errors die zich voordoen tijdens het uitvoeren van aangesproken externe services (bijvoorbeeld: een mailservice stuurt een e-mail uit naar een opgegeven adres, maar dit adres blijkt niet te bestaan). Indien het aanspreken van deze service geprogrammeerd is in Java Delegate code, wordt een Java exception opgeworpen.

• BPMN-errors opgevangen binnen de workflow. Dit zijn business errors die specifiek door de configurator zijn gedefinieerd, waarbij er een alternatief pad in de workflow wordt voorzien. Deze errors zijn geen technische fouten, maar eerder foutmeldingen die ontstaan door business-logica. Bijvoorbeeld, je stuurt een klantnummer naar een externe service met de bedoeling informatie op te halen, maar het klantnummer is niet bekend in de externe service. De service geeft dan een specifieke foutmelding terug. Deze fout wordt omgezet naar een BPMN-error die door een Error Catch Event wordt opgevangen, waarna de taak wordt afgebroken en het proces verdergaat via een alternatief pad (bijvoorbeeld: de gebruiker moet eerst een account aanmaken).

Errors beheren

Afhankelijk van het type gebeurt dit op een andere manier.

• Interne technische error: aangezien deze fouten een directe impact hebben op de workflow engine, gaat het proces onmiddellijk in incident modus. De taak wordt geannuleerd en er volgt een rollback tot aan het vorige safe point. De infrastructuurbeheerder of de technical support medewerkers pikken deze incidenten op in het ondersteuningsportaal en/of de Camunda cockpit.

• Externe technische error: deze worden niet automatisch opgepikt door de workflow engine. Hier zijn twee mogelijkheden.

  • Het proces merkt dat de service een foutstatus (exception) teruggeeft en concludeert dat de taak niet afgerond kan worden. Afhankelijk van instellingen zal het proces de service nog enkele keren aanspreken (retry) en na een aantal mislukte pogingen in incident modus gaan. De infrastructuurbeheerder of de technical support medewerkers pikken deze op in het ondersteuningsportaal en/of de Camunda cockpit.

  • Als de uitzondering door de externe service wordt opgevangen in de Java Delegate-code, kan het proces doorgaan alsof de taak succesvol is afgerond. Er kan een procesvariabele worden aangemaakt (bijvoorbeeld mailAdresOnbestaand=true), waarmee het proces een alternatieve route volgt. Dit kan bijvoorbeeld betekenen dat de dossierbehandelaar telefonisch contact opneemt met de klant als het opgegeven mailadres niet bestaat. Dit systeem is geschikt voor technische fouten die een verwacht resultaat zijn, maar niet voor onvoorziene fouten. Het verschil met een BPMN-error is hier klein. Belangrijk onderscheid is evenwel dat een BPMN-error visueel wordt weergegeven in de BPMN-workflow, terwijl dit bij het hierboven beschreven systeem niet het geval is.

• BPMN-error: business errors moeten expliciet worden geconfigureerd in de workflow. Ze worden alleen gegenereerd in specifieke scenario's die door de configurator zijn bepaald. Het aanmaken van een BPMN-error kan op verschillende manieren gebeuren, maar steeds binnen de context van het proces. De BPMN-error moet je vervolgens bewust opvangen in de BPMN-workflow, zodat het proces via een alternatief pad kan verdergaan. Dit vereist een Error Catch Event dat de fout opvangt en een alternatieve route activeert.

Symbool BPMN-error

Een BPMN-error wordt weergegeven via onderstaand symbool.

BPMN-error aanmaken

Java Delegate

Een BPMN-error aanmaken doe je meestal via Java Delegate code waarmee je de externe service aanroept. In onderstaand voorbeeld hebben we een call naar een e-mailservice. Deze retourneert de status van het opgegeven e-mailadres via emailService.isEmailValid. Indien dit false is, wordt via de functie throw new BpmnError een nieuwe BPMN-error met code “EMAILONBESTAAND” aangemaakt.

public class EmailServiceDelegate implements JavaDelegate {
    public void execute(DelegateExecution execution) throws Exception {
        String emailAddress = (String) execution.getVariable("emailAddress");
        
        // Retourneer status van het e-mailadres
        if (!emailService.isEmailValid(emailAddress)) {
            // Gooi een BPMN-error met de foutcode "EMAILONBESTAAND"
            throw new BpmnError("EMAILONBESTAAND");
        }
    }
}

Bij het aanmaken van een BPMN-error kan je twee argumenten meegeven. De eerste (code) is verplicht en definieert de key, de tweede (message) is optioneel en voegt een omschrijving of extra info toe.

JavaScript

Een BPMN-error aanmaken kan ook vanuit een workflow script gebeuren. Hieronder een stukje van het script met een check of het totale subsidiebedrag totaal groter is dan 5000. Indien true, dan zal de BPMN-error “TE_HOOG_SUBSIDIEBEDRAG” aangemaakt worden.

// Validatie: totaal mag niet hoger zijn dan 5000
if (totaal > 5000) {
    throw new org.camunda.bpm.engine.delegate.BpmnError("TE_HOOG_SUBSIDIEBEDRAG", ">5000");
    }

Bij het aanmaken van een BPMN-error kan je twee argumenten meegeven. De eerste (code) is verplicht en definieert de key, de tweede (message) is optioneel en voegt een omschrijving of extra info toe.

BPMN error event

Je kan de error ook via een BPMN error throw event definiëren. Dit gebeurt frequent binnen een subproces. Nemen we het voorbeeld van het subsidiebedrag zoals hierboven aangehaald. Het error throw event bevindt zich binnen het subproces. De error wordt opgevangen door een boundary catch event (zie verderop).

BPMN-error opvangen

Een BPMN-error kan je opvangen ofwel via een interrupting boundary error catch event die je aan de servicetaak of subproces toevoegt.

Uitgestuurde BPMN-errors die niet opgevangen worden door een error catch event, leiden tot het bruusk afsluiten van het proces. Als je dit niet wil, dan kan je volgende eigenschap toevoegen aan de workflow engine eigenschappen: enableExceptionsAfterUnhandledBpmnError:true. In dat geval worden niet-opgevangen BPMN-errors gewoon genegeerd.

Interrupting boundary error catch event

Meer info

Meer info over error handling binnen de context van de workflow engine kan je vinden via de Camunda 7 documentatie site.