# November 20, 2024 

** The November 20, 2024 Karbon API release adds the ability to retrieve and update User Role Assignments on Work and a new Webhook subscription type for Estimate Summaries **
---

## 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](https://karbonhq.github.io/karbon-api-reference/#tag--Work-Items) 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:

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

to:

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

The PUT request payload might then look like:

```JSON
{
  "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:
```JSON
{
  "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](https://karbonhq.github.io/karbon-api-reference/#post-/v3/WebhookSubscriptions) and [EstimateSummaries](https://karbonhq.github.io/karbon-api-reference/#get-/v3/EstimateSummaries/-WorkItemkey-) API documentation for more information.