Samenwerkfunctionaliteit

De REST API samenwerkfunctionaliteit (SWF) van het Digitaal Stelsel Omgevingswet. Er zijn services beschikbaar voor het starten, inzien, en stoppen van een samenwerking, het uitnodigen van ketenpartners om deel te nemen aan een samenwerking. Daarnaast kunnen documenten worden geüpload en gedownload. Ook kunnen actieverzoeken worden uitgezet, gereed gemeld of weer worden ingetrokken. Tot slot kunnen notificaties die op basis van een samenwerkingsgebeurtenis ontstaan, worden ontvangen (opgehaald) of verwijderd.

Label: Samenwerken

Endpoint Pre-productieomgeving V4

https://service.pre.omgevingswet.overheid.nl/overheid/samenwerken
/api/behandelen/v4

Endpoint Productieomgeving

https://service.omgevingswet.overheid.nl/overheid/samenwerken
/api/behandelen/v4

Release notes V4

De definitieve release notes (pdf, 448 kB) geven de wijzigingen aan ten opzichte van V3.

De introductie van versie 4 (V4) brengt een breaking change met zich mee, waardoor samenwerkingen die gecreëerd zijn vóór de release van V4, niet meer toegankelijk zullen zijn en zullen worden verwijderd.

Beveiligde REST-service

Vraag toegang aan voor deze beveiligde REST-service voor de PRE-productieomgeving via het aanvraagformulier.

Omschrijving

De samenwerkfunctionaliteit (SWF) maakt samenwerking tussen bestuursorganen onderling en tussen bestuursorganen en ketenpartners mogelijk, om zo de behandeling van een verzoek te ondersteunen en de doorlooptijd van de behandeling te verkorten. De SWF maakt het uitwisselen van documenten mogelijk en het uitzetten van actieverzoeken tussen de deelnemers aan de samenwerking onderling. De SWF-services worden ontsloten via het Open Stelsel voor Derden (OSvD), zodat ze direct door een externe toepassing (VTH- of zaaksysteem) gebruikt kunnen worden.

