Ons Tags: instructiehandleiding

Autorisatie

${client/hoofdadres}

De tag ${client/hoofdadres} maakt gebruik van de API AddressAPI.mainAddressByClientId. Hierbij wordt het hoofdadres voor de cliënt opgehaald op basis van de volgende rangschikking:

Deze volgorde is anders dan de oude rangschikking van Ons Administratie voor de tag [client/adres].

${client/adressen/bijType}

De tag ${client/adressen/bijType} maakt gebruik van de API AddressAPI.byClientId en filtert daarbij op enkel actuele adressen (zonder einddatum).

Het is mogelijk om in het gebruik van de tag een type mee te geven, bijvoorbeeld ${client/adressen/bijType[type=1]:straat}. Hierbij wordt voor een client een actueel adres gezocht van het type GBA (zie hieronder). Daarbij pakt de tag met : het eerste resultaat en wordt de straatnaam geprint.

Adres met aangepaste rangschikking

Het is mogelijk om een adres op te halen volgens een zelf opgegeven rangschikking. Gebruik daarvoor het filter eerste match. Bij dit filter geef je een aantal zoektermen op gescheiden door komma's. Ons Tags geeft vervolgens het adres terug dat voldoet aan de eerste gevonden zoekterm.

Voorbeeld

Stel je wilt het eerste adres zoeken dat een sleuteladres is. Als dat er niet is, wil je het eerste adres dat een GBA-adres is. Als dat er niet is, het eerste overige adres; enzovoorts. In dit voorbeeld is de rangschikking:

Type adres

Sleutel adres

GBA-adres

Overig adres

Het is hierbij belangrijk te onthouden wat je als filter kunt gebruiken:

Type adres	Te gebruiken filter
Onbekend	Unknown
GBA	Living
Correspondentie	Postal
Verblijf	Residence
Tijdelijk	Temporary
Sleutel	Key
Overig	Other
Factuur	Invoice

Je gaat dan als volgt te werk:

1. Maak een kopie van de tag ${client/adressen/bijType}.

2. Hernoem de tagCollectie en bovenste tagNode, bijvoorbeeld naar client/adressen/sleutel}.

3. Maak een filter op de lijstnode.

4. Bij Selecteer een node kies je getTypeString.

5. Bij Selecteer een filter kies je eerste match.

6. Bij waarde typ je de rangschikking: key,living,other.

7. Sla het filter op.

8. Zet de parameter type op vaste waarde null (je wilt immers zoeken in alle typen).

De lijstnode ziet er als volgt uit als je de bovenstaande stappen hebt uitgevoerd:

Bij het uitvoeren van de tag:

• van voorbeeldcliënt Jansen met een sleutel- en een GBA-adres, geeft deze tag nu het sleuteladres terug.

• van voorbeeldcliënt De Vries met een GBA- en overig adres, geeft de tag het GBA-adres terug.

• van een voorbeeldcliënt met alleen een verblijfadres, wordt geen adres teruggegeven. Wil je in dit laatste geval toch het eerste overgebleven adres terugkrijgen, dan gebruik je key,living,other,, (met twee kommas achteraan) als filterwaarde.

  Met dit filter krijg je een lijst met adressen terug, weliswaar met maar één adres erin. In een template kun je de notatie voor geaggregeerde tags gebruiken, bijvoorbeeld ${_client/adressen/sleutel:_volledig} voor het volledige adres.

Stap 1: Test de tagcollectie in Ons Tags

• Zijn er blokjes geel/rood?

  • Als een blokje geel is met de melding Er zijn geen parameters ingevuld met een 'parent waarde'. Deze API node kan niet correct worden gebruikt., dan moet een van de parameters de waarde parent waarde te krijgen.

  • Als een blokje rood is, dan verwijst het naar een API die niet meer bestaat.

  • Als een blokje geel is met de melding dat de API node als deprecated gemarkeerd is, dan kan die vooralsnog gebruikt worden, maar zal die in de toekomst komen te vervallen.

    • Kloppen de benodigde parameters voor het uitvoeren?

    • Komt de juiste data terug? Zo niet:

      • Klopt het clientId? Dit moet het id uit de URL zijn als je in Ons Administratie naar de cliënt toe gaat.

      • Zit er een typfout of ontbrekende spaties in een van de parameters?

Stap 2: Test het sjabloon in Ons Tags

• Controleer of de parameters voor het uitvoeren correct zijn (doorgaans zou hier enkel een clientId en optioneel een locationId moeten staan). Wijkt dit af, dan is er iets mis met de taginrichting (stap 1) of ontbreekt het meegeven van een parameter in een gebruikte tag in het sjabloon.

• Als je een foutmelding krijgt bij het uitvoeren, controleer of je de benodigde rechten hebt voor het uitvoeren van dit sjabloon en of de cliënt/medewerker in je bereik zit.

• Het kan zijn dat een tag incorrect is of niet meer bestaat. Probeer het sjabloon opnieuw te uploaden om te kijken of die door de validatie komt.

Stap 3: Test het sjabloon via Ons Administratie

Als het sjabloon niet wordt weergegeven, kan dit komen door:

