Adding connector triggers


After you have provided connector details, you can add a trigger for a connector. A "trigger" represents an event that takes place in your connector's target application. In the context of a flow, whenever a trigger "fires," a predefined action is performed in another application. 

For example, you can define a trigger for a GitHub connector that will fire when there is a new or updated comment in a GitHub project. If you integrate your GitHub connector with the Slack connector in BMC Helix Integration Studio, you can create a flow that sends out Slack channel notifications whenever there is a new or updated GitHub project comment.  

Note

A connector must have at least one trigger or action to be used in flows. Depending on whether it is being used for its triggers or actions, a connector can be the Source or Target in a flow, in that order. A connector with both triggers and actions can be selected as both the Source and Target.

To add or update a trigger

  1. Go to https://localhost:3000/ to open BMC Helix Connector Designer in your browser.
  2. Click Connectors, and then click the name of the intended connector.
  3. Do one of the following actions:
    • If you are adding a trigger, click the + next to Triggers in the left pane. Or, if no triggers already exist, click the Add Trigger button under the Triggers tab.
    • If you are updating a trigger, click the trigger name under Triggers in the left pane. Or, click the trigger row under the Triggers tab.
  4. After the pages refreshes, enter or update values for each section as required:

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

Trigger identity fields

Enter Identity values under the Triggers tab as described below.

FieldDescription
NameA sentence fragment describing what will trigger the flow to execute (for example, New incident created, Record updated, or New system provisioned).
Type

Choose one of the following trigger types:

  • POLLED—Periodically polls the server
  • LISTENING—Listening on a persistent (that is, actively connected) connection that streams data
  • WEBHOOK—Makes an event notification POST call to a listener URL

The default trigger type is POLLED. The polling interval can be updated from BMC Helix Integration Studio; see Adding throttling controls.

Trigger definition

You can specify a JSON definition to auto-generate input and output fields for your trigger (refer to the Input fields and Output fields sections below). Alternatively, you can enter the field information manually.

To specify a trigger definition entry method

In the How would you like to specify your Trigger definition section under the Triggers tab, select one of the following options:

  • Enter it manually—Implies no trigger definition is specified. You will need to add trigger input and output fields manually.
  • SwaggerImplies trigger input and output fields will be generated from a request endpoint (typically for GET) that is described in an API definition file. You can upload an API definition file from the API Definitions section under the General tab. Refer to Updating connector details for instructions.
  • JSONImplies trigger input and output fields will be generated from a JSON snippet or file; refer to the Input fields and Output fields sections below.

Proceed to specify the trigger definition.

To specify the trigger definition

In the Trigger Definition section under the Triggers tab, complete one of the following actions:

  • If you selected Enter it manually or JSON as your trigger definition entry method, provide values for:
    • URL—The API endpoint for the triggering event.
    • Method—The HTTP method for the API endpoint. The allowed methods are the following: GET, POST, PATCH, PUT, DELETE.
  • If you selected Swagger as your trigger definition entry method:
    1. Select the Swagger File containing the trigger definition. Refer to Updating connector details for information about uploading API definitions.
    2. Select the Request to execute the trigger. This is typically a GET call. Refer to your connecting application's API reference.
    3. Click Create Fields to auto-generate input and output fields for the selected request under the Input fields and Output fields sections.

Trigger input fields

A trigger input field maps to a request field (usually a query parameter) of the corresponding API call. Enter Input Fields values under the Triggers tab as described below. Depending on your selected trigger definition entry method (see Trigger definition above), values may be auto-generated.

Note

If you are updating an existing connector, remember that:

  • If you remove a trigger input field, a default value will be supplied for it so that the trigger will still work.
  • If you add a new input field, existing flows based on the previous version of the connector will no longer work. You will need to communicate the change to your users.
  • If you selected Enter it manually, click Add Field to manually enter input fields. The following table describes the properties of a trigger input field.
  • If you selected Swagger, all the input fields for the request are auto-generated. Update the values as required (for example, you may want to use a different display name); refer to the following table.
  • If you selected JSON:
    1. Click Load from JSON.
    2. In the dialog box, paste a JSON snippet, or click Upload JSON File to upload a JSON file.
      The JSON code must describe one or more input fields for the API call for the trigger. (The connector's target application's API reference will likely have code you can use.)
    3. Click Create Fields to generate input fields from the JSON code.
    4. Update values as required (for example, you may want to use a different display name); refer to the following table.
