Trellis Magento 2 Salsify Connector

Transcription

1 Trellis Magento 2 Salsify Connector Version 0.x 09/01/2018

2 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 Media & Images 7 Field Mapping 8 Category Import Settings 10 Default Values 10 Debugging 11 Usage 12 Manually 12 Automatically 12 Price 14 Installation 14 About Trellis 15 Contact Trellis 15 VERSION HISTORY 16

3 Introduction Overview Salsify is a leading cloud base PIM solution that can store and organize all your product data. We provide the tooling to map almost anything from Salsify into Magento 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 class ecommerce capabilities. Purpose of The Magento 2 Salsify Connector The Magento 2 Salsify Connector allows you to connect your Magento 2 store to your Salsify account in order to easily manage products across platforms in one place. Update and publish your products in Salsify and have them sync automatically to your Magento 2 storefront. You choose what Salsify Properties automatically pull into your Magento 2 store to update and what features to enable, such as product image galleries, or the ability to map configurable (base) products to simple (sellable) products.

4 Compatibility Magento CE EE

5 Installation & Configuration Installing 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 Admin Panel. 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 your Salsify Channel. 3. Automatically Enable New Images Automatically enable new images to appear on product pages. 4. Ignore Timestamp and Always Update Ignore the Salsify timestamp and update the products. 5. API Base URL The URL used to access the Salsify API. 6. API Key

6 Your auth token (API Key) can be retrieved by going to Profile -> API Access -> Show API Key. a. The Salsify Magento 2 Connector uses a query parameter to pass your auth token: =<auth_token> b. In order to call any Salsify APIs, you must provide your authentication token (API Key). The auth token is specific to a user account. 7. Product Feed Channel ID The Salsify Magento 2 connector uses channels to retrieve the latest product feed. A channel is configured to export your selected products and their attributes in JSON format. a. Set up a Channel to Export your JSON i. Click Product Selection and choose your products. ii. Go back and click Product Feed. iii. Set Format to JSON. iv. Choose the columns you want to export (these are product attributes you have in Salsify). v. Go back and click _Publication Schedule_ - you can configure this channel to be published every night so that you are dealing with up-to-date data. b. Retrieve the Channel ID i. This ID will be used to target the channel for future requests. It can be found at the end of the URL when you click into the channel. E.g API Timeout Set the Timeout (in milliseconds) for the API calls. If the API receives no response in the given time, the APU will timeout. 9. SSL Verify Peer Verify the authenticity of the peer's certificate. When negotiating an SSL connection, the server sends a certificate indicating its identity. The Salsify Connector will verify whether the certificate is authentic. 10.Sync Action The Sync Action button will trigger a manual sync from your Salsify Channel into Magento 2. Always remember to re-publish your channel on the Salsify platform to get the latest updates. Webhook

7 1. Enabled Enable or disable the functionality of the 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. For security purposes, we recommend a string with at least 12 characters. 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 configurable products. In order to map configurable (base) products to simple (sellable) products from Salsify to Magento 2, we need to supply Salsify products with a user created 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 are using the Sellable (simple) products color property to create different (simple) products in Magento. Media & Images 1. Digital Asset Feed Enabled Enable or disable the Top Level Digital Asset Feed. The Salsify Product Feed from your channel may contain a broken-out payload of the digital assets your products include. If this is the case, we use this option to tell the connector to look in this broken-out payload for your products digital assets. 2. Product-Level Digital Assets Enabled The Salsify Product Feed from your channel may contain an included payload of the digital assets your products include. If this is the case, we use this option to tell the connector to look in the included product payload for your products digital assets.

8 Field Mapping When a Salsify client doesn t name product properties in a Magento friendly way, we need to map Salsify Properties to Magento Attributes. IMPORTANT Salsify referrers to product attributes as properties. When working with Magento, these are attributes. Salsify property Magento attribute IMPORTANT Product attributes that you wish to map need to be created in Magento prior to syncing. IMPORTANT Product attributes that you wish to use to map configurable products to child products need to be created in Magento prior to syncing. 1. Property Mapping 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 to the Magento "sku" attribute, as well as the "url_key" Magento attribute.

