DXP PURLs CLI
Installation
The DXP PURL CLI uses Node 8+ and is installed using NPM. It works best when installed globally.
$ npm i -g @viewdo/dxp-purl-cli
Usage & Global Options
Figure out how to use this damn thing.
$ dxp-purl <flags> [command] <...args>
Global Options:
-V, --version output the version number
-h, --help output usage information
Commands:
init|i [options] Set up the environment variables for a working output
login|l [options] [email] Authenticates to the output using email verification code
config|c [options] Set up the config file for batch urls. Use a story key to auto configure it (requires login).
shorten|s [options] <url> Shortens the url using the DXP URL shortener
transform|t [options] <url> <custom-url> Transforms the url using the DXP URL shortener
personalize|p [options] <url> <template> Creates a personalized URL using the DXP URL personalize service
batch|b [options] [source] Convert a CSV file to XLinks and optionally a custom URL redirect. You must have a config file to run batch.
INIT : Getting Started
The first thing the tool needs to do is initialize a workspace on the filesystem. Like NPM, the init function will prompt the developer about basic settings and hold them in two small files at the root of the workspace.
$ dxp-purl init|i [options]
Set up the environment variables, login and configure the working directory.
Options:
-D, --debug Debug output.
-e, --environment <env> Environment to use against [local|dev|stage]
-E, --email <email> Email address of the current user
-h, --help output usage information
Environments
The environment determines which iVX environment endpoints will be used to upload the asset.
- local
- develop
- stage
- production
LOGIN : Authentication
We need to make sure this tool can only be used by authorized StoryAdmins (w/AssetManagement grant in production). This means we need to authenticate the user or server for a token with permission to update the assets. We should use our Auth0 to authenticate this tool in one of two modes, interactive or application.
Mode: Interactive
By default, this tool requires user credentials with permission to update the story assets. credentials and will prompt the user into the login-flow below, using the passwordless-email option in Auth0. No passwords will ever be transmitted or collected. However, the tokens should be saved in a location that allows the token to be reused if the command is run again.
$ dxp-purl login|l [options] [email]
Authenticates to the output using email verification code
Options:
-D, --debug Debug output.
-e, --environment [env] Environment to use against [local|dev|stage] (default: dev)
-E, --email <email> Your email address (for authentication)
-c, --code <code> Email verification code (default: null)
-t, --token <token> An existing token to write to the output
-f, --force Force new authentication
-h, --help Output usage information
Mode: Application
If we initialize Auth0 as Machine-to-Machine application and provide environment variables for the ClientID and ClientSecret for the client, this tool can authenticate as itself from the build-server with the special permissions needed to push assets to production.
Environment Variables:
- IVX_ENVIRONMENT
- AUTH0_CLIENT_ID
- AUTH0_CLIENT_SECRET
Shorten
Shortens the url using the DXP URL shortener
$ dxp-purl shorten|s [options] <url>
Options:
-D, --debug Debug output.
-e, --environment <env> Environment to use against [local|dev|stage]
-c, --custom-url <url> Custom URL to use with the shortener.
-k, --key <key> The story key
-h, --help output usage information
Personalize
Creates a personalized URL using the DXP URL personalize service
$ dxp-purl personalize|p [options] <url> <template>
Options:
-D, --debug Debug output.
-e, --environment <env> Environment to use against [local|dev|stage]
-k, --key <key> The story key
-h, --help output usage information
Transform
Transforms the url using the DXP URL shortener
$ dxp-purl transform|t [options] <url> <custom-url>
Options:
-D, --debug Debug output.
-f, --force Forces an overwrite if the custom URL already exists.
-e, --environment <env> Environment to use against [local|dev|stage]
-h, --help output usage information
Batch Config
Set up the config file for batch urls. Use a story key to auto configure sing the story data and local defaults (requires login).
$ dxp-purl batch-config|bc [options]
Options:
-D, --debug Debug output.
-s, --source <path> File path to source csv file
-o, --output <path> File path for output csv
-k, --key <key> The story key
-h, --help output usage information
Configuration with CSV file headers : ./batch-config.json
The dxp-purl-config file configures the 'batch' command, used for . There are two ways to map X
{
"source": "./sample-big.csv",
"has_header": true,
"story_key": "tech-sample",
"user_key": null,
"url_pattern": "http://sample-story/lucky-${id}",
"url_strategy": "transform", (or shorten or personalize)
"column_map": {
"id": "Id",
"email": "Email",
"name": "Name",
"phone": "Phone",
"color": "Color"
},
"additional_data": {
"useExisting": true,
"campaignKey": "test"
},
"days_to_live": 1
}
Configuration without CSV file headers : ./dxp-purl-config.json
The dxp-purl-config file configures the 'batch' command, used for . There are two ways to map X
{ "source": "./sample-big.csv", "has_header": false, "story_key": "tech-sample", "user_key": null, "url_pattern": "http://sample-story/${id}", "column_map": { "id": 1, "email": 0, "name": 4, "phone": 5, "color": 6 }, "additional_data": { "useExisting": true, "campaignKey": "test" }, "days_to_live": 1 }
url_pattern works just like JavaScript string interpolation, using the mapped input keys.
Batch
Convert a CSV file to XLinks and optionally a custom URL redirect. You must have a config file to run batch.
Here be dragons
$ batch|b [options] [source]
Options:
-c, --config Batch config file (default batch-config.json)
-o, --output Output file
-k, --key <key> The story key. This creates batch-config.<story-key>.json config file
-D, --debug Turns on debug console messages
-p, --preview Dry-run to preview and test
-e, --environment <env> iVX environment to use [local|dev|stage]
-h, --help output usage information
Examples
dxp-purl batch ./some-csv-file.csv
Multiple Configs
If you have more than one config you are testing.
dxp-purl batch -c ./test-config.json -p
Multiple story folders
This uses the config file convention './batch-config.<key>.csv '
dxp-purl batch -k <story-key> -p
Redirects Config
Set up the config file for redirects urls.
dxp-purl redirect-config|rc [options]
Sample config:
redirects:
- customUrl: 'http://admin.to.viewdo.run/'
targetUrl: 'https://app.dxp.media/administration'
daysToLive: 90
- customUrl: 'http://app.to.viewdo.run/'
targetUrl: 'https://app.dxp.media'
daysToLive: 90
Options:
-c, --config <config> Config file name
-D, --debug Debug output.
-h, --help output usage information
Apply Redirects
Apply redirects as configured in the redirects-config.yml file.
dxp-purl apply-redirects|r [options] [source]
Options:
-c, --config Redirects config file (default redirects-config.yml)
-D, --debug Turns on debug console messages
-p, --preview Dry-run to test things out. Creates the URLs in output, but they won't work
-e, --environment <env> DXP environment to use [local|dev|stage]
-h, --help output usage information
Execute w/ Docker
docker run -v ${cwd}/:/src dxp-purl-cli [command]
RELEASE NOTES
This package is not tested and has very little error-handing.
Use caution whenever performing batch-anything.
Development
Skip the NPM Install and instead use this repository as a real-time CLI. After cloning this repository, from this directory use yarn to sym-link as a cli without installing it globally.
yarn link