Handleiding Koppelvlak Stichting Opvoeden.nl 5.1 januari 2014

Handleiding koppelvlak
Stichting Opvoeden.nl
Versie 5.1
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Versie beheer
Versie
2.0
Datum
21 februari 2012
2.1
7 maart 2012
2.2
26 juni 2012
2.3
31 juli 2012
3.0
11 oktober 2012
4.0
17 juli 2013
4.1
20 december 2013
5.0
13 januari 2014
5.1
26 februari 2014
Door
Prisma IT
Vincent de Winter
Prisma IT
Jochem van Dieten
Prisma IT
Jochem van Dieten
Prisma IT
Jochem van Dieten
Prisma IT
Jochem van Dieten
Prisma IT
Ron Pasch
Prisma IT
Ron Pasch
Prisma IT
Ron Pasch
Prisma IT
Ron Pasch
Opmerkingen
Nieuwe initiële versie. Toevoegingen op aangepaste
procedure en vragen stellen inzake support.
Nadere toelichtingen op API datatypes, image URLs
en verwijdering documentatie van niet bestaande
functionaliteit.
Versie 2 van het koppelvlak toegelicht
Changelog toegevoegd
Versie 3 van het koppelvlak toegelicht
Canonical Tag instructies toegevoegd
Instructies toegevoegd mbt meldingen formulier op
externe websites
BrightCove video's beschrijving
Correctie op URL
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Inhoudsopgave
Versie beheer ...........................................................................................................................................2
Algemeen.................................................................................................................................................4
Vragen? ...................................................................................................................................................5
De inhoud ................................................................................................................................................6
Proces ......................................................................................................................................................7
De requests ..............................................................................................................................................7
Meldingen formulier op externe website ................................................................................................ 12
Appendix A Changelog............................................................................................................................ 13
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Algemeen
Stichting Opvoeden.nl biedt landelijk gevalideerde content aan op het gebied van opgroeien, opvoeden en
gezondheid. Door de combinatie van deze content wordt de betrouwbare informatie op een prettige en effectieve
manier toegankelijk voor ouders en opvoeders. Stichting Opvoeden.nl heeft de publieke verantwoordelijkheid
voor het onderdeel ‘content’. Dit document geeft u een toelichting op het gebruik en de mogelijkheden van het
koppelvlak dat wordt aangeboden om deze content te ontsluiten op uw eigen online CJG website.
Content
De landelijke database Opgroeien, Opvoeden en Gezondheid wordt via Stichting Opvoeden.nl gehost en kan door
een derde partij worden opgehaald via een koppelvlak (SOAP).
De content kan alleen in zijn geheel worden ontsloten en dus niet per artikel of een specifieke range van artikelen.
Gebruik
Aan het gebruik van het koppelvlak stelt Stichting Opvoeden.nl een aantal voorwaarden voor het gebruik.
Puntsgewijs:
 De workflow dient niet te worden veranderd;
 Content mag niet inhoudelijk worden veranderd;
 Content mag niet worden toegevoegd anders dan via Stichting Opvoeden.nl;
 Dagelijks dient te worden gecontroleerd of er een update beschikbaar is. Standaard wordt de content
één keer per maand bijgewerkt;
 Interne links en plaatjes worden op ID basis aangeleverd en dienen door de ontvangende partij te worden
aangepast naar de lokale verwijzingen;
 Daar de technische partij namens meerdere afnemers de content kan ophalen, dient bij elke update te
worden aangegeven namens welke afnemer(s) de content is opgehaald;
 Plaatjes dienen lokaal te worden opgeslagen. De Stichting Opvoeden.nl kan namelijk niet garanderen dat
de hosting van de multimedia elementen altijd beschikbaar is;
 Minimaal 1 keer per maand wordt verwacht dat de bezoekersaantallen per artikel, per week, per afnemer
worden bijgewerkt middels het koppelvlak;
 Zowel interne als externe links mogen niet geopend worden in een nieuw venster;
 De grafische opmaak is vrij, mits de bovenstaande punten in acht zijn genomen;
