How to create a custom connector -tutorial

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > How To´s > Integration how-to's >

How to create a custom connector -tutorial

Overview

This tutorial will walk you through the steps needed to create a Custom connector for Bizagi.

Custom connectors are distinguished by their offering of allowing you to write your own code.

Such possibility allows you to rely on these features:

Use any type of authentication to connect to an external service.

Include third-party libraries (Node.js packages).

 

Through this tutorial, you will be able to create a Custom connector which does all of the above (includes a third-party library and uses a custom type of authentication, which allows you to implement what the connector does).

The tutorial focuses on how to build the connector though it briefly suggest its use from within Bizagi (you need have basic knowledge on how to implement processes in Bizagi and run them).

The connector is built while using the Connector Editor, as accessible at www.Bizagi.com services.

 

ConnectorEditor_Custom00

 

 

Required profile

In order to make the most of this tutorial and be able to create Custom connectors on your own, you will require the following profile:

Programming skills, namely experience with JavaScript (web-application oriented development).

It is optimal and best if you have worked with asynchronous/event-driven coding practices before (e.g jQuery and AJAX).

Understanding of basic structures such as XML and JSON.

Being familiar with web-based services such as RESTFul services.

Being familiar with package managers such as npm (https://www.npmjs.com/) -or even code/git repositories such as GitHub.

You may need to install npm and use its command prompt options to download and package any open source API (available MIT-licensed libraries for Node.js -https://nodejs.org/en/).

 

note_pin

For more information about the connectors as a feature and this specific type of connector, refer to Custom connectors.

It is strongly recommended that you at least have an overview on Custom connectors, and possibly refer to the API Bizagi offers when coding it.

 

Required tools

For Custom connectors, and given that these will likely rely on third-party libraries, installing npm is required.

Npm is the package manager for Node.js libraries (which means, it allows you to download and pack available libraries at https://www.npmjs.com/, as suggested by its acronym meaning: Node Package Manager)

 

Download and install npm directly from https://nodejs.org/en/download/.

 

NodeJS_download

 

When installing npm, required components are the Node.js runtime, and the npm package manager:

 

NodeJS_install

 

 

Example

The example covered by this tutorial considers invoking a simple forecast service, in which you provide latitude and longitude coordinates to retrieve comprehensive data describing the weather forecast (by default, for the current day).

 

Forecast_mainsite

 

Such information is available at forecast.io as a RESTful service, executable via a browser as https://api.forecast.io/forecast/[API_KEY]/[LATITUDE],[LONGITUDE]:

For example, the service can be invoked by using these coordinates (40.9048938,-74.9462152), which represent New York in U.S.A.

 

The following image illustrates the availability of this service, and a sample response it returns for the above New York coordinates (notice it shows the same information as forecast's main website):

 

Forecast_teaser

 

Notice that the comprehensive response providing forecast details is JSON-structured.

And, you may rely on Google Maps to identify the coordinates in the URL (first latitude, then longitude), of any given place in the world:

 

GMaps_coordinates

 

 

 

Steps outline

These are the high-level steps taken into account by the tutorial, which are all performed outside of Bizagi Studio:

1.Ensuring we have a valid account and access rights for the external service (vary according to the policies of each external service).

2.Downloading a Node.js based connectivity library for that external service.

3.Re-packaging the connectivity library so that dependencies are fit for Bizagi's use.

4.Using the Connector Editor to create a Custom connector. While doing so, these steps are considered:

i.Configuring global parameters (i.e. authentication infrastructure).

ii.Importing the re-packaged connectivity library.

iii.Creating actions and specifying their implementation details (e.g, inputs, outputs and its coding).

 

 

Hands-on

Follow the guided steps described below.

 

1. Ensuring a valid account and access rights.

As with most external services available in the cloud, using them requires an active account on the external service's site, and explicit access rights to invoke these services via their API (mainly due to security reasons).

Therefore and in order to use the forecast.io service, as briefly suggested above, we need to request an access key known as API Key.

 

Obtain an API Key directly at https://developer.forecast.io/, by creating an account (entitles you to use 1000 service calls without charge).

 

Forecast_APIKey

 

Notice that once you create an account and get an API Key, the site already suggests a sample call, shown as a link in the upper blue box, for you to click and test (using Alcatraz' -U.S.A- coordinates as an example).

 

note_pin Quick tips

Always test first the services from outside of Bizagi (e.g directly from a browser or a REST plugin in it), in order to verify that these are operational and so that you can plan accordingly while acknowledging what you expect from the service, at least on a high-level.

 

Notice this page also provides a link to its official API documentation (https://developer.forecast.io/docs/v2), which is necessary for you to understand what the connector will need to do and consider.

 

2. Downloading a Node.js connectivity library

A key potential in having connectors rely on Node.js is the agility to build them while relying on a vast amount of ready-to-use npm libraries.

 

Therefore and in order to browse for such libraries, go to https://www.npmjs.com/.

For the forecast example, browse forecast.io and locate the library for its service (https://www.npmjs.com/package/forecast.io), while identifying its unique name (forecast.io):

 

Forecast_npm

 

note_pin Quick tips

You may want to download reliable libraries, as suggested by their last modification date, number of downloads and reputation, complete documentation, availability of its GitHub repository, number of reported and solved issues, or official support.

If you are still too concerned with a library's reliability, you will need to review and inspect its code.

 

Proceed to download the library by using a command prompt, stepping into the installation path of your npm, and using npm install [unique_library_name].

 

In this case:

npm install forecast.io

 

Npm_forecastio

 

 

note_pin Quick tips

It is recommended that you browse into the path where you want to install your library (i.e, a new folder you create).

You may use a NODEJS_HOME environment variable setting to use npm commands from such directories.

 

Notice you may use the option --greedy if the downloaded structure is not flat enough.

 

Notice how this successful download procedure lists the other libraries that the forecast.io one uses (debug, request and other dependencies of request).

These are all libraries needed for the main library to run.

 

Once the download is completed, you will find all libraries inside the node_modules folder, including forecast.io:

 

Npm_forecastzip

 

3. Re-packaging the connectivity library

This step is needed if the connectivity library has dependencies with other libraries (most likely scenario).

The goal of this step, is to pack the connectivity library into a single .zip file, while ensuring that libraries which are dependencies are located at the same level so that Bizagi includes them all.

 

 

In order to do this, browse into your downloaded connectivity library and into its node_modules sub-folder.

In here, you should see all those dependencies which were listed when downloading the main library via the command prompt.

Create a .zip file that includes dependencies (in this case, there should be 69 in total):

 

Npm_forecastall

 

In the end, you should have a self-contained forecast.io.zip file that depends on no libraries, other than the ones it already bundles.

 

4. Using the Connector Editor

As a last big step, browse into http://connector.bizagi.com in order to create a new Custom connector.

 

ConnectorEditor_Custom00

 

Select the Expert mode and input basic details of your connector:

 

Editor_basic

 

At this point and before you actually get into implementing your connector, you may want to ensure you have grasped everything you need to know about the forecast service specification.

Relevant details to start defining the authentication infrastructure are:

Which type of authentication it uses.

Which parameters are needed for the authentication.

 

Global parameters

Regarding the forecast service, recall that it doesn't rely on a traditional authentication method per se, though it relies on an API Key (to be considered as an authentication parameter).

Docs_APIKey

 

note_pin Quick tips

There is not one single place to look up details or overall documentation regarding how to code the behavior of your connector. It is likely that you may need to browse at: the official service's documentation, the documentation on how to use the connectivity library you downloaded, and also test the service externally to get a better idea of the information it can receive and return.

 

The above implies that for global parameters, we need to define an authentication parameter to store the API Key:

 

Editor_APIKey

 

Library imports

Regarding the forecast service, we import the one connectivity library we re-packaged and which contains all internal libraries as well (you should see many listed in there):

 

Editor_Library

 

note_pin

Importing a library may take a minute or so.

This depends on the size of the library being imported.

 

Implementing actions

Regarding the forecast service and this tutorial, we implement the main service of looking up the weather forecast for the current day.

This means creating one action, which you may call Obtain current weather (by defining in its Properties, the Name and Description):

 

Editor_Action

 

In order to start defining its inputs, outputs or code, browse to the service's documentation or test the service as well.

For inputs, we already know it receives latitude and longitude as parameters:

 

Editor_inputs

 

Notice that defining them as string and single-occurrence are best (string because coordinates may have a preceding negative sign).

For outputs, we may browse the complete documentation. For this tutorial, doing a sample test invocation and working with the test results works.

 

Notice the output is JSON-formatted and you will need to understand its hierarchical structure.
For the tutorial, we will focus on the written forecast summary for the current day (e.g Rainy, Outcast, Clear, Sunny, Windy, etc):

 

Forecast_summary

 

Notice the way to access to such information is by navigating first into the "currently" node and then into "summary".

In order to better understand the JSON-structured response, you may want to rely on online tools that format/beautify it, such as http://www.freeformatter.com/json-formatter.html. The sample image below shows how you can make the response tidier for better legibility:

 

Docs_SampleJSON

 

note_pin Quick tips

In case you are not that familiar with a JSON-structured output, you may rely on online tools that convert from JSON to XML such as http://www.freeformatter.com/json-to-xml-converter.html.

Though this might help you best understand the underlying data structure of the output, recall that the main "root" node is not really there in a JSON-format (it is implicit and actually unnamed):

 

Docs_SampleXML

 

Proceed to define outputs accordingly.

Consider that summary is an inner part of currently, and this means that currently should be defined as an object:

 

Editor_outputs

 

note_pin

Notice how you do not need to create an output structure with absolutely everything that the actual service's response may return. You may choose to include only that information which is valuable to your requirements and scenarios.

 

Finally, write the code that relies on the forecast connectivity library and ends up invoking the forecast service.

To do so, browse the connectivity library's documentation on how to use it.

 

Forecast_libdoc

 

note_pin

Further documentation on the actual service can be looked up at https://developer.forecast.io/docs/v2, which provides complete change-set details and others which are not as relevant for this tutorial.

 

Note there are 3 relevant blocks of code we will be using (and modifying slightly).

Copy and paste those into your connector's code, into the invoke function you need to implement (except the first block which always goes into the outer upper part):

 

Editor_Code0

 

Modify each of the blocks as shown in the images below.

Specific methods used above, and the reasons to use them, are described in the documentation of the Bizagi API for connectors.

 

Block 1:

Using REQUIRED() instead of require() is a best practice so that you rely on Bizagi proprietary methods that load libraries.
 

Editor_Code1

 

Block 2:
Getting the API_Key at execution is done by accessing global parameters, specifically the ones classified as authentication parameters.

This is done throughout the globals object.

Editor_Code2

note_pin

Consider:

The actual API_Key (its value) which will be configured in Bizagi Studio (or managed later on in a production environment with the Management Console).

What comes after global.authdata... needs to match the exact name given by you to that parameter (case-sensitive as well).

In the example above, API_Key is put exactly like that because it was its assigned name during previous steps.

 

Block 3:

Changing latitude and longitude as parameters so that their values are obtained from the data model, is done by using the data object.

Similarly, rely on the LOG object provided by Bizagi for tracing and troubleshooting purposes, instead of other types of logs (i.e instead of "log" in the initial sample code), that are used by third-party libraries.

 

Finally, recall that: you need to format and ensure the response is compliant to what expected by Bizagi by using RESPONSE(), and that you need to notify Bizagi when the invocation has finished via the callback() function (because of asynchronous/event-driven programming)
 

Editor_Code3

 

note_pin

Consider:

Either for an error or successful invocation, callback() is used to notify and delegate Bizagi the response. You should never include a throw clause for error handling blocks.

What comes after data.inputs.input... needs to match the exact name given by you to input structure definitions (case-sensitive as well).

In the example above, latitude and longitude are put exactly like that because these were their assigned names during previous steps.

 

And, that's it!

Use the Download button to save your progress into a local .bizc file with your connector's implementation.

At this point, you may move unto Bizagi Studio to configure the connector and use it within your processes.

 

Editor_Download

 

note_pin Quick tips

Bizagi may use cached information in execution, which is optimized for a production environment.

In order to avoid cache issues in your development environment, specially when performing roundtrips and changes in your connector, ensure you always increase the minor version of it when doing any modification.

This will force Bizagi to acknowledge it is a new implementation, and not rely on its cached information.

 

You may validate that changes were taken, or test quick modifications by accessing the implementation file which is created at

C:\Bizagi\Projects\[your_project]\Tools\connectors\node\[your_connector]\[your_connector_version]\actions\[your_connectors_action].js

 

Configuration in Bizagi

Configure the connector by first importing the .bizc connector file from the Expert view:

 

Installing_2_short

 

Then, ensure you use the API Key that was given to you at https://developer.forecast.io/ (upon the account's creation), in a new system configuration:

 

Forecast_config

 

When done, your connector will be ready to be plugged-in to any process.

This means that in order to test this connector, you only need a dummy process with 3 string-type attributes: latitude, longitude and response (and of course, at least 2 activities in which you first capture the latitude and longitude, and then display the response as a result).

 

Forecast_datamodel

 

Configure its use as an activity action at the On Exit timing of the first activity:

 

Forecast_onExit

 

When configuring its inputs, ensure you map latitude and longitude:

 

Forecast_intputs

 

And ensure you map response as output.

 

Forecast_output

 

note_pin Quick tips

Recall that you may use the built-in tracing options while ensuring that you turn on traces in Bizagi temporarily and watch over your logged detail at C:\Bizagi\Projects\[your_project]\Temporary\Connectors\.

 

When executing your process that uses this connector, you will get a written summary of the weather forecast given the coordinates you entered first (e.g, a latitude of 40.9048938 and longitude of -74.9462152):

 

Forecast_execution

 

 

Download this tutorial's connector

The built forecast connector example is available for download at:

http://download.bizagi.com/connectors/forecast/forecast.io.bizc.