1. Algemeen

Met behulp van de cloudplan webservice kunt u gegevens uit cloudplan ophalen en wegschrijven. De webservice wisselt gegevens uit via SOAP en XML. Hierbij valt te denken aan o.a.:

• projectgegevens
• personeelgegevens
• klantgegevens
• planning

Wat u precies kunt aanroepen van de webservice is te zien op de overzichtspagina van de webservice, beschikbaar op https://api.cloudplan.nl/v1/.
Hier zijn ook de WSDL's  te vinden die u nodig heeft als u bijvoorbeeld wilt experimenteren met bijvoorbeeld SoapUI.  

Iedere service heeft zijn eigen WSDL. Voor de authenticatieservice is dit bijvoorbeeld https://api.cloudplan.nl/v1/authentication?wsdl
SoapUI kan automatisch voorbeeldrequests voor u genereren aan de hand van de WSDL, en kunt u op eenvoudige wijze experimenteren.
De open source versie is gratis en beschikbaar op https://www.soapui.org/open-source.html

2. Ophalen, toevoegen, wijzigen en verwijderen van gegevens

Voor het gebruik van de cloudplan webservice dient u eerst in te loggen waarna u een authenticatietoken teruggestuurd krijgt.  Voor elke request die u doet dient u het verkregen authenticatietoken mee te sturen. Het proces is hieronder schematisch weergegeven. 

Gegevens in Cloudplan toevoegen en wijzigen kunt u doen mbv een 'push...' , ophalen met een 'get..' en verwijderen met 'delete...'.  Zie ook de overzichtspagina voor de beschikbare webmethods.

3. Matchers

In de XML die u naar de webservice stuurt zult u gebruik maken van matchers. Deze matchers bepalen welke gegevens opgehaald, gewijzigd of verwijderd moeten worden in cloudplan (get, push, delete).  Dat kunnen 1 of meerdere records zijn.  In het voorbeeld hieronder worden twee projecten opgehaald met projectnummers PROJ-01 en PROJ-02.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="https://api.cloudplan.nl/">
   <soapenv:Header/>
   <soapenv:Body>
      <api:getProjects>
         <authentication>
            <token>F42A1BA2F83074526E7E18238FA2D5C0</token>
         </authentication>
         <projectMatcher allowMultiple="false">
            <number>PROJ-01</number>
         </projectMatcher>
         <projectMatcher allowMultiple="false">
            <number>PROJ-02</number>
         </projectMatcher>
      </api:getProjects>
   </soapenv:Body>
</soapenv:Envelope>

Per matcher krijgt u vervolgens ook het resultaat terug.

Het volgende voorbeeld laat zien dat een enkele matcher ook meerdere resultaten kan opleveren, en dat binnen een matcher soms ook andere matchers gebruikt kunnen worden. Hieronder wordt alle planning opgehaald voor een klant met klantnummer 'KLANT-01' in de periode maart 2019:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="https://api.cloudplan.nl/">
   <soapenv:Header/>
   <soapenv:Body>
      <api:getPlanning>
         <authentication>
            <token>F42A1BA2F83074526E7E18238FA2D5C0</token>
         </authentication>
         <planningMatcher allowMultiple="true">
            <customerMatcher allowMultiple="false">
               <number>KLANT-01</number>
            </customerMatcher>
			<start>
         </planningMatcher>
      </api:getPlanning>
   </soapenv:Body>
</soapenv:Envelope>

Gebruik het 'nummer' veld in cloudplan om hierin uw eigen (unieke) referentie op te slaan (zoals projectnummer/personeelsnummer/afdelingsnummer/etc) , zodat uw de gegevens later ook weer makkelijk kunt terugvinden. De meeste matchers staan toe dat u zoekt op het nummer veld.

Elke matcher heeft een attribuut allowMultiple. Stel deze in op "FALSE" als u een enkel resultaat verwacht.  Dit is vooral nuttig als u gegevens wijzigt/verwijderd in een push/delete en verwacht dat slechts een enkel record wordt aangepast/verwijderd Als deze is ingesteld op false, maar de matcher levert wel meerdere resultaten op, dan zal er een foutmelding worden teruggestuurd. 

Binnen een matcher zijn diverse elementen beschikbaar om op te zoeken. Sommige elementen hoeven niet gespecificeerd te worden. Deze zijn te herkennen aan het Optional commentaar boven de tag.

Datum matcher

Een datum matcher bestaat uit een operator en een datum. Als er een datetime type gevraagd wordt, maar er is alleen een datum opgegeven, dan wordt de tijd op 00:00:00 gezet. De mogelijke operatoren zijn:

• EQUALS_TIME
• EQUALS_DATE
• AFTER_OR_EQUAL_TIME
• AFTER_OR_EQUAL_DATE
• AFTER_TIME
• AFTER_DATE
• BEFORE_OR_EQUAL_TIME
• BEFORE_OR_EQUAL_DATE
• BEFORE_TIME
• BEFORE_DATE

Response

4.3 Foutmeldingen

Als een bepaalde matcher tot een fout leidt, wordt er een error teruggestuurd. Binnen deze error is de matcher gespecificeerd samen met de melding.

Error Expand source