Toegang en beveiliging
De content uit de Opvoeden en Opgroeien database is alleen toegankelijk na opname van het IP-adres van de
server(website) waar de content op getoond zal worden. Bij aansluiting zal deze informatie worden gevraagd en
opgenomen worden in het koppelvlak.
U ontvangt een Gebruikersnaam van Stichting Opvoeden.nl, welke u nodig heeft bij het ophalen van de content.
De codes voor de betreffende afnemers, namens wie de content wordt opgehaald, kan middels het koppelvlak
worden opgevraagd. Per taalniveau (u-vorm of jij –vorm) heeft u een aparte gebruikersnaam nodig.
Werking Koppelvlak
Het koppelvlak is een SOAP koppeling en te bereiken op het volgende adres:
http://koppelvlak.stichtingopvoeden.nl/v5/koppelvlak.wsdl
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Vragen?
Mocht u als leverancier/implementatie partner na het lezen van deze handleiding nog aanvullende vragen en/of
ondersteuning nodig hebben dan kunt u contact opnemen met Stichting Opvoeden.nl.
Stichting Opvoeden.nl beschikt over een ICT servicedesk die als centraal meldpunt fungeert voor alle technische
vragen omtrent het gebruik van het koppelvlak. Het beheer van dit centraal meldpunt wordt uitgevoerd door onze
ICT leverancier Prisma IT.
Bereikbaarheid
De servicedesk is gevestigd in het kantoor van Prisma IT in Capelle a/d IJssel. Ze is zowel telefonisch als per e-mail
bereikbaar. Op reguliere werkdagen is de servicedesk bemand van 8:30 tot 17:00 uur.
Het aanmaken van een ticket
Vragen kunnen doorgegeven worden op de volgende manieren:
1. Door een email te sturen aan [email protected].
2. Door de vraag telefonisch aan te melden op nummer +31 10 458 7148
Zorgt u ervoor de volgende informatie bi de hand te hebben (telefonisch) of te vermelden (e-mail):
1. Gebruikersnaam
2. IP adres waarvandaan u het koppelvlak benaderd
3. Naam van de afnemer (indien van toepassing)
Responsetijden
Prisma IT streeft er naar om uw vraag binnen 8 (kantoor)uren te beantwoorden.
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
De inhoud
Weergave inhoud
De content die wordt aangeleverd is style neutraal en conform de webrichtlijnen. Alleen de volgende html tags
worden gebruikt:
<P>
zonder attributen
<em>, <strong>
zonder attributen
<h1>, < h2>, <h3>
zonder attributen
<a>
alleen href en name (target huidige pagina)
[a]
variable interne link
[img]
variabel plaatje
[bvid]
BrightCove Video
<br{spatie}/>
zonder attributen
<ol>
zonder attributen
<ul>
zonder attributen
<li>
zonder attributen
Menu indeling
Alleen het hoofdmenu staat vast en bevat de volgende leeftijdsfasen:
# Kinderwens
# Zwanger
# Baby
# Peuter
# Basisschoolkind
# Puber
# Jongvolwassene
Eigenschappen van het menu en artikelen






Het hoofdmenu bestaat uit 7 vaste artikelen. Dit aantal staat vast.
Per hoofdmenu artikel kan er maximaal 4 niveaus diep worden gegaan. Inclusief hoofdmenu bestaat de
menustructuur dus uit maximaal 5 niveaus. Er zit echter geen maximum aan het aantal submenu’s of
artikelen per niveau. In sommige gevallen kan dit oplopen tot 20 stuks!
Een titel van een menu (retrieveArticlesResponse.Article.shortTitle) bestaat uit maximaal 31 karakters.
De titel van een artikel/menu kan binnen een niveau maar 1 keer voorkomen.
Het artikelnummer (ExternalReference) verandert bij updates nooit, ongeacht wijzigingen aan de content.
De samenstelling van het menu kan wel bij elke update wijzigen.
Talen en taalniveaus
Mocht u namens meerdere afnemers handelen die verschillende niveaus hanteren, dan dient u een
gebruikersnaam per niveau te hebben. Een afnemer kan maar aan 1 gebruikersnaam gekoppeld zijn en dus maar 1
taalniveau hanteren. Op moment van schrijven zijn er 2 niveaus beschikbaar; de jij-vorm en de u-vorm.
Let op! De verschillende niveaus hebben geen afwijkende structuur en ook de artikelnummers zijn gelijk. Zo kent
het artikelnummer 10 (Kinderwens) een u-vorm en een jij-vorm. Houdt hier dus rekening mee bij het opslaan van
de artikelen.
Trefwoorden
Per artikel worden er maximaal 10 trefwoorden meegegeven.
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Proces
De volgende handelingen dienen te worden uitgevoerd:
 Dagelijks controle of er een update heeft plaats gevonden.
 Indien er een update is dient de gehele menustructuur, alle artikelen en bijbehorende plaatjes in zijn
