Ons Tags: sjablonen aanmaken en tags toevoegen

Aandachtspunten bij opstellen sjabloon

Er is een aantal beperkingen in het gebruik van tags:

• De tags binnen een begin- en eindtag moeten onderdeel zijn van de meervoudige node.

• Tags kunnen niet in headers of footers worden opgenomen.

Let er bij het aanmaken van tags in een sjabloon op dat:

• er alleen bestaande tags worden opgenomen;

• de karaktercombinaties ${ of } alleen aan het begin en het eind van een tag worden gebruikt. Verder mogen tags alleen uit letters, cijfers, -, _ en / bestaan;

• er geen spaties tussen de accolades staan

  Word voegt bij copy/paste-acties soms automatisch spaties toe

Aandachtspunten Word-sjablonen

Let er bij het maken van Word-sjablonen op dat:

• er geen gebroken tags zijn. Een Word-document is feitelijk een gezipt .xml-bestand. Teksten worden vervat in text nodes, bijvoorbeeld:

  ${client/voorbeeldtag}

• het kan gebeuren dat Word additionele xml-informatie binnen de tag toevoegt. Dit ziet er zo uit:

  ${client/voorbeeldtag}

Je kunt de fout herkennen en de metadata zien door de tekst te selecteren en opmaak te verwijderen. Je lost het het makkelijkst op door de tag te verwijderen en opnieuw te typen. Je voorkomt het door in één keer tags te typen.

Aandachtspunten Excel-sjablonen

In Excel worden geneste herhalende tags op een andere manier verwerkt. Je kunt een lijst (van bijvoorbeeld cliënten) produceren door met een begin-/eindtag te werken:

Dit levert het volgende resultaat op:

Als bijvoorbeeld ook de adressen per cliënt opgenomen worden, dan zal Ons Tags deze in één cel achter elkaar opnemen. Daarbij worden alle in de adrestag gedefinieerde velden weergegeven.

Dit levert het volgende resultaat op:

Van elk adres worden alle velden (straat, huisnummer, postcode, plaats) opgenomen; meerdere adressen worden gescheiden met puntkomma.

Documentformaat

Bij het genereren van een document kan worden aangegeven of het resultaat een Word-document (.docx) of een PDF (.pdf) is.

Tag tree

De zijbalk aan de linkerkant van het tabblad Tags toont een lijst met alle Tag trees. Een Tag tree is een verzameling van samenhangende nodes die op een gestructureerde manier de ONS API uitvragen. Bovenaan staan de benodigde, niet-voorgedefinieerde parameters vermeld die ingevoerd moeten worden bij het uitvoeren van deze Tag Tree.

API nodes

API nodes zijn nodes waarin een API-call gedaan wordt. De APIs staan gedocumenteerd op ons-api.nl. Bij het maken van een nieuwe tag kan een API worden gekozen die wordt aangeroepen. Door het aanroepen van de API worden één of meerdere stukken data opgehaald uit het Ons-systeem. Bij het aanroepen van een API worden een of meerdere parameters meegegeven. Deze parameters zijn via de instellingen van de node in te stellen. Je kunt ze ook leeg laten. In dat geval moeten de parameters meegegeven worden op het moment dat de Tag tree wordt uitgevoerd.

Uit een API node kan een dataobject of een lijst worden teruggegeven.

Voor een API node kan ook een tag gespecificeerd worden. Deze is enkel nuttig als de API node een lijst teruggeeft. Deze tag kan dan gebruikt worden om aan te geven dat er over de lijst geïtereerd moet worden (zie ook Herhalende Tags hieronder).

Data node

Een Data node is een data-object dat uit een API call/API node komt.

Leaf node

Een Leaf node bevat een waarde (value) en is doorgaans datgene wat uiteindelijk als tag in een sjabloon gebruikt wordt. Een Leaf node heet zo, omdat deze als uiteinde/blaadje van een boom kan worden gezien.

De gegeven naam van de Leaf node kan als tag gebruikt worden in een sjabloon. De naam mag uit letters, cijfers, -, _ en / bestaan. Als bijvoorbeeld client/voornaam als naam wordt gekozen, dan kan in een sjabloon ${client/voornaam} als tag worden gebruikt om de voornaam van de cliënt in een document te verwerken.

De waarde van een Leaf node (bijv. een clientId) kan ook gebruikt worden als invoer voor een nieuwe API call.

Parameters

Methoden die via een API worden aangeroepen, hebben meestal parameters nodig om aangeroepen te worden. Deze parameters kunnen worden meegegeven wanneer er een document wordt gegenereerd van een sjabloon met de betreffende tags.

Er kan ook een vaste waarde voor een parameter worden ingericht, zodat de waarde vastligt en niet ingevuld hoeft te worden bij het genereren van het document. Bijzondere vaste waarden:

• vandaag: te gebruiken voor datum-/tijdparameters (de datum van de huidige dag wordt dan gebruikt)

• null: te gebruiken voor alle typen parameters (er wordt dan een lege/onbekende waarde meegegeven)

Afhankelijk van welke tags in een sjabloon zijn opgenomen, worden bepaalde API-aanroepen gedaan. Welke parameters benodigd zijn, wordt bepaald in de API-aanroep. Welke parameters nodig zijn voor een bepaald sjabloon, kan via het testscherm worden opgevraagd.

Behalve het specificeren van een parameter tijdens het aanroepen, kan een parameter ook worden gespecificeerd aan de hand van de waarde van een andere eindnode. Als de Cliënt API bijvoorbeeld wordt aangeroepen om een Cliënt op te zoeken aan de hand van zijn bsn, dan kan er een eindnode worden gemaakt die de ID van de Cliënt bevat. De waarde is van tevoren niet bekend, maar als deze bekend is, dan kan de ID worden gebruikt om andere APIs aan te roepen die een ID van een Cliënt als parameter nodig hebben.

Testen

Als een tag is ingericht, dan kan er worden proefgedraaid. Door middel van testen kan worden gecontroleerd of de nodes de goede naam hebben en of de data goed wordt opgehaald/verwerkt, zonder dat er daadwerkelijk een sjabloon ingericht hoeft te worden. Dit doe je door met je muis over het blokje van de Tag tree te gaan en op het symbool Uitvoeren te klikken. Er wordt een scherm weergegeven waarin de benodigde parameters ingevoerd kunnen worden.