IMPLEMENTATION GUIDE RIBASE

IMPLEMENTATION GUIDE ” RIBASE”

Van:

:

Ritense B.V.

Datum

:

15 februari 2010

Version

:

3.1

IMPLEMENTATION GUIDE RIBASE

1 INTRODUCTIE Het riBase framework voorziet onder andere in de centrale opslag van gegevens in database tables. Centrale opslag wil zeggen dat ook andere, externe, applicaties met riBase kunnen communiceren om gegevens uit te wisselen. Hiervoor is een uitgebreide externe application programming interface (API) beschikbaar. Dit document bevat een beschrijving van die interface. De focus van de “centrale opslag functie” van riBase ligt, vanaf versie 3, in het onderdeel “Datastore”. De Datastore voorziet in opslag. Daarom heen zien diverse modules beschikbaar en al dan niet geïmplementeerd, die eigen functionaliteiten kennen die ook via de API worden ontsloten. Het centraal opslaan van gegevens in de Datastore biedt de volgende voordelen: 1. Applicaties putten gegevens uit één centrale database, zodat gegevens slechts op één punt onderhouden hoeven worden en over alle applicaties gelijk zijn; 2. Ondersteuning voor het principe van “Single Sign On” (SSO) waardoor gebruikers na één keer inloggen toegang krijgen tot meerdere applicaties. Gebruikers kunnen met één username/password combinatie in meerdere applicaties inloggen; 3. De synchronisatie met een eventueel backend systeem (“de administratie”) wordt vereenvoudigd. Dit document bevat de implementation guide voor de riBase API. Dit zou voldoende informatie moeten bevatten voor ontwikkelaars van “externe” applicaties, om aan te sluiten op de riBase API.

1.1 riBase3 Met de introductie van riBaseV3 is de API aanzienlijk veranderd. Dit komt omdat de core component “Paspoort” vervangen is door de “Datastore”. De API van riBaseV2 is anders dan die van riBase3. Dit document, in versies vanaf 3.0, heeft betrekking op riBaseV3.

© ritense bv – 2010

2

100622-IG-riBase(3.2).doc


2 VERSIE BEHEER Versie nr. 1.0 1.1 1.2

Datum 15/12/06 18/12/06 12/09/07

1.3 1.4

25/01/08 23/06/08

3.0 3.1

07/12/09 12/02/10


Wijzigingen Review Toegevoegd: batch update support. Query als XML Tekst wijzigingen nav feedback riBase3 Toevoegingen api calls

3

Auteur I. Verbeek P.J. van Klaveren P.J. van Klaveren I. Verbeek I. Verbeek I. Verbeek J. Caris



3 INHOUDSOPGAVE 1

INTRODUCTIE .......................................................................................................................2 1.1

RIBASE3............................................................................................................................2

2

VERSIE BEHEER ..................................................................................................................3

3

INHOUDSOPGAVE ...............................................................................................................4

4

BEGRIPPEN ...........................................................................................................................5

5

ALGEMEEN............................................................................................................................6 5.1 5.2 5.3 5.4 5.5

6

INTERFACES .......................................................................................................................10 6.1 6.2

7

W ORKSPACE.....................................................................................................................6 ACCESSCODE ...................................................................................................................6 BEPERKTE TOEGANG ........................................................................................................7 SINGLE SIGN ON (SSO)...................................................................................................7 SYNCHRONISATIE BACKEND .............................................................................................8

COMPONENT INTERFACE ................................................................................................10 W EBSERVICE INTERFACE ...............................................................................................10

METHODS ............................................................................................................................13 7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 7.9 7.10 7.11 7.12 7.13 7.14 7.15

AUTHENTICATE ................................................................................................................13 SELECTDATA ...................................................................................................................13 SEARCHDATA ..................................................................................................................14 INSERTDATA ...................................................................................................................14 UPDATEDATA ..................................................................................................................15 DELETEDATA ...................................................................................................................15 BATCHCHANGEDATA ......................................................................................................16 GETCHANGEDDATA ........................................................................................................16 SELECTCHOICEFIELDVALUES .........................................................................................17 RETURNCHOICEFIELDDETAILS ...................................................................................17 SUBSCRIBE ..................................................................................................................18 UNSUBSCRIBE .............................................................................................................18 ISSUBSCRIBED ............................................................................................................18 GENERATESSO ..........................................................................................................19 AUTHENTICATESSO ...................................................................................................19


