Best practices for connector development

To help you successfully develop a connector in BMC Helix Connector Designer, we recommend that you follow this set of best practices, which includes tips for naming a connector; tips for naming and describing connector triggers and actions; and recommendations for defining configuration parameters and authorization information.

For instructions on how to perform these tasks, see Adding an API definition file to generate fields related to the connector, Adding connector triggers to run a flow, and Adding connector actions to be performed in the target application.

Related topics

Developing connectors

Adding an API definition file to generate fields related to the connector

Adding connector triggers to run a flow

Adding connector actions to be performed in the target application

Best practices for naming a connector

The name you choose for your custom connector is similar to the name of the integrated application.

Example connector name

If you create a connector to integrate with LinkedIn, name the connector LinkedIn.

Best practices for naming a trigger

When naming a trigger, follow these guidelines:

Make the name unique within a connector.
Do not include special characters (such as a space and accents).
Follow the ObjectAction pattern, where Object is the name of an object, and Action is a past tense verb that describes the triggering cause.
Set the objectName field to the name of the object that this trigger is dealing with. For example, for the JIRA connector, the names of the objects can be Incident, Change Request, and Issue.

Example trigger names

IncidentCreated

RecordUpdated

SystemProvisioned

Best practices for describing a trigger

When describing a trigger, follow these guidelines:

Use a sentence fragment that describes what triggers a flow to run. The description pattern is as follows: "Trigger the flow when a certain event takes place in a source application"
The description should use standard capitalization rules.

Example trigger descriptions

New incident created

Record updated

New system provisioned

Best practices for naming an action

When naming an action, follow these guidelines:

Make the name unique within a connector.
Do not embed blanks.
Follow the ActionObject pattern, where Action is an active tense verb that describes what an action does, and Object is a name of an object.
Set the objectName field of an action to the name of the object that this action is dealing with. For example, for the JIRA connector, the names of the objects can be Incident, Change Request, and Issue.

Example action names

CreateIncident

UpdateRecord

ProvisionSystem

Best practices for describing an action

When describing an action, follow these guidelines:

The description should be a sentence fragment that describes what the action does. The description pattern is as follows: "Perform a certain action in a target application"
The description should use standard capitalization rules.

Example action descriptions

Create a new incident

Update an existing record

Provision a new system

Best practices for configuring a connector

While developing a connector, define any configuration parameters that the connector might need when connecting to the target application. Avoid including hard-coded values in your connector. Instead, use Configuration to pass parameters to your connector, for example, the server to which you want to connect:

Best practices for defining connector authorization and authentication

If a target application requires any authorization or authentication information, define an authorization type and use the configuration section to specify, instead of hard-coding. If you are sure that a connector will use only a single set of credentials, it can be specified in the connector configuration. Otherwise, we recommend that you define it separately in the authorization section.

The BASIC authorization type may be used for any type of credentials that take two values. The prompts for the BASIC authorization credentials can be configured.

Best practices for retrieving values from the target application (lookup operation)

If valid values for any trigger output fields or action input fields can be retrieved from the target application, define a lookup operation to retrieve a list of those values. For example, you might want to display a list of companies to select one specific company. A lookup can be referenced by a field, and when a field is selected, the doLookup() method of a connector is called to obtain the value list and return it for presentation in the UI as shown below:

If the values have different internal values and display labels, both can be returned in the result; however, only the display labels are used. The connector switches between the internal values and display labels.

Best practices for initializing a connector

Check the availability of a target application in the initialize() method of a connector. For example, in the LinkedIn connector, you might test the availability of the LinkedIn connection. If a target application is not currently available, perform one of the following actions:

For JavaScript connectors, reject the returned promise with a SERVICE_AVAILABILITY_ERROR error.
For Java connectors, generate the exception ServiceNotAvailableException.

Best practices for using debugging logs

While developing a connector, you might want to add console logging for debugging. When you have finished debugging, remove the extra console logging and log higher level events by using a regular logger.
Do not log data that is passing through a connector, especially sensitive data.
Avoid logging large objects as that can affect connector performance.