@viewdo/dxp-url-cli

1.0.18 • Public • Published

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 🐉 Always test the batch using the preview flag(-p)🐉 View the output file and double-check the XLinks work as expected, THEN run without the flag🐉

$ 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

Readme

Keywords

none

Package Sidebar

Install

npm i @viewdo/dxp-url-cli

Weekly Downloads

1

Version

1.0.18

License

ISC

Unpacked Size

64.2 kB

Total Files

33

Last publish

Collaborators

  • mrdav30
  • jasonwicker-archer
  • dkliewerarcher
  • jasonwicker
  • m.cutri