Creating HTTP actions

The HTTP action provider allows to send HTTP requests to a specified web service. It is highly recommended to send these requests using the HTTPS protocol, in order to have the communication encrypted and signed. If required in your environment, and if compliant with your company's security guidelines, you can also send requests using the unencrypted HTTP protocol (for example, in some test scenarios).

To create an action of type HTTP, click Actions > Create action and complete the following fields:

  • Type:

    Select HTTP.

  • Name:

    Provide a name that describes what this action does. For example, IBM Watson Translate.

  • Description:

    Provide any helpful additional information so that the user can immediately understand which problem this action solves.

  • Prerequisites:

    If this action requires prerequisites, add this information. For example, Watson service credentials are required.

  • Tags:

    Provide tags to filter actions. You can select any existing tags from the drop-down list and click the plus icon "+" to add them. To create a new tag, type the text into the field, select the text string displayed, and click the plus icon "+".

  • API endpoint:

    Specify the API endpoint of the web service to which the HTTP request will be sent. The API endpoint URL must start with "https://". Only if absolutely needed and if in compliance with your company's security guidelines, you can use the HTTP protocol, in which case the API endpoint URL may start with "http://". Alternatively, specify a parameter that contains a full valid web service URL at the time when the HTTP action is started. For example: $ticketingSystemApiURL.

    Supported Concert Operate APIs automatically handle authentication.

    When an action is run manually (for example, within a manual runbook or from a contextual menu in the Alert Viewer), the system uses the currently logged-in user's identity.

    Fully automated runbooks (FARBs) also support automatic authentication for supported Concert Operate APIs. When you create an HTTP action that calls a supported Concert Operate API within a fully automated runbook, you no longer need to manually specify an Authorization header.

    Instead, provide a username (User ID) as an input when creating or modifying the action. The user must already exist in the system. No password or interactive login is required.

    During execution, the Automation Service generates a short-lived API token on behalf of the specified user by using internal service credentials.

    Best practice: Use a dedicated functional or service user ID for fully automated runbooks.

    For example, to retrieve data from the Metric API, you can use an internal endpoint such as https://ibm-nginx-svc:443/aiops/api/app/metric-api/v1/metrics. Previously, this required specifying an Authorization header with an API (Zen) key when used in fully automated runbooks. With automatic authentication enabled for FARBs, the system generates the API token automatically when a valid username is provided as runbook input.

  • Method:

    Choose the HTTP method. For example: POST.

  • Username:

    If basic authentication is required to use the web service, specify the API user name for basic authentication.

  • Password:

    If basic authentication is required to use the web service, specify the API password for basic authentication.

  • Accept:

    Specify the accept request header. The accept header is used to specify the media types which are acceptable for the response of the request. For example text/html.

  • Accept-Language:

    Specify the accept-language request header which is used to restrict the set of languages that are preferred for the response of the request. For example en-US.

  • Additional header:

    Optionally, specify any additional request headers that are needed for the request. For example accept-charset: utf-8.

  • Ignore certificate errors:

    Select this check box to ignore certificate errors. Use this option only for test purposes. In production environments, ensure that the correct certificates are installed on the target web service.

  • Get result asynchronously?:

    Select this option if the target API is asynchronous, that is, if the API does not return an immediate result.

    Normally, HTTP Actions expect a synchronous response. If an external API takes an unusually long time to process (for example, provisioning a VM), the connection might time out. When you select this option, RBA initiates a request, then periodically polls the external system for a response until the operation completes or the maximum poll attempts or wait time is reached.

    The following fields are enabled when you select this option:

    • Job Id: Specify the identifier that is used by RBA to track the status of the submitted API request.

    • Status check URL: Specify the URL that RBA calls to check the status of the job.

    • Additional headers (optional): Specify any additional HTTP headers to include in the status check requests.

    • Poll interval: Specify how often, in seconds, RBA checks the status check URL for a response.

    • Maximum poll attempts: Specify the maximum number of attempts to checks the status check URL.

    • Timeout: Specify the maximum time, in seconds, to wait for the status check URL for a response.

    • Success condition: Define the JSONata expression to evaluate the success condition of the response.

    • Failure condition (optional): Define the JSONata expression to evaluate the failure condition of the response.

  • Action output:

    • Filter action output By default, all action output gets collected and printed to the action output field. If you are only interested in a subset of the action output (for example, because you want to create a chain of two actions within a runbook, where some particular information from the first action is used as input to the second action, then you can enable the Filter action output toggle and specify a pattern that controls which part of the action output gets returned.

    • Choose query syntax Depending on the type of output that gets created you can choose between three types of pattern-matching engines and their respective syntax:

      • XPath: best suited for parsing XML data

      • JSONPath: best suited for parsing JSON data

      • Regular expression: best suited for parsing unstructured data

    • Choose query syntax at runtime Select this checkbox if you want to allow the query syntax to be chosen when testing the automation, and also within the parent runbook. This checkbox is typically disabled. If this checkbox is enabled, the system property filter-syntax is added to the action.

    • Enter query pattern Enter a pattern that is supported by the selected query syntax. For example, if the JSON output object is expected to contain an attribute called "version" and you selected the "JSONPath" query syntax, then you can use the query pattern "$.version" to pick the value of the version attribute out of the overall JSON output.

    • Enter query pattern at runtime Select this checkbox if you want to allow the query pattern to be chosen when testing the automation, and also within the parent runbook. If this checkbox is enabled, the system property filter-query is added to the action.

    • Test output filter Click this link (or the Test button in the actions menu) when you are ready to test the action. This saves the action and directly opens the Test action page for the current action. For many developers, working with query patterns is an iterative process. Therefore it is recommended to enable Enter query pattern at runtime at least while you are developing the action, and switch to Test action to fine-tune the query pattern. The development of the query pattern is also supported within the Test action page itself, where you can toggle between Show filtered output and Show unfiltered output after you have run the action. You can also toggle between Edit action and Test action until you are satisfied with the result.

  • Parameters:

    Add input parameters to run the action. Those input parameters can be referred in the entry fields. For example, a parameter text can be referred as $text.