Managing Entity Roles
It is possible to set entity roles for an entity. These are business-level roles defined in the L3 that can be added by a user to a specific entity in the edit mode of the UI or via the API. For example, in Life Sciences these roles might be 'physician', 'nurse', or 'resident'. The benefit of the entity-role feature and its associated attribute is that in the UI, it provides an automatic drop-down list with an ability for the user to see all pre-defined values and an ability to place a checkmark next to any subset of them to select that subset for the entity of interest. For example, the user might select Physician, Resident, and Staff Member to characterize a doctor as all three roles. See the Entity Roles topic for more information about Entity Roles. (To be clear, Entity Roles are not the type of roles which are added to a user's Reltio profile which give the user various levels of functionality and access when using the Reltio platform.)
Add Roles
This operation adds roles to an entity object.
Request
POST {TenantURL}/{entity object URI}/roles| Parameter | Required | Description | |
|---|---|---|---|
| Headers | Authorization | Yes | Information about authentication access token in format "Bearer
<accessToken>" (see details in Authentication API). |
Content-Type
| Yes | Should be "Content-Type: application/json". | |
| Query |
returnObjects
|
Specifies if the response should contain the created objects. Note: Default value is true. | |
Body
| Yes | JSON array with URI of roles to be added (for example, the path used to reach the role). It has the format: configuration/roles/{RoleName}. The following optional properties can also be included: label (the readable name of the role) and description (the description of a role). | |
Response
JSON object representing result of an add operation. Result contains:
status: result of operation; possible values areOKorfailedarray: JSON array of entity roles created
Example Request
POST {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body
["configuration/roles/Client", "configuration/roles/Doctor"]Example Response
POST {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body
{
"status": "OK",
"array": ["configuration/roles/Client", "configuration/roles/Doctor"]
}Overwrite Roles
This operation overwrites roles in entity object.
Request
PUT {TenantURL}/{entity object URI}/roles| Parameter | Required | Description | |
|---|---|---|---|
| Headers | Authorization | Yes | Information about authentication access token in format "Bearer
<accessToken>" (see details in Authentication API). |
Content-Type
| Yes | Should be "Content-Type: application/json". | |
| Query |
returnObjects
|
Specifies if the response should contain the created objects. Note: Default value is true. | |
Body
| Yes | JSON array with URI of roles to be added. | |
Response
JSON object representing result of an add operation. Result contains:
status: result of operation; possible values areOKorfailedarray: JSON array of entity roles created
Example Request
PUT {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body
["configuration/roles/Client", "configuration/roles/Doctor"]Example Response
PUT {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512, Content-Type: application/json
Body
{
"status": "OK",
"array": ["configuration/roles/Client", "configuration/roles/Doctor"]
}Get Entity Roles
Returns all roles for an entity.
Request
GET {TenantURL}/{entity object URI}/roles| Parameters | Name | Required | Details |
|---|---|---|---|
| Headers | Authorization | Yes | Information about authentication access token in format "Bearer
<accessToken>" (see details in Authentication API). |
Response
An array of URIs for roles that an entity has.
Example Request
GET {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512Example Response
GET {TenantURL}/entities/1/roles
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
["configuration/roles/Client", "configuration/roles/Doctor"]Delete Role
Deletes a role from an entity.
Request
DELETE {TenantURL}/{entity object URI}/roles| Parameter | Required | Description | |
|---|---|---|---|
| Headers | Authorization | Yes | Information about authentication access token in format "Bearer
<accessToken>" (see details in Authentication API). |
| Query | element | Yes | Passes the URI of an element from the roles array to be deleted |
Response
JSON Object representing result of a delete operation. Result contains:
status- result of operation; possible values aresuccessorfailed
Example Request
DELETE {TenantURL}/entities/1/roles?element='configuration/roles/Nurse'
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512Example Response
DELETE {TenantURL}/entities/1/roles?element='configuration/roles/Nurse'
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
Body
{
"status": "failed"
"error": {
"errorCode": NNN,
"errorMessage": "'/entities/1' doesn't have 'configuration/roles/Nurse' role to be deleted",
"errorDetailMessage": "..."
},
}