Adding connector actions to be performed in the target application

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

For example, you can define an action for a Slack connector that is performed whenever a new comment in a GitHub project is created. If you integrate your Slack connector with the GitHub 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 an action

  1. To open BMC Helix Connector Designer in your browser, go 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 an action. 
  4. On the Connector Properties tab, click the Actions tab, and perform one of the following actions:
    • If you are adding an action, click .
    • If you are updating an action, click the action name from the Actions list.
  5. Enter the action details as described in the following table:

    FieldDescription
    Action NameA short description of the action to be taken when the flow is initiated, for example, Add new record, Update record.
    Definition Source

    Select the source for defining the action 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 action input and output fields, without any definition files.
    • Swagger—The action 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.
      For more information, see Adding an API definition file to generate fields related to the connector.
    • JSON—The action input and output fields will be generated from a JSON snippet or file.
      For more information, review the steps to add input and output file.
    For JSON or Enter it manually
    URL

    Enter the API endpoint for the action event.

    MethodSelect the HTTP method for the API endpoint. The allowed methods are : GET, POST, PATCH, PUT, DELETE.
    For Swagger
    Swagger File

    Select the swagger file that contains the action definition.

    For more information, see Adding an API definition file to generate fields related to the connector.

    Request

    Select the request to execute the action. This is typically a GET call. Refer to your connecting application's API reference.

    Create FieldsClick this option to automatically 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 action. 
    An action input field maps to a request field of the corresponding API call (typically a POST request). 

    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 an action input field, a default value is supplied for it so that the action will still work.
      • If you add a new input, 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 details.

      PropertyDescription
      Display 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.
      Show by default

      Indicates if the field is displayed in BMC Helix Integration Studio.


    • If you selected Swagger, all the input fields for the action are auto-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 action. The API reference documentation of the connector's target application should include the code that 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).
  7. Depending on the action definition entry method selected, add or update the output fields for the action. 

    An action 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 action is still functional.

    • 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
      Display 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 has dataIndicates whether the field will always be returned, regardless of its value. By default, this value is set to true.
    • 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); 
    • 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.
        The JSON code must describe one or more input fields for the API call for the action. The API reference documentation of the connector's target application should include the code that 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)
  8. Click Save.

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: "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

To delete an action

  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 Actions tab.
  4. Select the required action, and click .

Where to go from here

ActionReference
Add lookups to the connectorAdding lookups to display valid field values when mapping fields in a flow
Add queries for the connectorAdding queries to get data from a target server when running a flow
If you have defined all required triggers, actions, lookups, and queries for the connector, update connector authentication details.Adding connector authentication, configuration, and request parameters
Generate connector codeBuilding connectors
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Ezra Wise

    Does the Field Name for an Action Output Field need to map to a variable in the connector code? Or is this just any name that we want to give it?

    Aug 09, 2018 03:14
    1. Tashfeen Mahmud

      Hi Ezra, yes, the field name value maps to the corresponding field in the output object, and is therefore referenced in the connector code. You cannot use just any name, it has to match the name of the intended output field in the target application. Thanks for your comment!

      Aug 09, 2018 03:57