Copy, move, import and export with the CLI tool

This page explains how to use the CLI tool to migrate (copy, move, import and export) content across repositories and hubs.

We've provided some examples of using CLI commands to migrate content items, content type schemas, settings and extensions. For details about each CLI tool command and its options see the CLI documentation on Github.

Considerations for migrating content

Before using the CLI tool to migrate content, it's good to understand how using or ignoring schema validation can affect the steps you use for content migration.

Using schema validation

Schema validation helps to maintain the integrity of your migrated content, and takes place by default when you import, copy or move content items using the CLI tool.

Validation will check content items against their associated content schema types and content types on the destination hub. Any content items that fail validation will not be migrated.

You should use schema validation when migrating content to your production environments where users are creating and editing content.

tip

You can use the CLI tool without schema validation when the Ignore schema validation flag is set on the destination hub.

The CLI tool allows you to run migration commands in any sequence you want, however to avoid schema validation issues we recommend importing content in the following sequence:

1. Hub settings
2. Extensions
3. Content type schemas
4. Content types
5. Content items
6. Search indexes
7. Events

Using the copy and move commands

The CLI tool copy and move commands let you export and import content items in a single step. To make sure content items are not imported before their associated content type schemas and types, always run the copy and move commands after you've imported their schema and content types.

Ignoring schema validation

There may be times when you want the CLI tool to ignore schema validation when migrating content items, for example when copying content to a testing or QA environment.

With the "Ignore schema validation" feature, you are able to bypass some validation issues caused by schema drift on the destination hub, such as:

• New required fields
• Validation on fields that were not present previously
• Change in attribute names

tip

If you decide to bypass schema validation, you can copy and move content items either before or after importing their associated content.

To ignore schema validation when migrating content items:

1. Ensure the destination hub is set to ignore schema validation. See How to set hub schema validation. Allowing schema validation to be ignored means that developers will be able to create content that doesn't pass schema validation rules on the hub.
2. Use the –-ignoreSchemaValidation flag with the following content item commands:
   • Import
   • Copy
   • Move
   • Archive
   • Unarchive

You can ignore schema validation when cleaning and cloning hubs

You can use the –-ignoreSchemaValidation flag when cleaning and cloning hubs.

Here's an example, of how "ignore schema validation" works. In the schema snippet shown below, we have two properties, headline and strapline:

{
  "type": "object",
  "properties": {
    "headline": { "type": "string" },
    "strapline": { "type": "string" }
  },
}

In this example you want to import content items created from this content type schema to a new hub. That hub has a different version of the content type schema, where the properties are both required fields:

{
  "type": "object",
  "properties": {
    "headline": { "type": "string" },
    "strapline": { "type": "string" }
  },
  "required": ["headline", "strapline"]
}

The CLI will detect if the content you are trying to migrate doesn't meet the destination schema validation and will not import the content, unless you use the --ignoreSchemaValidation flag to bypass the validation of the properties, for example:

dc-cli content-item copy --srcFolder <srcfolderID> --dstFolder <dstfolderID> --dstHubId <dstHubID>  --facet schema:https://schema-examples.com/tutorial-banner --ignoreSchemaValidation

Using the --ignoreSchemaValidation flag will allow the content to be imported. The content items can be opened in the Dynamic Content authoring experience, and where possible the authoring experience will highlight where content values don't pass validation. With this example, any migrated content items with values missing for the headline and strapline properties, can be opened and their values populated.

Scope of the ignore validation flag

Setting the --ignoreSchemaValidation flag allows content items to be created if the content item body does not conform to the current version of the content type schema on the hub to which the content item will be imported.

However, the --ignoreSchemaValidation flag only applies to the body of the content, and some additional validation will always be done that can cause content items to fail to be imported:

