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.
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"?>
<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" />
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
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
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/">
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, the example contains the name of a fictional file.
- 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”.
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:
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.
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.
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