Data via een webservice in Relatics importeren

In Relatics beheren eindgebruikers projectinformatie zoals eisen, objecten, verificaties, documenten, etc. Meestal is er overlap qua informatie met andere systemen. Denk aan een object dat in Relatics aan een eis wordt gekoppeld, terwijl er in een ander systeem (bijv. een GIS-systeem) meer informatie over datzelfde object beschikbaar is. Regelmatig ontstaat de behoefte om grote hoeveelheden informatie uit een ander systeem automatisch over te zetten naar Relatics. Veelgenoemde redenen zijn het beschikbaar maken van extra metadata in Relatics (bijv. eigenschappen en relaties van objecten) en het gebruik van bepaalde Relatics features met die metadata (bijv. Distributed Integration). In dit artikel laat ik aan de hand van een voorbeeld met objecten zien hoe je met een combinatie van een import en een webservice data in Relatics importeert.

Benodigde voorkennis

In dit artikel ga ik ervan uit dat je ervaring hebt met het configureren van een import in Relatics. De nadruk van dit artikel ligt op het configureren van de webservice en het aanspreken van de webservice via een andere applicatie of ander systeem. Verder wordt in dit artikel ervan uitgegaan dat je bekend bent met de applicatie SoapUI.

Een importdefinitie in Relatics configureren

Om informatie in Relatics via een webservice te importeren dient er eerst een Import Definition beschikbaar te zijn. Voor deze voorbeeldcasus is een Import Definition gemaakt waarmee objecten inclusief metadata geïmporteerd wordt:

Als je informatie uit een ander systeem importeert, raad ik je aan om het ForeignKey attribuut te gebruiken. In deze voorbeeldcasus wordt in de ForeignKey een unieke, identificerende waarde van het betreffende object uit het andere systeem opgeslagen. Hierdoor kun je in Relatics altijd traceren om welk object het gaat. Dit is belangrijk omdat het andere systeem in dit voorbeeld leidend is in het ontstaan en beheren van de objecten.

De importdefinitie in Relatics testen

Voordat je de webservice configureert en test raad ik je aan om de import definition eerst in Relatics te testen. Als je later tegen problemen aanloopt bij het testen van de webservice, dan weet je zeker dat het niet aan de import definition in Relatics ligt. Om de import definition te testen kun je zelf een XML-bestand maken:

Voorbeeld: XML-bestand om de import definitie te testen

<?xml version="1.0" encoding="UTF-8"?>

<Import>

    <Row ForeignKey="Import-SysObj-001" Name="Pavement" Status="Actual" />

    <Row ForeignKey="Import-SysObj-002" Name="Beam" Status="Actual" />

    <Row ForeignKey="Import-SysObj-003" Name="Public Lighting" Status="Actual" />

</Import>

Voor het importeren van een XML-bestand in Relatics is het belangrijk om de eerste node Import te noemen. Binnen deze node dient voor elke importregel een node Row te zijn. In Row kun je vervolgens de attributen specificeren die de te importeren data bevatten. Op deze manier kun je het XML-bestand direct in Relatics importeren zonder gebruik te maken van een XSL-transformatie.

Een webservice voor een import in Relatics configureren

Om de Import Definition door een externe applicatie te laten gebruiken, dient deze gekoppeld te worden aan een webservice. In het geval van een Import Definition is hier een Server for receiving data voor nodig:

Belangrijk is om de OperationName in te vullen. Dit is de unieke naam waarmee je een webservice kunt aanroepen. Verder is de EntryCode belangrijk. Hier vul je een wachtwoord in om toegang te krijgen tot de webservice.

Gegevens verzamelen om de SOAP webservice aan te roepen via een ander systeem

Voordat je een webservice vanuit een ander systeem gaat aanroepen, is het belangrijk om eerst alle benodigde gegevens op een rijtje te zetten. Als eerste is dit de URL waarmee de webservice benaderd wordt:

Voorbeeld webservice: URL

https://my-environment.relaticsonline.com/DataExchange.asmx?wsdl

Het eerste gedeelte uit de URL (“my-environment”) dient vervangen te worden door die van de eigen Relatics Environment. Naast de URL is een Operation nodig. Het andere systeem moet expliciet de Operation opgeven, zodat duidelijk is dat het om een import webservice gaat. In deze casus dient de volgende Operation gebruikt te worden:

