Lease asset patch

This article explains how mutliple assets can be patched via the API.

General information

Patchable properties:

- serialNumber
- location
- locationOfInstallation
- orderNumber
- costCenter
- customerSpecificFields

The properties location, locationOfInstallation, orderNumber and costCenter can be renamed in Corporate Settings. This renaming only applies for the UI. The properties should always be sent with their original name in the API as seen above.
For all properties that are customer specific, the exact UI name has to be used.

This can be seen in the Example below.

Multiple asset patch

The general process to patch multiple assets at once is as follows: You send the request for all assets you want to patch to the endpoint. If your request is structually valid, the endpoint will accept your request and create a new bulk job, that will process the update. When you get the response from the PATCH endpoint, your patch has not been processed yet. The request is asynchronous, because we cannot guarantee that we can patch all assets within one HTTP Request. This means that once your request has been accepted, you have to query another endpoint with the id of the newly created bulk job, in order to retrieve the current status and potential errors of your desired patch operation.

In general the patch will only be accepted if we think it can be executed.

What we don't accept:

• invalid json
• a patch body that has at least one asset with property specified that cannot be patched or does not exist
• more than 10.000 assets
• a single request containing the same asset id more than once

Endpoints

• PATCH leases/assets: This endpoint only accepts the requests to patch multiple assets at once. Once the request has been accepted, the endpoint will return a 202 Accepted response containing the id, createdDate, assetsTotal and status of the created bulk job.
• GET leases/assets/bulkpatches/1: This endpoint is used to query the status with all errors that occurred for an already created bulk job.

Bulk job response

Example

Suppose we want to do the following changes:

• assetId: 111
  • serialNumber: abc123
• assetId: 222
  • costCenter: 70998
  • customerSpecificFields:
    • Employee name: Hans Peter
• assetId: 333
  • serialNumber: abc123

First we need to define our request body. Our changes can be translated to the following request body (note, that the order of the assets does not matter):

[
    {
        "assetId": 111,
        "serialNumber": "abc123"
    },
    {
        "assetId": 333,
        "serialNumber": "abc123"
    },
    {
        "assetId": 222,
        "costCenter": "70998",
        "customerSpecificFields":
        {
            "Employee name": "Hans Peter"
        }
    }
]

With this json as the body, we can then send a PATCH request to the endpoint leases/assets.

We then should get a 202 Accepted response, that could look like the following json:

{
    "id": 1337,
    "createDate": "2024-02-13T14:35:55.257",
    "assetsTotal": 3,
    "status": "notStarted",
    "errors": []
}

With this information we can then query the GET endpoint leases/assets/bulkpatches/1337 where "1337" is the id we got from the patch endpoint.

When the patch operation is still running we could get the following response:

{
    "id": 1337,
    "createDate": "2024-02-13T14:35:55.257",
    "startDate": "2024-02-13T14:35:56.233",
    "assetsTotal": 3,
    "assetsSuccessfullyUpdated": 1,
    "status": "inProgress",
    "errors": []
}

After the patch operation is finished, we would would get the following response:

{
    "id": 1337,
    "createDate": "2024-02-13T14:35:55.257",
    "startDate": "2024-02-13T14:35:56.233",
    "endDate": "2024-02-13T14:35:56.28",
    "assetsTotal": 3,
    "assetsSuccessfullyUpdated": 2,
    "status": "partiallySuccessful",
    "errors": [
        {
            "assetId": 333,
            "errors": [
                "Either an asset with the id '333' does not exist or it is not accessible to you."
            ]
        }
    ]
}