Fetching contributors…
Cannot retrieve contributors at this time
200 lines (142 sloc) 9 KB


Build Status Coverage Status Dependency Status devDependency Status

This repository contains a set of data connectors to sync data between brickfox <-> SPHERE.IO


  • install NodeJS (platform for running application)
  • install npm (NodeJS package manager, bundled with node since version 0.6.3!)
  • install [grunt-cli] ( (automation tool)
  • resolve dependencies using npm
$ npm install
  • build javascript sources
$ grunt build

General Usage


Before running this tool Brickfox to SPHERE.IO mapping has to be defined.

Product import mapping attributes

  • target: Specifies where to save mapped Brickfox value to. Possible values: product | variant

  • isCustom: Only relevant for targets of type variant and specifies if value should be mapped to one of the SPHERE.IO product type attributes. Possible values true | false

  • type: Defines attribute type. Standard type values.

Special type values: - special-tax: Attribute's value will be mapped to configured tax category IDs - special-price: Attribute's value will be mapped to configured customer group ID, channel group ID and country - special-image: Attribute's value will used as URL for creation of variant images. Optional special mapping attribute baseURL can be used for prefixing of values with base url if non defined

Make sure that localized Brickfox attributes are mapped to localized ltext / lnum SPHERE.IO attributes.

  • to: Defines SPHERE.IO product attribute name where the mapped value will be saved to. Possible product attributes. Possible variant attributes

  • logoutMissing: Used for output of missing product type attribute values. Can be usefull for product type setup

  • transformers: List of transformers to apply on the "enum" key or "text" value. Supported value transformers: regular expressions, lower case, upper case. Examples

To ensure successful synchronization with Brickfox following Brickfox attribute mappings are mandatory:

  • VariationId (as variant product type attribute)
  • ProductId (as variant product type attribute)
  • ExternVariationId (as variant sku)

Product attribute mapping examples

  "meta_title": {
        "target": "product",
        "type": "ltext",
        "to": "metaTitle"
    "ProductId": {
        "target": "variant",
        "isCustom": "true",
        "type": "number",
        "to": "productId"
    "PriceGross": {
        "target": "variant",
        "type": "special-price",
        "specialMapping": {
            "country": "DE",
            "customerGroup": "4b96b6f9-03b5-420e-8720-e243837482a8",
            "channel": "ad62d775-6d9c-49c0-af3a-3acd60008331"
        "to": "prices"

More mapping examples can be found here

This tool uses sub commands for the various task. Please refer to the usage of the concrete action:

  • [Import products](#Import products)
  • [Import stock and price updates](#Import stock and price updates)
  • [Export orders](#Export orders)
  • [Import order status updates](#Import order status updates)

General command line options can be seen by simply executing the command node lib/run.

node lib/run

  Usage: run [command] [globals] [options]


    import-products [options]  Imports new and changed Brickfox products from XML into your SPHERE.IO project.
    import-products-updates [options]  Imports Brickfox product stock and price changes into your SPHERE.IO project.
    export-orders [options]  Exports new orders from your SPHERE.IO project into Brickfox XML file.
    import-orders-status [options]  Imports order and order entry status changes from Brickfox into your SPHERE.IO project.


    -h, --help                      output usage information
    -V, --version                   output the version number
    --projectKey <project-key>      your SPHERE.IO project-key
    --clientId <client-id>          your OAuth client id for the SPHERE.IO API
    --clientSecret <client-secret>  your OAuth client secret for the SPHERE.IO API
    --mapping <file>                JSON file containing Brickfox to SPHERE.IO mappings
    --config [file]                 path to configuration file with data like SFTP credentials and its working folders
    --logLevel [level]              specifies log level (error|warn|info|debug|trace) [info]
    --logDir [directory]            specifies log file directory [.]
    --bunyanVerbose                 enables bunyan verbose logging output mode. Due to performance issues avoid using it in production environment

For all command specific options please call node lib/run <command> --help.

Import products


node lib/run import-products --help

  Usage: import-products --projectKey <project-key> --clientId <client-id> --clientSecret <client-secret> --mapping <file> --config [file] --products <file> --manufacturers [file] --categories [file]


    -h, --help              output usage information
    --products <file>       XML file containing products to import
    --manufacturers [file]  XML file containing manufacturers to import
    --categories [file]     XML file containing categories to import
    --safeCreate            If defined, importer will check for product existence (by ProductId attribute mapping) in SPHERE.IO before sending create new product request
    --continueOnProblems    When a product does not validate on the server side (400er response), ignore it and continue with the next products

Import stock and price updates


node lib/run import-products-updates --help

  Usage: import-products-updates --projectKey <project-key> --clientId <client-id> --clientSecret <client-secret> --mapping <file> --config [file] --products <file>


    -h, --help         output usage information
    --products <file>  XML file containing products to import

Export orders


node lib/run export-orders --help

  Usage: export-orders --projectKey <project-key> --clientId <client-id> --clientSecret <client-secret> --numberOfDays [days] --mapping <file> --config [file] --target <file>


    -h, --help             output usage information
    --target <file>        Path to the file the exporter will write the resulting XML into
    --numberOfDays [days]  Retrieves orders created within the specified number of days starting with the present day. Default value is: 7

Import order status updates


node lib/run import-orders-status --help

  Usage: import-orders-status --projectKey <project-key> --clientId <client-id> --clientSecret <client-secret> --mapping <file> --config [file] --status <file> --createStates


    -h, --help       output usage information
    --status <file>  XML file containing order status to import
    --createStates   If set, will setup order line item states and its transitions according to mapping definition


By default application logs into the file ./sphere-brickfox-connector.log with log level 'info'. Log level can be overriden with parameter --logLevel

Once you installed bunyan CLI npm install -g bunyan following can be used for prettyfied log output: tail -f ./sphere-brickfox-connector.log | bunyan


Tests are written using jasmine (behavior-driven development framework for testing javascript code). Thanks to jasmine-node, this test framework is also available for node.js.

To run tests, simple execute the test task using grunt.

$ grunt test


We <3 CoffeeScript here at commercetools! So please have a look at this referenced coffeescript styleguide when doing changes to the code.