dotCMS logodotCMS logo

REST API Index Policy

When saving content via the java ContentletAPI or a REST endpoint, you can specify an indexPolicy, which allows you to control when the changes made by the API call will take place.

Specifying the index policy allows you to ensure that content changes made by one API call or method have completed, and the content is available, before subsequent API calls or methods which depend on the first changes.

Index Policy Values#

There are 3 possible values for the index policy:

ValueDescription
DEFERContent will be indexed asynchronously, outside of the content check process. This means that valid content will finish the check in process and be returned via the APIs before the content is visible in the index.
This is the default index policy.
WAIT_FORThe API call or method will not return from the content check process until the content has been indexed by Elasticsearch.
FORCEForces Elasticsearch to index the content immediately.
Important: Using this value may cause system performance issues, and should only be used for testing purposes.

These values correspond to Elasticsearch’s “refresh” index policies. For more information, please see the Elasticsearch documentation.

Setting the Policy#

If you don't explicitly set an Index Policy, the Default Index Policy will be used.

You may override the default policy by setting the Index Policy in the request, either via a URL parameter or as part of the content body in the json. If the Index Policty is defined in both a URL parameter and the request body, the URL parameter takes precedence.

URL Parameter#

The following example demonstrates how to set the index policy using a URL parameter:

/api/v1/workflow/actions/b9d89c803d/fire?identifier=b105eddc-e4b0-4a7f-85ad-b09d29a1c31b&indexPolicy=WAIT_FOR

Request Body#

The following example demonstrates how to set the index policy in the request body:

curl -v -u admin@dotcms.com:admin -X PUT \ http://localhost:8082/api/v1/workflow/actions/b9d89c803d/fire?identifier=b105eddc-e4b0-4a7f-85ad-b09d29a1c31b -F "json={ 'contentlet': { "contentType":"fileAsset", "languageId":1, "hostFolder":"demo.dotcms.com", "fileName":"liz2.jpg", "title":"liz!" }, 'indexPolicy':'WAIT_FOR' }; type=application/json" -F "file=@//Users/user123/Downloads/liz.jpg; type=application/jpg"

Default Policy#

If no Index Policy is set in the request, a default value will be used.

  • The normal default policy is DEFER.
  • You can change the default policy by adding the INDEX_POLICY_SINGLE_CONTENT configuration property: INDEX_POLICY_SINGLE_CONTENT=WAIT_FOR