4



4 BEGRIPPEN Klanten In riBase termen zijn klanten de organisaties die gebruik maken van riBase. Per klant is een onbeperkt aantal workspaces mogelijk. Workspace Een workspace is een werkgebied voor een klant. Meerdere workspaces per klant zijn mogelijk. Een workspace kadert een specifieke toepassing van riBase waarbinnen gebruik kan worden gemaakt van de verschillende modules van riBase. Door middel van workspaces is het mogelijk riBase meerdere malen in te zetten ten behoeve van functioneel gescheiden toepassingen. Datastore De centrale opslag binnen riBase vind plaats in de Datastore. De Datastore bevat tables, inclusief relaties daar tussen. Table In analogie met een database table, bevat de Datastore ook tables met data. Een table kent records en columns. (Externe) applicatie Een externe applicatie die gebruik maakt van de externe applicatie interface (API) van riBase. Method Een functie in de externe API. De mogelijke methods van de API liggen vast en worden in dit document beschreven. Bij methods horen argumenten (parameters) die kunnen worden meegegeven. Unieke sleutelwaarde Een per table configureerbare eigenschap van het betreffende record die fungeert als unieke sleutelwaarde, dat wil zeggen dat voor alle records binnen de table deze waarde uniek is. Bijvoorbeeld een lidmaatschapsnummer, een email adres, etc. In table-termen ook wel naar gerefereerd als unique key value. SSO Staat voor Single Sign On. Het principe waarbij gebruikers door één maal in te loggen toegang hebben tot meerdere applicaties, allen aangesloten op riBase.


5



5 ALGEMEEN Voor alle methods binnen de API, die door applicaties gebruikt mogen worden geldt dat er altijd een tweetal argumenten moeten worden meegegeven. Deze zijn: -

workspace = de string die aangeeft wie er toegang vraagt en tot welke workspace deze toegang vraagt. accesscode = de accesscode is een password of een versleutelde accesscode, afhankelijk van de gekozen beveiliging.

De API en daarmee riBase is beveiligd tegen onrechtmatig gebruik. Uiteraard. Beveiliging van data is een hot item. Binnen riBase kan vrij precies worden bepaald tot welke resources elke applicatie toegang heeft. De autorisatie bestaat uit een workspace en een accesscode. De accesscode is of het password of een versleutelde accesscode. Per applicatie / workspace kan worden ingesteld welke vorm van beveiliging zal worden gebruikt. Een versleutelde accesscode is lastiger te implementeren aan de kant van de applicatie, maar wel veiliger.

5.1 Workspace Wanneer een applicatie gebruik wil maken van riBase dient deze bij elke connectie naar de API de volgende gegevens mee te sturen 1. applicatie identifier, noodzakelijk om zichzelf te identificeren 2. klant identifier, voor welke riBase klant worden gegevens opgeroepen 3. workspace identifier, tot welke workspace wenst de applicatie toegang Dit gebeurt in een enkele string die we workspace noemen. Deze is opgebouwd uit bovenstaande gegevens, gescheiden door een punt. Syntax: “applicatie.klant.workspace”. Voorbeeld workspace: “mijnapp.demo.leden” In dit voorbeeld wil de applicatie “mijnapp” toegang tot de workspace “leden” van de riBase klant “demo”. Beheerders van riBase maken deze identifiers aan en communiceren deze met de ontwikkelaars van de externe applicatie.

5.2 Accesscode Wanneer er geen encryptie vereist is, dan wordt een normaal password voor de accesscode gebruikt. Dit password is uniek per applicatie, maar gelijk voor alle workspaces waartoe deze applicatie toegang wenst. Wanneer er encryptie vereist is dan wordt de accesscode versleuteld. De string die zal worden versleuteld is wederom de workspace met daaraan toegevoegd een timestamp. Voorbeeld voor encryptie: “mijnapp.demo.leden:20061215123015” De timestamp is opgebouwd als “yyyymmddHHmmss”. Deze string wordt ge-“encrypt”. Door de timestamp is de encrypted waarde altijd uniek. Voorbeeld na encryptie: “A6-Q1F/B?TD*(V1JMBYF81JM>]-3\C-&K*
6



