Data-ops is a CLI tool for working with data in your Kontent.ai projects. It runs in Node.js with ESM support (lts).
We recommend running data-ops with npx
.
Use -h
or --help
anytime to get information about available commands and their options.
npx @kontent-ai/data-ops --help
# or
yarn dlx @kontent-ai/data-ops --help
# help for a specific command
npx @kontent-ai/data-ops <command> --help
# you can also install the package globally, or locally
npm i @kontent-ai/data-ops -g
# with the package installed, you can call the tool as follows
data-ops --help
All options (including options for commands) can be provided in three different ways:
- As command-line parameters (e.g.
--environmentId xxx
) - In a
json
configuration file (e.g.--configFile params.json
) - As environment variables with
DATA_OPS_
prefix and transformed into UPPER_SNAKE_CASE (e.g.DATA_OPS_ENVIRONMENT_ID=xxx @kontent-ai/data-ops ...
)
The tool usage is based on commands provided in the following format:
npx @kontent-ai/data-ops <command-name> <command-options>
With the export
command, you can export data from your Kontent.ai environment into a single .zip
file.
The command uses the Management API to get the environment data.
npx @kontent-ai/data-ops export --environmentId=<environment-id-to-export> --apiKey=<Management-API-key>
To see all supported parameters, run npx @kontent-ai/data-ops export --help
.
The exported .zip
package contains a .json
file for each exported entity and a metadata.json
file with additional information.
Format of all the entities is compatible with the output of the Management API.
[!TIP] If you need the data in a different format, you can process the
.zip
data with a variety of other tools to transform it as per your requirements.
- output.zip
|- assetFolders.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Asset-folders
|- assets
|- All the asset files named <assetId>-<fileName>
|- assets.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Assets
|- contentItems.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Content-items
|- contentTypeSnippets.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Content-type-snippets
|- languageVariants.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Language-variants
|- languages.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/languages
|- metadata.json # version, timestamp, environmentId
|- previewUrls.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Preview-URLs
|- roles.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Roles
|- workflows.json # https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#tag/Workflows
You can check out exported data of an example project in the data for integration tests.
[!CAUTION] Exporting roles requires the Enterprise plan.
If you don't want to export roles, you can specify them in the
--exclude
parameter or select only the other entities in the--include
parameter (e.g.npx @kontent-ai/data-ops export ... --exclude roles
).To get more information about the parameters or what other parameters are available, run
npx @kontent-ai/data-ops export --help
.
With the import
command, you can import data into your Kontent.ai environment.
The command uses the Management API to import the data.
[!CAUTION] The target environment needs to be empty, otherwise the command might fail (e.g. when there are entities with the same codename already present).
[!TIP] The command expects the data for import in a
.zip
file in the same structure that is produced by the export command.If you want to import data from a different structure, you can use any available tool to convert it into the supported format.
npx @kontent-ai/data-ops import --fileName <file-to-import> --environmentId <target-environment-id> --apiKey <Management-API-key>
To see all supported parameters, run npx @kontent-ai/data-ops import --help
.
The clean
command allows you to delete data in your Kontent.ai environment using the Management API.
[!WARNING] Running this command may result in irreversible changes to your content. Proceed with caution to avoid any unintended data loss.
[!TIP] You can select specific subset of entities to clean using either
include
orexclude
parameter. Note that the clean operation will fail if you attempt to delete an entity with existing dependants (e.g. a content type with existing items based on it).
npx @kontent-ai/data-ops clean --environmentId <target-environment-id> --apiKey <Management-API-key>
To see all supported parameters, run npx @kontent-ai/data-ops clean --help
.
Roles and asset type entities are currently not being exported due to API limitations. The tool also can't set role limitations when importing workflows.
Since the API format doesn't support language variants with both a published version and a draft version, only the newest version will be exported or imported. Published language variants that don't exist in any other workflow step are exported correctly.
As the current API format doesn't support inclusion of the publishing time for variants scheduled to be published, the tool instead puts the scheduled variants into the draft step (the first step in the workflow).
Web Spotlight currently can't be enabled/disabled through the tool. As a result, it is not possible to set root item for spaces as this can only be done on environments with Web Spotlight enabled. Furthermore, the clean
operation cannot delete the root type associated with Web Spotlight as long as it's enabled and therefore skips it.
The management API accepts only assets smaller than 100MB. If your export file contains assets bigger than that (they can be uploaded through the UI), the tool won't be able to import them.
The tool leverages the Management API to work with the project data and thus is bound by the API rate limitations.
-
npm ci
to install packages -
npm run build
to compile the tool -
node build/src/index.js --help
to run (ornpm run start -- --help
)
The tool is transpiled into the build
folder.
TypeScript in tests is handled by ts-jest.
-
npm run test:unit
to run unit tests -
npm run test:integration
to run integration tests (these create temporary Kontent.ai environments and delete them afterwards, interrupting the tests while they're running may lead to orphaned environments in your project)
The configuration is only necessary to run the integration tests.
- Copy the
.env.template
into.env
(cp .env.template .env
) - Fill in the values (each value is explained in comments in the template)
The main part of the tool is in the src
folder.
The project is structured around commands, with each command defined on the yargs object in its own file (with the same name) in the src/commands
folder.
The exported register
function (of type RegisterCommand
) must be included in src/index.ts
in the commandsToRegister
array.
You can find tests in the tests/integration
and tests/unit
folders.
Integration tests require Kontent.ai environments and a valid MAPI key to run.
You can use the withTestEnvironment
function to provide the tests with a new empty environment.
Try to limit the number of tests that require the environment as it takes some time to create and remove it.