Types van externe gegevens
Als je Yesplan integreert met een ticketingsysteem kan je gegevens uit je ticketingsysteem tonen in Yesplan via een customdataveld van het type “Externe gegevens”:
- Vóór Yesplan 28 was de inhoud van zo’n veld altijd “Tekst (één regel)”, zelfs als het veld eigenlijk een getal bevatte. Daardoor kon je de inhoud niet makkelijk gebruiken voor berekeningen als je het bijvoorbeeld exporteerde naar een Excel-bestand.
- Sinds Yesplan 28 kan je expliciet aangeven dat het gegevenstype van zo’n veld “Getal” moet zijn. Dan kan je er ook makkelijker berekeningen op uitvoeren.
Opmerking
Voor de overgangsperiode hebben we een instelling toegevoegd waarmee je externe gegevens van het gegevenstype “Getal” in de API toch nog terugkrijgt als “Tekst (één regel)”, zodat bestaande integraties niet in de problemen komen. Je kan deze instelling in- en uitschakelen in “Systeeminstellingen” > “Systeemvoorkeuren” > “Verouderde functionaliteit”. Zie Verouderde functionaliteit voor meer informatie.
Deze gids beschrijft welke stappen je moet zetten om vlot de nieuwe gegevenstypes te gebruiken.
Geen integratie§
Als je momenteel geen integratie gebruikt met een ticketingsysteem, dan kan je meteen overschakelen naar het gegevenstype “Getal”:
- Ga naar “Systeeminstellingen” > “Systeemvoorkeuren” > “Verouderde functionaliteit”.
- Selecteer “Nee” in de keuzelijst naast “Waarde van ‘Externe gegevens’-velden van het type ‘Getal’ wordt als tekenreeks (‘string’) verstuurd in REST API.”
Je moet verder niets doen.
Nieuwe integratie§
Maak je een nieuwe integratie aan met een ticketingsysteem? Dan kan je meteen het gegevenstype “Getal” gebruiken:
- Gebruik het juiste gegevenstype als je customdatavelden aanmaakt van het type “Externe gegevens” (bijv. “Getal” voor getallen, “Datum” voor datums enz.). Zie Externe gegevens voor meer informatie.
- Ga naar “Systeeminstellingen” > “Systeemvoorkeuren” > “Verouderde functionaliteit”.
- Selecteer “Nee” in de keuzelijst naast “Waarde van ‘Externe gegevens’-velden van het type ‘Getal’ wordt als tekenreeks (‘string’) verstuurd in REST API.”
De velden zullen altijd opgeslagen worden in het correcte gegevenstype en zullen ook zo doorgestuurd worden via de API.
Bestaande integratie§
Als je een bestaande integratie hebt met een ticketingsysteem, dan is de kans groot dat je customdatavelden van het type “Externe gegevens” gebruikt, en dat het type van deze velden “Tekst (één regel)” is, ook al bevatten ze een getal. We raden daarom aan om de stappen hieronder te volgen en deze velden om te zetten naar het gegevenstype “Getal” waar nodig.
Maak een lijst§
Maak eerst een lijst van velden van het type “Externe gegevens” die een getal bevatten en hun corresponderende velden in het ticketingsysteem:
- Voor Yesplan gebruik je best het keyword, bijv. ‘ticketing_extern_aantal_verkocht’.
- Gebruik voor het veld in het ticketingsysteem de technische naam.
Je vindt deze informatie op de configuratiepagina van je integratie in “Systeeminstellingen” > “Integraties”.
Vraag de conversie aan§
Eens je zeker weet dat je ticketingsysteem waarden als getal kan versturen, kan je aan Yesplan vragen om de velden om te zetten. Dat kan met een e-mail naar support@yesplan.be.
Vraag aan Yesplan om de bestaande velden om te zetten naar het gegevenstype “Getal”:
- Velden met getallen zullen het juiste gegevenstype krijgen: “Getal”.
- Je moet de configuratie van je integratie niet aanpassen.
- We zullen nagaan of de velden gebruikt worden in rapporten en ze aanpassen indien nodig.
Let op
We zullen enkel de velden omzetten die effectief gekoppeld zijn in de integratie op het moment van de conversie:
- Velden voor externe gegevens die niet gekoppeld zijn bij de conversie worden niet omgezet en behouden het gegevenstype “Tekst (één regel)”. Als je deze na de conversie koppelt, zullen ze het foute gegevenstype hebben.
- We raden daarom aan om na de conversie telkens een nieuw customdataveld aan te maken als je bijkomende externe gegegevens wilt weergeven in Yesplan. Die kan je immers het juiste gegevenstype toewijzen.
Controleer je integratie§
De database van Yesplan bevat nu waarden van het gegevenstype “Getal” voor de velden in kwestie. Via de API worden deze waarden echter nog weergegeven als een JSON string en dat moet je nog aanpassen.
Ga na welke integraties gebruik maken van de velden in kwestie:
- Dit gaat over je ticketingintegraties, maar ook andere integraties kunnen deze velden gebruiken (bijv. voor data-analyse, de website enz.).
- Vraag aan de ontwikkelaars van deze integraties om te testen of ze waarden kunnen doorsturen/ontvangen als gegevenstype “Getal”. De sectie Voor ontwikkelaars hieronder vertelt precies hoe ze dit na kunnen gaan.
- Ga pas naar de volgende stap als je zeker weet dat je integraties de nieuwe gegevenstypes ondersteunen.
Schakel over§
Eens je zeker weet dat alle integraties compatibel zijn met het gegevenstype “Getal”, moet je ervoor zorgen dat de API waarden ook in dit formaat verstuurt:
- Ga naar “Systeeminstellingen” > “Systeemvoorkeuren” > “Verouderde functionaliteit”.
- Selecteer “Nee” in de keuzelijst naast “Waarde van ‘Externe gegevens’-velden van het type ‘Getal’ wordt als tekenreeks (‘string’) verstuurd in REST API.”
Eens je dat gedaan hebt, bevat Yesplan waarden van het type “Getal” voor de velden in kwestie én stuurt de API deze waarden ook effectief door als getallen. Treedt er toch een probleem op? Dan kan je de instelling terug op “Ja” zetten terwijl je het probleem oplost.
Voor ontwikkelaars§
Yesplan verandert de manier waarop waarden uit ticketingsystemen opgeslagen worden in customdatavelden voor externe gegevens:
- Vóór Yesplan 28 was de inhoud van zo’n veld altijd “Tekst (één regel)”, zelfs als het veld eigenlijk een getal bevatte.
- Vanaf Yesplan 28 kan je verschillende gegevenstypes voor deze waarden kiezen. Dit is vooral relevant voor waarden van het type “Getal” (aantal beschikbare tickets, aantal verkocht enz.).
Vanaf Yesplan 28 zijn de waarden die je kan terugsturen of opvragen via de API dus niet langer beperkt tot het gegevenstype (“data type”) “Single-Line Text” voor customdatavelden van het type “Externe gegevens”. Zie Datatypes of Remote Data and Integration Data voor de nieuwe mogelijkheden.
Voor de overgangsperiode hebben we in Yesplan een instelling aangemaakt waardoor deze waarden altijd als een tekenreeks (“String”) verstuurd worden in de API, zelfs als het veld een getal bevat (en dus van het gegevenstype “Number” is). Eens deze instelling uitgeschakeld wordt zullen de waarden als een JSON number in plaats van een JSON string teruggegeven worden.
Dit kan gevolgen hebben voor je integratie: waar je vroeger voor zulke velden altijd een String ontving, kan dat nu ook een Number (of een ander gegevenstype) zijn. Hoe weet je zeker dat je integratie compatibel is met de nieuwe situatie?
Generieke Ticketing Module§
Maakt je integratie gebruik van de Generieke Ticketing Module en customdatavelden van het type “Externe gegevens”? Dan kan de JSON-waarde die Yesplan ophaalt uit jouw API:
- Voor het gegevenstype “Single-Line Text” voorlopig ook een getal zijn.
- Voor het gegevenstype “Number” voorlopig ook een JSON string zijn die een getal bevat.
Via de REST API§
Vraag of verstuur je via de REST API waarden voor customdatavelden van het type “Externe gegevens”? Dan moet je de volgende stappen zetten:
- De instelling voor verouderde functionaliteit zorgt ervoor dat de waarden van alle velden van het type “Externe gegevens” teruggegeven worden als een JSON string, zelfs als het gegevenstype “Number” is.
- Je kan testen of een verandering van het gegevenstype (van String naar Number) impact heeft op je integratie door een speciale HTTP Header in te bedden in je requests aan de Yesplan API. Zie Datatypes of Remote Data and Integration Data voor meer informatie.
- Eens elke integrator aan een klant bevestigd heeft dat de integratie compatibel is met de nieuwe gegevenstypes, zal de klant de instelling voor verouderde functionaliteteit op “Nee” zetten, waardoor waarden in de API verstuurd worden in het correcte gegevenstype.