About the orderingId Parameter

This is for:

Developer System Administrator
In this article

All Push API operations, except for the Get large file container and Set source status operations, have an orderingId parameter.

When this parameter is optional, its value indicates the age of the operation: a lower orderingId value corresponds to an older operation. By default, the Push API automatically sets this parameter to the current number of milliseconds since the Unix epoch (for example, 1506700606240). You can also provide your own optional orderingId parameter values when making Push API calls. When doing so, you must ensure that you somehow increase the orderingId value each time you perform a new Push API operation. In essence, any given Push API operation must have a higher optional orderingId parameter value than that of its immediate predecessor, otherwise consistency issues will arise.

When the orderingId is required, as in the Delete items older than and Delete identities older than operations, it has a different meaning. In these two cases, the orderingId value indicates that the service should try to delete or disable any previously pushed item or security identity whose orderingId value is strictly lower than the one specified in the operation.

Important

Unless you’re setting your own orderingId values when pushing item or security identity updates, you should typically set the orderingId of a delete-older-than operation to the current number of milliseconds elapsed since the Unix epoch, without adding any offset. Failing to do so may risk breaking the target source or security identity provider.

For example, if you use an orderingId set to a moment ten years in the future to delete old items in a Push source, the Coveo indexing pipeline will reject any new items pushed to that source for the next ten years. If this mistake occurs, the only solution is to recreate the source.
Example

A Push API operation whose optional orderingId value is 1506700606240 is older than an operation whose optional orderingId value is 1506700606241.

When performing a delete-items-older-than operation, specifying 1506700606241 as the value for the required orderingId indicates that the service should try to delete all previously pushed items with optional orderingId values that are lower (that is, older) than 1506700606241.

Potential issues

Critical consistency issues may arise if you carelessly assign custom optional orderingId values when making your own Push API calls. Therefore, you should make sure you know exactly what you’re doing if you choose not to let the Push API automatically set the value of the optional orderingId.

Example

You perform a Push API operation to add a new item in a Push source. You decide to use 42 as the custom optional orderingId value for this operation.

Later, you decide to perform a delete Push API operation to remove that same item from the source. This time, you decide to use 40 as the optional orderingId value.

Since 40 is lower (that is, older) than 42, the Push API considers the delete operation to predate the add operation, which makes no sense. Consequently, the delete operation fails at the indexing stage (with the OUT_OF_SEQUENCE_OPERATION error code in the source logs).

Important

The Crawling Module and the Coveo for Sitecore integration both use the Push API, and they both set their own opaque optional orderingId values (that is, they don’t use milliseconds since the Unix epoch). Trying to evaluate those values is neither trivial, nor recommended. Therefore, performing manual Push API operations on Push sources managed by Crawling Modules or Coveo for Sitecore is strongly discouraged.