Custom connector editor interface

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

Overview

Bizagi's connector editor allows you to create connectors from scratch. You can create two types of connectors: Easy REST connectors which require no code (preferred approach), and Custom connectors which allow you to include any third-party libraries and write your own code. The following article explains each section of the interface to create a custom connector.

 

User interface options explained

Either for new connectors or when opening an existing one for modifications, the work area will present the following options:

 

CustomConnector16

 

1. General Connector information

The first section contains overall information about the connector itself. That is, its name, version, author, website URL, description and icon. This information can be modified at any time.

 

CustomConnector17

 

2. Actions and work area

In this section, the actions defined for the connector are displayed while showing their properties.

 

CustomConnector03

 

The left panel lists actions and allows you to manage them (create new ones or delete existing ones). You can edit the name of an action by clicking the pencil icon, or delete one by clicking the trash can icon. When selecting an action, the work area to its right hand displays the implementation details for that action.

Finally, the lower section displays the details regarding the inputs and outputs.

CustomConnector04

 

 

 

3. Inputs and outputs

This section corresponds to the inputs and outputs of the action. The definition for both the inputs and the outputs is done the same.

This means that you have to define a hierarchical structure (compliant to and matching a JSON or XML format) with data types applicable to your service, either as inputs received by that service or as outputs returned by it.

 

note_pin

The data types must match the ones specified by your external system or application's API. Possible simple data types are:

Boolean

Byte

Date

Decimal

Double

Integer

String

 

The data types which are not simple but complex, need to be defined as Object, so that it may contain inner elements which in turn are simple data types or nested Objects as well.

 

CustomConnector05

 

Imagine that your action must receive an input structure as the one shown in the image above:

 

This, viewed from a JSON would look like this:

 

{

 "Main_element": {

   "Information1": "String",

   "Information2": "String"

 },

 "Unbount_element": {

   "Information3": "String"

 }

}

 

 

On the other hand, viewed from an XML would look like this:

 

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <Main_element>
     <Information1>String</Information1>
     <Information2>String</Information2>
  </Main_element>
  <Unbount_element>
     <Information3>String</Information3>
  </Unbount_element>
</root>

 

You have two options to define this structure in the connector editor. You can use the Autogenerate butttotn, or you can enter the structure by hand.

 

The Autogenerate allow you to upload a JSON or XML file with the input or the output definition. To do so, click in the button, select the file that you want to upload and the connector editor automatically generates the corresponding structure.

 

CustomConnector06

 

note_pin

When using the Autogenerate option, only Object and String data types are supported. If your structure has a different data type (e.g. Double), you must import the XML or the JSON file first, and the change the inputs or outputs that have a different data type.

 

The second option is to enter the inputs by hand. The object-type elements, as they are complex, may contain additional elements. This is why for this data-type, the Easy05 icon will appear on the right side. To add new elements to a particular structure, click the Easy05 icon. With this, a new element will appear, on which you can specify the name, the data type, and if it may show up more than once (list) or just one time (single).

 

CustomConnector07

 

Add one by one the input parameters until you have obtained the desired structure.

 

CustomConnector05

 

4. Libraries

Here you can manage the libraries in use by the connector. Notice that any library you import, along with other internal dependencies it may use, you will be able to see in the list, along with the built-in library provided by Bizagi for all connectors (bz-util):

 

CustomConnector08

 

