Custom connector example

<< 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 >

Custom connector example

Overview

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.

This means for this specific scenario, creating an app directly at https://apps.twitter.com/.

 

Register your application in order to obtain authorization credentials (which will be used later on).

 

example_custom_10

 

You should be provided with: an API Key, API Secret, Access Token and an Access Token Secret.

 

example_custom_9

 

And your app will end up being granted to access your account, which is verifiable at https://twitter.com/settings/applications.

 

Steps

The high-level steps we will illustrate in this example are:

1. Creating the connector: Steps needed to produce the connector relying on Node.js libraries and overall technology (using www.npm.com and the Connector Editor).

2. Testing the connector: Steps done with Bizagi Studio to have a process where we can use that connector.

 

note_pin

Step #2 considers a sample process aimed to illustrate all the potential of the use of this specific connector.

Although for this step you will need to have basic understanding of Bizagi Studio and its options, note that it is not required to use the same process as depicted in this example to test the connector.

 

1. Creating the connector

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

 

1.1 Finding a Node.js library.

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

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

 

Refer to its documentation or the code itself to pay special attention to inputs, outputs and authentication parameters as used by this library.

 

example_custom_11

 

example_custom_12

If not enough documentation is presented regarding the output structure and further optional parameters, you may always browse as well the application's API (e.g https://dev.twitter.com/rest/reference/post/statuses/update).

 

example_custom_32

 

1.2. Creating a new Custom connector.

Access the Connector Editor and create a new connector with these steps.

 

 

a.Add the twit library to the connector.

 

example_custom_14

 

b.Add the authentication parameters.

 

example_custom_15

 

note_pin

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.

 

example_custom_16

 

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).

 

example_custom_17

 

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

 

example_custom_18

 

 

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

 

example_custom_19

 

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

hmtoggle_plus1Show Action code

 

g.Download the connector as a .bizc file.

 

example_custom_20

 

 

2. Configuring the connector

Once you have created your connector, configuring it and using is done with 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:

 

example_custom_1

 

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). And, 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.

 

2.1 Implementing the process.

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

 

a.Use this data model:

 

example_custom_2

 

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

 

example_custom_28

 

c.Define the form for the Register News task.

 

example_custom_3

 

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

 

example_custom_4

 

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

 

example_custom_5

 

example_custom_6

 

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

 

example_custom_7

 

//Case information

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

 

g.Define a rule to be executed for the Publish news trough Twitter task.

 

 

example_custom_8

 

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");

Me.setXPath("MediaPublicity.Currentmessage",MessageToPublish);

 

Increase the total of published links:

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

 

 

2.2 Configuring the connector.

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

 

a.Go to the Expert view and into External Systems. Select Connectors and click on the Add connector from file button.

 

example_custom_21

 

b.Select the downloaded .bizc connector file and click Accept. Then select the new connector shown in the tree menu, and right click version 1.0.0 to add a New System Configuration.

 

example_custom_22

 

c.Give the new configuration a name and description. Ensure you also select the Authentication method drop down list and click on "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.

 

 

example_custom_23

 

d.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.

 

example_custom_24

 

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

 

example_custom_25

 

f.Map the inputs.

 

example_custom_26

 

note_pin

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.

 

g.Map the outputs and click Finish.

 

example_custom_27

 

 

 

Execution

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.

 

example_custom_30

 

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.

 

example_custom_31