From 4d7fc1b00dace8357d340ff37812a2fc9eefd122 Mon Sep 17 00:00:00 2001 From: Michael Date: Thu, 11 Nov 2021 11:50:00 +0000 Subject: [PATCH 1/7] docs: Readme overhaul --- HOW_TO_USE.1 | 42 -- HOW_TO_USE.md | 22 -- README.md | 161 ++++++-- .../BUILDING_THE_CLI.md | 2 + docs/CONTENT-ITEM.md | 372 ++++++++++++++++++ docs/CONTENT-REPOSITORY.md | 125 ++++++ docs/CONTENT-TYPE-SCHEMA.md | 211 ++++++++++ docs/CONTENT-TYPE.md | 270 +++++++++++++ docs/EVENT.md | 179 +++++++++ EXPORT_USAGE.md => docs/EXPORT_USAGE.md | 0 docs/EXTENSION.md | 78 ++++ docs/HUB.md | 148 +++++++ IMPORT_USAGE.md => docs/IMPORT_USAGE.md | 0 docs/SEARCH-INDEX.md | 79 ++++ docs/SETTINGS.md | 110 ++++++ 15 files changed, 1709 insertions(+), 90 deletions(-) delete mode 100644 HOW_TO_USE.1 delete mode 100644 HOW_TO_USE.md rename BUILDING_THE_CLI.md => docs/BUILDING_THE_CLI.md (96%) create mode 100644 docs/CONTENT-ITEM.md create mode 100644 docs/CONTENT-REPOSITORY.md create mode 100644 docs/CONTENT-TYPE-SCHEMA.md create mode 100644 docs/CONTENT-TYPE.md create mode 100644 docs/EVENT.md rename EXPORT_USAGE.md => docs/EXPORT_USAGE.md (100%) create mode 100644 docs/EXTENSION.md create mode 100644 docs/HUB.md rename IMPORT_USAGE.md => docs/IMPORT_USAGE.md (100%) create mode 100644 docs/SEARCH-INDEX.md create mode 100644 docs/SETTINGS.md diff --git a/HOW_TO_USE.1 b/HOW_TO_USE.1 deleted file mode 100644 index 72739b94..00000000 --- a/HOW_TO_USE.1 +++ /dev/null @@ -1,42 +0,0 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "DC\-CLI" "1" "August 2020" "" "" -. -.SH "NAME" -\fBdc\-cli\fR \- (Amplience) Dynamic Content command line interface -. -.SH "SYNOPSIS" -\fBdc\-cli\fR \fB\fR \fB[args]\fR -. -.SH "DESCRIPTION" -\fBdc\-cli\fR is a command line interface application for Amplience Dynamic Content management APIs\. -. -.P -Run \fBdc\-cli\fR to get a list of available commands -. -.SH "CONFIGURATION" -\fBdc\-cli\fR requires a valid set of Amplience client credentials (\fB\-\-clientId\fR & \fB\-\-clientSecret\fR) and hub ID (\fB\-\-hubId\fR) to operate\. These must be supplied for each command or alternatively they can saved to a user\-level configuration file using \fBdc\-cli configure\fR\. -. -.P -By default the configuration file is saved into the directory \fB/\.amplience/\fR, this can be overridden using the \fB\-\-config\fR option\. -. -.P -See \fBdc\-cli configure \-\-help\fR for more information\. -. -.SH "SEE ALSO" -. -.IP "\(bu" 4 -\fBdc\-cli \-\-help\fR -. -.IP "\(bu" 4 -\fBdc\-cli \-\-help\fR -. -.IP "\(bu" 4 -\fBREADME\.md\fR -. -.IP "\(bu" 4 -https://docs\.amplience\.net/ -. -.IP "" 0 - diff --git a/HOW_TO_USE.md b/HOW_TO_USE.md deleted file mode 100644 index 681e9db6..00000000 --- a/HOW_TO_USE.md +++ /dev/null @@ -1,22 +0,0 @@ -# dc-cli(1) - (Amplience) Dynamic Content command line interface -## SYNOPSIS - -`dc-cli` `` `[args]` - -## DESCRIPTION -**dc-cli** is a command line interface application for Amplience Dynamic Content management APIs. - -Run `dc-cli` to get a list of available commands - -## CONFIGURATION -**dc-cli** requires a valid set of Amplience client credentials (`--clientId` & `--clientSecret`) and hub ID (`--hubId`) to operate. These must be supplied for each command or alternatively they can saved to a user-level configuration file using `dc-cli configure`. - -By default the configuration file is saved into the directory `/.amplience/`, this can be overridden using the `--config` option. - -See `dc-cli configure --help` for more information. - -## SEE ALSO -* `dc-cli --help` -* `dc-cli --help` -* `README.md` -* https://docs.amplience.net/ diff --git a/README.md b/README.md index 2b5a7f1e..11b8e842 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,27 @@ 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) +- [Command categories](#commands) + - [configure](#configure) + - [content-type-schema](#content-type-schema) + - [content-type](#content-type) + - [content-item](#content-item) + - [extension](#extension) + - [search-index](#search-index) + - [content-repository](#content-repository) + - [event](#event) + - [settings](#settings) + - [hub](#hub) +- [Building the CLI](#building-the-cli) +- [Required permissions](#required-permissions) + + ## Installation @@ -23,45 +43,134 @@ 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. + +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) exists in the destination hub for each content item. -## Usage +[View commands for **content-item**](docs/CONTENT-ITEM.md) -- [How to use the CLI](HOW_TO_USE.md) -- [Export using the CLI](EXPORT_USAGE.md) -- [Import using the CLI](IMPORT_USAGE.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, list multiple repositories, or assign or unassign content types from a repository. + +[View commands for **content-repository**](docs/CONTENT-REPOSITORY.md) + +### event + +This category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots. These commands can be used to export and import events, and to archive events. + +[View commands for **event**](docs/EVENT.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..678e96aa --- /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 caterogies. + + + +- [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` value 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 | [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. | +| --name | [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. | +| --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 foo` + +##### 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. + +``` +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 foo` + +### 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 | [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. | +| --contentType | [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. | +| --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 foo` + +##### 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 | [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. | +| --contentType | [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. | +| --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 foo` + +##### 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..d4f96248 --- /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, 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 caterogies. + + + +- [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..096a0966 --- /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 caterogies. + + + +- [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. + +More details 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..48680c74 --- /dev/null +++ b/docs/CONTENT-TYPE.md @@ -0,0 +1,270 @@ +# 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 caterogies. + + + +- [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 a content type schema. This hides the schema 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` + +### 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 + +##### Example 1 + +##### Example 2 \ No newline at end of file diff --git a/docs/EVENT.md b/docs/EVENT.md new file mode 100644 index 00000000..e4a8cef7 --- /dev/null +++ b/docs/EVENT.md @@ -0,0 +1,179 @@ +# event + +## Description + +The **event** category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots. These commands can be used to export and import events, and to archive events. + +Run `dc-cli event --help` to get a list of available commands. + +Return to [README.md](../README.md) for information on other command caterogies. + + + +- [Common Options](#common-options) +- [Useful Information](#useful-information) + - [Mapping files](#mapping-files) + - [Snapshots and DC CLI](#snapshots-and-dc-cli) +- [Commands](#commands) + - [archive](#archive) + - [export](#export) + - [import](#import) + + + +## Common Options + +The following options are available for all **event** 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 content with the DC CLI, this creates or references a mapping file to determine whether the imported event should be created as new, or if an existing one within the Dynamic Content platform should be updated. + +For example exporting an event (eg `111111111111111111111111`) from one hub then importing it to another for the first time will create a new event with a randomly generated UUID (eg `222222222222222222222222`). + +To instruct the DC CLI on which event 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 event mapping identified for jobs using that mapping file. Using the previous examples: + +``` +{ + "contentItems": [], + "workflowStates": [], + "events": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ], + "editions": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ], + "slots": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ], + "snapshots": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ] +} +``` + +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 events 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 events found within the mapping file will be updated. Any events not contained in the mapping file will will be created as new, and will then be added to the mapping file. + +### Snapshots and DC CLI + +The most granular part of an event in Dynamic Content is a snapshot. This is a representation of a content item exactly as it appears at the point when it was added to an edition using the content browser, or when it was saved to an edition in the production view. + +Due to this nature of snapshots, the event import command will not always result in an exact copy of the events exported with the event export command. Whilst the properties of the parent edition and event will match those of the source, the snapshots will be created as new. If a snapshotted content item in the source hub's exported events have been updated since the snapshot was created, then it will be the updated version of that content item which will be created as snapshots in the destination hub. + +## Commands + +### archive + +Archives events and their child edition in the targeted Dynamic Content hub, and will also unschedule them if they have not yet started. + +This command requires either an event ID or name to filter, and will not archive any events if no filter is provided. + +``` +dc-cli event archive [id] +``` + +#### Options + +| Option Name | Type | Description | +| ----------------- | --------- | ------------------------------------------------------------ | +| --name | [string] | The name of an Event 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 event pattern.
Multiple --name options may be given to match multiple events' patterns at the same time, or even multiple | +| -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. | + +#### Examples + +##### Archive event with the ID of "foo" + +`dc-cli event archive foo` + +##### Archive all events with "Christmas" in their name + +`dc-cli event archive --name "/.*Christmas.*/"` + +### export + +Exports events from the targeted Dynamic Content hub into the specified filesystem location. + +We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. + +``` +dc-cli event archive +``` + +#### Options + +| Option Name | Type | Description | +| ----------- | --------- | ------------------------------------------------------------ | +| --id | [string] | Export a single event by ID, rather then fetching all of them. | +| --fromDate | [string] | Start date for filtering events.
Either "NOW" or in the format "\:\", example: "-7:DAYS". | +| --toDate | [string] | To date for filtering events.
Either "NOW" or in the format "\:\", example: "-7:DAYS". | +| --snapshots | [boolean] | Save content snapshots with events, in subfolder "snapshots/". | + +#### Examples + +##### Export all events from a Hub + +`dc-cli event export ./myDirectory/event` + +##### Export all events which start 7 days from now from a Hub + +`dc-cli event export ./myDirectory/event --fromDate "+7:DAYS"` + +### import + +Imports events from the specified filesystem location to the targeted Dynamic Content hub. + +We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. + +Before importing events you must ensure that a valid [content item](#CONTENT-ITEM.md) exists in the destination hub for each content item contained within each event. + +``` +dc-cli event archive +``` + +#### Options + +| Option Name | Type | Description | +| --------------- | --------- | ------------------------------------------------------------ | +| --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 existing events, editions, slots and snapshots without asking. | +| --originalIds | [boolean] | Use original IDs. | + +#### Examples + +##### Import events from the filesystem + +`dc-cli content-item import ./myDirectory/event` + +##### Specify a mapping file when importing + +`dc-cli settings event ./myDirectory/event --mapFile ./myDirectory/mappingFile.json` \ 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..dc53866b --- /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 caterogies. + + + +- [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..eb49f971 --- /dev/null +++ b/docs/HUB.md @@ -0,0 +1,148 @@ +# 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 caterogies. + + + +- [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, 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. + +### 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` value 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 +* Events +* 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` + +##### Resume a hub clone from the content item step + +`dc-cli hub clone --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..be18989c --- /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 caterogies. + + + +- [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..2e18fdc6 --- /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 caterogies. + + + +- [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, 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 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 From e522efa8541ee1c8b5409bfbb82a311dbf3d41c4 Mon Sep 17 00:00:00 2001 From: Michael Date: Thu, 11 Nov 2021 12:28:29 +0000 Subject: [PATCH 2/7] docs: Readme overhaul --- HOW_TO_USE.1 | 42 ++++++++++++++++++++++++++++++++++++++++++ HOW_TO_USE.md | 23 +++++++++++++++++++++++ docs/CONTENT-TYPE.md | 24 ++++++++++++++++++++++-- 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 HOW_TO_USE.1 create mode 100644 HOW_TO_USE.md diff --git a/HOW_TO_USE.1 b/HOW_TO_USE.1 new file mode 100644 index 00000000..72739b94 --- /dev/null +++ b/HOW_TO_USE.1 @@ -0,0 +1,42 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "DC\-CLI" "1" "August 2020" "" "" +. +.SH "NAME" +\fBdc\-cli\fR \- (Amplience) Dynamic Content command line interface +. +.SH "SYNOPSIS" +\fBdc\-cli\fR \fB\fR \fB[args]\fR +. +.SH "DESCRIPTION" +\fBdc\-cli\fR is a command line interface application for Amplience Dynamic Content management APIs\. +. +.P +Run \fBdc\-cli\fR to get a list of available commands +. +.SH "CONFIGURATION" +\fBdc\-cli\fR requires a valid set of Amplience client credentials (\fB\-\-clientId\fR & \fB\-\-clientSecret\fR) and hub ID (\fB\-\-hubId\fR) to operate\. These must be supplied for each command or alternatively they can saved to a user\-level configuration file using \fBdc\-cli configure\fR\. +. +.P +By default the configuration file is saved into the directory \fB/\.amplience/\fR, this can be overridden using the \fB\-\-config\fR option\. +. +.P +See \fBdc\-cli configure \-\-help\fR for more information\. +. +.SH "SEE ALSO" +. +.IP "\(bu" 4 +\fBdc\-cli \-\-help\fR +. +.IP "\(bu" 4 +\fBdc\-cli \-\-help\fR +. +.IP "\(bu" 4 +\fBREADME\.md\fR +. +.IP "\(bu" 4 +https://docs\.amplience\.net/ +. +.IP "" 0 + diff --git a/HOW_TO_USE.md b/HOW_TO_USE.md new file mode 100644 index 00000000..39e4c66f --- /dev/null +++ b/HOW_TO_USE.md @@ -0,0 +1,23 @@ +# dc-cli(1) - (Amplience) Dynamic Content command line interface +## SYNOPSIS + +`dc-cli` `` `[args]` + +## DESCRIPTION +**dc-cli** is a command line interface application for Amplience Dynamic Content management APIs. + +Run `dc-cli` to get a list of available commands + +## CONFIGURATION +**dc-cli** requires a valid set of Amplience client credentials (`--clientId` & `--clientSecret`) and hub ID (`--hubId`) to operate. These must be supplied for each command or alternatively they can saved to a user-level configuration file using `dc-cli configure`. + +By default the configuration file is saved into the directory `/.amplience/`, this can be overridden using the `--config` option. + +See `dc-cli configure --help` for more information. + +## SEE ALSO +* `dc-cli --help` +* `dc-cli --help` +* `README.md` +* https://docs.amplience.net/ + diff --git a/docs/CONTENT-TYPE.md b/docs/CONTENT-TYPE.md index 48680c74..aaecd616 100644 --- a/docs/CONTENT-TYPE.md +++ b/docs/CONTENT-TYPE.md @@ -196,6 +196,18 @@ dc-cli content-type register `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. @@ -265,6 +277,14 @@ dc-cli content-type update #### Examples -##### Example 1 +##### 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 -##### Example 2 \ No newline at end of file +`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 From ef47cefad539f80dfb3989b50e5fb142c2754ef3 Mon Sep 17 00:00:00 2001 From: Michael Date: Fri, 19 Nov 2021 14:11:54 +0000 Subject: [PATCH 3/7] Spelling/grammar corrections --- README.md | 6 +++--- docs/CONTENT-ITEM.md | 18 +++++++++--------- docs/CONTENT-REPOSITORY.md | 4 ++-- docs/CONTENT-TYPE-SCHEMA.md | 8 ++++---- docs/CONTENT-TYPE.md | 10 +++++----- docs/EVENT.md | 21 +++++++++++++-------- docs/EXTENSION.md | 2 +- docs/HUB.md | 14 +++++++------- docs/SEARCH-INDEX.md | 2 +- docs/SETTINGS.md | 10 +++++----- 10 files changed, 50 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 11b8e842..3262c075 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ Run `dc-cli --help` to get a list of available commands. - [Installation](#installation) - [Configuration](#configuration) -- [Command categories](#commands) - - [configure](#configure) + - [Options](#options) +- [Command categories](#command-categories) - [content-type-schema](#content-type-schema) - [content-type](#content-type) - [content-item](#content-item) @@ -120,7 +120,7 @@ This category includes interactions with Algolia search indexes for Dynamic Cont This category includes interactions with Dynamic Content's repositories. -These commands can be used to get details for a specific, list multiple repositories, or assign or unassign content types from a repository. +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) diff --git a/docs/CONTENT-ITEM.md b/docs/CONTENT-ITEM.md index 678e96aa..ace28cc7 100644 --- a/docs/CONTENT-ITEM.md +++ b/docs/CONTENT-ITEM.md @@ -10,12 +10,12 @@ Before importing, copying, or moving content you must ensure that a valid [conte Run `dc-cli content-item --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. - [Common Options](#common-options) -- [Useful information](#useful-information) +- [Useful Information](#useful-information) - [Mapping files](#mapping-files) - [Facets](#facets) - [Media-link rewriting](#media-link-rewriting) @@ -137,11 +137,11 @@ dc-cli content-item export ##### Export all content items from a specific repository -`dc-cli content-item export ./myDirectory/content --repoId foo` +`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.*/"` +`dc-cli content-item export ./myDirectory/content --facet "schema:/.+banner.json$/,name:/Christmas/"` ### import @@ -181,7 +181,7 @@ dc-cli content-item import ##### Import content into a specific repository -`dc-cli content-item import ./myDirectory/content --baseRepo foo` +`dc-cli content-item import ./myDirectory/content --baseRepo 111111111111111111111111` ### copy @@ -310,11 +310,11 @@ dc-cli content-item archive [id] ##### Archive all content items from a specific repository -`dc-cli content-item archive --repoId foo` +`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.*/"` +`dc-cli content-item archive --facet "schema:/.+banner.json$/,name:/Christmas/"` ### unarchive @@ -347,11 +347,11 @@ dc-cli content-item unarchive [id] ##### Unarchive all content items from a specific repository -`dc-cli content-item unarchive --repoId foo` +`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.*/"` +`dc-cli content-item unarchive --facet "schema:/.+banner.json$/,name:/Christmas/"` ### tree diff --git a/docs/CONTENT-REPOSITORY.md b/docs/CONTENT-REPOSITORY.md index d4f96248..8375bb0b 100644 --- a/docs/CONTENT-REPOSITORY.md +++ b/docs/CONTENT-REPOSITORY.md @@ -4,11 +4,11 @@ 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, list multiple repositories, or assign or unassign content types from a repository. +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 caterogies. +Return to [README.md](../README.md) for information on other command categories. diff --git a/docs/CONTENT-TYPE-SCHEMA.md b/docs/CONTENT-TYPE-SCHEMA.md index 096a0966..c5b264ec 100644 --- a/docs/CONTENT-TYPE-SCHEMA.md +++ b/docs/CONTENT-TYPE-SCHEMA.md @@ -8,7 +8,7 @@ These commands can be used to retrieve information on one or more schemas, creat 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 caterogies. +Return to [README.md](../README.md) for information on other command categories. @@ -66,7 +66,7 @@ dc-cli content-type-schema archive [id] ##### Archive all active content type schemas containing "Christmas" in their URI -`dc-cli content-type-schema archive --schemaId "/.*Christmas.*/"` +`dc-cli content-type-schema archive --schemaId "/Christmas/"` ### create @@ -117,7 +117,7 @@ dc-cli content-type-schema export ##### Export all content type schemas with "Christmas" in their URI -`dc-cli content-type-schema export ./myDirectory/schema --schemaId "/.*Christmas.*/"` +`dc-cli content-type-schema export ./myDirectory/schema --schemaId "/Christmas/"` ### get @@ -208,4 +208,4 @@ dc-cli content-type-schema unarchive [id] ##### Unarchive all archived content type schemas containing "Christmas" in their URI -`dc-cli content-type-schema unarchive --schemaId "/.*Christmas.*/"` +`dc-cli content-type-schema unarchive --schemaId "/Christmas/"` diff --git a/docs/CONTENT-TYPE.md b/docs/CONTENT-TYPE.md index aaecd616..12729b66 100644 --- a/docs/CONTENT-TYPE.md +++ b/docs/CONTENT-TYPE.md @@ -10,7 +10,7 @@ Before importing content types you must ensure that a valid [content type schema Run `dc-cli content-type --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. @@ -46,7 +46,7 @@ The following options are available for all **content-type** commands. ### archive -Archives a content type schema. This hides the schema from the active content type list in the Dynamic Content UI and prevents new content items being created of that type. +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] @@ -71,7 +71,7 @@ dc-cli content-type archive [id] ##### Archive all active content types containing "Christmas" in their URI -`dc-cli content-type archive --schemaId "/.*Christmas.*/"` +`dc-cli content-type archive --schemaId "/Christmas/"` ### export @@ -100,7 +100,7 @@ dc-cli content-type export ##### Export all content types with "Christmas" in their schema URI -`dc-cli content-type export ./myDirectory/type --schemaId "/.*Christmas.*/"` +`dc-cli content-type export ./myDirectory/type --schemaId "/Christmas/"` ### get @@ -255,7 +255,7 @@ dc-cli content-type unarchive [id] ##### Unarchive all archived content types containing "Christmas" in their URI -`dc-cli content-type unarchive --schemaId "/.*Christmas.*/"` +`dc-cli content-type unarchive --schemaId "/Christmas/"` ### update diff --git a/docs/EVENT.md b/docs/EVENT.md index e4a8cef7..58f0b207 100644 --- a/docs/EVENT.md +++ b/docs/EVENT.md @@ -6,7 +6,7 @@ The **event** category includes interactions with Dynamic Content's events and i Run `dc-cli event --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. @@ -39,15 +39,20 @@ The following options are available for all **event** commands. ### Mapping files -When importing content with the DC CLI, this creates or references a mapping file to determine whether the imported event should be created as new, or if an existing one within the Dynamic Content platform should be updated. +When importing events with the DC CLI, this creates or references a mapping file to determine whether the imported event should be created as new, or if an existing one within the Dynamic Content platform should be updated. For example exporting an event (eg `111111111111111111111111`) from one hub then importing it to another for the first time will create a new event with a randomly generated UUID (eg `222222222222222222222222`). -To instruct the DC CLI on which event 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 event mapping identified for jobs using that mapping file. Using the previous examples: +To instruct the DC CLI on which event 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 event mapping identified for jobs using that mapping file, along with its constituent parts (editions, slots, and snapshots). Using the previous examples: ``` { - "contentItems": [], + "contentItems": [ + [ + "111111111111111111111111", + "222222222222222222222222" + ] + ], "workflowStates": [], "events": [ [ @@ -76,7 +81,7 @@ To instruct the DC CLI on which event to update with future actions, a mapping b } ``` -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: +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` @@ -117,7 +122,7 @@ dc-cli event archive [id] ##### Archive all events with "Christmas" in their name -`dc-cli event archive --name "/.*Christmas.*/"` +`dc-cli event archive --name "/Christmas/"` ### export @@ -126,7 +131,7 @@ Exports events from the targeted Dynamic Content hub into the specified filesyst We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. ``` -dc-cli event archive +dc-cli event export ``` #### Options @@ -157,7 +162,7 @@ We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before Before importing events you must ensure that a valid [content item](#CONTENT-ITEM.md) exists in the destination hub for each content item contained within each event. ``` -dc-cli event archive +dc-cli event import ``` #### Options diff --git a/docs/EXTENSION.md b/docs/EXTENSION.md index dc53866b..4254abe7 100644 --- a/docs/EXTENSION.md +++ b/docs/EXTENSION.md @@ -6,7 +6,7 @@ The **extension** command category includes a number of interactions with Dynami Run `dc-cli extension --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. diff --git a/docs/HUB.md b/docs/HUB.md index eb49f971..704af1c6 100644 --- a/docs/HUB.md +++ b/docs/HUB.md @@ -8,17 +8,17 @@ These commands can be used to copy a hub's settings and content in their entiret Run `dc-cli hub --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +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) +- [Useful Information](#useful-information) + - [Mapping files](#mapping-files) + - [Media-link rewriting](#media-link-rewriting) - [Commands](#commands) - - [clone](#clone) - - [clean](#clean) + - [clone](#clone) + - [clean](#clean) @@ -59,7 +59,7 @@ To instruct the DC CLI on which content item to update with future actions, a ma } ``` -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: +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` diff --git a/docs/SEARCH-INDEX.md b/docs/SEARCH-INDEX.md index be18989c..40b74639 100644 --- a/docs/SEARCH-INDEX.md +++ b/docs/SEARCH-INDEX.md @@ -6,7 +6,7 @@ The **search-index** command category includes a number of interactions with Alg Run `dc-cli search-index --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. diff --git a/docs/SETTINGS.md b/docs/SETTINGS.md index 2e18fdc6..45059928 100644 --- a/docs/SETTINGS.md +++ b/docs/SETTINGS.md @@ -6,16 +6,16 @@ The **settings** command category includes interactions with the supporting prop Run `dc-cli settings --help` to get a list of available commands. -Return to [README.md](../README.md) for information on other command caterogies. +Return to [README.md](../README.md) for information on other command categories. - [Common Options](#common-options) - [Useful information](#useful-information) - - [Mapping files](#mapping-files) + - [Mapping files](#mapping-files) - [Commands](#commands) - - [export](#export) - - [import](#import) + - [export](#export) + - [import](#import) @@ -55,7 +55,7 @@ To instruct the DC CLI on which workflow state to update with future actions, a } ``` -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: +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` From 544061407c3810b8c78bcc8f44c2c282ac6eca24 Mon Sep 17 00:00:00 2001 From: Michael Date: Fri, 26 Nov 2021 10:17:04 +0000 Subject: [PATCH 4/7] docs: schema/item validation, content item references in events --- docs/CONTENT-ITEM.md | 2 +- docs/CONTENT-TYPE-SCHEMA.md | 4 ++-- docs/EVENT.md | 4 +++- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/CONTENT-ITEM.md b/docs/CONTENT-ITEM.md index ace28cc7..19627c0b 100644 --- a/docs/CONTENT-ITEM.md +++ b/docs/CONTENT-ITEM.md @@ -147,7 +147,7 @@ dc-cli content-item export 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. +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 diff --git a/docs/CONTENT-TYPE-SCHEMA.md b/docs/CONTENT-TYPE-SCHEMA.md index c5b264ec..e7911b9d 100644 --- a/docs/CONTENT-TYPE-SCHEMA.md +++ b/docs/CONTENT-TYPE-SCHEMA.md @@ -141,9 +141,9 @@ dc-cli content-type-schema get ### import -Imports content type schemas from the specified filesystem location to the targeted Dynamic Content hub. +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 can be found in [import usage](IMPORT_USAGE.md#CONTENT-TYPE-SCHEMAS). +More details on schema import can be found in [import usage](IMPORT_USAGE.md#CONTENT-TYPE-SCHEMAS). ``` dc-cli content-type-schema import diff --git a/docs/EVENT.md b/docs/EVENT.md index 58f0b207..80fa3460 100644 --- a/docs/EVENT.md +++ b/docs/EVENT.md @@ -88,6 +88,8 @@ If no mapping file is specified (with the `--mapFile` argument) then a default o If a mapping file does not exist at the point of import, then any imported events 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 events found within the mapping file will be updated. Any events not contained in the mapping file will will be created as new, and will then be added to the mapping file. +Content items referenced within your events' slots are not imported with the `event import` command, and will need to exist in the destination hub beforehand; these content item references will be reliant on existing mappings from a previous [content item](CONTENT-ITEM.md) import. + ### Snapshots and DC CLI The most granular part of an event in Dynamic Content is a snapshot. This is a representation of a content item exactly as it appears at the point when it was added to an edition using the content browser, or when it was saved to an edition in the production view. @@ -159,7 +161,7 @@ Imports events from the specified filesystem location to the targeted Dynamic Co We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. -Before importing events you must ensure that a valid [content item](#CONTENT-ITEM.md) exists in the destination hub for each content item contained within each event. +Before importing events you must ensure that a valid [content item](#CONTENT-ITEM.md) exists in the destination hub for each content item contained within each event, and contains an appropriate mapping within the [mapping file](#mapping-files). ``` dc-cli event import From 7a5e08c6b5536740a6ee91cc895b3d309684de69 Mon Sep 17 00:00:00 2001 From: Michael Date: Mon, 6 Dec 2021 09:29:50 +0000 Subject: [PATCH 5/7] docs: additional corrections (grammar, commands) --- README.md | 2 +- docs/CONTENT-ITEM.md | 70 ++++++++++++++++++++++---------------------- docs/EVENT.md | 4 +-- docs/HUB.md | 6 ++-- 4 files changed, 41 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 3262c075..e2c51d0b 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ These commands can be used to get details for a specific repository, list multip ### event -This category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots. These commands can be used to export and import events, and to archive events. +This category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots). These commands can be used to export and import events, and to archive events. [View commands for **event**](docs/EVENT.md) diff --git a/docs/CONTENT-ITEM.md b/docs/CONTENT-ITEM.md index 19627c0b..ab47861f 100644 --- a/docs/CONTENT-ITEM.md +++ b/docs/CONTENT-ITEM.md @@ -74,7 +74,7 @@ If a mapping file does not exist at the point of import, then any imported conte ### 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. +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` @@ -103,7 +103,7 @@ You can use regex values on string fields when filtering content. They cannot be ### 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` value 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. +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`). @@ -119,15 +119,15 @@ 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 | [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. | -| --name | [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. | -| --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. | +| 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 @@ -289,18 +289,18 @@ 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 | [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. | -| --contentType | [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. | -| --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. | +| 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 @@ -326,18 +326,18 @@ 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 | [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. | -| --contentType | [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. | -| --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. | +| 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 diff --git a/docs/EVENT.md b/docs/EVENT.md index 80fa3460..03cc848a 100644 --- a/docs/EVENT.md +++ b/docs/EVENT.md @@ -179,8 +179,8 @@ dc-cli event import ##### Import events from the filesystem -`dc-cli content-item import ./myDirectory/event` +`dc-cli event import ./myDirectory/event` ##### Specify a mapping file when importing -`dc-cli settings event ./myDirectory/event --mapFile ./myDirectory/mappingFile.json` \ No newline at end of file +`dc-cli event import ./myDirectory/event --mapFile ./myDirectory/mappingFile.json` \ No newline at end of file diff --git a/docs/HUB.md b/docs/HUB.md index 704af1c6..a5422156 100644 --- a/docs/HUB.md +++ b/docs/HUB.md @@ -68,7 +68,7 @@ If a mapping file does not exist at the point of import, then any imported conte ### 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` value 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. +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`). @@ -112,11 +112,11 @@ dc-cli hub clone ##### Clone hub from scratch -`dc-cli hub clone` +`dc-cli hub clone ./myDirectory/hub` ##### Resume a hub clone from the content item step -`dc-cli hub clone --step content` +`dc-cli hub clone ./myDirectory/hub --step content` ### clean From 673d8e6812149f3bcee7a7c8ca8c69406641b036 Mon Sep 17 00:00:00 2001 From: Michael Date: Thu, 16 Dec 2021 15:27:26 +0000 Subject: [PATCH 6/7] docs: aligning docs with upcoming release --- README.md | 7 -- docs/EVENT.md | 186 -------------------------------------------------- 2 files changed, 193 deletions(-) delete mode 100644 docs/EVENT.md diff --git a/README.md b/README.md index e2c51d0b..331d7d49 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ Run `dc-cli --help` to get a list of available commands. - [extension](#extension) - [search-index](#search-index) - [content-repository](#content-repository) - - [event](#event) - [settings](#settings) - [hub](#hub) - [Building the CLI](#building-the-cli) @@ -124,12 +123,6 @@ These commands can be used to get details for a specific repository, list multip [View commands for **content-repository**](docs/CONTENT-REPOSITORY.md) -### event - -This category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots). These commands can be used to export and import events, and to archive events. - -[View commands for **event**](docs/EVENT.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. diff --git a/docs/EVENT.md b/docs/EVENT.md deleted file mode 100644 index 03cc848a..00000000 --- a/docs/EVENT.md +++ /dev/null @@ -1,186 +0,0 @@ -# event - -## Description - -The **event** category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots. These commands can be used to export and import events, and to archive events. - -Run `dc-cli event --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) - - [Snapshots and DC CLI](#snapshots-and-dc-cli) -- [Commands](#commands) - - [archive](#archive) - - [export](#export) - - [import](#import) - - - -## Common Options - -The following options are available for all **event** 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 events with the DC CLI, this creates or references a mapping file to determine whether the imported event should be created as new, or if an existing one within the Dynamic Content platform should be updated. - -For example exporting an event (eg `111111111111111111111111`) from one hub then importing it to another for the first time will create a new event with a randomly generated UUID (eg `222222222222222222222222`). - -To instruct the DC CLI on which event 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 event mapping identified for jobs using that mapping file, along with its constituent parts (editions, slots, and snapshots). Using the previous examples: - -``` -{ - "contentItems": [ - [ - "111111111111111111111111", - "222222222222222222222222" - ] - ], - "workflowStates": [], - "events": [ - [ - "111111111111111111111111", - "222222222222222222222222" - ] - ], - "editions": [ - [ - "111111111111111111111111", - "222222222222222222222222" - ] - ], - "slots": [ - [ - "111111111111111111111111", - "222222222222222222222222" - ] - ], - "snapshots": [ - [ - "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 events 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 events found within the mapping file will be updated. Any events not contained in the mapping file will will be created as new, and will then be added to the mapping file. - -Content items referenced within your events' slots are not imported with the `event import` command, and will need to exist in the destination hub beforehand; these content item references will be reliant on existing mappings from a previous [content item](CONTENT-ITEM.md) import. - -### Snapshots and DC CLI - -The most granular part of an event in Dynamic Content is a snapshot. This is a representation of a content item exactly as it appears at the point when it was added to an edition using the content browser, or when it was saved to an edition in the production view. - -Due to this nature of snapshots, the event import command will not always result in an exact copy of the events exported with the event export command. Whilst the properties of the parent edition and event will match those of the source, the snapshots will be created as new. If a snapshotted content item in the source hub's exported events have been updated since the snapshot was created, then it will be the updated version of that content item which will be created as snapshots in the destination hub. - -## Commands - -### archive - -Archives events and their child edition in the targeted Dynamic Content hub, and will also unschedule them if they have not yet started. - -This command requires either an event ID or name to filter, and will not archive any events if no filter is provided. - -``` -dc-cli event archive [id] -``` - -#### Options - -| Option Name | Type | Description | -| ----------------- | --------- | ------------------------------------------------------------ | -| --name | [string] | The name of an Event 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 event pattern.
Multiple --name options may be given to match multiple events' patterns at the same time, or even multiple | -| -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. | - -#### Examples - -##### Archive event with the ID of "foo" - -`dc-cli event archive foo` - -##### Archive all events with "Christmas" in their name - -`dc-cli event archive --name "/Christmas/"` - -### export - -Exports events from the targeted Dynamic Content hub into the specified filesystem location. - -We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. - -``` -dc-cli event export -``` - -#### Options - -| Option Name | Type | Description | -| ----------- | --------- | ------------------------------------------------------------ | -| --id | [string] | Export a single event by ID, rather then fetching all of them. | -| --fromDate | [string] | Start date for filtering events.
Either "NOW" or in the format "\:\", example: "-7:DAYS". | -| --toDate | [string] | To date for filtering events.
Either "NOW" or in the format "\:\", example: "-7:DAYS". | -| --snapshots | [boolean] | Save content snapshots with events, in subfolder "snapshots/". | - -#### Examples - -##### Export all events from a Hub - -`dc-cli event export ./myDirectory/event` - -##### Export all events which start 7 days from now from a Hub - -`dc-cli event export ./myDirectory/event --fromDate "+7:DAYS"` - -### import - -Imports events from the specified filesystem location to the targeted Dynamic Content hub. - -We recommend reading about [snapshots and DC CLI](#snapshots-and-dc-cli) before exporting or importing events. - -Before importing events you must ensure that a valid [content item](#CONTENT-ITEM.md) exists in the destination hub for each content item contained within each event, and contains an appropriate mapping within the [mapping file](#mapping-files). - -``` -dc-cli event import -``` - -#### Options - -| Option Name | Type | Description | -| --------------- | --------- | ------------------------------------------------------------ | -| --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 existing events, editions, slots and snapshots without asking. | -| --originalIds | [boolean] | Use original IDs. | - -#### Examples - -##### Import events from the filesystem - -`dc-cli event import ./myDirectory/event` - -##### Specify a mapping file when importing - -`dc-cli event import ./myDirectory/event --mapFile ./myDirectory/mappingFile.json` \ No newline at end of file From 13fe2e92ae91d131cbc75504c3fa8d7daac889a2 Mon Sep 17 00:00:00 2001 From: Michael Date: Thu, 16 Dec 2021 15:32:02 +0000 Subject: [PATCH 7/7] docs: aligning docs with upcoming release --- docs/HUB.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/HUB.md b/docs/HUB.md index a5422156..17558ccd 100644 --- a/docs/HUB.md +++ b/docs/HUB.md @@ -83,7 +83,6 @@ Exports all of the following (where applicable) from the source hub, then import * Content Type Schemas * Content Types * Content Items -* Events * Search Indexes ```