Push API Tutorial 1 - Managing Shared Content

In this introductory Push API tutorial, you will create a shared Push source in which you will add, and then delete a single basic, dummy item. You will also learn how to update the status of a Push source to generate coherent activity logs.

Step 0 - Prerequisites

For this tutorial, you need:

If you have completed the Introductory Tutorial - Creating an Organization and a Source, and Getting Your First Query Results before, you can (and should) re-use the Coveo Cloud organization you created for that tutorial, if it is still available.

Step 1 - Create a Shared Push Source

The Push API allows you to manage items in pushEnabled sources only.

For this tutorial, you will create a shared Push source (see Content Security). Any user who can perform queries in a Coveo Cloud organization can see the items of a shared source in their query results.

Use the Source API to create a source with the following configuration in your Coveo Cloud organization (see Creating a Push Source):

{
  "sourceType": "PUSH",
  "name": "My Push API Tutorial Source",
  "sourceVisibility": "SHARED",
  "pushEnabled": true
}

You will learn how to deal with secured Push sources, security identities, and simplified item permission models in the next tutorial (see Push API Tutorial 2 - Managing Secured Content).

Step 2 - (Optional) Generate Your First Source Activity Logs

The Coveo crawlers automatically take care of generating activity logs for non-Push sources in your Coveo Cloud organization. However, you are fully responsible for managing the activity logs of your own Push sources. This means that when you plan to perform a set of Push API operations to update the content of a Push source, you should first update the status of that source accordingly.

Set the status of the source you created in step 1 to REBUILD (see Updating the Status of a Push Source).

If you navigate to the Sources panel in the Coveo Cloud administration console, you should now see that the status of your Push source went from Ready to receive items to Performing rebuild:

Typically, you should not bother to update the status of a Push source when you are simply performing tests, which is why this tutorial step is optional.

You will not be asked to generate source activity logs in subsequent Push API tutorials.

Step 3 - Add an Item in Your Source

Use the Push API to add the following dummy item in the Push source you created in step 1 (see Adding or Updating a Single Basic Item in a Shared Push Source):

{
  "data": "This is a dummy item."
}

When pushing the above item, set the documentId query parameter to file://folder/dummyItem.txt.

This URI does not actually reference an existing item, but this does not matter as you are merely pushing fictitious content.

It is important to understand that when you use the Push API to manage items in a source, the service does not directly add, update, and/or delete content in your index. In fact, the Push API simply forwards the required operations to the document processing manager (DPM). This means that:

Consequently, you may have to wait a few minutes before the item you just added becomes available in your source.

Step 4 - (Optional) Validate the Indexing Status of the Item

A simple way to validate whether the item you added in step 3 has been processed by the Coveo Cloud indexing pipeline is to perform queries to get the content of the source you created in step 1 at regular intervals until the item appears in your query results.

Use the Search API to query your source as follows (see Performing a Simple Query):

{
  "aq": "@source==\"My Push API Tutorial Source\"",
  "maximumAge": 0
}

Setting the maximumAge property to 0 when performing a query prevents the Search API from retrieving the results from cache, which can be useful when debugging.

Alternatively, you can use the Content Browser and select your Push source in the Source facet in the Coveo Cloud administration console to manually perform equivalent queries (see Inspect Items With the Content Browser).

When you see the item in your query response (or in the result list, if you are using the Content Browser), move on to the next step of this tutorial.

The indexing status validation method presented in this tutorial typically works well with shared and private, but not with secured Push sources (see Content Security).

You will learn how to validate the indexing status of items in a secured Push source in the next tutorial (see Push API Tutorial 2 - Managing Secured Content).

Step 5 - Remove the Item from Your Source

To start the Push API Tutorial 2 - Managing Secured Content tutorial with a clean source, use the Push API to delete the item you added in step 3 from the Push source you created in step 1 (see Deleting an Item and Optionally, its Children in a Push Source).

You do not need to include the deleteChildren query parameter in your call (its default value is false).

Again, you can perform queries to get the content of your source as explained in step 4 to validate whether the item is still present in your source before proceeding to the next step of this tutorial.

Step 6 - (Optional) Generate More Source Activity Logs

Now that your source content update is complete, set the status of the source you created in step 1 back to IDLE (see Updating the Status of a Push Source).

In the Coveo Cloud administration console, in the Sources panel, you should now see that the source status went from Performing rebuild to Ready to receive items:

What’s Next?

You are now ready to proceed to the next Push API tutorial (see Push API Tutorial 2 - Managing Secured Content).

Recommended Articles