Invoking actions using the Common REST API

You can use the Common REST API doAction endpoint to invoke an action.

• • Before you begin
  • Invoking an action using the doAction endpoint

Before you begin

• You must have the CRA installed and running. For more information, see Setting-up-the-Common-REST-API.
• Log in to the service and acquire a token. For more information, see Logging-in-to-a-service-using-the-Common-REST-API.
• To use the doAction endpoint, you must have an open session. To create an open session, use the data endpoint with close=false included as a query parameter. For more information, see Retrieving-view-data-using-the-Common-REST-API. The open session provides the product name and view name for the doAction endpoint.
• To get a list of available actions and their parameters, use the getAcTbl endpoint. For more information, see Retrieving-view-actions-using-the-Common-REST-API.

Invoking an action using the doAction endpoint

The doAction endpoint uses the POST method to invoke an action for a view. Use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/serviceGateway/services/<serviceName>/doAction?parms=<parms>

The variables represent the following values:

• <hostName> is the name of the mainframe host where the CRA server is running.
• <portNumber> is the port number of the CRA server.
• <serviceName> is the name of the service as it appears on the list. For more information, see To retrieve a list of services.

Authorization

Query parameters

The doAction endpoint accepts the following case-sensitive parameters:

Header parameter

Response data

There are three different possible formats for the response data based on the nature of the action.

• Simple Status
• Status with command
• Dialog prompt

Simple Status

Some commands return a simple status indicating that the action was performed. The current data your application may have is now stale and should be refreshed.

The following example shows using the PURGE (P) action from AutoOPERATOR to purge the output of a held job.

To invoke the action, perform a POST as follows:

This invocation purges the job named MVSABC1X with the job ID J0538551.

As with all other POST operations, the user token is sent as the body content of the request.

The following shows a successful response:

Status with command

Some commands return a simple status along with a command to be executed. BMC AMI Ops Explorer uses this command to open a new view. Your application may decide to use the command to fetch more data for a related view.

The following example shows how to navigate to the Real-time TCP CPU utilization view.

To invoke the action, perform a POST as follows:

The rownum parameter is an index into the view data from the JCPU view.

The following shows a successful response:

The desired data for this action is contained in the JTCB view.

Dialog prompt

Complex commands return information that must be filled out and returned using the lcdReply endpoint. Dialog data is returned in HTML format. You can present the HTML to a user or handle it programmatically. In either case, the data for the fields described in the HTML must be returned in the lcdReply endpoint.

The following example shows cancelling a job from the JCPU view.

To invoke the action, perform a POST as follows:

The following shows a successful response:

If you are running a dialog prompt action, to complete the action, you must POST an lcdReply command:

In this example, we obtain the command from the mvi-actions property. We obtain the cancconf and cancdump parameters from the <input> elements within the HTML.

If successful, the response contains a simple status:

HTTP status and reason codes

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.