Recommended steps to create connectors

<< Click to Display Table of Contents >>

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

Recommended steps to create connectors

Overview

There are two types of connectors (Assisted REST and Custom) as described at Creating connectors.

This section presents a high-level sketch of steps you should carry out to create connectors.

 

Before you start

It is very important that you first understand the API of that system or application you want to integrate to.

Pay special attention to the type of authentication used by that given API.

This means that you will need to browse the official documentation of that external system or application.

 

This information regarding the supported authentication methods should give you indications on whether you may create an Assisted REST Connector or if you will need to create a Custom Connector.

For detail about when you will need a Custom connector, refer to Authentication methods and REST connectors.

 

Recommended steps

We recommend you follow the recommended steps specific to the type of connector, in order for you to plan accordingly:

Steps to create Assisted REST connectors.

Steps to create Custom connectors.

 

Steps to create Assisted REST connectors (Easy mode)

When choosing to create an Assisted REST connector, these are the high-level steps you need to accomplish:

 

1.Ensure you have a valid account and authorized access to your external application from other applications (i.e, valid username and password, plus access tokens and further settings in that external application).

2.Use the Connector Editor to create a new REST connector (Easy option).

 

ConnectorEditor_REST00

 

3.Enter details of that new connector, including its supported authentication method.

 

REST_3

 

4.Create at least one action and specify its details.

 

REST_1

 

 

note_pin

In this step it is very important that you define its service URL (with all due query string parameters), its invocation method (GET/POST/PUT/DELETE), its content type, and if the action uses authentication or not.

 

5.Define inputs, as needed by your connector and supported by the API of the external system/application.

 

REST_7

 

6.Define outputs, as needed by your connector and supported by the API of the external system/application.

 

REST_8

 

note_pin

In this step you may define the structure for error messages as well.

 

7.Download the connector.

 

REST_9

 

 

Once you have it as a .bizc file, next steps are installing it and testing it from Bizagi Studio, as described at Installing and configuring connectors.

 

Steps to create Custom connectors (Expert mode)

When choosing to create a Custom connector, these are the high-level steps you need to accomplish:

 

1.Ensure you have a valid account and authorized access from applications to your external application (i.e, valid username and password, plus access tokens and further settings in that external application).

2.Browse for a reusable connectivity library at npm.

Ensure you find one at www.npmjs.com that is reliable (e.g by analyzing its popularity, open issues and its documentation, etc) and that you can use according to its license (e.g, MIT).

 

Custom_1

 

3.Package the connectivity library.

If you found a reliable library that suits your needs, ensure you download and package it via npm (the final package should be a .zip file). Otherwise you need to code it and still package it as a portable/reusable library.

To download and package a library, you will need to install npm in your machine, as described at Required profile, concepts and tools.

 

note_pin

Do not download the library directly from the browser, as it might not download with all its dependencies (if that library in turn uses other libraries which are not packaged inside). This will result in an incomplete/invalid library.

 

Packaging the library is done via a console prompt with admin rights as shown below (through the npm install <library-to-download> --greedy command).

Note you should execute this command from the folder you choose as the download destination; because otherwise it will be placed among your system32 path/files.

 

NODEJS_Npmcommand

 

 

note_pin

Keep in mind that the .zip file of the library you package, must have the following structure:

1. All dependencies and libraries in a flattened structure (non-recursive and non-hierarchical).

2. There must not be an intermediate folder.

The .zip file extracts these multiple folders (one for each library or dependency).

 

Npm_forecastzip

 

4.Use the Connector Editor to create a new Custom connector (Expert option) and enter details of that new connector.

 

ConnectorEditor_Custom00

 

5.Import the connectivity library.

 

Custom_5

 

 

6.Configure global parameters.

Mandatory parameters to manage at this point, are Authentication parameters:

 

Custom_9

 

note_pin

If the authentication itself has to be customized you can edit the auth.js file pressing the </> auth.js button.

 

Optionally, define the Connector and Errors parameters.

 

Custom_7

 

 

7.Create at least one action and specify its details.

 

Custom_12

 

8.Define inputs as defined by the API of the external system/application.

 

REST_7

 

 

 

9.Define outputs as defined by the API of the external system/application.

 

Custom_13

 

10.Implement the invoke function.

Write your own code to implement how to translate that action into invoking a method at the external application.

Do this in the invoke function and by making use of Bizagi API for connectors.

 

dashboard_patch_B_frame4

 

11.Download the connector.

Once you have it as a .bizc file, next steps are installing it and testing it from Bizagi Studio, as described at Installing and configuring connectors.

 

note_pin

Additionally and as best practices, consider these recommendations:

 

1. A downloaded connector will include proprietary Bizagi libraries (bz-util) which provide the API for connectors as well as other methods and general framework to connect to RESTful services.

You should never modify this library, and keep in mind that Bizagi Ltd will not support nor guarantee compatibility for connectors which use a modified bz-util library. At anytime Bizagi Ltd may modify or update the contents of this bz-util library or any related others, considered by Bizagi to successful run connectors in a secure and optimal manner.

 

2. You should include license information inside of the readme files of the connector (or alternatively, in the description text).

Recall that some libraries you may reuse in your connectors are available at www.npmjs.com (and most are MIT-licensed), may demand the use of a link to its source or other license clauses.