How to call a Web service from Natural

Table of Contents

How to call a Web service from Natural?

Publish a Web service

Prepare and start the XML/SOAP RPC Server

Administrate the XML/SOAP RPC Server with the provided script

Administrate the XML/SOAP RPC Server via Command Central

Steps to call the Web Service from Natural in the Designer

Add the XML RPC Server to the RPC Environments

The RPC Environment Monitor

Extract the Web service information

Download the deployed WSDL

Deploy the XML mapping

Generate Natural client code

Test the Web service

Recommended Reading

This Article is based on EntireX Version 10.3 and NaturalONE 9.1.
The port of the used Web Service depends on the installation. In this tutorial the web service is running on localhost: 9083. This may differ from your installation.

Publish a Web service

Follow all the steps in tutorial “How to publish a NaturalONE subprogram as a Web service”(see Recommended Reading on the bottom of this article).
However, keep the Web service deployed in the end.
I.e. don’t undeploy it as described as the lasts steps of that tutorial.
You will use that Web service in a loopback manner in this tutorial.

Prepare and start the XML/SOAP RPC Server

The XML/SOAP RPC Server can be administrated with Command Central or with local scripts.

Administrate the XML/SOAP RPC Server with the provided script

Start the script jxmlrpcserver.bat from the EntireX bin directory of your installation

This script uses the configuration files entirex.xmlrpcserver.properties and entirex.xmlrpcserver.configuration.xml in the EntireX config directory of your installation. The properties file specifies the Broker and the class/server/service to be used.  The provided properties file will use the default Broker of this installation and RPC/XMLSERVER/CALLNAT.

The XML/SOAP RPC Server will be started in a Command window

Administrate the XML/SOAP RPC Server via Command Central

As an alternative you can use Command Central to configure, start and stop the XML\SOAP RPC Server.
Logon to Command Central and select your installation where you want to run the XML/SOAP RPC Server. Switch to the instance tab to create a new instance for the XML/SOAP RPC Server.



Follow the wizard to configure the new instance for the XML/RPC Server.

The Server Tab

Specify the instance name, the Server Address (use RPC/XMLSERVER/CALLNAT) and a (free) port to administer the XML/SOAP RPC server. Click the tab Broker to continue
 

The Broker Tab

Specify the Broker connection parameter. The password is only required if the Broker is running with security. Click the tab Deployment to continue.
 

The Deployment Tab

Mark to allow dynamic Deployment. Click Next to continue

Verify Settings

 Verify the settings and click Finish to create the instance for the XML/SOAP RPC Server

New instance created

The new instance will become visible in the list of instances. Use the Refresh to refresh the list.

Start the XML/SOAP RPC Server

Click on the instance for MyXMLServer to administrate the XML/SOAP RPC Server. Click on the status to select ‘Start’ from the Lifecycle Actions


This will start the Server and the status will change from red to green.

Steps to call the Web Service from Natural in the Designer

Switch back to the Software AG Designer.

Add the XML RPC Server to the RPC Environments

Open the Preferences dialog via menu Window >> Preferences.


 

Choose Software AG >> EntireX >> Web Service >> RPC Environments
 

Check if the entry for RPC/XMLSERVER/CALLNAT already exists. If yes continue with the RPC Environment Monitor.
If the entry does not exist hit ‘Insert’ to create a new RPC Environment.

 Specify your default Broker (i.e. localhost:1971) and use RPC/XMLSERVER/CALLNAT as the Server Address.
Press Finish.

The RPC Environment Monitor

The XML RPC Server now appears on the RPC Environment Monitor. If the monitor is not visible, open the respective view in the EntireX perspective.

If the XML RPC Server is not displayed, refresh the monitor with the refresh button.

Extract the Web service information

Within the Travel project; create a new Natural Library “T2OUTBND”.
 

Change to the EntireX perspective.

Get the context menu of our Web service application archive GW2_SRV.aar.

Select Web Services Stack >> View deployed Web Service.

Copy the URL of the WSDL.

On the context menu for T2OUTBND >> RES

Select New >> IDL Extractor for WSDL.

Select “URL” and press “Next >”.  

Paste the WSDL copied before as. Press “Next >”.

Press “Next >”.

Set the Server Name to XMLSERVER. Press “Next >”.

Select Natural on the drop down of the usage with and press “Finish”.

Download the deployed WSDL

Get the context menu of our Web service application archive GW2_SRV.aar.

Select Web Services Stack >> View Web Services Stack…

Click on Services.

Scroll to our Web service (GW2_SRV). Right-click on GW2_SRV and download the WSDL (“Save target as” or the like). Save it into the RES folder, besides the .idl and the .xmm

Save it into the RES folder, besides the .idl and the .xmm.

Select the Travel project. Press F5 to refresh the Navigator view from the file system

GW2_SRV.xml will appear. Rename it to GW2_SRV.wsdl. This is done via the context menu (right-click). See below

Select Rename

Rename it to GW2_SRV.wsdl. Press OK

Deploy the XML mapping

Change back to the NaturalONE perspective

On the context menu of T2OUTBND >> RES >> GW2_SRV.xmm

Select Deploy to EntireX XML/SOAP RPC Server

Be sure that you Use an existing RPC Environment for the XML/SOAP RPC Server. This XML/SOAP RPC Server is the part to take your call and transform it into a WS call with the help of the deployed XML mapping file (.xmm). Press Next >.

Verify that the correct Web service URL appears as a subnode. Verify that the correct XML mapping file appears as another subnode of the Web service URL

Verify that the Target Service URL is correct. Verify that the Mapping Details are correct. Press Finish

Generate Natural client code

Ensure that you are in the NaturalONE perspective

On the context menu of T2OUTBND >> RES >> GW2_SRV.idl

select Generate Natural from Software AG IDL >> RPC Client

Be sure that you use an existing RPC Environment for the localhost:1971@NATSRV2800. The localhost:1971@NATSRV2800 is addressing the Natural runtime that is used for the Natural client code generation. In our case this is the local NaturalONE runtime. Press Next >.

Change the Container to end with SRC instead of RES. You want to place the source files in the SRC folder. Press Finish

Verify that 4 files have been generated. Rebuild the project to let the markers/decorators disappear.

GW_SRV.NSN: Subprogram that wraps the WS call. GW_SRV2A.NSA: Parameter data area used by the subprogram. GW_SRV2P.NSP: Sample client program to test the Web service consumption. NATRPCL.NSL: Data Area needed by the Natural RPC runtime

Test the Web service call

Right-click on GW_SRV2P.NSP to open the context menu

Select Run as -> Natural Application

Overwrite the default Server name with XMLSERVER. Specify an input value for GW_Location. Press F5 to execute

Verify that the Web service call has been successful

Recommended Reading