• The content item must be valid JSON.
• The content item must always link to a schema that exists on the destination hub.
• Delivery keys will always need to be validated for uniqueness. You will not be able to import a content item when another content item with the same delivery key already exists on the destination hub.
• Content links are always validated. If a content item links to other content items, then if the dependant items do not exist, the content will fail to import. This validation does not apply to content references.

Updating previously migrated items

When you use the CLI tool to import, copy or move content items, it generates or references a mapping file. The mapping file is used to determine whether migrated content items should be created as new items or whether they are existing items that need to be updated.

For example, if you export a content item (with ID 11111111-1111-1111-1111-111111111111) from one hub and then import it to another for the first time, a new content item will be created with a randomly generated UUID (for example, 22222222-2222-2222-2222-222222222222).

The mapping file will contain an array of every content item mapping identified for jobs using that mapping file. For example:

{
    "contentItems": [
        [
            "11111111-1111-1111-1111-111111111111",
            "22222222-2222-2222-2222-222222222222"
        ]
    ],
    "workflowStates": []
}

Read more about how to use mapping files.

Importing and exporting settings

You can export hub settings to a local directory using the settings command.

Commands:
  dc-cli settings export <dir>       Export Hub Settings
  dc-cli settings import <filePath>  Import Settings

dc-cli settings export /Users/yourUserName/myexport

This will create a file named hub-settings-5cf679244cedfd000109d2ef-ampproduct-doc.json in the "myexport" folder. The filename includes the hub id and hub name. The file includes visualization device settings, the schema validation setting, preview apps and workflow states.

These settings can then be imported into another hub.

Exporting extensions

Extensions (comprised of content field extensions, content editor extensions and dashboard extensions) can be developed using the Dynamic Content Extensions SDK, which is available in Github. In this example we're going to show how you would export all your extensions from the Dynamic Content App to a local folder.

To find the commands available for extensions, refer to the extension command on Github or type the following in your command line:

dc-cli extension --help

dc-cli extension

Extension

Commands:
  dc-cli extension export <dir>  Export Extensions
  dc-cli extension import <dir>  Import Extensions

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]

We're going to use the export command, so we'll get help for that:

dc-cli extension export --help

The export command can be used in several ways.

• To export all extensions from the specified hub you would use the hubID
• To export a particular extension you would use the ID of the extension you want. If no ID is given, all extensions will be exported. You can also use multiple IDs to export multiple extensions at the same time.
• To overwrite an extension without asking, you would use the --force command.

dc-cli extension export <dir>

Export Extensions

Positionals:
  dir  Output directory for the exported Extensions          [string] [required]

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]
  --id            The ID of an Extension to be exported.
                  If no --id option is given, all extensions for the hub are
                  exported.
                  A single --id option may be given to export a single
                  extension.
                  Multiple --id options may be given to export multiple
                  extensions at the same time.                          [string]
  -f, --force     Overwrite extensions without asking.                 [boolean]
  --logFile       Path to a log file to write to.
                                           [string] [default: (generated-value)]

In this example, we are exporting all extensions in our content hub to a local folder named 'exported_extensions'. To do this, we follow the below format for our command:

dc-cli extension export /Users/<yourUserName>/Documents/exported_extensions

This action exports all extensions to our specified local folder.

Importing extensions

To import extensions from a specified file location to a targeted Dynamic Content hub, you would follow a similar format to the above exporting process. First we ask for help:

dc-cli extension import --help

dc-cli extension import <dir>

Import Extensions

Positionals:
  dir  Directory containing Extensions                       [string] [required]

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]
  --logFile       Path to a log file to write to.
                                           [string] [default: (generated-value)]

From here on, you can import extensions from your local file location to your specified content hub using the following format for your command:

dc-cli extension import/yourDirectory/extension

Migrate schemas and content types

When copying content between hubs, you need to ensure that the content schemas and types that are used to create the content, are available on the destination hub. Otherwise the content would fail schema validation and you wouldn't be able to work with it on its destination hub. For example, if you try and copy content for which a content type does not exist, the CLI tool will display an error and the content will not be copied.

