diff --git a/HOW_TO_USE.md b/HOW_TO_USE.md index 7a9c29b2..6c9218be 100644 --- a/HOW_TO_USE.md +++ b/HOW_TO_USE.md @@ -45,3 +45,4 @@ You can use regex values on string fields when filtering content. They cannot be * `dc-cli --help` * `README.md` * https://docs.amplience.net/ + diff --git a/README.md b/README.md index 2b5a7f1e..331d7d49 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,26 @@ Command line interface for Amplience Dynamic Content service. **dc-cli** is a command line interface application for Amplience Dynamic Content management APIs. -Run `dc-cli` to get a list of available commands +Run `dc-cli --help` to get a list of available commands. + + + +- [Installation](#installation) +- [Configuration](#configuration) + - [Options](#options) +- [Command categories](#command-categories) + - [content-type-schema](#content-type-schema) + - [content-type](#content-type) + - [content-item](#content-item) + - [extension](#extension) + - [search-index](#search-index) + - [content-repository](#content-repository) + - [settings](#settings) + - [hub](#hub) +- [Building the CLI](#building-the-cli) +- [Required permissions](#required-permissions) + + ## Installation @@ -23,45 +42,128 @@ Or you can download the executable for your operating system on the [releases pa **dc-cli** requires a valid set of Amplience client credentials (`--clientId` & `--clientSecret`) and hub ID (`--hubId`) to operate. These parameters must be set using the command `dc-cli configure --clientId --clientSecret --hubId ` before using the CLI. -Once the tool has been configured the individual parameters can be overwritten by supplying them when running any of the commands, -e.g `dc-cli --hubId `. +Some commands (`content-item copy`, `content-item move`, & `hub-clone`) enable the export and import of content with a single command. These take additional options for the client credentials (`--dstClientId` & `--dstSecret`) and hub ID (`--dstHubId`) of a distinct Dynamic Content hub. If no destination options are provided, the destination for these commands will be the same as the source. + +Once the tool has been configured the individual parameters can be overwritten by supplying them when running any of the commands, e.g `dc-cli --hubId `. By default the configuration is saved to a file in the directory `/.amplience/`, this can be overridden using the `--config` option. -See `dc-cli configure --help` for more information. +### Options + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | +| --dstHubId | [string] | Destination hub ID. If not specified, it will be the same as the source. | +| --dstClientId | [string] | Destination account's client ID. If not specified, it will be the same as the source. | +| --dstSecret | [string] | Destination account's secret. Must be used alongside dstClientId. | + +#### Examples + +##### Create/Update configuration file for single hub + +`dc-cli configure --clientId foo --clientId bar --hubId baz` + +##### Create/Update configuration file for two-hub usage (copy/move/clone) + +`dc-cli configure --clientId foo --clientId bar --hubId baz --dstClientId qux --dstSecret quux --dstHubId quuz` + +## Command categories + +### content-type-schema + +This category includes interactions with content type schemas. + +These commands can be used to retrieve information on one or more schemas, create new schemas, export and import schemas from an individual hub, as well as archiving and unarchiving schemas. + +[View commands for **content-type-schema**](docs/CONTENT-TYPE-SCHEMA.md) + +### content-type + +This category includes interactions with content types. + +These commands can be used to retrieve information on one or more types, register new types or update existing ones, export and import types from an individual hub, as well as archiving and unarchiving types. + +Before importing content types you must ensure that a valid [content type schema](#content-type-schema) exists in the destination hub for each type. + +[View commands for **content-type**](docs/CONTENT-TYPE.md) + +### content-item + +This category includes interactions with content items. -## Usage +These commands can be used to export and import content from an individual hub, copy and move items between hubs, as well as archiving and unarchiving content. -- [How to use the CLI](HOW_TO_USE.md) -- [Export using the CLI](EXPORT_USAGE.md) -- [Import using the CLI](IMPORT_USAGE.md) +Before importing, copying, or moving content you must ensure that a valid [content type](#content-type) exists in the destination hub for each content item. + +[View commands for **content-item**](docs/CONTENT-ITEM.md) + +### extension + +This category includes interactions with Dynamic Content's UI Extensions, and can be used to export and import extensions from an individual hub. + +[View commands for **extension**](docs/EXTENSION.md) + +### search-index + +This category includes interactions with Algolia search indexes for Dynamic Content, and can be used to export and import indexes from an individual hub. + +[View commands for **search-index**](docs/SEARCH-INDEX.md) + +### content-repository + +This category includes interactions with Dynamic Content's repositories. + +These commands can be used to get details for a specific repository, list multiple repositories, or assign or unassign content types from a repository. + +[View commands for **content-repository**](docs/CONTENT-REPOSITORY.md) + +### settings + +This category includes interactions with the supporting properties of a Dynamic Content hub. These commands can be used to export and import a hub's breakpoint settings for visualization, preview applications, workflow states, and locales. + +[View commands for **settings**](docs/SETTINGS.md) + +### hub + +This category includes interactions with Dynamic Content's hubs in their entirety. + +These commands can be used to copy a hub's settings and content in their entirety to another hub, or to archive all parts of a hub which can be archived. + +[View commands for **hub**](docs/HUB.md) ## Building the CLI We have included some NPM scripts to help create various installations of the CLI. -- [Guide to building the CLI](BUILDING_THE_CLI.md) +- [Guide to building the CLI](docs/BUILDING_THE_CLI.md) ## Required permissions Outlined below are the detailed permissions required to run each command of the CLI. To request an API key to run the CLI, please contact Amplience support. -| Command | Required ACL(s) | Required Functional Permission(s) | -| ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `configure` | Hub - READ | | -| `content-repositories get ` | Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:READ | -| `content-repositories list` | Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:READ | -| `content-repositories assign-content-type ` | ContentRepository - EDIT
Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:EDIT | -| `content-repositories unassign-content-type ` | ContentRepository - EDIT
Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:EDIT | -| `content-type get ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | -| `content-type list` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | -| `content-type register` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE | -| `content-type sync ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | -| `content-type update ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | +| Command | Required ACL(s) | Required Functional Permission(s) | +| ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ | +| `configure` | Hub - READ | | +| `content-repositories get ` | Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:READ | +| `content-repositories list` | Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:READ | +| `content-repositories assign-content-type ` | ContentRepository - EDIT
Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:EDIT | +| `content-repositories unassign-content-type ` | ContentRepository - EDIT
Hub - READ | CONTENT:FUNCTIONAL:REPOSITORY:EDIT | +| `content-type get ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | +| `content-type list` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | +| `content-type register` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE | +| `content-type sync ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | +| `content-type update ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | | `content-type import ` | ContentRepository - EDIT
Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE
CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | -| `content-type export ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | -| `content-type-schema create` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE | -| `content-type-schema get ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | -| `content-type-schema list` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | -| `content-type-schema update ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | +| `content-type export ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | +| `content-type-schema create` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE | +| `content-type-schema get ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | +| `content-type-schema list` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ | +| `content-type-schema update ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | | `content-type-schema import ` | Hub - READ | CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE
CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT | + diff --git a/BUILDING_THE_CLI.md b/docs/BUILDING_THE_CLI.md similarity index 96% rename from BUILDING_THE_CLI.md rename to docs/BUILDING_THE_CLI.md index 9a75476d..1a0df00c 100644 --- a/BUILDING_THE_CLI.md +++ b/docs/BUILDING_THE_CLI.md @@ -6,6 +6,8 @@ We have included some NPM scripts to help create various installations of the CL - [Package the CLI into executables](#building-executables) - [Link the CLI with NPM for local development](#npm-link) +Alternatively, return to [README.md](../README.md) for more information on the DC CLI. + ### Compiling TypeScript to Javascript diff --git a/docs/CONTENT-ITEM.md b/docs/CONTENT-ITEM.md new file mode 100644 index 00000000..ab47861f --- /dev/null +++ b/docs/CONTENT-ITEM.md @@ -0,0 +1,372 @@ +# content-item + +## Description + +The **content-item** command category includes a number of interactions with content items. + +These commands can be used to export and import content from an individual hub, copy and move items between hubs, as well as archiving and unarchiving content. + +Before importing, copying, or moving content you must ensure that a valid [content type](#CONTENT-TYPE.md) exists in the destination hub for each content item. + +Run `dc-cli content-item --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Useful Information](#useful-information) + - [Mapping files](#mapping-files) + - [Facets](#facets) + - [Media-link rewriting](#media-link-rewriting) +- [Commands](#commands) + - [export](#export) + - [import](#import) + - [copy](#copy) + - [move](#move) + - [archive](#archive) + - [unarchive](#unarchive) + - [tree](#tree) + + + +## Common Options + +The following options are available for all **content-item** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | + +## Useful Information + +### Mapping files + +When importing content with the DC CLI, this creates or references a mapping file to determine whether the imported content item should be created as new, or if an existing one within the Dynamic Content platform should be updated. + +For example exporting a content item (eg `11111111-1111-1111-1111-111111111111`) from one hub then importing it to another for the first time will create a new content item with a randomly generated UUID (eg `22222222-2222-2222-2222-222222222222`). + +To instruct the DC CLI on which content item to update with future actions, a mapping between the source and destination is stored in a mapping file. This mapping file will contain an array of every content item mapping identified for jobs using that mapping file. Using the previous examples: + +``` +{ + "contentItems": [ + [ + "11111111-1111-1111-1111-111111111111", + "22222222-2222-2222-2222-222222222222" + ] + ], + "workflowStates": [] +} +``` + +If no mapping file is specified (with the `--mapFile` argument) then a default one will be created, using the destination's resource type (hub, repository, folder) and its ID, and stored within a default location in your user directory. For example: + +* Mac: `~/.amplience/imports/hub-111111111111111111111111.json` +* Windows: `%UserProfile%\.amplience\imports\hub-111111111111111111111111.json` + +If a mapping file does not exist at the point of import, then any imported content items will be created as new, and a new mapping file will be created. If a mapping file exists, and was provided with the `--mapFile` argument, then any items found within the mapping file will be updated. Any content items not contained in the mapping file will will be created as new, and will then be added to the mapping file. + +### Facets + +The content item export, copy, move, archive and unarchive commands allow the user to provide a facet string to filter the content that the commands work on. Multiple of these can be applied at a time, and you can even match on a regular expressions (RegEx) string. Note that you will need to surround your facet in quotes if it contains a space, which will change how backslash escaping works. + +- `name`: Filter on content item label. Example: `--facet "name:exact name match"` +- `schema`: Filter on schema ids. Example: `--facet schema:http://example.com/schema.json` +- `locale`: Filter on content item locale. Example: `--facet locale:en-GB` +- `lastModifiedDate`: Filter on last modified date. Example: `--facet "lastModifiedDate:Last 7 days"` + +Multiple facets can be applied at once when separated by a comma. Example: +`--facet "schema:http://example.com/schema.json, name:/name regex/"` + +Commas can be escaped with a backslash, if they are used in your values. The whitespace after a comma is optional. + +#### Preset date ranges + +The preset date ranges are the same as DC provides: + +- `Last 7 days` +- `Last 14 days` +- `Last 30 days` +- `Last 60 days` +- `Over 60 days` + +#### Regular expressions + +You can use regex values on string fields when filtering content. They cannot be used on date ranges. Regex are surronded by two forward slashes: +`--facet "name:/ends with this$/"` + +### Media-link rewriting + +The DC CLI is capable of importing or copying content into a Dynamic Content hub which resides on a distinct Content Hub account to the source by using the `--media` option with the import, copy, and move commands. This will update the `endpoint`, `id`, and `defaultHost` values for any `media-link` objects to reflect the endpoint of the destination hub's account, if an asset with a matching name exists in the destination account. + +This functionality requires additional Content Hub-specific permissions granting to your DC CLI client in order to grant it visibility of the destination account's media assets (`DAM:ASSET STORE:ASSET_STORE_NAME`). + +## Commands + +### export + +Exports content items from the targeted Dynamic Content hub into the specified filesystem location. + +``` +dc-cli content-item export +``` + +#### Options + +| Option Name | Type | Description | +| ------------------------------ | ------------------------------------------ | ------------------------------------------------------------ | +| --repoId | [string] | Export content from within a given repository.
Directory structure will start at the specified repository.
Will automatically export all contained folders. | +| --folderId | [string] | Export content from within a given folder.
Directory structure will start at the specified folder.
Can be used in addition to repoId. | +| --facet | [string] | 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 [facets](#FACETS). | +| --schemaId
*(Deprecated)* | [string] | Export content with a given or matching Schema ID.
A regex can be provided, surrounded with forward slashes.
Can be used in combination with other filters.

Deprecated by the [--facet](#facets) option. | +| --name
*(Deprecated)* | [string] | Export content with a given or matching Name.
A regex can be provided, surrounded with forward slashes.
Can be used in combination with other filters.

Deprecated by the [--facet](#facets) option. | +| --publish | [boolean] | When available, export the last published version of a content item rather than its newest version. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Export all content items from a Hub + +`dc-cli content-item export ./myDirectory/content` + +##### Export all content items from a specific repository + +`dc-cli content-item export ./myDirectory/content --repoId 111111111111111111111111` + +##### Export all content items with the "banner" schema type, with "Christmas" in their name + +`dc-cli content-item export ./myDirectory/content --facet "schema:/.+banner.json$/,name:/Christmas/"` + +### import + +Imports content items from the specified filesystem location to the targeted Dynamic Content hub. + +Before importing content you must ensure that a valid [content type](#CONTENT-TYPE.md) exists in the destination hub for each content item. It is also recommended that you check that any content items to be imported are still valid if any changes have been made to your content type schemas. Please see [guidelines for making changes to a content type schema](https://amplience.com/docs/integration/refreshingcontenttypes.html#guidelines) for more information. + +``` +dc-cli content-item import +``` + +#### Options + +| Option Name | Type | Description | +| ------------------ | ------------------------------------------ | ------------------------------------------------------------ | +| --baseRepo | [string] | Import matching the given repository to the import base directory, by ID.
Folder structure will be followed and replicated from there. | +| --baseFolder | [string] | Import matching the given folder to the import base directory, by ID.
Folder structure will be followed and replicated from there. | +| --mapFile | [string] | Mapping file to use when updating content that already exists.
Updated with any new mappings that are generated. If not present, will be created.
For more information, see [mapping files](#MAPPING-FILES). | +| -f
--force | [boolean] | Overwrite content, create and assign content types, and ignore content with missing types/references without asking. | +| -v
--validate | [boolean] | Only recreate folder structure - content is validated but not imported. | +| --skipIncomplete | [boolean] | Skip any content items that has one or more missing dependancy. | +| --publish | [boolean] | Publish any content items that have an existing publish status in their JSON. | +| --republish | [boolean] | Republish content items regardless of whether the import changed them or not.
(--publish not required) | +| --excludeKeys | [boolean] | Exclude delivery keys when importing content items. | +| --media | [boolean] | Detect and rewrite media links to match assets in the target account's Content Hub. Your client must have Content Hub permissions configured. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Import content from the filesystem + +`dc-cli content-item import ./myDirectory/content` + +##### Specify a mapping file when importing + +`dc-cli content-item import ./myDirectory/content --mapFile ./myDirectory/mappingFile.json` + +##### Import content into a specific repository + +`dc-cli content-item import ./myDirectory/content --baseRepo 111111111111111111111111` + +### copy + +Exports content items from the source hub and imports it into the destination hub with a single command. + +Before copying content you must ensure that a valid [content type](#CONTENT-TYPE.md) exists in the destination hub for each content item. + +``` +dc-cli content-item copy +``` + +#### Options + +| Option Name | Type | Description | +| ------------------ | ------------------------------------------ | ------------------------------------------------------------ | +| --revertLog | [string] | Path to a log file to revert a copy for.
This will archive the most recently copied resources, and revert updated ones. | +| --srcRepo | [string] | Copy content from within a given repository.
Directory structure will start at the specified repository.
Will automatically export all contained folders. | +| --srcFolder | [string] | Copy content from within a given folder.
Directory structure will start at the specified folder.
Can be used in addition to repoId. | +| --dstRepo | [string] | Copy matching the given repository to the source base directory, by ID.
Folder structure will be followed and replicated from there. | +| --dstFolder | [string] | Copy matching the given folder to the source base directory, by ID.
Folder structure will be followed and replicated from there. | +| --dstHubId | [string] | Destination hub ID.
If not specified, it will be the same as the source. | +| --dstClientId | [string] | Destination account's client ID.
If not specified, it will be the same as the source. | +| --dstSecret | [string] | Destination account's secret.
Must be used alongside dstClientId. | +| --facet | [string] | 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 [facets](#FACETS). | +| --mapFile | [string] | Mapping file to use when updating content that already exists.
Updated with any new mappings that are generated. If not present, will be created.
For more information, see [mapping files](#MAPPING-FILES). | +| -f
--force | [boolean] | Overwrite content, create and assign content types, and ignore content with missing types/references without asking. | +| -v
--validate | [boolean] | Only recreate folder structure - content is validated but not imported. | +| --skipIncomplete | [boolean] | Skip any content item that has one or more missing dependancy. | +| --lastPublish | [boolean] | When available, export the last published version of a content item rather than its newest version. | +| --publish | [boolean] | Publish any content items that have an existing publish status in their JSON. | +| --republish | [boolean] | Republish content items regardless of whether the import changed them or not.
(--publish not required) | +| --excludeKeys | [boolean] | Exclude delivery keys when importing content items. | +| --media | [boolean] | Detect and rewrite media links to match assets in the target account's DAM.
Your client must have DAM permissions configured. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Copy content with destination credentials in config file + +`dc-cli content-item copy ./myDirectory/content` + +##### Specify a mapping file when copying + +`dc-cli content-item copy ./myDirectory/content --mapFile ./myDirectory/mappingFile.json` + +##### Copy content wihout destination credentials in config file + +`dc-cli content-item copy ./myDirectory/content --dstClientId foo --dstSecret bar --dstHubId baz` + +### move + +Exports content items from the source hub and imports it into the destination hub with a single command. Content items in the source hub are archived after the successful move. + +Before moving content you must ensure that a valid [content type](#CONTENT-TYPE.md) exists in the destination hub for each content item. + +``` +dc-cli content-item move +``` + +#### Options + +| Option Name | Type | Description | +| ------------------ | ------------------------------------------ | ------------------------------------------------------------ | +| --revertLog | [string] | Path to a log file to revert a copy for.
This will archive the most recently copied resources, and revert updated ones. | +| --srcRepo | [string] | Copy content from within a given repository.
Directory structure will start at the specified repository.
Will automatically export all contained folders. | +| --srcFolder | [string] | Copy content from within a given folder.
Directory structure will start at the specified folder.
Can be used in addition to repoId. | +| --dstRepo | [string] | Copy matching the given repository to the source base directory, by ID.
Folder structure will be followed and replicated from there. | +| --dstFolder | [string] | Copy matching the given folder to the source base directory, by ID.
Folder structure will be followed and replicated from there. | +| --dstHubId | [string] | Destination hub ID.
If not specified, it will be the same as the source. | +| --dstClientId | [string] | Destination account's client ID.
If not specified, it will be the same as the source. | +| --dstSecret | [string] | Destination account's secret.
Must be used alongside dstClientId. | +| --facet | [string] | 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 [facets](#FACETS). | +| --mapFile | [string] | Mapping file to use when updating content that already exists.
Updated with any new mappings that are generated. If not present, will be created.
For more information, see [mapping files](#MAPPING-FILES). | +| -f
--force | [boolean] | Overwrite content, create and assign content types, and ignore content with missing types/references without asking. | +| -v
--validate | [boolean] | Only recreate folder structure - content is validated but not imported. | +| --skipIncomplete | [boolean] | Skip any content item that has one or more missing dependancy. | +| --lastPublish | [boolean] | When available, export the last published version of a content item rather than its newest version. | +| --publish | [boolean] | Publish any content items that have an existing publish status in their JSON. | +| --republish | [boolean] | Republish content items regardless of whether the import changed them or not.
(--publish not required) | +| --excludeKeys | [boolean] | Exclude delivery keys when importing content items. | +| --media | [boolean] | Detect and rewrite media links to match assets in the target account's DAM.
Your client must have DAM permissions configured. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Move content with destination credentials in config file + +`dc-cli content-item move ./myDirectory/content` + +##### Specify a mapping file when moving + +`dc-cli content-item move ./myDirectory/content --mapFile ./myDirectory/mappingFile.json` + +##### Move content wihout destination credentials in config file + +`dc-cli content-item move ./myDirectory/content --dstClientId foo --dstSecret bar --dstHubId baz` + +### archive + +Archives content items in the targeted Dynamic Content hub. + +``` +dc-cli content-item archive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --repoId | [string] | The ID of a content repository to search items in to be archived. | +| --folderId | [string] | The ID of a folder to search items in to be archived. | +| --facet | [string] | 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 [facets](#FACETS). | +| --name
*(Deprecated)* | [string] | The name of a Content Item to be archived.
A regex can be provided to select multiple items with similar or matching names (eg /.header/).
A single --name option may be given to match a single content item pattern.
Multiple --name options may be given to match multiple content items patterns at the same time, or even multiple regex.

Deprecated by the [--facet](#facets) option. | +| --contentType
(Deprecated) | [string] | A pattern which will only archive content items with a matching Content Type Schema ID.
A single --contentType option may be given to match a single schema id pattern.
Multiple --contentType options may be given to match multiple schema patterns at the same time.

Deprecated by the [--facet](#facets) option. | +| --revertLog | [string] | Path to a log file containing content items unarchived in a previous run of the unarchive command.
When provided, archives all content items listed as UNARCHIVE in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before archiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, archive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Archive all content items in a hub + +`dc-cli content-item archive` + +##### Archive all content items from a specific repository + +`dc-cli content-item archive --repoId 111111111111111111111111` + +##### Archive all content items with the "banner" schema type, with "Christmas" in their name + +`dc-cli content-item archive --facet "schema:/.+banner.json$/,name:/Christmas/"` + +### unarchive + +Unarchives content items in the targeted Dynamic Content hub. + +``` +dc-cli content-item unarchive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --repoId | [string] | The ID of a content repository to search items in to be unarchived. | +| --folderId | [string] | The ID of a folder to search items in to be unarchived. | +| --facet | [string] | 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 [facets](#FACETS). | +| --name
*(Deprecated)* | [string] | The name of a Content Item to be unarchived.
A regex can be provided to select multiple items with similar or matching names (eg /.header/).
A single --name option may be given to match a single content item pattern.
Multiple --name options may be given to match multiple content items patterns at the same time, or even multiple regex.

Deprecated by the [--facet](#facets) option. | +| --contentType
(Deprecated) | [string] | A pattern which will only unarchive content items with a matching Content Type Schema ID.
A single --contentType option may be given to match a single schema id pattern.
Multiple --contentType options may be given to match multiple schema patterns at the same time.

Deprecated by the [--facet](#facets) option. | +| --revertLog | [string] | Path to a log file containing content items archived in a previous run of the archive command.
When provided, archives all content items listed as ARCHIVE in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before unarchiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, unarchive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Unarchive all content items in a hub + +`dc-cli content-item unarchive` + +##### Unarchive all content items from a specific repository + +`dc-cli content-item unarchive --repoId 111111111111111111111111` + +##### Unarchive all content items with the "banner" schema type, with "Christmas" in their name + +`dc-cli content-item unarchive --facet "schema:/.+banner.json$/,name:/Christmas/"` + +### tree + +Print a dependency tree for any folder of content items on your system. The input directory should contain content items in the same format that the [export](#export) command generates. This is useful for examining the dependency structure of content that has been created, and identifying potential problems you might encounter when importing content items to a hub. + +``` +dc-cli content-item tree +``` + +#### Options + +The tree command only uses [common options](#Common Options) + +#### Examples + +##### Generate a content item tree for a filesystem directory + +`dc-cli content-item tree ./myDirectory/content` diff --git a/docs/CONTENT-REPOSITORY.md b/docs/CONTENT-REPOSITORY.md new file mode 100644 index 00000000..8375bb0b --- /dev/null +++ b/docs/CONTENT-REPOSITORY.md @@ -0,0 +1,125 @@ +# content-repository + +## Description + +The **content-repository** command category includes a number of interactions with Dynamic Content's repositories. + +These commands can be used to get details for a specific repository, list multiple repositories, or assign or unassign content types from a repository. + +Run `dc-cli content-repository --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Commands](#commands) + - [get](#get) + - [list](#list) + - [assign-content-type](#assign-content-type) + - [unassign-content-type](#unassign-content-type) + + + +## Common Options + +The following options are available for all **content-repository** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | + +## Commands + +### get + +Returns information for a single content repository. Returns name, label, assigned content types, repository type, and repository locales. + +``` +dc-cli content-repository get +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | --------------------- | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Get details for specific repository with ID of 'foo' + +`dc-cli content-repository get foo` + +### list + +Returns information for a all content repositories in the target hub. Returns name, label, assigned content types, features, and repository locales. + +``` +dc-cli content-repository list +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | ------------------------------------------------------------ | +| --sort | [string] | How to order the list.
e.g "\,\..." | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### List all repositories + +`dc-cli content-repository list` + +##### List all repositories sorted ascending by label + +`dc-cli content-repository list --sort "label,asc"` + +### assign-content-type + +Adds an association between a specified content type and a specified content repository, making it available for production in the Dynamic Content UI. + +``` +dc-cli content-repository assign-content-type +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | ------------------------------- | ------------------------- | +| --contentTypeId | [string]
[required] | Content Type ID to assign | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Create assignment between repository 'foo' and content type 'bar' + +`dc-cli content-repository assign-content-type foo --contentTypeId bar` + +### unassign-content-type + +Removes the association between a specified content type and a specified content repository, making it unavailable for production in the Dynamic Content UI. + +``` +dc-cli content-repository unassign-content-type +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | ------------------------------- | --------------------------- | +| --contentTypeId | [string]
[required] | Content Type ID to unassign | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Remove assignment between repository 'foo' and content type 'bar' + +`dc-cli content-repository unassign-content-type foo --contentTypeId bar` + diff --git a/docs/CONTENT-TYPE-SCHEMA.md b/docs/CONTENT-TYPE-SCHEMA.md new file mode 100644 index 00000000..e7911b9d --- /dev/null +++ b/docs/CONTENT-TYPE-SCHEMA.md @@ -0,0 +1,211 @@ +# content-type-schema + +## Description + +The **content-type-schema** command category includes a number of interactions with content type schemas. + +These commands can be used to retrieve information on one or more schemas, create new schemas, export and import schemas from an individual hub, as well as archiving and unarchiving schemas. + +Run `dc-cli content-type-schema --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Commands](#commands) + - [archive](#archive) + - [create](#create) + - [export](#export) + - [get](#get) + - [import](#import) + - [list](#list) + - [unarchive](#unarchive) + + + +## Common Options + +The following options are available for all **content-type-schema** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | + +## Commands + +### archive + +Archives a content type schema. This hides the schema from the active schema list in the Dynamic Content UI and prevents it being registered as a content type unless unarchived. + +``` +dc-cli content-type-schema archive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | A regex can be provided to select multiple schemas with similar IDs (eg /.header.\.json/).
A single --schemaId option may be given to archive a single content type schema.
Multiple --schemaId options may be given to archive multiple content type schemas at the same time. | +| --revertLog | [string] | Path to a log file containing content unarchived in a previous run of the unarchive command.
When provided, archives all schemas listed as unarchived in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before archiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, archive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Archive all active content type schemas + +`dc-cli content-type-schema archive` + +##### Archive all active content type schemas containing "Christmas" in their URI + +`dc-cli content-type-schema archive --schemaId "/Christmas/"` + +### create + +Imports a content type schema from a specified file on the filesystem to the targeted Dynamic Content hub. + +``` +dc-cli content-type-schema create +``` + +#### Options + +| Option Name | Type | Description | +| ----------------- | ------------------------------------------------------------ | ------------------------------------ | +| --schema | [string]
[required] | Content Type Schema source location. | +| --validationLevel | [string]
[required]
[choices: "SLOT", "CONTENT_TYPE", "PARTIAL"] | Content Type Schema validation Level | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Import slot content type schema from the filesystem + +`dc-cli content-type-schema create --schema ./myDirectory/schema/mySlot.json --validationLevel SLOT` + +### export + +Exports content type schemas from the targeted Dynamic Content hub into the specified filesystem location. + +More details can be found in [export usage](EXPORT_USAGE.md#CONTENT-TYPE-SCHEMAS). + +``` +dc-cli content-type-schema export +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | 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 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. | +| -f
--force | [boolean] | Overwrite content type schema without asking. | +| --archived | [boolean] | If present, archived content type schemas will also be considered. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Export all content type schemas from a Hub + +`dc-cli content-type-schema export ./myDirectory/schema` + +##### Export all content type schemas with "Christmas" in their URI + +`dc-cli content-type-schema export ./myDirectory/schema --schemaId "/Christmas/"` + +### get + +Returns information for a single content type schema. Returns status, validation level, body, schema ID (URI), created & modified by user, created & modified dates, version, and ID. + +``` +dc-cli content-type-schema get +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | --------------------- | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Get details for specific content type schema with ID of 'foo' + +`dc-cli content-type-schema get foo` + +### import + +Imports content type schemas from the specified filesystem location to the targeted Dynamic Content hub. It is recommended that you check that any content items you intend to import are still valid with any changes you make to your content type schemas. Please see [guidelines for making changes to a content type schema](https://amplience.com/docs/integration/refreshingcontenttypes.html#guidelines) for more information. + +More details on schema import can be found in [import usage](IMPORT_USAGE.md#CONTENT-TYPE-SCHEMAS). + +``` +dc-cli content-type-schema import +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------------------ | ------------------------------- | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Import content type schemas from the filesystem + +`dc-cli content-type-schema import ./myDirectory/schema` + +### list + +Returns information for a all content type schemas in the target hub. Returns ID, schema ID (URI), version, and schema validation level. + +``` +dc-cli content-type-schema list +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | --------------------- | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### List all content type schemas + +`dc-cli content-type-schema list` + +### unarchive + +Unarchives a content type schema. This returns the schema to the active schema list in the Dynamic Content UI and allows it to be registered as a content type once more. + +``` +dc-cli content-type-schema unarchive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | A regex can be provided to select multiple schemas with similar IDs (eg /.header.\.json/).
A single --schemaId option may be given to unarchive a single content type schema.
Multiple --schemaId options may be given to unarchive multiple content type schemas at the same time. | +| --revertLog | [string] | Path to a log file containing content archived in a previous run of the archive command.
When provided, unarchives all schemas listed as archived in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before unarchiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, unarchive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Unarchive all archived content type schemas + +`dc-cli content-type-schema unarchive` + +##### Unarchive all archived content type schemas containing "Christmas" in their URI + +`dc-cli content-type-schema unarchive --schemaId "/Christmas/"` diff --git a/docs/CONTENT-TYPE.md b/docs/CONTENT-TYPE.md new file mode 100644 index 00000000..12729b66 --- /dev/null +++ b/docs/CONTENT-TYPE.md @@ -0,0 +1,290 @@ +# content-type + +## Description + +The **content-type** command category includes a number of interactions with content types. + +These commands can be used to retrieve information on one or more types, register new types or update existing ones, export and import types from an individual hub, as well as archiving and unarchiving types. + +Before importing content types you must ensure that a valid [content type schema](#CONTENT-TYPE-SCHEMA.md) exists in the destination hub for each type. + +Run `dc-cli content-type --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Commands](#commands) + - [archive](#archive) + - [export](#export) + - [get](#get) + - [import](#import) + - [list](#list) + - [register](#register) + - [sync](#sync) + - [unarchive](#unarchive) + - [update](#update) + + + +## Common Options + +The following options are available for all **content-type** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +## Commands + +### archive + +Archives one or more content types. This hides them from the active content type list in the Dynamic Content UI and prevents new content items being created of that type. + +``` +dc-cli content-type archive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | The Schema ID of a Content Type's Schema to be archived.
A regex can be provided to select multiple types with similar or matching schema IDs (eg /.header.\.json/).
A single --schemaId option may be given to match a single content type schema.
Multiple --schemaId options may be given to match multiple content type schemas at the same time. | +| --revertLog | [string] | Path to a log file containing content unarchived in a previous run of the unarchive command.
When provided, archives all types listed as unarchived in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before archiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, unarchive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Archive all active content types + +`dc-cli content-type archive` + +##### Archive all active content types containing "Christmas" in their URI + +`dc-cli content-type archive --schemaId "/Christmas/"` + +### export + +Exports content types from the targeted Dynamic Content hub into the specified filesystem location. + +More details can be found in [export usage](EXPORT_USAGE.md#CONTENT-TYPES). + +``` +dc-cli content-type export +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | The Schema ID of a Content Type to be exported.
If no --schemaId option is given, all content types for the hub are exported.
A single --schemaId option may be given to export a single content type.
Multiple --schemaId options may be given to export multiple content types at the same time. | +| -f
--force | [boolean] | Overwrite content types without asking. | +| --archived | [boolean] | If present, archived content types will also be considered. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Export all content types from a Hub + +`dc-cli content-type export ./myDirectory/type` + +##### Export all content types with "Christmas" in their schema URI + +`dc-cli content-type export ./myDirectory/type --schemaId "/Christmas/"` + +### get + +Returns information for a single content type. Returns ID, URI, status, and settings. + +``` +dc-cli content-type get +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | --------------------- | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Get details for specific content type with ID of 'foo' + +`dc-cli content-type get foo` + +### import + +Imports content types from the specified filesystem location to the targeted Dynamic Content hub. + +Before importing content types you must ensure that a valid [content type schema](#CONTENT-TYPE-SCHEMA.md) exists in the destination hub for each content type. + +More details can be found in [import usage](IMPORT_USAGE.md#CONTENT-TYPES). + +``` +dc-cli content-type import +``` + +#### Options + +| Option Name | Type | Description | +| ------------ | ------------------------------------------ | --------------------------------------------- | +| --sync | [boolean]
[default: false] | Automatically sync Content Type schema. | +| --skipAssign | [boolean]
[default: false] | Skip assigning content types to repositories. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Import content types from the filesystem + +`dc-cli content-type import ./myDirectory/type` + +### list + +Returns information for a all content types in the target hub. Returns ID, label, and schema ID (URI). + +``` +dc-cli content-type list +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ------------------------------- | --------------------------------------------------------- | +| --sort | [string] | How to order the list e.g "\,\..." | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### List all content types + +`dc-cli content-type list` + +### register + +Registers a new content type with an existing content type schema in the targeted Dynamic Content hub. Allows you to specify custom cards and icons, as well as visualization URLs. + +Before registering a content type you must ensure that a valid [content type schema](#CONTENT-TYPE-SCHEMA.md) exists in the destination hub for this content type. + +``` +dc-cli content-type register +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------- | --------------------------------- | +| --schemaId | [string]
[required] | The content type's schema ID | +| --label | [string]
[required] | The content type's label | +| --icons | [default: {}] | The content type's icons | +| --visualizations | [default: {}] | The content type's visualizations | +| --cards | [default: {}] | The content type's cards | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Registering a content type with an existing schema + +`dc-cli content-type register --schemaId https://example.com/foo.json --label bar` + +##### Add an icon when registering a new content type + +`dc-cli content-type register --schemaId https://example.com/foo.json --icons.0.size 256 --icons.0.url "https://example.com/bar.jpg"` + +##### Add a visualization when registering a new content type + +`dc-cli content-type register --schemaId https://example.com/foo.json --visualizations.0.label "bar" --visualizations.0.templatedUri "https://example.com/baz" --visualizations.0.default true` + +##### Add a card when registering a new content type + +`dc-cli content-type register --schemaId https://example.com/foo.json —-cards.0.label "bar" —-cards.0.templatedUri "https://schema.localhost.com/baz" —-cards.0.default true` + +### sync + +Synchronises a content type, so that it matches the present version of its registered schema. + +``` +dc-cli content-type sync +``` + +#### Options + +| Option NameOption Name | TypeType | DescriptionDescription | +| ---------------------- | ------------------------------- | ---------------------- | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Synchronise content type with ID of 'foo' with its content type schema + +`dc-cli content-type sync foo` + +### unarchive + +Unarchives one or more content types. This returns them to the active content type list in the Dynamic Content UI and allows new content items to be created of that type once more. + +``` +dc-cli content-type unarchive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------------------ | ------------------------------------------------------------ | +| --schemaId | [string] | The Schema ID of a Content Type's Schema to be unarchived.
A regex can be provided to select multiple types with similar or matching schema IDs (eg /.header.\.json/).
A single --schemaId option may be given to match a single content type schema.
Multiple --schemaId options may be given to match multiple content type schemas at the same time. | +| --revertLog | [string] | Path to a log file containing content archived in a previous run of the archive command.
When provided, unarchives all types listed as archived in the log file. | +| -f
--force | [boolean] | If present, there will be no confirmation prompt before unarchiving the found content. | +| -s
--silent | [boolean] | If present, no log file will be produced. | +| --ignoreError | [boolean] | If present, unarchive requests that fail will not abort the process. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +#### Examples + +##### Unarchive all archived content types + +`dc-cli content-type unarchive` + +##### Unarchive all archived content types containing "Christmas" in their URI + +`dc-cli content-type unarchive --schemaId "/Christmas/"` + +### update + +Updates the supporting properties of the content type, including custom cards and icons, as well as visualization URLs. + +``` +dc-cli content-type update +``` + +#### Options + +| Option Name | Type | Description | +| ---------------- | ------------------------------- | --------------------------------- | +| --label | [string]
[required] | The content type's label | +| --icons | [default: {}] | The content type's icons | +| --visualizations | [default: {}] | The content type's visualizations | +| --cards | [default: {}] | The content type's cards | +| --json | [boolean]
[default: false] | Render output as JSON | + +#### Examples + +##### Add an icon when updating a content type + +`dc-cli content-type update foo --icons.0.size 256 --icons.0.url "https://example.com/bar.jpg"` + +##### Add a visualization when updating a content type + +`dc-cli content-type update foo --visualizations.0.label "bar" --visualizations.0.templatedUri "https://example.com/baz" --visualizations.0.default true` + +##### Add a card when updating a content type + +`dc-cli content-type update foo —-cards.0.label "bar" —-cards.0.templatedUri "https://schema.localhost.com/baz" —-cards.0.default true` \ No newline at end of file diff --git a/EXPORT_USAGE.md b/docs/EXPORT_USAGE.md similarity index 100% rename from EXPORT_USAGE.md rename to docs/EXPORT_USAGE.md diff --git a/docs/EXTENSION.md b/docs/EXTENSION.md new file mode 100644 index 00000000..4254abe7 --- /dev/null +++ b/docs/EXTENSION.md @@ -0,0 +1,78 @@ +# extension + +## Description + +The **extension** command category includes a number of interactions with Dynamic Content's UI Extensions, and can be used to export and import extensions from an individual hub. + +Run `dc-cli extension --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Commands](#commands) + - [export](#export) + - [import](#import) + + + +## Common Options + +The following options are available for all **extension** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +## Commands + +### export + +Exports extensions from the targeted Dynamic Content hub into the specified filesystem location. + +``` +dc-cli extension export +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | --------- | ------------------------------------------------------------ | +| --id | [string] | 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. | +| -f
--force | [boolean] | Overwrite extensions without asking. | + +#### Examples + +##### Export all extensions from a Hub + +`dc-cli extension export ./myDirectory/extension` + +##### Export extensions with IDs of 'foo' & 'bar' + +`dc-cli extension export ./myDirectory/extension --id foo --id bar` + +### import + +Imports extensions from the specified filesystem location to the targeted Dynamic Content hub. + +``` +dc-cli extension import +``` + +#### Options + +The import command only uses [common options](#Common Options) + +#### Examples + +##### Import extensions from the filesystem + +`dc-cli extension import ./myDirectory/extension` + diff --git a/docs/HUB.md b/docs/HUB.md new file mode 100644 index 00000000..17558ccd --- /dev/null +++ b/docs/HUB.md @@ -0,0 +1,147 @@ +# hub + +## Description + +The **hub** command category includes interactions with Dynamic Content's hubs in their entirety. + +These commands can be used to copy a hub's settings and content in their entirety to another hub, or to archive all parts of a hub which can be archived. + +Run `dc-cli hub --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Useful Information](#useful-information) + - [Mapping files](#mapping-files) + - [Media-link rewriting](#media-link-rewriting) +- [Commands](#commands) + - [clone](#clone) + - [clean](#clean) + + + +## Common Options + +The following options are available for all **hub** commands. + +| Option Name | Type | Description | +| --------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| -f
--force | [boolean] | Overwrite content, create and assign content types, and ignore content with missing types/references without asking. | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +## Useful Information + +### Mapping files + +When importing content with the DC CLI, this creates or references a mapping file to determine whether the imported content item should be created as new, or if an existing one within the Dynamic Content platform should be updated. + +For example exporting a content item (eg `11111111-1111-1111-1111-111111111111`) from one hub then importing it to another for the first time will create a new content item with a randomly generated UUID (eg `22222222-2222-2222-2222-222222222222`). + +To instruct the DC CLI on which content item to update with future actions, a mapping between the source and destination is stored in a mapping file. This mapping file will contain an array of every content item mapping identified for jobs using that mapping file. Using the previous examples: + +``` +{ + "contentItems": [ + [ + "11111111-1111-1111-1111-111111111111", + "22222222-2222-2222-2222-222222222222" + ] + ], + "workflowStates": [] +} +``` + +If no mapping file is specified (with the `--mapFile` argument) then a default one will be created or updated, using the destination's resource type (hub) and its ID, and stored within a default location in your user directory. For example: + +* Mac: `~/.amplience/imports/hub-111111111111111111111111.json` +* Windows: `%UserProfile%\.amplience\imports\hub-111111111111111111111111.json` + +If a mapping file does not exist at the point of import, then any imported content items will be created as new, and a new mapping file will be created. If a mapping file exists, and was provided with the `--mapFile` argument, then any items found within the mapping file will be updated. Any content items not contained in the mapping file will will be created as new, and will then be added to the mapping file. + +### Media-link rewriting + +The DC CLI is capable of importing or copying content into a Dynamic Content hub which resides on a distinct Content Hub account to the source by using the `--media` option with the clone command. This will update the `endpoint`, `id`, and `defaultHost` values for any `media-link` objects to reflect the endpoint of the destination hub's account, if an asset with a matching name exists in the destination account. + +This functionality requires additional Content Hub-specific permissions granting to your DC CLI client in order to grant it visibility of the destination account's media assets (`DAM:ASSET STORE:ASSET_STORE_NAME`). + +## Commands + +### clone + +Exports all of the following (where applicable) from the source hub, then imports them into the destination hub: + +* Hub Settings +* Extensions +* Content Type Schemas +* Content Types +* Content Items +* Search Indexes + +``` +dc-cli hub clone +``` + +#### Options + +| Option Name | Type | Description | +| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| --dstHubId | [string] | Destination hub ID.
If not specified, it will be the same as the source. | +| --dstClientId | [string] | Destination account's client ID.
If not specified, it will be the same as the source. | +| --dstSecret | [string] | Destination account's secret.
Must be used alongside dstClientId. | +| --mapFile | [string] | Mapping file to use when updating content that already exists.
Updated with any new mappings that are generated. If not present, will be created. | +| -v
--validate | [boolean] | Only recreate folder structure.
Content is validated but not imported. | +| --skipIncomplete | [boolean] | Skip any content item that has one or more missing dependancy. | +| --lastPublish | [boolean] | When available, export the last published version of a content item rather than its newest version. | +| --publish | [boolean] | Publish any content items that have an existing publish status in their JSON. | +| --republish | [boolean] | Republish content items regardless of whether the import changed them or not.
(--publish not required) | +| --excludeKeys | [boolean] | Exclude delivery keys when importing content items. | +| --media | [boolean] | Detect and rewrite media links to match assets in the target account's DAM.
Your client must have DAM permissions configured. | +| --revertLog | [string] | Revert a previous clone using a given revert log and given directory.
Reverts steps in reverse order, starting at the specified one. | +| --step | [string]
[choices: "settings", "schema", "type", "content"] | Start at a specific step.
Steps after the one you specify will also run. | + +#### Examples + +##### Clone hub from scratch + +`dc-cli hub clone ./myDirectory/hub` + +##### Resume a hub clone from the content item step + +`dc-cli hub clone ./myDirectory/hub --step content` + +### clean + +Archives all of the following (where applicable) from the source hub: + +* Hub Settings +* Content Type Schemas +* Content Types +* Content Items + +``` +dc-cli hub clean +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | ---------------------------------------------------- | ------------------------------------------------------------ | +| --step | [string]
[choices: "content", "type", "schema"] | Start at a specific step.
Steps after the one you specify will also run. | + +#### Examples + +##### Start off the clean hub process + +`dc-cli hub clean` + +##### Resume the clean hub process from the content item step + +`dc-cli hub clean --step content` \ No newline at end of file diff --git a/IMPORT_USAGE.md b/docs/IMPORT_USAGE.md similarity index 100% rename from IMPORT_USAGE.md rename to docs/IMPORT_USAGE.md diff --git a/docs/SEARCH-INDEX.md b/docs/SEARCH-INDEX.md new file mode 100644 index 00000000..40b74639 --- /dev/null +++ b/docs/SEARCH-INDEX.md @@ -0,0 +1,79 @@ +# search-index + +## Description + +The **search-index** command category includes a number of interactions with Algolia search indexes for Dynamic Content, and can be used to export and import indexes from an individual hub. + +Run `dc-cli search-index --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Commands](#commands) + - [Export](#export) + - [Import](#import) + + + +## Common Options + +The following options are available for all **search-index** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +## Commands + +### Export + +Exports search indexes from the targeted Dynamic Content hub into the specified filesystem location. + +``` +dc-cli search-index export +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | --------- | ------------------------------------------------------------ | +| --id | [string] | The ID of a Search Index to be exported.
If no --id option is given, all search indexes for the hub are exported.
A single --id option may be given to export a single Search Index.
Multiple --id options may be given to export multiple search indexes at the same time. | +| -f
--force | [boolean] | Overwrite search indexes without asking. | + +#### Examples + +##### Export search indexes + +`dc-cli search-index export ./myDirectory/indexes` + +### Import + +Imports search indexes from the specified filesystem location to the targeted Dynamic Content hub. + +``` +dc-cli search-index import +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | --------- | ------------------------------------------------------------ | +| --webhooks | [boolean] | Import the index's webhooks as well as the index itself.
The command will attempt to rewrite account names and staging environments in the webhook body to match the destination. | + +#### Examples + +##### Import search indexes without custom payload + +`dc-cli search-index import ./myDirectory/indexes` + +##### Import search indexes with custom payload + +`dc-cli search-index import ./myDirectory/indexes --webhooks` \ No newline at end of file diff --git a/docs/SETTINGS.md b/docs/SETTINGS.md new file mode 100644 index 00000000..45059928 --- /dev/null +++ b/docs/SETTINGS.md @@ -0,0 +1,110 @@ +# settings + +## Description + +The **settings** command category includes interactions with the supporting properties of a Dynamic Content hub. These commands can be used to export and import a hub's breakpoint settings for visualization, preview applications, workflow states, and locales. + +Run `dc-cli settings --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command categories. + + + +- [Common Options](#common-options) +- [Useful information](#useful-information) + - [Mapping files](#mapping-files) +- [Commands](#commands) + - [export](#export) + - [import](#import) + + + +## Common Options + +The following options are available for all **settings** commands. + +| Option Name | Type | Description | +| -------------- | ---------------------------------------------------------- | -------------------------------- | +| --version | [boolean] | Show version number | +| --clientId | [string]
[required] | Client ID for the source hub | +| --clientSecret | [string]
[required] | Client secret for the source hub | +| --hubId | [string]
[required] | Hub ID for the source hub | +| --config | [string]
[default: "~/.amplience/dc-cli-config.json"] | Path to JSON config file | +| --help | [boolean] | Show help | +| --logFile | [string]
[default: (generated-value)] | Path to a log file to write to. | + +## Useful information + +### Mapping files + +When importing workflow states from with the DC CLI, this creates or references a mapping file to determine whether a new workflow state should be created, or if an existing one should be updated. + +For example exporting a workflow state (eg `111111111111111111111111`) from one hub then importing it to another for the first time will create a new workflow state with a randomly generated UUID (eg `222222222222222222222222`). + +To instruct the DC CLI on which workflow state to update with future actions, a mapping between the source and destination is stored in a mapping file. This mapping file will contain an array of every workflow state mapping identified for jobs using that mapping file. Using the previous examples: + +``` +{ + "contentItems": [], + "workflowStates": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ] +} +``` + +If no mapping file is specified (with the `--mapFile` argument) then a default one will be created or updated, using the destination's resource type (hub) and its ID, and stored within a default location in your user directory. For example: + +* Mac: `~/.amplience/imports/hub-111111111111111111111111.json` +* Windows: `%UserProfile%\.amplience\imports\hub-111111111111111111111111.json` + +If a mapping file does not exist at the point of import, then any imported workflow states will be created as new, and a new mapping file will be created. If a mapping file exists, and was provided with the `--mapFile` argument, then any workflow states found within the mapping file will be updated. Any workflow states not contained in the mapping file will will be created as new, and will then be added to the mapping file. + +## Commands + +### export + +Exports the hub's settings from the targeted Dynamic Content hub into the specified filesystem location. + +``` +dc-cli settings export +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | --------- | ------------------------------------------------------------ | +| -f
--force | [boolean] | Overwrite settings when writing to the filesystem without asking. | + +#### Examples + +##### Export settings from a Hub + +`dc-cli settings export ./myDirectory/settings` + +### import + +Imports a hub's settings from the specified filesystem location to the targeted Dynamic Content hub. + +``` +dc-cli settings import +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | --------- | ------------------------------------------------------------ | +| --mapFile | [string] | Mapping file to use when updating workflow states that already exists.
Updated with any new mappings that are generated.
If not present, will be created.
For more information, see [mapping files](#MAPPING-FILES). | +| -f
--force | [boolean] | Overwrite workflow states on import without asking. | + +#### Examples + +##### Import settings the filesystem + +`dc-cli settings import ./myDirectory/settings` + +##### Specify a mapping file when importing + +`dc-cli settings import ./myDirectory/settings --mapFile ./myDirectory/mappingFile.json` \ No newline at end of file