Page tree

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 login endpoint. 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.
  • To log out from a given session, you need to run the logout endpoint.

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 nameDescription

<protocol>

Required

Protocol that you want to use for communication with the Console Server.

Can be one of the following:

  • http
  • https

<host>

Required

Host name of the Console Server.

<port>

Required

Port number of the Console Server.

The default port is 9797.

<action>

Required

Indicates the action that you want to perform – whether you want to enable or disable the Agents.

Can be one of the following:

  • enable: Set this value to enable Agents.
  • disable: Set this value to disable Agents.

agent

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.

version 

Optional 

Version of the API.

You can specify the version as 2.5.

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

Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/enable?agent=Agent1.bmc.com

Response
{
    "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
Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/enable?agent=Collection-station_hou1,Collection-agent_hou2

Response
{
    "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".

Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/agents/disable?agent=collection-station_hou.bmc.com

Response
{
    "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

Response elementDescription

statusCode

String

A string describing the status code returned.

For more information, see HTTP status codes.

statusMessage 

String

Message explaining the reason for the response.

agents

Array

Can be one of the following:
  • Successful response: Details of one or more Agents that were enabled or disabled.
  • Unsuccessful response: Details of the error – severity, error code, and error message.

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 codeDescription
200Request completed successfully.
401Authorization error (invalid authorization token or authorization token not present).
400Agent name does not exist.
500

Can occur in the following scenarios:

  • Invalid action.
  • Unable to connect with the Agent.
    Example: On the Administration > Hosts page, if the Agent (associated with the host) is not a real Agent.