Update Granular Roles for Users

Updates granular roles assigned to users provided in the REST API payload. To update a granular role assigned to a user, that user 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 users 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/users/update

Request

Supported Media Types: application/json

Table 13-55 Request Parameters

Name Description Type Required Default
userlogin User login IDs of the user, whose role assignment is to be modified. Payload Yes None
 

The name of a granular role to assign to the user 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/users/update
{
  "users": [
    {
      "userlogin": "jdoe",	
      "roles": [
        {
          "rolename": "Access Control - Manage"
        },
        {
          "rolename": "Ad Hoc - Read Only User"
        }
      ]
    },
    {
      "userlogin": "jeff",
      "roles": [
        {
          "rolename": "Access Control - View"
        },
        {
          "rolename": "Ad Hoc - User"
        }
      ]
    }
  ]
}

Response

Supported Media Types: application/json

Table 13-56 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/users/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/users/update",
    "action": "PUT"
  },
  "status": 0,
  "error": null,
  "details": {
    "processed": 5,
    "succeeded": 3,
    "failed": 2,
    "faileditems": {
      "users": [
        {
          "userlogin": "jdoe",
          "erroritems": {
            "roles": [
              {
                "rolename": "AccessControl-Manage",
                "errorcode": "EPMCSS-21140",
                "errormessage": "Failed to update role.Role doesn’t exist in System. Provide valid rolename."
              }
            ]
          }
        },
        {
          "userlogin": "jeff",
          "erroritems": {
            "roles": [
              {
                "rolename": "Dashboards-Manage",
                "errorcode": "EPMCSS-21140",
                "errormessage": "Failed to assignrole. Role doesn’t exist in System. Provide valid rolename."
              }
            ]
          }
        },
        {
          "userlogin": "Jack",
          "errorcode": "EPMCSS-21141",
          "errormessage": "Failed to update role for user. User doesn't exist in System. Provide valid user."
        }
      ]
    }
  }
}

Example 3: REST API Completes with Partial Errors

{
  "links": {
    "href": "https://<BASE-URL>/interop/rest/security/v1/roles/application/users/update",
    "action": "PUT"
  },
  "status": 0,
  "error": null,
  "details": {
    "processed": 5,
    "succeeded": 3,
    "failed": 2,
    "faileditems": {
      "users": [
        {
          "userlogin": "jdoe",
          "erroritems": {
            "roles": [
              {
                "rolename": "AccessControl-Manage",
                "errorcode": "EPMCSS-21140",
                "errormessage": "Failed to update role.Role doesn’t exist in System. Provide valid rolename."
              }
            ]
          }
        },
        {
          "userlogin": "jeff",
          "erroritems": {
            "roles": [
              {
                "rolename": "Dashboards-Manage",
                "errorcode": "EPMCSS-21140",
                "errormessage": "Failed to assignrole. Role doesn’t exist in System. Provide valid rolename."
              }
            ]
          }
        },
        {
          "userlogin": "Jack",
          "errorcode": "EPMCSS-21141",
          "errormessage": "Failed to update role for user. User doesn't exist in System. Provide valid user."
        }
      ]
    }
  }
}

Sample cURL Command Basic Auth

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

Sample cURL Command OAuth 2.0

curl -X PUT --header "Authorization: Bearer <OAUTH_TOKEN>"  -H 'Content-Type: application/json' -d ' {"users":[{"userlogin":"jdoe","option":"overwrite","roles":[{"rolename":"Access Control - Manage"},{"rolename":"Dashboards - Manage"}]},{"userlogin":"jeff","option":"append","roles":[{"rolename":"Access Control - View"},{"rolename":"Dashboards - View"}]}]} ' 'https://<BASE-URL>/interop/rest/security/v1/roles/application/users/update'