Custom connector example

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Integrating external applications from Bizagi > Bizagi connectors > Integration Hub > Creating connectors > Connector Editor user interface explained > Custom connectors >

Custom connector example


This section illustrates a step-by-step example that creates a Custom connector.

The example will post a new message in Twitter from a Bizagi process.

For more information about this feature, refer to Custom connectors.


Before you start

Recall that in order to connect to cloud services such as those provided by Twitter, you usually need a valid application granted with enough rights to access your account. For further information,  review the section on creating an application and obtaining authorization credentials in the article Configuring and Using the Twitter Connector.


Creating and Configuring the Process in Bizagi Studio

For this purpose and to illustrate its potential, we will emulate an online newspaper company publishing links to their news in their Twitter account.


We will use the following process:




The idea behind this process is that every time a new case is created, the news is published (in an URL) along with setting a predefined number of time for which the news will be announced via Twitter (every 2 hours). Note also that this case can be canceled at any time.

To configure the connector with this process, we will illustrate how to implement the process, and then how to use the connector in it.


Implementing the process

Based on the BPMN model of the process as shown above, further implementation details will consider the following aspects:


1.Use this data model:




2.Configure the wait time of the timer in the Process Model.




3.Define the form for the Register News task.




4.Define the form that manages information of the news:




5.Configure logic in the gateway (allowing to publish again only when the total of previous publications has not exceeded that predefined amount):






6.Define a rule to be executed for the Register news task (which assigns the current date and user):




//Case information

 <MediaPublicity.Newsregistrydate> = DateTime.Today;
 <MediaPublicity.Newsregistryperformer> = Me.Case.WorkingCredential.UserId;


7.Define a rule to be executed for the Publish news through Twitter task.




Select a random message to post in Twitter (from a list of predefined ones):

var MessagesEntity = CHelper.GetValueAsCollection(<MediaPublicity.Messagestopublish>);
var MessagesAmount = MessagesEntity.size();

var randNumb = CHelper.Math.Rand(0,MessagesAmount-1);
var MessageToPublish = MessagesEntity.get(randNumb).getXPath("Message");





Increase the total of published links:

<MediaPublicity.Currentpublication> = <MediaPublicity.Currentpublication>+1;


Creating the connector

To create a Twitter connector, we illustrate how to first find a library to connect and then how to rely on that library through a new connector.


1. Finding a Node.Js library

Download from, a Node.Js library to be used as a connection driver within the connector.


Refer to the documentation of the libraries themselves, or even their code, to pay special attention to how the libraries are used, including the configuration of input and output parameters.


In this example, we will use the twit library (created by ttezel).









If not enough documentation is presented regarding the output structure and further optional parameters, you may always browse as well the application's API.

For this example you can review:

API Documentation:

GitHub repository with sample codes:  




2. Creating a new Custom connector

Access the Integration Hub and create a new custom connector with these steps.


a.Add the downloaded libraries to the connector. For this example, the twit library is added to the connector.




b.Add the authentication parameters.





Since these parameter values will hold sensitive information, field encryption should be used.

This will change the input of the values in Bizagi Studio from a simple text field to a password field (making it protected when attempting to retrieve the values stored in these parameters).


c.Add an Action and set its properties. Keep in mind that its Name and Description will be shown when configuring the use of the connector from within processes.




d.Define the Inputs structure (you do not need to include all fields; only those you detect are mandatory and make sense for your connector).




e.Define the Outputs structure (you do not need to include all fields; only those you detect are helpful).




f.Add the code of the action to specify its behavior.




In this example, the following code is used (click to expand and view it):


hmtoggle_plus1Show Action code


g.Save the connector.




3. Testing the connector

In this part, a series of steps are performed with Bizagi Studio to have a process that uses this connector.



In this article, we consider an example process that illustrates the potential of this point connector.

For this step, you should know about the use and basic options of Bizagi Studio, and keep in mind that you should not necessarily use this same process to test this connector.


Configuring the connector

Once you have created your connector, configuring it and using is done with Bizagi Studio.


Now that the process is ready to use the connector, plug the connector into the process through these steps:


1.Go to the Expert view and into External Systems and open the Connectors API.




2.Select the new connector shown in the tree menu, and either right click the version to add a New System Configuration, or use the New System Configuration in the ribbon.




3.Give the new configuration a name and description. Make sure you also select the Authentication method drop down list and select custom to configure it. Enter the API Key, API Secret, Access Token and Access Token Secret, as given by your Twitter account. These credentials will now be used every time an action of the connector is executed.




4.Go back to the wizard view and select the forth step (Activity Actions). Add a connector action execution at the exit of the task by selecting the task and choosing the Connector option in the On Exit drop down list.




5.Select the connector and then the action to be executed.




6.Map the inputs.





Since Currentmessage and URL are separated attributes to go into a single parameter, you need to concatenate them.

To better display them, a constant defining a blank space is included between them.


7.Map the outputs and click Finish.





Launch Bizagi Work Portal to execute and test the connector for this process.

Create a new case, and register the news with an URL. Then add some messages to publish the specified news.




Click Next when done.


At this point you will notice that a new tweet will be published with the message and the URL of the news.