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 service 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.
|
Keep in mind that Interfaces traces can be enabled anytime, but it is strongly recommended to enable them temporarily only when needed (and afterwards, disable them). Changes in this configuration will most likely require a reset in your Bizagi server's services. |
Enabling these traces is useful to track down, after an error in the application, the exact point where said error has happened. There are six 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, two 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.
These properties can be set at the specific interface's properties:
•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).
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.
2. Setup the traces configuration
Through the Tracing options, enable all of the Interface's traces.
3. Re-run the interface invocation (to log the error detail)
Retry the invocation of the interface from the asynchronous activities console to have a log with detail.
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.
Last Updated 1/30/2024 4:09:31 PM