If your schema and content types reference any extensions, you should import the extensions before the schema and content types.

Ignoring schema validation

You can bypass schema validation when migrating content items. See Ignoring schema validation.

In this section we explain how to export content type schemas and content types from one hub and import them to another. You may also want to export content type schemas and content types for other reasons, such as to store them in a source control system.

Export schemas and content types

Exporting content type schemas

To export content type schemas use the export command.

dc-cli content-type-schema export --help

The options for the export command are shown in the help:

Export Content Type Schemas

Positionals:
  dir  Output directory for the exported Content Type Schema definitions
                                                             [string] [required]

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]
  --schemaId      The Schema ID of a Content Type Schema to be exported.
                  If no --schemaId option is given, all content type schemas for
                  the hub are exported.
                  A regex can be provided to select multiple type schemas with
                  similar or matching schema ids (eg /schema(0-9)\.json/).
                  A single --schemaId option may be given to export a single
                  content type schema.
                  Multiple --schemaId options may be given to export multiple
                  content type schemas at the same time.                [string]
  -f, --force     Overwrite content type schema without asking.        [boolean]
  --archived      If present, archived content type schemas will also be
                  considered.                                          [boolean]
  --logFile       Path to a log file to write to.
                                           [string] [default: (generated-value)]

By default the export command will export all unarchived schemas on a hub, but in this example we want to limit the export to those content type schemas used to create the content we want to copy: a carousel and carousel slides, and a simple banner:

dc-cli content-type-schema export exportedSchemas --schemaId "https://doc-example.com/carouselslide" --schemaId "https://doc-example.com/carousel" --schemaId "https://doc-example.com/simplebanner"

The schemas will be exported to the "exportedSchemas" folder.

Note, by default archived content type schemas are excluded from the export. If you want to include archived schemas, specify the --archived option.

Exporting content types

We also need to export the content types. Content types are registered from content type schemas and contain the settings for icons, cards and visualizations. Exporting our content types is very similar to the command we used for schemas:

dc-cli content-type export exportedContentTypes --schemaId "https://doc-example.com/carouselslide" --schemaId "https://doc-example.com/carousel" --schemaId "https://doc-example.com/simplebanner"

The content type schemas and content types are now ready to be imported into our destination hub.

Import schemas and content types

Importing content type schemas

To import content type schemas use the import command:

Import Content Type Schemas

Positionals:
  dir  Directory containing Content Type Schema definitions  [string] [required]

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]
  --logFile       Path to a log file to write to.
                                           [string] [default: (generated-value)]

You'll need to specify the hubId for your destination hub or include it in your configuration file. We'll include the hubId of the "Documentation" hub:

dc-cli content-type-schema import exportedSchemas --hubId <hubId>

The content type schemas exported to the "exportedSchemas" folder have now been imported into our destination hub.

Importing content types

Importing content types is very similar to the way we imported content type schemas. To import the content types from the "exportedContentTypes" folder use the following command:

dc-cli content-type import exportedContentTypes --hubId <hubId>

The content type schemas and content types have now been imported to the destination hub and registered.

The output from the command will show each of the imported content types, together with their IDs and schema IDs.

+--------------------------+------------------------------------------------------------------------------------------------------+------------+
| ID                       | Schema ID                                                                                            | Result     |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 6018318052faff00012b3bbd | https://doc-example.com/carousel                                                                     | CREATED |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 601832bbc9e77c00013a809a | https://doc-example.com/carouselslide                                                                | CREATED |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 601825c2c9e77c00013a7e21 | https://doc-example.com/simplebanner                                                                 | CREATED |

Assign content types to repositories

There's just one more step: you need to assign each of the content types to the repositories on which you want to use them to create or edit content.

You can associate a content type with a repository using the content-repository assign-content-type command:

dc-cli content-repository assign-content-type <id>

