Job user role assignment

In the context of a job, a role (such as Underwriter) can be assigned to a user and group (such as Alice Applegate from the Los Angeles Branch UW group). The roles that can be assigned are defined in the UserRoles typelist.

Some job role assignment occurs automatically. For example, the Creator role is assigned automatically to the user who creates a job. Job roles can also be assigned manually.

A single user can have multiple roles on a job. However, a single job role cannot be held by more than one user.

In Cloud API, job roles are managed through a roles array. Every member of the array has the following structure:

"roles": [
  {
      "group": "<groupId>",
      "role": {
          "code": "<UserRolesCode>",
          "name": "<UserRolesName>"
      },
      "user": "<userId>"
  },

For example, the following roles array identifies Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:55) as the Creator and Underwriter for the job.

"roles": [
    {
        "group": "pc:55",
        "role": {
          "code": "Creator",
          "name": "Creator"
        },
        "user": "pc:8"
    },
    {
        "group": "pc:55",
        "role": {
            "code": "Underwriter",
            "name": "Underwriter"
        },
        "user": "pc:8"
    }
  ]

Use the following endpoint to retrieve a list of job role assignments for a job:

• GET /job/v1/jobs/{jobId}/user-roles

Use the following endpoint to assign a job role to a user on a given job:

• POST /job/v1/jobs/{jobId}/user-roles/assign

The request body must specify the user, group, and role using the syntax below.

{
    "data": {
        "attributes": {
          "group": "<groupId>",
          "role": {
            "code": "<UserRolesCode>"
          },
          "user": "<userId>"
        }
    }
}

Each call consist of one role being assigned to a group and user. If that role was already assigned to another user, it is reassigned to the specified user. Beyond that, other assignments on the job are not affected.

For example, the following assigns the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117) on job pc:9.

POST /job/v1/jobs/pc:9/user-roles/assign

{
    "data": {
        "attributes": {
          "group": "pc:1117",
          "role": {
            "code": "Auditor"
          },
          "user": "pc:220"
        }
    }
}

Use the following endpoint to PATCH the role assignment for a job:

• PATCH /job/v1/jobs/{jobId}/user-roles

You can use the PATCH endpoint to add or remove multiple role assignments in one call.

PATCHes in Cloud API are destructive, not additive. When you PATCH the roles array, the new content replaces the previous content entirely.

If you want to only add user role assignments to a job, the PATCH must contain all current members of the roles array as well as the new one.

• To add multiple role assignments or reassignments, add multiple new entries to the roles array.
• To remove role assignments, omit those entries from the roles array.
• If there are assignments you do not want to change, you must also include those assignments in the roles array.

For example, suppose job pc:9 has already assigned the roles of Creator and Underwriter to Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:55) and the role of Customer Rep to Chris Clark (pc:303) from the Los Angeles Branch UW group (pc:55). The following PATCH does the following:

• Adds the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117).
• Unassigns the role of Customer Rep. (This is done by omitting it from the roles array.)
• Makes no changes to the Creator or Underwriter roles. (They are included in the roles array with their original data.)

PATCH /job/v1/jobs/pc:9/user-roles

{
    "data": {
        "attributes": {
          "group": "pc:1117",
          "role": {
            "code": "Auditor"
          },
          "user": "pc:220"
        },
        {
          "group": "pc:55",
          "role": {
            "code": "Creator"
          },
          "user": "pc:8"
        },
        {
          "group": "pc:55",
          "role": {
            "code": "Underwriter"
          },
          "user": "pc:8"
        }
    }
}