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 to. It is highly recommended to use the HTTPS protocol, so the API endpoint URL should start with "https://". Only if absolutely needed and if in compliance with your company's security guidelines, you can also use the HTTP protocol, so 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.

    You can choose between a custom API endpoint or one of the supported Cloud Pak for AIOps APIs.

    Note that these supported Cloud Pak APIs automatically handle authentication. Provided that the action is run manually (for example, inside of a manual runbook or via a contextual menu item in the Alert Viewer) by passing through the executing user's information.

    This automatic authentication is not supported in fully automated runbooks. To create an action that calls a supported Cloud Pak API and that can be used in a fully automated runbook, you must explicitly specify an Authorization header as documented for the respective API.

    If you want to access any other Cloud Pak for AIOps API you should do this via the internal hostname https://ibm-nginx-svc:443/aiops/api instead of using the external hostname. In this case, you must specify an Authorization header as documented for the respective API.

    For example, to retrieve some data from the Metric API, you can use https://ibm-nginx-svc:443/aiops/api/app/metric-api/v1/metrics with an Authorization header that contains your API (Zen) key. Alternatively, you can use a parameter for the entire URL that contains a full valid web service URL at the time when the HTTP action is started.

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

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