Adding connector triggers to run a flow

After you have provided the connector details, add a trigger for the connector. A trigger represents an event that takes place in a source application. In the context of a flow, whenever a trigger is activated, a predefined action is performed in another application. 

For example, you can define a trigger that when a new comment in a GitHub project is created, it activates the GitHub connector. If you integrate your GitHub connector with the Slack connector in BMC Helix Integration Studio, you can design a flow that sends out Slack channel notifications whenever there is a new GitHub project comment.  

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.
  
  

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.
  
  

To add or update a trigger

1. To open BMC Helix Connector Designer in your browser, navigate to https://<localHost>:3000/.
2. Log in to BMC Helix Connector Designer.
3. On the Connectors tab, click the name of the connector in which you want to add or update a trigger.
4. On the Connector Properties tab, click the Triggers tab, and perform one of the following actions:
   • If you are adding a trigger, click .
   • If you are updating a trigger, from the Triggers list click the trigger name.
     

5. Enter the trigger details as described in the following table: 

   Field	Description
   Trigger Name	A short description of what will trigger the flow, for example, New incident created, Record updated, or New system provisioned.
   Trigger Type	Choose one of the following trigger types: POLLED (Default)—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 polling interval can be updated from BMC Helix Integration Studio. For more information, see Adding throttling controls. The general polling logic is as follows: Records are retrieved with the modification date greater than the last update date from the previous polling cycle and less than the current time. For the first time, records are retrieved from a minute earlier. The last modification date from the retrieved records is saved as the last update date for the next polling cycle.
   Definition Source	Select the source for defining the trigger fields. You can enter the information manually, or use an API definition file or JSON definition file to automatically generate the fields. The following options are available: Enter it manually—Manually add the trigger input and output fields, without any definition files. Swagger—The trigger input and output fields are 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. For instructions, see Adding an API definition file to generate fields related to the connector for instructions. JSON—The trigger input and output fields will be generated from a JSON snippet or file. For more information, review the steps to add input and output fields.
   For JSON or Enter it manually
   URL	Enter the API endpoint for the triggering event.
   Method	Select the HTTP method for the API endpoint. The following methods are available: GET, POST, PATCH, PUT, DELETE.
   For Swagger
   Swagger File	Select the swagger file that contains the trigger definition. For more information, see Adding an API definition file to generate fields related to the connector.
   Request	Select the request to execute the trigger. This is typically a GET call. Refer to your connecting application's API reference.
   Create Fields	Click this option to auto-generate input and output fields for the selected request under the Input fields and Output fields tabs.

6. Depending on the Definition Source selected, add or update the input fields for the selected source.
   A trigger input field maps to a request field (usually a query parameter) of the corresponding API call.  

   Important

   • Input field names must be unique. Do not use duplicate field names. 
   • The field values for the input fields is the same for all action definition entry options.
   • 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 as the action definition entry method, on the Input Fields tab, click  and select the type. 
     
     
     Add or update the following field details.

     Property	Description
     Name	The field name displayed in BMC Helix Integration Studio. This value must be unique.
     Field Name	The actual field name in the target application of the flow to be created by using this connector. The Name and Field Name mapping must be  unique. Do not map an application field to multiple input fields.
     (Optional) Description	A brief description of the field.
     Required	Indicates whether the field is required. By default, this value is set to true.

     Field names 

   • If you selected Swagger, all the input fields for the request are automatically generated. Update the values as required (for example, you may want to use a different display name)

   • If you selected JSON, on the Input Fields tab, perform the following steps to add fields:
     1. Click .
     2. In the dialog box, paste a JSON snippet, or click Upload JSON File.
        The JSON code must describe one or more input fields for the API call for the trigger. The API reference documentation of the connector's target application should include the code that you can use.
     3. To generate input fields from the JSON code, click Create Fields.

     4. Update values as required (for example, you might want to use a different display name).

7. Depending on the trigger definition entry method selected, add or update the output fields for the trigger. 
   A trigger output field maps to a response field of the corresponding API call.

   Important

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

   • If you selected Enter it manually as the action definition entry method, on the Output Fields tab, click  and select the type. Then add the field details.
     
     

     You can add or update the following fields:

     Property	Description
     Name	The field name displayed in BMC Helix Integration Studio.
     Field Name	The actual field name in the connector's target application.
     (Optional) Description	A brief description of the field.
     Always has data	Indicates whether the field will always be returned, regardless of its value. By default, this value is set to true.
     Condition	Indicates whether the field is a precondition for the trigger to execute. By default, this value is set to false.
     Date Field	Indicates whether this is the record update timestamp field in the database. The value is auto-assigned.

   • If you selected Swagger, all the output fields for the request are automatically generated. Update the values as required (for example, you may want to use a different display name); 
   • If you selected JSON, on the Output Fields tab, perform the following steps to add fields:
     1. Click .
     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 output fields for the API call for the trigger. The API reference of the connector's target application will most likely have code you can use.
     3. Click Create Fields to generate output fields from the JSON code.

     4. Update values as required (for example, you might want to use a different display name). 

To delete a trigger

1. To open BMC Helix Connector Designer in your browser, navigate to https://<localHost>:3000/.
2. On the Connectors tab, click the name of the required connector.
3. On the Connector Properties tab, click the Triggers tab.

4. Select the trigger you want to delete, and click .

Where to go from here

Adding connector actions to be performed in the target application