Purpose

The update operation in JQL is used to modify existing resources in Antly’s backend system. This operation allows you to change the values of specific fields within a resource, based on specified criteria. The update operation is essential for maintaining and correcting data, as well as adapting records to reflect changes over time.

Syntax

The JSON structure for an update operation in JQL typically includes the following components:

• __meta__: Metadata about the query, including authentication details, the intent (update), the target namespace, the schema, and the unique identifier of the resource to be updated.
• Data Fields: The fields within the resource that need to be updated, each specified with the new value.

General Update Operation Structure:

{
    "__meta__": {
        "authenticationClass": "<authentication_method>",
        "intent": "update",
        "namespace": "<module_name>",
        "schema": "<schema_type>",
        "return": { "<field_to_return>": null }, // Optional: Specify fields to be returned after update
        "uniqueObject": {
            "id": "<instance_id>" // Identifier of the resource to be updated
        }
    },
    "<field_name_1>": "<new_value_1>",
    "<field_name_2>": "<new_value_2>",
    // Additional fields to be updated
}

Example: Sample Query

Let's assume we are updating the details of an existing vehicle in the fleet.Vehicle namespace. The query would look like this:

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "update",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "return": { "id": null }, // This will return the ID of the updated vehicle
        "uniqueObject": {
            "id": "67890" // The ID of the vehicle to be updated
        }
    },
    "gearbox": "manual",
    "model_colour": "Fleet_ModelColourType",
    "purchase_type": "cash",
    "vin": "1HGCM82633A004352",
    "vrm": "XY34ZFG",
    "year": "2025"
}

In this example:

• authenticationClass: Indicates that JWT token authentication is used.
• intent: Specifies the operation as update.
• namespace: Targets the fleet.Vehicle module.
• schema: Indicates that the operation is on the model schema.
• return: Requests that the ID of the updated vehicle be returned.
• uniqueObject: Specifies the unique identifier (id) of the vehicle to be updated.
• Data Fields: Includes the fields to be updated, such as gearbox type, model colour, purchase type, VIN, VRM, and year.

Example: Sample Response

Upon successful execution of the update operation, the response might look like this:

{
    "status": "OK",
    "data": {
        "id": "67890" // The ID of the updated vehicle
    },
    "errors": null,
    "il8n": "en-gb",
    "extras": {
        "filtered": 1,
        "display": 1,
        "queries": 1
    },
    "system_info": null,
    "intent": "update",
    "message": "Vehicle updated successfully."
}

In this response:

• status: Indicates that the operation was successful (OK).
• data: Contains the ID of the updated vehicle.
• errors: Will be null if no errors occurred.
• il8n: Specifies the locale used (en-gb).
• extras: Provides additional details about the operation, such as the number of filtered and displayed results.
• intent: Reflects the intent of the operation (update).
• message: Provides a human-readable message indicating the success of the operation.