Skip to content

Upgrade Developer Guide

Jump to bottom
Chris Millar edited this page Feb 26, 2025 · 6 revisions

Introduction

Upgrading a site from SharePoint or Google Drive is a low complexity task. Despite being low in complexity, there are differences to know about and features to enable on the DA side.

High level things to know

  1. Protecting content - By default, your content is public. When you turn on permissions, you will use Adobe Identity (aka IMS) to login.
  2. Protecting publishing - Your Adobe identity ID (not email) is used if you want to turn on any Edge Delivery authentication.
  3. Live Preview - There is a small code snippet to add to scripts.js to enable DA's live preview.
  4. Live Preview - Most project's 404.html file needs a small change for live preview.
  5. Sidekick - There are two properties to add to Sidekick to enable edit from aem.page.
  6. Assets - Turning on AEM Assets requires an AEMaaCS instance.
  7. Delivery - There is one known difference in rendered HTML between Markup (DA, UE, etc.) and Google Drive / SharePoint. It's in nested lists when an extra paragraph tag is added. This usually surfaces in header navigations, but you may find this elsewhere.
  8. Delivery - There are several differences in media publishing support. These are documented in our business practitioner guide.
  9. Configurations - DA has configs (settings icon in breadcrumb) and Edge Delivery has configs (config bus or .helix/config). They both have different use cases.
    1. DA Config - Used for DA permissions and DA feature flagging (UE, AEM Assets, etc.)
    2. Edge Delivery Config - Used for CDN info, preview and publish permissions, api keys, etc.

Additional resources

  1. We have an end to end upgrade guide for business practitioners here: https://da.live/docs/administration/upgrade
  2. We have a guide on how to import content: https://github.com/adobe/da-live/wiki/Restore-from-aem
  3. We have a guide on setting up permissions: https://da.live/docs/administration/permissions

Live preview

Enable

The following code should be put into your scripts.js file:

(async function loadDa() {
  if (!new URL(window.location.href).searchParams.get('dapreview')) return;
  // eslint-disable-next-line import/no-unresolved
  import('https://da.live/scripts/dapreview.js').then(({ default: daPreview }) => daPreview(loadPage));
}());

This is an immediately-invoked function expression (IIFE) that will load dapreview.js if the dapreview query param is present.

404.html

Find

<script src="/scripts/scripts.js" type="module" crossorigin="use-credentials"></script>

Replace

<script src="/scripts/scripts.js" type="module"></script>

This is a legacy value that prevents external scripts from loading.

Note: It may be confusing at first, but DA's live preview uses aem.live as the target domain of the live preview.

Why DA live preview uses aem.live:

  1. The live preview is a reflection of what the page looks like when it will go live. If you have un-published fragments, you will see them as un-published in your preview. You gnav contents are a reflection of your live page, inherited metadata is a reflection of live, etc.
  2. Authentication for aem.page - Some companies require auth for their pre-production content. SAML / OAuth redirects in the preview iframe or requiring sidekick to be loaded would provide a poor user experience.
  3. Content injection - DA pushes the content from your editor into the live preview after 500ms of in-activity. Even if the page does not exist, DA will push the content into a shell 404 page and you will get a proper preview.

Enable Sidekick edit

Place the following in your tools/sidekick/config.json:

{
  "project": "DA Block Collection",
  "editUrlLabel": "Document Authoring",
  "editUrlPattern": "https://da.live/edit#/{{org}}/{{site}}{{pathname}}"
}

This will tell Sidekick to use DA as your content editor.

Identity

Protecting authored content

DA uses IMS top to bottom for identity. If you are a part of an organization, you are encouraged to use your org and groups to protect your content. If you do not have an organization, or prefer to use email addresses, you can also do so. The full docs are here: https://da.live/docs/administration/permissions

Protecting preview and publish access

For security reasons, email addresses are not exposed in IMS JWTs. As a result, Edge Delivery Services uses the IMS user ID to gate previewing and publishing content. This can feel a little foreign to people who have used email addresses or email wildcards in the past. To get your user ID, DA provides this information in the user profile dropdown in the top right of any DA view. Simply copy it and use it where you would normally place an email address in .helix/config.

Overlay Identity

If your project is using DA as an overlay on top of SharePoint or Google Drive, Sidekick and Helix Admin will default to the original IdP associated with Microsoft or Google. As a result, you may need to keep IMS identities and email addresses in your helix config for preview and publish permissions. We know this is not ideal.

Clone this wiki locally