Upgrading

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. Query index / Sitemap - You no longer need to maintain a sheet for query indexes and sitemaps. These are now kept internal to Helix. You turn on your query indexes using a helix-query.yaml file (or in config bus yaml) YAML index docs.

    1. Note: Indexes that are not sheet based (ie. DA / XWalk / etc.) will be strongly typed. If you have code that expects strings for things like arrays, do know this difference.

  10. 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.

  11. Spreadsheets - DA's sheet editor is not meant to be an Excel replacement. It's good for about 5,000 rows (YMMV). If you believe your project has complex sheet needs: conditional formatting, formulas, a lot of data, please use Edge Delivery's content overlay feature. More on this below.

  12. Spreadsheets - Helix cannot accept a named single sheet from DA. If you use named single sheets, we recommend adding another empty sheet or adjusting your code.

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 at the bottom of your scripts.js file:

  • scripts.js (JavaScript)
(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.

Notes:

  1. It does not impact performance.
  2. It will load a CSS file to create a consistent experience (disable links).
  3. It will create a bi-directional communication with DA.
  4. It tells DA to resize the iframe if the page height changes.
  5. Please use the query param to set a body class if you are running into VH + infinite height issues.

404.html

Find

  • 404.html (markup)
<script src="/scripts/scripts.js" type="module" crossorigin="use-credentials"></script>

Replace

  • 404.html (markup)
<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 Sidekick config (config bus or file based):

  • Sidekick (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.

Content overlay

Below is the Config Bus content object you can use to overlay SharePoint / Google Drive with DA. This will allow you to seamlessly blend Excel sheets with your DA data.

  • Fstab (JSON)
"content": {
    "source": {
      "url": "https://adobe.sharepoint.com/:f:/r/sites/adobecom/DA%20Docs/da-bacom",
      "type": "onedrive"
    },
    "overlay": {
      "type": "markup",
      "url": "https://content.da.live/adobecom/da-bacom/"
    }
  }