User roles
A system permission is a granular permission that identifies something a user can view, edit, create, or otherwise work with.
A user role is a named group of system permissions. User roles simplify the work of granting access by allowing a set of related system permissions to be assigned to a user. (Note that in most Guidewire documentation, user roles are referred to simply as "roles". The Cloud API documentation uses the term "user role" to help distinguish them from "API roles", which is a feature with a similar purpose but different underlying functionality.)
Querying for user roles
To retrieve information about user roles, use the following endpoints:
- GET
/admin/v1/roles
- GET
/admin/v1/roles/{roleId}
For example, the following is the snippet of the response payload when retrieving the first four roles in the base configuration.
GET /admin/v1/roles?pageSize=4
{
"count": 5,
"data": [
{
"attributes": {
"carrierInternal": true,
"description": "Permissions for account admin",
"displayName": "Account Manager",
"id": "account_manager",
"name": "Account Manager"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "All permissions related to activity rules",
"displayName": "Activity Rules Admin",
"id": "activity_rules_admin",
"name": "Activity Rules Admin"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "Permissions to edit activity rules",
"displayName": "Activity Rules Editor",
"id": "activity_rules_editor",
"name": "Activity Rules Editor"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "Permissions to view activity rules",
"displayName": "Activity Rules Viewer",
"id": "activity_rules_viewer",
"name": "Activity Rules Viewer"
}
}
]
}
Querying for permissions in a user role
To retrieve information about the permissions in a given user roles, use the following endpoints:
- GET
/admin/v1/roles/{roleId}/permissions
- GET
/admin/v1/roles/{roleId}/permissions/{permissionId}
For example, the following is the snippet of the response payload when retrieving the first three permissions associated with a "claims_adjuster" role:
GET /admin/v1/roles/claims_adjuster/permissions
{
"count": 25,
"data": [
{
"attributes": {
"id": "sample_data:213",
"permission": {
"code": "lvprint",
"name": "Print listviews"
}
},
...
},
{
"attributes": {
"id": "sample_data:222",
"permission": {
"code": "searchpols",
"name": "Search related policies"
}
},
...
},
{
"attributes": {
"id": "sample_data:210",
"permission": {
"code": "actview",
"name": "View activities"
}
},
...
},
...
Creating user roles
To create a role through Cloud API, you must use multiple endpoints. The role itself is
created using the /roles
endpoint. Permissions are added to the role
using the /permissions
endpoint.
Create the role
To create a role, use the following endpoint:
- POST
/admin/v1/roles
For new roles, you must specify the following:
name
roleType
roleType
must be a value from the RoleType
typelist. The following table summarizes the role types available in
InsuranceSuite.
Name | Code | Description | Application |
---|---|---|---|
User Role | user |
Role associated with Users | All InsuranceSuite applications |
Producer Code Role | producercode |
Role associated with Producer Codes | PolicyCenter only |
User Producer Code Role | userproducercode |
Role associated with Users and Producer Codes | PolicyCenter only |
For example, the following creates a new user role for users named "finance_admin".
POST /admin/v1/roles
{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"name": "finance_admin"
}
}
}
Add permissions to the role
To add a permission to a role, use the following endpoint:
- POST
/admin/v1/roles/{roleId}/permissions
You must specify the permission to be added by its code from the
SystemPermissionType
typelist.
For example, the following adds the notecreate
permission to the
user role with id xc:222.
POST /admin/v1/roles/xc:222/permissions
{
"data": {
"attributes": {
"permission": {
"code": "notecreate"
}
}
}
}
There is no way to specify multiple permissions in a single call to the
/permissions
endpoint. You must invoke the
/permissions
endpoint once for each permission to be added to a
role.
Creating user roles with permissions in a single call
You can create a user role and one or more permissions for the role in a single call
using request inclusion. In this case, the name of the included resource is
RolePermission
. For more information on request inclusion, see
Request and response inclusion.
For example, the following call creates a user role with one permission.
POST /admin/v1/roles
{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"name": "finance_admin"
}
},
"included": {
"RolePermission": [
{
"attributes": {
"permission": {
"code": "noteview"
}
},
"method": "post",
"uri": "/admin/v1/roles/this/permissions"
}
]
}
}
Updating user roles
Use the following endpoints to modify an existing role.
Endpoint | Description |
---|---|
PATCH /admin/v1/roles/{roleId} |
Modify attributes about the role, such as its name or description |
DELETE
/admin/v1/roles/{roleId}/permissions/{permissionId} |
Remove a permission from a role |
DELETE /admin/v1/roles/{roleId} |
Delete a role |
Example of PATCHing a role
The following request modifies the name and description of role xc:222.
PATCH /admin/v1/roles/xc:222
{
"data": {
"attributes": {
"name": "Finance Administrator",
"description": "User role for finance administrators"
}
}
}
Example of removing a permission
The following request removes the permission with id xc:515 (notecreate) from role xc:222.
DELETE /admin/v1/roles/xc:222/permissions/xc:515
<no request body>
Example of DELETEing a role
The following request deletes role xc:222.
DELETE /admin/v1/roles/xc:222
<no request body>
You cannot a delete a role if it is associated with one or more users.