Home

November 20, 2024

Retrieve and Update User Role Assignments

GET / PUT WorkItems

Endpoint: https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}

When retrieving a single Work Item a collection of User Role assignments is now included in the API response under the UserRoleAssignments collection, each item in the collection consisting of a UserProfileKey and a RoleKey.

  • RoleKey is defined in WorkTemplates API responses as ActorKey.
  • UserProfileKey is the UserId returned in the Users API endpoints.

To update one of more of the roles, the UserRoleAssignments 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 UserProfileKey for that role. The RoleKey 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 UserId of the new staff member to be assigned to the role.

Process:

  1. Make a GET request to the WorkItems endpoint https://api.karbonhq.com/v3/WorkItems/{WorkItemKey} to retrieve the existing work item data
  2. Use the WorkTemplateKey property in the existing data to retrieve the Work Template and find the RoleKey of the role that “Accountant” role needs changing
  3. Modify the UserProfileKey for the Accountant role in the data retrieved in step 1.
  4. Make a PUT request to the WorkItems endpoint https://api.karbonhq.com/v3/WorkItems/{WorkItemKey} with the new payload.

For example: we wish to change the assignment of the RoleKey value 3m5lFYh11FvM from previous UserProfileKey of dd5sM3qrQLT to 2Bpd78LBHJ58. The UserRoleAssignment would be modified from:

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

to:

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

The PUT request payload might then look like:

{
  "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 null for the UserProfileKey - it is possible to leave these as 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 EstimateSummary for WebhookType.

When triggered, a webhook notificaiton will be send to the subscribed TargetUrl with a payload such as:

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

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

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