CAPO API Handleiding

CAPO API

De API van CAPO zorgt ervoor dat vrijwel alle functionaliteit in CAPO ook via een API is te gebruiken vanuit de eigen systemen.

Documentatie over de CAPO API is hier terug te vinden:

• Productie: https://services.dsplatform.nl/api/capo/documentation/#/

• Acceptatie: Swagger UI

De documentatie is ook als .JSON te downloaden: https://services.dsplatform.nl/api/capo/documentation.json

Toegang krijgen tot de CAPO API

De CAPO API is beschikbaar voor netbeheerders en aannemers in de contractgebieden die CAPO ondersteunt. Zie hiervoor de lijst van ondersteunde contractgebieden op de CAPO wiki. Om als organisatie toegang te krijgen tot de API kan een Informatieverzoek service request worden aangemaakt op onze Servicedesk. Er wordt dan een token voor je organisatie aangemaakt en verstuurd naar de primaire contactpersoon van die organisatie. Met deze token kan de API vervolgens gebruikt worden.

Indien je organisatie toegang heeft gekregen tot de API en er later incidenten optreden dan kunnen deze gemeld worden via de servicedesk van Mijn Aansluiting. Voeg hier een verwijzing aan toe van de eerdere toekenning van toegang voor jouw organisatie aan de CAPO API.

Om gebruik te kunnen maken van één van de API’s, dient het volgende service request te worden gebruikt:

https://mijnaansluiting.atlassian.net/servicedesk/customer/portal/1/group/24/create/197

Let op!: voor alle API’s worden dezelfde credentials gebruikt.
Dus als de deelnemer al credentials heeft voor de DSP API, dan kunnen die credentials ook gebruikt worden voor de CAPO API, mits de deelnemer toegang heeft tot de API.

Voorbeeld:

• Deelnemer maakt al gebruik van de DSP API en wil ook gebruik maken van de CAPO API.

• Deelnemer legt een ticket in om toegang te krijgen tot de CAPO API.

• Wanneer het ticket is afgerond, kan de deelnemer van de CAPO API gebruik maken met dezelfde credentials die hij voor de DSP API gebruikt.

Scope uitbreiden

De acties die een API gebruiker mag uitvoeren worden is de scope van een gebruiker. Bijvoorbeeld bij het uitrollen van nieuwe functionaliteit moet de scope worden uitgebreid. Dit doen we op verzoek. Bij een 401 - Scope insufficient melding kan je een ticket inleggen bij Functioneel beheer om de scope van de user uit te laten breiden. Geef daarbij aan wat de actie is die je probeert uit te voeren.

Limiet aantal verzoeken

Rate limiting is per client op het geheel van services, niet per API endpoint.

Uitleg veel voorkomende scenario’s

Hieronder worden een aantal scenario’s wat verder uitgelegd met voorbeelden, naar aanleiding van vragen van gebruikers. Let op dat de documentatie in de APIs zelf leading is, en onderstaande ter aanvulling.

Uploaden toegewezen bijlage

In CAPO werken we met toegewezen bijlagen. De toegewezen bijlage kan gezien worden als een container waar deelnemers bestanden (bijlagen) aan kunnen toevoegen. Het doel van deze container is het begeleiden van de projectvoortgang, door duidelijk te maken welke partij er verantwoordelijk is, wat de inhoud is en wat de planning(/tijdigheid) is van dit deel van het project.

• Een toegewezen bijlage is toegewezen aan een organisatie. Deze organisatie wordt geacht deze bijlage op te leveren

• Onder een toegewezen bijlage kunnen tot aan oplevering meerdere bestanden/bijlagen worden geupload.

• Na oplevering zijn er geen wijzigingen meer mogelijk op de toegewezen bijlage

Om via de API bijlagen (bestanden) te uploaden onder een toegewezen bijlage kunnen de volgende stappen worden gevolgd:

1. Vraag lijst bijlagen van specifiek project op
   GET /project/{projectId}/bijlageassigned
   Alternatief: alle bijlagen op naam van jezelf opvragen via GET /bijlageassigned

2. Vind juiste bijlageAssignedId. Bijv  "bijlageAssignedId": "62c7d159eb277e1b79161430"

3. Maak een URL voor de bijlage die je wil uploaden 
   POST ​/project​/{projectId}​/bijlageassigned​/{bijlageAssignedId}​/bijlage

4. Gebruik de teruggegeven URL direct om het bestand te uploaden

5. Geef aan dat het bestand is geupload
   PATCH /project/{projectId}/bijlage/{bijlageId} with content { "status": "uploaded" }

