Data-ops is a CLI tool for managing data in your Kontent.ai projects. It suppports complex operations such as:
- Import data
- Export data
- Sync data across environments
- Migrations execution
It runs in Node.js with ESM support (lts).
We recommend running data-ops with npx
. Be aware that npx
calls the cached version of the tool. Use @latest
to ensure you're using the latest version.
Use `-h` or `--help` anytime to get information about available commands and their options.
npx @kontent-ai/data-ops@latest --help
# or
yarn dlx @kontent-ai/data-ops --help
# help for a specific command
npx @kontent-ai/data-ops@latest <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
) - we recommend this approach - 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@latest <command-name> <command-options>
The documentation for individual commands are provided in the README.md files located in each command's respective folder (./src/commands). Data-ops supports the following commands:
- import & export
- clean
- sync-model
- sync-content
- migrations
Note
All command functions are publicly exposed, making it easy to include them in your scripts
npm ci
to install packagesnpm run build
to compile the toolnode 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 testsnpm 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)npm run test:advancedDiff
compares generated advanced diff with a test baseline. Part of integration tests.
To sucesfully execute integration tests, you need to prepare a Kontent.ai project with corresponding environments. You can use the import command to import prepared zip files located at tests/integration/<testName>/data/<zipName>.zip
.
All Kontent.ai test enviroments are exported in tests/integration/<testName>/data/<zipName>.zip
. When you update any of these environments, you should also update the corresponding exported zip files. To streamline this process, we've provided a script called exportTestEnvironments.js
. You can run it with the command npm run export:testEnv
. If you need to export specific environments, you can use the following command parameters: -i
for Import/Export test environment, -s
for Sync Source Template environment, and -t
for Sync Target Template environment. For instance, to export only the Sync Source and Sync Target environments, you would run npm run export:testEnv -- -s -t
.
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 located in the src
folder.
The project is structured around commands, with each command defined on the yargs object in a folder of the same name within the src/commands
folder.
The exported register
function (of type RegisterCommand
) must be included in src/index.ts
in the commandsToRegister
array.
Tests can be found in tests/integration
and tests/unit
folders.
Integration tests require Kontent.ai environments and a valid MAPI key for successful execution.
You can use the withTestEnvironment
function to provide the tests with a new empty environment.
Please note that creation and removal of new environments takes some time, therefore try to keep the number of environment-dependent tests to a minimum.