Connector in opbouw.
Inleiding
Lokale besturen beheren hun officiële vergaderingen (zittingen) in een notulenpakket. Denk aan een gemeenteraad of een college van burgemeester en schepenen. Per zitting plannen ze de nodige agendapunten in, leggen ze achteraf de beslissingen erin vast, en maken ze er de notulen mee op. De notulen-connector legt een link tussen een Skryv-dossier en zo’n notulenpakket.
Je kunt de connector op twee manieren gebruiken:
|
Vanuit? |
Hoe? |
Resultaat? |
|---|---|---|
|
Workflow |
een expressie in een service task, bv. |
een procesvariabele, via de result variable van de taak |
|
Formulier |
een veld van het type |
de gekozen optie, opgeslagen als veldwaarde in het document |
Beide wegen komen samen bij het indienen van een agendapunt. Een formulier biedt via lookupvelden een lijst van mogelijke zittingen en andere gerelateerde opties aan, waaruit de dossierbehandelaar een keuze maakt. Vervolgens geeft de behandelaar in datzelfde formulier de nodige input mee voor het agendapunt. De workflow geeft die informatie daarna door aan de connector, die het agendapunt overbrengt naar het notulenpakket.
De connector ondersteunt op dit moment één leverancier: Cobra van Cevi, bereikbaar via de Cevi Servicebus. Ondersteuning voor Notula van GreenValley staat gepland.
Use case
Omschrijving
De notulen-connector wordt ingezet in dossiers die een beslissing van het college of de gemeenteraad nodig hebben, bijvoorbeeld een aanvraag voor een evenement op openbaar domein.
Typische flow
Typisch verloop binnen een Skryv-toepassing:
-
Een burger of organisator dient een aanvraag in via het digitale loket.
-
Een medewerker vult een formulier in met lookupvelden die hun opties rechtstreeks uit het notulenpakket halen: soort zitting, zitting, verantwoordelijke dienst, soort punt en rubrieken, of een procedure. Verder bevat het formulier de inhoudelijke input nodig voor de opmaak van het agendapunt.
-
De workflow dient via de connector het agendapunt in bij het notulenpakket (
addAgendaItemofaddAgendaItemWithProcedure) en bewaart de referentie die het notulenpakket teruggeeft. -
Optioneel stuurt de workflow bijlagen uit het dossier mee, zoals een plan of een advies (
addAttachment). Een bijlage kan mee als ontwerpbesluit, zodat het notulenpakket het opneemt in de notulen. -
Na de zitting vraagt de workflow via de connector de status van het agendapunt op (
getAgendaItemStatus). Een medewerker beslist wanneer dat gebeurt: de connector vraagt de status niet zelf periodiek op, en het notulenpakket stuurt geen melding bij een wijziging. -
Zodra het agendapunt beslist is, haalt de workflow het besluitdocument op en bewaart het als bijlage in het dossier (
saveDecisionDocument). -
De beslissing (aanvaard, verworpen of verdaagd) bepaalt de verdere afhandeling van het dossier, bijvoorbeeld een toelating of een weigering aan de aanvrager.
Screenshots
Onderstaande screenshots tonen op een visuele manier het hierboven geschetste stappenplan.
Formulier met lookup velden die hun opties rechtstreeks uit het notulenpakket ophalen. Zie stap 2 hierboven.
Het agendapunt is klaar om ingediend te worden bij Cobra. Zie stap 3 hierboven.
Enkele typische opties nadat het agendapunt is ingediend bij het notulenpakket.
-
Status agendapunt opvragen bij Cobra. Zie stap 4 hierboven.
-
Bijlage (bijvoorbeeld ontwerpbesluit) meesturen naar Cobra. Zie stap 5 hierboven.
-
Besluitdocument opvragen bij Cobra. Zie stap 6 hierboven.
Setup
Onboarding bij aanbieder notulenpakket
Cobra (Cevi)
De connector spreekt Cobra aan via de Cevi Servicebus. Voor je hem kunt gebruiken, moet je zowel Vanden Broele als het lokaal bestuur aansluiten bij Cevi:
-
Een overleg met Cevi regelt de toegang tot hun testomgeving en de Servicebus. Daarbij krijg je de waarden die je nodig hebt voor de applicatie eigenschappen: client-id, private sleutel (JWK), headers en klantspecifieke id’s.
-
Per lokaal bestuur volgt een overleg met de klant en Cevi, over:
-
de documenten die je meestuurt;
-
de procedures die het bestuur gebruikt;
-
welke gegevens van het dossier naar Cobra gaan.
Reken voldoende tijd voor de configuratie in Cobra en de Servicebus.
-
-
In Cobra heb je per bestuur een gebruiker nodig die eigenaar wordt van de agendapunten die Skryv indient. Geef die gebruiker een standaarddienst. Zonder standaarddienst weigert Cobra een procedure die voor alle diensten geldt.
Dependency toevoegen in het pom.xml bestand
Voeg onderstaande dependency toe aan het pom.xml bestand van je applicatie. Zo wordt de connectorcode ingeladen bij de build van de applicatie. De zeven lookup sources komen automatisch mee: je hoeft ze niet zelf te registreren.
<dependency>
<groupId>com.skryv.connectors</groupId>
<artifactId>notulen</artifactId>
</dependency>
Applicatie eigenschappen
Met skryv.connectors.notulen.supplier kies je de leverancier. De enige waarde is vandaag COBRA, en die geldt ook als je de eigenschap weglaat.
Cobra (Cevi)
(skryv.connectors.notulen.cobra.*)
|
Eigenschap |
Default |
Uitleg |
|---|---|---|
|
NotulenConfiguration |
||
|
|
|
Niet verplicht. De leverancier van het notulenpakket. De enige waarde is vandaag |
|
Cobra: Servicebus |
||
|
|
- |
Verplicht. Adres van de Cevi Servicebus. |
|
|
|
Niet verplicht. Connect- en read-timeout naar de Servicebus, in milliseconden. |
|
|
- |
Verplicht. Header die je applicatie identificeert bij de Servicebus. Krijg je van Cevi. |
|
|
- |
Verplicht. Header voor de Servicebus. Krijg je van Cevi. |
|
|
- |
Verplicht. Per klant, van Cevi. |
|
|
- |
Niet verplicht. Per klant, van Cevi. De connector stuurt deze header alleen mee als je hem invult. |
|
Cobra: Authenticatie (Cevi IDP) |
||
|
|
- |
Verplicht. Token endpoint van de Cevi IDP. |
|
|
- |
Verplicht. Dezelfde waarde als |
|
|
- |
Verplicht. Per klant, van Cevi. |
|
|
- |
Verplicht, tenzij je |
|
|
- |
Verplicht, tenzij je |
|
Cobra: agendapunten |
||
|
|
- |
Verplicht. Het dossiertype waaronder Skryv agendapunten indient in Cobra. Per klant, van Cevi. |
|
|
- |
Verplicht. De Cobra-gebruiker die eigenaar wordt van de agendapunten die Skryv indient, bv. |
|
NotulenCacheProperties |
||
|
|
|
Niet verplicht. Hoe lang de lijst met zittingen in de cache blijft. |
|
|
|
Niet verplicht. Idem, voor de soorten zitting. |
|
|
|
Niet verplicht. Idem, voor de diensten. |
|
|
|
Niet verplicht. Idem, voor de soorten punt. |
|
|
|
Niet verplicht. Idem, voor de rubrieken. |
|
|
|
Niet verplicht. Idem, voor de procedures. |
|
|
|
Niet verplicht. Idem, voor de soorten bijlage. |
Services en functies
Overzicht
|
Functie |
Retourtype |
Info |
|---|---|---|
|
|
|
Agendapunt indienen voor een zitting, zonder procedure. |
|
|
|
Agendapunt indienen met een procedure van het notulenpakket. |
|
|
(geen) |
Een dossierbijlage meesturen met een agendapunt. |
|
|
|
Status van een agendapunt en beslissing opvragen. |
|
|
|
Het besluitdocument ophalen en als dossierbijlage bewaren. |
Elke functie hieronder roep je aan met een expressie in een service task. Ze is ook rechtstreeks aanroepbaar vanuit Java-code, door NotulenConnector (bean notulen) te injecteren in je klasse.
@RequiredArgsConstructor
public class MyOwnService {
private final NotulenConnector notulen;
}
addAgendaItem
Dient een agendapunt in voor een zitting, zonder procedure. In Cobra is dat de methode AddAgendapuntEx.
Workflow expressie
${notulen.addAgendaItem(agendaItem)}
Java-code
AgendaItemReference referentie = notulen.addAgendaItem(agendaItem); // agendaItem: Map<String, ?>
Input
Een expressie kan geen object aanmaken. Daarom bouw je het agendapunt op als een map in een inputparameter van de service task, met één entry per veld. In de Studio modeler is dat een input van het type Map.
|
Parameter |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
Map |
ja |
zie hieronder |
De velden van het agendapunt, één sleutel per veld. |
|
Sleutel |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
waarde van een lookupveld |
ja (Cobra) |
|
De waarde van een |
|
|
waarde van een lookupveld, of String |
ja (Cobra) |
|
De verantwoordelijke dienst: de waarde van een |
|
|
waarde van een lookupveld, of String |
nee |
|
Het soort punt, uit een |
|
|
waarde van een lookupveld, of String |
nee |
|
De hoofdrubriek, uit een |
|
|
waarde van een lookupveld, of String |
nee |
|
De nevenrubriek, uit een |
|
|
String |
ja (Cobra) |
|
Korte inhoud, maximaal 80 tekens. Komt in Cobra in het veld |
|
|
String |
ja (Cobra) |
|
Titel, maximaal 1024 tekens. De titel verschijnt in de documenten die Cobra genereert, zoals de agenda en de notulen. Vermijd er persoonsgegevens in. |
|
|
String |
nee |
|
Het Skryv-dossier waartoe het agendapunt behoort. Cobra legt er een relatie mee. |
Een sleutel die je weglaat of leeg laat, blijft leeg. Een sleutel die niet in deze tabel staat, wordt geweigerd, ook zonder waarde. Zo valt een typfout meteen op.
Een id geef je als tekst mee ('6'), niet als getal. Een getal zoals ${6} wordt geweigerd.
De eigenaar van het agendapunt geef je niet mee. Die komt uit de eigenschap skryv.connectors.notulen.cobra.owner.
Voorbeeld inputparameter van het type map
<camunda:inputParameter name="agendaItem">
<camunda:map>
<camunda:entry key="meeting">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('zitting')}</camunda:entry>
<camunda:entry key="responsibleDepartment">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('verantwoordelijkeDienst')}</camunda:entry>
<camunda:entry key="agendaItemType">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('soortPunt')}</camunda:entry>
<camunda:entry key="mainCategory">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('hoofdRubriek')}</camunda:entry>
<camunda:entry key="subCategory">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('nevenRubriek')}</camunda:entry>
<camunda:entry key="shortDescription">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('betreft')}</camunda:entry>
<camunda:entry key="title">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('agendapunt').getField('titel')}</camunda:entry>
<camunda:entry key="dossierId">${execution.processBusinessKey}</camunda:entry>
</camunda:map>
</camunda:inputParameter>
De connector controleert de verplichte velden en de maximale lengtes niet zelf. Doe dat in het formulier dat het agendapunt verzamelt, bijvoorbeeld met "required": true en een condition op de lengte. Anders zie je het probleem pas als Cobra het agendapunt weigert.
Documentatie
Cevi-documentatie “Cobra integration with Servicebus”, methode AddAgendapuntEx. Je krijgt toegang via Cevi.
Output
Je krijgt een AgendaItemReference terug. Bewaar die in een procesvariabele via de result variable van de service task, bijvoorbeeld agendapuntReferentie. Opvolgen, bijlagen meesturen en het besluitdocument ophalen gebruiken allemaal deze referentie.
|
Veld |
Uitleg |
|---|---|
|
|
Het id van het agendapunt in Cobra ( |
|
|
Link die het agendapunt opent in Cobra, voor gebruikers die het mogen zien. |
AgendaItemReference is een Java-record. In een expressie lees je de velden daarom uit met haakjes: ${agendapuntReferentie.id()}. Zonder haakjes (agendapuntReferentie.id) krijg je een fout.
Error-handling
|
Situatie |
Gedrag |
|---|---|
|
Cobra weigert het agendapunt, bv. omdat er geen zitting van dat soort is op die datum en dat uur, of omdat een verplicht veld ontbreekt |
|
|
De map bevat een onbekende sleutel |
|
|
|
|
|
Een id is geen tekst of lookupwaarde, bv. een getal |
|
De connector zet geen enkele fout om naar een BpmnError. Een synchrone service task geeft de fout door aan wie de vorige taak afrondt: die taak wordt niet afgerond, en de gebruiker ziet een foutmelding. Na een asynchrone grens volgt een incident, zodra de retries op zijn.
Wil je een weigering opvangen met een error boundary event, zet de exceptie dan om in Java-code:
try {
AgendaItemReference referentie = notulen.addAgendaItem(agendaItem);
execution.setVariable("agendapuntReferentie", referentie);
} catch (NotulenException e) {
throw new BpmnError("NOTULEN_AGENDAPUNT_GEWEIGERD", e.getMessage());
}
NotulenException zit in het package com.skryv.connectors.notulen.
Een agendapunt indienen is niet idempotent: elke call voegt een agendapunt toe. Mislukt de call nadat Cobra het agendapunt al aangemaakt heeft, bijvoorbeeld door een read timeout, dan voegt een retry het opnieuw toe. Dat gebeurt ook als de transactie rond de service task achteraf teruggedraaid wordt. Houd rekening met het aantal retries van de service task. Zet een asynchrone grens na de taak als latere stappen in dezelfde transactie kunnen mislukken.
addAgendaItemWithProcedure
Dient een agendapunt in met een procedure. Een procedure is een workflow die het lokaal bestuur in Cobra ingesteld heeft. Ze hoort bij een soort zitting, en bepaalt het soort punt en de rubrieken. In Cobra is dat de methode AddAgendapuntMetProcedure.
Workflow expressie
${notulen.addAgendaItemWithProcedure(agendaItem)}
Java-code
AgendaItemReference referentie = notulen.addAgendaItemWithProcedure(agendaItem); // agendaItem: Map<String, ?>
Input
Net als bij addAgendaItem bouw je het agendapunt op als een map, maar met minder sleutels.
|
Sleutel |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
waarde van een lookupveld, of String |
ja |
|
De procedure, uit een |
|
|
waarde van een lookupveld |
ja (Cobra) |
|
De waarde van een |
|
|
waarde van een lookupveld, of String |
ja (Cobra) |
|
De verantwoordelijke dienst. |
|
|
String |
ja (Cobra) |
|
Zoals bij |
|
|
String |
ja (Cobra) |
|
Zoals bij |
|
|
String |
nee |
|
Het Skryv-dossier. |
agendaItemType, mainCategory en subCategory worden hier geweigerd, net als elke andere sleutel die niet in de tabel staat.
Een procedure voor alle diensten, zoals “Standaard beslissing”, negeert de verantwoordelijke dienst die je meegeeft. Cobra neemt dan de standaarddienst van de eigenaar. Heeft de eigenaar geen standaarddienst, dan weigert Cobra het agendapunt. Een procedure van één dienst werkt met de dienst die je meegeeft. Cobra controleert niet of die dienst bij de procedure hoort. De lookup source notulenProcedures biedt daarom alleen de procedures van de gekozen dienst aan.
Documentatie
Cevi-documentatie, methode AddAgendapuntMetProcedure.
Output
Een AgendaItemReference, zoals bij addAgendaItem.
Error-handling
Zoals bij addAgendaItem. Ook het voorbeeld met BpmnError en de waarschuwing over idempotentie gelden hier.
addAttachment
Stuurt een bijlage van het dossier mee met een agendapunt, bijvoorbeeld een plan of een advies. Zo hoeft niemand ze manueel in Cobra op te laden. In Cobra is dat de methode AddBijlage.
Workflow expressie
${notulen.addAttachment(agendapuntReferentie, bijlageId, soortBijlageId, execution.processBusinessKey)}
Java-code
notulen.addAttachment(referentie, bijlageId, soortBijlageId, dossierId);
Input
|
Parameter |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
|
ja |
|
De referentie die |
|
|
String |
ja |
|
Het id van de dossierbijlage. |
|
|
String |
nee |
|
Leeg ( |
|
|
String |
ja |
|
Het dossier waartoe de bijlage behoort. |
Cobra neemt een Word-document met een soort bijlage op in andere documenten, zoals de notulen. Zo’n document volgt best de opmaak die het bestuur gebruikt voor de notulen. De connector controleert dat niet. De soorten bijlage verschillen per bestuur: haal het id op met de lookup source notulenAttachmentTypes. Uit een lookupveld lees je het id met getField('soortBijlage').key.
<camunda:inputParameter name="bijlageId">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('bijlageMeesturen').getField('bijlage').attachmentId}</camunda:inputParameter>
<camunda:inputParameter name="soortBijlageId">${skryv.dossierFromScope(execution).getOrCreateDocumentByDefinitionKey('bijlageMeesturen').getField('soortBijlage').key}</camunda:inputParameter>
De titel van de bijlage in Cobra is de bestandsnaam zonder extensie. De extensie komt uit de bestandsnaam. Eén call stuurt één bijlage. Voor meerdere bijlagen gebruik je een multi-instance service task over de bijlage-id’s. Hoe groot een bijlage mag zijn, vermeldt Cevi niet.
Documentatie
Cevi-documentatie, methode AddBijlage.
Output
Geen output. Slaagt de call, dan heeft Cobra de bijlage aanvaard.
Error-handling
|
Situatie |
Gedrag |
|---|---|
|
Geen referentie, bijlage of dossier meegegeven |
|
|
De bestandsnaam heeft geen naam of geen extensie |
|
|
De bijlage is leeg |
|
|
De bijlage bestaat niet in het dossier |
Exceptie van de platformbijlagen, zonder call naar Cobra |
|
De bijlage kan niet gelezen worden |
|
|
Cobra weigert de bijlage |
|
Een weigering opvangen doe je zoals bij addAgendaItem.
Ook een bijlage meesturen is niet idempotent: een retry stuurt ze opnieuw. Cobra kan een bijlage niet vervangen of verwijderen. Houd rekening met het aantal retries van de service task.
getAgendaItemStatus
Vraagt op waar een agendapunt staat in Cobra, en wat de zitting erover besliste. In Cobra is dat de methode GetAgendapuntStatus.
Workflow expressie
${notulen.getAgendaItemStatus(agendapuntReferentie)}
Java-code
AgendaItemStatus status = notulen.getAgendaItemStatus(referentie);
Input
|
Parameter |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
|
ja |
|
De referentie die |
Documentatie
Cevi-documentatie, methode GetAgendapuntStatus.
Output
Je krijgt een AgendaItemStatus terug. Bewaar die via de result variable, bijvoorbeeld agendapuntStatus. Een veld zonder waarde is leeg.
|
Veld |
Uitleg |
|---|---|
|
|
|
|
|
|
|
|
Datum van de beslissing, zonder uur. |
|
|
Datum en uur van de zitting waarop het punt staat. Die kan verschillen van de zitting waarvoor je het indiende: Cobra plaatst een punt meestal op de eerste zitting vanaf de opgegeven datum, en een medewerker kan het verplaatsen. |
|
|
Het soort zitting, bv. “College”. |
|
|
De beslissing zoals het bestuur ze in Cobra ingesteld heeft. Vrij per bestuur. |
|
|
Extra informatie over de beslissing. |
AgendaItemStatus heeft getters. Hier lees je de velden dus zonder haakjes uit. Een gateway vergelijkt de status en de beslissing met hun naam als tekst:
${agendapuntStatus.status == 'DECIDED'}
${agendapuntStatus.decision == 'ACCEPTED'}
Alleen Cobra 5.0.1.179 en later geven de beslissing mee. Op een oudere versie blijft decision leeg, ook voor een beslist punt. decisionCode en decisionDescription kunnen dan nog vertellen hoe het beslist werd.
Wachten op de beslissing
De connector vraagt de status niet zelf periodiek op, en Cobra meldt geen wijzigingen. Een medewerker beslist wanneer je kijkt, meestal na de zitting.
-
Een gebruikerstaak, bv. “Status opvragen”, waarin een medewerker bevestigt dat het punt intussen behandeld zou moeten zijn. Kan eventueel ook een timer zijn.
-
Een service task met
${notulen.getAgendaItemStatus(agendapuntReferentie)}en result variableagendapuntStatus. -
Een exclusive gateway:
-
${agendapuntStatus.status == 'DECIDED'}: het dossier gaat verder, bijvoorbeeld op basis vandecision. -
${agendapuntStatus.status == 'WITHDRAWN'}: een eigen pad, zodat de lus niet eindeloos doorgaat voor een punt dat verwijderd werd. -
anders, als default flow: terug naar de gebruikerstaak.
-
Error-handling
|
Situatie |
Gedrag |
|---|---|
|
Geen referentie meegegeven |
|
|
Het id van de referentie komt niet van Cobra |
|
|
Cobra weigert de call, bv. voor een agendapunt dat het niet kent |
|
|
Cobra antwoordt met een status of beslissing die de connector niet kent |
|
Een weigering opvangen doe je zoals bij addAgendaItem.
saveDecisionDocument
Haalt het document op waarin de beslissing over een agendapunt staat, en bewaart het als bijlage van het dossier. In Cobra is dat de methode GetBijlageData.
Workflow expressie
${notulen.saveDecisionDocument(agendapuntReferentie, '44', execution.processBusinessKey)}
Java-code
DecisionDocument besluitDocument = notulen.saveDecisionDocument(referentie, soortBijlageId, dossierId);
Input
|
Parameter |
Data type |
Verplicht |
Voorbeeld |
Uitleg |
|---|---|---|---|---|
|
|
|
ja |
|
De referentie van het agendapunt. |
|
|
String |
ja |
|
Het id van de soort bijlage waarin het bestuur de beslissing bewaart, bv. een uittreksel. Dat id verschilt per bestuur. |
|
|
String |
ja |
|
Het dossier waarin het document bewaard wordt. |
Er is geen lookup source voor decisionDocumentTypeId. notulenAttachmentTypes biedt alleen de soorten aan die je kunt opladen, en het besluitdocument is een soort die je alleen kunt downloaden. In Cobra zijn dat de soorten waarvoor GetSoortenBijlage de vlag beschikbaarVoorExternen zet, wat pas bestaat vanaf Cobra 5.0.1.83. Vraag het id op bij het bestuur of bij Cevi.
Documentatie
Cevi-documentatie, methodes GetBijlageData en GetSoortenBijlage.
Output
Je krijgt een DecisionDocument terug. Bewaar die via de result variable, bijvoorbeeld besluitDocument.
|
Veld |
Uitleg |
|---|---|
|
|
|
|
|
|
|
|
Het id van de dossierbijlage waarin het document bewaard werd. Leeg als het document niet beschikbaar is. |
De bijlage krijgt als naam de titel die Cobra aan het document geeft, of Besluit als er geen titel is, met de extensie van Cobra.
Wil je het document daarna tonen in het frontoffice:
${skryv.attachment(besluitDocument.attachmentId).addToDownloadZone('Besluit', null)}
Wachten tot het document beschikbaar is
Vlak na de beslissing heeft Cobra het document soms nog niet. Dan bewaart de connector niets, en vraag je later opnieuw, met dezelfde lus als bij getAgendaItemStatus:
-
een user task;
-
de service task;
-
een gateway op
${besluitDocument.available}die anders terugkeert naar de user task.
Start die lus pas nadat het agendapunt de status DECIDED heeft.
Elke call die het document vindt, bewaart het opnieuw, als een nieuwe bijlage. Stop dus met vragen zodra het beschikbaar is.
Error-handling
|
Situatie |
Gedrag |
|---|---|
|
Geen referentie, soort bijlage of dossier meegegeven |
|
|
Het id van de referentie of de soort bijlage komt niet van Cobra |
|
|
Cobra weigert de call |
|
|
Cobra antwoordt met een beschikbaarheid die de connector niet kent |
|
|
Het document is beschikbaar, maar heeft geen inhoud of geen extensie |
|
|
De platformbijlagen weigeren het document, bv. omdat de inhoud niet past bij de extensie |
exceptie van de platformbijlagen, ongewijzigd doorgegeven |
Een weigering opvangen doe je zoals bij addAgendaItem.
Lookup sources
Naast de workflowfuncties biedt de connector zeven lookup sources aan. Een veld van het type lookup in een formulier toont daarmee live opties uit het notulenpakket, zonder extra code in je applicatie. De sources komen automatisch mee met de dependency. Hoe je een lookupveld opbouwt in een formulier, lees je op bij formulieren > elementtypes > lookup.
Overzicht
|
Source |
Parameters |
Opties |
|---|---|---|
|
|
- |
De soorten zitting, bv. gemeenteraad of college. |
|
|
|
De zittingen van dat soort die nog agendapunten aanvaarden, gesorteerd op datum. |
|
|
- |
De actieve diensten. Eén ervan is verantwoordelijk voor het agendapunt. |
|
|
|
De soorten punt van dat soort zitting, bv. een beslissing of een kennisname. |
|
|
- |
De rubrieken waaronder je een agendapunt klasseert. Dezelfde lijst dient voor de hoofd- en de nevenrubriek. |
|
|
|
De procedures van dat soort zitting: de procedures voor alle diensten, en die van de verantwoordelijke dienst. |
|
|
- |
De soorten bijlage waarmee je een Word-document kunt meesturen, bv. Body Ontwerpbesluit. Alleen de soorten die je kunt opladen. |
notulenMeetings, notulenAgendaItemTypes en notulenProcedures hangen af van het soort zitting. Ze verwachten de parameter meetingTypeId, en antwoorden met een fout (400) als die ontbreekt. Het veld toont dan dat de opties niet geladen konden worden. notulenProcedures verwacht daarnaast departmentId, zodat een formulier geen procedure van een andere dienst kan aanbieden. Cobra zelf aanvaardt die combinatie wel.
Opgeslagen waarde
Een lookupveld bewaart de gekozen optie als geheel: een key, een label en data. Voor een zitting ziet dat er zo uit:
{
"key": "143",
"label": "College - 05/10/2026 15:00",
"data": {
"id": "143",
"meetingTypeId": "1",
"dateTime": "2026-10-05T15:00:00"
}
}
|
Source |
|
|
|
|---|---|---|---|
|
|
id |
omschrijving |
|
|
|
id |
soort zitting met datum en uur |
|
|
|
id |
omschrijving |
|
|
|
id |
omschrijving |
|
|
|
id |
omschrijving |
|
|
|
id |
titel, of het id als er geen titel is |
|
|
|
id |
omschrijving |
|
Een paar details:
-
dateTimevan een zitting is een lokale tijd, zonder tijdzone. -
codeendescriptionkunnen leeg zijn, als het notulenpakket ze niet meegeeft. -
Bij een procedure voor alle diensten is
departmentIdleeg. -
defaultShortDescriptionendefaultTitlezijn het voorstel van de procedure voor de korte inhoud en de titel van het agendapunt, als ze er een heeft.
Van formulier naar agendapunt
De waarden van de lookupvelden geef je ongewijzigd door aan addAgendaItem of addAgendaItemWithProcedure. De connector haalt er zelf uit wat hij nodig heeft.
|
Lookup source |
Sleutel in |
Wat de connector gebruikt |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
— |
|
notulenMeetingTypes heb je niet nodig voor het agendapunt zelf. Je gebruikt het om de parameter meetingTypeId door te geven aan de sources die ervan afhangen.
Caching
De lookup sources onthouden wat het notulenpakket antwoordt. Zo gaat er niet bij elke keer dat een formulier opent een call naar het notulenpakket. Agendapunten, hun status, hun bijlagen en hun besluitdocumenten worden nooit gecachet.
-
Een cache per source. Elke source heeft een eigen cache, per combinatie van parameters. De zittingen van het ene soort zitting worden apart bewaard van die van een ander soort.
-
Mislukte calls. Een mislukte call wordt niet bewaard: de volgende vraagt opnieuw.
-
Gelijktijdige vragen. Vragen meerdere gebruikers tegelijk dezelfde lijst op, dan gaat er maar één call naar het notulenpakket.
-
Een cache per node. Elke node heeft een eigen cache, en niets maakt die van buitenaf leeg. Een wijziging in het notulenpakket zie je pas als de ttl verstreken is.
Zittingen blijven standaard 5 minuten bewaard, de andere lijsten 1 uur. Je wijzigt dat met de eigenschappen skryv.connectors.notulen.cache.* (zie Applicatie eigenschappen). Een ttl van 0 zet de cache uit voor die source.
Het notulenpakket biedt alleen zittingen aan waarvan de deadline nog niet verstreken is. Een formulier kan een zitting nog aanbieden tot 5 minuten na die deadline. Een agendapunt voor die zitting indienen mislukt dan.