Manage the Push source

This is for:

Developer System Administrator

After creating a Push source, you shouldn’t have to interact with it much.

However, you should update the status of a Push source before and after a complete set of operations corresponding to a content update. You might also need to reset a Push source in rare cases.

This article explains how to update the status of a Push source and how to reset a Push source.

Update the status of a Push source

The status of a source should change as soon as a process begins retrieving content to be added, updated, or deleted in that source, and it should change again as soon as this process ends. The status of a source is displayed on the Sources (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console. Source status changes make up its activity logs.

Standard connectors automatically update the status of their respective sources, but it’s your responsibility to update the status of your Push sources. Otherwise, these sources will always appear as Ready to receive content in the Coveo Administration Console.

To update the status of a Push source

  1. Prior to any content update, use the POST status request to set the source to one of the active statuses.

    Status name Corresponding status name in the Coveo Administration Console When to set the Push source to this status Typical resource cost

    REBUILD

    Rebuild

    You plan to re-index the entire content of the source, updating all previously indexed items in the process.

    High

    REFRESH

    Rescan

    You plan to scan the current content of the source, compare it with the content you intend to push, and only update new, modified, or deleted items in the source.

    Moderate

    INCREMENTAL

    Refresh

    You plan to use a feature of the indexed enterprise system to identify and push only the delta between the system in its present state and the current content of the source, without scanning the content of the source first.

    Low

  2. Perform the desired content update operations.

  3. Set the status of the source back to IDLE.

Request template

Request definition

POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/sources/<MySourceId>/status?statusType=<MyStatusType> HTTP/1.1
​
Authorization: Bearer <MyAccessToken>

In the request path:

  • Replace <MyOrganizationId> with the ID of the target Coveo organization (see Retrieve the organization ID).

  • Replace <MySourceId> with the ID of the target Push source.

In the request query string:

  • Replace <MyStatusType> with the desired statusType value (that is, IDLE, INCREMENTAL, REBUILD, or REFRESH).

In the Authorization HTTP header:

  • Replace <MyAccessToken> with an access token that grants the Organization - View/Edit and Sources - View privileges in the target Coveo organization (see Create an API key).

A successful response (201 Created) has no content, but it signifies that the status of the target Push source has been updated.

Sample request

The following example shows how to set the status of a Push source to REFRESH.

POST https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy/status?statusType=REFRESH HTTP/1.1
​
Authorization: Bearer **********-****-****-****-************

201 Created response body

{}

Reset a Push source

Resetting a Push Source can be useful in instances where the data has become corrupted or when you want to clear out content/items.

There are two methods that you can use to reset a Push Source.

Reset a Push source using the Push API

The simplest (and typically recommended) method of resetting a Push source is to use the DELETE /sources/{sourceId}/documents/olderthan Push API HTTP request.

Important

Unless you’ve been setting your own orderingId values when pushing content updates to the Push source you want to reset, you should set the orderingId of your delete older than operation to the current number of milliseconds elapsed since the Unix epoch, without adding any offset. Otherwise, you risk irremediably breaking that Push source.

For example, if you use an orderingId set ten years in the future when making your delete older than operation, the indexing pipeline will keep rejecting new items pushed to the 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).

If you need to reset a Push source managed by the Coveo for Sitecore integration or by the Coveo Crawling Module, you must recreate the source instead (see Recreating a Push source from its raw configuration).

Recreate a Push source from its raw configuration

Sometimes, using a delete older than operation to reset a Push source is simply not an option. For example, when dealing with a Push source managed by the Coveo for Sitecore integration or by the Coveo Crawling Module, the orderingId has an opaque value. For this reason, performing manual Push API operations on these sources isn’t recommended, as it can cause critical consistency issues (see About the orderingId parameter). In such cases, you must replace the Push source you want to reset by a new source replicating the original one.

To recreate a Push source from its raw configuration

  1. Make a backup of the entire original source configuration by performing a GET raw Source API request.

    Important

    Ensure that the request was successful (status code 200) and that you have safely stored the entire response body before proceeding on to the next step. Otherwise, you could permanently lose your original source configuration.

  2. Delete the original source by performing a DELETE sourceId Source API request or using the Coveo Administration Console (see Delete an existing source).

  3. Create a new source with the exact same configuration as the original source using the POST raw Source API request. Use the raw JSON configuration retrieved in step 1 as your request body.