De encryptie sleutel of password worden met de ontwikkelaar van de applicatie kort gesloten. N.B. De door Paspoort gebruikte bronbestanden voor het encrypten en decrypten zijn standaard TDES libraries in een J2EE platform. Voor zover bekend zijn deze volledig compatibel met TDES libraries in een .NET platform.

5.3 Beperkte toegang Alle applicaties hebben default toegang tot alle methods en alle informatie binnen de workspaces waartoe ze toegang vragen. Binnen riBase kan de toegang per applicaties worden beperkt op de volgende manieren: •

Restrictie op methods

Dat wil zeggen dat niet alle methods in de interface enabled worden. Een goed voorbeeld is “alleen authenticatie”. Indien een applicatie alleen dient te autoriseren of een gebruiker een geldige gebruiker is, kan de toegang worden beperkte tot enkel de “Authenticate” en “AuthenticateSSO” methods. Hiermee kan een login-combinatie of een SSO waarde worden geautoriseerd. De applicatie ontvangt echter geen gebruikersgegevens en heeft hier ook geen toegang toe. Ook andere combinaties zijn mogelijk, bijvoorbeeld alleen “Select” / “Search” en geen “Update” of “Delete” rechten. •

Restrictie in record toegang

Binnen Datastore tables is het ook mogelijk een applicatie alleen toegang te verschaffen tot die records die voldoen aan een bepaalde eigenschap. Voor de hand ligt een eigenschap “toegankelijk voor applicatie A” waarbij de beperking is gebouwd al applicatie A heeft alleen toegang tot die records waarvoor geldt dat deze “toegankelijk zijn voor applicatie A”. •

Restrictie op column toegang

Binnen Datastore tables is het ook mogelijk een applicatie alleen toegang te verschaffen tot een aantal specifieke columns. Oftewel, precies bepalen welke informatie per record toegankelijk is voor de applicatie. Voorbeelden zijn wel toegang tot naam- en adresgegevens, maar bijvoorbeeld niet tot financieeele gegevens. De externe applicatie dient zich bewust te zijn van mogelijke beperkingen. Voor o.a. het toevoegen van nieuwe records gelden dan ook beperkingen. De geboden methods zijn gelijk voor alle situaties en dus niet afhankelijk van de toegangsrechten. De toegangsrechten bepalen alleen wel welke informatie de applicatie wel of niet terug ontvangt van riBase.

5.4 Single Sign On (SSO) riBase ondersteunt het principe van Single Sign On (SSO), oftewel het eenmalig inloggen voor meerdere applicatie. De situatie is als volgt: -

Applicatie A : geeft gebruikers de mogelijkheid om in te loggen, gebruik makend van hun username / password. Applicatie B : geeft gebruikers de mogelijkheid in te loggen, wederom gebruik makend van hun username / password. Het betreft dezelfde gebruikers.


7



Sommige tables in de Datastore zijn bij uitstek bedoeld om username / password centraal op te slaan, zodat gebruikers met dezelfde combinatie bij zowel applicatie A als B kunnen inloggen. Daartoe dienen beide applicaties op riBase te worden aangesloten. Stel dat een gebruiker reeds is ingelogd bij applicatie A en deze applicatie bevat een link naar applicatie B. Idealiter wil je dan dat gebruiker niet nogmaals opnieuw hoeft in te loggen, ook al is de username / password combinatie hetzelfde. Beter is dat de gebruiker bij applicatie B reeds is ingelogd. Aangezien het twee seperate applicaties betreft kan dit alleen als applicatie A in de link naar applicatie B informatie meegeeft, waarbij applicatie B weet welke gebruiker het betreft. Dit is daadwerkelijk een link, dus is het zeer onverstandig hierin bv. een wachtwoord mee te nemen. Juist voor deze problematiek is SSO ontworpen en ondersteunt riBase dit. Het stappenplan ziet er als volgt uit: 1) Applicatie A laat de gebruiker inloggen door de reguliere Authenticate functie van riBase. De gebruiker is nu ingelogd voor applicatie A. 2) Applicatie A genereert een SSO waarde door middel van de GenerateSSO method van riBase. De aanroep is niet lastiger dan een Select of een reguliere Authenticate. De geretourneerde SSO waarde is ingewikkeld van opbouw, maar de complexiteit ligt volledig bij riBase. De SSO waarde is een normale string. 3) Applicatie A genereert een link vergelijkbaar met deze: http://adres.applicatieb/login.cfm?sso=SSOWAARDE 4) Het exacte internet adres voor deze link moet uiteraard tussen applicaties A en B worden afgestemd. Deze bevat echter altijd de SSO argumenten die door applicatie A zal worden ingevuld op basis van de door riBase gegenereerde SSO waarde. 5) Applicatie B ontvangt een request op bovenstaand adres. 6) De SSO waarde wordt door applicatie B gebruikt als input voor de AuthenticateSSO method van riBase. Deze is sterk vergelijkbaar met een normale Authenticate aanroep. 7) De method retourneert of FALSE ingeval de SSO waarde ongeldig is, of TRUE indien het een geldige waarde is. Bij TRUE kan de gebruiker automatisch worden ingelogd. Optioneel kan dit aangevuld worden met return_type, waarna riBase ook een unieke ID voor de gebruiker retourneert. Het is belangrijk om te realiseren dat een internet adres inclusief een SSO waarde hetzelfde is als een ingevuld formulier met username / password of een adres in deze vorm: /login.cfm?username=username&password=password. Deze links zijn sterk persoonsgebonden en dienen dus nooit als algemeen adres voor een applicatie te worden gebruikt. Een link dient ook altijd real-time via paspoort dynamisch te worden opgebouwd en niet opgeslagen in favorieten of een startpagina. De SSO waarde bevat daadwerkelijk het username / password van een gebruiker, zei het in encrypted vorm en in een formaat die alleen paspoort kent. Een SSO waarde is nooit hetzelfde.

