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.  

Important

A connector must have at least one trigger or action to be used in flows. In a flow, if the connector trigger is used the connector is used as a source, and if the connector actions are to be run, it is used as a target in the flow. A connector with triggers and actions can be selected as both a source and a target.

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: 

    FieldDescription
    Trigger NameA 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.

    MethodSelect 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 FieldsClick 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

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

      PropertyDescription
      Name

      The field name displayed in BMC Helix Integration Studio.

      Field NameThe actual field name in the target application of the flow to be created by using this connector.
      (Optional) DescriptionA brief description of the field.
      RequiredIndicates whether the field is required. By default, this value is set to true.
    • 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:

      PropertyDescription
      Name

      The field name displayed in BMC Helix Integration Studio.

      Field NameThe actual field name in the connector's target application.
      (Optional) DescriptionA brief description for the field.
      Always has dataIndicates whether the field will always be returned, regardless of its value. By default, this value is set to true.
      ConditionIndicates whether the field is a precondition for the trigger to execute. By default, this value is set to false.
      Date FieldIndicates 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 .

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

Where to go from here

Adding connector actions to be performed in the target application

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
  2. Sudeepkumar Chandrasekaran

    Hi Tashfeen. Can i post transactions from another interface to BMC integration service? or is it always integration service connectors going and fetching information from another interface?

    Jul 17, 2020 10:00