PropertyDescription
Name

The display name for the field in BMC Helix Integration Studio.

Field NameThe actual field name in the connector's target application.
(Optional) DescriptionA brief description for the field.
Type

The data type for the field. The supported types and available qualifiers for this data types are as follows:

boolean

is true, is false

string

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

email

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

picklist

equals, not equals, is one of, is not one of

textarea

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

doubleequals, not equals, less than, less than or equal to, greater than, greater than or equal to
intequals, not equals, less than, less than or equal to, greater than, greater than or equal to
numberequals, not equals, less than, less than or equal to, greater than, greater than or equal to
currencyequals, not equals, less than, less than or equal to, greater than, greater than or equal to
percentequals, not equals, less than, less than or equal to, greater than, greater than or equal to
address

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

phone

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

url

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

datetimeequals, not equals, before, not before, after, not after
dateequals, not equals, before, not before, after, not after
timeequals, not equals
string_array includes one of, not includes one of, includes all of, not includes all of
password

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

attachmentN/A

The default data type is string.

RequiredIndicates whether the field is required. Defaults to true.

To remove an existing field, click the trash can icon at the end of its row. You can remove all fields using the Remove Fields button.


Trigger output fields

A trigger output field maps to a response field of the corresponding API call.

Enter Output Fields values under the Triggers tab as you did for Input Fields (refer to Input fields above for instructions). The following table describes properties of a trigger output field.

PropertyDescription
Name

The display name for the field in BMC Helix Integration Studio.

Field NameThe actual field name in the connector's target application.
(Optional) DescriptionA brief description for the field.
Always contains dataIndicates whether the field will always be returned, regardless of its value. Defaults to true.
Type

The data type for the field. The supported types and available qualifiers for this data types are as follows:

boolean

is true, is false

string

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

email

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

picklist

equals, not equals, is one of, is not one of

textarea

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

doubleequals, not equals, less than, less than or equal to, greater than, greater than or equal to
intequals, not equals, less than, less than or equal to, greater than, greater than or equal to
numberequals, not equals, less than, less than or equal to, greater than, greater than or equal to
currencyequals, not equals, less than, less than or equal to, greater than, greater than or equal to
percentequals, not equals, less than, less than or equal to, greater than, greater than or equal to
address

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

phone

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

url

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

datetimeequals, not equals, before, not before, after, not after
dateequals, not equals, before, not before, after, not after
timeequals, not equals
string_array includes one of, not includes one of, includes all of, not includes all of
password

equals, not equals, contains, not contains, matches, not matches, starts with, not starts with,

ends with, not ends with, is empty, is not empty

attachmentN/A


The default data type is
string.

Mapped

Indicates whether the field will appear in BMC Helix Integration Studio. Defaults to true.

ConditionIndicates whether the field is a precondition for the trigger to fire. Defaults to false.
Created Date FieldIndicates whether this is the record creation timestamp field in the database. Will be auto-assigned.
Updated Date FieldIndicates whether this is the record update timestamp field in the database. Will be auto-assigned.

Note

If you remove an output field, a default value is supplied for it so that the trigger still works.

To delete a trigger

  1. Go to https://localhost:3000 to open BMC Helix Connector Designer in your browser.
  2. Click Connectors, and then click the name of the intended connector.
  3. Complete one of the following actions:
    • Under Triggers in the left pane, hover on the trigger, and click the trash can icon.



    • Click the Triggers tab, and click the trash can icon for the trigger.

Where to go from here

Adding connector actions

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

Comments

  1. Tobias Buehl

    Hi, any plans to allow PUT methods as well?

    Apr 30, 2018 10:24
    1. Olga Kutetska

      Hello!

      Thank you for the question. We do not have such information about the plans regarding the PUT method.


      May 11, 2018 06:40
    1. Tashfeen Mahmud

      Hi Tobias, sorry for being late to join the party. I'm assuming you are referring to manually adding a trigger definition methods. There are no plans to support PUT, but technically POST can be used for PUT purposes.

      However, triggers typically only involve GET calls (since a trigger retrieves data of an event that took place on the source application). POST calls are only relevant when used for GET-like scenarios, for example when you have to provide a JSON object to retrieve a list. It is extremely unlikely that you will need to make a PUT call for triggers, but if you absolutely must, you can use POST for PUT as mentioned above.

      Jun 14, 2018 12:28