Using REST API with BMC AMI Ops Automation

You can receive and send REST API calls with BMC AMI Ops Automation.

Receiving REST API calls

BMC AMI Ops products can receive REST API calls though the Common REST API (CRA). See Administering the Common REST API for more information about the CRA.

For example, automation programs and scripts in non-z/OS products can invoke views and issue actions to BMC AMI Ops products, including BMC AMI OpsA, by issuing REST API calls to the CRA. The following shows the processing flow of how BMC AMI OpsA can receive calls via the REST API:

Non-z/OS_product -> curl -> REST_API_call -> CRA_host -> BMC_AMI_OpsA_PAS

We supply two BBSAMP members, QAOCRA1 and QAOCRA2, as sample shell scripts to help you utilize the Common REST API. For example, Linux users can use these sample shell scripts to access BMC AMI OpsA.

Sending REST API calls

BMC AMI OpsA can issue REST API calls using the curl program via the following methods:

The Command Type: USS action of a USS Rules Management Rule
A BMC AMI OpsA EXEC that invokes BPXWUNIX

Using the Command Type: USS action of a USS Rules Management Rule

Many non-z/OS products provide a REST API. BMC AMI OpsA supports the ability to run the curl program to access these products. This action is supported in a BMC AMI OpsA Rules Management Rule. Using a Rule, you can issue REST API commands using the Action Specification Command: Type USS. This action allows you to specify a USS program or a shell script.

When attempting to get data from or send actions to BMC AMI OpsA views, we recommend that you use the IMFEXEC MV or IMFEXEC MVX commands and not use the REST API. See Using-the-MV-API and Using-the-MainView-Extended-MVX-API for more information.

To see an example of how to issue a USS command from a Rules Management Rule, see the section Issue USS commands from a Rules Management Rule action.

One of the following solutions must be active in the BBI-SS PAS to support Rules to issue the Type USS command otherwise, an error message is issued:

MVN: BMC AMI Ops Automation for Data Centers
MVK: BMC AMI Ops for CICS
MV2: BMC AMI Ops for Db2
MVF: BMC AMI Ops for IMS
MVR: BMC AMI Ops for Networks
MVG: BMC AMI Ops for Messaging

The following shows the processing flow of how BMC AMI OpsA can send REST API calls via a USS command:

Rule → Action: Command Type USS → curl → REST API call
Rule → Action: Command Type USS → my_shell_script.sh → curl → REST API call
Rule → Action: schedule EXEC → REXX EXEC -> bpxwunix → curl → REST API call

When a Rule issues a Command, there is no way to check if the Command succeeded. A shell script allows you to check whether the curl request was successful and take corrective action if needed. For example, the script can check for return code 0 and HTTP code 200 from curl.

REXX EXECs and shell scripts are suitable for implementing more complex automation or multi-step automation such as:

Obtain information from a variety of sources to make complex decisions
Issue complex actions
Detect and handle any errors from the curl program

Using a BMC AMI OpsA EXEC that invokes BPXWUNIX

BMC AMI OpsA can issue REST API calls to other non-z/OS and z/OS products. One common way to issue REST API calls is using the curl program. Rocket Software provides an open source tool, “curl for z/OS”, that you can use. BMC AMI OpsA REXX EXECs can invoke the USS curl program with the aid of the IBM BPXWUNIX program. BBSAMP member QAOUSS2 includes an example of using BPXWUNIX to run a USS program.

The following example USS command runs a shell script named rest.sh and redirects the stdout output to the z/OS syslog (/dev/console):

/home/my-userid/rest.sh > /dev/console

Sample rest.sh script

The following sample rest.sh script runs the curl program to issue a REST API call to BMC Helix. You can execute this script from both the Command Type: USS field from a Rule or from an EXEC that invokes BPXWUNIX.

In this sample, the curl command sends an event which represents a critical alert. See BMC Helix Operations Management for information about the fields in the sample script.

#!/bin/sh
# LB=”helix-om.mycompany.com”
# API_key=”1234abcd-12ab-12ab-12ab-123456abcdef”
LB=<rest_api_url>
API_KEY=<REST API key>
#
#
<full curl path>/curl --insecure --header "Content-Type: application/json" --header "Authorization: apiKey $API_KEY" --request POST --data '[{
    "class": "EVENT",
    "severity": "CRITICAL",
    "msg": "sending test event.",
    "source_identifier": "OpsA-lpar-name",
    "status" : "OPEN",
    "source_hostname": "OpsA-lpar-name.mycompany.com",
    "source_port": "3181",
    "source_address" : "192.168.0.1",
    "category": "APPLICATION",
    "priority": "PRIORITY_2",
    "details":   "Detail information about the event situation"
}]' https://$LB:443/events-service/api/v1.0/events
exit 0

If you are integrating with BMC Helix Operation Management, see Managing-events-with-REST-APIs for more information.

Triggering BMC AMI Ops Automation Rules for REST API calls from the CRA

Users can issue REST API calls that trigger BMC AMI OpsA BRC event type Rules.

The CRA can create and send BAROC messages toBMC AMI OpsA which receives them as BRC events. The following describes the processing flow:

Non-z/OS_product -> curl -> REST_API_call -> CRA_host -> BAROC message -> BMC_AMI_OpsA_PAS -> BRC Rules

For more information about triggering BRC events from the CRA, see Triggering BMC AMI Ops Automation using the Common REST API.