Upgrade from v2 to v3

This is for:

Developer

In this article

Migration to Coveo Event Protocol
Organization endpoints
Localization
Exports
Modified behaviors
Removals

The Coveo Platform platform is constantly evolving. Atomic v3 introduces changes and innovations that align with the latest evolution of the Coveo Platform.

The following are breaking changes from Atomic v2 to v3

Migration to Coveo Event Protocol

Coveo Event Protocol becomes the new default protocol. In other words, the Engine interface analytics.analyticsMode default value is now next rather than legacy.

If you’re using the default value in V3 and aren’t ready to migrate to the new protocol, set the value to legacy to keep using the Coveo UA protocol.

Only Coveo for Commerce supports EP at the moment. For every other kind of implementation, set analyticsMode to legacy when upgrading to v3.

const searchInterface = document.querySelector('atomic-search-interface');

await searchInterface.initialize({
    // ...
    analytics: {analyticsMode: 'legacy'},
});
// ...

Organization endpoints

Organization endpoints is a feature that improves separation of concerns, resiliency, and makes multi-region and data residency deployments smoother. Starting with Atomic v3, the usage of organization endpoints will be enforced automatically, as opposed to being optional in v2.

Atomic Version 2

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

    await searchInterface.initialize({
      accessToken:'<ACCESS_TOKEN>',
      organizationId: '<ORGANIZATION_ID>',
      organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>'),
    });

  searchInterface.executeFirstSearch();
})();

Atomic Version 3

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

    await searchInterface.initialize({
      accessToken:'<ACCESS_TOKEN>',
      organizationId: '<ORGANIZATION_ID>',
    });

  searchInterface.executeFirstSearch();
})();

For HIPAA organizations, rather than specifying hipaa argument in the getOrganizationEndpoints function, set the environment property to hipaa.

Atomic Version 2

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

    await searchInterface.initialize({
      accessToken:'<ACCESS_TOKEN>',
      organizationId: '<ORGANIZATION_ID>',
      organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>', 'hipaa'),
    });

  searchInterface.executeFirstSearch();
})();

Atomic Version 3

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

    await searchInterface.initialize({
      accessToken:'<ACCESS_TOKEN>',
      organizationId: '<ORGANIZATION_ID>',
      environment: 'hipaa',
    });

  searchInterface.executeFirstSearch();
})();

For most implementations, this is the extent of the changes. However, if you used the organizationEndpoints property to send requests to your proxy, which then relayed them to the Coveo APIs, you’ll need to make additional changes. Atomic v3 introduces the search.proxyBaseUrl, analytics.proxyBaseUrl, and commerce.proxyBaseUrl engine configuration options for such cases.

Atomic Version 2

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

  await searchInterface.initialize({
    // ...
    organizationId: 'my-org-id',
    organizationEndpoints: {
       ...(await getOrganizationEndpoints('my-org-id')),
      search: 'https://myproxy.com/search',
    }
  });

  searchInterface.executeFirstSearch();
})();

Atomic Version 3

(async () => {
  await customElements.whenDefined('atomic-search-interface');
  const searchInterface = document.querySelector('#search');

  await searchInterface.initialize({
    // ...
    organizationId: 'my-org-id',
    search: {
      proxyBaseUrl: 'https://myproxy.com/search',
    },
  });

  searchInterface.executeFirstSearch();
})();

`platformUrl` property

The already deprecated platformUrl property was removed from the initialize method options of every search interface component. It was used prior to the introduction of organizationEndpoints and has been deprecated since.

Localization

i18next `compatibilityJSON`

In Atomic v2, the compatibilityJSON property in the atomic-search-interface, atomic-insight-interface, and atomic-recs-interface components was set to v3 by default. In Atomic v3, the compatibilityJSON is automatically set to v4. The main change is the way that plural forms are handled.

Atomic Version 2

"past-year": {
  "en": "Past year",
  "fr": "Année passée"
},
"past-year_plural": {
  "en": "Past {{count}} years",
  "fr": "{{count}} années passées"
},
// ...

Atomic Version 3

"past-year_one": {
  "en": "Past year",
  "fr": "Année passée"
},
"past-year_other": {
  "en": "Past {{count}} years",
  "fr": "{{count}} années passées"
},
// ...

See JSON Format.

`remove-filter-on` renamed to `remove-inclusion-filter-on`

The remove-filter-on locale key was renamed to remove-inclusion-filter-on in Atomic v3. If you have custom locales using remove-filter-on, you should update the key to remove-inclusion-filter-on.

Atomic Version 2

"remove-filter-on": {
  "en": "Remove inclusion filter for {{value}}",
  // ...
},
// ...

Atomic Version 3

"remove-inclusion-filter-on": {
  "en": "Remove inclusion filter for {{value}}",
  // ...
},
// ...

Exports

Atomic exports multiple entry points, each meant to support different use cases and environments. To improve the inter-operability of Atomic with different industry standard tools, and to guide those tools to properly use the appropriate entry points depending on the use case, Atomic will start enforcing and specifying export fields in package.json. This means that implementations relying on non-public modules of the package will stop functioning.

Atomic Version 3

// This will be blocked entirely
import {nonPubliclyDocumentedFunction} from '@coveo/atomic/dist/nonPublicFile.js';

// Will throw an error, or won't compile
nonPubliclyDocumentedFunction();

`moduleResolution` in `tsconfig.json` when installing via npm

If you use Typescript, note that the node10/node module resolution is no longer supported. The classic module resolution, which was never supported, remains unsupported.

We recommend setting moduleResolution to bundler instead. See TypeScript module resolution and Announcing TypeScript 5.0 --moduleResolution bundler.

Atomic React

The @coveo/atomic-react package will no longer export functionality from the Headless package. It will only contain Atomic React components. Instead, you should import them directly from the @coveo/headless package.

