Magento 2 Salsify Connector - Trellis · Magento 2 Salsify Connector INSTALLATION & CONFIGURATION...

MAGENTO 2

SALSIFY CONNECTOR

Version 1.4.1

08/02/2019

[Insert appropriate SOFTWARE LICENSE]

Magento 2 Salsify Connector

TABLE OF CONTENTS INTRODUCTION..............................................................................................................3

Overview.....................................................................................................................3

Purpose of The Magento 2 Salsify Connector...........................................................3

COMPATIBILITY...............................................................................................................4

INSTALLATION & CONFIGURATION.............................................................................5

Magento......................................................................................................................5

General.......................................................................................................................5

Webhook....................................................................................................................6

Configurable Products................................................................................................7

Bundled Products.......................................................................................................7

Grouped Products......................................................................................................8

Virtual Products..........................................................................................................8

Downloadable Products.............................................................................................8

Media & Images.........................................................................................................8

Field Mapping...........................................................................................................10

Custom Options........................................................................................................11

Product Relation Settings.........................................................................................13

Attribute Set Settings................................................................................................13

Category Import Settings.........................................................................................14

Default Values..........................................................................................................14

RabbitMQ.................................................................................................................15

Debugging................................................................................................................15

USAGE...........................................................................................................................17

Manually...................................................................................................................17

Automatically............................................................................................................17

PRICE.............................................................................................................................18

Installation................................................................................................................18

ABOUT TRELLIS...........................................................................................................19

Contact trellis............................................................................................................19

VERSION HISTORY.......................................................................................................20

of 21

[Insert appropriate disclaimer(s)]


INTRODUCTIONOVERVIEW

Salsify is a leading cloud base PIM solution that can store and organize all yourproduct data. We provide the tooling to map almost anything from Salsify intoMagento 2, so that you can leverage Salsify’s powerful PIM features as your‘source of truth’ for your catalog, while taking advantage of Magento’s best in classeCommerce capabilities.

PURPOSE OF THE MAGENTO 2 SALSIFY CONNECTOR

The Magento 2 Salsify Connector allows you to connect your Magento 2 store toyour Salsify account in order to easily manage products across platforms in oneplace. Update and publish your products in Salsify and have them syncautomatically to your Magento 2 storefront. You choose what Salsify Propertiesautomatically pull into your Magento 2 store to update and what features toenable, such as product image galleries, or the ability to map configurable (base)products to simple (sellable) products.

of 21



COMPATIBILITYMagento CE EE Cloud

2.3.x √ √ √

2.2.x √ √

of 21



INSTALLATION & CONFIGURATIONINSTALLING THE MAGENTO 2 SALSIFY CONNECTOR

MAGENTO

1. Install the Magento 2 Salsify Connector Module from Archive.

a) Unzip the module archive.

b) Upload the folder to your Magento 2 directory on the web server.

c) Run the commands in the Magento 2 directory via CLI:

php bin/magento setup:upgrade php bin/magento setup:di:compile

2. Navigate to the Salsify Connector settings through your Magento 2 AdminPanel.

a) Stores -> [Settings] Configuration -> [Trellis] Salsify

3. Configure the Salsify Connector.

CONFIGURE THE MAGENTO 2 SALSIFY CONNECTOR

GENERAL

1. Enabled

Enable or disable the complete functionality of the module.

2. Allow Delete

Allow the module to delete product records that no longer reside in yourSalsify channel.

3. Ignore Timestamp and Always Update

Ignore the Salsify timestamp and update the products.

4. API Base URL

The URL used to access the Salsify API.

1. If your organization is part of a “multi-organization” in Salsify, you will needto enter your API URL like so:

https://app.salsify.com/api/orgs/<your-organization-id>/

Replace ‘<your-organization-id> with your organization ID. An exampleorganization ID looks like “s-96237d05-38d1-9adk-b873-6fog96f93163”.DO NOT FORGET THE TRAILING SLASH.

5. API Key

of 21



