Working version v32.1.X v32.0.X v29.1.X
Working version v32.1.X v32.0.X v29.1.X Dutch

FOCUS

Connector in opbouw.

Inleiding

FOCUS is de softwareapplicatie die lokale politiezones gebruiken om evenementen te beheren. De FOCUS-connector legt een link met deze applicatie om enerzijds evenementgegevens en bijbehorende bijlages door te spelen (een happening), en anderzijds advies van de politie over dat evenement op te vragen en op te volgen (een adviesaanvraag).

Use case

De FOCUS-connector wordt ingezet in evenementgerelateerde dossiers waarbij een advies van de lokale politie nodig is vooraleer een evenement (sportmanifestatie, festival, rommelmarkt, enzovoort) kan doorgaan of vergund wordt.

Typisch verloop binnen een Skryv-toepassing:

  1. Een burger of organisator dient een evenementaanvraag in via het digitale loket.

  2. De workflow maakt een happening aan in FOCUS (addHappening) met de evenementgegevens uit het dossier.

  3. Optioneel voegt de workflow bijlagen uit het dossier toe aan de happening, zoals een eventplan, kaart of risicoanalyse (uploadHappeningAttachment), en controleert later of FOCUS de bijlage effectief verwerkt heeft (getHappeningAttachmentUploadStatus).

  4. De workflow voegt een adviesaanvraag toe voor de bevoegde politiezone (addAdviceRequest).

  5. Zolang er nog geen advies is, pollt de workflow periodiek (bijvoorbeeld via een timer-event) of het advies al beschikbaar is (getUnconfirmedAdvice).

  6. Zodra een advies beschikbaar is, haalt de workflow het advies en eventuele bijlagen op (getAdvice, saveAdviceAttachment) en bevestigt de ontvangst (confirmAdvice).

  7. Het advies dient als input voor de verdere afhandeling van het dossier, bijvoorbeeld bij de beslissing of de motivering ervan.

  8. Wordt de aanvraag ingetrokken of geannuleerd vóór het advies binnen is, dan trekt de workflow de adviesaanvraag in (repealAdviceRequest).

Setup

Onboarding bij FOCUS

Neem via de lokale politiezone contact op met het FOCUS-team om de onboardingprocedure te doorlopen. Tijdens dit proces verkrijg je de informatie die je via de applicatie eigenschappen moet toevoegen. Je krijgt ook toegang tot de FOCUS OpenAPI-specificatie. Die heb je nodig om specifieke calls op te bouwen.

Dependency toevoegen in het pom.xml bestand

Voeg onderstaande dependency toe aan het pom.xml bestand van je applicatie. Dit zorgt ervoor dat de connector code ingeladen wordt bij de build van de applicatie.

 <dependency>
      <groupId>com.skryv.connectors</groupId>
      <artifactId>focus</artifactId>
 </dependency>

Applicatie eigenschappen

Eigenschap

Default

Beschrijving

FocusProperties

skryv.connectors.focus.api.base-url

-

FOCUS base URL

skryv.connectors.focus.api.timeout

30000

Timeout (ms)

skryv.connectors.focus.api.token-url

-

Token URL

skryv.connectors.focus.api.client-id

-

Client ID

skryv.connectors.focus.api.client-secret

-

Client secret

FocusBusinessConnector

skryv.connectors.focus.api.provider

egovflow

FOCUS provider name

Services en functies

Overzicht

Advice

Functie

Retourtype

Info

addAdviceRequest

Object (ongetypeerd)

Adviesaanvraag koppelen aan een evenement, met zelf gegenereerde adviceRequestId.

confirmAdvice

Object (ongetypeerd)

Ontvangst van een advies bevestigen (haalt intern zelf de confirmationToken op).

getAdvice

Advies-response (met bijlagenlijst en confirmationToken)

Volledig advies opvragen voor een adviesaanvraag.

getUnconfirmedAdvice

UnconfirmedAdvice

Nagaan of er een onbevestigd advies is voor een evenement (pollingstap).

repealAdviceRequest

(geen)

Adviesaanvraag intrekken.

saveAdviceAttachment

Attachment

Bijlage bij een advies ophalen en als dossierbijlage opslaan.

Happening

Functie

Retourtype

Info

addHappening

Object (ongetypeerd)

Evenement aanmaken bij FOCUS.

getHappening

Object (ongetypeerd)

Bestaand evenement opvragen.

getHappeningAttachmentUploadStatus

UploadsUploadIdGet200Response

