Top
Top
LibraryEASYProcess Reference ManualAPISSOAP API
Creating a SOAP API
Consuming a SOAP API

Training: SOAP APIs

SOAP web services in EASYProcess are essentially just processes that are directly exposed to the internet rather than having to be run from a user interface. We will now create a simple SOAP API that allows the user to create sales order in JDE and the then return order number back to the user.

Step 1: Creating the Process

All EASYProcess API calls are directed to a process when they are called. Therefore, creating a process must be the first step in API creation. Creating a process that will be used as an API is no different than creating a process that is being created to run internally. In EASYProcess, navigate to the “Work with Processes” page either by clicking the Work with Processes button on the application home page or navigating to Process >> Process Home on the top menu. Click the Design New Process button on the top right to begin a new process creation.

Give the process a useful, informative name and description. Here we are making an web service that will look up an order in JDE, so we will name it OrderInfoLookup. Clicking continue on the Add New Process window will create the process and open the new process canvas.

Step 2: Creating Service Contract

The first step you should take after opening the process canvas is to define the SOAP contract. You do this by adding the  ‘SOAPWorkshop/SOAPContract’ service. Inside that service you define the Request and Response as described below.

Request:

See two examples below.

  • Example 1 shows a complex contract vs Example 2 which shows a simpler contract.
  • Objects defined in a contract can go to any depth
  • You cannot use any duplicate names in any node.
  • Use Array attribute as below if you want to mark any data structure to be sent as an Array.
  • The topmost node must be Arguments
  • You can have multiple nodes inside Arguments.
  • You should not have have nodes that will contain values directly inside Arguments. Example 3 is not a valid example.

Example 1:

<Arguments>

        <OrderHeader>

                <BillTo></BillTo>

                <ShipTo></ShipTo>

                <BranchPlant></BranchPlant>

        <OrderHeader>

        <OrderDetail Array=”True”>

                <ItemNumber></ItemNumber>

                <Quantity></Quantity>

        <OrderDetail>

</Arguments>

Example 2:

<Arguments>

<Input>

                <OrderNumber/>

                <OrderType/>

                <OrderCompany/>

        </Input>

</Arguments>

Example 3 (Not Valid):

<Arguments>

        <OrderNumber/>

        <OrderType/>

</Arguments>

For this exercise we can use the XML provided in Example 2 to define our request inputs.

Response:

See two examples below.

  • You can only have one top level node.
  • The data structure defined can go to any depth
  • Every node must be have a unique name
  • If you want any nodes to have multiples, use Array=True attribute.

Example 1:

<Order>

        <OrderHeader>

                <BillTo></BillTo>

                <ShipTo></ShipTo>

                <BranchPlant></BranchPlant>

        <OrderHeader>

        <OrderDetail Array=”True”>

                <ItemNumber></ItemNumber>

                <Quantity></Quantity>

        <OrderDetail>

</Order>

Example 2:

<Address>

<Output>

                <OrderNumber/>

                <OrderType/>

                <OrderCompany/>

        </Output>

</Address>

For this exercise we can use the XML provided in Example 2 to define our response.

Step 3: Complete your process

Go ahead and complete process. The values defined in the Request node of the SOAPContract service will appear in the Recommended Values. This will help in building the rest of the process. At run time, the user-provided input will appear in the exact same format.

Step 4: Specify output using SOAPResponse service.

The SOAPResponse service has a parameter Response that only takes XML as input. Make sure you specify the output exactly you defined it in the Response parameter in the SOAPContract service.

Step 5: Mapping the API to the Process

Once the process is defined it must be mapped to an API name before it can be used as an API. First navigate to the Work with SOAP Web Services page in the top menu by going to API >> SOAP Web Services. In the Add New section at the top of the page provide a name and description for your new web service. Then choose your process from the dropdown and select a security level. Finally, click Add.

This creates the web service, but it is not yet available. To make the web service available on your site, click the Publish button in the middle section of the page.

 

 

Step 5: Calling & Testing the API