• Je hebt niet de juiste rechten. Je hebt een van de rechten met Genereer documenten met [...] in Ons Tags nodig.

• De parameters benodigd voor het uitvoeren komen niet overeen met wat Ons Administratie verwacht. Bij het kopje Brieven versturen wordt minimaal een clientId en optioneel een locationId verwacht. Dit geldt ook voor het genereren van een Ons Tags Rapportage bij een cliënt.

Als het document niet gegenereerd wordt of er een foutmelding wordt weergegeven:

• Zorg dat enkel de informatie meegestuurd wordt die benodigd is voor documentgeneratie: een cliënt als een clientID nodig is voor de uitvoer van het sjabloon, een locatie als een locationID nodig is voor de uitvoer van het sjabloon, enz.

• Test het sjabloon in de Ons Tags-omgeving voor dezelfde cliënt. Doe vervolgens hetzelfde voor de gebruikte tagcollecties om er achter te komen waar potentieel een fout ontstaat.

Als het document gedownload wordt en niet bij de cliëntdocumenten terechtkomt:

• Probeer de opgegeven cliënt te verwijderen en opnieuw te selecteren in de selectiebox bij briefgeneratie.

Waarom krijg ik een foutmelding bij het uploaden van mijn sjabloon (.docx)?

Ons Tags controleert tijdens het uploaden of de tags in het sjabloon overeenkomen met de ingerichte tags. Ons Tags doet een poging te bepalen welke tag incorrect is en vermeldt dit in de foutmelding.

Een paar vaak voorkomende oorzaken:

• Typfouten

• Xml-elementen: Microsoft Word voegt soms onder water xml-elementen binnen stukken tekst toe, bijvoorbeeld bij het kopiëren/plakken. Dit is helaas niet te zien op het scherm. Dit is op te lossen door tekst in Word te selecteren en op Opmaak wissen (A met een gum) in Word te klikken.

• Bestandsformaten: Zorg dat het bestandsformaat .docx is en het bestand niet in compatibiliteitsmodus is opgeslagen.

• Header/footer: Het komt soms voor dat er problemen ontstaan bij tags in de header/footer. Controleer of het verwijderen van de header/footer het probleem op lost.

• Lijsttags: Zorg er in Word voor dat een lijsttag in een tabel staat en een openings- en sluitingstag heeft. Een geneste lijsttag moet in een geneste tabel in Word staan.

Waarom zie ik het sjabloon niet terug in Ons Administratie/Ons DBC?

Een sjabloon wordt enkel getoond als:

• Ons Tags is geactiveerd op de omgeving. Die activatie bestaat uit twee stappen die door Support uitgevoerd moeten worden:

  • Ons Tags-beheer moet worden geactiveerd voor de omgeving (de webapplicatie)

  • Het vinkje Cliënt-documenten genereren met Ons Tags aanzetten moet in Ons Administratie worden ingeschakeld.

• je de juiste rechten hebt voor het sjabloon (zie hoofdstuk Autorisatie hierboven)

• de cliënt in jouw bereik zit

• het sjabloon de correcte parameters heeft die nodig zijn voor het uitvoeren ervan

• het sjabloon geen fouten bevat.

  Dit kun je testen door het sjabloon opnieuw te uploaden.

Door in Ons Tags het sjabloon uit te voeren, zie je snel welke parameters nodig zijn voor het uitvoeren van het sjabloon. De benodigde parameters zijn een samenstelling van parameters om elke tag binnen het sjabloon uit te kunnen voeren. Op de pagina van de tagcollectie is te zien welke parameters nodig zijn voor de geselecteerde tagcollectie.

• Ons Administratie toont enkel sjablonen die een clientId (vereist) en/of een locationId (optioneel) nodig hebben.

• Ons DBC toont enkel sjablonen die een occurenceId (vereist) en/of een clientId (optioneel) nodig hebben. Sjablonen die aanvullende parameters nodig hebben (zoals startDate), worden niet weergegeven. We raden aan om tijdens het opbouwen van het sjabloon tussendoor te testen. De voorgestelde volgorde tijdens het maken van sjablonen is als volgt:

  • Tagcollectie (bij aangepaste tags)

  • Sjabloon in Ons Tags

  • Sjabloon via Ons Administratie

Het kan voorkomen dat als je het sjabloon uploadt, deze succesvol gevalideerd is maar de tags naderhand niet meer correct zijn door een gewijzigde taginrichting. In dit geval kun je dat testen door het bestand (.docx/.xlsx) opnieuw te uploaden om het opnieuw te valideren.

Waarom worden bepaalde tags niet ingevuld bij genereren van een document/brief?

Indien bij het genereren van een document sommige tags wel worden ingevoerd, maar andere niet, kan dit meerdere oorzaken hebben. Probeer eerst de tag collectie te testen (via Ons Tags) om te kijken of het als misgaat bij het ophalen van de informatie uit de APIs, of dat het mis gaat bij briefgeneratie.

• De informatie komt niet mee vanuit de API's.

  • Zie Waarom wordt een bepaald veld niet gevuld bij het uitvoeren van een tagcollectie? hieronder.

     

