Web Services¶

Web services are used to communicate with external systems. You can consume SOAP and REST services in your workflows.

SOAP services must be registered in process definition before using but REST services can be directly called with the $Rest object.

Registering SOAP Service¶

• To add a new service click plus ( + ) symbol in the web services list from the process designer dashboard.
• Enter the web service WSDL address in the URL field.
• After clicking on 'Ok' button, service is automatically discovered in couple seconds, and service methods are displayed on screen.

Service discovery scans the available methods on service and generates usage script in method description.

Test Mode URL This field is optional, you may leave it blank. If you want to use another service for testing environment, you can specify the URL of service. If the workflow instance is in test mode, this address is used automatically. Test and live service definition must be identical, otherwise unpredictable errors may occur.

Service Authentication¶

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, username 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.

Calling SOAP Service with JSON data¶

1
2
3

var result = $Services.webServiceName.endPointName.methodName({
    date : '2018-01-01'
});

Calling SOAP Service with XML data¶

1
2
3
4

var result = $Services.webServiceName.endPointName.methodName(
        '<tem:query xmlns:tem="http://tempuri.org/">' +
        '<tem:date>2018-01-01</tem:date>' +
        '</tem:query>');

Evaluating Service Response¶

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.

1
2
3
4
5
6
7
8
9

var result = $Services.webServiceName.endPointName.methodName(...);

// register service namespace as default
result.AddNamespace('', 'http://somenamespace');

// select all elements
result.SelectAll('TablePath/RowPath', function (rowNode) {
    console.info(rowNode.Evaluate('property'));
});

Using SOAP Service as Data Source¶

Web service registration also can be used as data source in list control (e.g. Dropdown)

After service is registered, add a new data source as "Web Service Query".

Click on "Edit" button to edit the data source. Service method is now displayed on screen and specify input parameters for the service method.

Custom SOAP Headers¶

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.

1
2
3
4
5

var result = $Services.webServiceName.endPointName.methodName({
    date : '2018-01-01'
}, {
    MyHeader: 'MyHeaderValue'
});

SOAP Service Diagnostics¶

In some conditions you may need to monitor the SOAP request and response for debugging or diagnostic purposes. In these cases you can add 3rd parameter to service call to get the raw request and response instead of service reply.

Monitoring Request¶

1
2
3
4
5
6
7

var result = $Services.webServiceName.endPointName.methodName({
    date : '2018-01-01'
}, null, {
    "return": 'request'
});

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

Monitoring Response¶

1
2
3
4
5
6
7

var result = $Services.webServiceName.endPointName.methodName({
    date : '2018-01-01'
}, null, {
    "return": 'response'
});

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