Diagnosing Web services errors

<< Click to Display Table of Contents >>

Navigation:  Automation Server > Automation Server configuration and administration guide > System maintenance and monitoring > Environment settings and administration > Management Console > Diagnosing errors in integrated systems >

Diagnosing Web services errors

Overview

When configuring Web service invocations in Bizagi, you can rely on several features for error control and diagnostics.

One of these features is using Traces whenever you detect there is an issue with the Web service invocation, and you wish to retrieve further detail.

 

Web Services traces

When you are debugging a Web service invocation (in Development environments) or wish to retrieve further details about a failed invocation, youcan turn on the WS Connector traces.

 

WSTrace_all_patch

 

note_pin

Interface traces can be enabled from either Bizagi Studio or the Management Console but we strongly recommend that you enable them temporarily only when you need them, and afterward, disable them.

Changes in this configuration will probably require a reset for your Work portal services.

 

These traces can help you track down at which point the execution fail, since there are six points where details are logged and you can diagnose a problem at your Web service (target's invocation) or when transformations were being applied to the information.

 

Types of traces

The following traces are logged in chronological order:

 

Chronological order

Trace type

Description

1

Request

Writes an XML-structured log with the business information retrieved from Bizagi.

Its name has the following convention:

[case_identifier]_BizAgiSOARequest_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

2

Request transformed

Wirtes an XML-structured log with the result of an applied transformation (either a custom XSLT or out-of-the-box mapping functions), to the business information retrieved from Bizagi.

Its name has the following convention:

[case_identifier]_BizAgiSOARequestTransformed_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

3

SOAP Message body - Request

Applies for invocations to SOAP Web services (RESTful services not included).

 

Writes information in a log with details regarding the invocation, including information sent in the request.

Its information is logged in a file with the following naming convention:

SOAP_TraceVersion02_[timestamp].svclog

The timestamp is set as yyyyMMddHHmm.

 

In earlier Bizagi versions, it logs the XML body content of the information just as it is sent to the external system and without the SOAP header information.

4

SOAP Message body - Response

Applies to invocations to SOAP Web services (RESTful services not included).

 

Writes information in a log with details regarding the invocation, including information received from the response.

The information is logged in a file with the following naming convention:

SOAP_TraceVersion02_[timestamp].svclog

The timestamp is set as yyyyMMddHHmm.

 

In earlier Bizagi versions, it logs the XML body content of the information just as it is received from the external system and without the information contained in the SOAP header.

5

Response

Writes an XML-structured log with the returned business information, just as returned by the web service.

Its name has the following convention:

[case_identifier]_BizAgiSOAResponse_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

6

Response transformed

Writes an XML-structured log with the result of an applied transformation (either a custom XSLT or by means of out-of-the-box mapping functions), to the business information returned by the web service.

Its name has the following convention:

[case_identifier]_BizAgiSOAResponseTransformed_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

 

Two additional traces are available to help verify how the inputs and outputs were mapped when configuring the integration.

 

Trace type

Description

Request mapping JSON

Useful mainly on production environments, as it is the immediate way to verify how the mapping was configured.

 

Writes a JSON-structured log with information of how the mapping is done for the input parameters (including any transformation functions).

Its name has the following convention:

[case_identifier]_BizAgiSOARequestMapping_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

Response mapping JSON

Useful mainly on production environments, as it is the immediate way to verify how the mapping was configured.

 

Writes a JSON-structured log with information of how the mapping is done for the output parameters (involving transformation functions).

Its name has the following convention:

[case_identifier]_BizAgiSOAResponseMapping_[timestamp].json

The timestamp is set as yyyyMMddHHmm.

 

Additional measure oriented to error control

We strongly recommended that you also define the service's expected time, so that you can explicitly assign both: a timeout for the service, and a logging threshold.

The logging threshold parameter for interfaces writes a log to alert you about interfaces whose invocations are delaying more than expected. In this way, you can perform early diagnostics on your Web service and any additional variables affecting its performance.

The timeout thrown in a service invocation is due to the service delaying more than its timeout definition.

For a service invoked in an asynchronous activity, the timeout definition is taken from the minimum time set from either: the timeout property set for the asynchronous task, or the timeout property set for the specific interface (through interfaces administration in the systems module).

 

For more information about these two2 options, refer to Interfaces administration.

 

How to trace your Web service?

With the following steps, we will illustrate how to use the interface invocations trace to detect and diagnose issues in external Web services invocations.

 

1. Detect the error

As a most common practice, you may find that your Web service is invoked from an Asynchronous Activity.

Should the invocation fail, further error detail can be viewed from the Admin menu, in the Asynchronous Activities console option.

 

WSTrace_console

 

 

2. Setup trace configuration

Through the Tracing options, enable all interfaces traces.

 

 

3. Re-run the interface invocation (to log the error details)

Retry the invocation of the interface to generate a log with error details.

 

On your Bizagi server, browse into the SOA interfaces traces folder (in this .NET example, the location would be C:\Bizagi\Projects\[project_name]\SOA).

 

You will not have all the files recorded.

For example, if an error occurs in the extraction of data from Bizagi, only the first file (Request mapping) appears because the error occurred before the request was made.

 

4. Validate the traces to identify the error

Validate information contained in the traces.
 

If you find that all of the files are there, and the error seems to be when Bizagi calls the Web service, you can review the SOAP_TraceVersion02_[timestamp].svclog or send it to our support team.

 

WSTrace_svclog

 

You can view this log can be viewed with the SvcTraceViewer provided by Microsoft within its 4.0 .NET framework.

 

WSTrace_prog