Overview
When configuring Connectors 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 execution of the connector and you wish to retrieve further detail.
Before tracing your connectors, make sure that the Bizagi Connector Service is up and running. Otherwise, the connector does not run, and thus, it does not generate traces.
Connector traces
Whenever you are debugging a Connector's execution (in Development environments) or whenever you wish to retrieve further detail about a failed execution, you may choose to turn on the External connectors traces.
|
Keep in mind that Connectors 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 five points where detail is logged and you may diagnose if there is a problem when executing your Connector, or whenever transformations were being applied to the information.
Types of traces
The following traces are logged as detailed in the table below.
Chronological order |
Trace type |
Description |
|---|---|---|
1 |
Inputs |
Leaves a JSON file with the inputs sent to the Connector before the execution of its logic. Its name has the following convention: [timestamp]_[case_identifier]_IN0_[Connector name]_[action name].json Note that timestamp is set as yyyyMMddHHmmss. |
2 |
Inputs transformed |
Leaves a JSON file with the inputs sent to the Connector after the execution of its logic. Its name has the following convention: [timestamp]_[case_identifier]_IN1_[Connector name]_[action name].json Note that timestamp is set as yyyyMMddHHmmss. |
3 |
Outputs |
Leaves a JSON file with the outputs received from the external system before any transformation done by Bizagi. Its name has the following convention: [timestamp]_[case_identifier]_OU0_[Connector name]_[action name].json Note that timestamp is set as yyyyMMddHHmmss. |
4 |
Outputs transformed |
Leaves a JSON file with the outputs received from the external system after all transformations done by Bizagi. Its name has the following convention: [timestamp]_[case_identifier]_OU1_[Connector name]_[action name].json Note that timestamp is set as yyyyMMddHHmmss. |
5 |
Connector logic |
Leaves four .log files: Connector log •[connector name].[connector name].log stores all the LOG commands found during the Connector logic execution. More information about these commands can be found in this article. Service logs •bz-facade.log stores the history of methods invoked by the Connector Service. •facade-exceptions.log stores the errors raised by asynchronous functions. For example, error in the callback of a REST request. •[connector name]-bz-ctrl.log stores the logs of the connector service controller.
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 connector?
With the following steps, we will illustrate how to use the interface invocations trace to detect and diagnose issues in connector invocations.
1. Detect the error
As a most common practice, you may find that your connector is invoked from an Asynchronous Activity.
If the invocation fails, 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 Interfaces 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.
Then, browse into your Bizagi Server and into the Connectors traces folders (in this .NET example, the locations are typically C:\Bizagi\Projects\[project_name]\Temporary\Connectors and C:\Program Files\Bizagi\Bizagi Studio\ConnectorsService\framework\Logs\Connectors\[project_name]).
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 transformation of inputs from Bizagi, then only the first file (Inputs) will appear because the error occurred before the transformation was made.
4. Validate the traces to identify the error (one by one)
Validate information contained in these traces.
When you install Bizagi, additional to the Connector service, a Windows scheduled task is installed, that constantly monitors the activity of the Connector service, and register in logs if the service is running. If not, this task tries to reset the service, so it can be running up again.
Scheduled task
When you open the Task Scheduler in the Windows server where Bizagi is installed, you can find the Connector Monitor folder, in the Task Scheduler Library.
What this task does, is executing a dummy connector, that verifies that the Connector service is up and running correctly. This task is set to be executed every three minutes, as follows:
|
We do not recommend reducing the repetition time because it can affect the performance of the Connector service. |
The logs associated with this task are stored in the following path:
Bizagi Studio: C:\Program Files\Bizagi\Bizagi Studio\ConnectorsService
Bizagi Engine: C:\Program Files\Bizagi\Engine\ConnectorsService
Here you find the file Monitor.text:
Connectors in Bizagi relay on the Node.js framework, so it is important to monitor that no only the Windows service is running, but also that the framework works correctly. So this task executes two monitor tasks: The first reviews the status of the Connector windows service, the second reviews that the node.js framework works correctly.
Each record in the Monitor log has the following structure:
[TimeStamp] _ [Component] _ [Message]
Time Stamp: WeekDay dd/mm/yyyy HH:mm:ss:ms
Component: Monitor.bat is the result of the windows service request. Flow monitor.bat is the request to the node.js framework.