Skip to main content

Create a Custom Action

To create a custom action, follow the steps below:

Custom actions are an advanced feature and we recommend you have some familiarity with REST APIs, including writing JSON and request structure, to get the most out of custom actions.

  1. Select the main nav icon, grid.png, in the upper left and select Enterprise Components. The Enterprise Components screen displays.

  2. Select the data source you want to create a custom action for. The data source configuration panel displays.

    select_data_source.png

  3. In the Output section of the data source configuration panel, select Actions. The Actions screen displays.

    data_source_config_select_actions.png

  4. Select Create New Custom Action in the upper right. The New HTTP Custom Action window displays.

    select_create_new_custom_action.png

  5. There are two dropdowns beneath the The action will be field, where you define the action type and the affected entity:

    1. Select the first dropdown to define the type of action.

      Your selection in this dropdown determines how Tonkean handles the results of the custom action in your module workflow. By selecting Creating or Updating, for example, you tell Tonkean that it can expect to handle a new entity or an update to an existing one, respectively, and plan to continue the module workflow accordingly. Alternatively, if you choose Custom Action, Tonkean does not expect a particular state and leaves it up to you to handle the result of the action.

      There are four options in the first dropdown:

      • Creating - The custom action creates a new entity of the defined type.

      • Updating - The custom action updates an existing entity.

      • Creating or Updating - The custom action can create a new entity or update an existing entity.

      • Custom Action - The action does not fit into any other category. Use this option to create an open-ended action that does not presuppose any particular entity state following the use of the action.

      new_custom_action_first_field.png

    2. Select the second dropdown to define the entity the action creates, updates, or otherwise acts upon. The options available in this dropdown are specific to the entity types in the data source.

      Additionally, the entity you select determines which field is available from the data source as part of the request. Select the entity you want to create, update, or otherwise affect.

      new_custom_action_entity.png

  6. Enter a Description for the custom action, if desired, then select Create. The custom actions General screen displays.

    new_custom_action_desc_and_create.png

  7. On the General screen, enter a descriptive Display Name for the custom action.

    config_enter_display_name.png

The basic details of the custom action are complete. Now, it's time to configure the details of the request and response.

Configure the Request

To ensure the action behaves as expected, you must configure the API request, including defining the path and query parameters, header, and body, where necessary. To locate the information needed to configure the request, refer to the relevant developer or API documentation for the application you're adding a custom action to. For example, if you're adding a custom action to a Jira data source, refer to the Jira REST API reference.

  1. In the Settings panel, select Request. The Request screen displays.

    config_select_request.png

  2. In the Path field, select the method dropdown and choose the API method for the request.

    The Request screen is responsive and changes to reflect your selections in each field. For example, if you select GET in the Path dropdown, the Body field no longer displays because a GET request doesn't require a body.

    request_select_method_dropdown.png

  3. Referring to the relevant documentation for your application, locate the request path and enter it into the Path field.

    Note that many request paths contain a variable for a path parameter (or "param"). In the image below, {issueIdOrKey} is a path param variable. You must provide a value for these params in order to form the request properly and return the information you want.

    request_enter_path.png

  4. Add a param for each variable you need to populate in the request. To add a param, locate the Action Params section and enter a param name in the provided field.

    This name displays as a field in the data source and the related data source action, so write a name that's easily recognizable and human-readable. That is, write "Issue Key" instead of "JiraIssueKey".

    When fished, select + Add Param. The param is added to the list above the field.

    request_enter_param.png

  5. In the Path field, remove any variables you created params for and select the insert field button, insert_field.png to choose the relevant param to replace the variable.

    request_insert_params_in_path.png

  6. You may need or want to include query params to specify details in your request. To add a query param, select + Add Query Param. A pair of Param and Value fields displays.

    request_add_query_param.png

    Enter the param name and param value for each query param you include.

    request_query_param_name_and_value.png

  7. Where relevant, add the body of your request in the Body field. Select the insert field button, insert_field.png, to include action params or data source fields. Refer to the documentation for your application to structure the body of your request properly.

    The Body field only displays if it's relevant to the method you select. For example, if you're making a GET request, the Body field does not display.

    request_insert_body.png

  8. Where relevant, select + Add Header to add any header values to the request. A pair of Header Name and Header Value fields displays.

    request_add_header.png

    Enter the header name and header value for each header value you include.

    request_add_header_values.png

Set Advanced Request Options

