Modifying user groups associated with hosts with a REST API

Use this endpoint to modify user group permissions 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 user groups associated with one or more hosts.

When you associate user groups to a host, data collected from that host is only available to the user groups specified. You can use this API to change user groups associated with hosts and thereby control access to the data collected.

To enable the user group permissions specified, you need to ensure that data access control is enabled at Administration > System Settings.

Request URL

PUT <protocol>://<host>:<port>/olaengine/itdaws/hostservices/groupaccess/<action>?host=<hostDetails>&type=<identifierType>&userGroupName=<userGroupNames>&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 add or remove user groups.

Can be one of the following:

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

host

Required

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

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

Optional, default is name

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.

userGroupName

Required

Name of the user group that you want to add or remove from the hosts specified.

To add or remove multiple user groups, specify a comma-separated list of user group names.

Note: You can only specify user group names that already exist in the system. For more information about adding user groups, see Managing user groups in IT Data Analytics.

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.


Example

The following examples illustrate the inputs for adding or removing user groups by using the PUT method.

Example 1: Add a single user group to multiple hosts

The following examples illustrates the input and response for associating the user group "TroubleshooterGroup", with hosts, "HostB" and "HostC.

Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/add?host=HostB,HostC&type=name&userGroupName=TroubleshooterGroup

Response
{
    "statusCode": "200",
    "statusMessage": "OK",
    "hosts": [{
        "host": {
            "id": "708d7095-e8a9-4633-b53b-def5d293776f",
            "name": "HostB",
            "instanceName": "HostB",
            "agents": [{
                "agentId": "Agent1.bmc.com",
                "agentName": "Agent1.bmc.com",
                "enabled": true
            }],
            "tagsList": {
                "os": ["Linux", "Windows"]
            },
            "userGroupList": [{
                "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
                "userGroupName": "TroubleshooterGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }, {
        "host": {
            "id": "32e08e0a-2331-4007-9436-bc40a00f69e0",
            "name": "HostC",
            "instanceName": "HostC",
            "agents": [{
                "agentId": "Agent2.bmc.com",
                "agentName": "Agent2.bmc.com",
                "enabled": true
            }],
            "tagsList": {
                "tier": ["AppServer", "WebServer"]
            },
            "userGroupList": [{
                "userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
                "userGroupName": "TroubleshooterGroup",
                "deletable": null,
                "organizationID": null,
                "users": null
            }]
        }
    }],
    "totalRecords": 2,
    "pageSize": 0
}

Example 2: Add multiple user groups to multiple hosts

The following example illustrates the input and response for associating user groups "TroubleshooterGroup" and "Administrators" with hosts, "HostD" and "HostE".

Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/add?host=HostB,HostE&type=name&userGroupName=TroubleshooterGroup,Administrators

Response
{
	"statusCode": "200",
	"statusMessage": "OK",
	"hosts": [{
		"host": {
			"id": "ae9890d7-40c1-4ca5-82bd-e58b81ada358",
			"name": "HostD",
			"instanceName": "HostD",
			"agents": [{
				"agentId": "Agent1.bmc.com",
				"agentName": "Agent1.bmc.com",
				"enabled": true
			}],
			"userGroupList": [{
				"userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
				"userGroupName": "TroubleshooterGroup",
				"deletable": null,
				"organizationID": null,
				"users": null
			}, {
				"userGroupId": "8fad3e87-594b-4c5b-a1ca-65fc75240b8c",
				"userGroupName": "Administrators",
				"deletable": null,
				"organizationID": null,
				"users": null
			}]
		}
	}, {
		"host": {
			"id": "f0cf44d7-4d5c-4578-905a-ed5e8c3b3cce",
			"name": "HostE",
			"instanceName": "HostE",
			"agents": [{
				"agentId": "Agent1.bmc.com",
				"agentName": "Agent1.bmc.com",
				"enabled": true
			}],
			"userGroupList": [{
				"userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
				"userGroupName": "TroubleshooterGroup",
				"deletable": null,
				"organizationID": null,
				"users": null
			}, {
				"userGroupId": "8fad3e87-594b-4c5b-a1ca-65fc75240b8c",
				"userGroupName": "Administrators",
				"deletable": null,
				"organizationID": null,
				"users": null
			}]
		}
	}],
	"totalRecords": 2,
	"pageSize": 0
}

Example 3: Remove a single user group from a single host

The following example illustrates the input and response for removing the user group, "Administrators" from the host, "HostB".

Request URL

PUT http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/remove?host=HostB&type=name&userGroupName=Administrators

Response
{
	"statusCode": "200",
	"statusMessage": "OK",
	"hosts": [{
		"host": {
			"id": "ae9890d7-40c1-4ca5-82bd-e58b81ada358",
			"name": "HostB",
			"instanceName": "HostB",
			"agents": [{
				"agentId": "Agent1.bmc.com",
				"agentName": "Agent1.bmc.com",
				"enabled": true
			}],
			"userGroupList": [{
				"userGroupId": "cb5d776a-0831-4a20-a3f5-37b7a7d043c3",
				"userGroupName": "TroubleshooterGroup",
				"deletable": null,
				"organizationID": null,
				"users": null
			}]
		}
	}],
	"totalRecords": 1,
	"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 UserGroupName. UserGroupName with value App1AdminGroup 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:

  • User group 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