Importing data in Relatics using a webservice

In Relatics, end users manage project information such as requirements, system objects, verifications, documents, etc. Usually, there is overlap in information with other systems. For example, in Relatics a system object is related to a requirement, while more information is available in another system (e.g. a GIS-system) about that same system object. Often, the need arises to transfer large amounts of information automatically from another system into Relatics. Common reasons are the availability of extra metadata in Relatics (e.g. properties and relations of system objects) and using certain Relatics features with that metadata (e.g. Distributed Integration). In this article, I will use an example with system objects to illustrate how you can import data in Relatics using a combination of an import and a webservice.

Required prior knowledge

In this article, I assume that you have experience with configuring an import in Relatics. The emphasis of this article is on configuring the webservice and performing a webservice request from another application or another system. Furthermore, this article assumes that you are familiar with the application SoapUI.

Configuring an import definition in Relatics

To import information in Relatics using a webservice, first an Import Definition has to be available. In this example case, an Import Definition was configured that allows to import system objects including metadata:

If you import information from another system, I recommend that you use the attribute ForeignKey. In this example case, the ForeignKey is used to store a unique, identifying value of the relevant system object. This always allows you to trace in Relatics which system object it concerns. This is important because the other system in this example is leading in the creation and management of system objects.

Testing the import definition in Relatics

Before you configure and test the webservice, I recommend you to first test the import definition in Relatics. If you run into problems later with testing, then you can be sure that it is not up to the import definition in Relatics. To test the import definition you can create an XML-file yourself:

Example: XML-file to test the import definition

<?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>

To import the XML-file in Relatics it is important to name the first node Import. Within this node, each import row needs a node named Row. Inside Row, you can specify attributes that contain the data that needs to be imported. In this way, you can directly import the XML-file in Relatics without the need of an XSL-transformation.

Configuring a webservice for an import in Relatics

In order for an external application to use the Import Definition, the Import Definition needs to be related to a webservice. In the case of an Import Definition a Server for receiving data is needed:

It is important to enter the OperationName. This is the unique name that you need for a webservice request. Furthermore, the EntryCode is important. Here you enter a password to get access to the webservice.

Collecting data for a SOAP webservice request from another system

Before you do a webservice request from another system, first it is important to collect all the necessary information. To start with, this is the URL to access the webservice:

Example webservice: URL

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

The first part of the URL (“my-environment”) needs to be replaced by the URL of your own Relatics Environment. Besides the URL, the Operation is needed. The other system must explicitly specify the Operation so that it is clear it concerns an import webservice. In this case the following Operation is needed:

Example webservice: Operation

Import

Finally, it is advised to prepare a SOAP-request in which all the necessary metadata has been filled in:

Example 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>

There are 5 XML-nodes filled in:

  • Operation: The OperationName of the webservice (example: System Objects)
  • Identification - Workspace: The ID of the Workspace, also called WID (example: 6cb35e56-3426-4dcc-ba0c-44536d4ae4c3)
  • Authentication - Entrycode: The Entry code of the webservice (example: MyEntryCode)
  • Filename: The name of the sent XML-file. Remark: You can choose either to send a file with the import data or to directly send the data that needs to be imported. In this example the data is directly sent. In this example the XML-node is not relevant. Therefore, in the example the name of the file contains the name of a non-existing file. You can also choose to omit this row from the XML.
  • Data: The XML-data that needs to be imported. Remark: The data needs to be Base64 encoded. In the example for the request above, you can find the XML from the example in the paragraph “Testing the import definition in Relatics”.

Tip: To test the webservice, use a website to base64 encode the data (e.g. https://www.base64encode.org/). You can use the result in the node Data of your request.

Using an external application to test the webservice

After collecting all the information, you are ready to test the webservice in another system or application. For this article, I used SoapUI to test the webservice:

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

On the left-hand side you can see the request as prepared in the previous paragraph. On the right-hand side you can see the result after submitting the request. If you recognize the result of the import log, you have successfully tested the webservice.

Downloaden

Upload the RCS file below to your Relatics environment to view the examples contained in this article:

About Kris de Waal

After graduating in Business Administration with a specialization in Business Information Management, Kris joined Relatics as a Business Information Consultant. He is eager to learn about new concepts, technologies, IT systems and apply the knowledge in his daily work. In addition, Kris loves to work on new ideas and innovations to get more out of Relatics.

Relatics Portret-120

Contact

Do you need help in applying the techniques and tips in your own case? Or do you have questions, comments or suggestions about this article? If so, don’t hesitate to contact one of our consultants