Push API Tutorial 1: Manage Public Content

This is for:

Developer System Administrator

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

Step 0: Prerequisites

For this tutorial, you need:

Tip

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 organization you created for that tutorial, if it’s still available.

Step 1: Create a Public Push Source

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

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

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

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

You’ll learn how to deal with secured Push sources, security identities, and simplified item permission models in the next tutorial (see Push API Tutorial 2: Manage 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 organization. However, you’re 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 (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you should now see that the status of your Push source went from Ready to receive content to Retrieving content.

Note

Typically, you shouldn’t bother to update the status of a Push source when you’re only performing tests, which is why this tutorial step is optional.

You won’t 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 Public Push Source):

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

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

This URI doesn’t actually reference an existing item, but this doesn’t matter as you’re merely pushing fictitious content.

It’s important to understand that when you use the Push API to manage items in a source, the service doesn’t 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:

  • A successful Push API call response does not imply that the required operations were fully and successfully processed by the Coveo indexing pipeline (for example, an item could still be rejected).

  • Using the Push API necessarily involves some processing delays (see About the Push API Processing Delay).

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

Step 4: Validate the Indexing Status of the Item

To validate whether the item you added in step 3 has been processed by the Coveo indexing pipeline, 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.

To do so, create a second API key that has the Execute queries privilege. Use the Search API to query your source as follows (see Perform a simple query):

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

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 (platform-ca | platform-eu | platform-au) and select your Push source in the Source facet in the Coveo 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’re using the Content Browser), move on to the next step of this tutorial.

Note

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

You’ll learn how to validate the indexing status of items in a secured Push source in the next tutorial (see Push API Tutorial 2: Manage Secured Content).

Step 5: Remove the Item from Your Source

To start the Push API Tutorial 2: Manage 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).

Note

You don’t 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 Administration Console, on the Sources page, you should now see that the source status is Ready to receive content:

Source Status is "Ready to receive content"

What’s Next?

You’re now ready to proceed to the next Push API tutorial (see Push API Tutorial 2: Manage Secured Content).