Signalen REST API

De volledige functionaliteit van Signalen is te gebruiken via de REST API. Deze API wordt gebruikt door de frontend, maar kan ook gebruikt worden door externe systemen om informatie uit Signalen te halen en acties uit te voeren. Denk bijvoorbeeld aan het veranderen van de status van een melding en het plaatsen van interne notities.

Techniek

Een extern systeem authenticeert zich bij Signalen met een systeemgebruiker door middel van een JWT token. Dit token wordt meegestuurd in de Authorization header. Door middel van rechten en rollen kan ingesteld worden welke acties toegestaan zijn voor de systeemgebruiker.

De volledige API documentatie kan bekeken worden via de OpenAPI specificatie.

Melding afhandelen

Met behulp van de API is het ook mogelijk om meldingen af te handelen. Een extern systeem kan meldingen op een bepaalde categorie en/of afdeling periodiek ophalen en afhandelen. Het ophalen van de meldingen kan met het volgende request:

GET /signals/v1/private/signals/?status=m&routing_department_code=<afdelingscode>
...
"results": [
    {
        "id": 1,
        ...
    }
]

Het externe systeem kan vervolgens voor iedere nog niet opgepakte melding een melding aanmaken in het eigen systeem en het meldingsnummer van Signalen opslaan bij de melding in het eigen systeem. Daarna koppelt het externe systeem de status "In afwachting van behandeling" terug naar Signalen met behulp van het volgende request:

PATCH /signals/v1/private/signals/{id}
{
    "status": {
        "state": "i",
        "text": "In behandeling via <naam externe applicatie>"
    }
}

Zodra de melding is afgehandeld in het externe systeem kan het externe systeem de status "Extern: verzoek tot afhandeling" terugkoppelen naar Signalen met behulp van het volgende request:

PATCH /signals/v1/private/signals/{id}
{
    "status": {
        "state": "closure requested",
        "text": "Afgehandeld via <naam externe applicatie>: <omschrijving>"
    }
}

De behandelaar in Signalen kan vervolgens de afhandeling beoordelen en de afhandeling verzorgen naar de melder door de melding op "Afgehandeld" te zetten.

Rekening houden met tussentijdse wijzigingen in Signalen

Eventueel kan het externe taakafhandelsysteem rekening houden met het feit dat meldingen - nadat ze verzonden zijn naar het externe systeem - aangepast worden in Signalen. Denk bijvoorbeeld aan het aanpassen van de categorie of een status.

Dit kan het externe taakafhandelsysteem doen door periodiek de API te pollen voor de lopende meldingen en meldingen af te sluiten in het eigen systeem op het moment dat de categorie gewijzigd wordt of de status aangepast wordt.

Liteweb

De standaardkoppeling met Liteweb is als volgt geïmplementeerd:

• Meldingen worden aangemaakt in Signalen op de status "Gemeld".
• Liteweb pakt de meldingen in de afdeling LIT op, zet de status opnieuw op "Gemeld" en rapporteert het meldingsnummer van Liteweb terug.
• Liteweb zet de status iets later op "In afwachting van behandeling" als de melding in het systeem verwerkt is.
• Liteweb zet de status op "In behandeling" als de melding is veiliggesteld (mail naar melder wordt verstuurd).
• Liteweb zet de status op "Ingepland" als de melding is ingepland (mail naar melder wordt verstuurd).
• Liteweb zet de status op "Afgehandeld" als de melding is afgehandeld.