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.