Projects manage their information in a variety of systems. For example, a DMS for document management, CAD software for designs, GIS software for geo-information and an SE tool for requirements. It is often necessary to display information from one system in another via a web service. What does it take to create a web service for a different system? And how do you make sure that the information that is required by the other system is send?
This article describes how to make a web service that allows another system (e.g. CAD software or GIS software) to use a parameter for a system object to receive the related requirements from Relatics.
Step 1: Make a report with all requirements per system object
The first step is to create a report. It is advisable to create a separate web service for each topic (e.g. requirements, system objects, activities, etc.). This gives the other system freedom of choice and allows for faster performance due to the smaller dataset per web service. The image below shows a created report that, given a system object, displays the relevant requirements. It is important to set the OutputExtension to XML. This is because the Relatics web service uses the SOAP protocol that sends XML messages.
Step 2: Make a web service and link the report
Once the report is complete, you can configure the web service. This is done by creating a server for providing data web service and linking it to the report. It is important to enter the OperationName, because this is needed to call the web service. The most commonly used authentication type is Entry code validation, meaning that a user can receive the data from the web service using a password. A tip here is to use a secure password consisting of many characters. You can easily generate a password using an (online) password generator.
Step 3: Collect data so that the other system can communicate with the web service
It is a good idea to collect all the data that the administrator of the other system needs to retrieve the information from Relatics using a SOAP web service. Firstly, you need the URL through which the web service can be accessed:
Web service example: URL
It is important here to adjust the first part of the URL (https://my-environment.relaticsonline.com) to the URL used by end users to access Relatics. Secondly, you need to indicate which operation must be called. For the retrieval of information, this is always the same operation:
Web service example: Operation
Finally, it is best to prepare a complete soap request, in which all required XML nodes have been filled out:
Web service example: SOAP request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rel="http://www.relatics.com/">
<rel:Operation>Requirements per System Object</rel:Operation>
<rel:Parameter Name="SystemObjectGUID" Value="7c48af84-1c84-e711-80ee-000af753dd43"/>
Four specific XML nodes have been filled out:
- Operation: The OperationName of the web service (example: Requirements per System Object)
- Workspace: The ID of the Workspace, also referred to as WID (example: 34dc8bac-2755-4682-aa8c-5b5b9c732bb0)
- Parameter: The name of the parameter of the report (example: SystemObjectGUID) and a system object ID used as an example (example: 7c48af84-1c84-e711-80ee-000af753dd43)
- Entrycode: The Entry code of the web service (example: 7FBpAkStBCA1qwCigXT9gVh7)
Step 4: Test the web service in an external application
Before sharing the collected data with the administrator of the other system, it is a good idea to test the web service first. Various tools are available on the internet for this purpose. In this article, we use SoapUI:
You can enter the request in the left-hand side of the screen. After running the web service, the result can be seen on the right-hand side of the screen. If the information from Relatics is shown in the result, you have successfully tested the web service. Scan the data to make sure that the web service is complete. If not, then check the required information again.
Upload the following RCS file into your environment to view the elaborated examples of this article:
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