Imports - Configuration file
Overview
This document explains in detail the structure of the configuration file used to define the behavior of the import engine.
Think of this file as a compendium: instead of reading it from cover to cover, which may be a daunting task, use it to find the information you need. The file contains hyperlinks to make it easier to find the configuration options for your scope.
Please refer to the Configuration file tutorial for examples.
Prerequisites
- A basic or better knowledge of the JSON syntax.
- A contact in Splio to receive and validate your config file.
- A text or code editor.
Use your favorite text or code editor to create and edit config files. An editor which can validate JSON syntax is recommended, as it will help you catch the most basic mistakes, such as missing commas, quotation marks, or brackets. If you do not know any such software, you might use JSON Editor Online, which is free software and is available via the website.
Definition of the config file
The configuration file is a text file conforming to the JavaScript Object Notation (JSON) format.
|
Filename |
<universe>_imports_config.json |
|
Encoding |
UTF-8 without BOM |
|
Format |
JSON |
The placeholders in the following definition which need to be replaced with actual names and values are enclosed in pointy brackets ("<>"). The optional parts are enclosed within square brackets ("[]"). Ellipsis (". . .") replaces repetitions.
{
"<universe>":{
"<scope1>":{
"<sub-sequence1>":{
"<configoption11>":"<value11>"[,
"<configoption12>":"<value12>"[, . . . ] ]
}[,
"<sub-sequence2>":{
"<configoption21>":"<value21>"[,
"<configoption22>":"<value22>"[, . . . ] ]
}[, . . . ] ]
}[,
"<scope2>":{
"<sub-sequence3>":{
"<configoption31>":"<value31>"[,
"<configoption32>":"<value32>"[, . . . ] ]
}[,
"<sub-sequence4>":{
"<configoption41>":"<value41>"[,
"<configoption42>":"<value42>"[, . . . ] ]
}[, . . . ] ]
}[, . . . ] ]
}
}
Universe
The file must contain exactly one "<universe>" object. The name of this object must match the name of your Splio universe and needs to be the part of the filename.
Scope
The universe must contain at least one "<scope>" object. Scopes represent data types which can be imported into the Splio database.
The following scopes are available:
- contacts
- products
- stores
- orders
- abandonedcarts
- ordersitems
- masterreward, earnreward, burnreward (referring to Loyalty Rewards)
- creditpoints
- events
- deletecontacts
- cardcode (Loyalty subscriptions)
Each scope except ordersitems has its corresponding deletion scope. See here to learn more about deletion.
Sub-sequence
Each scope must contain one or more "<sub-sequence>" objects. Sub-sequences are used to define import files, which always belong to a specific sub-sequence within a scope. Sub-sequences represent various data sources (e.g., external bases) or imports within the same scope carried out for different reasons.
All configuration options are defined within sub-sequences.
Scopes and configuration options
The following subsections list the configuration options available within each scope.
Contacts
You may think of contacts as phonebook entries belonging to your clients. See here to learn more about contacts.
The following configuration options are available for contacts:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
default cellphone prefix |
Yes |
numerical |
A prefix (country code) to be added to all local cellphone numbers found in the file. It will not be added to numbers already presented with a country code. |
|
init lists |
Yes |
list of numerical values |
A list which must include the numerical ids of all Splio lists which need to be initialized (that is, emptied) before import. |
|
create contacts |
No |
0 (no) / 1 (yes, default) |
Allows creating new contacts during import. Enabled by default. By disabling it you can prevent a given import file from creating new contacts. |
|
update contacts |
No |
0 (no) / 1 (yes, default) |
Allows updating existing contacts on the basis of the import file. Enabled by default. By disabling it you can make sure that no contacts records will be updated when importing this file. You can use it to automatically subscribe contacts to lists. |
Hint: if you do not wish to clear (initialize) any lists, provide an empty list as value: "init lists": \[].
Products
Products represent various merchandise which can be purchased by contacts or awarded to them. See here to learn more about products.
The following configuration options are available for products:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
create products |
No |
0 (no) / 1 (yes, default) |
Allows creating new products during import. Enabled by default. By disabling it you can prevent a given import file from creating new products. |
|
update products |
No |
0 (no) / 1 (yes, default) |
Allows updating existing products on the basis of the import file. Enabled by default. By disabling it you can prevent products records from being updated when importing. |
Stores
Stores represent physical or online stores and POS. See here to learn more about stores.
The following configuration options are available for stores:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
create stores |
No |
0 (no) / 1 (yes, default) |
Allows creating new stores during import. Enabled by default. By disabling it you can prevent a given import file from creating new stores. |
|
update stores |
No |
0 (no) / 1 (yes, default) |
Allows updating existing stores on the basis of the import file. Enabled by default. By disabling it you can prevent stores records from being updated when importing. |
Orders
Orders represent purchases made by contacts. See here to learn more about orders.
The following configuration options are available for orders:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
create orders |
No |
0 (no) / 1 (yes, default) |
Allows creating new orders records during import. Enabled by default. By disabling it you can prevent a given import file from creating new orders. |
|
update orders |
No |
0 (no) / 1 (yes, default) |
Allows updating existing orders on the basis of the import file. Enabled by default. By disabling it you can prevent orders records from being updated when importing. |
|
generate loyalty events |
No |
0 (no, default) / 1 (yes) |
Allows the orders to be processed as events by the Loyalty engine, to trigger rules as conditions. Without this parameter, no outcome can be given from rules triggered by orders. Compatible with the same parameter on order items. |
|
only orders |
No |
0 (no, default) / 1 (yes) |
Allows the Loyalty engine to process orders without order items for Loyalty rules. This option should be activated on orders or order items for the Loyalty rules to attribute outcomes (never on both). |
Abandonedcarts
Abandonedcarts represent purchases which were not completed. See here to learn more about abandonedcarts.
The following configuration options are available for abandonedcarts:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
create abandonedcarts |
No |
0 (no) / 1 (yes, default) |
Allows creating new abandonedcarts during import. Enabled by default. By disabling it you can prevent the creation of abandonedcarts records. |
|
update abandonedcarts |
No |
0 (no) / 1 (yes, default) |
Allows updating abandonedcarts during import. Enabled by default. By disabling it you can prevent the update of abandonedcarts records. |
Orders items (ordersitems)
Ordersitems represent individual items on a receipt or in a shopping cart. See here to learn more about ordersitems.
Note that items in this scope cannot be updated via import but will be deleted whenever a corresponding order or abandonedcart is imported (e.g., updated).
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |
|
generate loyalty events |
No |
0 (no, default) / 1 (yes) |
Allows the orders to be processed as events by the Loyalty engine, to trigger rules as conditions. Without this parameter, no outcome can be given from rules triggered by orders items (products). Compatible with the same parameter on order items. |
|
only order items |
No |
0 (no, default) / 1 (yes) |
Allows the Loyalty engine to process orders items without orders for Loyalty rules. This option should be activated on orders or order items for the Loyalty rules to attribute outcomes (never on both). |
Loyalty subscriptions (cardcode)
This scope uses the same set of configuration options as Ordersitems above.
See here to learn more about importing Loyalty subscriptions.
Credit points (creditpoints), Events (events), Delete contacts (deletecontacts)
This group of import scopes shares the same set of two configuration options.
See the following articles to learn more about individual scopes:
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
Loyalty Rewards (masterreward, earnreward, burnreward)
Importing the rewards-related scopes is described in the Loyalty rewards document.
|
Configuration option |
Required |
Value type |
Description/usage notes |
|
report recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive the report after the import is complete. |
|
alert recipients |
Yes |
list of email addresses |
Email addresses of all recipients to receive alerts during import. |
|
overwrite with empty values |
No |
0 (no, default) / 1 (yes) |
"masterrewards" only If set to "1" (yes), the existing values will be replaced by NULL when a record is being updated from file and the field in the file is empty. |