Listeners

Concept

Listeners zijn scripts of expressies die getriggerd worden bij de opstart of het einde van een element in de workflow (zoals een taak). Je kan ze gebruiken om extra handelingen uit te voeren binnen de context van het element (denk bijvoorbeeld aan het uitrekenen van inputvariabelen of aan het wegschrijven van de uitkomst van de taak naar een specifiek formulier). Hou er rekening mee dat listeners geen deel uitmaken van de visuele workflowdefinitie (geen apart element), en dus niet onmiddellijk zichtbaar zijn voor een business owner. Listeners hebben een onopvallend en discreet karakter. Ze voeren noodzakelijke opdrachten uit, maar blijven daarbij op de achtergrond. Zo blijft de BPMN-workflow zelf leesbaar.

Doorgaans zijn listeners het best geplaatst op taakelementen, omdat ze acties uitvoeren bij wijze van voorbereiding of nazorg op taken. Plaats ze nooit op elementen waar ze geen direct verband mee hebben, zoals bijvoorbeeld een sequence flow element.

Listeners zijn blokkerend voor de workflow. Als een script of expressie op een error botst, leidt dit tot een onmiddellijke onderbreking van de workflow uitvoering. Het proces gaat dan in incident status (zie Camunda cockpit).

Execution listener versus taak listener

Er bestaan twee verschillende types listeners: execution listeners die je kan toevoegen aan elk element, en task listeners die je enkel kan toevoegen aan gebruikerstaken. Daarnaast heeft elk type ook zijn eigen mogelijke triggers.

	Execution listener	Task listener
Toepasbaar op	Elk workflow-element	Enkel gebruikerstaken
Triggers	Start, End	Create, Assignment, Complete, Delete, Update, Timeout

Listener aanmaken

Binnen de workflow editor selecteer je het element waar je de listener wil toevoegen. Ga in het eigenschappen panel rechts naar het tabblad Geavanceerd.
Selecteer nu het tabblad Listeners.
Je ziet nu het venster Execution listener. Bij gebruikerstaken heb je nog het bijkomende venster Task listener. Klik op het + icoon om een nieuwe listener aan te maken. De volgende stap is om deze te configureren.

Listener configureren

Eigenschap	Beschrijving
Event type	Voor execution listeners `start` of `end`, dit bepaalt of de listener uitgevoerd wordt bij opstart of het afronden van het element. Voor task listeners `create`, `assignment`, `complete`, `delete`, `update`, `timeout`, dit zijn specifieke triggers voor gebruikerstaken.
Listener type	Je kan kiezen uit vier listener types: `Java Class` en `Delegate expression` vereisen server-side Java en implementeren de ExecutionListener-interface, waarbij Java Class geschikt is voor complexe, herbruikbare logica en Delegate expression extra flexibiliteit biedt via de Spring-container. `Expression` en `Script` vereisen geen Java: een expression is ideaal voor korte, eenvoudige bewerkingen via JUEL, terwijl een script (JavaScript) zich leent voor uitgebreidere logica.
Java Class	Volledig gekwalificeerde klassenaam van een Java-klasse die de `ExecutionListener`-interface implementeert (dummy voorbeeld: `be.skryv.listeners.MyListener`). Vereist server-side Java-ontwikkeling.
Expression	Hier kan je de workflow expressie (JUEL) definiëren.
Delegate expression	Verwijzing naar de Spring bean die je wil aanspreken. Dit gebeurt via een workflow expressie. Dummy voorbeeld: `${logTaskCompletionListener}`
Script	Script format: JavaScript. Script type: inline script. Script: schrijf hier het script.
Field injection	Bijkomend specifieke variabelen die nog niet voorhanden zijn, kan je die hier aanmaken. Gebruik daarbij het + icoon rechts boven het Fields venster. Field injection is nuttig wanneer je vaste waarden of configuratieparameters wil meegeven aan een Java Class listener zonder die in de klasse te hardcoderen. Voor script- en expressielisteners is dit zelden nodig. Name: naam variabele Type: string of expressie Value: letterlijke waarde (string) of waarde gebaseerd op expressie. Een aangemaakte variabele kan je terug verwijderen via het x icoon rechts boven het Fields venster.

Listener verwijderen

Selecteer in het venster Execution listener of Task listener de listener die je wil verwijderen. Klik rechts boven het venster op het x icoon. De listener is nu verwijderd uit de lijst.

XML-samples

Listeners zijn gedefinieerd als Camunda extensions binnen het element waarop je ze gemaakt hebt.

Voorbeeld 1

Gebruikerstaak met zowel een task listener als een execution listener. Beiden maken gebruik van een workflow expression.

CODE

    <bpmn:userTask id="Activity_1jggd2k" name="Bevestig" camunda:candidateGroups="aanvrager">
      <bpmn:extensionElements>
        <camunda:taskListener expression="${execution.setVariable(dummyVariable2,&#39;value&#39;)}" event="create" />
        <camunda:executionListener expression="${execution.setVariable(dummyVariable1,&#39;value&#39;)}" event="start" />
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_0mwmxok</bpmn:incoming>
      <bpmn:outgoing>Flow_1oype76</bpmn:outgoing>
    </bpmn:userTask>

Voorbeeld 2

Service taak met een execution listener. Deze verwijst naar een Java-klasse. Er zijn ook twee field injections gedefinieerd, eentje letterlijk via string value, de andere wordt ingevuld op basis van een workflow expressie.

CODE

    <bpmn:serviceTask id="Activity_1p9ag38" name="Uitvoeren" camunda:expression="${true}">
      <bpmn:extensionElements>
        <camunda:executionListener class="be.skryv.example.listeners.LogTaskCompletionListener" event="end">
          <camunda:field name="notificationEmail">
            <camunda:string>dossierbeheer@gemeente.be</camunda:string>
          </camunda:field>
          <camunda:field name="maxDuration">
            <camunda:expression>${dossierconfiguratie.maxDoorlooptijd}</camunda:expression>
          </camunda:field>
        </camunda:executionListener>
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_1oype76</bpmn:incoming>
      <bpmn:outgoing>Flow_02ubg0b</bpmn:outgoing>
    </bpmn:serviceTask>

Voorbeeld 3

Service taak met een execution listener. Deze verwijst via een delegate expression naar een Spring bean.

CODE

    <bpmn:serviceTask id="Activity_0teeuwi" name="Service aanspreken" camunda:expression="${true}">
      <bpmn:extensionElements>
        <camunda:executionListener delegateExpression="${logTaskCompletionListener}" event="start" />
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_1oype76</bpmn:incoming>
      <bpmn:outgoing>Flow_0czxltu</bpmn:outgoing>
    </bpmn:serviceTask>