$Services

Overview

const $Services;

SOAP Service Calling Walkthrough

First of all you need to introduce the web service to the process where you want to call its methods. To do so, on the main design page of process, create a new web service record and enter its address. After saving it, click on the newly created web service icon to reach its details page. On this page you can discover web service's methods, see details on how to call them, and edit the web service configuration. Upon creation, the web service methods gets automatically discovered.

Some web services may require a basic authentication to let you access and discover the service. In that case you should register the web service authentication information to Emakin as the following:

Go to System Administration folder and start Edit Domain task,

On the main page, click on the Security tab,

On the opening section click on the URL Credentials tab,

Fill in the address, user name and password information and save the form.

After saving these credentials, when you discover the service and call any of its methods, these credentials will be passed to the service automatically.

Service Snippets

After adding a SOAP service wsdl into a process, a details page of that service is generated automatically. You can access this page by clicking on the related web service icon on the main page of process design editor.

On this page, there is a discover button and a table listing the methods of the web service. When any change is made on the web service, you can use discover button to update your web service definition.

Click table's details button to view all the methods and again details button of any method to see its snippet on how to call it. You can also switch the snippet between XML / JSON input type using XML / JSON button.

Example

Calling with JSON content type

try {
    result = $Services.webServiceName.endPointName.methodName({
        param1: {
            param1_b: "2019-01-01",
            param1_a: "someText",
            param1_c: 50
        },
        param2: "someOtherText",
        param3: "119-229334"
    });
}
catch (e) {
    console.warn(JSON.stringify(e));
}

Example

Calling with XML content type

try {
    result = $Services.webServiceName.endPointName.methodName('<tem:query PageIndex="1" PageSize="25" xmlns:tem="http://tempuri.org/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">' +
        '<tem:StartDate>2018-01-01</tem:StartDate></tem:query>');
}
catch (e) {
    console.warn(JSON.stringify(e));
}

Sending additional header information

All standard SOAP headers are automatically handled by the system, but in some scenarios you may need to set additional SOAP headers transfer information.

While invoking service, after specifying request body you may give secondary object to headers body. If service definition has matching header by name, specified value is imported to the SOAP message.

Example

Sending additional header - JSON Example

try {
    result = $Services.webServiceName.endPointName.methodName({
        param1: "someText",
        param2: "119-229334"
    }, {
        myHeader: "myHeaderValue"
    });
}
catch (e) {
    console.warn(JSON.stringify(e));
}

Invocation Options

All service methods are supports a "return" parameter to controlling invocation and return value for monitoring request or response.

Monitoring Request

Following sample requests the soap envelope message to be sent to web service.

Example

Sending additional header - JSON Example

var result = $Services.webServiceName.endPointName.methodName({
    param1 : "someText",
    param2 : "119-229334"
}, null, {
    "return" : 'request'
});

// result is set to soap:Envelope with request body

Monitoring Response

Following sample requests the soap envelope is returned from web service.

Example

Sending additional header - JSON Example

var result = $Services.webServiceName.endPointName.methodName({
    param1: "someText",
    param2: "119-229334"
}, null, {
    "return": 'response'
});

// result is set to soap:Envelope with response body

Using web service response data

As SOAP web services return XML data, you can call Emakin's $XML methods on the response object to process any part of that response data.

Depending on the web service response structure, you might also need to add a namespace to the response data as seen below.

Example

try {
    result = $Services.webServiceName.endPointName.methodName(...);
 
    result.AddNamespace('', 'http://xmlns.oracle.com/oxp/service/PublicReportService');
    result.SelectAll('TablePath/RowPath', function(rowNode) {
        console.info(rowNode.Evaluate('property'));    
    });
}
catch (e) {
    console.warn(JSON.stringify(e));
}