5.5 Synchronisatie backend Het synchroniseren van een backend systeem van een organisatie enerzijds, en een online toegankelijke riBase workspace anderzijds, is een veel voorkomende probleemstelling. riBase biedt daartoe de volgende twee oplossings scenario’s. (Deels) handmatig © ritense bv – 2010

8



Elke wijziging aan een record in een table in de Datastore kan real-time worden doorgegeven aan het backend systeem. Dit kan maatwerk zijn. Indien de backend “open” is zou bijvoorbeeld een webservice request van online riBase naar de backend mogelijk zijn. Meer standaard is een email met daarin informatie over de wijziging. De meest voorkomende manier om wijzigingen in de backend door te geven aan riBase is gebruik te maken van de import mogelijkheden. Standaard ondersteunt riBase zowel CSV als XML import bestanden. Velden dienen vooraf afgestemd te worden. Automatisch De externe API biedt twee specifieke functies om het proces van automatisch synchronisatie te realiseren. De trigger ligt meestal bij het backend systeem. Deze neemt het initiatief ter synchronisatie. Dit kan in vaste periodes, bijvoorbeeld eens per dag, en werkt als volgt: 1. De functie batchChangeRelaties geeft de mogelijkheid om in één keer een batch door te geven van alle gewijzigde records, inclusief insert/update/delete informatie. De riBase externe API zal deze dan ook in batch verwerken. 2. De functie getChangedRelaties geeft de mogelijkheid om in één keer aan riBase te vragen welke wijzigingen er zijn geweest sinds een bepaalde datum. Het resultaat is een batch van gewijzigde records inclusief informatie over wat er gewijzigd is. Uitwerking van de functies in het daarvoor bestemde hoofdstuk. Wijzigingen die via batchChangeRelaties() worden doorgegeven, komen niet terug in de getChangedRelaties, waardoor er geen cirkel kan ontstaan.


9



6 INTERFACES De API van riBase biedt twee verschillende soorten interfaces die ingezet kunnen worden door externe applicaties. De manier van interactie met de interfaces is anders, de methods en bijbehorende argumenten echter niet. In dit hoofdstuk beschrijven we alleen de manier van interactie met elk van deze interfaces. De methods en argumenten worden in het volgende hoofdstuk beschreven. In dit hoofdstuk komt een aantal keren de URL http://ribaseapi/ terug. Hiervoor zal door beheerders van riBase seperaat een exact internet adres worden gecommuniceerd die overeen komt met de installatie van riBase waarmee de ontwikkelaar van de externe applicatie wenst te communiceren. Naast de methods en argumenten is er ook speciale aandacht voor de zogenaamde “variabele argumenten”. Dit zijn argumenten die optioneel zijn. Juist dergelijke variabele argumenten zijn voor met name de twee webservice interfaces problematisch en vragen een specifieke aanpak. Het gebruik van variabele argumenten zal per interface worden toegelicht.

