Best practices for connector development

To help you successfully develop a connector in BMC Helix Connector Designer, BMC recommends 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 Updating connector detailsAdding connector triggers, and Adding connector actions.

Best practice 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 practice for naming a trigger

When naming a trigger, follow these guidelines:

  • Make the name unique within a connector.
  • Do not embed blanks. 
  • 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 IncidentChange  Request, and Issue.

Example trigger names

IncidentCreated

RecordUpdated

SystemProvisioned

Best practice 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 practice 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  IncidentChange  Request, and Issue.

Example action names

CreateIncident 

UpdateRecord

ProvisionSystem

Best practice 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: "When the flow is triggered, then 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 practice for configuring a connector

Allow the connectors to be configured instead of hard coding configuration information in the connector. While developing a connector, define any configuration parameters that the connector might need when connecting to the target application. 

Best practice for defining connector authorization and authentication

If a target application requires any authorization or authentication information, define an authorization type and allow the information to be specified. If you are sure that a connector will use only a single set of credentials, it can be specified in the connector configuration. Otherwise, BMC recommends 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 practice 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. 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.

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 practice for initializing a connector

Check the availability of a target application in the initialize() method of a connector. 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, throw the exception ServiceNotAvailableException.

Best practice 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. 

Was this page helpful? Yes No Submitting... Thank you

Comments