November 20, 2024

Retrieve and Update User Role Assignments

GET / PUT WorkItems

Endpoint:

When retrieving a single Work Item a collection of User Role assignments is now included in the API response under the

collection, each item in the collection consisting of a and a .

• JSONCopyCopied!

  RoleKey
  is defined in WorkTemplates API responses as
  JSONCopyCopied!

  ActorKey
  .
• JSONCopyCopied!

  UserProfileKey
  is the
  JSONCopyCopied!

  UserId
  returned in the Users API endpoints.

To update one of more of the roles, the

collection should be included in a PUT request to update a Work Item. The User for any role can be changed by providing a new for that role. The is fixed and cannot be changed.

When a role is reassigned:

• the Role will be moved to the new user
• any incomplete tasks assigned to the reallocated role will be reassigned to the user
• any remaining budget for the reallocated role will be assigned to the new user

Refer to the Work API documentation for a full request and response payloads from these endpoints.

Example use case

You have used the API to create a Work Item called Monthly Accounting using an existing Work Template which has two roles defined: "Accountant" and "Admin". You wish to reassign the Accountant role to a new hire.

You'll need:

• the
  JSONCopyCopied!

  UserId
  of the new staff member to be assigned to the role.

Process:

1. Make a GET request to the
   JSONCopyCopied!

   WorkItems
   endpoint
   JSONCopyCopied!

   https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}
   to retrieve the existing work item data
2. Use the
   JSONCopyCopied!

   WorkTemplateKey
   property in the existing data to retrieve the Work Template and find the
   JSONCopyCopied!

   RoleKey
   of the role that "Accountant" role needs changing
3. Modify the
   JSONCopyCopied!

   UserProfileKey
   for the Accountant role in the data retrieved in step 1.
4. Make a PUT request to the
   JSONCopyCopied!

   WorkItems
   endpoint
   JSONCopyCopied!

   https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}
   with the new payload.

For example: we wish to change the assignment of the

value from previous of to . The UserRoleAssignment would be modified from:

JSONCopyCopied!
{
  "RoleKey": "3m5lFYh11FvM",
  "UserProfileKey": "dd5sM3qrQLT"
}

to:

JSONCopyCopied!
{
  "RoleKey": "3m5lFYh11FvM",
  "UserProfileKey": "2Bpd78LBHJ58"
}

The PUT request payload might then look like:

JSONCopyCopied!
{
  "WorkItemKey": "2LPSrkzbYrn4",
  "AssigneeEmailAddress": "joe@example.com",
  "AssigneeKey": "4gHCvnbFFqsq",
  "AssigneeName": "Joe Min",
  "Title": "Monthly Accounting - November 2024",
  "ClientKey": "4ncPZ7q96SGc",
  "ClientName": "Acme Corporation",
  "ClientType": "Organization",
  "StartDate": "2024-11-01T00:00:00Z",
  "DueDate": "2024-12-04T00:00:00Z",
  "DeadlineDate": "2024-12-12T00:00:00Z",
  "CompletedDate": null,
  "ToDoPeriod": null,
  "WorkType": "Accounting",
  "WorkStatus": "Ready To Start",
  "PrimaryStatus": "Ready To Start",
  "SecondaryStatus": null,
  "WorkTemplateKey": "p56mtcBhwb9",
  "WorkTemplateTile": "Monthly Accounting",
  "WorkScheduleKey": null,
  "FeeSettings": {
    "FeeType": "FixedFee",
    "FeeValue": 1500.00
  },
  "UserRoleAssignments": [
    {
      "RoleKey": "2mYzTtly89Lq",
      "UserProfileKey": "2Qy48WVCRBcP"
    },
    {
      "RoleKey": "3m5lFYh11FvM",
      "UserProfileKey": "2Bpd78LBHJ58"
    }
  ],
  "Description": "Monthly Accounting",
  "ClientTaskRecipient": null
}

Notes

• roles, budgets and tasks cannot be reassigned individually
• unassigned tasks will have
  JSONCopyCopied!

  null
  for the
  JSONCopyCopied!

  UserProfileKey
  - it is possible to leave these as
  JSONCopyCopied!

  null
  to avoid reassignment
• it is not possible to unassign a previously assigned role
• a role cannot be assigned to an inactive user

EstimateSummary Webhook notifcations

It is now possible to create a webhook subscription to be notified when an Estimate Summary changes. You can do this be using the value

for .

When triggered, a webhook notificaiton will be send to the subscribed

with a payload such as:

JSONCopyCopied!
{
  "ResourcePermaKey": "XkHRCdrg8yQ",
  "ResourceType": "Estimate",
  "ActionType": "Updated",
  "Timestamp": "2024-11-20T05:13:11Z"
}

The

can be used with the API endpoint to retrieve the updated data.

Refer to the Webhook Subscription and EstimateSummaries API documentation for more information.