Splio Sync Magento 2
1.Installation guide
1.1.Extension installation
Before the extension install, it must be ensured that the Magento environment is properly configured.
Please feel free to check among other topics:
- the cron tasks configuration, required for the proper functioning of the extension.
- the user rights configuration, required for the proper installation of the extension.
1.1.1.Through composer
- Place an order for the extension through the Magento marketplace.
- Open a terminal and run the following command in your Magento directory:
$ composer config repositories.private-packagist composer https://home-made-io.repo.packagist.com $ composer require home-made-io/splio-sync-m2 $ bin/magento module:enable HMio_SplioSync $ bin/magento setup:upgrade $ bin/magento cache:clean - If Magento runs in production mode, you also must compile and deploy the extension’s static files:
$ bin/magento setup:di:compile $ bin/magento setup:static-content:deploy
1.1.2.Through the Magento admin panel
- Place an order for the extension through the Magento marketplace.
- Go in Magento admin, menu System > Tools > Web Setup Wizard.
- Click the Extension Manager icon.
- Within the Magento Marketplace Account section, click on New Purchases, and follow the instructions to install the extension.
The extension installation must be relatively quick (under 5 minutes). If this delay is exceeded, please check the log files.
1.2.Extension uninstallation
Open a terminal and run the following commands in your Magento directory:
$ composer remove home-made-io/splio-sync-m2
$ composer config --unset repositories.private-packagist
$ bin/magento setup:upgrade
$ bin/magento setup:di:compile
$ bin/magento setup:static-content:deploy
$ bin/magento cache:clean2.User guide
2.1.Overall functioning
The Splio Sync extension for Magento 2 allows the synchronization of the abandoned carts between Magento 2 and Splio.
It synchronizes the following data of the abandoned carts:
- carts’ items: SKU, price, ordered quantity, totals
- products linked to the items: name, description, brand, image, URL, stock level, categories, creation, last update and last synchronization date
- carts’ customers: ID, email, names, gender, date of birth, phone number, VAT number, creation, last update, last connection and last synchronization date
- billing address of carts’ customers: address’s lines, city, zip code, country, company
- cart itself: ID, store, totals, currency, creation and last update date
The synchronization is done in almost real-time (less than a minute of delay), by adding non invasive synchronization tasks in a dedicated queue, and processed by a cron task.
2.2.Extension configuration
2.2.1.API key addition
Go in Magento admin, menu Stores > Configuration, then in the tab Splio Sync > API.
In the configuration field API key, place the API key displayed in the Splio admin interface.
You can check the proper functioning of the connection to the API by clicking on the button Test connection.
In case of error, feel free to copy the error message displayed and send it to the email address contact@home-made.io.
For more information on the API keys generation on Splio, please look at the documentation dédiée.
2.2.2.Splio multiple universes management
It’s possible to configure the extension to synchronize the abandoned carts of different websites on different universes in Splio.
To do so, go in Magento admin, menu Stores > Configuration, then in the tab Splio Sync > API. Then, change the scope to choose the website that must be synchronized in another Splio universe.
It’s a pretty advanced configuration, which has impacts on the synchronization process. Please feel free to talk about it at your contact within Splio in the first place.
2.2.3.Custom fields' installation
Splio uses custom fields to save the most data possible on your contacts.
The installation is done by clicking on the button Install the custom fields in Magento admin, menu Stores > Configuration, then in the tab Splio Sync > API.
In case of multi-universes configuration, the custom fields will be created automatically on each of the universe configured. If an universe is added in the configuration during the lifetime of the website, it’s necessary to rerun the custom fields installation the same way.
The installation through the button does not delete the custom fields already existing, nor does it create duplicates. You can click again on the button without fear of impacts in the data existing in Splio.
The extension offers a list of custom fields already made. As for now, it’s not possible to change it without the intervention of a third party, who has access to the code and the database of Magento 2, through the inclusion of the extension override.
Here is the complete list of custom fields created by the extension:
- For the contacts: Magento ID, prefix, gender, VAT number, date of birth, zip code, city, country, et company of the default billing address, activation status, creation, last update, last connection and last synchronization dates
- For the products: Splio ID of the parent product, URL, stock level, creation, last update and last synchronization dates
- For the carts: Last update
Feel free to consult your contact within Splio to obtain information about the development of the modification system of customs fields.
2.2.4.Choice of identifier attributes
Two last structuring choices are to be made before the launch of the first synchronization.
For the products and the contacts, the extension allows users to choose which will be the attribute identifying the entity in Splio, among the list of attributes existing in the Magento 2 website.
For the products, the favored choices are the SKU and the Magento ID. For the contacts, the email address or the Magento ID. Nonetheless, any other attribute can be used.
If none of the favored attributes suit your context, here is the important points to take into account for choosing the identifier attribute
- it must be filled for all products or customers
- it must be unique for each product or customer
- it must be defined globally, so no overridden at website / store scope
- it must be saved as a text or as an option of a list
Feel free to consult your contact within Splio to define what is the best choice for you.
Once the synchronization is launched, it’s strongly discouraged to change the identifier attribute. The configuration fields are disabled once the synchronization is launched.
2.2.4.1.Customer identifier attribute
Splio allows users to identify contacts with the email address, the phone number or any custom fields defined in the universe.
The phone number is rarely filled out within an ecommerce website. So the extension handles three hypotheses regarding the contacts’ identification
- the contacts are identified in Splio by their email address: The email address is sent at Splio, being a default field.
- the contacts are identified in Splio by their Magento ID: A custom field called m2_customer_id synchronizes the Magento ID of the customer. Besides, this custom field is filled out whatever the identifier attribute.
- the contacts are identified in Splio by other data existing in Magento: it can be an external ERP ID saved in Magento, a VAT number, etc… In this case, it is mandatory to create a custom field in Splio, then to save within the configuration the ID and the name of the custom field, both of them being mandatory to the synchronization. To do so, go into Magento admin, menu Stores > Configuration, then in the tab Splio Sync > Contacts, and fill the configuration fields as such.
2.2.5.Stores configuration
Before configuring the extension to synchronize the abandoned carts, you must create the store which will receive the carts within Splio.
Go in Splio, in the menu Data > Sales data, then in the tab Stores, and create one or more stores matching the stores in the Magento website.
The Splio Sync extension allows synchronizing the abandoned carts in a Splio store depending on the website or the store view on which it has been made. So you can create as many stores in Splio as there are store views in Magento, or only one store containing all abandoned carts existing in your Magento instance.
Once the stores are created in Splio, you can fill out their external ID in the configuration field of the Splio Sync extension.
Go in Magento admin, menu Stores > Configuration, then in the tab Splio Sync > Abandoned carts.
In the configuration field called Splio store external ID, fill out the external ID of the Splio store newly created.
By modifying the scope of the configuration, you can change the external ID of the Splio by website or store view.
2.3.Launching of the synchronization
After the configuration step, you can launch the synchronization of the abandoned carts.
To do so, go into Magento admin, menu Stores > Configuration, then in the tab Splio Sync > Job Queue, and change the value of the configuration field called Enable sync between Splio and Magento.
After that, for each entity synchronizable (at the time, only the abandoned carts), go in the matching tab, and change the value of the configuration field called Enable export.
2.4.Synchronization tracking
Into the menu System > Splio, several pages display information on the smooth running of the synchronization of the different entities.
2.4.1.Jobs tracking
Into the menu System > Splio > To Splio Job Queue, a grid displays the list of the jobs to be done to Splio, with their status, creation date and a potential error message.
The jobs can be in one of the following statuses:
- pending
- running
- in error
- skipped: the entity’s data indicates that it must not be synchronized
- finished
The jobs finished or skipped are automatically deleted after their processing.
In case of error, the synchronization process try to rerun the job 4 times, before giving up. The jobs definitively in error stay visible in the grid, with the error message matching.
2.4.2.Entities matching
2.4.2.1.Matching of the abandoned carts
Into the menu System > Splio > Abandoned carts synchronized, a grid displays the list of the abandoned carts already synchronized with Splio, including those which have been deleted since (because they were converted as orders, or deleted by the customer).
2.4.2.2.Matching of the products
Into the menu System > Splio > Products synchronized, a grid displays the list of the products synchronized with Splio.
In Magento, products can be affected to several websites, thus synchronized with several universes in Splio. The column Scope allows to determine with which it has been synchronized, and with which identifier.
2.4.3.Logs tracking
The extension offers two pages for tracking the smooth running of the synchronization into the menu System > Splio, Logs and API calls logs.
The first page displays information of the running of the synchronization of the different entities. The second one displays the calls made to the Splio API during the synchronization.
Authentication calls to the Splio API are never logged, for security purposes.
Those are primarily technical data, but which are very useful during errors resolution.
Nonetheless, you can choose to disable a part of logs (the least critical) in order to avoid populating the matching table in your database needlessly.
By default, logs are deleted after 7 days, and duplicated in a dedicated log file. The configuration allows modification of these behaviors nonetheless.
In case of error, feel free to send us the information contained in the matching tables, to ease the resolution of the issue.
2.5.Synchronization specificities
2.5.1.Abandoned carts synchronization
2.5.1.1.Delay before synchronization
The extension allows defining a delay before considering a cart as abandoned.
By default, this delay is valued at 36 hours.
2.5.1.2.Abandoned carts deletion
When a cart is transformed in an order, deleted by the customer, or considered as inactive by Magento, the extension synchronizes its deletion in Splio, if the cart was previously synchronized.
2.5.2.Abandoned carts' customers synchronization
2.5.2.1.Contacts' lists
The customers synchronized with Splio go all in the default contacts list.
Some customers may also be newsletter subscribers. The extension allows defining a contacts list in which those customers will also be synchronized.
If no ID is filled in the matching configuration field, or if the ID filled out is 0, the newsletter subscribers will not be synchronized in another list, except the default one.
2.5.3.Abandoned carts' products synchronization
2.5.3.1.Configurable and grouped products
The extension synchronizes only simple products (at the moment). If one of the products synchronized are a variation of a configurable product, or a part of a grouped product, the ID of the parent product will be saved in the custom field m2_parent_id, created by the extension.
3.Reference manual
3.1.Synchronized data mapping
The extension use the API given by Splio. The names of the fields below refers to fields expected by the API. See here for more information.
3.1.1.Contacts
3.1.1.1.Standard fields
| Splio field name | Magento 2 data | Comment |
|---|---|---|
| lastname | lastname | |
| firstname | firstname | |
| creation_date | created_at | |
| language | language code from the value of the configuration field « general/locale/code » in the store of the abandoned cart | « fr », « en », « es »… |
| cellphone | phone number of the customer’s default billing address | |
| lists | « 0 » and the value of the configuration field « splio_sync_contacts/newsletter/list_id » for the website of the abandoned cart | [0] or [0, x] |
3.1.1.2.Custom fields
Here is the list of the custom fields used by the addon for customers / contacts
| Splio field name | Magento 2 data | Data type | Comment |
|---|---|---|---|
| m2_customer_id | entity_id | int | |
| m2_prefix | prefix | text | Mr, Mme… |
| m2_gender | gender | text | « M » or « F » (« N/A » available soon) |
| m2_taxvat | tax_vat | text | VAT number |
| m2_dob | dob | date | Date of birth |
| m2_store | Value of the configuration field « splio_sync_carts/export/store_id » in the store of the abandoned cart | text | |
| m2_default_address_zipcode | postcode of the default billing address | text | |
| m2_default_address_city | city of the default billing address | text | |
| m2_default_address_country_code | country_id of the default billing address | text | In the ISO 3166-2 standard |
| m2_default_address_company | company of the default billing address | text | |
| m2_status | Unused | ||
| m2_last_sync_at | Current date | date | |
| m2_created_at | created_at | date | |
| m2_updated_at | updated_at | date | |
| m2_last_login | last_login_at | date |
3.1.2.Products
3.1.2.1.Standard fields
| Splio field name | Magento 2 data | Comment |
|---|---|---|
| external_id | Value of the configuration field « splio_sync_products/general/identifier » in the store of the abandoned cart | Default value: entity_id |
| name | name | |
| description | description | |
| brand | brand | |
| price | price_incl_tax of the parent product if configurable, of the product otherwise | |
| sku | sku | |
| img_url | product_small_image URL in the store of the abandoned cart | |
| category | Concatenation of the categories names | « Man, Shoes, Sales » |
3.1.2.2.Custom fields
Here is the list of the custom fields used by the addon for products
| Splio field name | Magento 2 data | Data type | Comment |
|---|---|---|---|
| m2_parent_id | entity_id of the parent product, if it exists | text | |
| m2_url_path | url_path | text | |
| m2_inventory_level | Inventory level | double | Works with or without MSI |
| m2_created_at | created_at | date | |
| m2_updated_at | updated_at | date | |
| m2_last_sync_at | Current date | date |
3.1.3.Abandoned carts
3.1.3.1.Standard fields
| Splio field name | Magento 2 data | Comment |
|---|---|---|
| external_id | « m2_cart_ » followed by the entity_id of the cart | m2_cart_2547 |
| contact_id | Splio ID of the contact, given the value of the configuration field « splio_sync_contacts/general/identifier » in the store of the abandoned cart | The customer ID, email address, or any other attribute defined in the configuration |
| store_external_id | Value of the configuration field « splio_sync_carts/export/store_id » in the store of the abandoned cart | |
| ordered_at | created_at | |
| discount_amount | discount_amount | |
| shipping_amount | shipping_amount | |
| total_price | grand_total + tax_amount | |
| tax_amount | tax_amount | |
| tax_amount | tax_amount | |
| completed | false | |
| currency | currency | ISO 4217 format |
3.1.3.2.Custom fields
Here is the list of the custom fields used by the addon for abandoned carts / tickets.
| Splio field name | Magento 2 data | Data type | Comment |
|---|---|---|---|
| m2_updated_at | updated_at | date |
3.1.4.Abandoned carts items
3.1.4.1.Standard fields
| Splio field name | Magento 2 data | Comment |
|---|---|---|
| unit_price | price_incl_tax of the parent product if configurable, of the product otherwise | |
| quantity | qty of the parent product if configurable, of the product otherwise | |
| discount_amount | discount_amount of the parent product if configurable, of the product otherwise | |
| tax_amount | tax_amount of the parent product if configurable, of the product otherwise | |
| total_line_amount | row_total_incl_tax of the parent product if configurable, of the product otherwise | |
| product_id | Product Splio ID, given the value of the configuration field « splio_sync_products/general/identifier » in the store of the abandoned cart |
3.1.4.2.Custom fields
No custom fields for the moment