AEM Import Helper

A helpful companion for importing your site to AEM.

Features

• Run large import jobs with AEM Import as a Service (API docs).
• Bundle your import scripts.
• Import Crosswalk Content to your AEM author.

Install

Preferably as a dev dependency, but it can be used globally as well:

npm install @adobe/aem-import-helper --save-dev

Prerequisites For Importing

Set your environment variables (either in your shell profile or in a .env file):

export AEM_IMPORT_API_KEY=your-import-api-key

Add an npm script entry to your Edge Delivery project's package.json:

"import": "aem-import-helper import"

Usage

There are two types of imports, document based and AEM Authoring (xwalk) based. Please see the following sections for more information on each type.

Both import types require a file that contains a list of all URLs to import, one per line. Create a file (named 'urls.txt') and add the URLs to this file.

Document Based Imports

By default imports are doc based, simply provide the urls.txt file and the import.js file.

Execute the import via the following command:

npm run import -- --urls ./urls.txt --importjs tools/importer/import.js

The import.js file you provide will be automatically bundled and sent to the Import as a Service API, so referencing other local scripts (such as transformers) is supported. Why are we bundling the import.js file? See the section below on bundling multiple import scripts for more details.

Once complete, a pre-signed URL to download the import result (as a .zip archive) from S3 will be printed to the console that will contain the generated documents.

SharePoint upload

Optionally, the m365 CLI can be installed and configured to upload the import result to SharePoint. You will need your tenantId and the clientId of a Microsoft Entra application (on your SharePoint) to setup the CLI:

m365 setup
m365 login

Copy a link from SharePoint to the directory you'd like to upload to. This can be done from the SharePoint web UI, via the "Copy link" button. Your new link should take the following form: https://example.sharepoint.com/:f:/r/sites/example/Shared%20Documents/destination-directory

Once logged in to SharePoint with the m365 CLI, pass the SharePoint link as a param to the aem-import-helper:

npm run import -- --urls urls.txt --sharepointurl https://example.sharepoint.com/:f:/r/sites/example/Shared%20Documents/destination-directory

Once the import job is complete, the import result will be downloaded from S3, extracted, and each document will be uploaded to the specified SharePoint directory.

AEM Authoring (Crosswalk) Imports

To perform a Crosswalk import, you will need to provide additional parameters to the invocation. The models, filters, and definition files are required. You must also specify the import type as xwalk and provide the siteName and assetFolder.

npm run import -- \
  --urls urls.txt \
  --importjs tools/importer/import.js \
  --options '{     
    "type": "xwalk", 
    "data": { 
      "siteName": "xwalk", 
      "assetFolder": "xwalk" 
    }  
  }' \
  --models ./component-models.json \
  --filters ./component-filters.json \
  --definitions ./component-definition.json

Once complete, a pre-signed URL to download the import result (as a .zip archive) from S3 will be printed to the console that will contain the generated documents.

Importing content into AEM

Add the following npm script entries to your Edge Delivery project's package.json:

"aem-upload": "aem-import-helper aem upload"

aem-upload: Uploads content packages and associated assets to AEM.

Authenticating with AEM

To authenticate with AEM, it is suggested to obtain a development token for your AEM environment. To do this, visit the Developer Console in your AEM author environment via Cloud Manager. For details on accessing the Developer Console, see the AEM as a Cloud Service documentation and Developer Flow to learn how to generate an Access Token.

Once in the Developer Console:

1. Click on Integrations
2. Click on Local token
3. Click on Get Local Development Token

NOTE: that the development token is only valid for 24 hours.

You can store this token in a file on your local machine, or pass the token as a cli argument. If you choose to store the token in a file, create a file and simply paste the token into the file and save it.

--token </path/to/token.txt> OR <token>

Uploading content to AEM

Run the following command to upload content package (JCR pages) and associated assets to your AEM author:

npm run aem-upload -- \
  --token token.txt \
  --zip /path/to/zip.zip \
  --asset-mapping /path/to/asset-mapping.json \
  --target https://author-p1234-e1234.adobeaemcloud.com
  --keep
  --output /path/to/download/folder

Required:

• token: Absolute path to the file containing the token generated from the AEM author environment, or the token value.
• zip: Absolute path to the content package ZIP file containing the JCR pages, generated by the importer tool.
• asset-mapping: Absolute Path to the asset mapping file (asset-mapping.json), which contains mappings for asset urls and their corresponding JCR paths.
• target: The target AEM author environment URL.

Optional:

• output: Absolute path to the output folder where the downloaded assets will be stored. Default is aem-assets.
• keep: Keep the downloaded assets in the output folder after execution. Default is false.

Once the command is executed, the content package and associated assets are uploaded to your AEM author environment. The content package is installed and the assets are uploaded to the DAM.

Bundling Multiple Import Scripts

By creating a bundled version of your import script, it makes it compatible with the Import Service as all scripts are required to be in one js file.

Add a npm script entry to your Edge Delivery project's package.json:

"bundle": "aem-import-helper bundle"

Run the script:

npm run bundle -- --importjs tools/importer/import.js