{"id":19622146,"url":"https://github.com/commercetools/sphere-category-sync","last_synced_at":"2025-04-28T03:32:24.014Z","repository":{"id":15832972,"uuid":"18572915","full_name":"commercetools/sphere-category-sync","owner":"commercetools","description":"Manage your SPHERE.IO category tree","archived":false,"fork":false,"pushed_at":"2024-11-17T12:08:47.000Z","size":753,"stargazers_count":4,"open_issues_count":36,"forks_count":4,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-20T15:17:59.489Z","etag":null,"topics":["audit-import-export"],"latest_commit_sha":null,"homepage":"https://docs.commercetools.com","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commercetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-04-08T19:57:35.000Z","updated_at":"2024-11-17T12:08:50.000Z","dependencies_parsed_at":"2024-10-23T13:05:54.898Z","dependency_job_id":null,"html_url":"https://github.com/commercetools/sphere-category-sync","commit_stats":{"total_commits":229,"total_committers":23,"mean_commits":9.956521739130435,"dds":0.4759825327510917,"last_synced_commit":"d07211ebdd5f09ce9487198ff08b4be73c19eb99"},"previous_names":["sphereio/sphere-category-sync"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fsphere-category-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fsphere-category-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fsphere-category-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fsphere-category-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercetools","download_url":"https://codeload.github.com/commercetools/sphere-category-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251246341,"owners_count":21558762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit-import-export"],"created_at":"2024-11-11T11:26:12.907Z","updated_at":"2025-04-28T03:32:24.009Z","avatar_url":"https://github.com/commercetools.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"background-color: yellow; color: black; padding: 10px; text-align: center; font-weight: bold;\"\u003e\n  \u003ch2\u003e🚨 Non-maintainable 🚨\u003c/h2\u003e\n  \u003cp\u003eStarting 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.\u003c/p\u003e\n\u003c/div\u003e\n\n\n\u003cimg src=\"https://impex.europe-west1.gcp.commercetools.com/static/images/ct-logo.svg\" alt=\"commercetools logo\" width=\"200\"\u003e\n\n# Category sync\n\n[![Build Status](https://travis-ci.org/sphereio/sphere-category-sync.png?branch=master)](https://travis-ci.org/sphereio/sphere-category-sync) [![Coverage Status](https://coveralls.io/repos/sphereio/sphere-category-sync/badge.png)](https://coveralls.io/r/sphereio/sphere-category-sync) [![Dependency Status](https://david-dm.org/sphereio/sphere-category-sync.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-category-sync) [![devDependency Status](https://david-dm.org/sphereio/sphere-category-sync/dev-status.png?theme=shields.io)](https://david-dm.org/sphereio/sphere-category-sync#info=devDependencies)\n\nThis component allows you to manage the category tree of your commercetools project by importing, updating and exporting categories via CSV files.\n\n# Usage\n\nIn general the command uses sub-commands for the different tasks.\n- [import and update](#import)\n- [export](#export)\n\nBase options are:\n```\n./bin/category-sync\nUsage: bin/category-sync \u003ccommand\u003e [options]\n\nCommands:\n  export    Export categories\n  import    Import categories\n\nOptions:\n  -p, --project-key     project key         [required]\n  -i, --client-id       client id\n  -s, --client-secret   client secret\n  --language            Language used for slugs when referencing parent.\n                                                                 [default: \"en\"]\n  --parentBy            Property used to reference parent - use externalId or\n                        slug or id                       [default: \"externalId\"]\n  --continueOnProblems  Continue with creating/updating further categories even\n                        if API returned with 400 status code.\n                                                      [boolean] [default: false]\n  -h, --help            Show help\n  --verbose             Add more information regarding the current run\n  --debug               Add information to debug\n  --version             Show version number\n```\nThe 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](https://github.com/sphereio/sphere-node-utils#projectcredentialsconfig) to avoid passing the credentials via command line options.\n\nWhen 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:\n```\nMissing required arguments: p\n```\n\n## Import\n\nThe command line to import or update categories is shown below:\n```\nUsage: bin/category-sync -p \u003cproject-key\u003e import -f \u003cCSV file\u003e\n\nOptions:\n  -f, --file            CSV file name                          [required]\n  --sort true/false     Sort CSV file before importing  [boolean] [default: true]\n\nExamples:\n  bin/category-sync -p my-project-42          Import categories from\n  import -f categories.csv                    \"categories.csv\" file into SPHERE\n                                              project with key \"my-project-42\".\n```\n\nDuring 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.\nIf no matching category is found the tool will create a new one.\nThe `import` sub-command will never delete a category.\n\nWhen 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.\n\n### Importing custom fields\nThis tool can import also category custom fields. First, the [CTP API type](https://docs.commercetools.com/http-api-projects-types) with custom field definitions has to be created. Example `type` can look like [this](/data/customTypeSchema.json).\n\nAfter the `type` has been created, categories with custom fields can be imported:\n```csv\nname.en,key,externalId,slug.en,customType,customField.number\ncategoryName,categoryKeys,categoryExternalId,category-en-slug,customTypeKey,123\n```\n\nMore detailed example of CSV with various custom fields can be found [here](/data/exportWithCustomFields.csv).   \n\n## Export\n\nTo export categories, you can pass a CSV file as template. The template needs to contain only the header.\nThis will allow you to define the content of the output file to your specific needs.\nPlease have a look at the [CSV Format section](#csv-format) for the different headers supported.\nIf no template is provided using the `-t' parameter, all possible category attributes will be exported incl. all localisations.\n\nThe command line to export categories into a CSV file is:\n```\nUsage: bin/category-sync -p \u003cproject-key\u003e [options] export -t \u003cCSV file\u003e -o \u003cCSV file\u003e\n\nOptions:\n  -t, --template  CSV template file name\n  -o, --output    CSV output file name                                [required]\n\nExamples:\n  bin/category-sync -p my-project-42          Export categories from SPHERE\n  export -t header.csv -o output.csv          project with key \"my-project-42\"\n                                              into \"output.csv\" file using the\n                                              template \"header.csv\".\n\n  bin/category-sync -p the-project-1          Export categories from SPHERE\n  export -o my.csv                            project with key \"the-project-1\"\n                                              into \"my.csv\".\n```\n\n## Resolving parent category\n\nA category without a parent is called `root` category. All other categories have a parent.\nTo define a parent by default you provide the externalId of the parent category.\n```csv\nexternalId,name,parentId\nroot123,Root Category,\nsub123,Sub Category,root123\n```\n\nBut you may also use the slug to reference your parent category.\n```csv\nname,slug.en,parentId\nRoot Category,root-cat,\nSub Category,sub-cat,root-cat\n```\n\nEnsure that you have set the right language to choose the slug. By default it's English.\n\n## CSV Format\n\nIn general the CSV is built up of a header row and the content rows.\nWe support the following headers:\n- name: [localized name for the category](#localized-attributes)\n- description: [category's description in different languages](#localized-attributes)\n- slug: [internationalized slugs for the category](#localized-attributes)\n- key: key of the category defined by the user\n- externalId: id of the category defined by the user\n- parentId: id of the parent category - we reference other categories by `externalId` here\n- orderHint: a string that is used to order categories of the same parent. We recommend to use values between `0.1` and `0.9`.\n- metaTitle: [localized title of category for search engines](#localized-attributes)\n- metaDescription: [localized description to be used by search engines](#localized-attributes)\n- metaKeywords: [localized SEO keywords for the category](#localized-attributes)\n- custom: [custom fields](#custom-fields)\n\nFurther you might use the following header during export:\n- id: id of category in SPHERE.IO\n- createdAt: The UTC time stamp when the category was created.\n- lastModifiedAt: The UTC time stamp when the category was changed the last time.\n\nPlease find some examples in the [data](https://github.com/sphereio/sphere-category-sync/tree/master/data) folder or in the acceptance tests of the tool in the `*.feature` located [here](https://github.com/sphereio/sphere-category-sync/tree/master/features).\n\nPlease note that there is no order in the header.\n\n## JSON Format\n\nWe support importing categories from JSON file. The import file should be in compliance with the following schema:\n```js\n{\n  \"categories\": {\n    \"type\": \"array\",\n    \"items\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"externalId\": {\n          \"type\": \"string\"\n        },\n        \"name\": {\n          \"$ref\": \"/ltext\"\n        },\n        \"slug\": {\n          \"$ref\": \"/ltext\"\n        },\n        \"description\": {\n          \"$ref\": \"/ltext\"\n        },\n        \"orderHint\": {\n          \"type\": \"string\"\n        },\n        \"parent\": {\n          \"$ref\": \"/reference\"\n        }\n      },\n      \"required\": [\"name\", \"slug\"]\n    }\n  }\n}\n```\nFor importing JSON file, please use the [cli](https://github.com/sphereio/sphere-node-cli)\nExpected configuration options are:\n- language: (en / de) localization language\n- parentBy: (externalId, slug)\n\nA sample cli command is as follows:\n\n```bash\n./bin/sphere import -p my-project-key -t category -f testCategories.json -c '{\"language\":\"de\", \"parentBy\":\"externalId\"}'\n#\n```\n\n### Localized attributes\n\nDifferent 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.\n\n### Custom fields\nThis module can also export custom fields from [category object](https://docs.commercetools.com/http-api-projects-categories#category).\nWhen given the following template, exporter will store `custom.type.key` in a `customType` column and `customField.*` columns will be filled with corresponding custom fields.\n```csv\nkey,slug.en,customType,customField.number,customField.moneyAttr\n```\nOutput:\n```csv\ncategoryKey,categorySlugEn,customTypeKey,123,9876 EUR\n```\n\nMore advanced CSV template for exporting custom fields can be found [here](./data/customFieldsTemplate.csv).\n\n# Setup\n\nIf you just want to use the tool, we recommend to use [SPHERE.IO's impex platform](https://impex.sphere.io) to avoid any local installation - you only need your browser.\n\nNevertheless, running the program locally, you need [NodeJS](https://nodejs.org/download/) installed and simply run the following command in your terminal:\n\n```bash\nnpm install sphere-category-sync\n./node_modules/.bin/category-sync\n#\n```\n\nYou may also install it globally if you have sufficent rights on your computer:\n```bash\nnpm install -g sphere-category-sync\ncategory-sync\n#\n```\n\n# Development\n\n* Clone this repository and change into the directory\n* Install all necessary dependencies with\n\n  ```bash\n  npm install\n  ```\n* Convert CoffeeScript into JavaScript by\n\n  ```bash\n  npm run build\n  ```\n* To run the test do:\n\n  ```bash\n  npm test\n  ```\n* To run the tests on each change you do to any `*.coffee` file run\n\n  ```bash\n  npm run watch:test\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fsphere-category-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercetools%2Fsphere-category-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fsphere-category-sync/lists"}