kontent-ai-consulting/kontent-ai-model-accelerator

Tool for importing prepared content models from Kontent.ai’s content model accelerators.

Kontent.ai Model Accelerator

Tip

The idea behind this tool is to export & import content model structures to & from Kontent.ai environments. Data is both exported and imported via Management Api into a specified json format.

Getting started

We recommend running @kontent-ai-consulting/content-model-accelerator with npx. Use --help anytime to get information about available commands and their options.

npx @kontent-ai-consulting/content-model-accelerator --help

# you can also install the package globally, or locally
npm i @kontent-ai-consulting/content-model-accelerator -g

# with the package installed, you can call the tool as follows
kontent-ai-accelerator --help

Use via CLI

Configuration

Config	Value
environmentId	Id of Kontent.ai environment (required)
apiKey	Management API key (required)
action	One of (export, list, remoteImport or fileImport) (required)
filename	Filename used to export or import
model	Codename of the remote model (required for remoteImport)
contentTypes	Comma-separated list of codenames. May be used to import only selected content types
contentTypeSnippets	Comma-separated list of codenames. May be used to import only selected content type snippets
taxonomies	Comma-separated list of codenames. May be used to import only selected taxonomies
debug	If set to true, full error messages are shown in console log
force	If set to true, confirmation prompt is disabled

Execution

Caution

We do not recommend importing into a production environment directly (without proper testing). Instead you should first create a testing environment and run the script there to make sure everything works as you intended to.

# List default accelerator models
kontent-ai-accelerator --action=list

# Export existing model to json
kontent-ai-accelerator --action=export --environmentId=xxx --apiKey=yyy --filename=my-export.json

# Import from file to an existing environment
kontent-ai-accelerator --action=fileImport --environmentId=xxx --apiKey=yyy --filename=my-export.json

# Import from the default accelerator model
kontent-ai-accelerator --action=remoteImport --environmentId=xxx --apiKey=yyy --model=advanced_model

# Import only parts from the default accelerator model
kontent-ai-accelerator --action=remoteImport --environmentId=xxx --apiKey=yyy --model=advanced_model --contentTypes=link --contentTypeSnippets=metadata --taxonomies=persona,product_type

# To get some help you can use:
kontent-ai-accelerator --help

kontent-ai-model-accelerator's Issues

Rename "project" attribute

Motivation

Due to the historical meaning of "project" in Kontent.ai, I would recommend changing --project= to --accelerator=

Although the accelerators are projects in their original form, this is internal and external customers never experience the accelerators as projects; only as targettable entities that they can import via codenames.

Validation error thrown when using the --taxonomies flag

Brief bug description

When using the command:

kontent-ai-accelerator --action=remoteImport --environmentId=<removedForIssue> --apiKey=<removedForIssue> --model=advanced_product --taxonomies=persona

error:
Error: The provided request body is invalid. See 'validation_errors' for more information and specify a valid JSON object. The referenced taxonomy group '{external id: b84ac429-274c-428d-ab8f-86f039664e4c}' was not found. Provide a reference to an existing taxonomy group.

The accelerator fails with a validation error as a taxonomy that is referenced within the "advanced_product" model is excluded due to the --taxonomies specification.

Repro steps

1. Run kontent-ai-accelerator --action=remoteImport --environmentId=<removedForIssue> --apiKey=<removedForIssue> --model=advanced_product --taxonomies=persona

Expected behavior

The taxonomies flag should import only the targetted taxonomy group, and not attempt to import the content types that reference it, to avoid reference errors.

'prompts' import error is thrown during remoteImport

Brief bug description

The addition of "prompts" has resulted in the remoteImport throwing an error:

cmd:
kontent-ai-accelerator --action=remoteImport --environmentId=<removedForIssue> --apiKey=<removedForIssue> --model=advanced_person

error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'prompts' imported from C:\Users\MichaelB\AppData\Roaming\npm\node_modules\@kontent-ai-consulting\content-model-accelerator\dist\es2022\lib\core\global-helper.js at new NodeError (node:internal/errors:400:5) at packageResolve (node:internal/modules/esm/resolve:889:9) at moduleResolve (node:internal/modules/esm/resolve:938:20) at defaultResolve (node:internal/modules/esm/resolve:1153:11) at nextResolve (node:internal/modules/esm/loader:163:28) at ESMLoader.resolve (node:internal/modules/esm/loader:842:30) at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18) at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40) at link (node:internal/modules/esm/module_job:76:36) { code: 'ERR_MODULE_NOT_FOUND' }