6. Als het het laatste bestand is voor deze bijlageAssigned; opleveren
   PATCH /project/{projectId}/bijlageassigned/{bijlageAssignedId} with content { "status": "done" }

Beoordelen toegewezen bijlage

Sommige bijlagen dienen beoordeeld te worden voordat ze opgeleverd worden. Welke dit zijn is per combi gebied vooraf instelbaar door de beheerder van het project.

Een te beoordelen toegewezen bijlage is te herkennen aan de boolean property requiresReview

Een toegewezen bijlage die beoordeeld moet worden volgt stap 1 t/m 5 van bovenstaand overzicht. Echter in plaats van direct opleveren (naar status done) gaat deze bijlage naar status review. Nadat de toegewezen bijlage is beoordeeld gaat deze bij goedkeur naar status done, na afkeur terug naar status uploaded (met verplicht een reden in veld reden) waarna het proces opnieuw begint.

Doorwerken na goedkeur

Het is mogelijk om door te werken aan een bijlage nadat de input van de andere partij is goedgekeurd. Dan wordt de toegewezen bijlage van status review terug geplaatst naar status assigned. Het systeem zal deze bijlage dan automatisch toewijzen aan de eigen organisatie.

Na deze statuswijziging terug assigned volgt weer het gebruikelijke proces.

Zie ook de uitleg van de statussen in de API’s onder PATCH '/project/{projectId}/bijlageassigned/{bijlageAssignedId} Swagger UI

Open

Voorbeelden van status flow

Samenvattend; een beoordeelde bijlage heeft bijvoorbeeld de volgende flows

• de volgorde van statussen in de happy flow:
  assigned → uploaded → review → done

• Bij één afkeur in het proces is de volgorde:
  assigned → uploaded → review → uploaded → review → done

• Bij één keer doorwerken na goedkeur in het proces is de volgorde:
  assigned → uploaded → review → assigned →uploaded → review → done

Ophalen reeds geuploade bijlagen/bestanden van een project

Om reeds geuploade bijlagen (bestanden) van een project te downloaden en te achterhalen bij welke toegewezen bijlage zij horen, zijn er een aantal stappen:

1. Ophalen lijst Toegewezen bijlagen op een project:
   GET /project/{projectId}/bijlageassigned

2. Ophalen lijst (al geuploade) bijlagen op een project:
   GET /project/{projectId}/bijlage

3. Koppelen van bijlage aan bijlageAssigned dmv parentId uit antwoord van /bijlage, dit heeft dezelfde waarde als bijlageAssignedId uit het antwoord op /bijlageassigned

Quickscan volgorde

Bij het uitvoeren van de Quickscan via de API door een netbeheerder zijn er een aantal stappen:

1. Doorgeven als er Hoofdleiding nodig is (optioneel) → POST /project/{projectId}/hoofdleiding-aanleggen

   1. Let op: De activiteit Hoofdleiding aanleggen (waar van toepassing) wordt automatisch aangemaakt zodra de status ‘aanvraag compleet’ bereikt is. Deze activiteit hoeft de API gebruiker niet zelf aan te maken.

2. Aangeven dat de Netbeheerder Extra werkvoorbereiding doet door een activiteit aan te maken van het type Extra werkvoorbereiding als dat relevant is → POST /project/{projectId}/activiteit

3. Aangeven of je Mee in Combi gaat → POST /project/{projectId}/mic

Let op: De Mee in Combi melding is altijd de laatste handeling.

De volgorde van handelingen tbv quickscan is belangrijk omdat, na de eerste combi melding van een netbeheerder, CAPO de quickscan beschouwt als afgerond. Hierna is het dan dus ook niet meer mogelijk om de andere twee handelingen te doen.

Contactgegevens gebruiker ophalen en doorgeven

Ophalen

Het emailadres van de individuele gebruiker die een actie heeft uitgevoerd in CAPO is beschikbaar via zowel de UI als de API. In de API vinden we deze informatie in de key email. Dit veld vinden we in de volgende types:

• type ActiviteitAct uitgebreid met key email

• type ActiviteitLogEntry bevat ActiviteitAct en is daarmee ook uitgebreid met key email

• type BijlageAct uitgebreid met key email

• type BijlageLogEntry uitgebreid met key email

Doorgeven

Sinds release 0.33.0 van de API is het mogelijk voor API gebruikers om deze gebruikers-informatie ook door te geven aan CAPO.

Elke POST, PUT en PATCH operatie ondersteunt nu de optionele header x-email hiermee is het mogelijk om aan iedereen te laten weten welke gebruiker de bewerking namens uw organisatie heeft uitgevoerd.

