Develop > Web Service Interfaces > Action Web Service Interface

Action Web Service Interface

The REST- based Action Web Service enables integrators to access the following functionality from an external application:

  • Execute an arbitrary command string on one or more monitored nodes. Requests can be run in parallel.

    A command type must be specified. A command can be executable (default), Perl script, VBScript, JavaScript, or Windows Scripting Host script. The script code must be passed in the web service call. For Unix agents, commands are executed in a shell. For Windows agents, commands are not executed in a shell. For example, an "echo hello world" command would read echo hello world on Unix and cmd /c echo hello world on Windows.

    Target hosts can be specified by hostname (from the RTSM) and by IP address.

    Requests are dropped when the OMi backend is disabled or restarted. In some cases, an Action Web Service request will not finish. For example, if you use the ovc- stop command to stop the action agent process, which sends back a call response, the call will continue to run until the OMi backend is disabled or restarted.

    On the agents, environment variables like OvDataDir, OvInstallDir, and so on are predefined. For a complete list you can call the OMi server using the following command:

    $ <OvBinDir>/ovdeploy –cmd set [ -host <remoteHost> ] | grep “Ov”

    Linux output: OvBinDir = /opt/OV/bin

    Windows output: Program Files\HP\HP BTO Softeare\bin\win64

  • Cancel the command on the managed nodes.

  • Retrieve the command status for the managed nodes.

    The OMi backend keeps the execution results for 10 minutes after the last managed node has finished execution. Web service clients must retrieve the results in that time period.

  • Retrieve the detailed command status for a specific managed node.

The Action Web Service only triggers command strings entered by the user. In this case, an "action" is an arbitrary string entered by the web service user, as opposed to a "tool", which is a predefined string stored in the database. The Action Web Service does not trigger automatic actions or user actions.

For further information about actions, see Actions

For information about tools, see Tools.

When using a JAVA client, the classes provided in the opr-external-api.jar can be used to marshal or unmarshal the XML content directly. See also the example code in <OMi_HOME>/opr/examples/action-ws-client

ClosedHow to Access the Action Web Service

Your entry point to the web service interface is the Service Document, using the following base URL and syntax:

https://<serviceURL>/<request>

<serviceURL>

The URL of the Action web service:

<server>:<port>/opr-web/rest/<version>

where <server> is the name of the OMi server and <version> is the web service interface version (for example: 10.10).
<request>

The service request. For a complete list and syntax of possible service requests, see Action Web Service request reference.

List of Services in the Service Document

OPR Action Web Services

URL

Action Web Service POST request:

https://<server>:<port>/opr-web/rest/10.10/direct_execution

Action Web Service GET | DELETE request:

https://<server>:<port>/opr-web/rest/10.10/direct_execution/{contextId}

Action Web Service GET details | DELETE request on single node:

https://<server>:<port>/opr-web/rest/10.10/direct_execution/{contextId}/{resultId}

ClosedSecurity and Authorization

Because the Action Web Service enables the user to trigger mass requests that run on all managed nodes, security and authorization settings are especially important. It is highly recommended that you configure OMi to use HTTPS while working with the Action Web Service. Make sure that the following security requirements have been met:

  1. Check if the Action Web Service is enabled. The Web Service is enabled by default. To edit the Tool Execution infrastructure setting, got to:

    Administration > Setup and Maintenance > Infrastructure Settings

    Alternatively, click Infrastructure Settings.

    Select Applications and use the list to set the context to Operations Management. Scroll down to Operations Management - Action Web Service Settings. Set Allow command execution through Action Web Service to true.

  2. To be able to access the Action Web Service, a user needs to be assigned a role with the Action Web Service permission. This permission can be accessed in the Operations Console category of the permission section of a role. For more information on permissions, see Users, Groups, and Roles.

  3. The Action Web Service user must specify a valid username and password in the web service.

ClosedError Handling

Error handling for the Action web service is as follows:

HTTP error codes:

  • HTTP error code 403: authorization problems
  • HTTP error code 409: requested hosts not in the RTSM or no CIs match requirements
  • HTTP error code 4xx (other than 403, 409): any form of communication problems with the OMi backend
  • HTTP code 200: at least one requested host is in the RTSM and meets the requirements

Individual return codes per requested host (HTTP code always 200):

  • Return code -404: requested host is not in the RTSM or the CI does not meet the requirements
  • Return code -500: communication problem with the requested host
  • Return code 0: execution succeeded
  • Other return codes (for example, 1): error code from the command to be executed

Send Help Center feedback