Calling an API is done by sending an appropriately formatted request to the URL at which the web service is located. EASYProcess SOAP web services are all hosted at the normal website URL followed by SOAP. The WSDL can be retrieved by going to the website url followed by SOAP?WSDL. This can then be used by a variety of testing tools to test your service.


Preparation

SOAP web services are generally more complicated with their complex data types and xml. We strongly recommend you to first test your SOAP web services using google chrome plug-in Boomerang. This will allow you to prepare XML requests without spending time studying SOAP wsdl. BoomerangUrl: https://chrome.google.com/webstore/detail/boomerang-soap-rest-clien/eipdnjedkpcnlmmdfdkgfpljanehloah?hl=en 

There is a small license fee to use this plugin.

Say you want to call web services at http://www.dneonline.com/calculator.asmx using EASYProcess. Using Boomerang, setup a new project with wsdl = http://www.dneonline.com/calculator.asmx?WSDL and Name = Calculator. Then setup a new request for Add.

SOAP Service : SOAPRequest

SOAPRequest service in SOAP  Services should be used to call a SOAP web service.

This service takes following parameters:

  • Url : Url for SOAP API.

  • Request : Request XML for SOAP method. As stated previously, a request XML is complicated to build and should be based on WSDL given by web services. It is always recommended to use google chrome plugin to get request XML. As in example above, for method ‘Add’, you will get following request from boomerang. You can paste it in Request node in EASYProcess.

<x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">

        <x:Header/>

        <x:Body>

                <tem:Add>

                        <tem:intA>4</tem:intA>

                        <tem:intB>3</tem:intB>

                </tem:Add>

        </x:Body>

</x:Envelope>

You can replace parameters like 4 and 3 with EASYProcess variables : <xsl:value-of select="WorkData/Input/X"/>

  • Headers : You have to add a new header: SOAP:Action. If any additional headers are needed form authentication, you need to study web services documentation for that.
  • ContentType: text/xml;charset=\"utf-8\" (This should be default value).
  • Accept: text/xml
  • Method : POST

        

SOAP Service : Output

Output of SOAP request will be an Xml as below. You can then use Xml Services : LoadFromString with “RemoveNameSpace = True” to load this into an Xml Tree to use inside EASYProcess.

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

<soap:Envelope

        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema">

        <soap:Body>

                <AddResponse

                        xmlns="http://tempuri.org/">

                        <AddResult>7</AddResult>

                </AddResponse>

        </soap:Body>

</soap:Envelope>

SOPA Service : Example

SOAPRequest

<SOAPRequest>

    <Url>http://www.dneonline.com/calculator.asmx</Url>

    <Request><x:Envelope xmlns:x="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">

        <x:Header/>

        <x:Body>

                <tem:Add>

                        <tem:intA>4</tem:intA>

                        <tem:intB>3</tem:intB>

                </tem:Add>

        </x:Body>

</x:Envelope></Request>

    <Headers>

      <Header>

        <Value>SOAP:Action</Value>

      </Header>

    </Headers>

    <ContentType>text/xml;charset=\"utf-8\"</ContentType>

    <Accept>text/xml</Accept>

    <Method>POST</Method>

  </SOAPRequest>

Response

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

<soap:Envelope

        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xmlns:xsd="http://www.w3.org/2001/XMLSchema">

        <soap:Body>

                <AddResponse

                        xmlns="http://tempuri.org/">

                        <AddResult>15</AddResult>

                </AddResponse>

        </soap:Body>

</soap:Envelope>

XML Services : LoadFromString

<LoadFromString>

    <XmlData><xsl:value-of select="WorkData/SOAPRequest/Response"/></XmlData>

    <RemoveNameSpace>True</RemoveNameSpace>

  </LoadFromString>

XML Services : LoadFromString - Output

<LoadFromString>

        <XmlData>

                <Envelope>

                        <Body>

                                <AddResponse>

                                        <AddResult>15</AddResult>

                                </AddResponse>

                        </Body>

                </Envelope>

        </XmlData>

</LoadFromString>


Powered by EASYProcess (© 2019 K-Rise Systems, Inc).