6.1 Component interface Met de component interface kan vanuit een ColdFusion applicatie op dezelfde server als riBase, direct in de externe API de juiste component worden aangeroepen die voor verdere afhandeling van de functies zorgt. De mapping naar de component is “ribaseinterface.”. Daarna moet nog de juiste component worden aangesproken. De aanroep ziet er bijvoorbeeld zo uit:
component=" ribaseinterface.datastore" method="Authenticate" workspace="mijnapp.demo.leden" accesscode="password" table=”leden” usr="uniekesleutel" pwd="wachtwoord" return_type=”boolean” returnvariable="hasAccess">

Dit is een voorbeeld van de Authenticate method. Overige methods werken vergelijkbaar, zei het dat argumenten anders kunnen zijn. Variabele argumenten worden als ColdFusion structure meegegeven. We geven wederom een voorbeeld:
component=" ribaseinterface.datastore " method="SelectData" workspace="mijnapp.demo.leden" accesscode="password" table=”leden” varargs="#varargs#" returnvariable="qry_relatie">

De component interface is niet geschikt voor applicaties die extern, dat wil zeggen op een andere fysieke server worden gehost en/of niet in Adobe ColdFusion zijn gemaakt.

6.2 Webservice interface © ritense bv – 2010

10



De webservice interface kan door middel van een webservice invocation worden aangeroepen. De URL is als volgt: http://ribaseapi/datastore.cfc?WSDL http://ribaseapi/security.cfc?WSDL http://ribaseapi/mailing.cfc?WSDL Door deze URL rechtstreeks aan te roepen kan online documentatie worden opgevraagd. De manier van het invoken van een webservice is verschillend voor ontwikkeltalen als ASP.NET, PHP, etc. We geven wederom een ColdFusion voorbeeld:

De argumenten usr, pwd en return_type zijn allemaal verplicht! Het probleem ontstaat bij de variabele argumenten. Variabele argumenten worden in XML formaat aangeleverd. Doel is de argumenten uiteindelijk als simple value, namelijk als string, door te geven, zei het wel verpakt. Een voorbeeld: <arguments> <customkey_value>uniekesleutel

Let op, bovenstaand voorbeeld gebruikt een functie cfsavecontent. Het uiteindelijke resultaat is een string met de naam xml_varargs en de inhoud is: <arguments> <customkey_value>uniekesleutel

De cfsavecontent functie aanroep is geen onderdeel van de string. De string bevat nu XML structure van argumenten. Daarna volgt de webservice invocation.

Een aantal methods vereisen bovendien dat er geen strings of numerieke waarden, maar complexe datastructuren als argument moeten worden meegegeven. De batchChangeRelaties bijvoorbeeld. De samenstelling van deze XML structuren is als volgt: Query Noodzakelijk als changes argument in batchChangeRelaties. Dit ziet er als volgt uit: © ritense bv – 2010

11



lidnr wachtwoord batch_change_type batch_changed_fields 1 <wachtwoord>nieuw wachtwoord update wachtwoord

Indien er meerdere kolommen zijn opgenomen, moeten die zowel in de columnlist definitie terug komen, maar ook als veld bij elk record. De aanroep is dan vervolgens als volgt: method="batchChangeRelaties" returnvariable="result">

Let wel, de columns batch_change_type en batch_changed_fields hebben een speciale toepassing binnen deze method. Het gaat bij bovenstaande uitleg echter vooral over het principe van het formateren van een query als XML.


12



7 METHODS De twee interfaces ondersteunen elk dezelfde methods. Deze worden hieronder elk per stuk benoemd. Een aantal aandachtspunten vooraf: -

Methods vallen binnen een component. De datastore is zo’n component. SSO kent zijn eigen component en ook alle modules hebben een eigen component in de API. De argumenten “workspace” en “accesscode” zijn verplicht voor ALLE methods en worden daarom niet elke keer expliciet genoemd. Veel voorkomende, maar niet altijd voorkomende argumenten als bijvoorbeeld “table” worden wel steeds vermeld. Het verschil tussen verplichte en variabele / optionele argumenten zal duidelijk worden vermeld.

