Enabling or disabling Agents with a REST API
Use this endpoint to enable or disable Agents. Agents can be of two types – Collection Stations and Collection Agents. For more information, see Agent types.
Notes
- Before running this endpoint, you need to generate an authorization token by running the
loginendpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint. If the
check.csrf.header.XRequestedWitholaengineConfig.propertiesfile is set to TRUE, then you need a new headerX-Requested-With=XMLHttpRequestto be added to the API calls. For accessing the application in secure mode (from CSRF), the addition of this header is mandatory in every request.- To log out from a given session, you need to run the
logoutendpoint.
For more information, see Developing.
This topic contains the following information:
Endpoint overview
Use the PUT method to enable or disable one or more Agents. By enabling an Agent, you enable the Agent to collect data. Conversely, by disabling an Agent, you stop the Agent from collecting data.
Note
When you disable an Agent that is associated with multiple hosts, data collection from all those hosts is automatically stopped.
Request URL
PUT <protocol>://<host>:<port>/olaengine/itdaws/hostservices/agents/<action>?agent=<agentNames>&version=<apiVersion>
Parameter definitions
The following parameters can be used in the request URL.
| Parameter name | Description |
|---|---|
Required | Protocol that you want to use for communication with the Console Server. Can be one of the following:
|
Required | Host name of the Console Server. |
Required | Port number of the Console Server. The default port is 9797. |
Required | Indicates the action that you want to perform – whether you want to enable or disable the Agents. Can be one of the following:
|
Required | Details of Agents that you want to enable or disable. The value must be the Agent name appearing on the Administration > Hosts page, under the Agent Name column. To specify multiple Agents, specify a comma-separated list of Agent names. For more information, see examples. |
Optional | Version of the API. You can specify the version as Tip: Generally the API version is the same as the product version on which the API can be run. |
Examples
The following examples illustrate the inputs for enabling or disabling Agents by using the PUT method.
Example 1: Enable a single Agent
The following example illustrates the input and response for enabling an Agent by specifying the Agent name, "Agent1.bmc.com".
PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/enable?agent=Agent1.bmc.com
{
"statusCode": "200",
"statusMessage": "OK",
"agents": [{
"agent": {
"agentName": "Agent1.bmc.com"
}
}]
}Example 2: Enable multiple Agents
The following example illustrates the input and response for enabling multiple Agents by specifying the following Agent names:
- Collection-station_hou1
- Collection-agent_hou2
PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/enable?agent=Collection-station_hou1,Collection-agent_hou2
{
"statusCode": "200",
"statusMessage": "OK",
"agents": [{
"agent": {
"agentName": "Collection-station_hou1"
"agentName": "Collection-agent_hou2"
}
}]
}Example 3: Disable a single Agent
The following example illustrates the input and response for disabling an Agent by specifying the Agent name, "collection-station_hou.bmc.com".
PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/disable?agent=collection-station_hou.bmc.com
{
"statusCode": "200",
"statusMessage": "OK",
"agents": [{
"agent": {
"agentId": "collection-station_hou.bmc.com"
}
}]
}Response elements
The following sections help you understand the response elements:
Element definitions
The endpoint response contains the following main elements:
| Response element | Description |
|---|---|
String | A string describing the status code returned. For more information, see HTTP status codes. |
String | Message explaining the reason for the response. |
Array | Can be one of the following:
|
Successful response sample
See examples.
Unsuccessful response sample
{
"statusCode": "400",
"statusMessage": "Bad Request",
"agents": [{
"messages": [{
"severity": "Error",
"code": "update.agent.invalid.id",
"text": "Agent with id provided=clm-hou-agent, doesnt exist."
}]
}]
}HTTP status codes
The following table describes the status codes that are likely to appear while working with this endpoint.
| Status code | Description |
|---|---|
| 200 | Request completed successfully. |
| 401 | Authorization error (invalid authorization token or authorization token not present). |
| 400 | Agent name does not exist. |
| 500 | Can occur in the following scenarios:
|
Comments
Log in or register to comment.