In dit artikel leggen we uit voor een ontwikkelaar wat er momenteel mogelijk is om uw CRM-systeem te koppelen met Caseware Cloud. We geven hierin een aantal voorbeelden en een postman collectie om hier zelf mee te starten. We adviseren om Postman te gebruiken en de SDK als naslagwerk te gebruiken.
Tip: Abonneer op dit artikel om bij wijzigingen hiervan een melding te krijgen.
Inhoud:
Inleiding
Het CRM-systeem is leidend. Best practice is dat gebruikers dus geen rechten in Caseware Cloud mogen krijgen voor het aanmaken en aanpassen van Entiteiten, Contacten en eventueel medewerkers. Je kunt Caseware Cloud koppelen aan Azure Active Directory zodat medewerkers (en de mutaties hierop) automatisch worden gesynchroniseerd.
De volgende userstories zijn uit te voeren met de huidige versie van de API.
- Als een ontwikkelaar wil ik vanuit het (CRM) systeem van de opdrachtgever de entiteiten (bedrijven) uit het bronsysteem aanmaken in Caseware Cloud zodat gebruikers direct de juiste gegevens hebben bij het aan maken van nieuwe opdrachten.
- Als een ontwikkelaar wil ik bij een wijziging van de gegevens van een entiteit de mogelijkheid hebben deze wijziging ook in Caseware Cloud te verwerken zodat deze wijziging ook in de opdracht wordt verwerkt.
- Als een ontwikkelaar wil ik vanuit het (CRM) systeem van de opdrachtgever de contacten die horen bij de entiteiten uit het bronsysteem aanmaken in Caseware Cloud en koppelen aan de juiste entiteit zodat gebruikers direct de juiste gegevens hebben bij het aan maken van nieuwe opdrachten.
- Stap 1 is aanmaken van het contact
- Stap 2 is het toewijzen van een rol aan het contact voor de entiteit die je wilt koppelen.
Bekend issue:
- Het aanmaken en koppelen van contacten is een probleem. Je bent op dit moment niet in staat om te achterhalen welke entiteiten er gekoppeld zijn aan welke contacten en andersom.
Generen Sleutel
Stap 1 is het genereren van een API Key. Zie documentatie: Firm settings - Integration (caseware.com)
Meer informatie over de API en bijvoorbeeld het genereren van de API Key, zie dan ook onze Nederlandstalige releasenotes in Zendesk:
- Releasenotes Cloud 31.3 - Samenwerken – Caseware Nederland
- Releasenotes Cloud 32.0 - Samenwerken – Caseware Nederland
Naar de SDK voor toegang tot de API
Om de SDK te vinden moet u inloggen op de Cloud omgeving.
Ga naar https://nl.casewarecloud.com/<'cloudsite'>/sdk/
Hier vind je een korte Getting Started uitleg over hoe de SDK-omgeving werkt.
Klik op /caseware-cloud. Hier vind je de SDK-pagina.
Genereren token en Autoriseren
Via Postman
POST: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/auth/token
BODY:
{ "ClientId": "{{clientId}}",
"ClientSecret": "{{clientSecret}}",
"Language": "en"
}
Flow
- Opzoeken Entiteit
- Aanmaken Entiteit
- Wijzigen Entiteit
- Verwijderen Entiteit (Waarschuwing)
- Opzoeken Contact
- Aanmaken Contact
- Wijzigen Contact
- Verwijderen Contact
Entiteiten
Opzoeken Entiteit
Hoewel je op willekeurige velden een entiteit kunt opzoeken, is het advies om dit te doen via het klantnummer dat zowel bekend is in het CRM-systeem als ook in Caseware Cloud. Waar u rekening mee moet houden is dat het klantnummer van het type String is en dat u het klantnummer moet aanvullen met spaties tot een totaal van 10 posities.
Let op het gebruik van de single quote bij een String bij het opvragen. Een dubbele quote leidt tot een error 400 "Bad Request".
Aanmaken entiteit
Onderstaand voorbeeld maakt een entiteit aan met een beperkt aantal gegevens. Dit zijn de verplichte minimale set aan variabelen. De volledige set aan data die je mee kan geven vind je in het Schema*.
Via Postman
POST: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/auth/entities
BODY:
In Caseware Cloud krijgen Entiteiten een interne sleutel bij het opslaan van deze gegevens. Een klantnummer bij Entiteiten heeft geen directe relatie tot de interne sleutel die u nodig heeft bij het aanpassen en verwijderen van gegevens.
*Het Schema vind je terug onder het kopje responses
Wijzigen Entiteit (Update Entity details)
Om een entiteit te wijzigen heb je het EntityId nodig. Op dit moment verkrijg je dat door
a) Eerst te zoeken op het klantnummer zoals dat hierboven is uitgelegd
b) Het EntityId ophalen
c) Dit EntityId gebruiken om de update (Patch) uit te voeren
In de request body zijn dezelfde parameters verplicht als bij het aanmaken van een entiteit.
Verwijderen van Entiteit
Let op: Het verwijderen van de Entiteit gebeurd zonder controles. Er wordt dus bijvoorbeeld niet gekeken of contactpersonen, documenten, opdrachten aan de entiteit zijn gekoppeld.
Het verwijderen is definitief en de gekoppelde onderdelen zijn daarna niet meer zichtbaar/vindbaar.
Contacten en Medewerkers
Contacten en medewerkers zijn hetzelfde objecttype. Onderscheid wordt gemaakt door de waarde in de parameter Type.
Op dit moment kunt u wel contacten aanmaken, maar niet koppelen aan een entiteit via de API. Dit moet u handmatig doen. In de API is de functionaliteit om relaties te controleren tussen contacten en entiteiten nog niet aanwezig. Het is dus bijvoorbeeld niet mogelijk om via een entiteit te achterhalen welke contacten hierbij horen en vice versa.
Opzoeken User - Contact/Staff
Aanmaken User
Onderstaand voorbeeld maakt een User aan met een beperkt aantal gegevens. Dit zijn de verplichte minimale set aan variabelen. De volledige set aan data die je mee kan geven vind je in het Schema.
Via Postman
POST: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/users
BODY:
In Caseware Cloud krijgen Users een interne sleutel bij het opslaan van deze gegevens. Een klant / personeelsnummer bij Users heeft geen directe relatie tot de interne sleutel die u nodig heeft bij het aanpassen en verwijderen van gegevens.
Wijzigen User (Update User details)
Om een user te wijzigen heb je het UserId nodig. Op dit moment verkrijg je dat door
a) Eerst te zoeken op bijvoorbeeld klant / personeelsnummer met de parameter PeopleNo , of op naam
b) Het UserId ophalen
c) Deze UserId gebruiken om de update (Patch) uit te voeren
In de request body zijn dezelfde parameters verplicht als bij het aanmaken van een user.
Via Postman
PATCH: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/users/:userId
BODY:
Verwijderen van User
Let op: Het verwijderen van de user gebeurd zonder controles. Het verwijderen is definitief en de gekoppelde onderdelen zijn daarna niet meer zichtbaar/vindbaar.
Rollen
Opzoeken rollen
Met het opvragen van de rollen heeft u de mogelijkheid om, aan de hand van de gevonden id's bij de gebruiker, te zien welke rechten deze heeft (Algemene Cloud rollen en Working papers beveiliging). Deze informatie kan ook worden gebruikt bij het aanmaken van een nieuwe medewerker of contact.
Rollen toewijzen / wijzigen / verwijderen van groepen
Om een rol toe te wijzen, wijzigen of te verwijderen heb je de groupId nodig.
Het veld isRemove is een verplicht veld.
Daarnaast heeft u nog de optie om een objId toe te voegen ( bijvoorbeeld: EntityId, EngagementId ) en een objType ( Entity, WorkingPapersBundle, CustomBundle ).
Via Postman
PATCH: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/groups/:groupId/role-assignments
BODY:
Als de de patch succesvol is doorgevoerd is de status 200.
U zou er voor kunnen kiezen om in Postman een test te schrijven waarin deze status gecheckt wordt.
Onderstaand een voorbeeld van zo een test.
Rollen toewijzen / wijzigen / verwijderen van users
Om een rol toe te wijzen, wijzigen of te verwijderen heb je de userId nodig.
Het veld isRemove is een verplicht veld.
Daarnaast heeft u nog de optie om een objId toe te voegen ( bijvoorbeeld: EntityId, EngagementId ) en een objType ( Entity, WorkingPapersBundle, CustomBundle ).
Via Postman
PATCH: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/users/:userId/role-assignments
BODY:
Als de de patch succesvol is doorgevoerd is de status 200.
U zou er voor kunnen kiezen om in Postman een test te schrijven waarin deze status gecheckt wordt.
Onderstaand een voorbeeld van zo een test.
Groepen
Opzoeken groep
Als u niets invult krijgt u een overzicht van alle groepen.
Mocht u specifiek een groep willen opvragen dan kunt u dit onder andere doen door op naam te zoeken.
Ook is het mogelijk om op Id te zoeken. Bij dit overzicht ziet u ook meer details van de groep.
Aanmaken Groep
Onderstaand voorbeeld maakt een Groep aan met een beperkt aantal gegevens. Dit is de verplichte minimale set aan variabelen. De volledige set aan data die je mee kan geven vind je in het Schema.
Let op:
- Als u geen OwnerType aangeeft dan komt deze als default op Staff te staan.
- SecurityGroupNo: de maximale lengte is 10 karakters, hoofdlettergevoelig en uniek.
Via Postman
POST: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/groups
BODY:
Wijzigen groep (Update Group details)
Om een groep te wijzigen heb je de groupId nodig. Op dit moment verkrijg je dat door
a) Eerst te zoeken op bijvoorbeeld naam
b) GroupId ophalen
c) Deze groupId gebruiken om de update (Patch) uit te voeren
In de request body zijn dezelfde parameters verplicht als bij het aanmaken van een user.
Via Postman
PATCH: https://nl.casewarecloud.com/<firm>/ms/caseware-cloud/api/v1/groups/:groupId
BODY:
Verwijderen groep
Let op: Het verwijderen van de groep gebeurd zonder controles. Het verwijderen is definitief en de gekoppelde onderdelen zijn daarna niet meer zichtbaar/vindbaar.
Postman
Bijgevoegde voorbeelden van API requests via Postman.
Caseware Cloud API.postman_collection.json
Caseware Cloud.postman_environment.json