Connector Editor user interface explained

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Integrate > Application integration > Integrating APIs and extending Bizagi > Bizagi connectors > Creating connectors >

Connector Editor user interface explained

Overview

Bizagi presents a software development kit which easily allows you to create and modify connectors, called the Connector Editor.

The Connector Editor only requires a browser and internet connectivity (trusted access to www.Bizagi.com).

Recall that there are two types of connectors: Assisted 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.

For more information about these above concepts, refer to Creating connectors.

 

ConnectorEditor_start

 

Main features

Through the Connector Editor you create connectors in an assisted manner, from a starting template.

Main features available to speed up the implementation of your specific integration requirements are:

 

1.Rely on powerful options such as: the possibility to include third-party libraries, using Bizagi API right away, or package and download your final connector.

2.Make the most of an easy-to-use graphic user interface that helps you define the structure of inputs, outputs and error handling.

 

Connector Editor access

Use a browser of your choice to access the online Connector Editor, by typing the following URL:

http://connector.bizagi.comĀ 

 

Getting started with the Connector Editor

The Connector Editor allows you to easily start off by:

Creating an Assisted REST connector.

Creating a Custom connector.

Opening an existing connector.

 

Creating an Assisted REST connector

Create a new connector by selecting the option labeled as Easy:
 

ConnectorEditor_REST00

 

This will prompt you to enter general information for this new connector.

 

ConnectorEditor_REST01

 

OPTION

DESCRIPTION

Icon

The icon shown by the connector (optional), which can be uploaded or modified at anytime by the user while creating the connector.

This image is shown when configuring the connector in Bizagi Studio.

Name

 

The name (mandatory) that identifies the connector when viewed by users.

It can modified at anytime by the user while creating the connector.

Author

 

The name of the author (optional), which can be modified at anytime by the user while creating the connector.

Website (Developer Site)

 

The URL of the author's website (optional), which can be modified at anytime by the user while creating the connector.

Description

 

A meaningful description about what the connector does (optional), which can be modified at anytime by the user while creating the connector.

Authentication Methods

The Authentication method or set of authentication methods enabled for the connector (optional), which can be modified at anytime by the user while creating the connector.

For detailed information about the authentication options at this point, refer to Authentication methods and REST connectors.

 

Once you have defined the basic properties of your new connector, click the Create button.

Options in the work area relevant to Assisted REST connectors show up.

Refer to the sections below for detailed information on the user interface of the work area.

 

Creating a Custom connector

Create a new connector by selecting the option labeled as Expert:

 

ConnectorEditor_Custom00

 

This will prompt you to enter general information for this new connector.

 

ConnectorEditor_Custom01

 

OPTION

DESCRIPTION

Icon

The icon shown by the connector (optional), which can be uploaded or modified at anytime by the user while creating the connector.

This image is shown when configuring the connector in Bizagi Studio.

Name

 

The name (mandatory) that identifies the connector when viewed by users.

It can modified at anytime by the user while creating the connector.

Author

 

The name of the author (optional), which can be modified at anytime by the user while creating the connector.

Website (Developer Site)

 

The URL of the author's website (optional), which can be modified at anytime by the user while creating the connector.

Description

 

A meaningful description about what the connector does (optional), which can be modified at anytime by the user while creating the connector.

 

Once you have defined the basic properties of your new connector, click the Create button.

Options in the work area relevant to Custom connectors show up.

Refer to the sections below for detailed information on the user interface of the work area.

 

Opening an existing connector

When having downloaded a connector as a .bizc file (for instance, if you want to modify and customize an existing connector as made available at the Connector Xchange), you can open it and modify it.

When wanting to modify it  to include some changes or produce a new version, use the Open connector option as shown below:

 

ConnectorEditor_open

 

 

When opening a connector, the Connector Editor will automatically identify if your connector is of the Assisted REST type or Custom, and load the appropriate user interface.

Note that this process may take a minute or so (depending on how large the file size of your connector is, along with its imported libraries).

