As software systems become increasingly specialized, many customers find themselves needing to integrate more systems than ever before. This blog will guide you through the process of integrating an external source with Coveo and Sitecore for an optimized digital asset management experience.
Coveo offers numerous built-in integrations that can serve as indexing sources, Sitecore being one of them. However, there are various use cases that necessitate the integration of external sources for which no built-in connector exists. If your external source provides an API, you can leverage Coveo’s generic REST API source to retrieve results from that external source.
Prerequisites
Before starting the integration, ensure you have the following prerequisites:
- External DAM Account: Access to your DAM instance, including API credentials.
- Coveo Account: Coveo platform with API key access. Your Coveo license must include the use of the Rest API Source.
- Sitecore Instance: A running Sitecore instance with access to Sitecore Experience Platform (XP) or XM with the Coveo for Sitecore package installed and setup.
- Basic Programming Knowledge: Familiarity with REST APIs, JavaScript, and C# for Sitecore.
Part 1: Set Up External API Access to the Digital Asset Management System
To begin, confirm that the external API is prepared for integration with Coveo. I will use OAuth2 for illustration purposes but the process will be similar for other authentication methods.
- Log into your Digital Asset Management System and find the section for API access.
- Set the necessary authentication values. Using OAuth2 the could include: Grant type, Redirect URI, CORS, Scope
- Make note of the client ID and client secret and base URL of your Asset Management API instance.
Part 2: Set Up Coveo to Index your external assets
This is where most of the setup and configuration will take place. You need to configure Coveo to connect to and index your external sources’ digital assets so they can be searched and displayed within Sitecore.
1. Create a Connector in Coveo:
- Log in to the Coveo Admin Console.
- Navigate to Content → Sources and create a new custom source.
- In the Source Setup, choose REST API Source to configure a custom API integration.
- Configure the source using the API settings created in the step 1, setting the Endpoint URL to your asset list endpoint (e.g., /api/v6/media/). This is done in the Authentication section of the new source JSON configuration. Example Below.
In the above example, @ClientId, @ClientSecret, @RefreshToken, and any URL’s would be replaced by the values you received in Part 1. If using a Refresh Token then set the SupportsRefreshToken value to True.
There are many other possible authentication methods such as, no authentication (public access), user/pass, api key etc...
For examples of using other methods see the following documentation
2. Define the MetaData & Structure:
You will now need to define the structure of the data and ensure that Coveo indexes key metadata fields.
Using the above sample JSON, at the root level of Endpoints, set the API path to retrieve your media items, as well as any query parameters you may be passing in to filter the results.
The following properties are required:
- ClickableUri
- ItemType
- Path
- Uri
There are many additional optional fields which can be found with descriptions here.
In the Metadata section of the JSON you must provide a key/value mapping of fields returned, where the left hand side is the Key and right hand value is the JSON path. You only need to map fields that you require from the API.
Some common mapping formats include
- %[field_name] – general field mapping
%[field_name[*]] – return all items from a multi-value field - %[field_name[0]] – return the first item from a multi-value field
- %[[‘field name has whitespace’]] – property has whitespace in the name
- %[parent.field] or %[parent.raw.uri] – if querying subitems you can reference a parent items data, include raw if the item was not included with the parent mapping.
- “static property” – static text
For additional field type mappings see REST API source concepts | Coveo Platform
For additional JSON examples, such as mapping subitems or setting a token refresh endpoint see the following url: REST API source configuration examples | Coveo Platform
Once configured, Coveo will automatically fetch and index digital assets from your external source.
3. Map the Metadata to Coveo Fields:
Aside from the JSON configuration you just setup Coveo has 2 additional tools to assist in mapping Metadata. If you click on your source you will see a Mappings option and a View and map metadata option.
View and map metadata is useful for seeing all available fields pulled in from the source and indicates if they are currently included in the index
The Mappings option allows you to Map Metadata Keys to Coveo fields. If a Coveo field already exists with the Metadata Key name this mapping is automatic. If a field name doesn’t exist with the Metadata Key you will need to map it here.
Below is a complete example of a basic JSON configuration for an External Source: 
4. Test the Source:
- Save and test the new source.
- Make sure Coveo is able to fetch and index assets by checking the Content Browser within Coveo's Admin UI.
- Schedule the Source. You can setup how often you want a full rescan or a refresh. Refresh will only work if you have setup the refresh configuration in your json as outlined here.
Part 3: Display Search Results in Sitecore with Coveo Search
The final part of this puzzle is getting your newly indexed assets to display in Sitecore. It is assumed that you already have Coveo for Sitecore installed and returning results from Sitecore with a search interface.
1. Check for custom code that may specify Coveo Sources to include:
If you have any custom code that specifies the source you must update it to include the newly created source name. An example of this might be if you pointed Coveo to your own Coveo Search Interface.cshtml and manually specified the source. A quick search for @@source would likely determine if this is the case:
2. Specify the external source name in Sitecore:
If you have not customized the Coveo Search Interace query/code you can add the source by specifying the external source name on the Sitecore datasource item for the Coveo Search Interface.
Part 4: Personalize and Optimize Results in Sitecore
Once the basic integration is complete, you can leverage Sitecore's personalization capabilities and Coveo’s machine learning features to tailor the search results to specific users.
1. Use Sitecore Personalization:
Using Sitecore Experience Platform (XP), create personalized search experiences by:
- Setting up rules based on user profiles or behavioral data.
- Displaying different DAM assets based on user segments (e.g., showing media for specific industries).
2. Coveo Machine Learning:
Coveo’s Recommendations and Query Suggestions can optimize the search experience by suggesting the most relevant assets based on user interaction and preferences.
- Enable Coveo’s Automatic Relevance Tuning (ART) to prioritize popular assets.
- Use query suggestions to help users discover relevant content faster.
Part 5: Testing and Troubleshooting
1. Test the Integration:
- Check that your assets show up. If everything is setup correctly you should see your assets show up in search results alongside any other sources you have, such as Sitecore Items.
- Try searching for specific asset from your DAM in Sitecore’s search interface.
- Ensure that Coveo properly indexes new assets added to your DAM and they appear in Sitecore's search results.
- Test how different types of users interact with the search, leveraging Sitecore personalization.
2. Troubleshoot:
A very useful tool for troubleshooting search results is the Coveo Debugger. Hovering over any search result in Sitecore while holding down the Alt-key and double-clicking the left mouse button will bring up a debug modal that shows:
- All fields
- Ranking Info
- The Coveo template display code that the item is mapped to
You have now Integrated your external Digital Asset Management system with both Coveo and Sitecore. Do you have additional questions about Coveo, Sitecore or DAM systems? Get in touch with us now and Happy Searching!!
References:
- https://docs.coveo.com/en/1896/index-content/add-a-rest-api-source
- https://docs.coveo.com/en/1525/index-content/rest-api-source-reference#endpoints-array-required
- https://docs.coveo.com/en/3131/index-content/rest-api-source-concepts#multi-value-fields
- https://docs.coveo.com/en/1996/index-content/rest-api-source-configuration-examples