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.
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/).
|
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/.
When installing npm, required components are the Node.js runtime, and the npm package manager:
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).
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):
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:
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).
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).
|
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):
|
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
|
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:
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):
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.
Select the Expert mode and input basic details of your connector:
At this point and before you actually get into implementing your connector, you may want to make sure 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).
|
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:
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):
|
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):
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:
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):
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:
|
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):
|
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:
|
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.
|
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):
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.
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.
|
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 make sure 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)
|
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.
|
Bizagi may use cached information in execution, which is optimized for a production environment. In order to avoid cache issues in your development environment, especially when performing roundtrips and changes in your connector, make sure 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:
Then, make sure 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:
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).
Configure its use as an activity action at the On Exit timing of the first activity:
When configuring its inputs, make sure you map latitude and longitude:
And make sure you map response as output.
|
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):
Download this tutorial's connector
The built forecast connector example is available for download at:
http://download.bizagi.com/connectors/forecast/forecast.io.bizc.