Bizagi API for connectors

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Integrate > Application integration > Integrating APIs and extending Bizagi > Bizagi connectors > Creating connectors > Custom connectors >

Bizagi API for connectors

Overview

When creating your own Bizagi connectors, and specifically a custom connector, you will need to write your own code, as described at Custom connectors.

In order to do this, it is important that you rely on the API provided by Bizagi when applicable.

 

 

Starting point and API objects

The starting point when creating your custom Bizagi connector is implementing the invoke function as included by Bizagi when defining a new action:

 

Invoke fn

 

 

note_pin

Note you may include additional functions to help you out organize your code. However, what you need to acknowledge is that the invoke function will always be the starting point when Bizagi runs a connector's given action.

 

In this function you may include code as supported by JavaScript and as provided by Bizagi API.

Within the function's input parameters, notice you are provided with the following objects:

 

OBJECT

TYPE

DESCRIPTION AND EXAMPLE

globals

Object

Contains all parameters as defined within the tabs presented in the rightmost panel: Connector, Authentication and Errors.

These parameters are accessed according to the above categories, as:

Connector parameters: globals.systemproperties.[your_parameter]

Authentication parameters: globals.authdata.[your_parameter]

 

Additionally, the project's name is available as globals.projectname

actionName

String

Contains the name of the action you are implementing.

Though it is not commonly needed, the purpose of this information is for you to use for detailed tracing and logging.

data

Object

Contains all values that make part of the defined inputs and the defined outputs.

Access them as:

data.inputs.input.[structure_inside_input] (as defined in your input structure)

data.outputs.output.[structure_inside_output] (as defined in your output structure) or data.outputs.error.[structure_inside_error]

authenticationType

Object

Contains the authentication types supported by your implementation. Though it is not commonly needed, the purpose of this object is for you to check its value to separate the implementation of your action should you need to use more than 1 type of authentication (basic, digest or oauth2).

None can be also valid.

LOG

Object

Manages use of the tracing log.

It provides a set of functions for you to write into the logged detail in different tracing levels (debug, info, error, warn or trace). For example:

LOG.info('detailed_stack');

callback

Function

Refers to the callback function you need to include to notify Bizagi that your invocation has been completed.

It receives mandatory JSON-structured information and its use is typically set as either:

callback(response_information); for a successful invocation

callback(error); should an error occur

 

API (bz-util)

The API for you to use in custom connectors is provided by the bz-util library which is automatically included in every new connector (these part from already having bizagiUtil as: var bizagiUtil = require ('bz-util'); ).

Methods offered by this API are described in the tables shown below.

 

METHOD AND INPUTS

OUTPUT AND DESCRIPTION

EXAMPLE

REQUIRED (string moduleName)

Imports a node.js library (specified by moduleName).

Returns an instance of the object of that imported library.

The following example, imports a node.js library called twit, into a variable set as TwitterService for further use:

 

var TwitterService = bizagiUtil.REQUIRED('twit');

getResponse (JSON response, JSON error, integer statuscode, string errormsg)

Allows you to format a successful response to send it back to Bizagi.

The successful response is to be set in the response JSON-structured parameter, while exceptions require filling in the JSON-structured parameter called error and a legible string-type error message (given by errormsg).

For either successful invocations or those presenting errors, it is recommended to define your own unique status codes (given by statuscode).

This example considers a successful invocation:

var success = bizagiUtil.getResponse({data: {key: ‘s22ssoj44sfj’}}, null, 200, null);

 

This example considers an error during the invocation:

var error = bizagiUtil.getResponse (null, {error: ‘invalid_request’}, 400, ‘The request is missing a required authentication parameter’);

validator.isValidDataJson (JSON json)

Validates if a JSON is well formed, i.e compliant to standard JSON for the data parameter.

Returns an object having a success element set to true if it is, while returns false if it doesn't, and it also pushes the JSON output or error structure accordingly into data.outputs.output or data.outputs.error.

 

The exact structure of the returned object is:

{

   response: {

       outputs: {

           output: {},

           error: {}

       }

   },

   success: true|false,

   connectorstatuscode: 200|?,

   errormessage: ""

}

This example validates the content in globals:

var result = bizagiUtil.validator.isValidDataJson(data);

if (result.success) {
   data = result.response.outputs.output;
} else´{
   callback(result);

return;
}

validator.isValidGlobalsJson (JSON globals)

Validates if a JSON is well formed, i.e compliant to standard JSON, for the globals parameter.

Returns an object having a success element set to true if it is, while returns false if it doesn't, and it also pushes the JSON output or error structure accordingly into response.outputs.error.

 

The exact structure of the returned object is:

{

   response: {

       outputs: {

           output: { globals {...} },

           error: {}

       }

   },

   success: true|false,

   connectorstatuscode: 200|?,

   errormessage: ""

}

This example validates the content in globals:

var result = bizagiUtil.validator.isValidGlobalsJson(globals);

if (result.success) {
   globals = result.response.outputs.output;
} else´{
   callback(result);

return;
}

error (string errorId, object[] detail)

Allows you to format an error so that you catch and manage it.

Error information gets structured with a main error identifier (errorId) and having further detail such as error code and detailed message.

This example formats an error message with a status-code 500:

 

var errormsg = bizagiUtil.error('OBJECT_REF', [500, 'Unsupported parameter value or unknown data']);

LOG.error (object[] detail)

Logs the detail provided in the message for error-level tracing. Notice you may concatenate into an array multiple texts.

The following 2 examples are valid:

LOG.error (['Error 009']);

LOG.error ('[My connector] Error:', error, {'invalid request'} ]);

LOG.debug (object[] detail)

Logs the detail provided in the message for debug-level tracing. Notice you may concatenate into an array multiple texts.

Same use as in LOG.error()

LOG. warn (object[] detail)

Logs the detail provided in the message for warning-level tracing. Notice you may concatenate into an array multiple texts.

Same use as in LOG.error()

LOG. trace (object[] detail)

Logs the detail provided in the message for basic tracing. Notice you may concatenate into an array multiple texts.

Same use as in LOG.error()

LOG.info (string[] message)

Logs the detail provided in the message for information-level tracing. Notice you may concatenate into an array multiple texts.

Same use as in LOG.error()

 

 

Best practices

Consider the following best practices:

 

1. Importing libraries

Always use REQUIRED() instead of require() to import your libraries.

The only library (the only exception) which is imported by using require() is Bizagi API which is always seen in the first coded line:

var bizagiUtil = require('bz-util');

Afterwards, and other than this one, the use of the REQUIRED() method of the bz-util library, ensures that your libraries are imported by using Bizagi's API which validates for dependencies.

For example, you will be then using:

var TwitterService = bizagiUtil.REQUIRED('twitter_library');

 

2. Tracing and logging details

Always use those traces and log capabilities offered by Bizagi API, which can be turned off and on by means of settings in Bizagi.

Ensure that you define accurately such information (the right amount of tracing, useful and legible information at best, etc), and do not log details into another destination.

 

3. Status code nomenclature

We recommend using the following ranges for status codes.

Status codes from 400 to 500: To declare issues during authentication.

Negative status codes: To declare exceptions in the logic of your invocation.

200 status code: Should be specified for a successful invocation.

 

4. Bz-util unchanged

We strongly recommend you to avoid modifying the bz-util library (provided as-is).

Any modifications done to this library are not supported by Bizagi.