Voorbeeld webservice: Operation

Import

Als laatste is het verstandig om een voorbeeld van een SOAP-request te maken, waarin alle benodigde metadata is ingevuld:

Voorbeeld webservice: SOAP request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:rel="http://www.relatics.com/">

   <soap:Header/>

   <soap:Body>

      <rel:Import>

         <rel:Operation>System Objects</rel:Operation>

         <rel:Identification>

            <rel:Identification>

               <rel:Workspace>6cb35e56-3426-4dcc-ba0c-44536d4ae4c3</rel:Workspace>

            </rel:Identification>

         </rel:Identification>

         <rel:Authentication>

            <rel:Authentication>

                     <rel:Entrycode>MyEntryCode</rel:Entrycode>

            </rel:Authentication>

         </rel:Authentication>

         <rel:Filename>Test_not_needed.xml</rel:Filename>   <rel:Data>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEltcG9ydD4KCTxSb3cgRm9yZWlnbktleT0iSW1
wb3J0LVN5c09iai0wMDEiIE5hbWU9IlBhdmVtZW50IiBTdGF0dXM9IkFjdHVhbCIgLz4KCTxSb3cgRm9yZWlnbktleT0iSW1wb3J0LVN5
c09iai0wMDIiIE5hbWU9IkJlYW0iIFN0YXR1cz0iQWN0dWFsIiAvPgoJPFJvdyBGb3JlaWduS2V5PSJJbXBvcnQtU3lz
T2JqLTAwMyIgTmFtZT0iUHVibGljIExpZ2h0aW5nIiBTdGF0dXM9IkFjdHVhbCIgLz4KPC9JbXBvcnQ+</rel:Data>

      </rel:Import>

   </soap:Body>

</soap:Envelope>

Er zijn 5 specifieke XML-nodes ingevuld:

  • Operation: De OperationName van de webservice (voorbeeld: System Objects)
  • Identification - Workspace: De ID van de Workspace, ook wel WID genoemd (voorbeeld: 6cb35e56-3426-4dcc-ba0c-44536d4ae4c3)
  • Authentication - Entrycode: : De Entry code van de webservice (voorbeeld: MyEntryCode)
  • Filename: De naam van het meegestuurde XML-bestand. Opmerking: Je kan kiezen voor het meesturen van een bestand of voor het direct opnemen van de data. In dit voorbeeld is gekozen om de data direct op te nemen. Deze node is dus niet relevant. Daarom is in het voorbeeld de naam van een bestand opgenomen dat niet bestaat. Je kan er voor kiezen om deze regel weg te laten.
  • Data: De te importeren XML-data. Opmerking: Deze data dient Base64 gecodeerd te zijn. In bovenstaand voorbeeld van de request, staat de XML uit de paragraaf “De importdefinitie testen in Relatics”.

Tip: Gebruik voor het testen van de webservice een website (e.g. https://www.base64encode.org/) om de XML-data Base64 te coderen. Het resultaat kun je in de node Data Data van je request opnemen.

Gebruik een externe applicatie voor het testen van de webservice

Nadat alle gegevens verzameld zijn ben je klaar om de webservice in een ander systeem of applicatie te testen. Voor dit artikel heb ik de applicatie SoapUI gebruikt om de webservice testen:

03_test-relatics-webservice-in-soap-ui

In het linker scherm zie je het request zoals voorbereid in de vorige paragraaf. In het rechterscherm zie je het resultaat na het uitvoeren van de webservice request. Als je in het resultaat de import log herkent, dan heb je de webservice succesvol getest.

Downloaden

Upload onderstaand rcs-bestand in je Relatics environment om de voorbeelden van dit artikel zelf te bekijken:

Over Kris de Waal

Na het afronden van de studie Bedrijfskunde met een specialisatie in Business Information Management, werkt Kris bij Relatics als Business Information Consultant. Hij leert graag over nieuwe concepten, technologieën, IT-systemen en past deze kennis toe in zijn dagelijkse werk. Daarnaast werkt Kris graag aan nieuwe ideeën en innovaties om meer uit Relatics te halen.

Relatics Portret-120

Contact

Heeft u hulp nodig bij het toepassen van de genoemde technieken in uw eigen casus? Of heeft u vragen, opmerkingen of suggesties over dit artikel? Laat het ons dan weten via onderstaand formulier.