7.1 authenticate Onderdeel “security” component. Met deze method kan een record in een table worden geauthenticeerd. Per table ligt vastgelegd welke kolommen fungeren als sleutelwaarde en welke als wachtwoord. Aan de method worden deze als vaste argumenten USR en PWD meegegeven. Verplichte argumenten: TABLE : Desbetreffende table identifier. USR : de waarde die fungeert als username (= sleutelwaarde). PWD : de waarde die fungeert als wachtwoord. RETURN_TYPE : hiermee kan de applicatie bepalen wat voor soort returnvariabele deze wenst. Default is “boolean” die overigens wel verplicht moet worden meegegeven. Variabele argumenten: Geen Retourneert: Boolean in geval van return_type=boolean, dat wil zeggen “true” or “false”. Een string in het formaat “true;ID” in geval van return_type=id, waarbij “ID” daarin een uniek door Paspoort gegenereerd relatienummer is. Of een string in het formaat “true;CUSTOMKEY_VALUE” in geval van return_type=customkey_value, waarij “CUSTOMKEY_VALUE” de sleutelwaarde is van desbetreffende record.

7.2 selectData Onderdeel “datastore” component. Deze method kan gebruikt worden voor het selecteren van alle records uit een tabel, of een specifiek record of set van records. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. XML_ARGUMENTS: XML container bestaande uit variabele argumenten. Variabele argumenten: Geen : selecteert alle records van een tabel. ID : dit is een riBase interne identifier voor het record, die uniek is. Selecteert max 1 record. CUSTOMKEY_VALUE : de unieke sleutelwaarde van een record. Selecteert ook max 1 record. © ritense bv – 2010

13



Retourneert: Query van records. Kan nul, één of meerdere records bevatten.

7.3 searchData Method die gebruikt kan worden voor het zoeken van records die voldoen aan een specifieke criteria of serie van criteria. Verplichte argumenten: LIJST : Desbetreffende lijst identifier. Variabele argumenten: SEARCHFIELDS en SEARCHVALUE : deze combinatie zoekt naar alle records waarbij de searchvalue voorkomt in een veld binnen de searchfields. Dit kan een set van velden zijn. COLNAME : een variabel aantal is mogelijk, waarbij er zal worden gezocht op records waarbij de genoemde colname matched met de opgegeven waarde. Ook combinaties van bovenstaande zijn mogelijk Een aantal concrete voorbeelden: 1) searchfields=voornaam,achternaam,bedrijfsnaam, searchvalue=jan retourneert alle records waarbij “jan” voorkomt in of de voornaam, of de achternaam of de bedrijfsnaam. 2) klantsoort=mkb, isBelangrijk=1 retourneert alle records waarbij de klantsoort gelijk is aan “mkb” en het veld isBelangrijk gelijk aan “1”. 3) klantsoort=mkb, isBelangrijk=1, searchfields=voornaam,achternaam,bedrijfsnaam, searchvalue=jan retourneert alle records waarbij “jan” voorkomt in of de voornaam, of de achternaam of de bedrijfsnaam en waarbij de klantsoort gelijk is aan “mkb” en het veld isBelangrijk gelijk aan “1”. Retourneert: Query van records.

7.4 insertData Onderdeel “datastore” component. Method die gebruikt kan worden om relaties toe te voegen aan een lijst. Verplichte argumenten: TABLE : Desbetreffende lijst identifier. XML_DATA : XML container bestaande uit data die geinsert moet worden. Variabele argumenten: Hierbij kunnen alle mogelijke kolommen inclusief hun waarde worden toegevoegd. De kolom definities worden tussen riBase en applicatie afgesproken. Een voorbeeld: Voornaam=jan, achternaam=jansen, [email protected], klantsoort=mkb, etc. Retourneert: Numerieke 0 indien de insertion niet heeft plaats gevonden. Een voor de hand liggende reden is dat de sleutelwaarde (uniquekey_value) niet uniek is. Andere numerieke waarde als zijnde het ID van het nieuw toegevoegde record bij een succesvolle insertion. © ritense bv – 2010

14



7.5 updateData Onderdeel “datastore” component. Method die gebruikt kan worden om de gegevens van een specifieke record te updaten. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. RECORD_ID : Desbetreffende interne identifier voor het record. XML_DATA : XML container bestaande uit data die geupdate moet worden. Variabele argumenten: Hierbij kunnen alle mogelijke kolommen inclusief hun waarde worden toegevoegd. De kolom definities worden tussen riBase en applicatie afgesproken. Een voorbeeld: Voornaam=jan, achternaam=jansen, [email protected], klantsoort=mkb, etc. Retourneert: TRUE

