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
relatiegegevens
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/. Gegevens naar Cloudplan sturen kunt u doen mbv een 'Push' en ophalen met een 'Get'. Hiervoor dient u wel een authenticatietoken mee te sturen. Deze kunt u opvragen in de authenticatie webservice mbv uw gebruikersnaam en wachtwoord.

2. Voorbeeld

Om het voorbeeld uit te kunnen voeren heeft u een gebruikersnaam & wachtwoord nodig voor de webservice. Neem hiervoor contact op met Planning.nl

Klik hieronder om het voorbeeld, geschreven in powershell, te downloaden en te bekijken.

In de voorbeelden kunt u zien hoe:

de authenticatie werkt en hoe u een authenticatietoken ophaalt
alle resources uit Cloudplan ophaalt
een nieuwe resource toevoegt
gegevens van een bestaande resource wijzigt

3. SoapUI

Op de overzichtspagina is ook een link naar de WSDL te vinden die u nodig heeft als u 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

4. Structuur

4.1 Requests (informatie opvragen)

De request voor het opvragen van informatie bestaat uit de authenticatie token en één of meerdere matchers.

4.2 Matchers

Elke matcher heeft een attribuut allowMultiple. 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.

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

4.4 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

5. Foutafhandeling

Als de server niet bereikbaar is of als deze de opgestuurde informatie niet kan verwerken, kunt u verschillende antwoorden verwachten.

Een socket timeout als de webserver om welke reden dan ook niet reageert
Een HTTP 404 error (Page not found), als de webservice bv tijdelijk offline is voor onderhoud
Een HTTP 500 error (Internal Server Error). Dit kan voorkomen als er op de server een fout optreedt bij het verwerken van de opgestuurde gegevens.

Soap faults (bijvoorbeeld als er syntax fouten zitten in de opgestuurde XML):

Soap fault: unmarshalling error

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<soap:Fault>
			<faultcode>soap:Client</faultcode>
			<faultstring>Unmarshalling Error: Unexpected close tag &lt;/usernaem>; expected &lt;/username>.
 at [row,col {unknown-source}]: [6,35]</faultstring>
		</soap:Fault>
	</soap:Body>
</soap:Envelope>

<error> blok in de response, bijvoorbeeld als de authenticatie token verlopen

<error> not authenticated

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:getResourcesResponse xmlns:ns2="https://api.cloudplan.nl/">
			<return>
				<authenticationTokenExpiration>0</authenticationTokenExpiration>
				<error>
					<message>The current session is not authenticated</message>
				</error>
			</return>
		</ns2:getResourcesResponse>
	</soap:Body>
</soap:Envelope>

of als een loginpoging is mislukt

<Error> Authentication failed

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:loginResponse xmlns:ns2="https://api.cloudplan.nl/">
			<return>
				<authenticationTokenExpiration>0</authenticationTokenExpiration>
				<error>AUTHENTICATION_FAILED</error>
				<accountLocked_RemainingTimeout>0</accountLocked_RemainingTimeout>
			</return>
		</ns2:loginResponse>
	</soap:Body>
</soap:Envelope>

Of als het toevoegen van gegevens mislukt, bijvoorbeeld als je niet genoeg gegevens aanlevert voor bij het opslaan (Push) van een resource.

<Error> Validation failed

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ns2:pushResourcesResponse xmlns:ns2="https://api.cloudplan.nl/">
			<return>
				<authenticationTokenExpiration>0</authenticationTokenExpiration>
				<MatcherResults>
					<MatcherResult>
						<matcher xsi:type="ns2:resourceMatcher" allowMultiple="false" validationPolicy="SKIP" select="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
							<number>9999</number>
						</matcher>
						<InsertedIds/>
						<UpdatedIds/>
						<Errors>
							<Error entityId="0">Name is empty!</Error>
						</Errors>
					</MatcherResult>
				</MatcherResults>
			</return>
		</ns2:pushResourcesResponse>
	</soap:Body>
</soap:Envelope>

Algemene informatie