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:

Related topics

API for creating hosts

API for deleting hosts

API for enabling or disabling Agents

API for modifying tag details associated with hosts

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.


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

The endpoint response contains the following main elements:

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.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*