7.6 deleteData Onderdeel “datastore” component. Met deze functie kan een record uit de lijst worden verwijderd. Verplichte argumenten: TABLE : Desbetreffende lijst identifier. RECORD_ID : Desbetreffende interne identifier voor het record. Variabele argumenten: Geen Retourneert: TRUE


15



7.7 batchChangeData Hiermee kunnen verschillende relaties van een lijst in één keer toegevoegd, gewijzigd en/of verwijderd worden. Typische toepassing is synchronisatie met extern back-office systemen. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. CHANGES : Query met wijzigingsgegevens. Retourneert: TRUE als geen fouten zijn opgetreden. De CHANGES query bevat de volgende kolommen: Unique key (met sleutelwaarde, kolomnaam is instelbaar per lijst) BATCH_CHANGE_TYPE (insert,update,delete) BATCH_CHANGED_FIELDS (geeft aan welke kolommen gewijzigd zijn) De BATCH_CHANGED_FIELDS kolom is optioneel en alleen significant bij updates. Indien aanwezig en niet leeg, worden alleen de gespecificeerde kollommen gewijzigd. Het scheidingsteken is een comma. NB: Bij een aanroep in XML formaat (bv. de Webservice XML interface) dient het CHANGES argument te worden vervangen door een XML_CHANGES, waarbij deze als XML is geformateerd. Een toelichting hierop is eerder gegeven bij desbetreffende interface.

7.8 getChangedData Hiermee kunnen wijzigingen in een bepaalde periode van een lijst opgevraagd worden. Typische toepassing is synchronisatie met extern back-office systemen. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. FROMDATE : Eerste dag van de periode in yyyymmdd formaat. TODATE : Laatste dag van de periode in yyyymmdd formaat. Retourneert: Query met gevraagde wijzigingen. De resultaat query bevat de volgende kolommen:: Alle kollommen van de betreffende relatie BATCH_CHANGE_TYPE (insert,update,delete) BATCH_CHANGED_FIELDS (geeft aan welke kolommen gewijzigd zijn) De BATCH_CHANGED_FIELDS waarde is alleen significant bij updates. NB1: Wijzigingen zullen indien mogelijk gecombineerd worden. Als een relatie is toegevoegd en daarna gewijzigd en tenslotte verwijderd zal geen melding worden gemaakt. Als een relatie is toegevoegd en daarna gewijzigd zal deze als een 'insert' worden gemeld. Als een relatie verschillende keren is gewijzigd zullen alle wijzigingen gecombineerd als 'update' worden gemeld. Indien een relatie is verwijderd zullen eventuele voorgaande wijzigingen niet meer gemeld worden.


16



NB2: Als alle wijzigingen uitsluitend via batchChangeRelaties() zijn binnengekomen zullen deze niet meer teruggemeld worden.

7.9 selectChoicefieldValues Onderdeel “datastore” component. Per workspace kunnen één of meerdere keuze-velden zijn gedefinieerd. Dat wil zeggen dat de database representatie een cijfer is die correspondeert met een specifieke titel. In formulieren vaak een selectbox, radiobutton of checkbox. De mogelijke combinaties kunnen door de applicatie worden opgevraagd middels deze method. Een keuze-veld kan ook worden gebruikt voor een multiple-select veld. Dat wil zeggen dat de database representatie een lijst van cijfers is, waarbij elk cijfer correspondeert met een specifieke titel. In formulieren vaakt een rij van checkboxes of een multiple-selectbox. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. CHOICEFIELD : Het keuzeveld waarvoor de keuze-waarden worden opgeroepen. Retourneert: Query met alle keuze-velden. Deze query bevat in ieder geval een kolom ID, die refereert met de specifieke foreignkey waarde in het relatie record, en een kolom TITLE die fungeert als naam. Voorbeeld: een lijst met relaties heeft een kolom PROVINCIE. Er is tevens een keuzeveld PROVINCIE die als query retourneert: 1,Drente 2,Flevoland 3,Friesland 4,Gelderland 5,Groningen 6,Limburg 7,Noord Brabant 8,Noord Holland 9,Overijssel 10,Utrecht 11,Zeeland 12,Zuid Holland In de lijst met relaties staan dan de waarden 1 t/m 12 die corresponderen met desbetreffende provincies. Indien dit vooraf duidelijk is afgesproken tussen paspoort en de externe applicatie, kunnen dit soort keuze-velden uiteraard ook hard gecodeerd worden, zodat deze niet steeds door de applicatie moeten worden opgehaald. De waarde van een keuze-veld is altijd een numerieke waarde.

7.10 returnChoicefieldDetails Indien enkel voor één numerieke waarde die correspondeert met een keuze-veld, de keuze-optie gewenst is, kan deze method worden gebruikt. Verplichte argumenten: CHOICEFIELD : Het keuzeveld waarvoor de keuze-waarden worden opgeroepen. SELECTED : De waarde van het keuze-veld. RETURN_TYPE : Het formaat van de returnvariabele. © ritense bv – 2010

17



Retourneert: Afhankelijk van het return_type. Indien “struct” retourneert de method een structure, oftewel het specifieke record uit de keuze-waarden in de vorm van een struct. Indien “query” retourneert de method een query met max 1 record zijnde het specifieke record uit de keuze-waarden. Indien “title” retourneert de method een string, namelijk de naam van het specifieke record uit de keuze-waarden. Voorbeeld: Bij column_name=provincie (uit eerder voorbeeld), select_value=11, return_type=title, retourneert de method “Zeeland”.

7.11 subscribe Onderdeel “mailing” component. De method om een gebruiker te subscriben voor een specifieke mail toepassing. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. RECORD_ID : Desbetreffende interne identifier voor het record. Variabele argumenten: Geen Retourneert: TRUE

7.12 unsubscribe Onderdeel “mailing” component. In tegenstelling tot subscribe, uiteraard bedoeld om een relatie te unsubscriben voor een specifieke mail toepassing. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. RECORD_ID : Desbetreffende interne identifier voor het record. Variabele argumenten: Geen Retourneert: TRUE

7.13 isSubscribed Onderdeel “mailing” component. De method om te bepalen of een relatie al dan niet is ge-subscribed voor een specifieke mail toepassing. Verplichte argumenten: TABLE : Desbetreffende tabel identifier. RECORD_ID : Desbetreffende interne identifier voor het record. © ritense bv – 2010

18



Variabele argumenten: Geen Retourneert: TRUE of FALSE, wat aangeeft of de relatie ge-subscribed (true) of juist ge-unsubscribed (false) is.

7.14 generateSSO Onderdeel “security” component. Met deze functie zal riBase een SSO waarde gegeneren. Hiermee kan de applicatie een SSO link maken naar een andere applicatie die ook is gekoppeld aan riBase. Zie apart hoofdstuk over SSO. Verplichte argumenten: TABLE : Desbetreffende table identifier. Variabele argumenten: ID : dit is een interne identifier voor het record, die uniek is. Selecteert max 1 record. Dit argument wordt gebruikt om een record te bepalen voor wie de SSO waarde zal worden gegenereerd. Retourneert: Een string met een SSO waarde. Deze waarde is een op het eerste gezicht willekeurige string van een groot aantal karakters. De SSO waarde is bij elke aanvraag anders. SSO waarden kunnen dus niet worden opgeslagen. Bij niet bestaande gebruiker of onvoldoende rechten is de SSO waarde leeg.

7.15 authenticateSSO Onderdeel “security” component. Met deze method kan een record op de lijst worden geauthenticeerd. Er wordt echter geen username / password meegegeven, zoals bij de originele Authenticate functie, maar als input dient een SSO waarde zoals die eerder door de GenerateSSO functie is gegenereerd. Zie apart hoofdstuk over SSO. Verplichte argumenten: TABLE : Desbetreffende table identifier. SSO : de SSO waarde. RETURN_TYPE : hiermee kan de applicatie bepalen wat voor soort returnvariabele deze wenst. Default is “boolean” die overigens wel verplicht moet worden meegegeven. Variabele argumenten: Geen Retourneert: Boolean in geval van return_type=boolean, dat wil zeggen “true” or “false”. Een string in het formaat “true;ID” in geval van return_type=id, waarbij “ID” daarin een uniek door Paspoort gegenereerd relatienummer is. Of een string in het formaat “true; CUSTOMKEY_VALUE” in geval van return_type=customkey_value, waarij “CUSTOMKEY_VALUE” de sleutelwaarde is van desbetreffende record. © ritense bv – 2010

19


IMPLEMENTATION GUIDE RIBASE

Recommend Documents