---
title: SAP source reference
slug: '2515'
canonical_url: https://docs.coveo.com/en/2515/
collection: index-content
source_format: adoc
---
# SAP source reference
When [creating an SAP source](https://docs.coveo.com/en/9618/) in the [Coveo Administration Console](https://docs.coveo.com/en/183/), you must provide a JSON configuration detailing which [services and endpoints](https://docs.coveo.com/en/3131#repository-structure) to crawl to retrieve the desired content, and how to retrieve items of each type.
This configuration has a single property, [`Services`](#services-array-required), whose value must be an array of objects.
**Example**
```json
{
"services": [
{
"url": "https://api.acmestore.com/odata2webservices",
"headers": {
"Accept": "application/json",
"Application-Interface-Key": "xxxxxxxx"
},
"paging": {
"pageSize": 10,
"offsetStart": 0,
"offsetType": "item",
"nextPageKey": "__next",
"parameters": {
"limit": "$top",
"offset": "$skip"
}
},
"endpoints": [
{
"path": "/Product/Products",
"method": "GET",
"queryParameters": {
"$filter": "catalogVersion/integrationKey eq 'Online%7CpowertoolsProductCatalog' and approvalStatus/code eq 'approved'",
"$expand": "supercategories,thumbnails,picture,thumbnail,unit,catalogVersion/catalog,europe1Prices,europe1Prices/currency,bundleTemplates,localizedAttributes,supercategories/localizedAttributes,approvalStatus"
},
"itemPath": "d.results",
"itemType": "product",
"uri": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]",
"clickableUri": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]",
"metadata": {
"objecttype": "Product",
"ec_brand": "%[brand]",
"ec_name": "%[name]",
"name": "%[name]",
"ec_item_group_id": "%[code]",
"ec_shortdesc": "%[summary]",
"ec_description": "%[description]",
"ec_price": "%[europe1Prices.results[0].price]",
"ec_thumbnails": "https://accstorefront.commerce.ondemand.com%[thumbnail.URL]",
"ec_in_stock": "%[stock]",
"ec_images": "https://accstorefront.commerce.ondemand.com%[picture.URL]",
"ec_category": "%[supercategories.results[:].name]",
"ec_pricerange": "%[priceRange]",
"ec_configurable": "%[configurable]",
"ec_code": "%[code]",
"ec_url": "https://accstorefront.commerce.ondemand.com/coveob2bstorefront/powertools/en/USD/%[url]"
}
}
]
}
]
}
```
This reference article defines parameters to include in your JSON configuration.
When working on your SAP source, you may also want to refer to the following articles:
* [Add an SAP source](https://docs.coveo.com/en/9618/)
* [Concepts](https://docs.coveo.com/en/o2qa5325/)
* [Permission configuration reference](https://docs.coveo.com/en/0333/)
> **Tip**
>
> Use online tools such as [JSONPath Online Evaluator](https://jsonpath.com/) to test your [JSON paths](https://docs.coveo.com/en/o2qa5325/), and [freeformatter.com](https://www.freeformatter.com/) to validate and escape your JSON configuration.
## Table of contents
To help you jump to the right section, here's a hierarchical and alphabetical list of all supported arrays, objects, and parameters.
**Show table of contents**
Details
[%header,cols="columns"]
|===
|Hierarchical list |Alphabetical list
a|[`Services`](#services-array-required) (required)
* [`Endpoints`](#endpoints-array-required) (required)
** [`ClickableUri`](#clickableuri-string-required) (required)
** [`ItemType`](#itemtype-string-required) (required)
** [`Path`](#path-string-required) (required)
** [`Uri`](#uri-string-required) (required)
** [`Body`](#body-string)
** [`DateFormat`](#dateformat-string)
** [`ExtendedMetadata`](#extendedmetadata-object)
*** [`Expression`](#expression-object-required) (required)
**** [`Value`](#value-string-required) (required)
**** [`IsDynamicCondition`](#isdynamiccondition-boolean)
*** [`ExtendedMetadataActions`](#extendedmetadataactions-array)
**** [`ActionName`](#actionname-string-enum-required) (required)
**** [`OldValue`](#oldvalue-and-newvalue-string)
**** [`NewValue`](#oldvalue-and-newvalue-string)
**** [`DefaultValue`](#defaultvalue-string)
**** [`FallbackValuesTrigger`](#fallbackvaluestrigger-array)
**** [`StringSeparator`](#stringseparator-string)
** [`IndexingAction`](#indexingaction-object)
*** [`ActionOnItem`](#actiononitem-string-required) (required)
*** [`Condition`](#action-condition-string)
** [`ItemPath`](#itempath-string-required) (required)
** [`Metadata`](#metadata-object)
** [`Method`](#method-string-enum)
** [`ModifiedDate`](#modifieddate-string)
** [`PayloadJsonContent`](#payloadjsoncontent-string)
** [`PayloadParameters`](#payloadparameters-object)
** [`PermanentId`](#permanentid-string)
** [`ProcessingAction`](#processingaction-object)
** [`QueryParameters`](#queryparameters-object)
*** [`Filter`](#filter-string)
*** [`Expand`](#expand-string)
** [`RefreshEndpoints`](#refreshendpoints-array)
*** [`IsDeletionQuery`](#isdeletionquery-boolean)
*** [`IsDeletedItem`](#isdeleteditem-boolean)
*** [`DeleteChildren`](#deletechildren-boolean)
** [`SubItems`](#subitems-array)
** [`SubQueries`](#subqueries-array)
*** [`ExecutionCondition`](#executioncondition-string)
*** [`IsBinaryBody`](#isbinarybody-boolean)
*** [`IsThumbnail`](#isthumbnail-boolean)
** [`Title`](#title-string)
* [`Url`](#url-string-required) (required)
* [`Authentication`](#authentication-object)
** [`Username`](#username-string)
** [`Password`](#password-string)
** [`Domain`](#domain-string)
** [`ForceBasicAuthentication`](#forcebasicauthentication-boolean)
** [`OAuth`](#oauth-object)
*** [`Query`](#query-object-required) (required)
**** [`RefreshUrl`](#refreshurl-string-required) (required)
**** [`Headers`](#oauth-query-headers-object)
**** [`Method`](#oauth-query-method-string-enum)
**** [`Parameters`](#oauth-query-parameters-object)
*** [`Response`](#response-object)
**** [`AccessToken`](#accesstoken-string)
**** [`SupportsRefreshToken`](#supportsrefreshtoken-boolean)
**** [`RefreshToken`](#refreshtoken-string)
**** [`ExpiresIn`](#expiresin-string)
**** [`ExpiresInDefaultValue`](#expiresindefaultvalue-number)
**** [`TokenType`](#tokentype-string)
**** [`TokenTypeDefaultValue`](#tokentypedefaultvalue-string)
**** [`AuthorizationHeader`](#authorizationheader-string)
*** [`UsingSingleUseRefreshToken`](#usingsingleuserefreshtoken-boolean)
* [`Headers`](#headers-object)
* [`Paging`](#paging-object)
** [`OffsetType`](#offsettype-string-enum-required) (required)
** [`PageSize`](#pagesize-number-required) (required)
** [`DoNotInherit`](#donotinherit-boolean)
** [`NextPageKey`](#nextpagekey-string)
** [`OffsetStart`](#offsetstart-number)
** [`Parameters`](#paging-parameters-object)
*** [`Limit`](#limit-string-required) (required)
*** [`FetchNextPageUntilNoResult`](#fetchnextpageuntilnoresult-boolean)
*** [`Offset`](#offset-string)
** [`TotalCountHeaderKey`](#totalcountheaderkey-string)
** [`TotalCountKey`](#totalcountkey-string)
* [`Permissions`](#permissions-array)
** [`Name`](#permission-level-name-string)
** [`PermissionsSets`](#permissionssets-array)
*** [`Name`](#permission-set-name-string)
*** [`AllowedMembers` and `DeniedMembers`](#allowedmembers-and-deniedmembers-arrays)
**** [`Name`](#member-name-string-required) (required)
**** [`Type`](#member-type-string-enum-required) (required)
**** [`Condition`](#permission-condition-string)
**** [`PermissionType`](#permissiontype-string)
**** [`AdditionalInfo`](#additionalinfo-object)
*** [`IsAnonymousAllowed`](#isanonymousallowed-boolean)
*** [`PermissionsFromMetadata`](#permissionsfrommetadata-array)
*** [`PermissionSubQueries`](#permissionsubqueries-array)
**** [`IsAllowedMember`](#isallowedmember-boolean)
* [`RetryableHttpErrorCodes`](#retryablehttperrorcodes-string)
* [`SkippableErrorCodes`](#skippableerrorcodes-string)
|[`AccessToken`](#accesstoken-string)
[`ActionName`](#actionname-string-enum-required)
[`ActionOnItem`](#actiononitem-string-required)
[`AdditionalInfo`](#additionalinfo-object)
[`AllowedMembers`](#allowedmembers-and-deniedmembers-arrays)
[`Authentication`](#authentication-object)
[`AuthorizationHeader`](#authorizationheader-string)
[`Body`](#body-string)
[`ClickableUri`](#clickableuri-string-required)
[`Condition`](#action-condition-string) (action on item)
[`Condition`](#permission-condition-string) (permission)
[`DateFormat`](#dateformat-string)
[`DefaultValue`](#defaultvalue-string)
[`DeleteChildren`](#deletechildren-boolean)
[`DeniedMembers`](#allowedmembers-and-deniedmembers-arrays)
[`Domain`](#domain-string)
[`DoNotInherit`](#donotinherit-boolean)
[`Endpoints`](#endpoints-array-required)
[`ExecutionCondition`](#executioncondition-string)
[`Expand`](#expand-string)
[`ExpiresIn`](#expiresin-string)
[`ExpiresInDefaultValue`](#expiresindefaultvalue-number)
[`Expression`](#expression-object-required)
[`ExtendedMetadata`](#extendedmetadata-object)
[`ExtendedMetadataActions`](#extendedmetadataactions-array)
[`FallbackValuesTrigger`](#fallbackvaluestrigger-array)
[`FetchNextPageUntilNoResult`](#fetchnextpageuntilnoresult-boolean)
[`Filter`](#filter-string)
[`ForceBasicAuthentication`](#forcebasicauthentication-boolean)
[`Headers`](#oauth-query-headers-object) (OAuth query)
[`Headers`](#headers-object) (service level)
[`IndexingAction`](#indexingaction-object)
[`IsAllowedMember`](#isallowedmember-boolean)
[`IsAnonymousAllowed`](#isanonymousallowed-boolean)
[`IsBinaryBody`](#isbinarybody-boolean)
[`IsDeletedItem`](#isdeleteditem-boolean)
[`IsDeletionQuery`](#isdeletionquery-boolean)
[`IsDynamicCondition`](#isdynamiccondition-boolean)
[`IsThumbnail`](#isthumbnail-boolean)
[`ItemPath`](#itempath-string-required)
[`ItemType`](#itemtype-string-required)
[`Limit`](#limit-string-required)
[`Metadata`](#metadata-object)
[`Method`](#method-string-enum) (endpoint query)
[`Method`](#oauth-query-method-string-enum) (OAuth query)
[`ModifiedDate`](#modifieddate-string)
[`Name`](#member-name-string-required) (member)
[`Name`](#permission-level-name-string) (permission level)
[`Name`](#permission-set-name-string) (permission set)
[`NewValue`](#oldvalue-and-newvalue-string)
[`NextPageKey`](#nextpagekey-string)
[`OAuth`](#oauth-object)
[`Offset`](#offset-string)
[`OffsetStart`](#offsetstart-number)
[`OffsetType`](#offsettype-string-enum-required)
[`OldValue`](#oldvalue-and-newvalue-string)
[`PageSize`](#pagesize-number-required)
[`Paging`](#paging-object)
[`Parameters`](#oauth-query-parameters-object) (OAuth query)
[`Parameters`](#paging-parameters-object) (paging)
[`Password`](#password-string)
[`Path`](#path-string-required)
[`PayloadJsonContent`](#payloadjsoncontent-string)
[`PayloadParameters`](#payloadparameters-object)
[`PermanentId`](#permanentid-string)
[`Permissions`](#permissions-array)
[`PermissionsFromMetadata`](#permissionsfrommetadata-array)
[`PermissionsSets`](#permissionssets-array)
[`PermissionSubQueries`](#permissionsubqueries-array)
[`PermissionType`](#permissiontype-string)
[`ProcessingAction`](#processingaction-object)
[`Query`](#query-object-required)
[`QueryParameters`](#queryparameters-object)
[`RefreshEndpoints`](#refreshendpoints-array)
[`RefreshToken`](#refreshtoken-string)
[`RefreshUrl`](#refreshurl-string-required)
[`RetryableHttpErrorCodes`](#retryablehttperrorcodes-string)
[`Response`](#response-object)
[`Services`](#services-array-required)
[`SkippableErrorCodes`](#skippableerrorcodes-string)
[`StringSeparator`](#stringseparator-string)
[`SubItems`](#subitems-array)
[`SubQueries`](#subqueries-array)
[`SupportsRefreshToken`](#supportsrefreshtoken-boolean)
[`Title`](#title-string)
[`TokenType`](#tokentype-string)
[`TokenTypeDefaultValue`](#tokentypedefaultvalue-string)
[`TotalCountHeaderKey`](#totalcountheaderkey-string)
[`TotalCountKey`](#totalcountkey-string)
[`Type`](#member-type-string-enum-required) (member)
[`Uri`](#uri-string-required)
[`Url`](#url-string-required)
[`Username`](#username-string)
[`UsingSingleUseRefreshToken`](#usingsingleuserefreshtoken-boolean)
[`Value`](#value-string-required)
|===
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
* `"%[author_id]"` is true if the item has an `author_id`.
* `"NOT %[author_id]"` is true if the item doesn't have an `author_id`.
* `"%[author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `"%[author_id] > 123"` is true if the item `author_id` is greater than 123.
* `"(%[author_id] OR %[author_sys_id]) AND %[author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
You use the `FormatHierarchical` action because you're planning to add a [hierarchical facet](https://docs.coveo.com/en/2667/) to your Coveo-powered search interface.
This action reformats your metadata in the way that's required for the hierarchical facet to work properly.
Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
So, if your API returns `"category": "Men > Clothing > Shoes"`, Coveo indexes `Men;Men|Clothing;Men|Clothing|Shoes` in the `ec_categories` field.
Then, once you add a hierarchical facet based on the `ec_categories` field to your search interface, your search interface will allow users to filter results by selecting a category such as `Men`, and then a subcategory such as `Shoes`, and so on.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "FormatHierarchical",
"StringSeparator": " > " <4>
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
Details
The following rule trims leading and trailing whitespace characters from values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": " Surf boards "`, Coveo indexes `Surf boards` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Trim"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": "None"` or `"name_author": "(Empty)"`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
"FallbackValuesTrigger": [
"None", "(Empty)"
]
}
]
},
},
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
You use the `FormatHierarchical` action because you're planning to add a [hierarchical facet](https://docs.coveo.com/en/2667/) to your Coveo-powered search interface.
This action reformats your metadata in the way that's required for the hierarchical facet to work properly.
Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
So, if your API returns `"category": "Men > Clothing > Shoes"`, Coveo indexes `Men;Men|Clothing;Men|Clothing|Shoes` in the `ec_categories` field.
Then, once you add a hierarchical facet based on the `ec_categories` field to your search interface, your search interface will allow users to filter results by selecting a category such as `Men`, and then a subcategory such as `Shoes`, and so on.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "FormatHierarchical",
"StringSeparator": " > " <4>
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/o2qa5325#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
Details
With the following `IndexingAction` object, all items with an `id` greater than `5` are ignored.
Only items with an `id` of `5` or less are indexed.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "%[id] > 5"
}
```
Details
With the following `IndexingAction` object on an endpoint, all items that have a `name` metadata value other than `myvalue` are ignored.
The [`ProcessingAction`](#processingaction-object) object has the same condition.
As a result, a [child item](#subitems-array) of the ignored items is also ignored if its `name` metadata value is not `myvalue`.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'" <1>
},
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'"
}
```
<1> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/o2qa5325#raw).
Details
Let's say you want to index store data, with full-time employee data as store subitems.
However, in your API, the employee data isn't directly linked to the store data.
Instead, it's linked to the store data through the department data.
Here's an example of the data structure as it would be returned by your API:
```text
Store 1
Department A
Employee 1
type: full time
Employee 2
type: full time
Department B
Employee 3
type: full time
Employee 4
type: part time
Employee 5
type: full time
Store 2
Department C
Employee 6
type: part time
Employee 7
type: full time
Employee 8
type: full time
Department D
Employee 9
type: full time
Department E
Employee 10
type: full time
Employee 11
type: full time
Employee 12
type: maternity leave
```
To index employee items, you need to retrieve the parent department items first.
However, since you want don't want to index the department data, you'll use the `IndexingAction` object to have Coveo ignore it.
As a result, Coveo will index employee items as subitems of the store items, even if they don't have a parent-child relationship in the API response.
Your source configuration is the following:
```json
{
"Services": [
{
"Url": "https://api.com",
"Endpoints": [
{
"Path": "/search",
"Method": "GET",
"Headers": {
"x-api-key": "@ApiKey",
"Accept": "application/json",
"Host": "api.com"
},
"QueryParameters": {
"type": "grocery"
},
"ItemType": "Store",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"Body": "%[address]",
"Metadata": {
"id": "%[id]"
},
"SubItems": [
{
"ItemPath": "departments",
"ItemType": "Department",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"IndexingAction": { <1>
"ActionOnItem": "Ignore"
},
"Body": "description",
"Metadata": {
"id": "%[id]"
},
"SubItems": [
{
"ItemPath": "employees",
"ItemType": "Employee",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"Body": "description",
"Metadata": {
"id": "%[id]",
},
"IndexingAction": { <2>
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.type]=='full time'" <3>
}
}
]
}
]
}
]
}
]
}
```
<1> This `IndexingAction` object is used to ignore `Department` items.
Since there's no condition, all `Department` items will be ignored.
<2> This `IndexingAction` object is used to index only the `Employee` items that have `full time` as their `type` metadata value.
`Employees` items with a different `type` value will be ignored.
<3> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/o2qa5325#raw).
Details
* `"%[author_id]"` is true if the item has an `author_id`.
* `"NOT %[author_id]"` is true if the item doesn't have an `author_id`.
* `"%[author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `"%[author_id] > 123"` is true if the item `author_id` is greater than 123.
* `"(%[author_id] OR %[author_sys_id]) AND %[author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
```json
"PayloadParameters": {
"type": "post",
"expand": "true",
"id": 120
}
```
Details
```json
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "%[id]==1"
}
```
Details
With the following `IndexingAction` object on an endpoint, all items that have a `name` metadata value other than `myvalue` are ignored.
The [`ProcessingAction`](#processingaction-object) object has the same condition.
As a result, a [child item](#subitems-array) of the ignored items is also ignored if its `name` metadata value is not `myvalue`.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'" <1>
},
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'"
}
```
<1> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/o2qa5325#raw).
Details
```json
"QueryParameters": {
"type": "post",
"expand": "true",
"id": 120
}
```
Details
When refreshing your source, Coveo indexes only the published items that have been updated since the last refresh operation, as instructed by the following `RefreshEndpoints` array.
Since no other property is specified, Coveo will index these items exactly like during the initial indexing operation.
```json
"Endpoints": [
{
"Path": "/api/now/table/kb_knowledge",
"Method": "GET",
"ItemPath": "result",
"ItemType": "kbknowledge",
"Uri": "%[coveo_url]/kb_knowledge/%[sys_id]",
"PermanentId": "%[sys_id]",
"ModifiedDate": "%[sys_updated_on]",
"ClickableUri": "%[coveo_url]/nav_to.do?uri=kb_knowledge.do?sys_id=%[sys_id]%26sysparam_view-ess",
"Title": "%[short_description]",
"Body": "%[text]",
"QueryParameters": {
"sysparm_query": "workflow_state=published"
},
"Metadata": {
"short_description": "%[short_description]",
"number": "%[number]",
"workflow_state": "%[workflow_state]",
},
"RefreshEndpoints": [
{
"DateFormat": "\'yyyy-MM-dd\',\'hh:mm:ss\'", <1>
"QueryParameters": {
"sysparm_query": "workflow_state=published^sys_updated_on>javascript:gs.dateGenerate(@RefreshDate)"
}
}
]
}
]
```
<1> The [`DateFormat`](#dateformat-string) property specifies the format of the date value in the query parameters.
Details
* `"%[author_id]"` is true if the item has an `author_id`.
* `"NOT %[author_id]"` is true if the item doesn't have an `author_id`.
* `"%[author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `"%[author_id] > 123"` is true if the item `author_id` is greater than 123.
* `"(%[author_id] OR %[author_sys_id]) AND %[author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
If your API uses API keys for authentication, Coveo will typically need to provide such a key in an [HTTP header](#headers-object), as a [query parameter](#queryparameters-object), or as a [payload parameter](#payloadparameters-object).
You therefore don't need an `Authentication` object in your JSON configuration.
Details
If your API uses password-based authentication, you must enter the username and password in the [**Authentication** section](https://docs.coveo.com/en/9618#authentication-section) of the **Add an SAP source** panel.
Then, in your JSON configuration, you must use the `@Username` and `@Password` placeholders to refer to these credentials.
Your `Authentication` object therefore looks like this:
```json
"Authentication": {
"Username": "@Username",
"Password": "@Password",
"ForceBasicAuthentication": "true"
}
```
Details
If your API uses OAuth 2.0 authentication, you must enter the client ID, client secret, and refresh token in the [**Authentication** section](https://docs.coveo.com/en/9618#authentication-section) of the **Add an SAP source** panel.
Then, in your JSON configuration, you must use the `@ClientId`, `@ClientSecret`, and `@RefreshToken` placeholders to refer to this information.
Your `Authentication` object could therefore look like this:
```json
"Authentication": {
"OAuth": {
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
}
}
}
}
}
```
Details
```json
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
}
}
}
```
Details
```json
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
}
}
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
```json
"Authentication": {
"OAuth": {
"UsingSingleUseRefreshToken": true,
"Query": {
"RefreshUrl": "https://auth.example.com/oauth/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
}
}
}
}
}
```
Details
```json
"Headers": {
"Custom-Header-Name": "myValue",
"Application-Interface-Key": "xxxxxxxx"
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=100&pageNumber=0+` for the first page, and `+http://example.com/api/item?limit=100&pageNumber=1+` for the second page.
With these URLs, Coveo would request the first page (page 0), and then increment the page number by 1 to request the second page, and so on.
In this case, your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 100,
"OffsetStart": 0,
"OffsetType": "page",
"Parameters": {
"Limit": "limit",
"Offset": "pageNumber"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=100&start=0+` for the first page, and `+http://example.com/api/item?limit=100&start=100+` for the second page.
With these URLs, Coveo would request the 100 first items starting from item 0, and then the 100 next items, starting from item 100.
In this case, your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 100,
"OffsetStart": 0,
"OffsetType": "item",
"Parameters": {
"Limit": "limit",
"Offset": "start"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=8+` for the first page, and `+http://example.com/api/item?page=3d170d80d8n3n2342c328s+` for the second page.
In this context, Coveo would request the first page, and then the next page using the URL provided in the `nextPage` value in the JSON response.
In this case, if your API returns the following first page:
```json
{
"nextPage": "http://example.com/api/item?page=3d170d80d8n3n2342c328s",
"items": [
{ "id": 1, "name": "Caroline" },
{ "id": 2, "name": "Marcella" },
{ "id": 3, "name": "Susie" },
{ "id": 4, "name": "Rhonda" },
{ "id": 5, "name": "Wendy" },
{ "id": 6, "name": "Barbara" },
{ "id": 7, "name": "Deirdre" },
{ "id": 8, "name": "Lynda" }
]
}
```
Then your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 8,
"NextPageKey": "nextPage",
"OffsetType": "url",
"Parameters": {
"Limit": "limit"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=8+` for the first page, and `+http://example.com/api/item?limit=8&nextPageToken=3d170d80-7b3b-4377+` for the second page.
With these URLs, Coveo would request the 8 first items, and then the next page using the token provided in the `NextPageId` value in the JSON response.
In this case, if your API returns the following first page:
```json
{
"nextPageId": "3d170d80-7b3b-4377",
"items": [
{ "id": 1, "name": "Caroline" },
{ "id": 2, "name": "Marcella" },
{ "id": 3, "name": "Susie" },
{ "id": 4, "name": "Rhonda" },
{ "id": 5, "name": "Wendy" },
{ "id": 6, "name": "Barbara" },
{ "id": 7, "name": "Deirdre" },
{ "id": 8, "name": "Lynda" }
]
}
```
Then your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 8,
"NextPageKey": "NextPageId",
"OffsetType": "cursor",
"Parameters": {
"Limit": "limit",
"Offset": "nextPageToken"
}
}
}
```
Details
Your source configuration contains the following `Permissions` object, which indicates that members of the Support Agents group should be allowed to access the indexed content:
```json
"Permissions": [
{
"Name": "Permission Level 1",
"PermissionsSets": [
{
"Name": "Permission Set 1",
"AllowedMembers": [
{
"Name": "Support Agents",
"Type": "Group",
"PermissionType": "MyPermissionType2",
"AdditionalInfo": {
"group_id": "00841"
}
}
],
}
]
}
]
```
To extract the members of this group, you provide the following permission configuration.
Therefore, the security identity provider will use the `group_id` you specified in the source configuration to make an API request and obtain the group members.
Then, the security provider will refer to the `user` instructions to retrieve the desired information on the extracted group members.
```json
"identities": {
"group": {
"permissionSubQueries": [
{
"path": "/group/%[coveo_parent.group_id]/members",
"method": "GET",
"itemPath": "members",
"permissionType": "user",
"name": "%[username]",
"type": "User",
"additionalInfo": {
"user_id": "%[user_id]"
}
}
]
},
"user": {
"permissionSubQueries": [
{
"path": "/users/%[user_id]",
"method": "GET",
"itemPath": "user",
"name": "%[email]",
"type": "User"
}
]
}
}
```