- Usage Example
- Leading Practices
- Managing Items and Permissions
- Managing Security Identities in a Security Identity Provider
- Updating the Status of a Push Source
- Resetting a Push Source
- Creating a File Container
- Understanding the orderingId Parameter
- Understanding the API Processing Delay
- Troubleshooting API Error Codes
- API Reference
Understanding the 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 (e.g.,
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 (see Potential Issues).
orderingId parameter has a different meaning when it’s required, as in the Delete items older than and Delete identities older than operations. In these two cases, the
orderingId value rather indicates that the service should try to delete/disable any previously pushed item/security identity whose
orderingId parameter was set to a strictly lower value than the specified value.
Unless you’re setting your own
orderingId values when pushing content/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. Otherwise, you risk irremediably breaking the target source/security identity provider.
For instance, if you use an
orderingId corresponding to a moment ten years in the future to delete old items in a Push source, the indexing pipeline will keep rejecting new items pushed to that source for the next ten years. If you make that mistake, there’s nothing left to do but to recreate the source (see Recreating a Push Source from Its Raw Configuration).
A Push API operation whose optional
orderingIdparameter value is set to
1506700606240is older than an operation whose optional orderingId parameter value is set to
1506700606241as a the value of the required
orderingIdparameter value when performing a Delete items older than operation indicates that the service should try to delete all previously pushed items whose optional
orderingIdparameter were set to values which are lower (i.e., older) than
Critical consistency issues may arise if you carelessly assign custom optional
orderingId parameter 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
You perform a Push API operation to add a new item in a Push source. You decide to use
42 as your own custom optional
orderingId parameter 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 an optional
orderingId parameter value.
40 is lower (i.e., 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).
The Crawling Modules and the Coveo for Sitecore integration both use the Push API, and they both set their own opaque optional
orderingId values (i.e., they don’t use milliseconds since the Unix epoch). Trying to evaluate those values is typically neither trivial, nor recommended. Performing manual Push API operations on Push sources managed by Crawling Modules or Coveo for Sitecore is thus very strongly discouraged.
If you really need to perform manual Push API operations on a Push source managed by the Coveo for Sitecore integration, contact Coveo Support.