You will need the content type id and the id of the repository to assign it to:

Assign Content Type

Positionals:
  id  Content Repository ID                                  [string] [required]

Options:
  --version        Show version number                                 [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config         Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help           Show help                                           [boolean]
  --contentTypeId  content-type ID to assign                 [string] [required]
  --json           Render output as JSON              [boolean] [default: false]

The content id of the carousel is 6018318052faff00012b3bbd and we'll assign this to the "content" repository with the id of 5cf6792e4cedfd0001885b67 as follows:

dc-cli content-repository assign-content-type 5cf6792e4cedfd0001885b67 --contentTypeId 6018318052faff00012b3bbd

The content type is now assigned to the repository.

Exporting and importing content items

This example shows how to export all the content items in a folder called "Collections" in the "Content" repository on our "Documentation" hub to a local folder.

tip

The copy and move commands let you migrate content items in one step. If you are using schema validation, make sure to use copy and move after migrating any associated content type schemas and content types.

To find the commands available for content items, refer to content-item command on Github or type the following in your command line:

dc-cli content-item --help

We're going to use the export command, so we'll get help for that:

dc-cli content-item export --help

The export command can be used in several ways, to export all content from a specified repository, all content in a folder, created from a given schema id, or other options including matching the name with a string.

Export Content Items

Positionals:
  dir  Output directory for the exported Content Items       [string] [required]

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]
  --repoId        Export content from within a given repository. Directory
                  structure will start at the specified repository. Will
                  automatically export all contained folders.           [string]
  --folderId      Export content from within a given folder. Directory structure
                  will start at the specified folder. Can be used in addition to
                  repoId.                                               [string]
  --facet         Export content matching the given facets. Provide facets in
                  the format 'label:example name,locale:en-GB', spaces are
                  allowed between values. A regex can be provided for text
                  filters, surrounded with forward slashes. For more examples,
                  see the readme.                                       [string]
  --publish       When available, export the last published version of a content
                  item rather than its newest version.                 [boolean]
  --logFile       Path to a log file to write to.
                                           [string] [default: (generated-value)]

If you specify a repoId then every content item in that repository will be exported. But we want to export just the content in the "collections" folder, so we just need to specify the folderId which is unique within the hub.

To find the folder Id you can use the Dynamic Content Management API and use a tool such as Insomnia to list the folder in a repository. See the finding folder IDs section for more information.

In this example, the Id of the collections folder is 5f89ce13cff47e000168dc0f.

The list of repository folders shows that the "Collections" folder id is called "exportedCollection". Note that the client Id, secret and hub id will be read from the default configuration file, but you can also specify these credentials via the following command line.

dc-cli content-item export exportedCollection --folderId 5f89ce13cff47e000168dc0f

When the command runs, the following output is shown in the command line:

Retrieving content items, please wait.
Found 1 base folders.
Processing ...
Fetching additional folder: Collections
Scanning for dependancies.
Referenced content 'winter coats banner' added to the export.
Referenced content 'winter dresses banner' added to the export.
Referenced content 'winter hats banner' added to the export.
Saving content items.
exportedCollection/Summer sale carousel.json
exportedCollection/Winter collection slider.json
exportedCollection/Summer collection sale- carousel.json
exportedCollection/Summer collection sale- dresses.json
exportedCollection/Summer collection- jeans.json
exportedCollection/Summer collection sale- group image.json
exportedCollection/Summer collection sale- hats.json
exportedCollection/Summer collection sale banner.json
exportedCollection/_dependancies/winter coats banner.json
exportedCollection/_dependancies/winter dresses banner.json
exportedCollection/_dependancies/winter hats banner.json
Log written to "/Users/yourUserName/.amplience/logs/item-export-1611927735061.log".

All of the content items in the "Collection" folder are exported, together with any content that is referenced by these items. Some of the content items are carousels, so the items they reference are exported as well, even though they're not in the "Collections" folder.