geheel te worden opgehaald, met de vermelding namens welke contractant.
 Idem voor de FAQ artikelen.
 Verwerken content in de eigen omgeving.
 Minimaal 1 keer per maand de statistiek van de artikelen wegschrijven per afnemer, per artikel, per week.
De requests
De volgende request zijn mogelijk:
 lastReleaseDate
 retrieveArticles
 retrieveFAQs
 updateArticleStatistics
 retrieveConfiguredClientNames
lastReleaseDate
Hiermee kan gecontroleerd worden wanneer de content door Stichting Opvoeden.nl voor het laatst is vernieuwd.
Standaard zal er maandelijks een update plaats vinden, maar bij bijzondere landelijke ontwikkelingen kan dit vaker
zijn. Het is de ook de bedoeling dat elke 24 uur wordt gecontroleerd of er een update heeft plaats gevonden.
Request:
username
: Gebruikersnaam (String)
Response:
Date/time
: Datum en tijd (dateTime)
retrieveConfiguredClientNames
Bij het ophalen van de content moet aangegeven voor welke afnemer dit gedaan wordt. Via deze request kunnen
de namen van de afnemers worden opgehaald die nodig zijn.
Request:
username
: Gebruikersnaam (String)
Response:
Namen
: namen van de afnemers (ArrayOfString)
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
retrieveArticles
Met deze request kan gebruikt worden om alleen de menustructuur te ontsluiten, maar ook om alle artikelen op
te halen. De structuur van het menu zit in de opbouw van de response.
Request:
username
onbehalfOf
: Gebruikersnaam (String)
: Verzameling afnemer namen (ArrayOfString)
Response:
De structuur is zo plat mogelijk gehouden. De indeling van de xml is tevens de menu indeling.
In de basis zit de response er als volgt uit:
<article>
0001
<article>
0001.0001
<article>
0001.0001.0001
</article>
</article>
<article>
0001.0002
<article>
0001.0002.0001
</article >
<article>
0001.0002.0002
</article >
</article >
</article >
Voor een artikel is de opbouw als volgt:
-
Article
o
o
o
o
o
o
o
o
articletext (String)
articles (ArrayOfArticle)
shorttitle (String)
title (String)
lastChangeDate (dateTime)
externalReference (int)
tags (ArrayOfString)
canonicaltag (String)
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Uitleg velden:
Articles
Articletext
Shorttitle
Title
ExternalReference
Tags
lastChangeDate
Image
Canonicaltag
: Verzameling van artikelen die onder dit artikel vallen
: Tekst (body) van het artikel (zie toelichting verderop)
: Korte titel ten behoeve van het menu
: Titel van het artikel
: Artikelnummer
: Verzameling van tags (trefwoorden)
: Datum / tijd dat de artikeltext voor het laatst is geupdate
: Nog niet operationeel
: Dit is de canonical tag welke opgenomen moet worden in de <head> sectie.
Articletext
In 2 (en later 3) gevallen wordt er gebruik gemaakt van variabelen. Het betreft hier interne links, plaatjes en
video’s. De variabelen zijn:
Interne links
Dit zijn verwijzingen naar andere artikelen. Stel dat er interne link is naar een artikel met het ExternalReference
nummer 501, dan wordt dit in de tekst weergegeven als: [a = 501, voorbeeld]. Het is aan de ontvangende partij om
hier de juiste pagina aan te geven. De bijbehorende tekst maakt deel uit van de content. Bijvoorbeeld:
<a target=”_self” href=”http://www.mysite.nl/501.html”> voorbeeld</a>.
Plaatjes
Ook voor plaatjes wordt een variabele getoond, bijvoorbeeld [img=144]. Vanaf een vaste locatie vanaf de site van
Stichting Opvoeden.nl kunnen de plaatjes worden opgehaald. De locatie waar de plaatjes zich bevinden is:
http://koppelvlak.stichtingopvoeden.nl/<versienummer>/image?id=<ID>. Om het betreffende plaatje op te halen
dient de volgende url gebruikt te worden voor versie 2 van het koppelvlak:
http://koppelvlak.stichtingopvoeden.nl/v2/image?id=144
Om het betreffende plaatje op te halen dient de volgende url gebruikt te worden voor versie 3 van het koppelvlak:
http://koppelvlak.stichtingopvoeden.nl/v3/image?id=144
Afbeeldingen kunnen ook in een uitgebreider formaat worden aangeleverd, bijvoorbeeld [img=145,alt=”Een
beschrijving van de afbeelding.”]. In dit formaat wordt een extra beschrijving meegegeven die gebruikt kan
worden voor attributen als “alt” en “title”. De inhoud van de alt zal alleen tekens bevatten uit de verzameling
letters, cijfers, spatie, punt, komma, uitroepteken, vraagteken en minteken.
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
BrightCove Video
Een artikel kan een video bevatten welke relevant is voor de inhoud van het artikel. De video kan in tegenstelling
tot plaatjes wel gestreamd worden. Een video wordt als volgt weergegeven: [bvid=X] waarbij X een lang getal is.
Dit getal is de ID code van de video. Het is aan de ontvangende partij om [bvid=X] te vervangen met de HTML die
nodig is om de video af te kunnen spelen. Deze HTML is als volgt;

