Migrating Search Pages and Custom UI Components to a Production Instance

Depending on your enterprise workflow, you may have two Dynamics instances, i.e., one for pre-production tests and one for production, each linked to their own Coveo Cloud organization. You may use your pre-production instance and sandbox organization to ensure that your changes have the desired effect before making them officially available in production to all Dynamics users. For instance, if you want to change your Microsoft Dynamics 365 source configuration, edit a search page, or install the latest Coveo for Microsoft Dynamics 365 upgrade (see Add/Edit a Microsoft Dynamics 365 Source, Editing a Search Page, and Upgrading Coveo for Microsoft Dynamics 365), you can test it first using your Dynamics pre-production instance and your Coveo Cloud sandbox organization.

When satisfied with your changes to search pages and UI custom components in your pre-production instance, you can export the pages and components to a production instance, thus avoiding to reproduce your changes manually in your production instance.

If you do not have any search pages or custom UI components to migrate to production, you do not need to follow these steps. Other changes, such as changes to a Microsoft Dynamics 365 source configuration or a Coveo for Microsoft Dynamics 365 upgrade, must be redone manually in your production instance.

Step 1 - Create a Custom Export Solution

To migrate your search pages and custom UI components to a production instance, you must first create an export solution.

  • If your migration flow already includes a solution exporting and importing changes from a pre-prod to a prod-instance, you can use it and skip this step.
  • Similarly, if this is not your first time following these steps, you can reuse the solution you previously created. It is however a good practice to increase the solution version (set to 1.0.0.0 in the screenshots below).
  1. In your Dynamics instance, in the top black ribbon, navigate to Settings > Customization > Solutions.
  2. In the All Solutions page, click New.
  3. In the Solution: New Solution window that opens:
    1. Enter a solution Display Name and a Name.
    2. In the Publisher field, click the search icon, and then select the Default Publisher for [your instance].
    3. Enter a version number.
    4. At the top of the window, click Save and Close.

Creating Solution

Step 2 - Export Customized Entity Forms

If you made changes to an Insight panel embedded in an entity form, you must include the modified form in the export solution you created. If you only modified search pages, you can skip this step.

When a form is exported, the export includes all form modifications. As a result, if you made other modifications beside embedding an Insight panel, these modifications will be exported as well.

  1. If not already done, in your Dynamics instance, in the top black ribbon, navigate to Settings > Customization > Solutions.
  2. In the All Solutions page, click your export solution display name.
  3. In the Solution: [Solution Display Name] window that opens, in the Add Existing drop-down menu, click Entity.
  4. In the Select solution components dialog that opens, select the entities in which you embedded an Insight panel, and then click OK.

    Selecting Solution Components

  5. In the next dialog, select the entity assets that you modified and want to export, and then click Finish.

    Selecting Entity Assets

  6. In the Missing Required Component dialog, select Yes, include required components, and then click OK.

    Selecting this option also exports the search pages embedded in the selected forms, allowing you to skip the search page export step.

Step 3 - Export Search Pages

You must now include the Coveo for Microsoft Dynamics 365 search pages to export, such as your full search page or your side panel search page (see Search Pages and Searching With Coveo in Dynamics).

If you already included all your search pages at Step 2 - Export Customized Entity Forms, you can skip this step.

  1. If not already done, in your Dynamics instance, in the top black ribbon, navigate to Settings > Customization > Solutions.
  2. In the All Solutions page, click your export solution display name.
  3. In the Solution: [Solution Display Name] window that opens, in the Add Existing drop-down menu, click Web Resource.
  4. In the Select solution components dialog that opens, select the coveo_/searchpages search pages to export, and then click OK.

    Typically, your selection should include the coveo_/searchpages/default and the coveo_/searchpages/sidepanel search pages, as well as any other page that was not included in the entities exported at Step 2 - Export Customized Entity Forms.

Step 4 - Export Custom Web Resources

If you have custom UI components in your pre-production instance and want to export them to your production instance, you must create a web resource similar to the one you created in Step 3 - Export Search Pages.

If you do not have any custom UI components, you can skip this step.

  1. In the Solution: [Solution Display Name] window, in the Add Existing drop-down menu, click Web Resource.
  2. In the Select solution components dialog that appears, select the .js and .css resources required by your custom components, and then click OK.

    If you followed the coveofordynamics-search-ui-seed tutorial, you must select the following resources:

    • coveo2_/coveo.extension.js
    • coveo2_/coveo.extension.jsa.map
    • coveo2_/coveoextension.css

Step 5 - Export Custom Solution

Once you prepared your search pages and custom UI components for exportation, you can use your custom solution to make your changes available to your production instance.

  1. In the Solution: [Solution Display Name] window, click Publish All Customizations. Once the customizations are published, you can close this window.
  2. Back in the All Solutions page, select your export solution, and then click Export.
  3. In the export wizard, click Next and Export without altering the default parameters. A .zip file named after your solution will then be downloaded.

Step 6 - Create Search Page Records

If you only exported search pages of which your target production instance contains an older version, you can skip this step. This includes pages imported along with entity forms (see Step 2 - Export Customized Entity Forms).

Since a Coveo for Microsoft Dynamics 365 search page consists in a web resource and a record of the Coveo search page entity, the records in your production instance must match the search pages to import. You must therefore ensure that, for each pre-production search page to import, there is a search page of the same type and with the same name in your production instance (see Classic and Insight Panel Search Pages). To do so, use the Coveo for Microsoft Dynamics 365 interface (see Creating a Search Page). As a result, when you import your custom solution, the code of each production page will be replaced with the code of the corresponding pre-production page.

Alternatively, you could export these records using a custom view on the Coveo Search Pages entity. This method requires more manual steps and offers no benefits, unless you want to automate the export. If you decide to go this way, you must export the Name, Type and Web Resource fields to an Excel worksheet, which you will import in your Dynamics production instance (see Step 7 - Import the Custom Solution in your Production Instance).

Step 7 - Import the Custom Solution in your Production Instance

Once you prepared your exportation and created search page records matching the new search pages to import, you are ready to import your search pages and custom UI components in your production instance.

  1. In your production instance, navigate to Settings > Customization > Solutions.
  2. In the All Solutions page, click Import.
  3. In the Import Solution dialog, select the .zip file you previously downloaded, and then click Next (see Step 5 - Export Custom Solution and Step 6 - Create Search page Records).
  4. Click Import, and then Publish All Customizations.