Nagaan of FOCUS de geüploade bijlage ook verwerkt heeft.

updateHappening

Object (ongetypeerd)

Bestaand evenement wijzigen.

uploadHappeningAttachment

String (uploadId)

Een dossierbijlage uploaden naar een happening in FOCUS.

Er zijn op dit moment geen kant-en-klare workflow expressies voorzien voor de FOCUS-functies. Elke aanroep verloopt via een workflow script task: de developer stelt daarin zelf de JSON-payload samen volgens de FOCUS OpenAPI-spec en roept de gewenste functie aan op de geïnjecteerde focus-bean. Dit is een bewuste, tijdelijke aanpak in afwachting van een uitgewerkte procesopzet met eigen businesslogica in de backend. Deze pagina is daarom momenteel enkel relevant voor developers, niet voor pure Studio-configuratoren.

Elke functie hieronder is, naast de workflow, ook rechtstreeks aanroepbaar vanuit Java-code door FocusConnector (bean focus) te injecteren in je klasse.

Java
@RequiredArgsConstructor
public class MyOwnService {
    private final FocusConnector focus;
}

Advice

addAdviceRequest

Java-code

Object response = focus.addAdviceRequest(externalId, adviceRequestId, request);

Input

Parameter

Data type

Voorbeeld

Uitleg

externalId

String

-

De external ID van de happening waarvoor advies gevraagd wordt.

adviceRequestId

String

-

Zelf gegenereerde identifier voor deze adviesaanvraag (pad-parameter, vandaar PUT).

request

JSON-object conform FOCUS OpenAPI-spec

Zie onder

De configuratie van de adviesaanvraag.

Structuur van request (verplicht: type):

  • type (string, max 50): bv. "Technisch advies".

  • options (array, min. 2 items): de mogelijke adviesuitkomsten, elk met label, value (patroon ^[a-zA-Z0-9_]*$) en optioneel fields (extra invulvelden met key, label, required, maxLength).

  • attachments (optioneel): allowedTypes (array, bv. "IMAGE") en maxAmount (1 tot 10).

Output

Geen output, anders dan statuscodes.

Error-handling

Statuscode

Betekenis

201

Happening aangemaakt.

404

Happening bestaat niet.

409

adviceRequestId bestaat al.

422

Onverwerkbaar

confirmAdvice

Java-code

Object response = focus.confirmAdvice(advice); // advice: UnconfirmedAdvice

Input

Parameter

Data type

Uitleg

advice

UnconfirmedAdvice

Het onbevestigde advies dat je wil bevestigen (bv. het resultaat van getUnconfirmedAdvice). Moet minstens externalId en externalAdviceId bevatten.

De connector haalt intern zelf eerst getAdvice() op om de confirmationToken te vinden, en stuurt die dan door naar FOCUS — je geeft die token dus niet zelf mee.

Output

Geen inhoud, anders dan statuscodes.

Error-handling

Situatie

Gedrag

advice is null, of externalId/externalAdviceId ontbreekt

IllegalArgumentException

Geen confirmationToken gevonden in het opgehaalde advies

IllegalStateException

FOCUS antwoordt met een REST-foutcode tijdens de effectieve bevestiging

  • 204 (bevestigd),

  • 400 (ongeldige/ontbrekende confirmationToken),

  • 404 (happening of adviesaanvraag niet gevonden),

  • 409 (advies kan gewijzigd zijn sinds ophalen)

getAdvice

Java-code

HappeningsProviderExternalIdAdviceRequestsAdviceRequestIdAdviceGet200Response response =
        focus.getAdvice(externalId, adviceRequestId);

Input

Parameter

Data type

Uitleg

externalId

String

External ID van de happening.

adviceRequestId

String

ID van de adviesaanvraag.

Output

Veld

Uitleg

confirmationToken

Token nodig om het advies te bevestigen via confirmAdvice.

advice.author

Auteur van het advies.

advice.adviceTime

Tijdstip van het advies.

advice.advice

De adviestekst zelf.

advice.fields

Bijkomende, vrij ingevulde velden (structuur niet vast gedefinieerd in de spec).

advice.attachments[]

Lijst van bijlagen (name, description, attachmentId). Elk afzonderlijk op te halen via saveAdviceAttachment.

Geeft null terug als de adviesgever nog geen advies gegeven heeft — FOCUS antwoordt dan met een 404, die de connector zelf opvangt en vertaalt naar null. Dit is een normale, verwachte toestand voor een proces dat nog op advies wacht, geen fout.

