Exporting and importing workplace studio pages
Create your studio pages 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.
From the pages selected for export, the export operation creates an export ZIP package that contains a data file in the 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, note the following information:
|Catalog sections and items||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.
|Entitlements||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.|
Additionally, when importing catalog sections, note the following:
- 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.
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.
- Ensure that Use enhanced catalog section and tile framework (version 22.1.05 and later) 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:
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 Actions > Import, and then 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.
- Confirm the import.
The following image shows the steps in an import operation:
To verify that imported pages 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 or to embedded pages.
- 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.
To make imported pages available to end users
- 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.
Troubleshooting content in the Studio pages
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:
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.