Update Application Roles for Users

Updates application roles assigned to users provided in the REST API payload. To update an application 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 application 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.

This API is version v1.

Required Roles

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

REST Resource

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

Note:

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See Implementation Best Practices for Cloud EPM REST APIs. Using this REST API requires prerequisites. See Prerequisites.

Request

Supported Media Types: application/json

Table 12-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 an application role to assign to the user exactly as listed in Access Control.

For a list of application 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 12-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

The following examples show the contents of the response body in JSON format:

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'