De volgende services zijn beschikbaar:

  • Het starten van een samenwerking. Hierbij wordt een samenwerkingsdossier met bijbehorende identificatie gecreëerd (het samenwerkingID) en wordt (optioneel) een bijbehorend “verzoek” (vergunningsaanvraag) opgehaald uit het DSO-LV en in een digitaal samenwerkdossier geplaatst. Het is ook mogelijk om, via het eigen zaak- of VTH-systeem, een samenwerking te starten op basis van een OLO-aanvraag. Een samenwerking kan alleen door een bevoegd gezag of behandeldienst worden gestart: de initiator van de samenwerking.
    Gegevens die betrekking hebben op de samenwerking (metadata) kunnen worden toegevoegd, gewijzigd en ingezien. In de periode tot inwerkingstreding van de Omgevingswet is het ook mogelijk om samenwerkingen te starten op basis van OLO-verzoeken; echter zulke verzoeken kunnen niet worden opgehaald uit OLO maar moeten via het VTH- of zaaksysteem van de gebruiker worden ingebracht in de samenwerking.
  • Het uitnodigen van ketenpartners om deel te nemen aan de samenwerking. Dit gebeurt op basis van het OIN (Organisatie-identificatienummer) van de betreffende ketenpartner. Bij de uitnodiging kan de ketenpartner een "privilege" worden toegekend, te weten "Volledige toegang" of "Beperkte toegang". Bij privilege "Beperkte toegang" heeft de betreffende ketenpartner alleen toegang tot documenten die als "Vertrouwelijk" zijn gemarkeerd. Alle documenten die onderdeel van een samenwerking uitmaken zijn vertrouwelijk, maar deze documenten bevatten geen persoonsgegevens en ook geen bedrijfsgevoelige gegevens. Bij privilege "Volledige toegang” heeft de betreffende ketenpartner daarnaast toegang tot documenten die als "Strikt vertrouwelijk" zijn gemarkeerd. Dergelijke documenten bevatten mogelijk wél persoonsgegevens en/of bedrijfsgevoelige gegevens. Alleen de initiator kan ketenpartners uitnodigen.
  • Het verwijderen van een ketenpartner uit de samenwerking. Alleen de initiator kan ketenpartners verwijderen.
  • Het aanpassen van de privileges van een ketenpartner. Alleen de initiator kan privileges aanpassen.
  • Het toevoegen van een document aan het samenwerkdossier, waarbij moet het vertrouwelijkheidskenmerk (“Strikt vertrouwelijk” of “Vertrouwelijk”) van het document worden aangegeven. Het samenwerkdossier bestaat uit een DSO-voorziening voor de opslag van documenten; zgn. “federatieve toegang” tot documenten wordt op dit moment niet ondersteund. Gegevens die betrekking hebben op een document (metadata) kunnen worden toegevoegd, gewijzigd en ingezien.
  • Het downloaden van een document uit het samenwerkdossier, mits de privileges van de ketenpartner die het document downloadt overeenkomen met het vertrouwelijkheidskenmerk van het document.
  • Het aanpassen van de rechten die een ketenpartner heeft op een (specifiek) document. Hiermee wordt het mogelijk om een ketenpartner rechten te geven die niet overeenkomen met het privilege dat aan de ketenpartner is toegekend.
  • Het verwijderen van een document uit het samenwerkdossier.
  • Het actualiseren van de inhoud en/of de metadata van een document in het samenwerkdossier.
  • Het uitzetten van een actieverzoek (en gereed melden of intrekken), bijvoorbeeld het verzoek om een brandveiligheidsadvies te geven aan een veiligheidsregio. Elke deelnemer aan de samenwerking kan een actieverzoek uitzetten voor elke andere deelnemer. Een actieverzoek kan worden gereed gemeld (eventueel met toelichting) of weer worden ingetrokken (eventueel ook met toelichting).
  • Het ophalen van notificaties. De meeste gebeurtenissen die tijdens een samenwerking optreden (toevoegen document, uitzetten van een actieverzoek, etc.) leiden tot een notificatie aan de betrokkene(n). Deze notificaties kunnen door aangesloten systemen actief worden opgehaald waarna ze zelf gepaste verdere actie kunnen ondernemen.
    Het formaat van notificaties is beschreven; zie 'beschrijving notificaties' onder kopje documentatie.
  • Het verwijderen van notificaties die door het aangesloten systeem zijn verwerkt.
  • Overzicht geven van:
    • Aan welke samenwerkingen je als initiator of ketenpartner deelneemt;
    • De deelnemers die een bepaalde samenwerking kent;
    • De documenten die onderdeel uitmaken van een bepaald samenwerkdossier;
    • Welke actieverzoeken er voor je uitstaan of die je hebt uitgezet;
    • Welke notificaties er voor je zijn.
  • Het stoppen van een samenwerking. Als een samenwerking is afgerond dan kan deze worden gestopt. Dit betekent dat er geen documenten meer kunnen worden toegevoegd (zie hieronder) en er ook geen actieverzoeken meer kunnen worden uitgezet. De deelnemers aan de samenwerking worden van deze gebeurtenis genotificeerd. Wél kunnen ze, totdat de het samenwerkdossier fysiek wordt verwijderd, relevante documenten uit het samenwerkdossier downloaden om aan hun archiveringsverplichtingen te voldoen.
  • Het verwijderen van een samenwerking. Alle gegevens van het dossier, dus documenten, actieverzoeken en notificaties worden dan fysiek verwijderd. Dit kan alleen als de samenwerking eerst gestopt is. Het verwijderen van een samenwerking gebeurt ook automatisch één (1) jaar nadat de samenwerking is gestart, ongeacht of deze nu gestopt is of niet.

Known issues

Issue SWF-PI17-001

12 maart 2021: Het ophalen van notificaties leidt regelmatig tot foutmeldingen (401; unauthorized). Er wordt aan gewerkt om dit probleem op te lossen. Als “workaround” wordt het volgende voorgesteld: beperk de frequentie waarmee notificaties worden opgesteld tot één keer per 1-5 minuten, per gebruiker waar voor de notificaties worden opgehaald. Het aantal keren dat dit probleem optreedt wordt dan sterk gereduceerd of zelfs teruggebracht tot nul.

Documentatie

Aanvullende informatie

  • De API is beschikbaar voor bevoegd gezagen en voor ketenpartners in de samenwerking, mits deze in het bezit zijn van een PKIO-certificaat.

Status

Pre-productieomgeving:  versie 4

Productieomgeving: versie 4

Meer informatie

Deze service is van belang bij het afhandelen van een verzoek.

PKIoverheid-certificaat

Deze service kan alleen worden gebruikt met een PKIoverheid-certificaat.

Feedback

Ga naar het forum om je bevindingen te delen.