Update Granular Roles For Groups

Updates granular roles assigned to EPM or IDCS groups provided in the REST API payload. To update the granular role assigned an IDCS group, that group should already have a predefined role assigned to it.

This version contains all parameters in the payload and does not require URL encoding while calling the REST APIs.

The API is synchronous and returns the outcome of the operation in the response. Any non-zero status indicates that updating groups granular roles failed. With this API, you can see which records failed and the reason why they failed, in addition to how many records passed and failed.

Required Roles

Service Administrator or any predefined role and the Access Control - Manage granular role

REST Resource

PUT /interop/rest/security/v1/roles/application/groups/update

Request

Supported Media Types: application/json

Table 13-53 Request Parameters

Name Description Type Required Default
groupname Name of group whose granular role assignment is to be modified. Payload Yes None
rolename

The name of an granular role to assign to the group exactly as listed in Access Control.

For a list of granular roles, see these links in Administering Access Control: 		Payload Yes None

Example URL and Payload

https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update
{
  "groups": [
    {
      "groupname": "EPMGroup1",
      "roles": [
        {
          "rolename": "Access Control - Manage"
        },
        {
          "rolename": "Ad Hoc - Read Only User"
        }
      ]
    },
    {
      "groupname": "IDCSGroup1",
      "roles": [
        {
          "rolename": "Access Control - View"
        },
        {
          "rolename": "Ad Hoc - User"
        }
      ]
    }
  ]
}

Response

Supported Media Types: application/json

Table 13-54 Response Parameters

Name Description
links Detailed information about the link and HTTP call type
status

Identifies the status of the operation

  • 0 - Operation succeeded

  • 1 - Operation failed
error Detailed information about the error
details Detailed status of the operation performed. Total number of records processed, succeeded, and failed, and the reason for why they failed.

Examples of Response Body

Example 1: REST API Issued without any Payload Completes without Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update",
    "action": "PUT"
  },
  "status": 0,
  "error": null,
  "details": {
    "processed": 2,
    "succeeded": 2,
    "failed": 0,
    "faileditems": null
  }
}

Example 2: REST API Completes with Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update",
    "action": "PUT"
  },
  "status": 1,
  "error": {
    "errorcode": "EPMCSS-21192",
    "errormessage": "Failed to update granular roles for group. Authorization failed. Please provide valid authorized user."
  },
  "details": null
}

Example 3: REST API Completes with Partial Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update",
    "action": "PUT"
  },
  "status": 0,
  "error": null,
  "details": {
    "processed": 5,
    "succeeded": 3,
    "failed": 2,
    "faileditems": [
      {
        "groupname": "EPMGroup1",
        "errorcode": "EPMCSS-21140",
        "errormessage": " Failed to update granular roles for group. Found invalid role(s). Provide valid granular role(s).",
        "erroritems": {
          "roles": [
            {
              "rolename": "AccessControl-Manage",
              "errorcode": "EPMCSS-21140",
              "errormessage": "Failed to update granular role for group. Role doesn’t exist in System. Provide valid rolename."
            }
          ]
        }
      },
      {
        "groupname": "IDCSGroup1",
        "errorcode": "EPMCSS-21140",
        "errormessage": "Failed to update granular roles for group. Found invalid role(s). Provide valid granular role(s).",
        "erroritems": {
          "roles": [
            {
              "rolename": "Dashboards-Manage",
              "errorcode": "EPMCSS-21140",
              "errormessage": "Failed to update granular role for group. Role doesn’t exist in System. Provide valid rolename."
            }
          ]
        }
      },
      {
        "groupname": "IDCSGroup2",
        "errorcode": "EPMCSS-21141",
        "errormessage": "Failed to update granular role for group. Group doesn't exist in System. Provide valid Group.",
        "roles": null
      }
    ]
  }
}

Sample cURL Command Basic Auth

curl -X PUT -s -u '<USERNAME>:<PASSWORD>' -H 'Content-Type:application/json' -d '{"groups":[{"groupname":"IDCSGroup1","roles":[{"rolename":"Access Control - Manage"},{"rolename":"Dashboards - Manage"}]},{"groupname":"epmgroup1","roles":[{"rolename":"Access Control - View"},{"rolename":"Dashboards - View"}]}]}' 'https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update'

Sample cURL Command OAuth 2.0

curl -X PUT --header "Authorization: Bearer <OAUTH_TOKEN>" -H 'Content-Type:application/json' -d ' {"groups":[{"groupname":"IDCSGroup1","roles":[{"rolename":"Access Control - Manage"},{"rolename":"Dashboards - Manage"}]},{"groupname":"epmgroup1","roles":[{"rolename":"Access Control - View"},{"rolename":"Dashboards - View"}]}]}' 'https://<BASE-URL>/interop/rest/security/v1/roles/application/groups/update'