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. - 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
://<host>:<port>/olaengine/itdaws/hostservices/groupaccessPUT
<protocol>/
<action>?host=<hostDetails>&type=<identifierType>&userGroupName=<userGroupNames>&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 add or remove user groups. Can be one of the following:
|
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
To specify multiple hosts, specify a comma-separated list of host names or host IDs. For more information, see examples. |
Optional, default is name | Type of identifier that must be used as criterion for providing host details. Can be one of the following:
|
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 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.
PUT
http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/add?host=HostB,HostC&type=name&userGroupName=TroubleshooterGroup
{
"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".
PUT
http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/add?host=HostB,HostE&type=name&userGroupName=TroubleshooterGroup,Administrators
{
"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".
PUT
http://localhost:9797/olaengine/itdaws/hostservices/groupaccess/remove?host=HostB&type=name&userGroupName=Administrators
{
"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
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:
|
Long | The total number of hosts modified. |
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 code | Description |
---|---|
200 | Request completed successfully. |
400 | Invalid inputs:
|
401 | Authorization 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. |
Comments
Log in or register to comment.