sw-sync-cli-0.8.0 is not a library.

sw-sync-cli

A CLI tool that communicates with the Shopware admin API (over an integration) to export data into (CSV) files or import data from (CSV) files.

[!WARNING]
This tool is experimental and for now just a proof of concept.

Overview

Features

It's fast, with a focus on performance
Every entity and field available in the Shopware API can be exported / imported
Supports data filtering and sorting using the API criteria
Import / Export profiles are just .yaml files
- That define the way data is processed for import and export
- Which can be copied + adapted + shared freely
- They include a scripting engine for arbitrary data transformations
For now only supports CSV data files

Installation

With Cargo (Rust toolchain)

cargo install sw-sync-cli

Same command can be used for updates. See crate

Manual

head to GitHub releases and download the right binary for your operating system. Then either execute the binary directly or put it in your PATH.

Build it from this repository

Clone this repository
Have the latest Rust toolchain installed
Run cargo build --release inside the repository root folder
You will get your executable here ./target/release/sw-sync-cli

Usage

Set up an integration inside shopware.
Call sw-sync-cli auth with the required arguments (credentials)

[!WARNING]
This will create a .credentials.toml file in your current working directory. This file contains your credentials in plain text, you might want to remove it again after you are done syncing.

Call sw-sync-cli sync in either -m import or -m export mode, with a profile (profile.yaml) and data file data.csv

[!Note]
You can call sw-sync-cli help at any time to get more information

Profiles

Profiles are used to define the mapping between (CSV) file columns and Shopware entity fields, as well as additional configuration for the import / export. To get started take a look at Profiles in this repository. The structure of a profile .yaml is as follows:

entity: product

# optional filtering, only applied on export
filter:
  # export main products (parentId = NULL) only
  - type: "equals"
    field: "parentId"
    value: null

# optional sorting, only applied on export
sort:
  - field: "name"
    order: "ASC"

# optional additional associations (that you need in your deserialization script)
# note: entity_path associations are already added by default
# only applied on export
associations:
  - "cover"

# mappings can either be
# - by entity_path
# - by key
# the latter needs to be resolved by custom scripts
mappings:
  - file_column: "id"
    entity_path: "id"
  - file_column: "name (default language)"
    entity_path: "name"
  - file_column: "product number"
    entity_path: "productNumber"
  - file_column: "stock"
    entity_path: "stock"
  - file_column: "tax id"
    entity_path: "taxId"
  - file_column: "tax rate"
    # entity path can resolve "To-One-Associations" of any depth
    entity_path: "tax.taxRate"
  - file_column: "manufacturer name"
    # They can also use the optional chaining '?.' operator to fall back to null
    # if the association is null
    entity_path: "manufacturer?.name"
  - file_column: "manufacturer id"
    # for importing, you also need the association id in the association object
    entity_path: "manufacturer?.id"
  - file_column: "gross price EUR"
    key: "gross_price_eur"
  - file_column: "net price EUR"
    key: "net_price_eur"

# optional serialization script, which is called once per entity
serialize_script: |
  // See https://rhai.rs/book/ for scripting language documentation
  // you receive an entity object, which consists of the whole entity API response for that single entity
  // you also receive an empty row object where the specified keys above are missing (you need to set them)
  // the other simple mappings are executed (added to the row object) after this script

  // debugging utils
  // debug(entity); // contains the full entity object from the API (can be huge!)
  // print(row); // will be empty

  // Use 'get_default' to look up a value equivalent to Defaults.php
  let default_currency = get_default("CURRENCY");
  let price = entity.price.find(|p| p.currencyId == default_currency);
  row.gross_price_eur = price.gross;
  row.net_price_eur = price.net;

# optional deserialization script, which is called once per entity
deserialize_script: |
  // See https://rhai.rs/book/ for scripting language documentation
  // you receive 'row' as an object that has all the keys defined above with the corresponding value
  // you also receive an empty entity object, where you need to resolve your keys
  // the other simple mappings are executed (added to the entity object) after this script

  // print(entity); // will be empty
  // debug(row); // will contain only the specified keys + their values

  entity.price = [];
  entity.price.push(#{
    gross: row.gross_price_eur,
    net: row.net_price_eur,
    linked: true,
    currencyId: get_default("CURRENCY"),
  });

  // You can get the default language or a specific language id by their ISO code
  // Default language is used here and will return the default language id
  let default_language_id = get_default("LANGUAGE_SYSTEM");
  // For a specific language id you can use the get_language_by_iso function:
  let specific_language_id = get_language_by_iso("de-DE"); // It will return the language id for "de-DE"

  // You can also get different currencies by their ISO code
  // Default currency is used here and will return the default currency id
  let default_currency_id = get_default("CURRENCY");
  // For a specific currency id you can use the get_currency_by_iso function:
  let eur_currency_id = get_currency_by_iso("EUR"); // It will return the currency id for "EUR"

License

sw-sync-cli is distributed under the terms of the MIT License.
See the LICENSE file for details.

sw-sync-cli 0.8.0