Atomic Version 2

import {
  AtomicFacet,
  AtomicText,
  // This function is coming from @coveo/headless
  buildSearchEngine,
  // This interface is coming from @coveo/headless
  Result,
} from '@coveo/atomic-react';

Atomic Version 3

import {AtomicFacet, AtomicText} from '@coveo/atomic-react';
import {buildSearchEngine, Result} from '@coveo/headless';

Also, you need to set moduleResolution": "bundler" in your tsconfig.json file to access secondary entry points such as @coveo/atomic-react/commerce or @coveo/atomic-react/recommendation. See TypeScript module resolution for more information.

Modified behaviors

`textarea` search box is now the default

To better support Relevance Generative Answering (RGA) use cases, some work was done to expand the search box input when the queries are verbose. This required modifying the HTML for the search box input to be a <textarea> element, as opposed to an <input type="text"> element.

In Atomic v2, an option was added on the atomic-search-box component to allow implementers to choose between a textarea and an input. In Atomic v3, that option has been removed, and only one type of input, textarea, is supported.

Atomic Version 2

<!-- Control the input type with the textarea option -->
<atomic-search-box textarea="true"></atomic-search-box>

Atomic Version 3

<!-- Option is no longer necessary, and the component will output a textarea element -->
<atomic-search-box></atomic-search-box>

`queryCorrectionMode`

The atomic-did-you-mean queryCorrectionMode property default value is now next rather than legacy. This means that the default behavior of the atomic-did-you-mean component will be to use a query suggestions model for query correction rather than the index mechanism.

Removals

`atomic-recs-list` and `atomic-result-list` `gridCellLinkTarget` property

The gridCellLinkTarget property was removed from the atomic-recs-list and atomic-result-list components. Instead of using this property, provide an atomic-result-link in the link slot of the atomic-result-template component.

Atomic Version 2

<atomic-result-list grid-cell-link-target="_blank">
    <atomic-result-template>
        <template>
            My template
        </template>
    </atomic-result-template>
</atomic-result-list>

Atomic Version 3

<atomic-result-list>
    <atomic-result-template>
        <template slot="link">
            <atomic-result-link>
                <!-- Moreover, you can add other attributes on the anchor element as well -->
                <a slot="attributes" target="_blank"></a>
            </atomic-result-link>
        </template>
        <template>
            My template
        </template>
    </atomic-result-template>
</atomic-result-list>

`atomic-hosted-page` and `atomic-simple-builder`

Use atomic-hosted-ui instead.

`atomic-load-more-children-results`

The component has been removed and its functionality has been integrated into atomic-result-children.

Atomic Version 2

<atomic-result-section-children>
  <atomic-load-more-children-results></atomic-load-more-children-results>
  <atomic-result-children image-size="icon">
  <!-- ... -->
  </atomic-result-children>
</atomic-result-section-children>

Atomic Version 3

<atomic-result-section-children>
  <atomic-result-children image-size="icon">
  <!-- ... -->
  </atomic-result-children>
</atomic-result-section-children>

`atomic-generated-answer` `withRephraseButtons` and `answerStyle` properties

The withRephraseButtons and answerStyle properties were removed from the atomic-generated-answer component due to low usage not justifying their maintenance.

Atomic React

The following are no longer supported in Atomic React.

IIFE

Atomic React is no longer exported via CDN. While this method was useful for quick prototyping, it wasn’t recommended for production. Instead, you should install Atomic React NPM.

Analytics configuration

Atomic React no longer exposes the analytics prop on the AtomicSearchInterface component, as it didn’t function correctly. Instead, you should use the engine.analytics.enabled configuration option.

Atomic Version 2 (Not working correctly)

<AtomicSearchInterface analytics={false} />

Atomic Version 3

const engine = buildSearchEngine({
  configuration: {
    // ...
    analytics: {enabled: false},
  },
});

`CommerceSearchBoxSuggestionsEvent`

When implementing custom query suggestions, you need to dispatch an event of type SearchBoxSuggestionsEvent from the registered query suggestions to the parent search box.

In v2, an event of type CommerceSearchBoxSuggestionsEvent was instead required in Commerce implementations.

In v3, the CommerceSearchBoxSuggestionsEvent type no longer exists. You should use SearchBoxSuggestionsEvent type instead.

Atomic React wrapper props

Two undocumented props were removed from the Atomic React wrapper component:

WrapperProps.pipeline
WrapperProps.searchHub

They were both marked as deprecated in v2, due to being ineffective. Rather, if you need to set those properties client-side, use the engine search configuration.

const MyPage = () => {
  const engine = buildSearchEngine({
    configuration: {
      search: {
        pipeline: 'my-pipeline',
        searchHub: 'my-search-hub',
      },
    },
    }
  });
  return (
    <AtomicSearchInterface engine={engine}>
      // ...
    </AtomicSearchInterface>
  );
};

Or better yet, enforce those properties through authentication (see Search token authentication and API key authentication).

Headless no longer exported through Atomic

In Atomic v2, the Headless library was exported through the Atomic library. This is no longer the case in Atomic v3. Instead, you should import Headless directly in your project.

Atomic Version 2

<head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css" />
    <script type="module">
      import {
        buildRedirectionTrigger,
        loadAdvancedSearchQueryActions
      } from 'https://static.cloud.coveo.com/atomic/v2/headless/headless.esm.js';

        // ...
    </script>
</head>

Atomic Version 3

<head>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v3/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v3/themes/coveo.css" />
    <script type="module">
      import {
        buildRedirectionTrigger,
        loadAdvancedSearchQueryActions
      } from 'https://static.cloud.coveo.com/headless/v3/headless.esm.js';

        // ...
    </script>
</head>