After installing "prompts" as a separate package globally, the remoteImport still fails silently.

Importing content types that contain existing snippets fails

Brief bug description

Replacing an existing content type with an Accelerator that has the same codename fails if it contains a content type snippet. Full cmd debug attached.

cmd used:
kda --action=remoteImport --environmentId=<envIdOmittedFromIssue> --apiKey=<apiKeyOmittedFromIssue> --project=basic_organization

Repro steps

1. Go to a project containing an already imported "Organization" content type
2. Delete the existing content type
3. Use the remoteImport cmd to import the basic_organization Accelerator from the master project to the target project
4. See attached error

Expected behavior

The import will ignore the metadata snippet, provide a message, and import successfully (similar to other pre-existing elements).

Debug:

debug-log-failed-due-to-snippet.txt

Add confirmation dialogue prior to executing imports/exports

Motivation

Users may need to consider what is about to be imported before executing a remote import.

Proposed solution

Raise a dialogue in the terminal that contains a readout of:

1. what is about to be imported
2. what the name of the accelerator is
3. what the name of the target environment is
4. a final "Y/N" confirmation that kicks off the import process

Additional context

The feature was originally requested by Jan Cerman.

README feedback

Motivation

The Execution section with commands confused some of my testers and required re-reading the README or using the kda --help command to understand.

Proposed solution

A diagram & summary of how the tool works behind the scenes could help users understand what the tool is for and how to leverage it. Each action should contain some summary/description and a practical example.

Additional comment

When we get final approval for naming, kda as an action command should likely be replaced.

Using contentTypes flag leads to misleading prompts

Motivation

When using the --contentTypes= flag to target a specific content type in the model, the prompt suggests that all content types in the model will be imported.

Example command:

kontent-ai-accelerator --action=remoteImport --environmentId=<removedForIssue> --apiKey=<removedForIssue> --model=advanced_product --contentTypes=disclaimer

Terminal output:

√ Are you sure to import models into Empty Environment environment of project zKDA Test? ... yes
Fetch: Downloading template 'advanced_product'
Content Types: Compliance, Video, Product, Disclaimer, Resource, Link, Call to action
Snippets: Metadata
Taxonomies: Product Type, Persona, Resource Type, Compliance Type, Category, Disclaimer Type
√ Continue import with the models above? ... yes

The tool does work in that it only imports the specified type, but the dialogue is confusing.

Proposed solution

Potential solution A: list only the specified content type in the "Content Types:" portion of the prompt.

Potential solution B: change the terminology from "Content Types:" to "All Content Types in Model:" and the confirmation message states: "Continue import with the specified models?"

Taxonomies command not working with multiple codenames

Brief bug description

The comma delimiter in the --taxonomies command does not work. Console displays:
[Warning][persona product_type]: Could not find taxonomy with given codename

Repro steps:

Command run:
kda --action=remoteImport --environmentId= --apiKey=<apiKeyOmittedFromIssue --project=basic_product --taxonomies=persona, product_type

Expected behavior

The two taxonomies from the basic_product should be imported from the master project to the target environment.

Tool does not proceed after "Fetch"

Brief bug description

After confirming the prompt to import the models, the terminal exits the command.

Repro steps

1. Run:
   kontent-ai-accelerator --action=remoteImport --environmentId=<removedForIssue> --apiKey=<removedForIssue> --model=advanced_person
2. Type "y" to confirm the prompt
3. See "Fetch" message and the command stops.

Expected behavior

1. Import informs the user of what is being imported and completes successfully.

Minor edit:

The "prompt" has a lowercase "y" and an uppercase "N" for options.

Export command fails with Error: taxonomiesRaw.trim is not a function

Brief bug description

When creating a new export.json file for advanced product, the accelerator CLI command fails with: Error: taxonomiesRaw.trim is not a function .

Repro steps

Command used:

npx @kontent-ai-consulting/content-model-accelerator --action=export -environmentId=<redacted_for_GH_Issue> --apiKey=<redacted_for_GH_Issue> --filename=product-model-advanced.json

Expected behavior

Command finishes without error.

Additional context

The method in the error is found at:

kontent-ai-model-accelerator/lib/node/cli/app.ts

Line 289 in 08ed4f3

taxonomies: taxonomiesRaw

Contact @mberry1989 for the source project ID and MAPI key, if needed.