Purpose

The create operation in JQL is used to add new resources to Antly’s backend system. This operation allows you to create a new instance of a resource, such as a vehicle, user, or any other entity defined within the system. The create operation ensures that all necessary fields are provided and validates the data before inserting the new record into the database.

Syntax

The JSON structure for a create operation in JQL typically includes the following components:

• __meta__: Metadata about the query, including authentication details, the intent (create), the target namespace, and the schema.
• Data Fields: The fields relevant to the resource being created, each specified with the appropriate type and value.

General Create Operation Structure:

{
    "__meta__": {
        "authenticationClass": "<authentication_method>",
        "intent": "create",
        "namespace": "<module_name>",
        "schema": "<schema_type>",
        "return": { "<field_to_return>": null } // Optional: Specify fields to be returned after creation
    },
    "<field_name_1>": "<field_value_1>",
    "<field_name_2>": "<field_value_2>",
    // Additional fields as needed
}

Example: Sample Query

Let's assume we are creating a new vehicle in the fleet.Vehicle namespace. The query would look like this:

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "create",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "return": { "id": null } // This will return the ID of the newly created vehicle
    },
    "gearbox": "automatic",
    "model_colour": "Fleet_ModelColourType",
    "purchase_type": "lease",
    "vin": "1HGCM82633A004352",
    "vrm": "AB12CDE",
    "year": "2024"
}

In this example:

• authenticationClass: Indicates that JWT token authentication is used.
• intent: Specifies the operation as create.
• namespace: Targets the fleet.Vehicle module.
• schema: Indicates that the operation is on the model schema.
• return: Requests that the ID of the newly created vehicle be returned.
• Data Fields: Includes details about the vehicle, such as gearbox type, model colour, purchase type, VIN, VRM, and year.

Example: Sample Response

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

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

In this response:

• status: Indicates that the operation was successful (OK).
• data: Contains the ID of the newly created 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 (create).
• message: Provides a human-readable message indicating the success of the operation.

The create operation is a fundamental part of JQL, enabling users to add new resources to Antly’s system efficiently and securely.