9 For instance, if our "Vendor SKU" is TEST-0001 in Salsify, our mapping will create (or update) a Magento product with a "sku" of TEST-0001 and a "url_key" of `/test-0001.html`. 2. Image Mapping Enabled Enable or disable the functionality of Image Mapping. The Salsify Connector allows you to map images from Salsify to their products in Magento. In order to map images, we need to supply a mapped Salsify property to Magento attributes. 3. Image Tag Mapping Much like the Field Mapping feature, the Salsify Connector allows you to map images 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" } 4. Media Gallery Enabled Enable or disable the functionality of the Image Gallery. Media Gallery functionality allows you to assign multiple images from a Salsify Property into the product Media Gallery. The connector will download the images from this Salsify Property and map them accordingly into the Product Media Gallery. 5. Media Gallery Input the Salsify Property which holds additional media images for your product. 6. Category Mapping and Generation Enable or disable the Category Mapping and Generation feature. Category Mapping and Generation allows the mapping or creation of categories for your products on-the-fly. 7. 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 Salsify Connector will recognize these nested categories and place the products in their respective category, or create the categories on-the-fly. 8. Ready For Import Field **DEPRECIATED** This field will be removed from the connector. 9. Enable Website ID(s) Mapping Enable or disable the Website ID(s) Mapping feature.

10 Website Mapping enables the user to map products to the Magento website of their choosing from a Salsify Channel (i.e. websites with different languages, or different countries). If this feature is disabled, the Magento 2 Salsify Connector will map products to the default website. If this feature is enabled, but no Salsify Property is found to match, the Magento 2 Salsify Connector will map products to the default website. 10.Website ID(s) Field The Salsify Property you've defined that holds a comma separated list of Website 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 you would enter in the Magento 2 Salsify Connector Website ID(s) field. The value(s) of the Salsify Property would be the comma separated list of Website ID(s) you wish to map products to. Category Import Settings 1. Root Category Node ID When generating categories from Salsify Properties, specify the Magento 2 Root Category ID upon which ALL categories from Salsify will be created under. E.g. A value of `1` will create all categories from the Salsify products under the Magento 2 Category with an ID of `1`. 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 for products from a Salsify Channel upon publication. Common uses would be to set the stock status for products to true, or set the visibility of the product on the website. 2. Default Value Mapping The value of the setting expects a JSON object.

11 { "status": true, "stock_data": { "is_in_stock": true, "manage_stock": false, "qty":9999, "use_config_manage_stock": false }, "visibility": 4 } Debugging 1. Download Log File If you ever have any problems with the Magento 2 Salsify Connector, a button is provided to download the latest log files generated by the connector. You can use this file to debug any problems the connector may be having.

12 Usage Manually 1. Button Sync Arguably the easiest way to sync your products between the Salsify & Magento 2 platforms, 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 is by use of a built-in console command. On your server, navigate via console to your 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 on your Magento 2 instance via webhooks, then updating those products in Magento 2 via cron on a schedule. 1. Webhooks To use webhooks, they need to be enabled on your Magento 2 platform as described above, and enabled on your Salsify platform. Magento 2: Stores Configuration [Tab] Trellis Salsify Webhooks a. Enable Webhooks b. Create a Client ID Salsify: More Channels (Your Channel) Notifications Call Webhook: Successful Publication The build of the URL is important: -store.com/salsify/hook/update/client_id/ <Client ID>

13 The Client ID you ve created in the Magento 2 Salsify Connector admin settings panel needs to match the one at the end of the URL in order for webhooks to successfully communicate and verify the request. The route salsify/hook/update/client_id/ triggers the updating of products. 2. Cron The webhook described above will set a timestamped flag when called upon. The Magento 2 cron will pick up that flag and run the product update. After a successful update, the flag will be removed in anticipation of the next webhook update. This cron is set to run every 15 minutes to ensure the system is not overloaded with requests from Salsify.

14 Price 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, 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. a. Trellis will install the Magento 2 Salsify connector on all appropriate environments. b. 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. a. Trellis will consult with the client on the best ways to map products, attributes, attribute sets, and categories. b. Trellis will also bulk integrate images and media from the Salsify platform in Magento. c. 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. a. Trellis is not providing or creating content. b. Trellis can not do major consulting work on your Salsify or Magento implementation (additional fees may apply, if needed). c. 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. d. Any bugs with your Magento implementation affecting the Salsify integration will not be included. Additional fees may apply if Trellis has to fix them.

15 About Trellis Trellis is a forward thinking digital agency and information technology company that focuses on building scalable and effective websites for our clients. Our tactical approach to improving your website 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 your specific goals and budget today, but will also scale with you as you grow. Once a site is launched we stick side by side with our clients to help them improve the site and market the site to generate more customers. Unlike many development firms, our work does not cease there. In order to achieve maximum ROI it is essential to invest properly in the continual expansion of your online reach while constantly monitoring and improving your website to keep your conversion rate high. Therefore we work with our clients on an on going basis to consistently improve their websites. Contact Trellis hello@trellis.co

16 VERSION HISTORY Version Date Changelog 0.x 09\01\2018 Initial Commit