Operations batches

The ERP-API provides "operations batches" that allow clients to upload a whole set of operations of the same type to be executed as a batch. This allows for a controlled execution of thousands of updates without needing an independent HTTP call for each operation.

The basic concept is that clients create a ZIP file containing all the single operations that they want to have executed as part of the batch, then request an "S3 upload URL" via GET /org/{org-id}/operations-batches/upload-url, then upload the ZIP file to that URL, and then trigger creation and execution of the batch via a call to POST /org/{org-id}/operations-batches/XXX (where XXX depends on the type of batch).

Batch payload ZIP file

The single operations included in an operations batch are to be provided as a ZIP file. Within the ZIP file, a single JSON file is expected for each single operation. The name of the file must be the ID of the operation followed by .json.

Operations are executed in the order of their IDs, sorted as ASCII ascending.

For example, an '"valid from"-price update' batch that aims to change the future prices for a single product on three different sales channel as well as the base price of the product would need to consist of four operations:

// Product base prices
{
    "@type": "ProductValidFromPriceUpdate",
    "operation_id": "no_channel",
    "product": {…},
    "price_list": […]

}

// Product prices for sales channel 1
{
    "@type": "ProductSalesChannelValidFromPriceUpdate",
    "operation_id": "c1",
    "product": {…},
    "sales_channel": {
        "id": "61bc6aa66e5ecde3f5caa2cd",
        "type": "POS_SALES_CHANNEL"
    },
    "price_list": […]
}

// Product prices for sales channel 2
{
    "@type": "ProductSalesChannelValidFromPriceUpdate",
    "operation_id": "c2",
    "product": {…},
    "sales_channel": {
        "id": "61bc6aab98ad9ead7d332972",
        "type": "POS_SALES_CHANNEL"
    },
    "price_list": […]
}

// Product prices for sales channel 3
{
    "@type": "ProductSalesChannelValidFromPriceUpdate",
    "operation_id": "c3",
    "product": {…},
    "sales_channel": {
        "id": "61bc6aaf317c902434238bbd",
        "type": "POS_SALES_CHANNEL"
    },
    "price_list": […]
}

Therefore, the ZIP file is expected to contain the four files:

• no_channel.json
• c1.json
• c2.json
• c3.json

The operations would then be executed in the order c1, c2, c3, no_channel.

The ZIP file must be a basic ZIP file that does not use any advanced features like encryption, volume spanning/segmentation, digital signatures or compression algorithms other than DEFLATE. At the minimum, the file must be fully compatible with the Java ZipInputStream implementation.

Types of operations batches

Each type of batch allows only a limited set of operation types as its payload. This is done so the enfore platform can optimize execution of the operations by, for example, using different scheduling and/or caching options for each type of batch. Additionally, having only operations of related type on one batch helps users when viewing the list of active/complete batches.

"Valid from"-price updates

A batch of type "Valid from"-price updates supports two types of operations:

• ProductValidFromPriceUpdate - Update (or remove) the list of "valid from"-base prices for a product
• ProductSalesChannelValidFromPriceUpdate - Update (or remove) the list of channel-specific "valid from"-prices for a product

ProductValidFromPriceUpdate:

    ProductValidFromPriceUpdate:
      type: object
      properties:
        "@type":
          type: string
          enum: ["ProductValidFromPriceUpdate"]
        operation_id:
          type: string
          minLength: 1
          maxLength: 256
        product:
          $ref: 'product_shared.yaml#/components/schemas/ProductReference'
        price_list:
          $ref: 'product_valid_from_prices.yaml#/components/schemas/ValidFromPricesList'
      required:
        - "@type"
        - operation_id
        - product

ProductSalesChannelValidFromPriceUpdate:

    ProductSalesChannelValidFromPriceUpdate:
      type: object
      properties:
        "@type":
          type: string
          enum: ["ProductSalesChannelValidFromPriceUpdate"]
        operation_id:
          type: string
          minLength: 1
          maxLength: 256
        product:
          $ref: 'product_shared.yaml#/components/schemas/ProductReference'
        sales_channel:
          $ref: 'product_shared.yaml#/components/schemas/SalesChannelReference'
        price_list:
          $ref: 'product_valid_from_prices.yaml#/components/schemas/ValidFromPricesList'
      required:
        - "@type"
        - operation_id
        - product
        - sales_channel