Error-handling

Geen specifieke foutcodes: een 404 betekent dat er nog geen advies is en komt als null terug (zie Output).

getUnconfirmedAdvice

Deze functie is een pollingstap: ze haalt de volledige lijst van onbevestigde adviezen op voor de eigen provider (GET /happenings/{provider}/advices/unconfirmed) en filtert die client-side op externalId én adviceRequestId. Er is geen server-side filterparameter. Bij elke aanroep wordt dus de volledige lijst opgehaald en pas daarna doorzocht.

Java-code

UnconfirmedAdvice advice = focus.getUnconfirmedAdvice(externalId, adviceRequestId);

Input

Parameter

Data type

Uitleg

externalId

String

External ID van de happening waarvoor je wil weten of er onbevestigde adviezen zijn.

adviceRequestId

String

ID van de specifieke adviesaanvraag waarvoor je wil weten of er al een onbevestigd advies is.

Output

Situatie

Resultaat

Onbevestigd advies gevonden voor deze combinatie van happening én adviesaanvraag.

Een UnconfirmedAdvice met externalId, externalAdviceId en status.

Geen match, of de lijst is leeg.

null

Error-handling

Situatie

Gedrag

externalId of adviceRequestId is null

Geen call naar FOCUS. Waarschuwing gelogd, null teruggegeven.

Geen match in de lijst

null, zonder logging. Normaal, verwacht scenario.

repealAdviceRequest

Java-code

focus.repealAdviceRequest(externalId, adviceRequestId);

Input

Parameter

Data type

Uitleg

externalId

String

External ID van de happening.

adviceRequestId

String

ID van de adviesaanvraag die ingetrokken wordt.

De connector verstuurt hierbij zelf een leeg JSON-object als request body. Er is geen inhoudelijke input mee te geven.

Output

Geen output, anders dan statuscodes.

Error-handling

Statuscode

Betekenis

204

Ingetrokken.

404

Happening of adviesaanvraag niet gevonden

saveAdviceAttachment

Java-code

Attachment attachment = focus.saveAdviceAttachment(dossierId, externalId, adviceRequestId, attachmentId);

Input

Parameter

Data type

Uitleg

dossierId

String

ID van het Skryv-dossier waaraan de bijlage toegevoegd moet worden.

externalId

String

External ID van de happening.

adviceRequestId

String

ID van de adviesaanvraag.

attachmentId

String (uuid)

ID van de specifieke bijlage, zoals opgelijst in advice.attachments[] bij getAdvice.

Output

Een Attachment, opgeslagen bij het opgegeven dossier. Bestandsnaam en content-type worden niet uit het JSON-antwoord gehaald, maar rechtstreeks uit de HTTP-headers van FOCUS: de bestandsnaam komt uit Content-Disposition, het content-type uit Content-Type. De connector saniteert de bestandsnaam (verwijdert niet-toegelaten tekens) en garandeert dat er een extensie aanwezig is.

Error-handling

Situatie

Gedrag

Lege of ontbrekende bijlage-inhoud

IllegalStateException ("Focus returned empty attachment for attachmentId ...")

Geen bestandsnaam in Content-Disposition

IllegalStateException ("Focus Content-Disposition missing filename ...")

Bestandsnaam zonder extensie na sanitisatie

IllegalStateException ("Focus Content-Disposition missing file extension ...")

FOCUS geeft 404

(niet apart afgevangen — zie algemeen openstaand punt over RequestExecutor)

Happening

addHappening

Java-code

Object response = focus.addHappening(request);

Input

Parameter

Data type

Uitleg

request

JSON-object conform FOCUS OpenAPI-spec

De evenementgegevens, samengesteld volgens de FOCUS OpenAPI-specificatie voor deze operatie. De connector legt geen eigen Skryv-modelstructuur op. Je bouwt het object zelf op, conform de FOCUS-specs, en geeft het ongewijzigd door.

Top-level structuur van request (beide verplicht):

  • happening: de kerngegevens van het evenement: startTime, endTime, name (max 255), happeningTypeKey (enum: escort, filmShoot, localSoccer, manifestation, publicDomainIntake, studentActivity), externalId, externalReference, en location (één van vier varianten: fixedLocation, multipleFixedLocations, trail of specialLocation).

  • providerData: bijkomende context zoals contactpersonen, locatie-intakes, hindermuziek, activiteiten (bv. drones met piloten) en beveiliging/diensten.