Your auth token (API Key) can be retrieved by going to Profile -> API Access-> Show API Key.

The Salsify Magento 2 Connector uses a query parameter to pass yourauth token: `https://app.salsify.com/api/v1/products/1234?access_token=<auth_token>`. In order to call any Salsify APIs, you mustprovide your authentication token (API Key). The auth token is specific toa user account.

6. Product Feed Channel ID

The Salsify Magento 2 connector uses channels to retrieve the latest productfeed. A channel is configured to export your selected products and theirattributes in JSON format.

1. Set Up a Channel to Export your JSON

a) Click “Product Selection” and choose your products.

b) Go back and click “Product Feed”.

c) Set “Format” to JSON.

d) Choose the columns you want to export (these are product attributesyou have in Salsify).

e) Go back and click _Publication Schedule_ - you can configure thischannel to be published every night so that you are dealing with up-to-date data.

2. Retrieve the Channel ID

a) This ID will be used to target the channel for future requests. It can befound at the end of the URL when you click into the channel.

b) https://app.salsify.com/app/channels/123456

7. API Timeout

Set the Timeout (in milliseconds) for the API calls. If the API receives noresponse in the given time, the APU will timeout.

8. SSL Verify Peer

Verify the authenticity of the peer's certificate. When negotiating an SSLconnection, the server sends a certificate indicating its identity. The SalsifyConnector will verify whether the certificate is authentic.

9. Sync Action

The Sync Action button will trigger a manual sync from your Salsify Channelinto Magento 2. Always remember to re-publish your channel on the Salsifyplatform to get the latest updates.

WEBHOOK

1. Enabled

of 21


https://app.salsify.com/app/channels/123456

https://app.salsify.com/api/v1/products/1234?access_token

https://app.salsify.com/api/v1/products/1234?access_token


Enable or disable the functionality of the webhooks. Please see section“Usage” on setting up automatic webhooks.

2. Client ID

The client ID is used to identify the request as actually coming from Salsify.This ID is user-made. It can be any string of characters, and any length. Forsecurity purposes, we recommend a string with at least 12 characters.

3. Cron Expression

The cron value in which you’d like to check for updates from Salsify. Thedefault value is 15 minutes. For examples and help building your own cronexpressions, visit https://crontab.guru/.

CONFIGURABLE PRODUCTS

1. Enabled

Enable or disable the functionality of configurable products.

2. Attributes Field

A comma-separated list of attributes used to construct the configurableproducts.

In order to map configurable (base) products to simple (sellable) productsfrom Salsify to Magento 2, we need to supply Salsify products with a usercreated property to do so. In our example, we've created a property`magento_configurable_attributes` with a value `parent_color` in Salsify.Then in Magento, we use Property Mapping to map the attribute:

{ "Parent Color":"parent_color"}

In the Salsify payload, Sellable (simple) products have a property `parent_id`that lets us know what Base (configurable) product it belongs to. Base(configurable) products do not contain this property. In our example, we areusing the Sellable (simple) products color property to create different (simple)products in Magento.

BUNDLED PRODUCTS

1. Enabled


2. Attributes Field

Specify the Salsify Property in which the connector will look for a commaseparated list of product skus to create bundled products from.

of 21



GROUPED PRODUCTS

1. Enabled


2. Attributes Field

Specify the Salsify Property in which the connector will look for a commaseparated list of product skus to create grouped products from.

VIRTUAL PRODUCTS

1. Enabled


2. Attributes Field

Specify the Salsify Property in which the connector will look for to determine ifthe product is a virtual product.

3. Virtual Products Details Field

Specify the Salsify Property in which the connector will look for to determinethe details of the Virtual Product.

DOWNLOADABLE PRODUCTS

1. Enabled


2. Downloadable Products Details Field

Specify the Salsify Property in which the connector will look for to determinethe details of the Downloadable Product.

A json object is required to set up and map downloadable details. For eachoption, there are required fields that also need to be set. Here is an examplejson object that would map the downloadable title, link type, and link url:

3. Downloadable Product Sample Field

– UNDER DEVELOPMENT –Specify the Salsify Property in which the connector will look for to determine ifthe product has sample links.

MEDIA & IMAGES

1. Digital Asset Feed Enabled

of 21



Enable or disable the Top Level Digital Asset Feed.

The Salsify Product Feed from your channel may contain a broken-outpayload of the digital assets your products include. If this is the case, we usethis option to tell the connector to look in this broken-out payload for yourproducts digital assets.

2. Product-Level digital Assets Enabled

The Salsify Product Feed from your channel may contain an included payloadof the digital assets your products include. If this is the case, we use thisoption to tell the connector to look in the included product payload for yourproducts digital assets.

3. Automatically Enable New Images

Automatically enable new images to appear on product pages.

4. Image Mapping Enabled

Enable or disable the functionality of Image Mapping.

The Salsify Connector allows you to map images from Salsify to theirproducts in Magento. In order to map images, we need to supply a mappedSalsify property to Magento attributes.

5. Image Tag Mapping

Much like the Field Mapping feature, the Salsify Connector allows you to mapimages from Salsify to their products in Magento. To do so, provide a `json`object to map your Salsify Property to Magento attributes.

{ "Main Image":["image"]}

6. Media Gallery Enabled

Enable or disable the functionality of the Image Gallery.

Media Gallery functionality allows you to assign multiple images from aSalsify Property into the product Media Gallery. The connector will downloadthe images from this Salsify Property and map them accordingly into theProduct Media Gallery.

7. Media Gallery

Input the Salsify Property which holds additional media images for yourproduct.

8. Media Gallery Download Path

Directory where the images will be downloaded. (inside pub/media/import)

9. Enable Video

Enable Video Functionality for Products

10.Video Property

of 21



A Salsify Property that holds the json object for product video details.

A json object is required to set up and map video links to products. Using a jsonobject allows uploading multiple video links in one property.{

"1": {

"video_title": "Product Video",

"video_url":"https://www.youtube.com/watch?v=6WaKS7xYfQU",

"video_description":"November rain-subtitulada GUNS NROSES",

"video_mediaattribute":"thumbnail,base,image"

}

}

The json object is wrapped in brackets {}The “1” represents the id of the first video. The next video, inside the same object, would have a “2”.“video_title” is required.“video_url” is required.“video_description” is optional.“video_mediaattribute” is optional.

FIELD MAPPING

When a Salsify client doesn’t name product properties in a “Magento” friendlyway, we need to map Salsify Properties to Magento Attributes.

IMPORTANT

Salsify referrers to product attributes as “properties”. When working withMagento, these are “attributes”

Salsify Magento

“property” “attribute”

IMPORTANT

Product attributes that you wish to map need to be created in Magento prior tosyncing.

IMPORTANT

Product attributes that you wish to use to map configurable products to childproducts need to be created in Magento prior to syncing.

1. Property Mapping

of 21



The value of the setting expects a JSON object. For example, in order to map"Vendor SKU" from Salsify to the Magento "sku" product attribute, our**Property Mapping** would look like this:

{ "Vendor SKU":"sku", "Item Name":"name"}

We can also pass an array to set the value in multiple attributes:{ "Vendor SKU":["sku", "url_key"], "Item Name":"name"}

In the above example, our "Vendor SKU" will be used to map our product tothe Magento "sku" attribute, as well as the "url_key" Magento attribute.

For instance, if our "Vendor SKU" is TEST-0001 in Salsify, our mapping willcreate (or update) a Magento product with a "sku" of TEST-0001 and a"url_key" of `/test-0001.html`.

2. Enable Website ID(s) Mapping

Enable or disable the Website ID(s) Mapping feature.

Website Mapping enables the user to map products to the Magento websiteof their choosing from a Salsify Channel (i.e. websites with differentlanguages, or different countries).