AGD: Aansluit Gereed Datum

In steeds meer gebieden wordt de klant gevraagd of hij/zij al gereed is, of op welke datum dat zal zijn. Deze werkwijze wordt per Contractgebied ‘aan’ gezet. Deze gegevens geven we ook door via de CAPO API.

Wordt AGD gebruikt in dit project?

Dit is zichtbaar op de projectdetails, GET /project/{projectId}, type agdRelevant. Bij waarde true wordt er op dit project AGD toegepast

Waar vind ik de AGD die de klant heeft doorgegeven?

De datum die de klant heeft doorgegeven geven we door op produkt niveau (= de combinatie van een aansluitobject en een discipline). Via GET /project/{projectId}, aansluitObjecten → produkten → agd. Het veldt geeft de datum die de klant heeft ingevuld. Deze kan ook leeg zijn als de klant niet weet wanneer hij aansluitgereed is.

Op dit moment zijn alle agd waarden binnen een project gelijk. Met het oog op de toekomst is het per produkt beschikbaar.

Wensdatum

Het veld wensdatum wordt ook gevuld bij projecten waarbij de AGD wordt gebruikt. Dit geeft, op projectniveau, aan wat de afgeleide aansluitgereeddatum zal zijn. Er zijn hiervoor 3 scenario’s:

1. De klant heeft een AGD aangegeven die eerder is dan de wachttijd van de netbeheerder
   → wensdatum = aanvraagDatum + wachttijd

2. De klant heeft geen AGD aangegeven
   → wensdatum = aanvraagDatum + wachttijd

3. De klant heeft een AGD aangegeven die later is dan de wachttijd van de netbeheerder:
   → wensdatum = de agd van het eerste produkt op dit project

Hoofdleiding projecten filteren op veranderingen

Filteren op Hoofdleiding projecten die veranderd zijn kan door in GET /hoofdleiding de parameters changedFrom en changedTo te gebruiken. Dit kijkt naar het veld changed en geeft alle projecten waar iets in veranderd is in de opgegeven tijdsspanne.

Filteren op projectplanning

Daarnaast is het mogelijk om de parameters planningChangedFrom en planningChangedTo te gebruiken. Deze filteren alleen op het veld planningChanged, waardoor er alleen projecten worden teruggegeven waarvan de startUitvoeringWeek is veranderd in de aangegeven periode.

Hoofdleiding; Algemene bijlagen

Naast toegewezen bijlagen zijn er ook Algemene bijlagen op hoofdleiding projecten. Deze bijlagen zijn niet aan één specifieke partij toegewezen en kunnen niet worden opgeleverd.

Welke Algemene bijlagen zijn er

Algemene bijlagen worden geconfigureerd per template, en dus per projectverantwoordelijke en per combi. Als een algemene bijlage is geconfigureerd in de template is deze op alle projecten van die projectverantwoordelijke/combi combinatie aanwezig.

Welke algemene bijlagen er geconfigureerd zijn is te zien via het Template scherm in CAPO en via de call GET /bijlageassigned/template door te filteren op een lege processtatus; “processtatus=”

Ook wordt er in de output van GET /bijlageassigned/template het kenmerk “isAlgemeen”: true teruggegeven als het een Algemene bijlage betreft

Downloaden Algemene bijlagen

Downloaden van bestanden die reeds geupload werkt hetzelfde als reguliere toegewezen bijlagen:

• Opvragen alle bijlagen op project via GET /project/{projectId}/bijlage

• Intern filteren op documentsoort: “Correspondentie” (of andere ‘algemene’ documentsoort)

• URL opvragen via GET /project/{projectId}/bijlage/{bijlageId}

• Downloaden bestand

Uploaden Algemene bijlagen

• Kennis is vooraf nodig welke Algemene bijlagen er bestaan bij een bepaalde projectverantwoordelijke. Bijvoorbeeld “Correspondentie”

• Via route POST /project/{projectId}/bijlage de bijlageID en url aanvragen

• Via curl --upload-file ./foto.png -X "PUT" "url hier let op aanhalingstekens" bestand naar S3 uploaden

• Via PATCH /project/{projectId}/bijlage/{bijlageId} patchen naar status uploaded

Deactiveren van een product

Het is mogelijk om een specifiek product (een discipline op een object) de deactiveren. Dit gaat als volgt:

1. Vind het specifieke disciplineId van het product dat je wil deactiveren via GET /project/{projectId} onder produkten (onder aansluitObjecten)

2. Gebruik route POST /project/{projectId}/product-actief om dit specifieke product inactief te maken. Het is verplicht om een reden mee te geven