Voor de volledige, gedetailleerde structuur (verplichte velden, enums, varianten) verwijzen we naar de FOCUS OpenAPI-documentatie zelf.

Output

Geen response body.

Error-handling

Statuscode

Betekenis

200

Succesvol aangemaakt.

422

Onverwerkbaar (bv. verplicht veld ontbreekt of ongeldige waarde).

getHappening

Java-code

Object response = focus.getHappening(externalId);

Input

Parameter

Data type

Uitleg

externalId

String

External ID van de happening die je wil ophalen.

Output

Object, ongetypeerd. De spec definieert voor dit endpoint geen response-schema (enkel de statuscodes).

Error-handling

Statuscode

Betekenis

404

Happening bestaat niet.

getHappeningAttachmentUploadStatus

Java-code

UploadsUploadIdGet200Response status = focus.getHappeningAttachmentUploadStatus(uploadId);

Input

Parameter

Data type

Uitleg

uploadId

String

De waarde die uploadHappeningAttachment teruggaf.

Output

Veld

Uitleg

id

ID van de upload.

status

pending-upload, processing of completed. Bij een mislukte verwerking staat hier failed.

failure

Bij een mislukking: code en message. Anders null.

Error-handling

Geen eigen afhandeling in de connector. Een foutstatus van FOCUS komt als HTTP-exceptie naar boven.

updateHappening

Java-code

Object response = focus.updateHappening(externalId, request);

Input

Parameter

Data type

Uitleg

externalId

String

External ID van de happening die je wil wijzigen.

request

JSON-object conform FOCUS OpenAPI-spec

Partiële update: je geeft enkel de top-level sleutel(s) mee die je wil wijzigen — happening en/of providerData, beide optioneel op het hoogste niveau.

Output

Object, ongetypeerd. Geen response-schema gedefinieerd (net als bij getHappening/addHappening).

Error-handling

Statuscode

Betekenis

404

Happening bestaat niet.

422

Onverwerkbaar.

uploadHappeningAttachment

Java-code

String uploadId = focus.uploadHappeningAttachment(dossierId, externalId, attachmentId, type, description, author);

Input

Parameter

Data type

Uitleg

dossierId

String

ID van het Skryv-dossier waarin de bijlage zit.

externalId

String

External ID van de happening waaraan de bijlage toegevoegd wordt.

attachmentId

String

ID van de dossierbijlage die je doorstuurt. Dit ID wordt ook als referentie aan FOCUS meegegeven.

type

String (max. 255)

Optioneel. Soort bijlage in FOCUS, bijvoorbeeld plan. Bij null of leeg wordt document gebruikt.

description

String (max. 1000)

Optioneel. Omschrijving van de bijlage.

author

String (max. 255)

Optioneel. Auteur van de bijlage.

De bestandsnaam en het bestandstype haalt de connector uit de dossierbijlage zelf (de originele bestandsnaam, anders de opgeslagen naam).

Ondersteunde bestandstypes. De FOCUS-spec kent een gesloten lijst: PDF, BMP, JPEG, PNG en Microsoft Office-bestanden (Word, Excel, PowerPoint, inclusief sjablonen en macro-varianten). Elk ander type weigert de connector vóór er een call naar FOCUS vertrekt, met een foutmelding die de ondersteunde types opsomt. FOCUS communiceert geen maximale bestandsgrootte.

Output

De uploadId van de upload in FOCUS. Gebruik die voor getHappeningAttachmentUploadStatus.

Dat de aanroep slaagt, betekent niet dat het bestand verwerkt is. FOCUS verwerkt de bijlage achteraf, en een mislukte verwerking zie je pas via de statusfunctie.

Error-handling

Situatie

Gedrag

Bijlage niet gevonden in het dossier

NotFoundException

Bestandstype niet ondersteund door FOCUS

IllegalArgumentException

FOCUS geeft geen handler, uploadticket of uploadlocatie terug

IllegalStateException

Uploadlocatie heeft een onverwachte vorm

IllegalStateException

Bestandsinhoud kan niet geopend of gesloten worden

IllegalStateException

FOCUS antwoordt met een foutstatus (bijvoorbeeld 404 of 422)

Niet apart afgevangen

De drie opeenvolgende FOCUS-calls en de bestandsoverdracht worden niet automatisch herhaald. Een herhaling zou een dubbele handler of ticket aanmaken, en de uploadlocatie is eenmalig bruikbaar en verloopt na 60 seconden.