The Advanced section features several options for more complex use cases. Select the relevant checkbox to enable any of these options:

  • Ignore untrusted certificates - Ignore warnings generated by SSL or TLS certificates your browser has marked as untrusted.

  • Disable auto charset - Disable automatic assignment of the character set. Enable this option if you want to set the charset for your request by manually setting a value for Content-Type (for example, Content-Type: text/html; charset=utf-8).

  • Disable follow redirects - Disable automatic browser redirection.

  • Keep trailing forward slash - Maintain the trailing forward slash, "/" in the request path. Generally, the presence of a trailing slash indicates the resource is a directory as opposed to a file, which doesn't usually have a trailing slash.

  • Remove keys with empty values - Delete fields that are passed in with no values. Depending on the request method, such as whether it's a POST or a PATCH, determines whether the values for those fields are overwritten.

  • Enable dynamic key-value parameters - Allow users to dynamically provide key-value pairs as part of the action. Use this option when creating a request that supports key-value pairs not defined in the schema, such as within a dynamic object.

Test the Request

After you have configured the request, you can test it to make sure it's working as expected.

  1. Select Test Request. The Test Action window displays.

    request_select_test_request.png

  2. In the Action Params section, enter valid values for each of the params you included in the request. In the image below, there is only one param that needs a value to run a test.

    test_enter_param_values.png

  3. Select Run Test. The request runs with the param values you provided and the Response section populates, including a notification with the HTTP response code. The Response Body and Headers tabs in the Response section display the response from the endpoint.

    test_response_success.png

  4. Scroll down in the Response Body tab to ensure you received the response you expect. Select the expand icon in the upper right of the response body for a full-screen view of the response.

    test_response_expand_button.png

    If you don't receive the expected response, or your test request fails, close the Test Action window and return to the Request screen to troubleshoot the problem.

    The HTTP response code you receive in the test can be a helpful starting point for diagnosing potential problems, but we recommend first checking each of the fields in the Path, Query Params, Body, and Headers sections, where relevant. Additionally, check your request against the documentation for the application to ensure it's formed properly and contains the required values.

    Once you've identified the cause of the error, return to the Test Action window and run the test again.

  5. If the test is successful and you receive the response you expect, close the Test Action window and select Save Action Changes in the upper right of the Request screen.

Handle the Response

With the request complete and successfully tested, you can select the fields in the response you want to extract. These fields become matched entity fields when you incorporate the custom action into your module workflow.

  1. In the Settings panel, select Handle Response. The Handle Response screen displays, including the response you received in your previous test.

    If you haven't tested your action yet, no data displays in the Response Body tab of the Handle Response screen. You must perform a successful test to gain access to the needed fields in the response.

    select_handle_response.png

  2. In the Run Action section, select + Add Field. Name and Value fields display.

    response_select_add_field.png

  3. Enter a Name for the field you want to extract. Once extracted by the custom action, this field is added as a matched entity field in your module, so write a name that's easily recognizable and human-readable.

    response_enter_field_name.png

  4. To extract the value for the field, you must select it from the response body. In the Response Body tab, locate the field value you want the action to extract.

    In the image below, we want to extract the comment id value. Notice how the value is highlighted when you place your cursor over it.

    response_select_field_value.png

  5. Select the value. The JSON path for that value displays in the field below the response body.

    response_json_path_populated.png

  6. Select Copy to copy the JSON path, then paste the path into the Value field.

    response_copy_and_paste_json_path.png

  7. When finished, select Save Action Changes.

    response_save_changes.png

Your custom action is complete and ready to use in a module.

To leverage your custom action and the fields it extracts, add the relevant data source action block in your module and select the custom action from the Custom API Action section.

custom_action_in_action_block.png

Configure Retry and Request Failure Criteria

Despite configuring your request correctly, errors can occur—whether due to maintenance activity at the application endpoint, a service outage, or an unknown network issue. To help provide an extra layer of stability, you can configure the conditions where Tonkean retries the request when it encounters certain errors.

When configured to retry the request on certain codes, Tonkean retries three times consecutively, without a delay between each retry.

To configure the retry criteria and request failure criteria, follow the steps below:

  1. Select the Retry Criteria dropdown. The Retry Criteria options display.

    response_retry_criteria_select.png

  2. Select Retry on specific codes (advanced), then enter the HTTP response codes you want to prompt a retry. Enter each code in the field, then select Enter.

    If you do not wish to configure specific failure criteria, this process is complete. Select Save Action Changes in the upper right.

    response_retry_criteria_retry_on_specific_codes.png

  3. To configure specific failure criteria that logs the error message, locate the Failure Criteria section and select the Handle dropdown. The failure criteria handling options display.

    response_failure_handle_select.png

  4. Select + OR. Keyword and response fields display.

    response_failure_handle_or_select.png

  5. Enter the keywords that you want to prompt a specific message to the Module Events History page.

    response_failure_handle_keyword_and_message.png

  6. When finished, select Save Action Changes in the upper right. Your response failure behavior is configured.

In this section: