2. Documenthistorie
Versiebeheer
Versie Datum Auteur Samenvatting van de wijzigingen
Goedkeuring
De hieronder genoemde personen hebben kennis genomen van de inhoud van het document
en deze goedgekeurd:
Versie Datum Naam Functie Handtekening
R0s1
Distributie
Dit document is aan de onderstaande personen verstuurd:
Versie Datum Naam Functie Bedrijf
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 2 van 75
4. 1. Technische specificatie Itris SOAP calls
1.1. Inleiding
Dit document beschrijft in detail de beschikbare SOAP calls in de Itris ViewPoint koppeling.
Calls zijn geordend op basis van hun functionaliteit.
1.2. Gebruikte conventies
TODO/aanpassen
1.3. Gebruikte termen en begrippen
Voor een goed begrip worden de volgende termen en definities gebruikt in de tekst.
ViewPoint, ViewPoint Systeem
Met deze termen bedoelen we het gehele ViewPoint systeem. In dit document wordt hier
meestal de SOAP receptor voor het systeem bedoeld. Het ViewPoint systeem bestaat echter uit
een webserver, database server, Business Objects server en verschillende fysieke machines.
Peer systeem
Met deze term bedoelen we de “tegenpartij”, d.w.z. het systeem waarmee ViewPoint
communiceert.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 4 van 75
5. 2. Algemene eigenschappen en details
De hier beschreven mogelijkheden zijn een standaard functionaliteit van ViewPoint, en worden
dus niet gebouwd voor een enkele, specifieke koppeling. Dit betekent dat dezelfde calls gebruikt
worden door alle koppelingen, waar nodig.
2.1. Het low-level koppelvlak
Voor de interactie zijn de volgende onderdelen en begrippen belangrijk:
• Het “peer” systeem: dit is een systeem waar ViewPoint SOAP messages kan afleveren, en
wat zelf ook messages kan sturen aan het ViewPoint systeem.
• Het ViewPoint systeem bestaat (op dit moment) uit één of meer web servers en één
database server, veelal aanwezig op locatie bij een klant. Dit systeem kan later worden
uitgebreid met extra web servers; deze mogelijkheid mag niet tot problemen leiden. De hele
combinatie van web server(s) en database server noemen we een ViewPoint cluster.
De koppeling tussen beide systemen is gebaseerd op web services, concreet SOAP 1.1 over
HTTP(s). Het heeft onze sterke voorkeur om géén https te gebruiken om de volgende redenen:
• Gebruik over VPN is sneller en veiliger
• Opzetten van de benodigde certificaten (aan beide zijden) is relatief veel werk. Omdat een
certificaat ook regelmatig ververst moet worden (het verloopt na enige tijd) is pro-actief
beheer nodig – wat erg eenvoudig kan worden vergeten met ernstige gevolgen.
• De SSL implementatie vereist aparte IP adressen voor iedere gebruikte host; dit is veelal
een probleem voor op het Internet beschikbare machines.
• Gebruik van SSL vereist nog steeds dat het ViewPoint systeem rechtstreeks bereikbaar is
op het Internet. Dit is een onacceptabel beveiligingsrisico. Voor deze configuratie neemt
Itris geen verantwoording voor de beveiliging van het systeem.
2.2. Fysieke koppeling tussen de systemen
Een ViewPoint systeem en het peer systeem moeten kunnen communiceren voor het
uitwisselen van de SOAP berichten. Dit kan op twee manieren:
• Over een Internet-verbinding.
• Over een privé netwerk (Epacity).
2.2.1. Koppelen via het Internet
Voordeel van deze methode is dat de beschikbare bandbreedte vaak groot is tegen relatief
geringe kosten. Belangrijkste nadeel is dat de beschikbaarheid van de totale verbinding (dus
niet alleen van een machine naar het Internet, maar de volledige verbinding van machine tot
machine) niet gegarandeerd kan worden1.
Verder geldt dat het direct aansluiten van het primaire systeem op het Internet een enorm
veiligheidsrisico oplevert. Om deze reden is een directe koppeling via het Internet sterk
1 Let op: Internet providers kunnen wel een beschikbaarheid specificeren maar deze gaat
alleen over de verbinding van de locatie tot het Internet over hun netwerk. De volledige (dwz.
end-to-end) verbinding loopt over allerlei Internet infrastructuren van vele andere partijen
waar de beschikbaarheid niet van gegarandeerd wordt. Dit betekent dat de beschikbaarheid
van de totale verbinding niet gedefinieerd kan worden. Concreet betekent het ook dat bij
uitval van de verbinding de leverancier niet altijd het probleem op kan lossen.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 5 van 75
6. ongewenst.
Het advies is om in dit geval gebruik te maken van een VPN verbinding over het Internet. Hierbij
wordt alle verkeer door het VPN beveiligd en versleuteld verzonden. De voor deze koppeling
benodigde regels voor infrastructuur valt buiten de scope van dit document.
Omdat de juiste werking van het VPN voorwaardelijk is voor een betrouwbare koppeling
verdient dit onderdeel wel aandacht en moet vooral het beheer ook goed geregeld zijn.
Als laatste geldt natuurlijk ook dat de Internet verbinding aan beide kanten voldoende capaciteit
moet hebben om het berichtenverkeer tussen de verschillende omgevingen met voldoende
snelheid uit te wisselen. De benodigde snelheid is sterk afhankelijk van het gebruik en
implementatie van een specifieke koppeling, maar zal minimaal 2Mbit/s symmetrisch moeten
zijn. Dit laatste betekent dat ADSL-achtige Internet verbindingen (technisch gelimiteerd tot max.
1.3Mbit/s retour) niet voldoen.
2.2.2. Koppelen via Epacity
Het is ook mogelijk om de verbinding tussen beide systemen te maken door ze te verbinden via
Epacity. In dit geval moeten beide locaties aangesloten worden op het Epacity netwerk, met een
aansluiting met voldoende snelheid voor het verwerken van de berichtenstroom. Gezien de
mogelijke latency zal de verbindingssnelheid aan beide zijden niet lager mogen zijn dan 2MBit/s
symmetrisch; de snelheid zal veelal hoger moeten zijn voor websites met meer verkeer.
Een Epacity verbinding kost (veel) meer dan een Internet verbinding, maar heeft als voordeel
dat beschikbaarheid en gegarandeerde bandbreedte veel beter geregeld zijn, bij een enkele
aanbieder. Het betekent dat een end-to-end beschikbaarheid bekend is, en dat er een enkel
aanspreekpunt is voor communicatieproblemen.
Voor de aanvullende kosten die gemoeid zijn met een Epacity aansluiting dienen de klant en de
aanbieder van het peer systeem zelf afspraken te maken met elkaar en met Itris. De kosten
voor de snellere Epacity verbinding aan de zijde van de klant worden niet door Itris gedragen.
2.3. Gebruik van XML binnen de koppeling
De koppeling gebruikt XML als “taal” binnen de koppeling. We gebruiken XML volgens de
standaard (XML 1.0), en gebruiken namespaces om varianten (versies) van objecten en calls te
specificeren.
De gebruikte XML moet worden gelezen door een conformant parser. Deze parser moet in staat
zijn om XML met namespaces op de juiste manier te lezen. Dit betekent concreet dat de aan
een namespace gekoppelde prefix2 geen enkele betekenis heeft in het resultaat. Bij het
lezen van de XML mag dus nooit een specifieke prefix worden verwacht, noch mag een
specifieke indeling qua namespace definitie worden verwacht door de lezer. Anders gezegd: het
lezen van ontvangen XML mag niet uitgaan van:
• De vaste prefix “soap” als indicatie van een SOAP tag. De tag “ns1” kan net zo goed
verwijzen naar de SOAP namespace. Omdat veel van de ViewPoint SOAP interface
automatisch gegenereerd wordt zijn de gebruikte prefixen volledig random en kunnen
per versie en zelfs per bericht verschillen.
• Het is mogelijk dat meer dan een prefix verwijst naar dezelfde namespace.
• Het definiëren/gebruiken van namespaces binnen het XML bericht kan expliciet op
iedere door de XML standaard ondersteunde wijze. Dit betekent dat bijvoorbeeld een
2 Met prefix wordt bedoeld de “ns1” in een tag als <ns1:Envelope>.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 6 van 75
7. ontvanger er niet van uit mag gaan dat een bepaalde namespace definitie altijd op een
bepaalde plaats staat! Prefixen mogen zelfs ontbreken wanneer de “default
namespace” wordt toegepast.
Dit alles betekent dat bij juist gebruik van de interface alleen namespaces plus de namen van
elementen en attributen definiëren over welk begrip we praten. De prefix moet volledig
onzichtbaar zijn in de code.
Wanneer in het peer systeem een eigen XML parser geïmplementeerd wordt, zonder hulp van
de op het platform geboden XML mechanismes, dan dient deze implementatie de volledige
XML standaard correct te implementeren. Elke fout die veroorzaakt wordt doordat de ontvanger
de XML standaard incorrect implementeert is ter verantwoording van de ontvanger, ook als de
Itris software wordt aangepast!
In de voorbeelden van SOAP calls zullen verschillende namespace definities en prefixen
aanwezig zijn. Rekening houdende met het bovenstaande, moet het duidelijk zijn dat deze
prefixen in de werkelijke calls verschillend zullen zijn.
2.4. Datatypes binnen de gegevensset
De data binnen de gegevensset wordt gecodeerd volgens de W3C schema definities voor data
(zie http://www.w3.org/TR/xmlschema-2/#built-in-datatypes).
TODO: Lijst van mogelijke primitieve datatypes.
2.5. De Itris SOAP interfaces
De door Itris aangeboden SOAP interface wordt niet specifiek voor een bepaalde koppeling
gebouwd. Er bestaan een aantal standaard “services” die herbruikbaar zijn voor verschillende
processen en verschillende klanten. Om een grote mate van interoperabiliteit te kunnen geven
is gekozen om alleen een basale vorm van SOAP te implementeren. Deze keuze betekent dat
vrijwel ieder platform zonder al te veel problemen kan koppelen met onze implementatie, en dat
we geen interoperabiliteitsproblemen krijgen doordat verschillende producten net een andere
versie (of interpretatie) van een van de ruim 30 verschillende (combinaties van) WS-I en andere
“standaarden” en versies van de standaarden gebruiken.
2.6. Stabiliteit/levensduur van de SOAP interface
De door Itris opgeleverde SOAP interface, met de beschrijvingen van de calls en het resultaat
van de calls wordt door Itris als interface gegarandeerd stabiel gehouden (= niet incompatibel
aangepast, maar zie verder!) over een periode van drie jaar. Na deze periode kan Itris de
interface wijzigen, of bepalen dat een andere versie van de interface gebruikt moet worden. Dit
betekent dan ook een aanpassing in de gekoppelde applicaties gedaan moet worden. De
kosten van deze aanpassingen zijn voor rekening van de klant, omdat de “levensduur” van de
interface is beëindigd.
De reden dat een interface end-of-life kan raken heeft voornamelijk te maken met de technische
ontwikkeling van ViewPoint als product. Het product kan beter en stabieler worden gebouwd als
niet alle historie met alle compatibiliteitslagen continu moeten worden onderhouden.
Als Itris tussentijds een interface (gevormd door een bepaalde specificatie qua invoer en
uitvoer) moet aanpassen op een niet-compatibele wijze, bijvoorbeeld doordat de functionaliteit
van ViewPoint rond de interface is veranderd, dan zal dat gebeuren door een nieuwe versie van
de interface te definiëren. Deze nieuwe versie bestaat dan gewoon naast de oude, bestaande
versie (mits de oude versie nog wordt ondersteund). De oude versie beschikt natuurlijk niet over
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 7 van 75
8. de nieuwe functionaliteit; het gedrag van de oude interface wordt in de nieuwe versie van
ViewPoint “geëmuleerd”. De nieuwe versie van de call wordt aangeroepen doordat deze call
een andere namespace gebruikt dan de oude call.
Versies van interfaces worden binnen de SOAP call omgeving gespecificeerd door de gebruikte
namespace van de calls binnen de interface. De namespaces bepalen zowel de mogelijke
invoer als de mogelijke uitvoer van calls.
2.7. Wat betekent het stabiel houden van de interfaces?
Itris maakt één belangrijke uitzondering op het “stabiel” houden van interfaces: voor elke
mogelijke call kan op elk moment extra informatie aan zowel invoer als uitvoer van een call
worden toegevoegd. Itris garandeert wél dat de oude definitie van de call niet wijzigt door deze
toevoegingen. Dit betekent concreet dat:
• Er nooit velden verdwijnen in een bestaande interface. Als ooit is gespecificeerd dat veld X
in het resultaat zit dan blijft dat te allen tijde het geval.
• Velden zullen nooit van niveau in de antwoordstructuur veranderen.
• De semantische betekenis van het opgeleverde resultaat zal nooit veranderen zolang de
call wordt aangeroepen met de ook eerder gedefinieerde parameters(!).
• Als een call wordt uitgebreid met extra “invoerparameters” dan is dit altijd transparant, en de
parameters zijn altijd optioneel. Verder geldt dat bij afwezigheid van de “nieuwe” parameters
de hele call exact hetzelfde functioneert als de eerdere versie waar de parameters nog niet
bestonden. Pas als de nieuwe parameters zouden worden gebruikt mag het resultaat van
de call verschillend zijn. Omdat eerder gebouwde koppelingen natuurlijk nooit vanzelf extra
parameters toevoegen brengt dit op geen enkele manier de betekenis van eerder
gebouwde koppelingen in gevaar.
• De volgorde van elementen is altijd onbepaald. Dit geldt zowel voor de volgorde van
elementen in een resultaat als de volgorde van parameters. Dit betekent dat alle complexe
types de indicator <xs:all> gebruiken in plaats van <xs:sequence>. De volgorde van
elementen in een call kan in verschillende versies van ViewPoint veranderen. Je mag dus
niet afhankelijk zijn van deze volgorde. Door de uitzonderlijk slechte definitie van de XML
Schema 1.0 standaard betekent dit uitgangspunt dat XML schema's gemaakt via deze
standaards veelal niet correct de XML kunnen weergeven, dan wel dat ze weinig restricties
op elementen kunnen definiëren.
Voorbeelden van mogelijke (toegestane) aanpassingen in een resultaat:
Oud Nieuw
<woning> <woning>
<straatnaam>Fluitekruid</straatnaam> <straatnaam>Fluitekruid</straatnaam>
<plaatsnaam>Huizen</plaatsnaam> <plaatsnaam>Huizen</plaatsnaam>
<huisnummer>123</huisnummer> <postcode>1273XG</postcode>
</woning> <huisnummer>123</huisnummer>
</woning>
<registratie> <registratie>
<id>xgh43789526ghi-346hx</id> <id>xgh43789526ghi-346hx</id>
<hoofdaanvrager>523972569234763</hoofdaanv <hoofdaanvrager>523972569234763</hoofdaanv
rager> rager>
<partner>43562693475</partner> <partner>43562693475</partner>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 8 van 75
9. </registratie> <bestaande-woning>
<id>2346827</id>
<adres>Fluitekruid</adres>
</bestaande-woning>
</registratie>
Let op: extra entities kunnen voorkomen op ieder niveau binnen een structuur mits de structuur
zélf uit entities bestaat. Een entity als <plaatsnaam> die nu bestaat uit een enkele string zal
nooit veranderen in een entity met tekst plus onderliggende entities (oftewel: mixed=false zal
nooit veranderen in mixed=true).
Concreet betekent dit het volgende voor een derde die een interface gebruikt:
− Je mag een resultaat niet afkeuren omdat er een entity in staat die je niet kent. Je moet de
extra entity negeren.
− Je mag een resultaat niet afkeuren omdat er een attribute op zit die je niet kent (ignore).
− Je mag ieder gedefinieerd element volledig controleren zonder verdere restricties, met
uitzondering van element-volgorde.
Dit betekent dat de “schema's” voor de calls in iedere definitie eindigen met <xs:any/>, en dat
elk element <xs:anyAttribute> bevat3. Het betekent ook niet dat geen controle mogelijk is; alle
werkelijk gebruikte elementen mogen in een eigen schema worden opgenomen en gevalideerd.
Gezien bovenstaande eisen beperkt de validatie zich dan tot elementtypes, domeinrestricties
enz; restricties op bijv. minOccurs en maxOccurs zijn technisch niet mogelijk.
2.8. Message formaat van SOAP calls
De Itris SOAP calls moeten worden gedaan in het Doc/Lit Wrapped soap messaging model. Dit
betekent dat een typische call er als volgt uitziet:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ih="http://xml.itris.nl/viewpoint/2009/01/29/soap-header">
<soap:Header>
<ih:soapuserid>xxxx</ih:soapuserid>
<ih:plainpasswd>yyyyy</ih:plainpasswd>
</soap:Header>
<soap:Body>
<v:getVPRelation xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:id>160019361</v:id>
</v:getVPRelation>
</soap:Body>
</soap:Envelope>
In het bericht wordt de naam van de call (getVPRelation) gespecificeerd, en het is deze naam
die wordt gebruikt voor het dispatchen van de call naar de juiste afhandeling. De SOAPAction
http header wordt door Itris niet gebruikt noch gevalideerd.
3 Doch slechts conceptueel, omdat een aantal restricties in XML Schema 1.0 het gebruik van
deze technisch vrijwel onmogelijk maakt als een flexibel/uitbreidbaar schema model gewenst
is (ambiguity restrictions).
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 9 van 75
10. Voor meer details over de verschillende SOAP messaging models zie bijvoorbeeld
http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/
2.9. Authenticatie voor het uitvoeren van ViewPoint calls
Het door Itris aangeboden koppelvlak bevat calls voor ieder mogelijk onderdeel van ViewPoint.
Omdat het niet de bedoeling is dat iedere derde meteen alle mogelijke calls kan uitvoeren op
het systeem van een klant, dient iedere gebruiker van een call zich te identificeren. Let op: het
gaat hier dus om authenticatie van de partij die de SOAP calls doet, niet de authenticatie van
een consument op een website!
Voordat de SOAP interface te gebruiken is dient een bedrijf dat er gebruik van wil maken een
SOAP account plus wachtwoord aan te vragen bij de beheerder van het ViewPoint systeem. Dit
account representeert daarna het bedrijf en de systeembeheerder van het ViewPoint systeem
kan daarna rechten voor de verschillende calls uitdelen aan dit bedrijf. Hierdoor is te allen tijde
duidelijk welke calls mogen worden uitgevoerd door welke derden.
Iedere call die wordt uitgevoerd dient de volledige accountgegevens te bevatten (account naam
en wachtwoord) in de SOAP:Header, als volgt:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ih="http://xml.itris.nl/2009/01/29/soap-header">
<soap:Header>
<ih:soapuserid>bedrijfX</ih:soapuserid>
<ih:plainpasswd>fl0rk3lbr3mm3lheim</ih:plainpasswd>
</soap:Header>
(rest van het bericht)
</soap:Envelope>
Omdat dit wachtwoord zichtbaar is in het bericht, is een veilige transmissiemethode een
voorwaarde.
De gegevens benodigd voor authenticatie moeten door de caller eenvoudig kunnen worden
aangepast.
Calls waarbij de authenticatie ontbreekt of waarbij de authenticatie mislukt resulteren in een
SOAP Fault.
2.10. Encoding van SOAP calls
Alle informatie in ViewPoint is opgeslagen in Unicode. Standaard en bij voorkeur worden SOAP
calls gedaan in UTF-8 encoding. De ViewPoint omgeving zal andere encodings accepteren
(mits ondersteund door ons platform). In principe zal het antwoord op een SOAP call worden
gedaan in dezelfde encoding als het verzoek.
De huidige (1.x) versie van de SOAP interface zal, wanneer een encoding wordt gebruikt
waarbij tekens in de uitvoer niet kunnen worden gerepresenteerd, deze tekens vervangen door
het bij de gebruikte encoding behorende “onbekend teken” karakter. In dit geval gaat dus
informatie verloren; dit wordt dan ook sterk afgeraden voor iedere gegevensset waar ook
updates worden teruggestuurd! In dat geval overschrijft iedere update de niet ondersteunde
tekens met “onbekend teken” characters, zelfs als de ontvangende set (waar het teken
oorspronkelijk vandaan kwam) de juiste waarde voor het teken bevat!
Een typische ViewPoint omgeving bevat naast alle ASCII tekens ook alle mogelijke tekens met
accenten en bedragtekens zoals de Euro. Als UTF-8 encoding niet mogelijk is dan is het beste
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 10 van 75
11. alternatief iso-8859-154. Niet standaard encodings zoals win1252 worden niet ondersteund. In
dit geval moet onze klant (de corporatie) akkoord gaan met het mogelijk verlies van bijzondere
tekens in gegevens die vanuit het remote systeem worden gewijzigd.
2.11. Target adres voor SOAP calls
Het target adres voor de SOAP calls bestaat uit een door Itris uitgegeven URL. Deze moet
eenvoudig te wijzigen zijn in het peer systeem en is voor iedere klant verschillend (omdat we
praten over verschillende systemen). De tekstuele representatie van deze URL is dus geen
deel van de interface en is niet constant. De URL zal onder andere verschillen voor een
productiesysteem of voor een testsysteem. Een voorbeeld van een target URL is:
http://hostnaam:poort/viewpoint/soap/LAEV?[optionele parameters]
De optionele parameters zijn meestal afwezig. In bijzondere gevallen kan het nodig zijn dat de
SOAP user ID als parameter wordt meegegeven. Dit is alleen nodig als blijkt dat de caller een
niet-standaard vorm van SOAP gebruikt waar uitzonderingen op de afhandeling gemaakt
moeten worden. De specificatie van welke uitzonderingen moeten worden gemaakt zijn namelijk
gekoppeld aan het soap user ID.
2.12. Foutafhandeling van SOAP calls.
We onderscheiden twee soorten fouten binnen de SOAP interface:
• Harde fouten
• Zachte fouten
2.12.1. Harde fouten
Harde fouten zijn alle systeemfouten en onverwachte fouten. Voorbeelden van harde fouten
zijn:
• De verbinding naar het andere systeem (Internet) is onderbroken.
• Het andere systeem antwoordt met een niet-SOAP http bericht (http error 500: Server error
met een text/html exception stacktrace).
• Het andere systeem antwoordt met een Fault van een niet gedefinieerd type.
• Het andere systeem rapporteert een fout in de validatie/structuur van de inkomende XML.
Als een call betrokken is in een interactief proces dan kan de fout aan de gebruiker worden
gepresenteerd als een systeemfout zodat de gebruiker zelf kan besluiten wanneer hij/zij het
proces opnieuw probeert. Dit is alleen geldig als de call geen deel is van een reeks calls die
samen een resultaat moeten bereiken (als het goed is komt dit überhaupt niet voor – alle calls
zijn zo veel mogelijk gebaseerd op het compleet uitvoeren van een complete transactie).
Als de harde fout optreedt binnen een automatisch proces (zoals het proces dat de twee
databases up-to-date houdt) dan is het van primair belang dat mislukken van de call niet tot
problemen leidt! Als een “update” verzoek mislukt en niet wordt herhaald dan lopen de
databases uit elkaar zonder dat dit wordt geconstateerd.
Afhankelijk van het type van de harde fout kan een mislukte call worden “bewaard” en later
opnieuw worden uitgevoerd, handmatig of automatisch. Dit kan bijvoorbeeld door de call in een
4 Dus niet iso-8859-1; deze encoding bevat geen Euro teken en dat wordt binnen ViewPoint
veel gebruikt.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 11 van 75
12. database op te slaan en de gebruiker de mogelijkheid te geven om eventueel de gegevens aan
te passen en de call opnieuw te proberen.
Binnen ViewPoint worden belangrijke calls opgeslagen in de “Pending Operation Queue”. Deze
zorgt ervoor dat calls, indien mogelijk, op de juiste manier herhaald worden verzonden. Als een
call blijft mislukken dan is handmatig ingrijpen vereist. De status van de Pending Operation
Queue kan in ViewPoint worden bekeken middels het scherm Beheer → Beheren van
uitgestelde bewerkingenqueue.
Een harde fout wordt gemeld als een reguliere SOAP Fault. Een voorbeeld is:
<A:Envelope xmlns:A="http://schemas.xmlsoap.org/soap/envelope/">
<A:Body>
<A:Fault>
<A:faultcode>Server.unexpectedException</A:faultcode>
<A:faultstring>No row with the given identifier exists</A:faultstring>
<A:faultactor></A:faultactor>
<A:detail>org.hibernate.ObjectNotFoundException: No row with the given identifier
exists: [nl.itris.viewpoint.db.crm.Relation#12342341000034] at
org.hibernate.impl.SessionFactoryImpl$1.handleEntityNotFound(SessionFactoryImpl.java:379
)at
org.hibernate.proxy.AbstractLazyInitializer.checkTargetState(AbstractLazyInitializer.jav
a:79)</A:detail>
</A:Fault>
</A:Body>
</A:Envelope>
In alle gevallen waarin een uniek numeriek ID invoerveld/parameter niet kan worden gekoppeld
aan een bestaand record resulteert dit in een harde fout. De rationele is dat het client systeem
dit ID ooit van de SOAP server of via een batch-aanlevering heeft gekregen en dat deze
waardes onveranderlijk zijn en niet uit de ViewPoint database verwijderd worden, met name
waar het relaties, objecten, contracten e.d. betreft. Het niet (meer) kunnen vinden van deze ID’s
duidt op een ernstige fout.
2.12.2. Zachte fouten
Zachte fouten zijn in de definitie van een call gespecificeerde mogelijke foutsituaties. Deze
fouten kunnen door de aanroepende partij worden gebruikt om het gedrag van de applicatie te
bepalen: het belangrijkste kenmerk van een zachte fout is dat de aanroeper in staat moet zijn
om gepaste actie te ondernemen en zo nodig de call opnieuw te plaatsen met gewijzigde
parameters.
Typische voorbeelden zijn validatiefouten door ontbrekende, onvolledige of onjuiste gegevens in
aanroepparameters: bijvoorbeeld een ongeldig burgerservicenummer, letters in een numeriek
veld, lege verplichte velden, etc.
Een zachte fout wordt als volgt gerapporteerd middels een RejectedRequest element:
<B:getSomeFunctionResponse>
<RejectedRequest>
<Items>
<Item>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 12 van 75
13. <Field>SocialSecurityNr</Field>
<OriginalValue>00001</OriginalValue>
<FaultCode>socialSecurityNumberNotFound</FaultCode>
<FaultDescription>Ongeldig BSN</FaultDescription>
</Item>
<Item>
<Field>DateOfBirth</Field>
<OriginalValue>10-10-1830</OriginalValue>
<FaultCode></FaultCode>
<FaultDescription>Geboortedatum te ver in het verleden</FaultDescription>
</Item>
</Items>
</RejectedRequest>
</B:getSomeFunctionResponse>
Bovenstaand informatieobject bevat ten minste een Item element met details over de
geconstateerde fout:
Naam Type Omschrijving
Field String (opt) Indien te bepalen: het pad naar veldnaam binnen de input
XML waar de fout is gevonden.
OriginalValue String (opt) Indien te bepalen: de originele invoerwaarde.
FaultCode String De code van de fout. Deze code kan worden gebruikt om
besluiten te nemen over het afhandelen van de fout.
FaultDescription String Een tekstuele beschrijving van de fout, voor
presentatiedoeleinden. Deze tekst mag alleen getoond
worden; het is niet de bedoeling dat op de inhoud van de
tekst besluiten genomen worden – gebruik daar de
FaultCode voor.
De met (opt) gemarkeerde velden komen niet in ieder bericht voor. De FaultDescription en
FaultCode zijn wel altijd aanwezig en gevuld.
De SOAP server zal normaliter bij het constateren van een zachte fout onmiddellijk retourneren.
Client-systemen mogen daarom geen aannames doen dat een RejectedRequest element een
complete lijst van alle (validatie) fouten bevat. In bovenstaand voorbeeld zou dan alleen het
eerste Item worden geretourneerd, omdat de server aan validatie van de geboortedatum niet
meer toe zou komen. Voor een nette afhandeling van fouten op de website blijft het daarom de
verantwoordelijkheid van het cliënt systeem om data voor aanroep te valideren op basale
kenmerken zoals verplicht/niet verplicht en de juiste inhoud (numeriek, alfanumeriek, maximale
lengte).
Een lijst met de meest voorkomende foutcodes voor zachte fouten is in Appendix A toegevoegd.
2.13. Media “bestanden” in calls
Binnen ViewPoint zijn allerlei media bestanden aanwezig die voor verschillende gegevens
kunnen worden opgevraagd. Het gaat dan om veelal grote, binaire bestanden die PDF's, foto's,
MS/Word documenten enz. bevatten. De inhoud van deze bestanden wordt nooit in XML
teruggegeven omdat daardoor de XML bestanden extreem groot zouden worden. Verder zorgt
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 13 van 75
14. de grote hoeveelheid data voor sommige calls voor problemen met de performance van de
koppeling als bestanden telkens weer worden opgevraagd. Om deze reden bevat de ViewPoint
koppeling een algemeen mechanisme voor het effectief opvragen van deze bestanden zodat ze
op het peer systeem kunnen worden gecached. Het implementeren van deze caching is
verplicht voor ieder systeem wat de bestanden presenteert aan consumenten.
Performance-problemen die worden veroorzaakt doordat deze Media bestanden niet worden
gecached zijn ter verantwoording van de bouwer van de koppeling, en zullen niet door Itris
worden opgelost.
Wanneer een object een of meer media bestanden bevat dan wordt ieder “bestand” altijd
weergegeven als een Media object, als volgt:
<itrs:Media xmlns:itrs="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<itrs:ID>xagnilas:160000428</itrs:ID>
<itrs:Description>plattegrond 2</itrs:Description>
<itrs:Mimetype>image/gif</itrs:Mimetype>
<itrs:Type>????</itrs:Type>
<itrs:Size>721193</itrs:Size>
<itrs:Hash>67f19641bf825238d5277b7801dd366b<itrs:Hash>
<itrs:Url>http://itris25.itris.nl/xawv/info?id=160000428.gif</itrs:Url>
<itrs:PixelWidth>575</itrs:PixelWidth>
<itrs:PixelHeight>575</itrs:PixelHeight>
</itrs:Media>
De betekenis van de velden is als volgt:
Naam Type O/V Omschrijving
ID String[128] V Een unieke sleutel voor dit bestand. Toekomstige referenties
naar hetzelfde bestand gebruiken exact hetzelfde ID. Het ID
is een string maar kan alleen uit cijfers bestaan. Het ID is
uniek over alle bestanden op hetzelfde systeem; duplicaten
kunnen wel optreden wanneer gegevens van meerdere VP
systemen worden gecombineerd.
Description String[128] O Een tekstuele beschrijving van de inhoud.
Mimetype String[50] V Het MIME type van het aangeleverde bestand.
Type ? ? ?
Size int V De grootte, in bytes, van het bestand.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 14 van 75
15. Hash String[32] V De MD5 hash berekend over de inhoud in bytes van het
bestand.
Url String[256] V Een URL waarmee de inhoud van het bestand kan worden
opgevraagd, normaliter als http: verzoek aan de server.
PixelHeight int O Indien het bestand een bitmap image (GIF, PNG, JPEG)
bestand is dan bevat dit de hoogte van het plaatje in pixels.
PixelWidth int O Indien het bestand een bitmap image (GIF, PNG, JPEG)
bestand is dan bevat dit de breedte van het plaatje in pixels.
Mimetype, pixelwidth en pixelheight worden gebruikt voor het op de juiste manier tonen van
plaatjes. Als een plaatje een bitmap is (te zien aan het mime type) dan kunnen pixelwidth en
pixelheight worden gebruikt om de aspect ratio5 van een plaatje te berekenen; deze aspect ratio
is dan weer belangrijk voor een juiste berekening van alternatieve grootten voor het plaatje
(bijvoorbeeld voor tonen als thumbnail). Bijvoorbeeld: in het Media record staat dat de grootte
van het plaatje 800x600 pixels is. Om dit te verkleinen naar een thumbnail die past in 200x200
pixels is de aspect ratio (hier 4:3) nodig om te voorkomen dat het plaatje in lengte of breedte
wordt “uitgerekt”. De juiste grootte voor de thumbnail is dan 200x150. Het is vaak belangrijk de
nieuwe grootte van het resized plaatje te weten voordat de “inhoud” wordt opgevraagd 6.
In deze media structuur is het bestand (de inhoud) zelf niet aanwezig. In plaats daarvan is een
URL aanwezig waarmee die inhoud kan worden opgevraagd wanneer nodig. Let op: de URL
moet gezien worden als “opaque” verwijzing naar het medium; de inhoud en opbouw van de
URL kan gewijzigd worden zonder dat dit de werking mag verstoren. Dit betekent dat de
ontvanger de URL niet mag “decoderen” of aanpassen. In een aantal gevallen kan het URL veld
ook iets anders bevatten als een “echte” URL; bijvoorbeeld in bulk bestanden (later beschreven)
voor een initiële load van een systeem bevat het URL veld een relatieve bestandsnaam naar
een bestand binnen de dump-directory. Het datatype is dus “string”, niet “URL”.
De combinatie van ID en Hash wordt gebruikt om caching voor images te regelen. Dit
mechanisme moet worden geïmplementeerd. Het mechanisme werkt als volgt:
• Het peer systeem slaat de inhoud van de bestanden lokaal op. Naast de inhoud wordt in
ieder geval ook de Hash en het ID opgeslagen. De gegevens moeten snel kunnen worden
opgezocht met het ID als sleutel.
• Wanneer gegevens met een Media set worden opgevraagd dan levert ViewPoint de laatste
stand van deze gegevens aan.
• Het peer systeem kijkt eerst of het door ViewPoint aangeleverde ID al bestaat in de eigen
cache. Als dit niet het geval is dan vraagt het peer systeem de inhoud van het bestand op
door de URL te openen en de datastroom te lezen. Daarna wordt deze data opgeslagen
onder het betreffende ID en inclusief de in het Media bestand aanwezige Hash. Nu is de
media lokaal te benaderen zonder het ViewPoint systeem te raadplegen.
• Als het bestand al aanwezig is dan wordt de Hash in het ViewPoint bericht vergeleken met
de Hash die locaal is opgeslagen voor het bestand. Als de Hashes verschillen dan is de
ViewPoint versie van het bestand gewijzigd en moet het peer systeem een nieuwe versie
ophalen via de URL. Deze versie wordt daarna met de nieuwe Hash locaal opgeslagen en
5 De verhouding tussen lengte en breedte
6 Bijvoorbeeld bij presenteren in HTML moet de grootte van het plaatje in het HTML document
worden gemeld, terwijl in een heel ander request naar de server de inhoud later wordt
opgevraagd.
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 15 van 75
16. gebruikt.
Op deze manier worden grote media bestanden alleen opnieuw opgevraagd als ze zijn
aangepast, en wordt de performance van het complete systeem niet nadelig beïnvloed door
grote data transfers tijdens de communicatie.
De reden voor caching is dat veel basale processen voor consumenten heel veel media nodig
hebben. Bijvoorbeeld het tonen van het beschikbare woningaanbod levert iedere keer voor
iedere woning meerdere grote bestanden op, die ook nog mogelijk moeten worden geresized
als “thumbnail” tijdens presenteren.
Media bestanden kunnen ook worden aangeleverd als onderdeel van een initiële dump. Op
deze manier kan het initieel vullen van een website-database snel plaatsvinden zonder dat
gigabytes aan dataverkeer nodig is.
2.14. Caching voor opgevraagde gegevens
Er is een (klein) aantal calls waarbij de maximale frequentie van uitvoeren van de call is
gelimiteerd. Dit is gedaan omdat de call grote gevolgen heeft voor de performance van het
totale systeem. Een voorbeeld is de call voor het opvragen van het hele woningaanbod: voor
een gemiddelde klant kan het antwoord op deze call bestaan uit tientallen megabytes aan
gegevens. Als deze call voor iedere consument telkens weer moet worden uitgevoerd dan is het
resultaat dat de performance dramatisch slecht is: de hoeveelheid tijd voor het opvragen van
deze hoeveelheid gegevens over een relatief trage verbinding is vele seconden. Als meerdere
personen gelijktijdig deze set opvragen dan is de vertraging nog veel langer. Dit is niet
acceptabel.
Om deze reden moet het peer systeem het resultaat van een dergelijke call ook lokaal opslaan,
en een mechanisme implementeren om de gegevens up-to-date te houden door regelmatig te
verversen, of door een “push” mechanisme te accepteren waarbij wijzigingen aan individuele
objecten door het ViewPoint systeem op het moment van aanpassen worden doorgegeven.
Performance problemen die worden veroorzaakt door het niet implementeren van caching voor
deze calls komen ter verantwoording voor de implementator en zullen door Itris niet (kunnen!)
worden opgelost.
2.14.1. Verversen via “timeout”
De meest eenvoudige methode voor het verversen van deze lokaal opgeslagen informatie is om
een “refresh interval” af te spreken. Bijvoorbeeld dat de gegevens maximaal een (1) uur oud
zijn; dit betekent dat ze ieder uur opnieuw moeten worden opgevraagd. Dit kan dan worden
geregeld door een achtergrondproces. Vaak wordt dit ook gedaan tijdens het opvragen van de
gegevens door een willekeurige gebruiker, door op dat moment te kijken of de gegevens
ververst moeten worden en ze op dat moment dan ook meteen op te vragen indien nodig. Dit is
echter onverstandig gezien de lange data-transfer tijd voor de gegevens: het betekent dat deze
ongelukkige gebruiker plotseling meerdere seconden moet wachten op zijn antwoord.
2.14.2. Verversen van gegevens door middel van events (Pushes)
Een alternatief voor het up-to-date houden van grote gegevensverzamelingen is gebruik maken
van events. In dit geval wordt het peer systeem initieel voorzien van een “dump” van de
gegevens binnen ViewPoint. Daarna zal ViewPoint voor ieder object wat wordt aangepast
binnen ViewPoint een SOAP call doen náár het peer systeem. Deze call noemen we een push,
en bevat alle aangepaste gegevens van het gewijzigde object. Het peer systeem gebruikt
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 16 van 75
17. daarna de aangepaste gegevens om zijn eigen, locale kopie aan te passen.
Dit mechanisme is relatief eenvoudig te implementeren als de gegevensverzameling alleen
wijzigt aan de ViewPoint zijde en niet aan de kant van de peer. Gegevensverzamelingen die wel
aan beide kanten kunnen wijzigen (bijvoorbeeld inschrijvingen, persoonsgegevens) zijn
moeilijker te implementeren via dit mechanisme.
2.15. Representatie van Null velden, xsi:nil
Velden zonder inhoud (NULL velden) worden in de huidige versie van de SOAP omgeving (1.x)
gerepresenteerd door het element zonder inhoud. Voorbeelden:
<address>
<houseNumber></houseNumber>
<streetName/>
In beide gevallen moet de inhoud van het veld gezien worden als NULL. Omdat deze definitie
feitelijk onjuist is volgens de XML Schema definities zal de volgende versie (2.x) van de
interface gebruik maken van xsi:nil=”true” (in de XMLSchema-instance namespace) op alle
elementen die werkelijk null representeren, en zal het lege element overeenkomen met de lege
string. Het verdient aanbeveling om te zorgen dat code hier nu al rekening mee houdt. De
nieuwe versie zal de bovenstaande elementen representeren als:
<address xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
<houseNumber xsi:nil=”true”></houseNumber>
<streetName xsi:nil=”true”/>
2.16. Gedrag van updatende calls
Diverse calls wijzigen informatie in de database aan de hand van de aangeboden gegevensset.
Voor het aanpassen van gegevens zijn een aantal regels rond ontbrekende elementen, “leeg”
zijn van elementen (nullity) enz.
De voor een update call aangeleverde gegevens in een set (bijv. persoonsgegevens) zal
doorgaans kleiner zijn dan wat in de database voor deze persoon is opgeslagen. Het
standaardgedrag van alle calls is dat niet aangeleverde elementen worden genegeerd: ze
behouden in de database hun oude waarde. We noemen dit “Partial updateability”.
Alleen de in de update genoemde elementen worden aangepast: hun waarde wordt aangepast
of op NULL gezet als de inhoud van het element nil is. Dus een ontbrekend element in een
update betekent niet dat het gegeven NULL is!
Bij het valideren van een update worden wel alle benodigde gegevens gebruikt, ook als ze niet
aanwezig zijn in de update. Gegevens die nodig zijn voor validatie/controle die niet aanwezig
zijn in het update bericht behouden hun oude waarde, en dus wordt deze waarde gebruikt in de
validatie. Als dan een combinatie van deze waarden ongeldig is dan wordt de update
geweigerd.
Een ander voorbeeld is het aanpassen van naamsgegevens. De volledige naam is verspreid
over meerdere velden (initialen, achternaam-prefix, achternaam) die samen de volledige naam
vormen. Bij de update moeten de aangepaste velden worden genoemd ook als ze leeg
gemaakt worden door de update. Bijvoorbeeld: mevrouw “A. de Boer” neemt de achternaam
van haar echtgenoot (Jansen) over. Enkel aanleveren van een nieuwe achternaam is
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 17 van 75
18. onvoldoende, omdat er dan A. de Jansen zou staan. De “Prefix” van de achternaam moet ook in
het update bericht zitten met een lege waarde zodat de oude waarde “de” verandert in NULL.
Uitzonderingen:
Bij adreswijziging moet het volledige adres (straat, huisnummer, toevoeging, postcode,
plaatsnaam) worden aangeleverd. Bij verhuizing van nummer 7a naar 9 zal de
huisnummertoevoeging altijd op NULL gezet worden, tenzij aangeleverd. Wijzigen van de
postcode zonder nieuwe adresgegevens is dus ook niet toegestaan.
Enkele voorbeelden:
Een volledig gevuld Address element:
<Address>
<Type>CORADR</Type>
<Street>Kadoelenweg</Street>
<HouseNumber>358</HouseNumber>
<HouseNumberSuffix></HouseNumberSuffix>
<Postcode>5941 ED</Postcode>
<City>Amsterdam</City>
<Country>Nederland</Country>
</Address>
Optioneel veld HouseNumberSuffix ontbreekt en zal op NULL worden gezet:
<Address>
<Type>CORADR</Type>
<Street>Kadoelenweg</Street>
<HouseNumber>358</HouseNumber>
<Postcode>5941 ED</Postcode>
<City>Amsterdam</City>
<Country>Nederland</Country>
</Address>
Fout: postcode ontbreekt:
<Address>
<Street>Kadoelenweg</Street>
<HouseNumber>358</HouseNumber>
<City>Amsterdam</ City>
<Country>Nederland</ Country>
</Address>
2.17. Klant specifiek datatypes
Datum : XMLDATE
Integer : NUMBER
Bedragen : NUMBER
Media : BLOB
Default : CHARACTER
2.18. Formulier inschrijving
Elk entry bestaat uit
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 18 van 75
19. Field : Uniek field code / technische naam
Deze naam wordt ingesteld binnen ViewPoint.
Value(s) : : Waarde / Lijst van waarden
Datatype : Type
2.19. Voorbeeld
<v:RegistrationForm>
<v:Form>dsnRegistration</v:Form>
<v:EntryList>
<v:Entry>
<v:Field>inschrijfBevestiging</v:Field>
<v:Value>Ja</v:Value>
<v:DataType>CHARACTER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>correspondentieViaEmail</v:Field>
<v:Value>Ja</v:Value>
<v:DataType>CHARACTER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>grootteHuishouding</v:Field>
<v:Value>5</v:Value>
<v:DataType>NUMBER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>huidigeWoonsituatie</v:Field>
<v:Value>Huur</v:Value>
<v:DataType>CHARACTER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>brutoMaandInkomen</v:Field>
<v:Value>3.333</v:Value>
<v:DataType>NUMBER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>brutoMaandInkomenPartner</v:Field>
<v:Value>2.222</v:Value>
<v:DataType>NUMBER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>brutoMaandInkomenTotaal</v:Field>
<v:Value>5.555</v:Value>
<v:DataType>NUMBER</v:DataType>
</v:Entry>
<v:Entry>
<v:Field>woonwensen</v:Field>
<v:Value>Woonwensen memo veld</v:Value>
<v:DataType>CHARACTER</v:DataType>
</v:Entry>
</v:EntryList>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 19 van 75
20. 3. Specificatie calls ViewPoint SOAP server
3.1. Authenticeren publieke gebruiker
NAAM : Authenticeren publieke gebruiker
PARAMETERS: userid : String - Aan de eindgebruiker toegekende gebruikersnaam
password : String - Aan de eindgebruiker toegekend wachtwoord.
OUTPUT: {VP}Relation
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.authenticatiePublicUser
SOAP: authenticatePublicUser
OMSCHRIJVING: Zoekt een relatie (persoon of bedrijf) waarvan de publieke gebruikersnaam en
wachtwoord overeenkomen met de opgegeven details. Zal gebruikt worden bij
websitekoppelingen om de inloggegevens van een gebruiker te controleren op
geldigheid. Het geretourneerde element is gelijk aan de call getVPRelation met
alle ‘include’ parameters op false, dus zonder adressen, bankgegevens,
contracten of saldi.
CHECKS: Userid en password moeten overeenkomen met de corresponderende waardes
in ViewPoint.
FOUTMELDINGEN: Foutdocument met melding Public user ID or password incorrect
REFERENTIES:
3.1.1. Input XML - authenticatePublicUser
<v:authenticatePublicUser
xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/
viewpoint">
<v:userid>BEUKERS</v:userid>
<v:password>srekueb</v:password>
</v:authenticatePublicUser>
3.1.2. Output XML - authenticatePublicUserResponse
<B:authenticatePublicUserResponse>
<B:Company>
<B:ID>160036545</B:ID>
<B:Role>Crediteur</B:Role>
<B:CompanyName>Netvlies</B:CompanyName>
</B:Company>
</B:authenticatePublicUserResponse>
Of
<B:authenticatePublicUserResponse>
<B:Person>
<B:ID>160015585</B:ID>
<B:Role>Debiteur</B:Role>
<B:Initials>H.H.E.</B:Initials>
<B:SurnamePrefix></B:SurnamePrefix>
<B:Surname>Beukers</B:Surname>
<B:HomePhone>013613642742</B:HomePhone>
<B:MobilePhone>0612345678</B:MobilePhone>
<B:WorkPhone>0426967816</B:WorkPhone>
<B:Email>adebeuker@itris.nl</B:Email>
<B:Gender>man</B:Gender>
<B:DateOfBirth>19810901</B:DateOfBirth>
<B:SocialSecurityNr>256646399</B:SocialSecurityNr>
<B:MaritalStatus></B:MaritalStatus>
</B:Person>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 20 van 75
21. </B:authenticatePublicUserResponse>
3.2. Control bij het verzoek voor wijzigen wachtwoord
NAAM : Verzoek wijzigen wachtwoord
PARAMETERS: emailAddress : String – Email adres van de eindgebruiker
socialSecurityNumber : Integer – BSN van de eindgebruiker
OUTPUT: Long RelationId
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.verifyEmailForPasswordChangeRequest
SOAP: verifyEmailForPasswordChangeRequest
OMSCHRIJVING: Controleert of er een persoon bestaat binnen viewpoint met de aangegeven
email adres en bsn nummer, eventueel ook de geboortedatum.
CHECKS: Email adres bestaat in combinatie met bsn nummer, eventueel ook
geboortedatum.
FOUTMELDINGEN:
BSN niet gevonden
<B:RejectedRequest>
<B:Items>
<B:Item>
<B:OriginalValue>250432868</B:OriginalValue>
<B:FaultCode>socialSecurityNumberNotFound</B:FaultCode>
<B:FaultDescription>Geen hoofdaanvrager aanwezig met bsn:
250432868.
</B:FaultDescription>
</B:Item>
</B:Items>
</B:RejectedRequest>
Email adres niet gevonden
<B:RejectedRequest>
<B:Items>
<B:Item>
<B:OriginalValue>jo.ston@itris.nl</B:OriginalValue>
<B:FaultCode>emailAddressNotFound</B:FaultCode>
<B:FaultDescription>
Geen hoofdaanvrager aanwezig met email: jo.ston@itris.nl.
</B:FaultDescription>
</B:Item>
</B:Items>
</B:RejectedRequest>
REFERENTIES:
3.2.1. Input XML - verifyEmailForPasswordChangeRequest
<v:verifyEmailForPasswordChangeRequest
xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:emailAddress>jo.seaton@itris.nl</v:emailAddress>
<v:socialSecurityNumber>250452868</v:socialSecurityNumber>
</v:verifyEmailForPasswordChangeRequest>
3.2.2. Input XML - verifyEmailForPasswordChangeRequestResponse
<B:verifyEmailForPasswordChangeRequestResponse>
160036871
</B:verifyEmailForPasswordChangeRequestResponse>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 21 van 75
22. 3.3. Wijzigen public password
NAAM : Wijzigen wachtwoord
PARAMETERS: relationId : Long – Id van de {VP}Relation
OUTPUT: String - bericht
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.changePasswordWebCredentials
SOAP: changePasswordWebCredentials
OMSCHRIJVING: Wijzigt de wachtwoord van de aangegeven relatie
CHECKS: Relation moet wel bestaan – zo niet wordt een harde fout geretourneert
FOUTMELDINGEN:
Email adres niet gevonden
<B:RejectedRequest>
<B:Items>
<B:Item>
<B:OriginalValue>jo.ston@itris.nl</B:OriginalValue>
<B:FaultCode>emailAddressNotFound</B:FaultCode>
<B:FaultDescription>
Geen hoofdaanvrager aanwezig met email: jo.ston@itris.nl
</B:FaultDescription>
</B:Item>
</B:Items>
</B:RejectedRequest>
REFERENTIES:
3.3.1. Input XML - changePasswordWebCredentials
<v:changePasswordWebCredentials
xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:relationId>160036871</v:relationId>
</v:changePasswordWebCredentials>
3.3.2. Input XML - changePasswordWebCredentialsResponse
<B:changePasswordWebCredentialsResponse>
Wachtwoord gewijzigd nieuwe wachtwoord is naar relatie gemaild
</B:changePasswordWebCredentialsResponse
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 22 van 75
23. 4. Relaties
4.1. Aanmaken nieuw persoon in ViewPoint
NAAM : Maakt een nieuw record voor een persoon
PARAMETERS: Person – {VP}/Person - Person element
OUTPUT: {VP}Person
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.createPerson
SOAP: Deze call maakt een nieuw record aan voor een ViewPoint persoon en
retourneert dezelfde XML structuur met toegevoegde Ids
OMSCHRIJVING: Het aangeleverde persoonselement mag geen ID bevatten
CHECKS:
FOUTMELDINGEN: Field: ID, OriginalValue: <12345>, FaultCode: INPUT, Faultdescription: ID
should be empty.
REFERENTIES:
4.1.1. Input XML - createPerson
<v:createPerson xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<Person xmlns="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<Role>Crediteur</Role>
<AddressList>
<Address>
<Type>CORADR</Type>
<Street>Sparrenlaan</Street>
<HouseNumber>6</HouseNumber>
<Postcode>5941 ED</Postcode>
<City>Velden</City>
<Municipality>Velden</Municipality>
<Country>Nederland</Country>
</Address>
</AddressList>
<BankAccountList>
<BankAccount>
<Type>B</Type>
<Preferred>false</Preferred>
<AccountNumber>476967996</AccountNumber>
</BankAccount>
<BankAccount>
<Type>G</Type>
<Preferred>true</Preferred>
<AccountNumber>12345</AccountNumber>
</BankAccount>
</BankAccountList>
<CapacityList>
<Capacity>
<Description>MAKELAAR</Description>
<StartDate>19690507</StartDate>
<EndDate>20100507</EndDate>
</Capacity>
</CapacityList>
<ContractList/>
<InvoiceList/>
<RequestsForRepairList/>
<Initials>H</Initials>
<SurnamePrefix>de</SurnamePrefix>
<Surname>Kooten</Surname>
<HomePhone>02011112222</HomePhone>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 23 van 75
25. 4.2. Tonen klantgegevens
NAAM : Tonen klantgegevens met contracten en saldi.
PARAMETERS: relId : Long - Id van ViewPoint relatie
includeAddresses : Boolean - Indien “true”, exporteer adressen van relatie in
{VP}[Person|Company]/AddressList/Address*
includeBankAccounts : Boolean - Indien “true”, exporteer bankgegevens van
relatie in {VP} [Person|Company]/BankAccountList/BankAccount*
includeCapacities : Boolean - Indien “true”, exporteer hoedanigheden van
relatie in {VP} [Person|Company]/CapacityList/Capacity*
includeContracts : Boolean - Indien “true”, exporteer contracten van relatie in
{VP} [Person|Company]/ContractList/Contract*
includeInvoices : Boolean - Indien “true”, exporteer saldi van relatie in
{VP} [Person|Company]/InvoiceList/Invoice*
OUTPUT: {VP}[Person|Company]
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.getVPRelation
SOAP: getVPRelation
OMSCHRIJVING: Deze call exporteert gegevens direct gekoppeld aan een ViewPoint relatie.
Naamgegevens zijn altijd aanwezig. Adres-, bank-, contract-, saldogegevens en
hoedanigheden (bijv. huismeester, aannemer) zijn optioneel.
CHECKS: Het ID moet verwijzen naar een bestaande relatie in ViewPoint.
FOUTMELDINGEN: Indien ID niet verwijst naar een bestaande relatie wordt er een record.not.found
foutcode geretourneerd.
REFERENTIES:
4.2.1. Input XML - getVPRelation
<v:getVPRelation xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:relId>1100045493</v:relId>
<v:includeAddresses>true</v:includeAddresses>
<v:includeBankAccounts>true</v:includeBankAccounts>
<v:includeCapacities>true</v:includeCapacities>
<v:includeContracts>true</v:includeContracts>
<v:includeInvoices>true</v:includeInvoices>
</v:getVPRelation>
4.2.2. Output XML - getVPRelationResponse
<B:getVPRelationResponse>
<B:Person>
<B:ID>1100045493</B:ID>
<B:Role>Debiteur</B:Role>
<B:AddressList>
<B:Address>
<B:Type>CORADR</B:Type>
<B:ID>1100067674</B:ID>
<B:Street>Poorthofsweg</B:Street>
<B:HouseNumber>22</B:HouseNumber>
<B:Postcode>3246 CG</B:Postcode>
<B:Municipality>DIRKSLAND</B:Municipality>
<B:City>DIRKSLAND</B:City>
<B:Country>Nederland</B:Country>
<B:StartDate>19000101</B:StartDate>
</B:Address>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 25 van 75
27. <B:Country>Nederland</B:Country>
<B:StartDate>19000101</B:StartDate>
</B:Address>
<B:Type>MEDEBEWONER</B:Type>
</B:Contractee>
</B:ContracteeList>
<B:BankAccountList/>
<B:PaymentTermsList>
<B:PaymentTerms>
<B:StartDate>19991201T00:00:00+01:00</B:StartDate>
<B:PaymentMethod>HANDMATIG</B:PaymentMethod>
<B:PrintingMethod>GEEN</B:PrintingMethod>
<B:AccountNumber>2656702</B:AccountNumber>
</B:PaymentTerms>
</B:PaymentTermsList>
</B:Contract>
</B:ContractList>
<B:InvoiceList/>
<B:RequestsForRepairList/>
<B:Initials>E.</B:Initials>
<B:Surname>Hulzebos</B:Surname>
<B:DateOfBirth>19751031</B:DateOfBirth>
</B:Person>
</B:getVPRelationResponse>
4.3. Bijwerken relatiegegevens met adressen
NAAM : Aanpassen persoonsgegevens met adressen
PARAMETERS: Person – {VP}/Person – Person element
OUTPUT: {VP}Relation
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.updatePerson
nl.itris.soap.calls.crm.SoapCrmCalls.updateCompany
SOAP: getVPRelation
OMSCHRIJVING: Deze call exporteert gegevens direct gekoppeld aan een ViewPoint relatie.
Naamgegevens zijn altijd aanwezig. Adres-, bank-, contract-, saldogegevens en
hoedanigheden (bijv. huismeester, aannemer) zijn optioneel.
CHECKS: Het ID moet verwijzen naar een bestaande relatie in ViewPoint.
FOUTMELDINGEN: Indien ID niet verwijst naar een bestaande relatie: Relation with id <id> does
not exist.
REFERENTIES:
4.3.1. Input XML - updatePerson
<v:updatePerson xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<Person xmlns="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<ID>160022012</ID>
<AddressList>
<Address>
<Type>CORADR</Type>
<ID>160037881</ID>
<Street>Rhijnspoor</Street>
<HouseNumber>243</HouseNumber>
<HouseNumberSuffix>245</HouseNumberSuffix>
<Postcode>2901 LB</Postcode>
<Municipality>CAPELLE AAN DEN IJSSEL</Municipality>
<City>CAPELLE AAN DEN IJSSEL</City>
<Country>Nederland</Country>
</Address>
</AddressList>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 27 van 75
28. <BankAccountList />
<CapacityList>
<Capacity>
<Description>MEDEWERKER</Description>
<StartDate>20050101</StartDate>
</Capacity>
</CapacityList>
<ContractList />
<Invoices />
<RequestsForRepairList />
<SurnamePrefix>dé</SurnamePrefix>
<Surname>Business Consultant</Surname>
<HomePhone>01012341234</HomePhone>
<MobilePhone>0612341234</MobilePhone>
<WorkPhone>01012341234</WorkPhone>
<Email>itrisbusinessconsultant@itris.nl</Email>
</Person>
</v:updatePerson>
4.3.2. Output XML - updatePersonResponse
<B:updatePersonResponse />
4.4. Adressen opzoeken via postcode
NAAM : Adressen opzoeken via postcode
PARAMETERS: zipcode String postcode
houseNumber String housenummer [optioneel]
houseSuffix String housesuffix [optioneel]
OUTPUT: SoapAddress
CALL: nl.itris.soap.calls.crm.SoapCrmCalls.lookupAddressViaZipcode
SOAP: lookupAddressViaZipcode
OMSCHRIJVING: Deze call zoekt een adres gebaseerd op de opgegeven postcode, als eventueel
housenummer en suffix worden meegegeven worden deze ook gecontroleerd.
CHECKS: Het zipcode moet verwijzen naar een geldig adres
FOUTMELDINGEN:
Ongeldige postcode
<B:RejectedRequest>
<B:Items>
<B:Item>
<B:OriginalValue>8231 XE</B:OriginalValue>
<B:FaultCode>invalidPostCode</B:FaultCode>
<B:FaultDescription>Ongeldig postcode</B:FaultDescription>
</B:Item>
</B:Items>
</B:RejectedRequest>
Ongeldig huisnummer
<B:RejectedRequest>
<B:Items>
<B:Item>
<B:OriginalValue>1315</B:OriginalValue>
<B:FaultCode>invalidHouseNumber</B:FaultCode>
<B:FaultDescription>Ongeldig housenummer: 1315.</B:FaultDescription>
</B:Item>
</B:Items>
</B:RejectedRequest>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 28 van 75
30. 5. Objecten
5.1. Opvragen specificaties woningwaardering
NAAM : Opvragen specificaties woningwaardering
PARAMETERS: vpPropertyId – Long - Id van ViewPoint object
includeEvaluations – Boolean - Boolean vlag: indien true,
OUTPUT: {VP}Property/ PropertyEvaluationList/PropertyEvaluation*
CALL: nl.itris.soap.calls.crm.SoapBaeCalls.getVPProperty
SOAP: getVPProperty
OMSCHRIJVING: Selecteert een ViewPoint object (BAE_VHO.bot_id = vpPropertyId) en indien
includeEvaluations true is, ook alle records uit de view
V_INFO_WONINGWAARDERING.bot_id
CHECKS: vpPropertyId moet verwijzen naar een geldig bot_id in BAE_VHO
5.1.1. Input XML - getVPProperty
<v:getVPProperty xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:vpPropertyId>160011689</v:vpPropertyId>
<v:includeEvaluations>true</v:includeEvaluations>
</v:getVPProperty>
5.1.2. Output XML - getVPPropertyResponse
<B:getVPPropertyResponse>
<B:Property>
<B:ID>160011689</B:ID>
<B:Street>Kingsfordweg</B:Street>
<B:HouseNumber>85</B:HouseNumber>
<B:HouseNumberSuffix></B:HouseNumberSuffix>
<B:Postcode>1043 GP</B:Postcode>
<B:Municipality>AMSTERDAM</B:Municipality>
<B:City>AMSTERDAM</B:City>
<B:Country>Nederland</B:Country>
<B:Nickname>210291</B:Nickname>
<B:Description>21.0291</B:Description>
<B:PropertyEvaluationList>
<B:PropertyEvaluation>
<B:Section>Vertrekken</B:Section>
<B:Element>Woonkamer</B:Element>
<B:Value>21,14</B:Value>
<B:ValueSuffix>m?</B:ValueSuffix>
<B:Subjective>false</B:Subjective>
</B:PropertyEvaluation>
...
<B:PropertyEvaluation>
<B:Section>Centrale verwarming</B:Section>
<B:Element>Aantal verwarmde vertrekken</B:Element>
<B:Value>7</B:Value>
<B:Points>14.0</B:Points>
<B:Subjective>false</B:Subjective>
</B:PropertyEvaluation>
</B:PropertyEvaluationList>
</B:Property>
</B:getVPPropertyResponse>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 30 van 75
31. 5.2. Tonen woonbezit
NAAM : Tonen woonbezitgegevens van een enkel object
PARAMETERS: vpPropertyId – Long - Id van ViewPoint verhuurbaar object
OUTPUT: {VP}AvailablePropertyData
CALL: nl.itris.soap.calls.crm.SoapBaeCalls.getAvailablePropertyData
SOAP: getAvailablePropertyData
OMSCHRIJVING: Deze call exporteert een lijst van gegevens voor een enkel ViewPoint
verhuurbaar object
CHECKS: Het ID moet verwijzen naar een bestaand object in ViewPoint.
FOUTMELDINGEN: Indien ID niet verwijst naar een bestaande relatie is het responsdocument leeg:
<B:getAvailablePropertyDataResponse/>
REFERENTIES:
5.2.1. Input XML - getAvailablePropertyData
<v:getAvailablePropertyData
xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:vpPropertyId>160011676</v:vpPropertyId>
</v:getAvailablePropertyData>
5.2.2. Output XML - getAvailablePropertyDataResponse
<B:getAvailablePropertyDataResponse>
<B:AvailablePropertyData>
<B:PropertyId>160011676</B:PropertyId>
<B:PropertyDescription>21.0276</B:PropertyDescription>
<B:PropertySubtype>Woning</B:PropertySubtype>
<B:MainCluster>Woningcorporatie Itris</B:MainCluster>
<B:Complex>Complex 21.100</B:Complex>
<B:RentablePropertyType>eengezinswoning eind</B:RentablePropertyType>
<B:Address>
<B:Street>Zanzibarstraat</B:Street>
<B:HouseNumber>57</B:HouseNumber>
<B:HouseNumberSuffix></B:HouseNumberSuffix>
<B:Postcode>1339 RP</B:Postcode>
<B:Municipality>ALMERE</B:Municipality>
<B:City>ALMERE</B:City>
<B:Country>Nederland</B:Country>
<B:Type>CORADR</B:Type>
</B:Address>
<B:BwkArea>Wijk</B:BwkArea>
<B:Neighbourhood>5534</B:Neighbourhood>
<B:DefaultDeposit>0</B:DefaultDeposit>
<B:NumberOfBedRooms>3</B:NumberOfBedRooms>
<B:LotSquareMetres>55.38</B:LotSquareMetres>
<B:Kitchen>5,20</B:Kitchen>
<B:Garden>101,00</B:Garden>
<B:ConstructionYear>01011952</B:ConstructionYear>
<B:MediaList/>
</B:AvailablePropertyData>
</B:getAvailablePropertyDataResponse>
5.3. Tonen woonaanbod
NAAM : Tonen woonaanbodgevens van een enkel object
PARAMETERS: vpPropertyId – Long - Id van ViewPoint verhuurbaar object
vacantFrom – Date - Datum vanaf welke het object leeggemeld moet zijn
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 31 van 75
32. OUTPUT: {VP}UnoccupiedPropertyData
CALL: nl.itris.soap.calls.crm.SoapBaeCalls.getUnoccupiedPropertyData
SOAP: getUnoccupiedPropertyData
OMSCHRIJVING: Deze call exporteert een lijst van gegevens voor een enkel ViewPoint
leegstaand object.
CHECKS: Het ID moet verwijzen naar een bestaand object in ViewPoint.
FOUTMELDINGEN: Indien ID niet verwijst naar een bestaande relatie is het responsdocument leeg:
<B:getUnoccupiedPropertyDataResponse/>
5.3.1. Input XML - getUnoccupiedPropertyData
<v:getUnoccupiedPropertyData
xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">
<v:vpPropertyId>160021983</v:vpPropertyId>
<v:vacantFrom>20050630T11:00:00</v:vacantFrom>
</v:getUnoccupiedPropertyData>
5.3.2. Output XML - getUnoccupiedPropertyDataResponse
<B:getUnoccupiedPropertyDataResponse>
<B:UnoccupiedPropertyData>
<B:Name></B:Name>
<B:ID>160003602</B:ID>
<B:PropertyID>160021983</B:PropertyID>
<B:StartDate>20060301</B:StartDate>
<B:AvailableFrom>01032006</B:AvailableFrom>
<B:EndDateAsAdvertised>20100902</B:EndDateAsAdvertised>
<B:DatePublished>20100819</B:DatePublished>
<B:UrgentReactions>0</B:UrgentReactions>
<B:NonUrgentReactions>1</B:NonUrgentReactions>
<B:Subtype>Woning</B:Subtype>
<B:Status>VOORDRACHT</B:Status>
<B:Identification>105.0015</B:Identification>
<B:CompanyName>Eigen haard</B:CompanyName>
<B:Model>AANBODMODEL</B:Model>
<B:Type>appartement 1e verdieping</B:Type>
<B:Address>
<B:Street>Korenbeursstraat</B:Street>
<B:HouseNumber>1</B:HouseNumber>
<B:HouseNumberSuffix>15</B:HouseNumberSuffix>
<B:Postcode>1335 XL</B:Postcode>
<B:Municipality>ALMERE</B:Municipality>
<B:City>ALMERE</B:City>
<B:Country>Nederland</B:Country>
<B:Type>CORADR</B:Type>
</B:Address>
<B:StreetAddress>Korenbeursstraat 1 15</B:StreetAddress>
<B:Postcode>1335 XL</B:Postcode>
<B:City>ALMERE</B:City>
<B:Country>NEDERLAND</B:Country>
<B:District>Centrum</B:District>
<B:Municipality>ALMERE</B:Municipality>
<B:Neighbourhood>5465</B:Neighbourhood>
<B:TotalRent>0.0</B:TotalRent>
<B:BasicRent>0.0</B:BasicRent>
<B:HeatingCosts>0.0</B:HeatingCosts>
<B:ServiceCharges>0.0</B:ServiceCharges>
<B:GeneralCharges>0.0</B:GeneralCharges>
<B:IHSRent>0.0</B:IHSRent>
<B:DepositAmount>0.0</B:DepositAmount>
<B:NrOfRooms></B:NrOfRooms>
20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 32 van 75