• Er gaat iets mis tijdens het genereren van de brief bij het invullen van de informatie bij de tag.

  • De tag bestaat niet of bevat een spelfout.

  • De tag ziet er visueel goed uit, maar het Word-bestand bevat verborgen tekens binnenin de tag. Word heeft zonder dat je het door hebt xml-data in de tag geplaatst. Dit kun je oplossen door de tekst te selecteren en opmaak te verwijderen. Verwijder en typ de tag opnieuw in het Word-sjabloon. Wees vooral voorzichtig bij het kopiëren/plakken als er opmaak mee komt of er regelafbrekingen ontstaan.

Waarom wordt een bepaald veld niet gevuld bij het uitvoeren van een tagcollectie?

Hoe filter ik op meerdere niveaus?

Het is niet mogelijk om op meerdere niveaus diep te filteren. Dit betekent dat enkel binnen API-nodes op direct onderliggende velden gefilterd kan worden. Als onder een API-node eerst een grijs blokje en dan een blauw blokje ligt, is het niet mogelijk om op de waarde uit het blauwe (of grijze) blokje te filteren.

Hoe gebruik ik geneste lijsten?

Bij lijsten in lijsten moet je in Word een tabel binnen een tabel maken. Bij de instellingen van API-calls staat of er een object, waarde of een lijst wordt opgehaald.

Hoe haal ik de huisarts van een cliënt op?

Gebruik de tag ${client/contacten/bijType[type=huisarts]}. Deze geeft een lijst met alle contactpersonen van het type huisarts van de client terug.

Hoe haal ik het type van een externe zorgleverancier (bijvoorbeeld huisartsen) op?

1. Haal een externe zorgleverancier op (bijvoorbeeld CareProviderAPI.byClientId).

2. Pak hieruit de getOrganisationCategoryId.

3. Start een nieuwe API-call OrganisationCategoryAPI.byId en geef de getOrganisationCategoryId mee als bovenliggende waarde.

4. Maak een tag van de getName.

Waarom is het veld ID niet automatisch gekoppeld bij een node op basis van een cliënt-ID?

Bij het instellen van een node met daarin een nieuwe API-call op basis van opgehaalde informatie (zoals een ID), wordt dit niet automatisch voor je gekoppeld. Bij een node die op basis van een cliënt-ID het client*object opvraagt via de ClientAPI.byId, kan het voorkomen dat het veld Id niet automatisch gekoppeld wordt met het hiervoor verkregen cliënt-ID. Dit kun je oplossen door het veld id/client id op Parent Value in te stellen.

Hoe filter ik op datum?

Als bij een API een startdatum/einddatum als parameter meegegeven kan worden, dan kan een vaste datum (bijvoorbeeld 2023-01-25) worden opgegeven of een relatieve datum (bijvoorbeeld vandaag - 7 dagen).

Een voorbeeld van zo'n API is de AgendaOccurrence.byClientId die alle agenda-afspraken in een periode opzoekt:

Als een API geen startdatum/einddatum als parameter accepteert is het alsnog mogelijk achteraf (na het ophalen van alle data) te filteren. Het nadeel is dat er meer data opgehaald wordt uit de API dan strikt noodzakelijk is. Als je wilt filteren op afspraken die al zijn afgelopen, kan je filteren op een einddatum kleiner dan vandaag:

Einddatums zijn in het algemeen inclusief (dus een einddatum van 2023-01-01 betekent tot en met 1 januari).

Filteren op 'actieve' data:.

www.ons-api.nl

Zie www.ons-api.nl voor aanvullende documentatie over de API's die je via Ons Tags aanroept.

Testuitvoer van een tag tree

Het is mogelijk om in de ontwerppagina een testuitvoer te doen om te zien welke informatie wordt opgehaald voor elke tag. Beweeg met je muis over de bovenste node en klik op het uitvoericoontje.

'Berekende' parameterwaarden

Bij het opgeven van een vaste waarde voor een parameter van een API-node kun je een berekende waarde in het tekstvak invoeren.

Manipulatie t.o.v. 'vandaag'

• Vandaag

• Vandaag -1 dag

• Vandaag + 2 weken

Toegestaan: dagen, weken, jaren. Bij het uitvoeren van het sjabloon wordt de waarde berekend.

Lijsten

In het scherm met extra informatie over nodes zie je of er een object, waarde of een lijst wordt opgehaald. Als een lijst wordt teruggegeven, dan moeten de tags van nodes eronder binnen tags van die lijst staan. Zie het voorbeeld in het kopje hieronder.

Beknopte tags en naamgeving

De namen van tags moeten uniek zijn binnen de gehele omgeving. Als er echter een node met een tag onder een node hangt die een lijst teruggeeft, hoeft die tag enkel uniek binnen deze lijst te zijn.

In het overzicht van tags hieronder gaan we uit van een inrichting met een node met de tag medewerkerRelatiesVanClient die een lijst met medewerkerrelaties ophaalt op basis van een cliënt-ID.

• ${client/voornaam}

• ${client/achternaam}

• ${medewerkerRelatiesVanClient}

  • ${voornaam}

  • ${achternaam}

• ${medewerkerRelatiesVanClient}