Detail of that connector will show up and will be up for modifications.

 

note_pin

Consider:

Bizagi does not save your work in progress of any connector you are creating. Hence, remember to download it before closing the Connector Editor.

You can load a connector even though its implementation has not been completed yet.

If you create a new connector by parting from an existing one (by modifying it), then you will need to ensure you create new actions (reusing existing ones may generate issues).

 

 

User interface options explained

Either for new connectors or when opening an existing one for modifications, the work area will present the following options according to the type of connector (some options apply only to Assisted REST connectors while others apply only to Custom connectors).

 

1. General Connector information

Contains overall information about the connector itself (icon, name, version, author, website URL and description) which you may modify at any time.

For Assisted REST connectors, you will notice that the Authentication method setting shows up:

 

Easy01

 

While for Custom connectors, the above Authentication method setting doesn't apply:

 

Expert01

 

2. Actions and work area

Displays the actions defined for this connector while showing their properties.

The left panel lists actions and allows you to manage them (create new ones or delete existing ones).

 

Notice that for Assisted REST connectors, you can easily identify which actions use a GET, POST, PUT or DELETE method by their colors (green, orange, blue or red respectively).

 

Easy03

 

For Custom connectors, the above setting is not applicable because you implement how each action will invoke a service.

 

Expert03

 

When selecting an action, the work area to its right hand displays the implementation details for that action.

Only for Custom connectors, this will mean exactly the code behind that action:

 

Expert02

 

For both, the lower part will display details regarding the properties, inputs and outputs.

 

3. Properties

Displays relevant characteristics for each action, which you may modify at any time.

For Custom connectors, this is merely the name and description of the action, given that full implementation details are put on the coding above (as illustrated before).

 

For Assisted REST connectors, this panel includes:

Name: The display name for the action.

URL: The service URL where the action is available (as a REST service). Ensure you use these brackets: { } twice to enclose parameters which are variable and to be sent upon execution (e.g, {{your_parameter}} ).

HTTP method: GET, POST, PUT, or DELETE. Notice that only for POST and PUT methods, are inputs applicable.

Description: A meaningful text.

Content type: Select according to how the external service handles information as either:

oapplication/json

oapplication/x-www-form-urlencoded

otext/plain

Use authentication: Switch on to enable the use of authentication for this action (as defined for the connector), or switch off if not needed.

 

Easy02

 

4. Inputs and outputs

Inputs and outputs are build in a same manner: you define a hierarchical structure (compliant to and matching a JSON format) with data types applicable to your service, either as inputs received by that service or as outputs returned by it.

Inputs are not shown for actions of Assisted REST connectors which use the GET or DELETE method.

 

Easy04

 

To build a definition, use the Easy05 icon to add child nodes to one which is explicitly of type Object.

Notice you may define if that piece of information may show up more than once (list) or just one time (single).

 

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.

 

5. Libraries (apply to Custom connectors)

Manages the libraries in use (imported) by this 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):

 

Expert04

 

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

 

6. Global parameters (apply to Custom connectors)

Allows you to specifies overall connectivity, authentication or error parameters to be used by the connector in general (for any number of actions).

 

Expert05

 

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

 

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:

 

Expert06

 

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

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

 

Additional options and tips

Consider the following options:

 

1. Periodically save your work by using the Download option.

This option saves a local .bizc file with your connector so that you can open it anytime with the Connector Editor in the same machine or another one.

 

DownloadButton

 

Note that if you navigate away from the current page, your work will not be saved.

 

2. Maximize your work area if desirable.

While using the work area, note that you can re-size each frame or choose to hide/show them.

To hide/show a frame, click the highlighted part of the divide lines.

 

dashboard_patch_B_frame_size

 

The limits of the frame will be visible at the border of the window, so you can open the frame again.

A keyboard shortcut to hide/show a frame is to press CTRL + <Arrow>, where <Arrow> indicates the frame you want to hide/show.

This shortcut is disabled when the focus is at a text field.