Starting January 1, 2025, we will no longer provide maintenance or updates for the CLI ImpEx tools. After this date, this tool will no longer receive bug fixes, security patches, or new features.
This component allows you to manage the category tree of your commercetools project by importing, updating and exporting categories via CSV files.
In general the command uses sub-commands for the different tasks.
Base options are:
./bin/category-sync
Usage: bin/category-sync <command> [options]
Commands:
export Export categories
import Import categories
Options:
-p, --project-key project key [required]
-i, --client-id client id
-s, --client-secret client secret
--language Language used for slugs when referencing parent.
[default: "en"]
--parentBy Property used to reference parent - use externalId or
slug or id [default: "externalId"]
--continueOnProblems Continue with creating/updating further categories even
if API returned with 400 status code.
[boolean] [default: false]
-h, --help Show help
--verbose Add more information regarding the current run
--debug Add information to debug
--version Show version number
The tool uses the API to talk to SPHERE.IO and therefore needs the 3 access properties - project key, client id and client secret. For automation reason you may use our project credentials files to avoid passing the credentials via command line options.
When you provide a wrong argument or one argument is missing the tool will inform you. Please have a look at the last line of the output. You might find some useful hints like this one:
Missing required arguments: p
The command line to import or update categories is shown below:
Usage: bin/category-sync -p <project-key> import -f <CSV file>
Options:
-f, --file CSV file name [required]
--sort true/false Sort CSV file before importing [boolean] [default: true]
Examples:
bin/category-sync -p my-project-42 Import categories from
import -f categories.csv "categories.csv" file into SPHERE
project with key "my-project-42".
During import we match categories to existing categories according to the externalId. If a category with the same externalId is found we will call it an update as the tool will then update the existing category properties - like name etc. - to those values defined in the CSV file.
If no matching category is found the tool will create a new one.
The import sub-command will never delete a category.
When importing categories, the right order has to be provided to ensure that the category parent already exists before importing a category. For this purpose you can specify a --sort parameter which will preprocess categories and sort them before importing.
This tool can import also category custom fields. First, the CTP API type with custom field definitions has to be created. Example type can look like this.
After the type has been created, categories with custom fields can be imported:
name.en,key,externalId,slug.en,customType,customField.number
categoryName,categoryKeys,categoryExternalId,category-en-slug,customTypeKey,123
More detailed example of CSV with various custom fields can be found here.
To export categories, you can pass a CSV file as template. The template needs to contain only the header. This will allow you to define the content of the output file to your specific needs. Please have a look at the CSV Format section for the different headers supported. If no template is provided using the `-t' parameter, all possible category attributes will be exported incl. all localisations.
The command line to export categories into a CSV file is:
Usage: bin/category-sync -p <project-key> [options] export -t <CSV file> -o <CSV file>
Options:
-t, --template CSV template file name
-o, --output CSV output file name [required]
Examples:
bin/category-sync -p my-project-42 Export categories from SPHERE
export -t header.csv -o output.csv project with key "my-project-42"
into "output.csv" file using the
template "header.csv".
bin/category-sync -p the-project-1 Export categories from SPHERE
export -o my.csv project with key "the-project-1"
into "my.csv".
A category without a parent is called root category. All other categories have a parent.
To define a parent by default you provide the externalId of the parent category.
externalId,name,parentId
root123,Root Category,
sub123,Sub Category,root123
But you may also use the slug to reference your parent category.
name,slug.en,parentId
Root Category,root-cat,
Sub Category,sub-cat,root-cat
Ensure that you have set the right language to choose the slug. By default it's English.
In general the CSV is built up of a header row and the content rows. We support the following headers:
- name: localized name for the category
- description: category's description in different languages
- slug: internationalized slugs for the category
- key: key of the category defined by the user
- externalId: id of the category defined by the user
- parentId: id of the parent category - we reference other categories by
externalIdhere - orderHint: a string that is used to order categories of the same parent. We recommend to use values between
0.1and0.9. - metaTitle: localized title of category for search engines
- metaDescription: localized description to be used by search engines
- metaKeywords: localized SEO keywords for the category
- custom: custom fields
Further you might use the following header during export:
- id: id of category in SPHERE.IO
- createdAt: The UTC time stamp when the category was created.
- lastModifiedAt: The UTC time stamp when the category was changed the last time.
Please find some examples in the data folder or in the acceptance tests of the tool in the *.feature located here.
Please note that there is no order in the header.
We support importing categories from JSON file. The import file should be in compliance with the following schema:
{
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"externalId": {
"type": "string"
},
"name": {
"$ref": "/ltext"
},
"slug": {
"$ref": "/ltext"
},
"description": {
"$ref": "/ltext"
},
"orderHint": {
"type": "string"
},
"parent": {
"$ref": "/reference"
}
},
"required": ["name", "slug"]
}
}
}For importing JSON file, please use the cli Expected configuration options are:
- language: (en / de) localization language
- parentBy: (externalId, slug)
A sample cli command is as follows:
./bin/sphere import -p my-project-key -t category -f testCategories.json -c '{"language":"de", "parentBy":"externalId"}'
#Different languages for the same attribute are defined by a suffix to the actual header delimited by a . - examples are name.de or slug.en. You may define as many languages as you want for those attributes.
This module can also export custom fields from category object.
When given the following template, exporter will store custom.type.key in a customType column and customField.* columns will be filled with corresponding custom fields.
key,slug.en,customType,customField.number,customField.moneyAttr
Output:
categoryKey,categorySlugEn,customTypeKey,123,9876 EUR
More advanced CSV template for exporting custom fields can be found here.
If you just want to use the tool, we recommend to use SPHERE.IO's impex platform to avoid any local installation - you only need your browser.
Nevertheless, running the program locally, you need NodeJS installed and simply run the following command in your terminal:
npm install sphere-category-sync
./node_modules/.bin/category-sync
#You may also install it globally if you have sufficent rights on your computer:
npm install -g sphere-category-sync
category-sync
#-
Clone this repository and change into the directory
-
Install all necessary dependencies with
npm install
-
Convert CoffeeScript into JavaScript by
npm run build
-
To run the test do:
npm test -
To run the tests on each change you do to any
*.coffeefile runnpm run watch:test