We could then import these items to another hub or a different repository on the same hub.

Copying content items

The CLI tool includes the following commands for working with content:

Content Item

Commands:
  dc-cli content-item archive [id]    Archive Content Items
  dc-cli content-item copy            Copy content items. The active account and
                                      hub are the source for the copy.
  dc-cli content-item export <dir>    Export Content Items
  dc-cli content-item import <dir>    Import content items
  dc-cli content-item move            Move content items. The active account and
                                      hub are the source for the move.
  dc-cli content-item tree <dir>      Print a content dependency tree from
                                      content in the given folder.
  dc-cli content-item unarchive [id]  Unarchive Content Items

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]

Schema validation for copy and move

To minimize schema validation issues, the copy and move commands should be run after you have exported and imported the associated schema and content types. See Using schema validation.

The following example shows how to copy content between two hubs. You can also copy content from one repository to another in the same hub.

To begin, we want to copy the content to the destination without removing it from the source hub, so we'll use copy:

Copy content items. The active account and hub are the source for the copy.

Options:
  --version         Show version number                                [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config          Path to JSON config file
            [string] [default: "/Users/username/.amplience/dc-cli-config.json"]
  --help            Show help                                          [boolean]
  --revertLog       Path to a log file to revert a copy for. This will archive
                    the most recently copied resources, and revert updated ones.
                                                                        [string]
  --srcRepo         Copy content from within a given repository. Directory
                    structure will start at the specified repository. Will
                    automatically export all contained folders.         [string]
  --srcFolder       Copy content from within a given folder. Directory structure
                    will start at the specified folder. Can be used in addition
                    to repoId.                                          [string]
  --dstRepo         Copy matching the given repository to the source base
                    directory, by ID. Folder structure will be followed and
                    replicated from there.                              [string]
  --dstFolder       Copy matching the given folder to the source base directory,
                    by ID. Folder structure will be followed and replicated from
                    there.                                              [string]
  --dstHubId        Destination hub ID. If not specified, it will be the same as
                    the source.                                         [string]
  --dstClientId     Destination account's client ID. If not specified, it will
                    be the same as the source.                          [string]
  --dstSecret       Destination account's secret. Must be used alongside
                    dstClientId.                                        [string]
  --facet           Copy content matching the given facets. Provide facets in
                    the format 'label:example name,locale:en-GB', spaces are
                    allowed between values. A regex can be provided for text
                    filters, surrounded with forward slashes. For more examples,
                    see the readme.                                     [string]
  --mapFile         Mapping file to use when updating content that already
                    exists. Updated with any new mappings that are generated. If
                    not present, will be created.                       [string]
  -f, --force       Overwrite content, create and assign content types, and
                    ignore content with missing types/references without asking.
                                                                       [boolean]
  -v, --validate    Only recreate folder structure - content is validated but
                    not imported.                                      [boolean]
  --skipIncomplete  Skip any content item that has one or more missing
                    dependancy.                                        [boolean]
  --lastPublish     When available, export the last published version of a
                    content item rather than its newest version.       [boolean]
  --publish         Publish any content items that either made a new version on
                    import, or were published more recently in the JSON.
                                                                       [boolean]
  --batchPublish    Batch publish requests up to the rate limit. (35/min)
                                                                       [boolean]
  --republish       Republish content items regardless of whether the import
                    changed them or not. (--publish not required)      [boolean]
  --excludeKeys     Exclude delivery keys when importing content items.[boolean]
  --media           Detect and rewrite media links to match assets in the target
                    account's DAM. Your client must have DAM permissions
                    configured.                                        [boolean]
  --logFile         Path to a log file to write to.
                                           [string] [default: (generated-value)]

The source folder is called "CLI tool content" and has an id of 648831b9147e044acb973583 in the "Amp Doc Examples" hub. To find the folder Id use the Content Management API, as explained in Finding folder Ids.

This content will be copied into the "CLI tester folder" in the "Amp Docs Hub" that has an id of 64a3e079c5d8d7697391414a.

We also want to publish any content item that was published on the source hub so we'll use the "--publish" option.

The copy command is as shown below. The destination hub Id must be specified and we assume that the clientId, secret and source hub are specified in the configuration file:

dc-cli content-item copy --srcFolder <srcfolderId> --dstFolder <dstfolderId> --dstHubId <dstHubId> --publish

If the clientID, secret and source hub are not specified in the configuration file, you will need to specify them in the query, as shown below:

dc-cli content-item copy  --srcFolder <srcfolderId>  --clientId <clientId>  --clientSecret <clientSecret> --dstClientId <dstclientId> --dstSecret <dstclientSecret> --dstFolder <dstfolderId> --dstHubId <dstHubId> --publish

After running the copy command the following output is shown in the command line.

=== Exporting from source... ===
Retrieving content items, please wait.
Found 1 base folders.
Processing ...
Fetching additional folder: CLI tool content
Scanning for dependancies.
Saving content items.
/Users/kojogbede/.amplience/copy-1688513127224/CLI tool text.json
/Users/kojogbede/.amplience/copy-1688513127224/CLI tool image.json
/Users/kojogbede/.amplience/copy-1688513127224/CLI tool author.json
/Users/kojogbede/.amplience/copy-1688513127224/Autumn banner.json
/Users/kojogbede/.amplience/copy-1688513127224/CLI tool banner.json
=== Importing to destination... ===
Creating new mapping file at '/Users/username/.amplience/imports/folder-64a3e079c5d8d7697391414a.json'.
Scanning structure and content in '/Users/username/.amplience/copy-1688513127224/' for repository 'Content'...
Done. Validating content...
Importing 5 content items...
Creating circular dependants.
Resolving circular dependants.
Publishing 5 items. (0 children included)
Started publish for Autumn banner.
Started publish for CLI tool text.
Started publish for CLI tool author.
Started publish for CLI tool banner.
Started publish for CLI tool image.
Waiting for all publishes to complete...
Finished publishing, with 0 failed publishes total.
Done!
=== Done! ===

The items have been copied to the "CLI tester folder" in the "Amp Docs Hub" and have all been published.

Copying items between different accounts

The --media command allows you to copy between hubs on different content hub accounts. Before using --media, make sure there are matching files existing on both content hub accounts. To do this, you can import all the same assets into your destination hub either via an external process like an ftp upload, or you can manually upload them using Content Hub.

There are some useful additional commands available when you copy, move or import content items from one location to another, for example --lastPublish.

Revert logs: undoing a copy or move

When you run a dc-cli content-item copy or dc-cli content-item move command, a log file is created containing a list of the content items that were copied or moved. This file is stored locally in the ".amplience/logs" folder. The log file can be specified in the --revertLog parameter to undo a copy or move, archiving the content items on the destination.

 --revertLog       Path to a log file to revert a copy for. This will archive
                    the most recently copied resources, and revert updated ones.

You can revert the folder copy example by specifying the log file generated from the original copy:

dc-cli content-item copy --srcFolder <srcfolderID> --dstFolder <dstfolderID> --dstHubId <dstHubID> --publish --config cli-config-2.json --revertLog  "/Users/userName/.amplience/logs/item-copy-1612203317991.log"

The output generated will be as follows:

Archiving Blue dress slide.
Archiving Get ready for summer.
Archiving Sunglasses slide.
Archiving Hat slide.
Archiving Bright colours slide.
Archiving Summer carousel.
Done!
Log written to "/Users/userName/.amplience/logs/item-copy-1612481700095.log".

The items that were copied to the destination are now archived.

Mapping files: updating migrated content

A mapping file is generated when you run a copy, move, import or clone command. This file is created in the ".amplience/imports" folder and contains the content ids of the content items on the source and destination. The content ids for the source and destination are presented in JSON format as an array of arrays. An example mapping file is shown below:

{
   "contentItems":[
      [
         "91bb8048-2553-48a2-98a3-2ea6da1f9bb5",
         "4d81e399-2415-4d50-8049-164efb7360a5"
      ],
      [
         "c397ad5b-d005-417b-865f-993c19e8a329",
         "42b7414d-f098-4c47-8b16-4ed9b6261724"
      ],
      [
         "12ba5d26-98b6-4bc4-9616-822fa5c26520",
         "656848b2-3eeb-4b51-aeae-34e1fbee8f9a"
      ],
      [
         "f84be933-fba1-4c3a-85ae-5251ab8a85a3",
         "24b46785-cc72-4003-aeb8-2a27b98bacb1"
      ],
      [
         "0c8b4c5b-4220-4425-920e-d28f5f6a2885",
         "018a826e-31d0-4677-a9a5-7e097be8db38"
      ],
      [
         "8f0a5d52-b699-474a-a9cc-2d80253e9ad8",
         "6757c1ab-6458-4ece-995e-9819a5cce7ff"
      ]
   ]
}

The CLI tool will attempt to load a mapping file when it is run. For example if you are copying from one folder to another, by default it will look for a mapping file labeled with the source folder id in the .amplience/imports directory. If a mapping file cannot be found, then new content items will be created in the destination.

Mapping files for settings

Mapping files are generated for some hub settings, such as workflow states. See Importing and exporting settings.

Generating mapping files

Generating mapping files when migrating across multiple hubs

When migrating content between hubs, by default the CLI tool will try to create the migrated content based on the hub ID provided. Due to this being considered new content, a different mapping file will be created for the content copied to each hub.

In the copying content items example a mapping file is generated when we copy content in a specific folder from the source folder "CLI tool content" in the "Amp Doc Examples" hub into the "CLI tester folder" in the "Amp Docs Hub".

{
   "contentItems":[
      [
         "91bb8048-2553-48a2-98a3-2ea6da1f9bb5",
         "4d81e399-2415-4d50-8049-164efb7360a5"
      ],
      [
         "c397ad5b-d005-417b-865f-993c19e8a329",
         "42b7414d-f098-4c47-8b16-4ed9b6261724"
      ],
      [
         "12ba5d26-98b6-4bc4-9616-822fa5c26520",
         "656848b2-3eeb-4b51-aeae-34e1fbee8f9a"
      ],
      [
         "f84be933-fba1-4c3a-85ae-5251ab8a85a3",
         "24b46785-cc72-4003-aeb8-2a27b98bacb1"
      ],
      [
         "0c8b4c5b-4220-4425-920e-d28f5f6a2885",
         "018a826e-31d0-4677-a9a5-7e097be8db38"
      ],
      [
         "8f0a5d52-b699-474a-a9cc-2d80253e9ad8",
         "6757c1ab-6458-4ece-995e-9819a5cce7ff"
      ]
   ]
}

If we were to copy our content items across multiple hubs, then mapping files would be created for each destination hub. ​

Generating mapping files when migrating within a single hub

Copying content within a single hub works in a similar way to copying content across different hubs. You need the folder id of the folder you'd like to copy your content to, as well as the hub id.

If you don't have your credentials saved in a config file, you will need to include the client id and client secret associated with your hub in the command.

A new mapping file will be generated by default when the content is copied into the new folder as this is considered new content, despite being in the same hub. If you were to copy into multiple folders, as explained above, multiple mapping files would be generated. ​

Using existing mapping files

 --mapFile         Mapping file to use when updating content that already
                   exists. Updated with any new mappings that are generated. If
                   not present, will be created.                       [string]

​ If you want to include your own mapping file while performing an import, clone or copy, the command would be:

--mapFile [path to mapping file document]

​Using —-mapFile to include an existing mapping file is recommended, as this avoids any duplicate content being made.

Example: Updating content with an existing mapping file

When you run a copy, clone or import command and an existing mapping file is used, you can choose whether to update existing content items or not.

In the example below, we are asked whether we would like to update some items that already exist in the mapping file, when we repeat the same copy command as we used in the folder copy example.

We are given this option because a mapping file already exists that includes some of the content items we'd like to import. This means that we can choose to either update or leave them as they are:

=== Exporting from source... ===
Retrieving content items, please wait.
Found 1 base folders.
Processing ...
Fetching additional folder: CLI tool content
Scanning for dependancies.
Saving content items.
/Users/kojogbede/.amplience/copy-1688514570584/CLI tool text.json
/Users/kojogbede/.amplience/copy-1688514570584/CLI tool image.json
/Users/kojogbede/.amplience/copy-1688514570584/CLI tool author.json
/Users/kojogbede/.amplience/copy-1688514570584/Autumn banner.json
/Users/kojogbede/.amplience/copy-1688514570584/CLI tool banner.json
=== Importing to destination... ===
Existing mapping loaded from '/Users/kojogbede/.amplience/imports/folder-64a3e079c5d8d7697391414a.json', changes will be saved back to it.
Scanning structure and content in '/Users/kojogbede/.amplience/copy-1688514570584/' for repository 'Content'...
Done. Validating content...
5 of the items being imported already exist in the mapping. Would you like to update these content items instead of skipping them? (y/n) y
Found 1 dependancy levels in 5 items, 0 referencing a circular dependancy.
Importing 5 content items...
Creating circular dependants.
Resolving circular dependants.
Publishing 5 items. (0 children included)
Started publish for Autumn banner.
Started publish for CLI tool text.
Started publish for CLI tool author.
Started publish for CLI tool banner.
Started publish for CLI tool image.
Waiting for all publishes to complete...
Finished publishing, with 0 failed publishes total.
Done!
=== Done! ===

Workflow status mapping files

Workflow states (also referred to as content statuses) are tags that you can assign to content items. You can set them up from the status menu in your hub settings and apply one workflow state to a content item at a time.

note

Currently you cannot delete content statuses once you create them. You can only re-label them.

A workflow state is identified by its id. When you export settings from one hub and import to another (without specifying an existing mapping file), ids will be generated for each of the workflow states exported from the source hub. A mapping file will be created containing the workflow states exported from the source hub, and the ids of the corresponding workflow states imported to the destination hub.

Below is an example of a mapping file with workflow state ids for a source and destination hub:

{
  "contentItems": [],
  "workflowStates": [
    [
      "64b6553fa880f143e02bd7b3",
      "64c79bc468e3416098a3d604"
    ],
    [
      "64b655332348f70ed5c9468c",
      "64c79bc4c1f4a12c87d1789f"
    ],
    [
      "64b655575441c26a32aef1ee",
      "64c79bc463847d45a4d145b7"
    ]
  ],
  "events": [],
  "editions": [],
  "slots": [],
  "snapshots": []
}

When you import these settings into another hub, the workflow state from the source hub is mapped to the corresponding workflow state in the destination hub. If you import settings again using an existing mapping file, then you can update existing workflow states and prevent duplication. This is particularly useful because workflow states cannot be deleted from a hub.

Finding folder Ids

To retrieve the folder Id you will need to set your grant type to client credentials, and have the following information on hand:

• The Id of your chosen repository
• Client Id
• Client Secret
• Request URL

To get the folder Id, use the List folders API request in the Content Management API:

GET https://api.amplience.net/v2/content/content-repositories/{contentRepositoryId}/folders

In the example shown below, the "Content" repository has the Id 5cf6792e4cedfd0001885b67.

From the list of folders in the repositories we can see that the Id for the "Collections" folder is 5f89ce13cff47e000168dc0f.

Related pages

Dynamic Content CLI tool on GitHub