Modifying tag details associated with hosts with a REST API

Use this endpoint to modify tag details for existing hosts.

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.
  • If the check.csrf.header.XRequestedWith header property in the olaengineConfig.properties file is set to TRUE, then you need a new header 
    X-Requested-With=XMLHttpRequest to 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 logout endpoint.

For more information, see Developing.

This topic contains the following information

Endpoint overview

Use the PUT method to add or remove tag details associated with one or more hosts.

You can add or remove tags associated with hosts by specifying the host names or host IDs. You can add or remove tag details for multiple hosts by specifying a comma-separated list of host names or host IDs. You can obtain the host ID by running the API for listing host details.

If the specified tag name does not exist, the API ignores the details, and does not perform any action on it.

Request URL

PUT <protocol>://<host>:<port>/olaengine/itdaws/hostservices/tags/<action>?host=<hostDetails>&type=<identifierType>&version=<apiVersion>

Request body

To understand the structure of the request body, see the examples.

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 add or remove tags.

Can be one of the following:

  • add: Set this value to associate new tags to one or more hosts.
  • remove: Set this value to remove existing tags associated with one or more hosts.

Note: You can only add tags that already exist in the system.

host

Required

Details of the hosts on which you want to perform the action – associate new tags or remove existing tags.

Depending on the value of the type parameter, the value can be one of the following:

To specify multiple hosts, specify a comma-separated list of host names or host IDs. For more information, see examples.

type

Required

Type of identifier that must be used as criterion for providing host details.

Can be one of the following:

  • name: Set this value if you plan to specify host names.
  • id: Set this value if you plan to specify host IDs.

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 adding or removing tags by using the PUT method.

Example 1: Associate new tags to a single host

The following example illustrates the inputs and response for adding the following new tags, to a single host by specifying the host name, "HostA".

  • Tag name, "os" with corresponding tag values, "Windows" and "Linux".
  • Tag name, "Application Context" with corresponding tag values, "APP2" and "APP3".
Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/tags/add?host=HostA&type=name

Request body
{
  "os": [
   "Windows",
   "Linux"
  ],
  "ApplicationContext": [
   "APP2",
   "APP3"
  ]
}
Response
{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "host": {
            "id": "50976f92-793e-4d14-b644-c02ce632d32a",
            "name": "HostA",
            "instanceName": "HostA",
            "agents": [{
                "agentId": "collection-station_Hou.bmc.com",
                "agentName": "collection-station_Hou.bmc.com",
                "enabled": false
            }],
            "tagsList": {
                "ApplicationContext": ["NewTag_2", "APP2", "APP3"],
                "os": ["Windows", "Linux"]
            },
            "userGroupList": [{
                "userGroupId": "1b9ef5be-850c-49fe-b931-da19336d763e",
                "userGroupName": "AppAdminGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }, {
                "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
                "userGroupName": "TroubleshooterGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }, {
                "userGroupId": "f821278d-2dce-4fb2-92ba-dc34c024ab00",
                "userGroupName": "Administrators",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }],
    "totalRecords": 1,
    "pageSize": 0
}

Example 2: Remove tags from multiple hosts

The following example illustrates the inputs and response for removing an existing tag name, "Tier" with corresponding tag values, "DB" and "UI", associated with the following hosts.

  • "HostB"
  • "HostC"
Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/tags/remove?host=HostB,HostC&type=name

Request body
{
  "Tier": [
   "DB",
   "UI"
  ]
}
Response
{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "host": {
            "id": "923d9231-89c5-484d-8cab-9d23f86ba1dc",
            "name": "HostB",
            "instanceName": "HostB",
            "agents": [{
                "agentId": "Agent1.bmc.com",
                "agentName": "Agent1.bmc.com",
                "enabled": true
            }],
            "userGroupList": [{
                "userGroupId": "1b9ef5be-850c-49fe-b931-da19336d763e",
                "userGroupName": "AppAdminGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }, {
        "host": {
            "id": "bf6051b9-a17b-47bc-ac42-adb4746c3903",
            "name": "HostC",
            "instanceName": "HostC",
            "agents": [{
                "agentId": "Agent1.bmc.com",
                "agentName": "Agent1.bmc.com",
                "enabled": true
            }],
            "userGroupList": [{
                "userGroupId": "1b9ef5be-850c-49fe-b931-da19336d763e",
                "userGroupName": "AppAdminGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }],
    "totalRecords": 2,
    "pageSize": 0
}

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.

hosts

Array

Can be one of the following:
  • Successful response: Details of one or more hosts modified.
    The parameters in the array have one-to-one mapping with the inputs specified in the request body.
  • Unsuccessful response: Details of the error – severity, error code, and error message.

totalRecords

Long

The total number of hosts modified.

pageSize

Long

By default, the value displayed is zero.

Successful response sample

See examples.

Unsuccessful response sample

{
    "statusCode": "400",
    "statusMessage": "Bad Request",
    "hosts": [{
        "messages": [{
            "severity": "Error",
            "code": "entity.does.not.exist",
            "text": "Invalid Host Name. Host Name with value host5 does not exist."
        }, {
            "severity": "Error",
            "code": "entity.does.not.exist",
            "text": "Invalid Host Name. Host Name with value host6 does not exist."
        }]
    }],
    "totalRecords": 1,
    "pageSize": 0
}

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

Invalid inputs:

  • Tag name does not exist.
  • Host name does not exist.
401Authorization error (invalid authorization token or authorization token not present).
500

Error occurred while processing the request. Occurrence of this error is rare.

For more information, see the error message. Alternatively, see the itda.log located at %BMC_ITDA_HOME%\logs.


Was this page helpful? Yes No Submitting... Thank you

Comments