Upgrading

If your site already uses Edge Delivery Services with document-based authoring (SharePoint or Google Drive) and you wish to upgrade to Experience Workspace, you have two options for how to upgrade.

The upgrade option you choose is largely dependent on your QA practices. This is because, in general, upgrading a project to Experience Workspace from document-based authoring is about 90% QA, 5% development, and 5% operations. The goal is to ensure with 100% confidence that your new Experience Workspace site is exactly like the existing SharePoint or Google Drive-based site.

This document focuses on the general strategies for upgrading your project. If you want a developer-centric view into the upgrade process including differences you should be aware of, please see our developer guide on upgrading.

Approaches

There are two approaches to upgrading your document-based project to Experience Workspace:

  1. fstab swap - Change the fstab of the original repo without involving your CDN team.
  2. origin swap - Change your origin at the CDN layer to point to your new Experience-Workspace based repo.

Both options have their advantages and disadvantages. Both options require a new project (repoless or full repo) to be made.

Both methods also allow you to work in parallel on each project.

fstab Swap

Advantages

  1. It requires no involvement from a CDN / web operations team.
  2. You can keep your existing repo name.
  3. No re-training creators on new domains (mysite--myorg.aem.live vs da-mysite--myorg.aem.live) is necessary.

Disadvantages

  1. It is not possible to spoof test with the final origin before go-live.
  2. Code must be carefully scrubbed for references to different origins.
  3. Any code on the Experience Workspace repo will need to be ported back and done in a way that is forwards and backwards-compatible with the new and old content.

Origin Swap

Advantages

  1. It offers the ability to spoof test before go-live.
  2. It offers the ability to QA across different phases (dev, stage, prod) before moving to the next phase.
  3. There is no need to sync code changes back to the original repo.

Disadvantages

  1. A typical convention is to make a new repo with da- appended to the existing repo name. You would then have this prefix for your site going forward which can feel a bit redundant and un-clean.
  2. Code changes in the original repo must be brought forward.

Approach recommendation

If you have the ability to spoof test or change your CDN origins before go-live, an origin swap is the safest path to upgrade. It allows you to change each part of your CDN and gain confidence over the lifecycle of your CDN stack:

  1. Point CDN stage to new repo.
  2. Test and QA.
  3. Configure CDN prod for new repo (via staging network / spoof test).
  4. Test & QA.
  5. Push staged production config to production.

If you do not have the ability to perform an origin swap, an fstab swap does have some advantages. Because Edge Delivery Services does not allow different content sources for different branches, when you change your fstab, it changes everywhere.

At the expense of extra work, if the da- prefix bothers you post go-live, you can do an origin swap and an fstab swap:

  1. Go-live with the new da- repo.
  2. Change old repo to point to Experience Workspace-based content.
  3. Change origin back to original repo.

Comprehensive upgrade strategy

Below you will find the steps to upgrade a project to Experience Workspace. This example uses the origin swap method with extensive QA with an indication of the roles responsible for each task. Where time estimates are known, they are given.

  1. Developer - Fork the existing site and prefix the repo name with da-. - 5-10 minutes
    1. You can also create a repoless project.
    2. For a repoless project, you would need to make any code changes in the source repo.
  2. Developer - Make some dummy content to ensure basic functions work. - 2-5 minutes
  3. Developer - Query your content tree to get a list of docs, sheets, fragments, videos, pdfs, svgs, and redirects. - 5-10 minutes
  4. Developer - Run an import of the result from the content tree query. - 1 minute per 1,000 pieces of content
  5. Developer - Import redirects, .helix/config since these are not in the status result. 5-10 minutes
  6. Developer - Make note of date and time of this import.
  7. Developer - Preview and publish all content. - 3s per 10 pieces of content
  8. Developer / QA engineer - Smoke test high profile content on new repo.
  9. Developer - Fix any known issues from smoke test.
  10. Content QA - Full regression / validate new repo content. Any bugs should be checked against the original repo to ensure these are not pre-existing issues.
  11. Content author - Fix issues flagged by content QA.
  12. SEO - Validate sitemap parity with original repo.
  13. Web Ops (CDN team) - Point CDN stage to new origin.
  14. Content QA / QA Engineer - Full regression test against CDN stage.
  15. Developer - Fix any new issues from CDN stage testing.
  16. Web Ops (CDN team) - Setup spoof test config for production.
  17. Developer / content author - Perform delta import (and publish) to import anything that was published after the initial import.
  18. Everyone (PM, Content QA, QA engineer, SEO, developer) - Point /etc/hosts to staged production config and test.
  19. Web Ops (CDN team) - Push staged production config live.

Known issues

  1. Edge Delivery Services limits markup sources to 10MB images.
    1. If you have very large images in SharePoint or Google Drive, you may run into errors when trying to preview.
  2. Edge Delivery Services limits markup sources to 100 images per document.
    1. If you have more than 100, you may run into errors when trying to preview.
  3. If your site has cross origin protections, you may need to use a browser extension to import your content.
    1. Please reach out to the Experience Workspace team for assistance.
  4. There's a small difference in the HTML that Edge Delivery renders from markup sources.
    1. This manifests as an extra paragraph tag in lists.
    2. You may need to change your blocks to accommodate this difference.
  5. Query Indexes from markup sources are strongly typed.
    1. If you have arrays of content or rely on certain date formats, you may need to change your blocks to account for this difference.

Developer upgrade guide

If you want a developer-centric view into the upgrade process including differences you should be aware of, please see our developer guide on upgrading.