<div style="display:none"></div>
<script language="JavaScript" type="text/javascript"
src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>
<object id="OpvoedenVideo***BVID_ID***" class="BrightcoveExperience">
<param name="bgcolor" value="#FFFFFF" />
<param name="width" value="480" />
<param name="height" value="270" />
<param name="playerID" value="2377566964001" />
<param name="playerKey" value="AQ~~,AAACKW9LYjE~,S2dOrnGtegFdR8xOmOYyEMNa-s8Nqi9y" />
<param name="isVid" value="true" />
<param name="isUI" value="true" />
<param name="dynamicStreaming" value="true" />
<param name="@videoPlayer" value="***BVID_ID***" />
</object>
<script type="text/javascript">brightcove.createExperiences();</script>

In deze HTML moet de tekst ***BVID_ID*** vervangen worden door de video ID code uit [bvid=X] (waarbij X de
video ID code is)
Canonicaltag
Artikelen hebben een canonicaltag veld. Dit veld bevat de URL welke opgenomen moet worden in een <link>
tag. De canonicaltag wordt gebruikt om aan google’s indexeringsmechanisme een voorkeer in prioritering aan te
geven. Voor meer informatie zie https://support.google.com/webmasters/answer/139394?hl=en
De <link> tag moet er als volgt uitzien;
<link rel=”canonical” href=”” />
De waarde in de canonicaltag van het artikel moet vervolgens gebruikt worden in het href attribuut van de
<link> tag. Bijvoorbeeld; een canonicaltag waarde in het artikel van http://www.cjg.nl/kinderwens
zou dan de volgende <link> tag opleveren;
<link rel=”canonical” href=”http://www.cjg.nl/kinderwens” />
De link tag moet zich vervolgens bevinden binnen de <head> … </head> sectie van de pagina.
retrieveFAQs
De request werkt nagenoeg hetzelfde als retrieveArticles. Echter het FAQ onderdeel kent geen menu
structuur en per leeftijdsfase (hoofdmenu artikel) worden er maximaal 10 artikelen weergegeven.
Request:
username
onBehalfOf
: Gebruikersnaam (String)
: Verzameling afnemer namen (ArrayOfString)
Response:
Zie retrieveArticles
Onder elk hoofdmenu artikel hangen alle betreffende FAQ artikelen.
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
updateArticleStatistics
De request is bedoeld om de aantallen bezoekers per artikel per week per afnemer te registreren. Minimaal 1 keer
per maand dienen deze gegevens te zijn bijgewerkt in de database van Stichting Opvoeden.nl. Mocht er voor een
reeds ingevoerde week nog een keer statistiek worden doorgegeven, dan worden de bestaande gegevens
overschreven en dus niet toegevoegd. Realtime turven is hierdoor niet mogelijk.
Request:
username
year
week
statistics
: Gebruikersnaam (String)
: Jaar (jjjj) (Integer)
: betreffende weeknummer (weeknummer berekend conform ISO/NEN 8601) (Integer)
: gegevens (ArrayOfArticleStatitics)
ArticleStatistics
articleId
numberOfVisitors
onBehalfOf
: artikelnummer (externalReference) (Integer)
: aantal unieke bezoekers (Integer)
: betreffende contractant (=website/gemeente) (String)
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Meldingen formulier op externe website
Het “externe melding” formulier is beschikbaar voor externe websites welke content van Stichting Opvoeden
ontsluiten. Het formulier is te koppelen aan een eigen HTML element naar keuze. Dit kan een link zijn of een
button of iets anders. Daarin is de externe website vrij.
Om het formulier toe te voegen dient de volgende script tag in de <head> sectie aanwezig te zijn:
<script id="cjgExterneMelding" src="http://www.cjg.nl/assets/js/melding.cfm"
data-selector=”” data-externalreference=""></script>
Het is belangrijk dat de ID attribuut onveranderd blijft. De twee andere attributen moeten gevuld worden.
Data-externalreference attribuut
Deze attribuut moet gevuld worden met de externalReference waarde van het artikel dat op dat moment op de
externe site getoond wordt.
Data-selector attribuut
Deze attribuut moet gevuld worden met een jQuery selector die één of meerdere elementen binnen de externe
site matched. Hieronder een voorbeeld:
Stel dat de externe site een <a> tag wilt gebruiken als trigger voor het externe melding formulier en de <a> tag
heeft een class attribuut van “externeMelding”, dan zou dit er zo uitzien:
<a class=”externeMelding” href=”…..”>Feedback geven op dit artikel </a>
De waarde voor de data-selector attribuut van het script zou dan moeten zijn “.externeMelding”.
Ander voorbeeld: De externe site heeft een <button> met een id attribuut van “feedbackForm”.
<button id=”feedbackForm”>Geef feedback</button>
De waarde voor de data-selector attribuut van het script zou in dat geval “#feedbackForm” moeten zijn.
Er kunnen ook meerdere elementen gematched worden. Stel dat de externe site bijvoorbeeld meerdere <a
class=”externeMelding”> elementen op de pagina heeft staan, dan zullen al deze anchor tags een trigger
worden als de jQuery selector waarde van “.externeMelding” gebruikt wordt als waarde voor de dataselector attribuut van het script.
Voor meer uitleg over jQuery selectors, zie http://api.jquery.com/category/selectors/
De meest gebruikte jQuery selectors zijn Class Selectors (.externeMelding) en ID Selectors
(#feedbackForm)
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl
Appendix A Changelog
v5.1
Kleine correctie op URL van koppelvlak
v5.0
Beschrijving toegevoegd hoe om te gaan met BrightCove video’s in artikelen.
v4.1
Instructies toegevoegd hoe op externe websites het meldingen formulier geïmplementeerd kan worden.
v4.0
Beschrijving toegevoegd hoe canonicaltags geïmplementeerd moeten worden.
v3
Nieuwe features
De afbeelding gebruikt in het keurmerk is voorzien van een “alt”-text voor gebruik als title en alt van de afbeelding.
Afbeeldingen hebben een stabiele URL gekregen: ze worden niet meer overschreven en als u een afbeelding al
heeft gedownload hoeft u de afbeelding niet opnieuw meer te downloaden.
Artikelen (en FAQs) hebben een lastChangeDate gekregen van de laatste datum dat ze gewijzigd zijn.
Bugfixes
Datatypes die door het koppelvlak terug gegeven worden zijn aangepast voor:
article -> externalReference is een int geworden
lastReleaseDate is een dateTime geworden
In de aanroepen naar het koppelvlak zijn een alle parameters als verplicht gemarkeerd. Ze zijn (en waren) allemaal
al nodig voor correcte verwerken, maar waren nog niet als zodanig aangemerkt.
Upgrade instructies
Pas de URL van het koppelvlak aan naar http://koppelvlak.stichtingopvoeden.nl/v3/koppelvlak.wsdl
Pas de URL van de plaatjes aan naar http://koppelvlak.stichtingopvoeden.nl/v3/image?id=<id>
Pas de datatypes aan, hercompileer en hertest uw applicatie.
v2
Nieuwe features
De content van artikelen en FAQs opgehaald via het koppelvlak bevat een extra paragraaf met het keurmerk.
Upgrade instructies
Pas de URL van het koppelvlak aan naar http://koppelvlak.stichtingopvoeden.nl/v2/koppelvlak.wsdl
Pas de URL van de plaatjes aan naar http://koppelvlak.stichtingopvoeden.nl/v2/image?id=<id>
v1
Initiële versie.
Koppelvlak Stichting Opvoeden.nl – Versie 5.1 – Jan ‘14
Postbus 27050 | 3003 LB Rotterdam | T 088-118 02 00 | E [email protected] | www.stichtingopvoeden.nl