If this feature is disabled, the Magento 2 Salsify Connector will map productsto the default website. If this feature is enabled, but no Salsify Property isfound to match, the Magento 2 Salsify Connector will map products to thedefault website.

3. Website ID(s) Field

The Salsify Property you've defined that holds a comma separated list ofWebsite IDs values in which to map the products to from the Salsify Channel.

e.g. `magento_website_codes` would be your Salsify Property, and what youwould enter in the Magento 2 Salsify Connector Website ID(s) field. Thevalue(s) of the Salsify Property would be the comma separated list of WebsiteID(s) you wish to map products to.

CUSTOM OPTIONS

1. Enabled


2. Attributes Field

Specify the Salsify Property in which the connector will look for a json objectto create custom options from.

of 21



A json object is required to set up and map a products custom options. Foreach option, there are required fields that also need to be set. Here is anexample json object that would map one custom option “Color” with threeoptions “Red”, “White”, and “Blue”.

{"1": {

"sort_order": 1,"title": "Color","price_type": "fixed","price": "","type": "drop_down","is_require": 0,"is_default":1,"values": [{

"record_id": 0,"title": "Red","price": 10,"price_type": "fixed","sort_order": 1,"is_delete": 0

}, {"record_id": 1,"title": "White","price": 10,"price_type": "fixed","sort_order": 1,"is_delete": 0

}, {"record_id": 2,"title": "Blue","price": 10,"price_type": "fixed","sort_order": 1,"is_delete": 0

}]

}}

Here is an example with this in a Salsify Property:

of 21



PRODUCT RELATION SETTINGS

1. Related Products Enabled

Enable or disable the functionality of related products.

2. Property

Specify the Salsify Property in which the connector will look for a commaseparated list of product skus to create related products from.

3. Product Crosssell Enabled

Enable or disable the functionality of crosssell products.

4. Products Crosssell Property

Specify the Salsify Property in which the connector will look for a commaseparated list of product skus to create crosssell products from.

5. Product Upsells Enabled

Enable or disable the functionality of upsell products.

6. Product Upsell Property

Specify the Salsify Property in which the connector will look for a commaseparated list of product skus to create upsell products from.

ATTRIBUTE SET SETTINGS

1. Attribute Set Mapping Enabled

Enable or disable the Attribute Set Mapping feature.

2. Attribute Set Property

The Salsify Property you’ve defined that holds the name of the MagentoAttribute Set you wish to map the product to.

e.g. If you have a Magento Attribute Set “Accessories”, you would create aSalsify Property, for example “Attribute Set”, with a value “Accessories”. Whenthe product is created, it will be placed in the “Accessories” Attribute Set.

of 21



Please note, Magento Attribute Sets that you wish to import into must existbefore importing can take place. The Trellis Salsify Connector cannot createMagento Attribute Sets on-the-fly.

CATEGORY IMPORT SETTINGS

1. Category Mapping and Generation

Enable or disable the Category Mapping and Generation feature.

Category Mapping and Generation allows the mapping or creation ofcategories for your products on-th-fly.

2. Category Parent

When generating categories from Salsify Properties, specify the Magento 2Category upon which ALL categories from Salsify will be created under.

3. Category Field

This field allows you to input a Salsify Property that you use for categories.Categories in Salsify can be (and should be) nested. The Magento 2 SalsifyConnector will recognize these nested categories and place the products intheir respective category, or create the categories on-the-fly.

4. Category Type

Currently, the Trellis Salsify Connector only supports “Simple String” typecategories.

5. Category String Delimiter

Enter the delimiter for category strings. This CAN NOT be a comma.

An example category string in Salsify would look like: “Grandparent > Parent> Child”, with the delimiter set as “>” in the Magento configuration field.

DEFAULT VALUES

1. Default Value Mapping Enabled

Enable or disable the Default Value Mapping feature.

The Default Value Mapping feature allows you to specify default values forproducts from a Salsify Channel upon publication. Common uses would be toset the stock status for products to true, or set the visibility of the product onthe website.