This option imports (bundles into the connector) a given library, though you still need to include the line of code that references that library (i.e analog to an import or using clause when programming in Java or C# respectively).

 

5. Global parameters

Global parameters allow you to specify generic properties to be used by any action within the connector.

 

CustomConnector18

 

Manage such parameters by adding them, deleting them or editing them (such parameters use a name, default value, required and Field encryption properties).

 

CustomConnector09

 

There are three types of Global parameters:

Connector: properties that do not change during the execution of the actions (e.g. the URL of an external system). Also, you can define generic properties that may change depending on the environment where the application is being executed (development, test, production). In this way, you are able to perform each configuration in Bizagi Studio without affecting other mappings or additional connector configurations. To access these properties, you may use the following code: globals.systemproperties.[PropertyName]. Take into account that the brackets are not part of the code line (e.g. globals.systemproperties.SERVER)

 

CustomConnector10

 

Notice that for Connector type parameters, you may rely on a definition of a list of values. In order to do so, input each value in the default value(s) field and use Enter to define many:

 

CustomConnector11

 

 

Authentication: in this section you can define the security parameters that are going to be used within the actions, like the user, the password, the clientId, the clientSectret, etc. To access these properties, you may use the following code: globals.authdata.[PropertyName]. Take into account that the brackets are not part of the code line (e.g. globals.systemproperties.USER)

 

CustomConnector12

 

Errors: in this section you can define customized error messages. Defining error parameters will allows you to use a list of known errors by unique code, in order to provide best error handling capabilities (as different exceptions in your connector's logic), which improves the user experience. To define an error parameter, you must fill the key field, which is a unique identifier for the parameter, and the value field, that corresponds to the error message to be displayed. To access these properties, you must use the following code:

 

var bizagiUtil = require("bz-util");
var ERROR = bizagiUtil.error;
LOG.error(ERROR("<Key>", [Params]));

 

The ERROR function receives two parameters: the key defined in the parameter and an array of strings where the parameters that you want to be resolved are sent. Thus, the above code goes as follows:

 

var bizagiUtil = require("bz-util");
var ERROR = bizagiUtil.error;
LOG.error(ERROR("MYCUSTOMERROR.REQUIRED", ["ID"]));

 

CustomConnector13

 

 

When defining such unique codes for later use, keep in mind that Bizagi already provides a series of error codes which are common for use.

 

ConnectorErrors

 

You should NOT name new errors with the error codes listed below, as these are already in use:

GLB.EXCEPTION

GLB.IS_NOT_A

GLB.IS_NOT_AN

GLB.UNKNOW_ACTION

GLB.RESOURCE_REDIRECT

GLB.RESOURCE_NOT_FOUND

GLB.RESPONSE_ERROR

VAL.REQUIRED_PARAM

VAL.REQUIRED_ELEMENT

VAL.REQUIRED_PARAMS

VAL.PARAM_TYPE

 

Using the proxy configuration

If your custom connector is meant to use the Proxy configuration option it's necessary that you configure the connector so that it works properly with the proxy. To do so, the framework sends a proxy object inside the global parameters of the invoke function. The structure of the proxy object is as follows:

 

tryProxy object structure
{
 "globals": {
   ...
   "proxy": {
     "isEnable": boolean,
     "password": string,
     "port": string,
     "url": string,
     "useAuthentication": boolean,
     "username": string,
     "allowedIps": [
       string
     ]
   }
 }
}

 

With this object is possible to program the HTTP request using the proxy, as in the following example:

 

CodeExampleProxy example
var bizagiUtil = require('bz-util');
var REQUIRED = bizagiUtil.REQUIRED;
var ERROR = bizagiUtil.error;
var RESPONSE = bizagiUtil.getResponse;
var request = REQUIRED("request");

function invoke(globals, actionName, data, authenticationType, LOG, callback) {
 ...
 const proxyUrl = globals.proxy ? globals.proxy.url : null;
 request({
   url: data.inputs.input.url,
   method: "POST",
   proxy: proxyUrl,
   ...
 }, () => {
   ...
 })
 ...
}

exports.invoke = invoke;

 

How to test your connector

the Test option in the Connector editor let you test the actions of without having to download it and execute it in the Work Portal.

To test your connectors action, complete these steps:

 

1. Configure your connector's action. Take into account that depending on the action that you want to test, you will need to configure more parameters, such as the global parameters, the inputs or the outputs.

 

CustomConnector32

 

2. In this case, the action receives a token as a global parameter. To test the connector, it is necessary to give a test value to the parameter.

 

CustomConnector33

 

CustomConnector34

 

3. Click the Test button.

 

CustomConnector35

 

If the definition of your connector is correct, the test outputs tab opens and shows the output that would be sent by the connector during execution.

 

CustomConnector36