Web services error control and diagnostics

<< Click to Display Table of Contents >>

Navigation:  Bizagi Engine > Bizagi system administration > Maintenance and administration > Environment administration > Error control and diagnostics >

Web services error control and diagnostics

Overview

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

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

 

 

Web Services traces

Whenever you are debugging a Web service invocation (in Development environments) or whenever you wish to retrieve further detail about a failed invocation, you may choose to turn on the WS Connector traces.

 

WSTrace_all_patch

 

note_pin

Keep in mind that Interfaces traces can be enabled from either Bizagi Studio or the Management Console but it is strongly recommended to enable them temporarily only when needed (and afterward, to disable them).

Changes in this configuration will most likely require a reset in your Work portal services.

 

Enabling these traces is useful to track down at which point exactly did the execution fail, mainly because there are 6 points where detail is logged and you may diagnose if there is a problem at your Web service (target's invocation), or whenever transformations were being applied to the information.

 

Types of traces

The following traces are logged with a chronological order, as detailed in the table below.

 

Chronological order

Trace type

Description

1

Request

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

Its name has the following convention:

[case_identifier]_BizAgiSOARequest_[timestamp].json

Note that timestamp is set as yyyyMMddHHmm.

2

Request transformed

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

Its name has the following convention:

[case_identifier]_BizAgiSOARequestTransformed_[timestamp].json

Note that timestamp is set as yyyyMMddHHmm.

3

SOAP Message body - Request

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

 

Leaves information in a log with details regarding the invocation, specifically considering information sent in the request.

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

SOAP_TraceVersion02_[timestamp].svclog

Note that 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 for invocations to SOAP Web services (RESTful services not included).

 

Leaves information in a log with details regarding the invocation, specifically considering information received from the response.

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

SOAP_TraceVersion02_[timestamp].svclog

Note that 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

Leaves 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

Note that timestamp is set as yyyyMMddHHmm.

6

Response transformed

Leaves an XML-structured log with the result of an applied transformation (either a custom XSLT or by means of the 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

Note that timestamp is set as yyyyMMddHHmm.

 

In addition to the above, 2 additional traces are presented as an aid to verify how the inputs and outputs were mapped when configuring the integration.

 

Trace type

Description

Request mapping JSON

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

 

Leaves 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

Note that timestamp is set as yyyyMMddHHmm.

Response mapping JSON

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

 

Leaves 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

Note that timestamp is set as yyyyMMddHHmm.

 

 

Additional measure oriented to error control

It is 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 leaves a log to alert you about those interfaces whose invocations are delaying more than expected (more than usual). 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 2 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 the traces configuration

Through the Tracing options, enable all of the Interfaces traces.

 

 

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

Retry the invocation of the interface to have a log with detail.

 

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

 

It is important to note that not for all cases, you could have all the files recorded.

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

 

4. Validate the traces to identify the error (one by one)

Validate information contained in these traces.
 

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

 

WSTrace_svclog

 

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

 

WSTrace_prog