Handling Locked ACC files with APS

Introduction

In this blog, we'll cover the Lock Files feature from ACC Docs from API perspective.

Before reading this blog, please refer to Lock Files and read the documentation for this feature if you're not familiar with that.

How it works?

As described in the documentation, members with Edit permission or above can lock files to prevent other members from deleting, moving, renaming, editing custom attribute values, or overwriting the file.

As a best practice, you should always verify if an item is reserved before performing any modification.

If you try to modify a locked file without proper permission, you will receive a 403 response with a message like the one below:

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "id": "4bqw9e70-8r11-4we3-b13b-0a3dsf41a261",
      "status": "403",
      "code": "ERR_WIP_ERROR",
      "title": "RESERVATION_LINEAGE_RESERVED",
      "detail": "[WIP] The target lineage is reserved and can only be modified by the reserving user"
    }
  ]
}

There are two ways to know if a file is locked.

Through Webhooks API

There are two specific webhooks events addressing locked files:

1. dm.lineage.reserved - Triggered once a file is locked by a user
2. dm.lineage.unreserved - Triggered once a file is unlocked by a user

You can take advantage of those to get notified based on these actions.

You can also check that with Data Management API.

Through Data Management API

Once you retrieve data from an item in the response, it always comes with the reserved field.

If the item is not locked, the response will be like the one below:

{
...
  "type": "items",
  "id": "urn:adsk.wipprod:dm.lineage:yasldjas_flg",
  "attributes": {
    ...
    "reserved": false,
    ...
}

If the item is locked, the response will be like the one below:

{
...
  "type": "items",
  "id": "urn:adsk.wipprod:dm.lineage:yasldjas_flg",
  "attributes": {
    ...
    "reserved": true,
    "reservedTime": "2024-07-30T18:22:27.0000000Z",
    "reservedUserId": "USHRKLENFK",
    "reservedUserName": "João Martins",
    ...
}

If a file is locked (reserved=true) you have two options:

1. Perform the modification on behalf of a user with proper permission (either using the x-user-id header or a three-legged token)
2. Unlock the file and then perform the modification.

You can unlock a file using the PATCH item endpoint.

Keep in mind that to unlock an item, you'll also need to pass the x-user-id header (in case of two-legged token) or a three-legged token with a user context that has a proper permission.

You can find a complete workflow addressing locked files with Webhooks and Data Management in the video below: