Supply sync transparency

Inventory Visibility processes a large amount of supply synchronization requests daily, most of these requests originate from a ship node or an item, or both. Inventory synchronization process is heavy in computation and requires a longer processing time. Therefore, as a fulfillment manager you can have visibility into the status of request and see that the network inventory is accurate.

Inventory Visibility offers you the capability to track the transaction ID and the status of a supply sync request. When the sync request is made, the API returns the corresponding supply sync transaction ID, which can be used to locate the status and the details of the request.

The various levels of functionality that is offered by the supply sync transparency feature is as follows.

  • Supply sync transactional status (v1/supplies/transaction/{supplySyncTransactionId}/status).
  • Supply sync transactional records (v1/supplies/transaction/{supplySyncTransactionId}/records).
  • Supply history (v1/supplies/history).

To provide a comprehensive view of multiple sync requests, as a fulfillment manager you can use the supply sync batch processing. This feature enables one or more supply sync requests to be referenced by a single batch ID and provides an insight on the number of records that is processed successfully. It also offers you the ability to retrieve and reprocess failed records.

  • Supply sync batching (/v1/supplies).
  • Supply sync transaction search (v1/supplies/transaction/status).

An example of supply sync workflow

Consider a scenario where the fulfillment manager pushes multiple sync request for ITEM001 to ITEM100 at NODE01. Assume that 10 supply sync request is made with 10 unique items at for a single node such as ITEM001-ITEM010, ITEM011-ITEM020, and so on. For each request, the fulfillment manager applies the same batchId. Aside from the standard supply sync request, the supply sync API (/v1/supplies) now returns a supplySyncTransactionId in the response payload, which can be used to trace the status of the update.

{
  "supplySyncTransactionId": "a014bba7-8d08-4d87-885a-fb24323b1cf8",
  "batchId": "a014bba7-8d08-4d87-885a-fb24323b1cf8"
}

The fulfillment manager can then use the supply sync transaction status API (v1/supplies/transaction/{supplySyncTransactionId}/status) to verify the overall status of the single request [ITEM001-ITEM010] to view the estimated completion time and the number of records in each status.

The supply sync transaction records (v1/supplies/transaction/{supplySyncTransactionId}/records) can also be used to see the original request input of the supply sync. The status of each record is also provided along with the details to see whether the record is published through events. If the event is disabled, then the published attribute is always false.

The fulfillment manager can check the individual sync request by using the transaction ID. However, if the transaction IDs are forgotten, the supply sync transaction search can be used. The supply sync transaction search API (v1/supplies/transaction/status) can locate the transaction for a time period or by the batchId. The response consists of multiple matching transactional status records along with the supplySyncTransactionId.

If one of the supply sync records fails, the fulfillment manager can use the supply history API (v1/supplies/history) to verify the sourceTs and the updatedTs values to determine whether the individual record needs to be resynced or skipped.

Steps to activate supply transparency and associating request to a batch ID

You can activate the supply sync transparency tracking by setting recordTransaction query parameter as part of supply sync. Upon accepting the supply sync request, the system automatically generates the supplySyncTransactionId, which can be used to identify the status and the detail of the request. To associate one or more supply sync requests to a single batch, the three query parameters that can be used are as follows.

  • batchId - Associates current request to an existing batchId generated by the system.
  • newBatch - Is set to true to start a new batch. The system generates a new unique batchId for the transaction.
  • endOfBatch - Identifies that this request is the end of the batch, which allows the status to move to be completed when all records are processed.
Table 1. Supply sync API query parameters
Name Description Example
newBatch Set to true to start a new batch. The system automatically generates a batchId. true (default false).
batchId Associate this transaction with an existing batch that has the matching batchId. System-generated UUID. [UUID.randomUUID()]
endOfBatch Declares the end of a batch. true (default false).
recordTransaction Activates the supply sync transparency tracking. It can be used as a single transaction or as a batch. For the batch use case, recordTransaction=true must be passed along with the newBatch query parameter. All children associated to the same batch are automatically considered for transparency tracking. true (default false)
An example.
> /{tenantId}/v1/supplies?recordTransaction=true&newBatch=true
> /{tenantId}/v1/supplies?recordTransaction=true&batchId=a014bba7-8d08-4d87-885a-fb24323b1cf8
> /{tenantId}/v1/supplies?recordTransaction=true&endOfBatch=true
A sample supply sync response payload.
{
  "supplySyncTransactionId": "a014bba7-8d08-4d87-885a-fb24323b1cf8",
  "batchId": "a014bba7-8d08-4d87-885a-fb24323b1cf8"
}
Note: The first transaction that is accepted in a batch is considered as the parent transaction.
By adding multiple requests to a batch, you gain a comprehensive view across all sync processes. This is beneficial because you can see the overall status of multiple sync requests that results from a single stocking-taking job at a warehouse.

Supply sync transactional status

The transactional status API provides a high-level view of the supply sync transaction status. To view the status, you must provide a valid supplySyncTransactionId. This API provides the submitted timestamp, estimated completion duration, and the completed timestamp. The estimated completion duration provides the time when the overall sync process is expected to be completed and when you can review it in case for any errors. The estimatedCompletionTime status is returned when the job is not in COMPLETED or EXCEPTION status.

The transactions can have any of the following statuses.
  • QUEUED
  • IN_PROGRESS
  • EXCEPTION - If one or more exceptions are encountered during execution.
  • COMPLETED
  • DELAYED - When the job is completed after the estimated completion time.
At any point during sync processing, you can use this API to verify the record counts that fall into each of the categories that are listed.
  • submitted - The number of records that are accepted by the system or waiting in queue.
  • changed: The number of records that are updated.
  • unchanged: The number of records that are skipped because the inventory value is identical or older.
  • failed: The number of records failed to be processed by the system, the causes of failure can be invalid input or a system error.
  • published - The number of records that are successfully published through Supply.Change events. This number remains 0 if event publish is not enabled for your tenant.
The parent attribute is displayed in the output if it is the first accepted transaction.
Note: The data-refresh rate is 15 minutes.

Supply sync transactional record

This API allows searching the original supply sync request input as part of the transaction and the result can be filtered by the following record state [SUBMITTED, CHANGED, UNCHANGED, FAILED], and published by state [true].

Each supply sync transaction record represents the request input that is accepted by the system that is allowed with its processing state.

With this capability, you can locate all records in FAILED state by using the original request input that is found in the record. You can then resubmit a new supply sync job to reprocess the supply record after rectifying the erroneous records.
Note: The data-refresh rate is 15 minutes.

Supply history

While you are able to retrieve the original record by using the supply sync transaction record API, there are cases where supply adjustment can be made during a supply sync. The Supply update history API returns the true value of the supply record that is last updated on the system.

The API returns the details of the supply record along with the sourceTS provided by the user input and the updatedTs, which is the timestamp when the supply record was last modified. Both attributes enable you to determine whether the adjustment or the sync request is made to the system first.

Supply sync transaction search

The supply sync transaction status and record API require you to provide a supplySyncTransactionId. In case you are unable to locate the value of the ID, you can use the transaction search API to locate the matching supplySyncTransactionId or batchId.

The search supports the query by these options.
  • submitted timestamp range - The time when the request was submitted by the user.
  • completed timestamp range - The time when the transaction was completed.
  • status: [QUEUED, IN_PROGRESS, COMPLETED, EXCEPTION, DELAYED].
  • batchId
  • parent - Locate all transaction parents or the first request of a batch.