ViewPoint Interactief Specificatie SOAP callsDocument:          ViewPoint Interactief specificatie SOAP callsVersie:      ...
DocumenthistorieVersiebeheer Versie     Datum                      Auteur                    Samenvatting van de wijziging...
Inhoudsopgave1. Technische specificatie Itris SOAP calls.....................................................................
1.              Technische specificatie Itris SOAP calls1.1.            InleidingDit document beschrijft in detail de besc...
2.              Algemene eigenschappen en detailsDe hier beschreven mogelijkheden zijn een standaard functionaliteit van V...
ongewenst.Het advies is om in dit geval gebruik te maken van een VPN verbinding over het Internet. Hierbijwordt alle verke...
ontvanger er niet van uit mag gaan dat een bepaalde namespace definitie altijd op een        bepaalde plaats staat! Prefix...
de nieuwe functionaliteit; het gedrag van de oude interface wordt in de nieuwe versie vanViewPoint “geëmuleerd”. De nieuwe...
</registratie>                                           <bestaande-woning>                                               ...
Voor meer details over de verschillende SOAP messaging models zie bijvoorbeeldhttp://www.ibm.com/developerworks/webservice...
alternatief iso-8859-154. Niet standaard encodings zoals win1252 worden niet ondersteund. Indit geval moet onze klant (de ...
database op te slaan en de gebruiker de mogelijkheid te geven om eventueel de gegevens aante passen en de call opnieuw te ...
<Field>SocialSecurityNr</Field>              <OriginalValue>00001</OriginalValue>              <FaultCode>socialSecurityNu...
de grote hoeveelheid data voor sommige calls voor problemen met de performance van dekoppeling als bestanden telkens weer ...
Hash             String[32]       V     De MD5 hash berekend over de inhoud in bytes van het                              ...
gebruikt.Op deze manier worden grote media bestanden alleen opnieuw opgevraagd als ze zijnaangepast, en wordt de performan...
daarna de aangepaste gegevens om zijn eigen, locale kopie aan te passen.Dit mechanisme is relatief eenvoudig te implemente...
onvoldoende, omdat er dan A. de Jansen zou staan. De “Prefix” van de achternaam moet ook inhet update bericht zitten met e...
Field               : Uniek field code / technische naam                                        Deze naam wordt ingesteld ...
3.              Specificatie calls ViewPoint SOAP server3.1.            Authenticeren publieke gebruiker     NAAM :       ...
</B:authenticatePublicUserResponse>3.2.          Control bij het verzoek voor wijzigen wachtwoord   NAAM :                ...
3.3.          Wijzigen public password   NAAM :                   Wijzigen wachtwoord   PARAMETERS:              relationI...
4.              Relaties4.1.            Aanmaken nieuw persoon in ViewPoint     NAAM :                   Maakt een nieuw r...
    <MobilePhone>06­99998888</MobilePhone>             <WorkPhone>010­12341234</WorkPhone>             <Email>test_email@g...
4.2.          Tonen klantgegevens   NAAM :                   Tonen klantgegevens met contracten en saldi.   PARAMETERS:   ...
        </B:AddressList>             <B:BankAccountList>               <B:BankAccount>                 <B:Type>B</B:Type> ...
                  <B:Country>Nederland</B:Country>                           <B:StartDate>1900­01­01</B:StartDate>        ...
<BankAccountList />                  <CapacityList>                    <Capacity>                      <Description>MEDEWE...
REFERENTIES:4.4.1.        Input XML - lookupAddressViaZipcode           <v:lookupAddressViaZipcode                 xmlns:v...
5.              Objecten5.1.            Opvragen specificaties woningwaardering     NAAM :                   Opvragen spec...
5.2.          Tonen woonbezit   NAAM :                   Tonen woonbezitgegevens van een enkel object   PARAMETERS:       ...
OUTPUT:                  {VP}UnoccupiedPropertyData   CALL:                    nl.itris.soap.calls.crm.SoapBaeCalls.getUno...
        <B:NrOfBedrooms></B:NrOfBedrooms>        <B:TotalSquareMetres>55.0</B:TotalSquareMetres>        <B:Sanitary></B:Sa...
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
20111013   view point interactief - soap calls
Upcoming SlideShare
Loading in...5
×

20111013 view point interactief - soap calls

295

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
295
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Transcript of "20111013 view point interactief - soap calls"

  1. 1. ViewPoint Interactief Specificatie SOAP callsDocument: ViewPoint Interactief specificatie SOAP callsVersie: 1.2Datum: 13 oktober 2011In opdracht van: Remco van NiekerkAuteur: Jo SeatonReview:Copyright: © 2010 Itris BV Rhijnspoor 243-245 2901 LB Capelle aan den IJssel Tel: +31(0)10 2666111 Fax: +31(0)10 2666112
  2. 2. DocumenthistorieVersiebeheer Versie Datum Auteur Samenvatting van de wijzigingenGoedkeuringDe hieronder genoemde personen hebben kennis genomen van de inhoud van het documenten deze goedgekeurd: Versie Datum Naam Functie Handtekening R0s1DistributieDit document is aan de onderstaande personen verstuurd: Versie Datum Naam Functie Bedrijf 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 2 van 75
  3. 3. Inhoudsopgave1. Technische specificatie Itris SOAP calls..............................................................................42. Algemene eigenschappen en details....................................................................................53. Specificatie calls ViewPoint SOAP server..........................................................................214. Relaties ............................................................................................................................... 245. Objecten ............................................................................................................................... 316. Werkverzoeken..................................................................................................................... 367. Betaalafspraken.................................................................................................................... 408. Objectverdeling Interactief.................................................................................................. 499. Technische specificatie SOAP client pushes versie 5......................................................6610. Bulk data aanlevering ........................................................................................................ 7011. Appendix A: Meest voorkomende foutcodes...................................................................7112. Wijzigingshistorie............................................................................................................... 73 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 3 van 75
  4. 4. 1. Technische specificatie Itris SOAP calls1.1. InleidingDit document beschrijft in detail de beschikbare SOAP calls in de Itris ViewPoint koppeling.Calls zijn geordend op basis van hun functionaliteit.1.2. Gebruikte conventiesTODO/aanpassen1.3. Gebruikte termen en begrippenVoor een goed begrip worden de volgende termen en definities gebruikt in de tekst.ViewPoint, ViewPoint SysteemMet deze termen bedoelen we het gehele ViewPoint systeem. In dit document wordt hiermeestal de SOAP receptor voor het systeem bedoeld. Het ViewPoint systeem bestaat echter uiteen webserver, database server, Business Objects server en verschillende fysieke machines.Peer systeemMet deze term bedoelen we de “tegenpartij”, d.w.z. het systeem waarmee ViewPointcommuniceert. 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 4 van 75
  5. 5. 2. Algemene eigenschappen en detailsDe hier beschreven mogelijkheden zijn een standaard functionaliteit van ViewPoint, en wordendus niet gebouwd voor een enkele, specifieke koppeling. Dit betekent dat dezelfde calls gebruiktworden door alle koppelingen, waar nodig.2.1. Het low-level koppelvlakVoor 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 overHTTP(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 systemenEen ViewPoint systeem en het peer systeem moeten kunnen communiceren voor hetuitwisselen van de SOAP berichten. Dit kan op twee manieren:• Over een Internet-verbinding.• Over een privé netwerk (Epacity).2.2.1. Koppelen via het InternetVoordeel van deze methode is dat de beschikbare bandbreedte vaak groot is tegen relatiefgeringe kosten. Belangrijkste nadeel is dat de beschikbaarheid van de totale verbinding (dusniet alleen van een machine naar het Internet, maar de volledige verbinding van machine totmachine) niet gegarandeerd kan worden1.Verder geldt dat het direct aansluiten van het primaire systeem op het Internet een enormveiligheidsrisico oplevert. Om deze reden is een directe koppeling via het Internet sterk1 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. 6. ongewenst.Het advies is om in dit geval gebruik te maken van een VPN verbinding over het Internet. Hierbijwordt alle verkeer door het VPN beveiligd en versleuteld verzonden. De voor deze koppelingbenodigde regels voor infrastructuur valt buiten de scope van dit document.Omdat de juiste werking van het VPN voorwaardelijk is voor een betrouwbare koppelingverdient 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 capaciteitmoet hebben om het berichtenverkeer tussen de verschillende omgevingen met voldoendesnelheid uit te wisselen. De benodigde snelheid is sterk afhankelijk van het gebruik enimplementatie van een specifieke koppeling, maar zal minimaal 2Mbit/s symmetrisch moetenzijn. Dit laatste betekent dat ADSL-achtige Internet verbindingen (technisch gelimiteerd tot max.1.3Mbit/s retour) niet voldoen.2.2.2. Koppelen via EpacityHet is ook mogelijk om de verbinding tussen beide systemen te maken door ze te verbinden viaEpacity. In dit geval moeten beide locaties aangesloten worden op het Epacity netwerk, met eenaansluiting met voldoende snelheid voor het verwerken van de berichtenstroom. Gezien demogelijke latency zal de verbindingssnelheid aan beide zijden niet lager mogen zijn dan 2MBit/ssymmetrisch; 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 voordeeldat beschikbaarheid en gegarandeerde bandbreedte veel beter geregeld zijn, bij een enkeleaanbieder. Het betekent dat een end-to-end beschikbaarheid bekend is, en dat er een enkelaanspreekpunt is voor communicatieproblemen.Voor de aanvullende kosten die gemoeid zijn met een Epacity aansluiting dienen de klant en deaanbieder van het peer systeem zelf afspraken te maken met elkaar en met Itris. De kostenvoor de snellere Epacity verbinding aan de zijde van de klant worden niet door Itris gedragen.2.3. Gebruik van XML binnen de koppelingDe koppeling gebruikt XML als “taal” binnen de koppeling. We gebruiken XML volgens destandaard (XML 1.0), en gebruiken namespaces om varianten (versies) van objecten en calls tespecificeren.De gebruikte XML moet worden gelezen door een conformant parser. Deze parser moet in staatzijn om XML met namespaces op de juiste manier te lezen. Dit betekent concreet dat de aaneen namespace gekoppelde prefix2 geen enkele betekenis heeft in het resultaat. Bij hetlezen van de XML mag dus nooit een specifieke prefix worden verwacht, noch mag eenspecifieke indeling qua namespace definitie worden verwacht door de lezer. Anders gezegd: hetlezen 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 een2 Met prefix wordt bedoeld de “ns1” in een tag als <ns1:Envelope>. 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 6 van 75
  7. 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 vanelementen en attributen definiëren over welk begrip we praten. De prefix moet volledigonzichtbaar zijn in de code.Wanneer in het peer systeem een eigen XML parser geïmplementeerd wordt, zonder hulp vande op het platform geboden XML mechanismes, dan dient deze implementatie de volledigeXML standaard correct te implementeren. Elke fout die veroorzaakt wordt doordat de ontvangerde XML standaard incorrect implementeert is ter verantwoording van de ontvanger, ook als deItris software wordt aangepast!In de voorbeelden van SOAP calls zullen verschillende namespace definities en prefixenaanwezig zijn. Rekening houdende met het bovenstaande, moet het duidelijk zijn dat dezeprefixen in de werkelijke calls verschillend zullen zijn.2.4. Datatypes binnen de gegevenssetDe 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 interfacesDe door Itris aangeboden SOAP interface wordt niet specifiek voor een bepaalde koppelinggebouwd. Er bestaan een aantal standaard “services” die herbruikbaar zijn voor verschillendeprocessen en verschillende klanten. Om een grote mate van interoperabiliteit te kunnen gevenis gekozen om alleen een basale vorm van SOAP te implementeren. Deze keuze betekent datvrijwel ieder platform zonder al te veel problemen kan koppelen met onze implementatie, en datwe geen interoperabiliteitsproblemen krijgen doordat verschillende producten net een andereversie (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 interfaceDe door Itris opgeleverde SOAP interface, met de beschrijvingen van de calls en het resultaatvan de calls wordt door Itris als interface gegarandeerd stabiel gehouden (= niet incompatibelaangepast, maar zie verder!) over een periode van drie jaar. Na deze periode kan Itris deinterface wijzigen, of bepalen dat een andere versie van de interface gebruikt moet worden. Ditbetekent dan ook een aanpassing in de gekoppelde applicaties gedaan moet worden. Dekosten van deze aanpassingen zijn voor rekening van de klant, omdat de “levensduur” van deinterface is beëindigd.De reden dat een interface end-of-life kan raken heeft voornamelijk te maken met de technischeontwikkeling van ViewPoint als product. Het product kan beter en stabieler worden gebouwd alsniet alle historie met alle compatibiliteitslagen continu moeten worden onderhouden.Als Itris tussentijds een interface (gevormd door een bepaalde specificatie qua invoer enuitvoer) moet aanpassen op een niet-compatibele wijze, bijvoorbeeld doordat de functionaliteitvan ViewPoint rond de interface is veranderd, dan zal dat gebeuren door een nieuwe versie vande interface te definiëren. Deze nieuwe versie bestaat dan gewoon naast de oude, bestaandeversie (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. 8. de nieuwe functionaliteit; het gedrag van de oude interface wordt in de nieuwe versie vanViewPoint “geëmuleerd”. De nieuwe versie van de call wordt aangeroepen doordat deze calleen andere namespace gebruikt dan de oude call.Versies van interfaces worden binnen de SOAP call omgeving gespecificeerd door de gebruiktenamespace van de calls binnen de interface. De namespaces bepalen zowel de mogelijkeinvoer 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 elkemogelijke call kan op elk moment extra informatie aan zowel invoer als uitvoer van een callworden toegevoegd. Itris garandeert wél dat de oude definitie van de call niet wijzigt door dezetoevoegingen. 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 schemas 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</hoofdaanvrager> rager> <partner>43562693475</partner> <partner>43562693475</partner> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 8 van 75
  9. 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 structuurzélf uit entities bestaat. Een entity als <plaatsnaam> die nu bestaat uit een enkele string zalnooit veranderen in een entity met tekst plus onderliggende entities (oftewel: mixed=false zalnooit 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 “schemas” voor de calls in iedere definitie eindigen met <xs:any/>, en datelk element <xs:anyAttribute> bevat3. Het betekent ook niet dat geen controle mogelijk is; allewerkelijk gebruikte elementen mogen in een eigen schema worden opgenomen en gevalideerd.Gezien bovenstaande eisen beperkt de validatie zich dan tot elementtypes, domeinrestrictiesenz; restricties op bijv. minOccurs en maxOccurs zijn technisch niet mogelijk.2.8. Message formaat van SOAP callsDe Itris SOAP calls moeten worden gedaan in het Doc/Lit Wrapped soap messaging model. Ditbetekent 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 naamdie wordt gebruikt voor het dispatchen van de call naar de juiste afhandeling. De SOAPActionhttp 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. 10. Voor meer details over de verschillende SOAP messaging models zie bijvoorbeeldhttp://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/2.9. Authenticatie voor het uitvoeren van ViewPoint callsHet 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 ophet systeem van een klant, dient iedere gebruiker van een call zich te identificeren. Let op: hetgaat hier dus om authenticatie van de partij die de SOAP calls doet, niet de authenticatie vaneen consument op een website!Voordat de SOAP interface te gebruiken is dient een bedrijf dat er gebruik van wil maken eenSOAP account plus wachtwoord aan te vragen bij de beheerder van het ViewPoint systeem. Ditaccount representeert daarna het bedrijf en de systeembeheerder van het ViewPoint systeemkan daarna rechten voor de verschillende calls uitdelen aan dit bedrijf. Hierdoor is te allen tijdeduidelijk welke calls mogen worden uitgevoerd door welke derden.Iedere call die wordt uitgevoerd dient de volledige accountgegevens te bevatten (account naamen 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 eenvoorwaarde.De gegevens benodigd voor authenticatie moeten door de caller eenvoudig kunnen wordenaangepast.Calls waarbij de authenticatie ontbreekt of waarbij de authenticatie mislukt resulteren in eenSOAP Fault.2.10. Encoding van SOAP callsAlle informatie in ViewPoint is opgeslagen in Unicode. Standaard en bij voorkeur worden SOAPcalls 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 wordengedaan in dezelfde encoding als het verzoek.De huidige (1.x) versie van de SOAP interface zal, wanneer een encoding wordt gebruiktwaarbij tekens in de uitvoer niet kunnen worden gerepresenteerd, deze tekens vervangen doorhet bij de gebruikte encoding behorende “onbekend teken” karakter. In dit geval gaat dusinformatie verloren; dit wordt dan ook sterk afgeraden voor iedere gegevensset waar ookupdates worden teruggestuurd! In dat geval overschrijft iedere update de niet ondersteundetekens met “onbekend teken” characters, zelfs als de ontvangende set (waar het tekenoorspronkelijk vandaan kwam) de juiste waarde voor het teken bevat!Een typische ViewPoint omgeving bevat naast alle ASCII tekens ook alle mogelijke tekens metaccenten 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. 11. alternatief iso-8859-154. Niet standaard encodings zoals win1252 worden niet ondersteund. Indit geval moet onze klant (de corporatie) akkoord gaan met het mogelijk verlies van bijzonderetekens in gegevens die vanuit het remote systeem worden gewijzigd.2.11. Target adres voor SOAP callsHet target adres voor de SOAP calls bestaat uit een door Itris uitgegeven URL. Deze moeteenvoudig te wijzigen zijn in het peer systeem en is voor iedere klant verschillend (omdat wepraten over verschillende systemen). De tekstuele representatie van deze URL is dus geendeel van de interface en is niet constant. De URL zal onder andere verschillen voor eenproductiesysteem 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 deSOAP user ID als parameter wordt meegegeven. Dit is alleen nodig als blijkt dat de caller eenniet-standaard vorm van SOAP gebruikt waar uitzonderingen op de afhandeling gemaaktmoeten worden. De specificatie van welke uitzonderingen moeten worden gemaakt zijn namelijkgekoppeld aan het soap user ID.2.12. Foutafhandeling van SOAP calls.We onderscheiden twee soorten fouten binnen de SOAP interface: • Harde fouten • Zachte fouten2.12.1. Harde foutenHarde fouten zijn alle systeemfouten en onverwachte fouten. Voorbeelden van harde foutenzijn:• 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 wordengepresenteerd als een systeemfout zodat de gebruiker zelf kan besluiten wanneer hij/zij hetproces opnieuw probeert. Dit is alleen geldig als de call geen deel is van een reeks calls diesamen een resultaat moeten bereiken (als het goed is komt dit überhaupt niet voor – alle callszijn 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 tweedatabases up-to-date houdt) dan is het van primair belang dat mislukken van de call niet totproblemen leidt! Als een “update” verzoek mislukt en niet wordt herhaald dan lopen dedatabases uit elkaar zonder dat dit wordt geconstateerd.Afhankelijk van het type van de harde fout kan een mislukte call worden “bewaard” en lateropnieuw worden uitgevoerd, handmatig of automatisch. Dit kan bijvoorbeeld door de call in een4 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. 12. database op te slaan en de gebruiker de mogelijkheid te geven om eventueel de gegevens aante passen en de call opnieuw te proberen.Binnen ViewPoint worden belangrijke calls opgeslagen in de “Pending Operation Queue”. Dezezorgt ervoor dat calls, indien mogelijk, op de juiste manier herhaald worden verzonden. Als eencall blijft mislukken dan is handmatig ingrijpen vereist. De status van de Pending OperationQueue kan in ViewPoint worden bekeken middels het scherm Beheer → Beheren vanuitgestelde 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 identifierexists: [nl.itris.viewpoint.db.crm.Relation#12342341000034] atorg.hibernate.impl.SessionFactoryImpl$1.handleEntityNotFound(SessionFactoryImpl.java:379)atorg.hibernate.proxy.AbstractLazyInitializer.checkTargetState(AbstractLazyInitializer.java:79)</A:detail> </A:Fault> </A:Body></A:Envelope>In alle gevallen waarin een uniek numeriek ID invoerveld/parameter niet kan worden gekoppeldaan een bestaand record resulteert dit in een harde fout. De rationele is dat het client systeemdit ID ooit van de SOAP server of via een batch-aanlevering heeft gekregen en dat dezewaardes onveranderlijk zijn en niet uit de ViewPoint database verwijderd worden, met namewaar het relaties, objecten, contracten e.d. betreft. Het niet (meer) kunnen vinden van deze ID’sduidt op een ernstige fout.2.12.2. Zachte foutenZachte fouten zijn in de definitie van een call gespecificeerde mogelijke foutsituaties. Dezefouten kunnen door de aanroepende partij worden gebruikt om het gedrag van de applicatie tebepalen: het belangrijkste kenmerk van een zachte fout is dat de aanroeper in staat moet zijnom gepaste actie te ondernemen en zo nodig de call opnieuw te plaatsen met gewijzigdeparameters.Typische voorbeelden zijn validatiefouten door ontbrekende, onvolledige of onjuiste gegevens inaanroepparameters: bijvoorbeeld een ongeldig burgerservicenummer, letters in een numeriekveld, 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. 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 degeconstateerde fout:Naam Type OmschrijvingField 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 enFaultCode 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 eencomplete lijst van alle (validatie) fouten bevat. In bovenstaand voorbeeld zou dan alleen heteerste Item worden geretourneerd, omdat de server aan validatie van de geboortedatum nietmeer toe zou komen. Voor een nette afhandeling van fouten op de website blijft het daarom deverantwoordelijkheid van het cliënt systeem om data voor aanroep te valideren op basalekenmerken zoals verplicht/niet verplicht en de juiste inhoud (numeriek, alfanumeriek, maximalelengte).Een lijst met de meest voorkomende foutcodes voor zachte fouten is in Appendix A toegevoegd.2.13. Media “bestanden” in callsBinnen ViewPoint zijn allerlei media bestanden aanwezig die voor verschillende gegevenskunnen worden opgevraagd. Het gaat dan om veelal grote, binaire bestanden die PDFs, fotos,MS/Word documenten enz. bevatten. De inhoud van deze bestanden wordt nooit in XMLteruggegeven omdat daardoor de XML bestanden extreem groot zouden worden. Verder zorgt 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 13 van 75
  14. 14. de grote hoeveelheid data voor sommige calls voor problemen met de performance van dekoppeling als bestanden telkens weer worden opgevraagd. Om deze reden bevat de ViewPointkoppeling een algemeen mechanisme voor het effectief opvragen van deze bestanden zodat zeop het peer systeem kunnen worden gecached. Het implementeren van deze caching isverplicht voor ieder systeem wat de bestanden presenteert aan consumenten.Performance-problemen die worden veroorzaakt doordat deze Media bestanden niet wordengecached zijn ter verantwoording van de bouwer van de koppeling, en zullen niet door Itrisworden opgelost.Wanneer een object een of meer media bestanden bevat dan wordt ieder “bestand” altijdweergegeven 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 OmschrijvingID 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. 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 vanplaatjes. Als een plaatje een bitmap is (te zien aan het mime type) dan kunnen pixelwidth enpixelheight worden gebruikt om de aspect ratio5 van een plaatje te berekenen; deze aspect ratiois 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 groottevan het plaatje 800x600 pixels is. Om dit te verkleinen naar een thumbnail die past in 200x200pixels is de aspect ratio (hier 4:3) nodig om te voorkomen dat het plaatje in lengte of breedtewordt “uitgerekt”. De juiste grootte voor de thumbnail is dan 200x150. Het is vaak belangrijk denieuwe 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 eenURL aanwezig waarmee die inhoud kan worden opgevraagd wanneer nodig. Let op: de URLmoet gezien worden als “opaque” verwijzing naar het medium; de inhoud en opbouw van deURL kan gewijzigd worden zonder dat dit de werking mag verstoren. Dit betekent dat deontvanger de URL niet mag “decoderen” of aanpassen. In een aantal gevallen kan het URL veldook 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 naareen 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. Ditmechanisme 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 en5 De verhouding tussen lengte en breedte6 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. 16. gebruikt.Op deze manier worden grote media bestanden alleen opnieuw opgevraagd als ze zijnaangepast, en wordt de performance van het complete systeem niet nadelig beïnvloed doorgrote data transfers tijdens de communicatie.De reden voor caching is dat veel basale processen voor consumenten heel veel media nodighebben. Bijvoorbeeld het tonen van het beschikbare woningaanbod levert iedere keer vooriedere woning meerdere grote bestanden op, die ook nog mogelijk moeten worden geresizedals “thumbnail” tijdens presenteren.Media bestanden kunnen ook worden aangeleverd als onderdeel van een initiële dump. Opdeze manier kan het initieel vullen van een website-database snel plaatsvinden zonder datgigabytes aan dataverkeer nodig is.2.14. Caching voor opgevraagde gegevensEr is een (klein) aantal calls waarbij de maximale frequentie van uitvoeren van de call isgelimiteerd. Dit is gedaan omdat de call grote gevolgen heeft voor de performance van hettotale systeem. Een voorbeeld is de call voor het opvragen van het hele woningaanbod: vooreen gemiddelde klant kan het antwoord op deze call bestaan uit tientallen megabytes aangegevens. Als deze call voor iedere consument telkens weer moet worden uitgevoerd dan is hetresultaat dat de performance dramatisch slecht is: de hoeveelheid tijd voor het opvragen vandeze hoeveelheid gegevens over een relatief trage verbinding is vele seconden. Als meerderepersonen gelijktijdig deze set opvragen dan is de vertraging nog veel langer. Dit is nietacceptabel.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 teverversen, of door een “push” mechanisme te accepteren waarbij wijzigingen aan individueleobjecten door het ViewPoint systeem op het moment van aanpassen worden doorgegeven.Performance problemen die worden veroorzaakt door het niet implementeren van caching voordeze 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 omeen “refresh interval” af te spreken. Bijvoorbeeld dat de gegevens maximaal een (1) uur oudzijn; dit betekent dat ze ieder uur opnieuw moeten worden opgevraagd. Dit kan dan wordengeregeld door een achtergrondproces. Vaak wordt dit ook gedaan tijdens het opvragen van degegevens door een willekeurige gebruiker, door op dat moment te kijken of de gegevensververst moeten worden en ze op dat moment dan ook meteen op te vragen indien nodig. Dit isechter onverstandig gezien de lange data-transfer tijd voor de gegevens: het betekent dat dezeongelukkige 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 makenvan events. In dit geval wordt het peer systeem initieel voorzien van een “dump” van degegevens binnen ViewPoint. Daarna zal ViewPoint voor ieder object wat wordt aangepastbinnen 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. 17. daarna de aangepaste gegevens om zijn eigen, locale kopie aan te passen.Dit mechanisme is relatief eenvoudig te implementeren als de gegevensverzameling alleenwijzigt aan de ViewPoint zijde en niet aan de kant van de peer. Gegevensverzamelingen die welaan beide kanten kunnen wijzigen (bijvoorbeeld inschrijvingen, persoonsgegevens) zijnmoeilijker te implementeren via dit mechanisme.2.15. Representatie van Null velden, xsi:nilVelden 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 definitiefeitelijk onjuist is volgens de XML Schema definities zal de volgende versie (2.x) van deinterface gebruik maken van xsi:nil=”true” (in de XMLSchema-instance namespace) op alleelementen die werkelijk null representeren, en zal het lege element overeenkomen met de legestring. Het verdient aanbeveling om te zorgen dat code hier nu al rekening mee houdt. Denieuwe 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 callsDiverse 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) zaldoorgaans kleiner zijn dan wat in de database voor deze persoon is opgeslagen. Hetstandaardgedrag van alle calls is dat niet aangeleverde elementen worden genegeerd: zebehouden in de database hun oude waarde. We noemen dit “Partial updateability”.Alleen de in de update genoemde elementen worden aangepast: hun waarde wordt aangepastof op NULL gezet als de inhoud van het element nil is. Dus een ontbrekend element in eenupdate betekent niet dat het gegeven NULL is!Bij het valideren van een update worden wel alle benodigde gegevens gebruikt, ook als ze nietaanwezig zijn in de update. Gegevens die nodig zijn voor validatie/controle die niet aanwezigzijn in het update bericht behouden hun oude waarde, en dus wordt deze waarde gebruikt in devalidatie. Als dan een combinatie van deze waarden ongeldig is dan wordt de updategeweigerd.Een ander voorbeeld is het aanpassen van naamsgegevens. De volledige naam is verspreidover meerdere velden (initialen, achternaam-prefix, achternaam) die samen de volledige naamvormen. Bij de update moeten de aangepaste velden worden genoemd ook als ze leeggemaakt worden door de update. Bijvoorbeeld: mevrouw “A. de Boer” neemt de achternaamvan haar echtgenoot (Jansen) over. Enkel aanleveren van een nieuwe achternaam is 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 17 van 75
  18. 18. onvoldoende, omdat er dan A. de Jansen zou staan. De “Prefix” van de achternaam moet ook inhet 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 dehuisnummertoevoeging altijd op NULL gezet worden, tenzij aangeleverd. Wijzigen van depostcode 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 : CHARACTER2.18. Formulier inschrijving Elk entry bestaat uit 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 18 van 75
  19. 19. Field : Uniek field code / technische naam Deze naam wordt ingesteld binnen ViewPoint. Value(s) : : Waarde / Lijst van waarden Datatype : Type2.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. 20. 3. Specificatie calls ViewPoint SOAP server3.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>1981­09­01</B:DateOfBirth>         <B:SocialSecurityNr>256646399</B:SocialSecurityNr>         <B:MaritalStatus></B:MaritalStatus>       </B:Person> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 20 van 75
  21. 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. 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. 23. 4. Relaties4.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>1969­05­07</StartDate>             <EndDate>2010­05­07</EndDate>         </Capacity>     </CapacityList>     <ContractList/>     <InvoiceList/>     <RequestsForRepairList/>     <Initials>H</Initials>     <SurnamePrefix>de</SurnamePrefix>     <Surname>Kooten</Surname>     <HomePhone>020­11112222</HomePhone> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 23 van 75
  24. 24.     <MobilePhone>06­99998888</MobilePhone>     <WorkPhone>010­12341234</WorkPhone>     <Email>test_email@google.com</Email>     <Gender>man</Gender>     <DateOfBirth>1969­04­03</DateOfBirth>     <SocialSecurityNr>160040139</SocialSecurityNr>     <MaritalStatus>GESCHEIDEN</MaritalStatus> </Person> </v:createPerson>4.1.2. Output XML - createPersonResponse <B:createPersonResponse>       <B:Person>         <B:ID>1100102948</B:ID>         <B:Role>Crediteur</B:Role>         <B:AddressList>           <B:Address>             <B:Type>CORADR</B:Type>             <B:ID>1100117497</B:ID>             <B:Street>Sparrenlaan</B:Street>             <B:HouseNumber>6</B:HouseNumber>             <B:Postcode>5941 ED</B:Postcode>             <B:City>Velden</B:City>             <B:Country>Nederland</B:Country>           </B:Address>         </B:AddressList>         <B:BankAccountList>           <B:BankAccount>             <B:Type>B</B:Type>             <B:Preferred>false</B:Preferred>             <B:AccountNumber>476967996</B:AccountNumber>           </B:BankAccount>           <B:BankAccount>             <B:Type>G</B:Type>             <B:Preferred>true</B:Preferred>             <B:AccountNumber>12345</B:AccountNumber>           </B:BankAccount>         </B:BankAccountList>         <B:CapacityList>           <B:Capacity>             <B:Description>MAKELAAR</B:Description>             <B:StartDate>1969­05­07</B:StartDate>             <B:EndDate>2010­05­07</B:EndDate>           </B:Capacity>         </B:CapacityList>         <B:ContractList/>         <B:InvoiceList/>         <B:RequestsForRepairList/>         <B:Initials>H</B:Initials>         <B:SurnamePrefix>de</B:SurnamePrefix>         <B:Surname>Kooten</B:Surname>         <B:HomePhone>020­11112222</B:HomePhone>         <B:MobilePhone>06­99998888</B:MobilePhone>         <B:WorkPhone>010­12341234</B:WorkPhone>         <B:Email>test_email@google.com</B:Email>         <B:Gender>man</B:Gender>         <B:DateOfBirth>1969­04­03T00:00:00+01:00</B:DateOfBirth>         <B:SocialSecurityNr>160040139</B:SocialSecurityNr>         <B:MaritalStatus>GESCHEIDEN</B:MaritalStatus>       </B:Person>     </B:createPersonResponse> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 24 van 75
  25. 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>1900­01­01</B:StartDate>           </B:Address> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 25 van 75
  26. 26.         </B:AddressList>         <B:BankAccountList>           <B:BankAccount>             <B:Type>B</B:Type>             <B:Preferred>false</B:Preferred>             <B:AccountNumber>366557882</B:AccountNumber>           </B:BankAccount>           <B:BankAccount>             <B:Type>G</B:Type>             <B:Preferred>true</B:Preferred>             <B:AccountNumber>232323</B:AccountNumber>           </B:BankAccount>         </B:BankAccountList>         <B:CapacityList/>         <B:ContractList>           <B:Contract>             <B:ID>1100023807</B:ID>             <B:Description>Deze contracten worden automatisch aangemaakt  t.b.v. het verwerken van huurtoeslag (huursubsidie)      </B:Description>             <B:StartDate>1999­12­01</B:StartDate>             <B:EndDate>2005­02­28</B:EndDate>             <B:Type>EOS</B:Type>             <B:ContracteeList>               <B:Contractee>                 <B:ID>1100030940</B:ID>                 <B:StartDate>1999­12­01</B:StartDate>                 <B:Person>                   <B:ID>100026596</B:ID>                   <B:Role>Debiteur</B:Role>                   <B:Initials>F.L.V.D.E.</B:Initials>                   <B:Surname>Schuur /hut</B:Surname>                   <B:Gender>man</B:Gender>                 </B:Person>                 <B:Address>                   <B:Type>CORADR</B:Type>                   <B:ID>100048811</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>1900­01­01</B:StartDate>                 </B:Address>                 <B:Type>HOOFDCONTRACTANT</B:Type>               </B:Contractee>               <B:Contractee>                 <B:ID>1100030939</B:ID>                 <B:StartDate>1999­12­01</B:StartDate>                 <B:Person>                   <B:ID>1100045493</B:ID>                   <B:Role>Debiteur</B:Role>                   <B:Initials>E.</B:Initials>                   <B:Surname>Hulzebos</B:Surname>                   <B:DateOfBirth>1975­10­31</B:DateOfBirth>                 </B:Person>                 <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>20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 26 van 75
  27. 27.                   <B:Country>Nederland</B:Country>                   <B:StartDate>1900­01­01</B:StartDate>                 </B:Address>                 <B:Type>MEDEBEWONER</B:Type>               </B:Contractee>             </B:ContracteeList>             <B:BankAccountList/>             <B:PaymentTermsList>               <B:PaymentTerms>                 <B:StartDate>1999­12­01T00: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>1975­10­31</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. 28. <BankAccountList /> <CapacityList>   <Capacity>     <Description>MEDEWERKER</Description>     <StartDate>2005­01­01</StartDate>          </Capacity> </CapacityList> <ContractList /> <Invoices /> <RequestsForRepairList />   <SurnamePrefix>dé</SurnamePrefix>   <Surname>Business Consultant</Surname>   <HomePhone>010­12341234</HomePhone>   <MobilePhone>06­12341234</MobilePhone>   <WorkPhone>010­12341234</WorkPhone>   <Email>itris­business­consultant@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.lookupAddressViaZipcodeSOAP: 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
  29. 29. REFERENTIES:4.4.1. Input XML - lookupAddressViaZipcode   <v:lookupAddressViaZipcode  xmlns:v="http://xml.itris.nl/viewpoint/2009/01/29/viewpoint">   <v:zipcode>8231GE</v:zipcode>   <v:houseNumber>2215</v:houseNumber>   <v:houseSuffix>d</v:houseSuffix>  </v:lookupAddressViaZipcode>4.4.2. Output XML - lookupAddressViaZipcodeResponse <B:lookupAddressViaZipcodeResponse>      <B:Address>        <B:Street>Kempenaar</B:Street>        <B:HouseNumber>2215</B:HouseNumber>        <B:HouseNumberSuffix>d</B:HouseNumberSuffix>        <B:Postcode>8231 GE</B:Postcode>        <B:Municipality>LELYSTAD</B:Municipality>        <B:City>LELYSTAD</B:City>        <B:Country>Nederland</B:Country>        <B:Type>CORADR</B:Type>      </B:Address>  </B:lookupAddressViaZipcodeResponse> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 29 van 75
  30. 30. 5. Objecten5.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_VHO5.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. 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>01­01­1952</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. 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>2005­06­30T11: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>2006­03­01</B:StartDate>        <B:AvailableFrom>01­03­2006</B:AvailableFrom>        <B:EndDateAsAdvertised>2010­09­02</B:EndDateAsAdvertised>        <B:DatePublished>2010­08­19</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
  33. 33.         <B:NrOfBedrooms></B:NrOfBedrooms>        <B:TotalSquareMetres>55.0</B:TotalSquareMetres>        <B:Sanitary></B:Sanitary>        <B:MaxOccupancy></B:MaxOccupancy>        <B:Kitchen></B:Kitchen>        <B:Furniture></B:Furniture>        <B:Balcony></B:Balcony>        <B:RoofTerrace></B:RoofTerrace>        <B:Garden></B:Garden>        <B:Lift></B:Lift>        <B:Attic></B:Attic>        <B:Floor></B:Floor>        <B:CentralHeating></B:CentralHeating>        <B:StorageRoom></B:StorageRoom>        <B:Stories></B:Stories>        <B:Surroundings></B:Surroundings>        <B:Description></B:Description>        <B:AdvertisementNr>20107</B:AdvertisementNr>        <B:ComplexName>Complex 105</B:ComplexName>        <B:PreliminaryInspectionData></B:PreliminaryInspectionData>        <B:FinalInspectionData></B:FinalInspectionData>        <B:ReorderingMethod></B:ReorderingMethod>        <B:NumberOfPropertiesForRent></B:NumberOfPropertiesForRent>        <B:ConstructionYear>1968</B:ConstructionYear>        <B:WaitingTimeInWeeks></B:WaitingTimeInWeeks>        <B:AdminCharges>0.0</B:AdminCharges>        <B:FuturePlans></B:FuturePlans>        <B:Summary></B:Summary>        <B:Price></B:Price>        <B:PriceLabel></B:PriceLabel>        <B:TransferCharges></B:TransferCharges>        <B:LotSquareMetres></B:LotSquareMetres>        <B:CapacityInCubicMetres></B:CapacityInCubicMetres>        <B:TypeOfBuilding></B:TypeOfBuilding>        <B:Garage></B:Garage>        <B:Insulation></B:Insulation>        <B:Situation></B:Situation>        <B:EstateAgents></B:EstateAgents>        <B:MonthlyMortgage></B:MonthlyMortgage>        <B:SwimmingPool></B:SwimmingPool>        <B:AirCo></B:AirCo>        <B:Fireplace></B:Fireplace>        <B:TypeOfSale></B:TypeOfSale>        <B:Remarks></B:Remarks>        <B:BlockingType></B:BlockingType>        <B:TargetGroup></B:TargetGroup>        <B:WaitingTime></B:WaitingTime>        <B:DegreeOfMutation></B:DegreeOfMutation>        <B:PropertySyncStatus></B:PropertySyncStatus>        <B:PropertySyncConditions>Dit zijn de voorwaarden.</B:PropertySyncConditions>        <B:RenovationDescription></B:RenovationDescription>        <B:LivingRoomAreaSquareMetres></B:LivingRoomAreaSquareMetres>        <B:TotalFloorAreaSquareMetres></B:TotalFloorAreaSquareMetres>        <B:StorageSquareMetres></B:StorageSquareMetres>        <B:GardenSquareMetres></B:GardenSquareMetres>        <B:UOEPropertyKey></B:UOEPropertyKey>        <B:DistrictInfo></B:DistrictInfo>        <B:Street></B:Street>        <B:Huurvast5></B:Huurvast5>        <B:Huurvast10></B:Huurvast10>        <B:HuurZeker5></B:HuurZeker5>        <B:Huurzeker10></B:Huurzeker10>        <B:Koopgarant5></B:Koopgarant5>        <B:Koopgarant10></B:Koopgarant10>        <B:Koopgarant15></B:Koopgarant15> 20111013 - ViewPoint Interactief - SOAP calls.doc Pagina 33 van 75

×