Processing States

When you send an ImportRequest to an ImportSink, the ImportSink returns a list of ImportOperations. Each ImportOperation has a state, indicating its current status in the import process.

ImportOperations can have any state listed in the ProcessingState enumeration. Those states change as follows.

The Import state flow

Reference resolution

To discuss processing states, it is necessary to agree on what is meant by reference resolution. In this page, references are said to be resolved if the relevant ImportOperation is consistent in terms of data from the point of view of the Import API. The Import API does not duplicate the validation logic of the commercetools platform. In particular, this means that the term, a successful reference resolution, does not imply the data consistency in the commercetools Project (cf. the diagram). For example, the uniqueness of product variant sku's cannot be checked by the Import API but only by the platform.

Successful States

In general, a successful ImportOperation goes through the following states:

  • Unresolved: The ImportOperation contains valid data for import. References are not yet resolved.
  • Imported: The resource is either created or updated on the commercetools platform. The ImportOperation is completed.

Unsuccessful States

ImportOperation requires the user's attention in the following states:

  • ValidationFailed: An ImportOperation can be marked in this state in two cases:
    • The format (JSON structure and fields) of the data is not valid as per the API specifications.
    • All the references are resolved. However, the data was not accepted by the commercetools platform because of further platform constraints. Please check errors.
  • Rejected: An ImportOperation has resolved all its references but the system has not been able to import the data into the platform (see Reference resolution) and the limit of retry has been reached. Hence there are most likely problems with the data that need to be addressed before they can be sent again in a follow up ImportRequest. Please check the error messages to see details about the problems with the data rejected by the platform.

The Delete state flow

When you send a delete request to an ImportSink, the ImportSink returns the ImportOperation. It has different states as follows:

  • Delete: This is the initial state of a delete request. It means that the resource is being deleted.
  • Deleted: This means that the ImportOperation has reached to its final state. The resource has been deleted from the project successfully.
  • Rejected: The ImportOperation has resolved all its references but system reached its maximum limit of retry to delete this resource from the platform. You need to send a delete request again if you still want to delete it.

Retrials and Time to live

  • Once all the references are resolved, the system tries to import the resource to the commercetools platform up to five times of retry attempts.
  • Once the delete request is received, the service tries to delete the resource from the commercetools platform up to five times of retry attempts.
  • Once the ImportOperation is in its final state, that is ValidationFailed, Rejected, Imported, or Deleted, the service cleans up the ImportOperation after 48 hours. Hence, any attempt afterwards to retrieve the ImportOperation by ID would result in HTTP 404 errors. You can call Query operations to fetch all the existing ImportOperations.

Retrieving progress by processing states

You can check the overall progress of an import process by fetching an ImportSummary. This will aggregate all the ImportOperation's various states into a single report for easy monitoring. More information about how to fetch an ImportSummary is available in the API Specification.

The list of Processing States

This enumeration describes the processing state of an import operation.

The validation of the import resource failed.
This is an initial state of the import resource, it might contain unresolved references and needs to be resolved further.
The import resource is resolved and doesn't contain any unresolved references.
Wait for a master variant to arrive. The product import has required attributes and thus requires a master variant that provides those.
The import resource was imported successfully.
The import resource is being deleted.
The import resource was deleted successfully.
The import resource couldn't be imported or deleted after several retries.
The import resource was skipped because the skip predicate was evaluated to true.