Exporting and importing workplace studio pages and search views

Create your studio pages or search views in a development environment, and then easily transfer the pages to your staging and production environments. Use the export operation to create an export package of the studio pages in one environment. You can then import this package into another environment. You can import a single page or multiple pages. In a multitenant environment, the export and import between subtenants have certain restrictions to be considered. For more information, see Export import limitations.

Required license

BMC Helix Digital Workplace Advanced

Video demonstration

The following video (3:40) demonstrates how you can export and import studio pages and provides some best practices and checks when you use this functionality.

Watch this video on YouTube to learn how to use the export-import functionality to transfer studio pages between different environments.

From the pages selected for export, the export operation creates an export ZIP package that contains a data file in JSON format and an export manifest file. You must import this package into the other environment. The following image shows the different steps in transferring studio pages from one environment to another.

You can export pages irrespective of their status. If a page being exported has a Published with draft status, only the published version of page is exported. All pages are imported in a draft state. BMC Helix Digital Workplace identifies studio pages by their IDs. When you import pages, if a page with the same ID exists in the import environment, the existing page is overwritten by the page being imported. Note that you cannot undo an import operation. Because studio pages are always imported as drafts, you can discard drafts that you do not want.

Export import limitations

When you export and import studio pages or search views, note the following information:

Feature	Limitation	Action
Catalog sections and items in a studio page	Although the catalog section IDs and metadata are exported, the services themselves are not exported.	You might need to import catalog items to the destination environment first. The sections themselves remain invisible until you click them.
Catalog sections and items in a studio page	Catalog sections are tenant-specific. In a multitenant environment, you can't export and import catalog sections from one subtenant to another. If you export a page that contains catalog sections from one subtenant and try to import it in a different subtenant, the page import fails because the catalog section IDs already exist for the source subtenant in this multitenant environment. The import process is interrupted to preserve data segregation between subtenants.	To export and import pages between subtenants, you must remove catalog sections from the pages. After you import the pages to other subtenants, manually add the catalog sections to them. As a result, unique IDs are assigned to catalog sections in each subtenant.
Entitlements of a studio page	Entitlements are not retained when you export and import pages. The imported pages are accessible to all users.	Use the Entitlement Manager to add entitlements and restrict your imported pages to select people groups.
Navigation menu	Because pages are imported as drafts, they are not available in the Navigation Manager UI.	After you import the pages, publish them and then add them to the navigation menu. This makes them available to your end users.

Import considerations for a studio page with catalog sections

If a matching catalog section ID does not exist in the destination environment, a new catalog section is created during the page import. This new section includes the specified ID, metadata, and references to catalog items or services.
If a matching catalog section ID exists in the destination environment, you are prompted to choose whether to use the imported catalog section or the destination catalog section.

Import considerations for an embedded search view

If a search view that you want to import is embedded within another studio page, consider the following scenarios:

The studio page and the search view are independent of each other. You must import both in the same target environment so that the embedded search view is not broken. You can import both separately.
If the search view and studio page both are in the same source environment, but only the studio page is imported to the target environment, the search view link is broken.
If the search view and studio page are in different source environments, and you import only the search view to the target environment, the link is broken. If you import the studio page to the same target environment as the search view, the broken link is resolved automatically.
If the search view and studio page are in different source environments, but you import both in the same environment, the link is resolved and is not broken.

Best practices for exporting and importing pages

Import the export package created by the BMC Helix Digital Workplace Studio export operation.
Do not edit or modify the generated files or the export package.
If a page with the same ID exists in the import or target environment, publish the page in the target environment before importing. If you do not do so, the page will exist in a draft state and the page being imported is will also be in a draft state. Consequently, the imported page will overwrite the existing content.
Note that page ID is different from the page title or name. Page ID is the unique ID that gets generated when you create a page.
For pages with Published with draft status, BMC Helix Digital Workplace exports only the published version of the page. To export the draft changes, ensure that you publish the changes before exporting the page.
For environment-specific URLs, ensure that URLs work after the import is complete.
Ensure that the Studio (expose pages to end users) setting is enabled.

To export studio pages

Log in to BMC Helix Digital Workplace in the export environment.
In the admin console, select Configuration > Studio.
Select the pages that you want to export, and then select Actions > Export.
Download the export package.
The following image shows the steps in an export operation:

Important

Some browsers might automatically open and unzip downloaded files. Either use a different browser to download the export file or configure your browser to download ZIP files without unzipping them.

To import studio pages

Log in to BMC Helix Digital Workplace in the import environment.
In the admin console, select Configuration > Studio.
Select the My pages and select Actions > Import.
Select the export package that you downloaded earlier.
Select how to resolve catalog sections that exist in both the import environment and the export package:
- To keep the catalog section definition that is currently present in the import environment, select Use the destination definition. Select this option when you want to ensure that the existing catalog sections are retained.
- To use the catalog section definition from the export package, select Use the imported definition. Select this option when you want to overwrite the existing catalog sections with the imported definitions.
  Important
  In a multitenant environment, you can't export and import catalog sections from one subtenant to another. For more information, see Export import limitations.