2. Default Value Mapping

The value of the setting expects a JSON object.

{ "status": true, "stock_data": {

of 21



"is_in_stock": true, "manage_stock": false, "qty":9999, "use_config_manage_stock": false }, "visibility": 4}

RABBITMQ

RabbitMQ is a message broker and queueing software used to lighten the load ofmassive product feeds. Instead of digesting a feed of 30,000 products all at once,RabbitMQ can be setup to digest them over time at a set interval.

To install RabbitMQ, head over to their [official website](https://www.rabbitmq.com/download.html#installation-guides) and follow thedocumentation. [Magento also has guides on the topic](https://devdocs.magento.com/guides/v2.3/cloud/project/project-conf-files_services-rabbit.html).

1. Enabled

Enable or disable the functionality.

2. Host

The host where RabbitMQ lives, usually localhost.

3. Port

The port RabbitMQ will bind to in order to accept client connections.

4. User

The RabbitMQ user created for your Magento instance.

5. Password

The RabbitMQ password for the user listed above.

6. Vhost

The RabbitMQ vHost for this instance of Magento.

7. Number of Product(s)

The number of products you would like to sync from RabbitMQ at a time.Default value is 10.

8. Cron Expression

The cron value in which you’d like to sync products from RabbitMQ.Default value is every 15 minutes.

DEBUGGING

1. Salsify Connector Version Number

Displays the currently installed version of the Trellis Salsify Connector.

of 21



2. Download Log File

If you ever have any problems with the Magento 2 Salsify Connector, a buttonis provided to download the latest log files generated by the connector. Youcan use this file to debug any problems the connector may be having.

USAGE

of 21



MANUALLY

1. Button Sync

Arguably the easiest way to sync your products between the Salsify & Magento 2platforms, the Connector offers syncing your products at the press of a button.Located in the Magento 2 Admin Panel: Stores -> Configuration -> (Tab)**Trellis**-> **Salsify** -> (Section) General -> **Salsify Sync**.

2. Command Line Interface

Another way to sync your products between the Salsify & Magento 2 platforms isby use of a built-in console command. On your server, navigate via console toyour Magento 2 directory and execute the following command:

php bin/magento salsify:sync

AUTOMATICALLY

When a product is updated on the Salsify platform, it is capable of setting a flag onyour Magento 2 instance via webhooks, then updating those products in Magento2 via cron on a schedule.

1. Webhooks

To use webhooks, they need to be enabled on your Magento 2 platform asdescribed above, and enabled on your Salsify platform.

Magento 2: Stores → Configuration → [Tab] Trellis → Salsify → Webhooks

1. Enable Webhooks

2. Create a Client ID

Salsify: More → Channels → (Your Channel) → Notifications → Call Webhook:Successful Publication

The build of the URL is important:

https://your-store.com/rest/all/V1/salsify/update/<Client ID>

The Client ID you’ve created in the Magento 2 Salsify Connector admin settingspanel needs to match the one at the end of the URL in order for webhooks tosuccessfully communicate and verify the request.

The route rest/all/V1/salsify/update/ sets an interanl flag that triggers the updatingof products.

2. Cron

The webhook described above will set a timestamped flag when called upon. TheMagento 2 cron will pick up that flag and run the product update. After asuccessful update, the flag will be removed in anticipation of the next webhookupdate. This cron is set to run every 15 minutes by default to ensure the systemis not overloaded with requests from Salsify.

PRICE

of 21



Trellis is happy to provide this extremely convenient and time-saving module for only$2,500.

INSTALLATION

An installation service is available for an additional $2,500.

1. Technical discovery outlining how we will approach the Salsify and Magento integration

2. Trellis will follow proper development operations that will reduce the risk of web

development errors, allowing for faster development, easy deployment, and the ability to

experiment and Q/A in a staging environment before going live.

1. Trellis will install the Magento 2 Salsify connector on all appropriate environments

2. If proper development operations are not in place, additional fees may apply

3. Trellis will bulk create attributes, categories, and products via the integration from Salsify

to Magento

1. Trellis will consult with the client on the best ways to map products, attributes,

attribute sets, and categories

2. Trellis will also bulk integrate images and media from the Salsify platform in Magento

3. During discovery we may determine to manually create or adjust attributes and

categories due to certain limitations and parameters

4. Quality assurance & testing of the integration

5. Production deployment of the integration

1. Trellis is not providing or creating content.

2. Trellis can not do major consulting work on your Salsify or Magento implementation

(additional fees may apply, if needed)

3. Trellis will not do any major data manipulation work to integrate the data, that data

will integrate as is or will be changed by the client

4. Any bugs with your Magento implementation affecting the Salsify integration will not

be included. Additional fees may apply if Trellis has to fix them.

ABOUT TRELLIS

of 21



Trellis is a forward thinking digital agency and information technology company that focuses onbuilding scalable and effective websites for our clients. Our tactical approach to improving yourwebsite and web presence focuses on four major targets: Strategy, design, technology & operations,and post launch maintenance & marketing.

Trellis is a full service eCommerce solution provider that specializes in implementing Magento,based websites. Our capabilities allow us to plan and design a solution that not only meets yourspecific goals and budget today, but will also scale with you as you grow. Once a site is launched westick side by side with our clients to help them improve the site and market the site to generate morecustomers.

Unlike many development firms, our work does not cease there. In order to achieve maximum ROI itis essential to invest properly in the continual expansion of your online reach while constantlymonitoring and improving your website to keep your conversion rate high. Therefore we work withour clients on an on going basis to consistently improve their websites.

CONTACT TRELLIS

[email protected]

855-567-3843

of 21


mailto:[email protected]


VERSION HISTORY

Version # Revision Date Changelog1.4.1 08/02/2019 Remove $digitalAssetExportUrl parameter.1.4.0 08/01/2019 MEQP2 fixes.

Fix webhooks to digest POST events.Cleanup webhook methods.Stop webhook cron from running if it is disabled.

1.3.4 07/17/2019 Add proxy to avoid area code not set.Add message for null payloads.Allow webhook cron to be declared by the client.Turn comments into tooltips.

1.3.0 07/02/2019 Automatic Downloadable Packages.1.2.9 06/25/2019 Fix RabbitMQ Implementation.1.2.8 06/18/2019 Fix attributes global mapping.

Fix attributes global mapping.Fix ordering.Fix ordering.Fix Image Attribute Update.Imporved Category Sync.Fix trim.Improved category mapping.

1.2.0 05/29/2019 Fix conflict.Implement RabbitMQ.Implement RabbitMQ.Implement RabbitMQ.Implement RabbitMQ.Implement RabbitMQ.Refactor.Complete CS.Fix undefined variable.

1.1.3 05/24/2019 Fix category check. Fix chance of duplicate video.1.1.2 05/23/2019 Fix category mapping issues.

Fix duplicate image downloads.1.1.0 Add Product Video Functionality.

1.0.17 05/12/2019 Wrap image processing in try/catch.Check if a given media filename is valid.Better error handling on product updates.Cleaner logging.Convert to LF.

HOTFIX 05/08/2019 Fix undefined variable.1.0.11 05/08/2019 Improve logging accuracy.

Remove unnecessary logging.PHPDoc Block generation.README.md additions, fixes.Comment attribute logging.Fix multiselect values.Fix incorrect sku catch.

1.0.4 05/06/2019 Add README.md to module files.Fix label setting for attributes.Check all files for metadata.

of 21



Log Magento Edition, Version1.0.0 03/04/2019 Initial Release

of 21


Magento 2 Salsify Connector - Trellis · Magento 2 Salsify Connector INSTALLATION & CONFIGURATION...

Documents

Transcript of Magento 2 Salsify Connector - Trellis · Magento 2 Salsify Connector INSTALLATION & CONFIGURATION...