Om data toe te kunnen voegen aan de Johan-kluis van de deelnemer, zodat deze ook vanuit het Johan-portaal inzichtelijk zijn, dienen een aantal zaken te worden geregeld:
- Datapunten toevoegen binnen Johan
- External Data product maken
- Token opvangen
- Gebruikers ID ophalen
- Lijst met dependencies en metingen ophalen
- Data terugsturen
- Workflow aanmaken (t.b.v. testen)
Op deze pagina staat uitgelegd wat er gedaan moet worden en welke API calls je hiervoor gebruikt. Op https://developers.johan.nl staat onze technische documentatie met voorbeelden van calls die je doet op onze API en de respons die je vervolgens terugkrijgt.
Datapunten toevoegen binnen Johan
Voordat je data kunt terugsturen naar Johan dienen deze datapunten wel te zijn toegevoegd aan jouw Johan omgeving om opgevangen te worden. Hiervoor zijn er twee entiteiten binnen Johan: dependencies/variabelen en metingen.
De dependencies/variabelen zijn de individuele datapunten die je terugstuurt naar Johan. Dit zijn bijvoorbeeld de scores op een construct, een PDF-bestand of een stuk tekst. De meting is de interpretatie van deze data en bepaalt hoe de data wordt weergeven in het Johan-portaal van de deelnemer. Hier voeg je bijvoorbeeld rapportteksten en normtabellen aan toe.
Meer uitleg over het aanmaken van dependencies en metingen vind je op deze supportsite.
Stuur je alleen een PDF-rapport terug? Dan gebruik je een dependency van type ‘File’. Als je een berekend resultaat als numerieke waarde terugstuurt, gebruik dan een Period-dependency.
External Data product aanmaken
Vanuit Johan klikken deelnemers op een knop om naar jouw applicatie te worden doorgestuurd. De link waarmee deelnemers worden doorgestuurd wordt aangevuld met een token. Dit token gebruik je vervolgens om de benodigde acties voor deze deelnemers uit te voeren.
De knop om deelnemers naar jouw applicatie door te sturen wordt gegenereerd binnen een product van type External Data. Dit is het product die de deelnemer in zijn Johan-dashboard ziet staan met informatie over jouw applicatie. Bij dit product staat ook de button die gebruikt wordt om de link naar jouw applicatie te genereren waarmee je het data token kunt ontvangen die je nodig hebt voor het plaatsen van resultaten in de Johan-kluis van de deelnemer. Het is mogelijk om deze link in de vorm van een QR-code te tonen, zodat deze bv. gescand kan worden op mobiel.
Het product aanmaken doe je als volgt:
- Log in bij jouw Johan-partneromgeving.
- Ga naar Content > Producten
- Klik op Add new product en kies voor de optie External data.
- Vul de volgende gegevens in.
- Name: de titel van het product zoals deze in de backend van Johan wordt getoond
- Label: de titel van het product zoals deze aan de deelnemer wordt getoond.
- Price: kun je op 0 instellen indien een deelnemer niet zelf hoeft te betalen.
- Short description: vul hier een korte beschrijving in van wat jouw applicatie is.
- Description: hier kun je meer informatie over jouw applicatie verschaffen.
- Button text: vul hier de tekst in die op de knop getoond moet worden om naar jouw app te gaan.
- Onderin heb je bij Options twee opties om de deelnemer door te linken:
- Redirect url: in dat geval wordt een deelnemer na het klikken op de knop in Johan doorgestuurd naar deze redirect url. De redirect url wordt aangevuld met het data token dat je kunt gebruiken om data terug te sturen naar Johan.
- QR code: je hebt ook de optie om de link als QR-code te tonen. Deze kun je vervolgens in jouw applicatie laten scannen om de link op te halen. Bij deze QR-code kun je verder een korte instructie plaatsen die deelnemers uitlegt welke stappen zij moeten ondernemen.
- Klik op Save om het product aan te maken.
Het product is nu aangemaakt en je landt op de Product Detail pagina. Hier moet je tenslotte aangegeven welke metingen je wilt kunnen invullen voor deze persoon. Hiervoor ga je naar de onderkant van de pagina en klik je op Add measure content. Selecteer vervolgens de metingen die je wilt invullen en klik nogmaals op Add measure content om deze metingen toe te voegen.
Dit product kan nu worden aangeboden aan de deelnemers via een workflow.
Token opvangen
Zodra een deelnemer op de knop bij het External Data product klikt wordt hij dus doorgestuurd naar de redirect URL, aangevuld met een external data token. Een link zou er dus als volgt uit kunnen zien: https://mijnapplicatie.nl/api/johan?token={EXTERNAL_DATA_TOKEN}. M.b.v. dit token heb je de mogelijkheid om diverse calls te doen op onze API en deze moet dus aan jouw kant worden opgevangen en opgeslagen.
Gebruiker ID controleren
De eerste stap die m.b.v. het token gedaan kan worden is het opvragen van het ID van deze gebruiker. Dit gaat via de ‘GET UUID’ call op onze API. Hiermee krijg je geen herleidbare gegevens over deze persoon binnen, puur het ID-nummer van deze gebruiker. Dit ID is uniek voor één specifieke gebruiker binnen Johan en kan dus gebruikt worden om te kijken of deze gebruiker zich eerder bij jullie heeft gemeld.
Heb je bij het External Data product aangevinkt dat je naast een uniek ID ook zaken als naam of e-mailadres wilt weten? Dan kun je deze opvragen via de GET Identity User call op onze API.
Is er al een gebruiker met dit ID bekend binnen jouw applicatie, dan kun je het external data token dat in de link is meegestuurd opslaan bij deze gebruiker. Is deze gebruiker nog niet bekend? Dan kun je een nieuwe gebruiker aanmaken of deze gebruiker doorsturen naar het registratieproces. Vervolgens kun je het external data token toevoegen aan het account dat is aangemaakt.
Lijst met dependencies ophalen
Uiteindelijk is de bedoeling dat je via ‘POST dependency results’ de data vanuit jouw applicatie doorstuurt naar Johan. Hiervoor heb je de ID’s nodig van de dependencies die je in de eerste stap hebt aangemaakt. Van de ‘GET depenendencies’ call op de API haal je de lijst van dependencies op die je kunt invoeren voor deze persoon. Daarbij staat tevens aangegeven om wat voor type dependency het gaat.
Data terugsturen
Nu je de ID-nummers hebt van de dependencies die je mag invullen voor deze persoon kun je op door jou gewenste momenten de data terugsturen naar Johan. Hiervoor gebruik je de ‘POST dependency results’ call op de API.
Bij deze API-call geef je het ID van de dependency op met de bijbehorende waarde die je mee wilt sturen. Op https://developers.johan.nl zie je een voorbeeld van deze API-call en staat per type dependency aangegeven in welk format de data doorgestuurd moet worden.
Nadat je alle data hebt teruggestuurd geef je ons een seintje dat alles is doorgestuurd door het product te updaten via de PUT Product status call op de API. Hiermee wijzig je de status van de vragenlijst naar ‘Completed’ en weten wij dat de vragenlijst volledig afgerond is en de deelnemer doorgestuurd kan worden naar de volgende stap.
Als alle bovenstaande stappen zijn ingebouwd is de koppeling gereed om getest te worden!
Workflow aanmaken
Om uiteindelijk gebruik te maken van de koppeling dient het External Data product te zijn opgenomen in een workflow. Indien je jouw koppelingsproduct beschikbaar wilt stellen aan andere partners kunnen zij zelf een workflow maken waar deze koppeling onderdeel van uitmaakt.
Om het geheel te kunnen testen is het makkelijkst om zelf een korte workflow in te richten met jouw External Data product, zodat je geheel een keer kunt doorlopen voordat hij in gebruik genomen wordt.
Heb je nog vragen over het inbouwen van jouw koppeling? Neem dan contact met ons op via consult@johan.nl.