---
title: Sandbox Migration Checklist
slug: guide/sandbox-migration-checklist
description: Follow the sandbox migration checklist for Unaric Guide to safely test and deploy help content changes in Salesforce.
docTags: 
createdAt: 2025-11-15T22:52:47.831Z
---

This page describes the most important steps one will typically take for migrating Embedded Help from a pre-production environment, such as a sandbox, to a production org. The precise to-do list will vary depending on your pre-production setup and production requirements.

:::hint{type="warning"}
These steps assume deployment into the **Lightning User Experience**: whilst many steps are the same or similar in **Salesforce Classic**, some will vary.
:::

## Install Unaric Guide into destination org

Ensure the destination org contains the desired version of Embedded Help. For more information, see [Getting Started](docId:0fctL9ZoPm9eIevGz0sW4) and [Embedded Help Setup](docId:4FdYLQ4XcjOiu-3coKHm6).

## Extract reusable materials from source org

If the source org contains Help-related content to be used in production, gather these materials in preparation for migration. 

### Local components and files

Take copies of relevant images, code, and other resource files.Items you may need to migrate include the following:

- **Local Lightning components**: If you have created any local *wrapper* Lightning components that extend or use those shipped with Unaric Guide, obtain a copy of the relevant code files so they can be re-created in the destination.
- **Other documents and resources**: If your Help Portal branding and / or individual Help Topics reference Salesforce ([https://ihdev-dev-ed.lightning.force.com/a00d000000o6j0nAAA](https://ihdev-dev-ed.lightning.force.com/a00d000000o6j0nAAA)) assets, such as Documents or Static Resources, from the source org, obtain copies of these for upload into the destination.

### Extract source Help Content records

Export any Help Content you wish to replicate in the destination org. If Topics, Reading Lists, Guides, details of embedded help etc. are to be migrated, export the desired content:

- Help content of this kind largely consists of Salesforce records, so can be migrated using a variety of specialist tools.
- For details of a simple, free content migration utility available from Improved Apps for simple needs, please see Related Help list associated with this Topic.

### Extract *local* Configuration Items

Mark locally customised Help Configuration Items and export all records. Unaric Guide **Configuration item** records are used to define *clickables* (buttons, menu items etc) on our Lightning components and also certain items of metadata. If any of these records have been modified to suit local requirements, the relevant items should be exported for porting to the destination org:

- Ensure any customised Configuration records are marked as such by checking the **Prevent Import Overwrites** field on the records in question. If you have modified your Lightning CSS, this will be stored as a Configuration Item, so this should be marked too.
- Ensure that the **Skip Export** check box **is not** checked on these items. Ticking **Skip Export** prevents the record in question from being included in downloads, so only check this box if you specifically do not wish to migrate a particular clickable.

:::hint{type="warning"}
Unaric Guide sets the **Skip Export** check box for certain ,metadata records: where this is the case, please do not amend this setting.
:::

:::Paragraph{indent="1"}
Export your source Configuration Items as described in the Topics related to this one.
:::

## Import reusables into destination org

Import Help content plus Configuration Items as well as any custom wrappers.

- **To import Help Content**, use the **Upload Additional Help** facility on the** Data Migration** tab of the **Help Global Settings **page.
- **To import Configuration Items**, use the **Upload Configuration Items** facility on the **Data Migration **tab of the** Help Global Settings** page.

## Create Lightning page layouts

Add the desired Help Lightning components to user page layouts and create Help Authoring app pages.

### Page layouts for Helped Users

Salesforce offers many ways to migrate the metadata that defines Lightning page layouts, including any Improved Help components, between orgs. For more information on what's the most convenient for you, refer to Salesforce's documentation.

### Page layouts for Help Authoring

Unaric Guide includes a number of page layouts designed to get you started with Help authoring. Refer to the listing tiles on the Welcome tab of the app for more information. You are free to define as many of your own authoring layouts as you require.
For authoring collections of Topics for multiple Help Domains (if desired):

1. Create a new Lightning page layout from the Lightning App Builder.
2. Name the page **Domain Editor** or similar.
3. Select the header and 3-page section template.
4. In the header area, add an Improved Help 'Tree Selector' component, as follows:
   1. **Height**: 100
   2. **Available Tree IDs**: enter a comma separated list of the Help Topic Ids that are to act as the 'root' of a tree for each desired Help Domain.
   3. **Tree Node Providers**: Enter X commas, where 'X' is the number of desired selector buttons minus 1. For example, if you entered a comma separated list of 3 topic IDs in the 'Available Tree IDs' parameter, enter ",," (2 commas).
   4. **Tree Labels**: Enter a comma separated list of the labels to use for each tree selector button. Each label corresponds to one of topics in the list of Available Topic IDs entered.
   5. **Component ID**: *Selector*.
5. In the left-hand column, add an **Improved Help Listing** component, as follows:
   1. **Height**: -2
   2. **Callout option**: *Topic Selected Event Only*.
   3. **Listing Type**: *Fixed Help*.
   4. **Overall Listing Style**: *Narrow.*
   5. **Component ID**: *List*.
6. In the centre column, add an **Improved Help Tree Viewer** component, as follows:
   1. **Height**: *-2*
   2. **Default Tree**: *\[None].*
   3. **Enable Drag and Drop**: Checked.
   4. **Component ID**: *Tree.*
   5. **Listens To: Topic**: *Selector.*
7. In the right-hand column, add an **Improved Help Topic Viewer** component, as follows:
   1. **Height**: *-2*
   2. **Default Help Topic**: *\[None]*
   3. **Component ID**: *Topic*.
   4. **Listens To**: *Tree, List.*
8. Save and activate the page, adding it (or not) to apps / navigation as desired.
   Create App & add list, Tree & Detail and tree selector for Helped Languages.

## Migrate Custom Wrapper components

Create Help Index wrapper component.

If locally defined Lightning wrapper components for Help were extracted as part of the migration, these can be recreated in the destination org at this point. To do this, open Developer Console, create new Lightning components and paste in the relevant code, as gathered during extraction.

## Set up Help Domains

Set up and test Help Domains to show different Help to different groupings of users.

If Help is to serve multiple audiences, for example defined by language or business role, each of which should see differing collections of help, Help Domains should be created in the destination org. See [Help Domains](docId:91AzE-2CvP3NoB6KTAmAh).

Once Help Domains have been created, we recommend creating Domain-specific test user accounts with appropriate sharing group membership and custom Permission Set assignments. One can then log in as these users to verify that (only) the desired Help appears.

## Setup contextual Help for the Utility Bar

Use the Improved Help Utility Bar component to make contextual help available throughout your Salesforce Apps.

Unaric Guide ships with a ready-made utility bar component (Utility 1) that combines a tree viewer and linked topic viewer that is ideal for providing a 'Help Index' or corporate glossary of available help content. The content can be made to contextualise (i.e., the tree can be made to change the topics it displays) as users navigate. 

1. In **Salesforce Setup**, navigate to the **App Manager** and edit the Lightning app to which a utility is to be added.
2. In the **App Settings **sidebar, select **Utility Items**.
3. Click **Add Utility Item **and select **Improved Help Utility 1**.
4. Tick the **Start automatically** check box.
5. In the **General\:Root Topic** field, add the ID of the desired default **root** for the tree.
6. In the **Contextualisation: Navigation Checking Interval** field, enter a number representing the time in milliseconds between checks of user location. Any change in location can be used to recontextualise. Where recontextualisation is desired, we recommend a minimum value of no less than 1000 for this.

Contextualisation occurs on any change of URL subject to two conditions:

- Unaric Guide must be able to locate a Helped Page Layout record that corresponds to the page being visited. Add Helped Page Layouts manually for pages that cannot be Help-enabled via point and click (using our Improved Help Autoform component).
- The Helped Page Layout must have an associated Helped Element record with the special Identifier of **ContextTreeRoot**.