Use this API to modify user group permissions for existing hosts.
Notes
login
API. 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 API.logout
API.For more information, see Developing.
This topic contains the following information:
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.
://<host>:<port>/olaengine/itdaws/hostservices/groupaccessPUT
<protocol>/
<action>?host=<hostDetails>&type=<identifierType>&userGroupName=<userGroupNames>&version=
<apiVersion>
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. |
The following examples illustrate the inputs for adding or removing user groups by using the PUT method.
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 }
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 }
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 }
The following sections help you understand the response elements:
The API 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. |
See examples.
{ "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 }
The following table describes the status codes that are likely to appear while working with this API.HTTP status codes
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. |