Confirm the import.
The following image shows the steps in an import operation:

To make imported studio pages available to end users

This task is not required for imported search views.

Add the desired catalog sections manually, if needed; for more information, see Creating-pages-in-the-studio.
Enable the Studio (expose pages to end users) setting, if not already enabled.
Entitle the pages to appropriate people groups; for more information, see Making-studio-pages-available-to-end-users.
Publish the pages.
Add the pages to the navigation menu; for more information, see Setting-up-navigation-for-your-workplace.

To export search views

Log in to BMC Helix Digital Workplace in the export environment.
In the admin console, select Configuration > Studio.
On the search views tab, select the search view that you want to export, and then select Actions > Export.
Download the export package.
The following image shows the steps in an export operation:

Important

Some browsers might automatically open and unzip downloaded files. Either use a different browser to download the export file or configure your browser to download ZIP files without unzipping them.

To import search views

Log in to BMC Helix Digital Workplace in the import environment.
In the admin console, select Configuration > Studio.
On the search views tab select Actions > Import.
Select the export.zip package that you downloaded earlier.
Select how to resolve search views that already exist in both the import environment and the export package:
- To keep the search view that is currently present in the import environment, select Skip the import. Select this option when you want to ensure that the existing search view is retained.
- To use the search view from the export package, select Replace with imported. Select this option when you want to overwrite the existing search view with the imported search view.
  Important
  In a multitenant environment, you can't export and import search views from one subtenant to another. For more information, see Export import limitations.
Confirm the import.
The following image shows the steps in an import operation:

When Studio pages are created with HKM filters under all sources in Source environment, Filters details will not be visible to Target environment after Import.

To verify that imported pages and search views work in the new environment

After the export and import operations, perform the following steps to ensure that the imported pages work as designed in the new environment:

Check for broken links, links that do not work, or links that appear as plain text:
- For internal links, the page that a link points to must exist in the import environment. Internal links are links to the BMC Helix Digital Workplace pages, embedded pages, or search views.
- Links must be of the supported URI schemes. For more information, see Creating-workplaces-for-your-lines-of-business.
If the colors have changed, check the Branding page in the import environment.
By default, studio pages follow the theme or branding colors. If you selected branding colors when you created a page, after import the page displays the branding colors of the new environment. You might need to customize the colors as desired. For more information about branding, see Rebranding-BMC-Helix-Digital-Workplace.

Upgrade considerations

After upgrading to the new version of BMC Helix Digital Workplace, consider the following changes to the studio pages:

If you are have upgraded to the newer product version, then after import, the categories in studio pages are separated by a semicolon. The items inside the category are separated by a comma and begin with an hyphen. End users view the settings in read-only mode.
The following image is an example of how categories and its items are displayed:
(Upgrade from version 23.3.04 to version 25.1) If you created a studio page with filters for BMC Helix Knowledge Management by ComAround and after upgrade, imported it in the new environment, then the filter details are not displayed.

Troubleshooting content in the Studio pages and search views

The following table describe the common problems that might occur after importing pages and steps to troubleshoot these problems:

Problem	Steps to troubleshoot
Broken links of components Links to the following components can break if the mapped component has its content removed from an environment, or when the page is imported to a different environment where the content might not exist: Asset Group—Linked to a logical group of services with associated service actions and assets. Catalog Section—Linked to a group requestable services, items, and knowledge articles. Catalog Banner—Linked to promotional banners. Search view—Linked to an action button in a content block or a search bar.	Click the component to open the Properties panel and relink content, as shown in the following video example where the Catalog section is linked to Quick Links:
Unable to view content due to lack of permission	The following message is displayed if the Catalog administrator does not have permission to view the content inside the linked component: For end users, blocks with empty content are not displayed in the page at runtime. Provide the necessary permissions to the Catalog administrator to view the content inside the linked component.

Problem

Steps to troubleshoot

Broken links of components

Links to the following components can break if the mapped component has its content removed from an environment, or when the page is imported to a different environment where the content might not exist:

Asset Group—Linked to a logical group of services with associated service actions and assets.
Catalog Section—Linked to a group requestable services, items, and knowledge articles.
Catalog Banner—Linked to promotional banners.
Search view—Linked to an action button in a content block or a search bar.

Click the component to open the Properties panel and relink content, as shown in the following video example where the Catalog section is linked to Quick Links:

Unable to view content due to lack of permission

The following message is displayed if the Catalog administrator does not have permission to view the content inside the linked component:

For end users, blocks with empty content are not displayed in the page at runtime. Provide the necessary permissions to the Catalog administrator to view the content inside the linked component.