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:
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.
2. Actions and work area
In this section, the actions defined for the connector are displayed while showing their properties.
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.
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.
|
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. |
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.
|
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 
icon will appear on the right side. To add new elements to a particular structure, click the 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).
Add one by one the input parameters until you have obtained the desired structure.
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):
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).
Global parameters allow you to specify generic properties to be used by any action within the connector.
Manage such parameters by adding them, deleting them or editing them (such parameters use a name, default value, required and Field encryption properties).
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)
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:
•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)
•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"]));
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.
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
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:
 | Proxy 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:
| Proxy 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.
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.
3. Click the Test button.
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.
Last Updated 1/9/2024 11:24:50 AM