About the PermanentId Field
permanentid field contains a value that uniquely and permanently identifies each item with respect to the original repository. The field value remains the same, even for an item that is indexed more than once with different sources. This field was introduced with the May 5, 2017 Coveo Cloud release so that Coveo Machine Learning (Coveo ML) models can learn user behavior on stable item IDs.
Prior to the addition of the
urihash field by default to identify index items. However, for some sources, such as a repository that allows9 to share items, an item could have more than one URI, and therefore more than one
urihash field value.
In a Box source, the item URIs include the Box user ID, so a shared file or folder has many URIs. The
permanentid field value is based on the Box
file_id value, which remains the same even when an item is shared and accessible with various paths by various users.
PermanentId Field Value
The method to get the
permanentid field value may be different depending on the repository type:
For most standard sources, the
Based on the item URI, because it is an appropriate unique and permanent identifier.
A 60 hexadecimal character hash of the item URI (to optimize index performances).
For other repository types, such as Google Drive and Youtube, where one item can have more than one URI, the
permanentidfield is typically a hash of a string containing:
(repository type identification) + (Unique separator) + (Source dependent unique item identifier)
In a Box source, the item
permanentidfield value is a hash of the string:
"https://www.box.com/" + "@@@" + file_id
file_idis the Box unique identifier for each item.
For Salesforce sources, the Salesforce item ID is used to set the
permanentidfor Coveo for Salesforce editions using a Coveo index. Coveo for Salesforce editions using a Salesforce index also pass the Salesforce item ID as the unique ID for all usage analytics events.
Consequently, if you migrate from a Coveo for Salesforce edition using a Salesforce index to one using a Coveo index, the item ID remains the same, keeping the Coveo ML learned behavior history for all Salesforce items.
The URI for a Salesforce case is:
permanentidvalue will be:
Taking Advantage of the PermanentId Field
permanentId field usage should be mostly transparent, but you may need to perform some tasks to fully take advantage of the custom aspects benefits.
Standard source types
The introduction and usage of the
permanentidfield is meant to be mostly transparent for standard source types:
permanentIdfield for each clicked item. It sends this field and its value with each usage analytics event, in the
contentIdValuemetadata fields respectively. The page always sends the
urihashfield and its value.
The Coveo ML models update take the
contentIdKeyfield and the
contentIdValuemetadata passed in usage analytics events to identify each item to learn from, using the
urihashas a fallback. The transition from the
permanentidfields is therefore automatic. Within an index or even a source, items may be identified using either fields.
The models can map older usage analytics events, which contain only the
urihashfield, to newer ones with both the
permanentIdfields. This allows each item’s click history to be preserved through the transition.
Following the transition from the
permanentidfields, your end users may experience a minor and temporary degradation of Coveo ML Automatic Relevance Tuning (ART) and Event Recommendations (ER) model performance, but only if you push custom usage analytic click events that do not include both the
This is because items whose unique identifier suddenly changes will appear as new items to Coveo ML models. With time, however, new usage analytics events on these items will accumulate, rebuilding their usage history and allowing Coveo ML models to learn from them again.
Custom sources (Push API)
For custom sources populated through the Push API, when the URI is not a unique identifier and you want to allow Coveo ML models to learn usage of pushed items, you can:
Push metadata that uniquely and permanently identifies each pushed item.
The content of the metadata can be anything such as a URI or a GUID, as long as it is unique and never changes.
Using an alphanumeric string of at most 60 characters (without spaces) optimizes index performance. However, you can use any value you want. Using a value that is not hashed can help with troubleshooting.
Map this metadata to the
permanentidfield (see Adding and Managing Source Mappings).