{"type":"doc","content":[{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration in Sana","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE:","type":"text","marks":[{"type":"strong"}]},{"text":" This section assumes that you are using Sana 9.3.0 and hereby is implementing a so-called Add On (The connector). See Sana Documentation in order to find the so-called Perfion Extension in the Sana-interface.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"After the connector has been installed, it needs to be configured in order for it to reach the Perfion API. This “connection to Perfion” is almost the only thing you need to configure in Sana, since the rest of the configuration resides in Perfion.","type":"text"}]},{"type":"paragraph","content":[{"text":"In Sana Admin, go to Apps -> Add-ons and pick any of the tabs. The list of “Installed add-ons” will contain “Perfion Add-on 3.0”, so simply hit the “Configure”-button for it. This will bring the dialog shown in Figure 4.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":50.0},"content":[{"type":"media","attrs":{"width":470,"id":"6f8d5955-3227-4abf-8a4b-0f3a7aafff53","collection":"contentId-244338214","type":"file","height":567}},{"type":"caption","content":[{"text":"Figure 1: A sample configuration of the Perfion Connector in Sana Admin","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Web Service Url:","type":"text","marks":[{"type":"strong"}]},{"text":" Here you type the full URL to the Perfion Web Service API. This is the source for data from Perfion. The connector accesses the ECommerce API provided by that service.","type":"text"}]},{"type":"paragraph","content":[{"text":"Web Service Timeout (Available from version 3.0.7): ","type":"text","marks":[{"type":"strong"}]},{"text":"Here you can change how much time you allow the Web Service to answer the ECommerce API methods called by the Sana Connector. The default timeout of 100 seconds, which is also the timeout used by older versions of the connector. Generally 100 seconds should be long time enough so this should only rarely be changed to allow more time.","type":"text"}]},{"type":"paragraph","content":[{"text":"User ","type":"text","marks":[{"type":"strong"}]},{"text":"and","type":"text"},{"text":" Password (Available from version 3.1.5","type":"text","marks":[{"type":"strong"}]},{"text":"): If Perfion API Service Authentication is enabled on the Perfion API, it will require you to supply the user name and password for a valid user. These can be supplied here.","type":"text"}]},{"type":"paragraph","content":[{"text":"Logging:","type":"text","marks":[{"type":"strong"}]},{"text":" Enable logging in order to log all calls from Sana, all data fetching and data transformation done by the connector. This logging is quite verbose, and should only be enabled when configuring and debugging an installation. ","type":"text"}]},{"type":"paragraph","content":[{"text":"From Connector version 3.0.5 you can additionally choose to log to the Perfion Add-on Storage. This only makes sense, when you have access to that storage from for example File Explorer. You are likely only to have that when running your Sana On-Premise (as opposed to in the cloud). When running ON-Premise you will find these log files in the folder \\@data\\packages-data\\Perfion where Sana is installed. Logging to Add-on Storage creates files suitable for debugging the communication between Sana, ERP and Perfion. The files created are quite similar to those created by the 2.0-connector, for those familiar to that. When logging to Add-on storage you additionally have the option to prefix all filenames with a timestamp. That way you can log everything that happens over a time period. Be aware, though, that these log-files might take up considerable space and they are not cleaned up automatically. Another warning: Be careful when deleting all the debug-files not to delete the file named “imagecache.xml” (if enabled). IF you accidentally delete it, though, it will turn up again provided you do not recycle the site.","type":"text"}]},{"type":"paragraph","content":[{"text":"Output Images as Fields on Products and Variants","type":"text","marks":[{"type":"strong"}]},{"text":": Introduced in Connector version 3.0.8, enabling this setting will make all images mapped in the ECommerce API become output as fields (not images) to Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"When enabled Sana will receive the unique guid of all images mapped to Sana as Fields, like shown below where 3 images are shipped to Sana:","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"As can be seen it is the unique Guid that is sent to Sana as the value of each field.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a very special setting reserved for a special custom setup done by Sana. This should be left ","type":"text"},{"text":"off","type":"text","marks":[{"type":"strong"}]},{"text":" in all but these cases.","type":"text"}]},{"type":"paragraph","content":[{"text":"Enable Image Cache","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"Image Life Time","type":"text","marks":[{"type":"strong"}]},{"text":" controls an Image Cache added to the connector in version 3.0.3. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Ignore Errors From ERP: ","type":"text","marks":[{"type":"strong"}]},{"text":"Normally, when the Perfion connector calls the ERP, any errors returned from the ERP will make the Connector simply return the result (the error) from the ERP to Sana, without trying to augment the result with data from Perfion. If this setting is on, however, such errors will not stop the connector from going to Perfion augmenting the data. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE:","type":"text","marks":[{"type":"strong"}]},{"text":" Even with this setting on, the errors from ERP are still returned to Sana. Normally this setting is only on during an implementation phase.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Refresh configuration on every call: ","type":"text","marks":[{"type":"strong"}]},{"text":"The connector caches the entire setup made in Perfion (Mappings, Settings etc.) in order to work as fast as possible. Only when Sana calls the “GetEntityFields”-method this internal cache is refreshed. Enabling this setting will refresh this cache on every call to the connector, so that changes in the configuration in Perfion is immediately reflected on next call.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is helpful when doing changes to the setup to have them immediately reflected in Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"This setting should only be enabled when configuring and debugging an installation, since having it enabled slows the connector.","type":"text"}]},{"type":"paragraph","content":[{"text":"Bottommost you will find the ","type":"text"},{"text":"Version","type":"text","marks":[{"type":"strong"}]},{"text":" of the connector together with the version of the called ECommerce API. The later can only be retrieved, if the Web Service Url is filled out and there is an answering ECommerce API at its endpoint.","type":"text"}]},{"type":"paragraph","content":[{"text":"Test Connection Mode: ","type":"text","marks":[{"type":"strong"}]},{"text":"Sana quite frequently calls a method named “TestConnection” to test whether it has connection to ERP. If this call continuously fails, say, 3 times Sana will go into “Maintenance mode” meaning a lot of things, for example that the order process is hampered. Introduced in Connector 3.0.5 you now have the option to choose whether the connector should only call the ERP ","type":"text"},{"text":"or","type":"text","marks":[{"type":"em"}]},{"text":" both call the ERP and Perfion when Sana tests whether or not a connection is available. Since Perfion is not involved in the order processing it is recommended to switch this to “Only ERP”. For those used to the 2.0 connector, this was indeed how “TestConnection” was handled there.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Test Connection ","type":"text","marks":[{"type":"strong"}]},{"text":"button (not to be confused with the above described “TestConnection”-call done by Sana “behind the scenes”) tests that the Connector is configured correctly. Before Perfion is configured, you will get an error as the example shown in Figure 2. In the example we can see, reading the red message from top to bottom, that the Web Service Url does indeed point to a Perfion API, that the ECommerce API is installed with version at least 4.5.52 but the connector complains that it does not find any Channels set up for Sana (known as stores or web sites in Sana).","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":31.0},"content":[{"type":"media","attrs":{"width":219,"id":"d27fbf1b-da88-4836-9151-05fac9984239","collection":"contentId-244338214","type":"file","height":87}},{"type":"caption","content":[{"text":"Figure 2: Clicking Test connection when something in Perfion is still to be configured","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Table 1 below lists all the possible issues you can get from clicking “Test Connection” and which steps should be taken to correct them. Each issue will all make the test list show up in red as shown in Figure 2.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"752491eb-74e0-40c5-892d-7847fa52b86b"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Error message","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Perfion Web Service... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The connector cannot call the Perfion API pointed to by the Url.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Check that the Web Service Url in Sana indeed points to a Perfion Web Service and that this end point can be reached from the Server running Sana.","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Check that the Perfion API is correctly configured and can connect to the Perfion Database.","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Run any ECommerce API-method (for example GetVersion) using the Web Tester tool. Preferably using the server running Sana. You might get an error stating that database is not the right version. Make sure to upgrade/downgrade Perfion API to match database version.","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Note: Test Connection tests only back end. The Sana front end must be able to reach the Perfion API as well.","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"ECommerce API configured... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"The Perfion API installed does not support ECommerce API.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Upgrade the Perfion API to version 4.5 R1 2019 (4.5.52) or later.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"ECommerce API must be at least version 4.5.52... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"ECommerce API installed must be version 4.5 R1 2019 (4.5.52) in order to support methods called by the Connector.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Upgrade the Perfion API to version 4.5 R1 2019 (4.5.52) or later.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"0 Sana Store(s) found... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"There needs to be at least one Channel in the ECommerce API that has ECommerce System set to “Sana” (without quotes)","type":"text"},{"type":"hardBreak"},{"text":"In Connector versions previous to 3.0.4 you would get this if your license did not include “Sana Connector”.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Create a channel associated with ECommerce System “Sana”. ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Missing license to use Sana Connector… Failed","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"(Connector version 3.0.4 and later)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"You need to have license for Sana Connector.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Contact Perfion Support to obtain a Perfion License File containing license for Sana Connector.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Failed to retrieve configuration for Sana Store(s)... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"For some reason the configuration for all channels marked for Sana cannot be fetched.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"This should really never happen. If problem persists please Contact Perfion.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"“x” Image Service(s)... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"At least one Perfion Image Service cannot be accessed by Sana.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Make sure the ImageUrl-setting is correctly typed for all channels associated with Sana. The Url typed must be accessible from Sana (back end).","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"The Image Server is ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" accessed by the server running the EC API but directly by the connector. Unless (of course) the EC API is accessed through other means than the Connector.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"“x” File Service(s)... Failed","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Same as above, just for the File Services.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1},"content":[{"type":"paragraph","content":[{"text":"Same as above, just for the File Services.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Table 1: The list of issues that can be met clicking “Test connection” and measures on how to remedy them","type":"text"}]},{"type":"paragraph","content":[{"text":"The next section will take you through the steps necessary to configure Perfion. When that is done, clicking “Test connection” should give a result similar to the one shown in Figure 3.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":31.0},"content":[{"type":"media","attrs":{"width":199,"id":"0633ff1d-2a0e-4d2e-8714-b3efd610f274","collection":"contentId-244338214","type":"file","height":107}},{"type":"caption","content":[{"text":"Figure 3: Clicking Test connector when everything is OK","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Setting up Image Transfer","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to make sure that images are transferred correctly to the frontend, the following steps are required:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Go to Scheduled Tasks, click “Edit” on Product Image Import","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Ensure that “Import product images from ERP” is enable","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center","width":50.0},"content":[{"type":"media","attrs":{"width":331,"id":"96db76bc-7e26-401c-aac0-5f04e7aab175","collection":"contentId-244338214","type":"file","height":218}},{"type":"caption","content":[{"text":"Figure 4: Product image import","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Where are the missing settings known from 2.0?","type":"text"}]},{"type":"paragraph","content":[{"text":"The old Connector 2.0 had a few more settings. In that version, you could set two additional urls pointing to an Image- and a File-service, respectively. Furthermore, you had the possibility to switch between the “Advanced” and “Simple” mode.","type":"text"}]},{"type":"paragraph","content":[{"text":"These settings are gone for two different reasons:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Image and File-server urls are found in the ECommerce API settings, so they are no longer needed in the Sana Admin interface.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Simple and Advanced mode relied on accessing file folders in the Starter Site. This option has been removed as part of making the connector “cloud aware”, i.e. it may no longer access files in the Starter Site.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"As a consequence of item 2, the possibility of customizing the connector using customized xsl-documents, known from the 2.0 connector for 9.1.4-9.2.x, is no longer available in the 3.0 connector.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuration in Perfion","type":"text"}]},{"type":"paragraph","content":[{"text":"This section will take you through all the necessary steps to make a first simple configuration.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Install ECommerce API","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"If you have ECommerce features as per the screenshot below, ECommerce API features are created. Following version 5.2 these features are installed automatically, in prior versions you will need to go to ","type":"text"},{"text":"Settings > Integration","type":"text","marks":[{"type":"strong"}]},{"text":" and Install ","type":"text"},{"text":"ECommerce API Features and Data","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"paragraph","content":[{"text":"To see the most important of the features that have been added, go to “Feature Data”, then expand the “String”-features node and finally expand the “ECommerce Features”-node. Here you will find seven selectable features where some needs to be filled out by you and the rest can and should be left as is. In Figure 5 one of the features, the ECommerce Settings, are shown:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":988,"id":"f4f23b06-676b-477a-ad69-fb6457f7a55f","collection":"contentId-244338214","type":"file","height":654}},{"type":"caption","content":[{"text":"Figure 5: The ECommerce Settings within Perfion for the Connector","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Below is an overview on what each of the ECommerce-features on the left hand side contains:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Channel","type":"text","marks":[{"type":"strong"}]},{"text":": Here you create all the channels you needed. Roughly speaking, you will need a channel per output channel. For the Sana Connector you are likely to need a channel per website/shop. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Entity:","type":"text","marks":[{"type":"strong"}]},{"text":" Here are a list of all entities supported currently by the ECommerce API: Site, Category, Product, Variant and Language Deviation. This is used internally by the connector and should not be modified.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Mapping:","type":"text","marks":[{"type":"strong"}]},{"text":" Here you find all mappings from Perfion to some Channel (that is, to Sana). A mapping is a way of expressing that “X in Perfion is called Y in Sana”. All mappings can be edited by clicking this node. This is where the main part of the configuration of the connector will take place.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Output Kind:","type":"text","marks":[{"type":"strong"}]},{"text":" Here is a list of all the Output Kinds, that is, ways of expressing how the “Y” from previous item should be output knowing “X”. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Settings:","type":"text","marks":[{"type":"strong"}]},{"text":" Here you find the settings needed to set up the Connector. These are the ones shown in Figure 5.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce System: ","type":"text","marks":[{"type":"strong"}]},{"text":"Here you will find a list of ECommerce Systems to pick from. Version 4.5.52 auto creates four ECommerce Systems: Shopify, Ucommerce, Sana and Magento, since these are the systems recognized by Perfion and the systems for which Perfion provides a connector. If you are making your own output from the ECommerce API, it makes good sense to add a new ECommerce System to this list. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ECommerce Type:","type":"text","marks":[{"type":"strong"}]},{"text":" This is just a selectable feature that you will need if you want to use support for variants. The two values here “Product” and “Variant” should not be modified in any way. ","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE:","type":"text","marks":[{"type":"strong"}]},{"text":" From version 4.5.52, when accessing the ECommerce API for data belonging to one of the known channels, it is checked that the Perfion license does include a license to connector used.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The next sections will take you through setting up an entire (although) small configuration of the connector.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ECommerce Channels","type":"text"}]},{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"Channel","type":"text","marks":[{"type":"em"}]},{"text":" is the ECommerce API equivalence of a store (aka website) in Sana. Below in Figure 6 a single channel named “SanaStore” has been added and assigned to the ECommerce System ","type":"text"},{"text":"Sana","type":"text","marks":[{"type":"em"}]},{"text":". Assigning it to the ECommerce System Sana makes it recognizable as a channel used for Sana.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":985,"id":"c7e90f91-2c6d-44c4-b181-aecd75b105f1","collection":"contentId-244338214","type":"file","height":496}},{"type":"caption","content":[{"text":"Figure 6: A singel channel name “SanaStore” has been added to the ECommerce API as a “Sana”-channel","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The name “SanaStore” is not chosen to be chosen randomly. It must exactly match the Sana Web Site Id for the store whose data should be augmented with data from Perfion. SanaStore is a demo web site on our demo server.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE:","type":"text","marks":[{"type":"strong"}]},{"text":" The channel named “*” is not a real channel, but the item is there to allow picking the *-channel (“star-channel”) which means “all channels”. More on the *-channel in a later chapter where we discuss how to setup multiple channels (multiple shops) in a single Perfion installation.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ECommerce Settings","type":"text"}]},{"type":"paragraph","content":[{"text":"Having added a channel (a store) and associated it with Sana will allow the “Test connection” in the Sana Admin-interface to get a bit further. Now it should show the next issue (as compared to Figure 3):","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":31.0},"content":[{"type":"media","attrs":{"width":186,"id":"86fe8355-f513-4f8a-8b90-fea3c576667e","collection":"contentId-244338214","type":"file","height":105}},{"type":"caption","content":[{"text":"Figure 7: The next issue when performing a “Test connection” is that Sana cannot reach either the Image or the File-server","type":"text"}]}]},{"type":"paragraph","content":[{"text":"In order to fix that, let us go to ECommerce Settings to supply some settings for the ECommerce API (and hereby the Sana Connector). We will add a Url to both the Perfion Image Service and the Perfion File Service.","type":"text"}]},{"type":"paragraph","content":[{"text":"Going to “ECommerce Settings” in Perfion will show all settings currently set up. In Figure 8 all settings have been set up correctly (for some demo-setup):","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":454,"id":"3c064df9-cb3d-4ef9-abd5-78d0faa4564e","collection":"contentId-244338214","type":"file","height":160}},{"type":"caption","content":[{"text":"Figure 8: Sample ECommerce Settings","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE:","type":"text","marks":[{"type":"strong"}]},{"text":" TimeZone is supported starting from Perfion 4.7.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The following describes the settings shown in Figure 8. The first 5 should be considered the minimum number of settings: 4.2.3.1","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: ImageServiceUrl","type":"text"}]},{"type":"paragraph","content":[{"text":"This url should point to a Perfion Image Service usually installed in the exact same location as the Perfion API. The Url should be on the form:","type":"text"}]},{"type":"paragraph","content":[{"text":"http://:/perfion/image.aspx","type":"text"}]},{"type":"paragraph","content":[{"text":"The Sana Connector will work without this url, but only in the rare case that no images come from Perfion.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: FileServiceUrl","type":"text"}]},{"type":"paragraph","content":[{"text":"This","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"works exactly as ImageServiceUrl, but is used by the Sana Connector for File Attachments. This Url should be on the form:","type":"text"}]},{"type":"paragraph","content":[{"text":"http://:/perfion/image.aspx","type":"text"}]},{"type":"paragraph","content":[{"text":"Only in situation where attachments are not needed by some installation, you can avoid setting this up, but it does not hurt to do it despite it is not being used.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: Languages","type":"text"}]},{"type":"paragraph","content":[{"text":"Here you indicate which languages in Perfion that should be output to Sana. In this case, let us simply output English, German and Dutch to Sana (Perfion language name “EN”, “DE” and “NLD”). ","type":"text"}]},{"type":"paragraph","content":[{"text":"Sana does not work with languages but cultures denoted by their LCID (a Language Code Identifier proprietary to Microsoft). In later section we will see, how we make the ECommerce API translate from the Perfion Language to the Sana LCID.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: ImageHeight","type":"text"}]},{"type":"paragraph","content":[{"text":"This setting controls the height of all images sent to Sana. This is here set to 1024, but you can change it here if wanted. Default value for this setting is 1024, so since we set it to exactly that in Figure 11 we might as well delete the setting.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: ImageWidth","type":"text"}]},{"type":"paragraph","content":[{"text":"Same as ImageHeight, except that it controls the width of the images sent to Sana rather than the height.","type":"text"}]},{"type":"paragraph","content":[{"text":"The next two settings require a bit more description","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: SanaTimeDifference (requires SanaConnector 3.0.1 or later)","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Note: This configuration was introduced in earlier Perfion versions when time zones were unsupported, requiring manual alignment with Sana, which always operated on UTC.","type":"text"}]},{"type":"paragraph","content":[{"text":"Since Perfion introduced time zone support, this setting has become mostly redundant but was kept to ensure compatibility for users ","type":"text"},{"text":"upgrading without proper time zone configuration.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Sana now primarily uses UTC time, though not always","type":"text","marks":[{"type":"strong"}]},{"text":", which can cause discrepancies with Perfion’s time settings. When issues arise, the SanaTimeDifference setting helps correct misalignments.","type":"text"}]},{"type":"paragraph","content":[{"text":"While its purpose has evolved, this setting remains useful for resolving time-related conflicts between Perfion and Sana.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Here you enter the whole number of hours (positive or negative) that tells the connector what the time difference is between Perfion and Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"In most installations, Sana runs on UTC time, but that is not always the case, they are actually using “IIS Server Time”. To find Sana timezone, please check what timezone the IIS-server running Sana is using.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Perfion timezone is defined in the Ecommerce setting “Timezone” (See ","type":"text"},{"text":"Ecommerce Documenation","type":"text","marks":[{"type":"link","attrs":{"href":"https://perfion.atlassian.net/wiki/spaces/PIM/pages/244331086"}}]},{"text":"). If this setting has not been defined, the timezone of the Perfion database will be used. If you are using Perfion version 4.7 or later, the database will be in UTC time.","type":"text"}]},{"type":"paragraph","content":[{"text":"SanaTimeDifference should be set to the time difference between the Sana IIS-Servers timezone and the timezone of the Perfion database. Here are a few examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Perfion runs in Universal Time Coordinated (UTC) – Sana runs also in UTC","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"This will be the most common scenario, and in this scenario this setting is redundant and not needed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Perfion runs in UTC – Sana Runs in Central European Time (CET)","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"SaneTimeDifference should be set to -1, since Coordinated Universal Time is one hour ahead of CET","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Perfion runs in UTC – Sana Runs in Pacific Time (PT) ","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"SanaTimeDifference should be set to -7, since Coordinated Universal Time is seven hours ahead of UTC.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Perfion runs in India Standard Time (IST) – Sana Runs in UTC","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"SanaTimeDifference should be set to -5.5, since India Standard Time is 5 and a half hours ahead of UTC. Note that you must use a “.” (punctuation mark) as decimal separator.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If you are unsure of what timezone your Perfion Database runs in, the difference can also be done in SQL Server Management Studio using the query shown in Figure 12:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":567,"id":"1c66607b-01d9-4996-a257-20a8b8ae8007","collection":"contentId-244338214","type":"file","height":564}},{"type":"caption","content":[{"text":"Figure 9: The SQL query to find database time and UTC-time","type":"text"}]}]},{"type":"paragraph","content":[{"text":"As can be seen in the figure the database is 2 hours ahead of UTC Time (because it is in Central European Time), so a -2 needs to be put in as time difference. This assumes that Sana runs on UTC, but remember to check the Sana IIS-server time.","type":"text"}]},{"type":"paragraph","content":[{"text":"Query is repeated below for easy copy/paste to Management Studio:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"sql"},"content":[{"text":"select getdate() as databasetime, getutcdate() as utctime, DATEDIFF(hour, getdate(), getutcdate()) as SanaTimeDifference","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: SanaCaptionTemplate (requires Connector 3.0.1 or later)","type":"text"}]},{"type":"paragraph","content":[{"text":"Per default only the caption on features are sent as Caption on Fields to Sana. Same could be done with the unit, but unfortunately there is currently the limitation in Sana that it does not support units on fields.","type":"text"}]},{"type":"paragraph","content":[{"text":"This limitation can been circumvented using the ","type":"text"},{"text":"SanaCaptionTemplate","type":"text","marks":[{"type":"em"}]},{"text":"-Setting in the connector. By setting this to some value, a template, you can make the unit from Perfion part of the caption sent to Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"For constructing such a template, you have three tags available: %CAPTION%, %CAPTIONALTERNATIVE% and %UNIT% each representing the similarly named properties on a feature in Perfion. In Figure 10, you see the feature ","type":"text"},{"text":"WeightKg","type":"text","marks":[{"type":"em"}]},{"text":" which has a unit set to kg (short for kilo gram).","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Settings: SanaCategoriesSource, SanaRelatedProductsSource and SanaAttachmentsSource (requires Connector 3.0.1 or later)","type":"text"}]},{"type":"paragraph","content":[{"text":"These 3 settings controls whether categories, related products and attachments come from either the ERP-System, Perfion or are completely disabled. They can be assigned one of the following values: None, ERP, Perfion.","type":"text"}]},{"type":"paragraph","content":[{"text":"Assigning one of them to ","type":"text"},{"text":"ERP ","type":"text","marks":[{"type":"strong"}]},{"text":"will fetch data from the ERP-system and ignore what comes from Perfion. This comes in handy, if, say, you products are related in ERP-system and you want to avoid doing the same in Perfion.","type":"text"}]},{"type":"paragraph","content":[{"text":"If any of the settings are not set (or setting is there but set to blank), it means the same as setting it to Perfion, i.e. all data comes from Perfion.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":752,"id":"6c64b23f-5238-4d7a-9ee4-27c8ccc98357","collection":"contentId-244338214","type":"file","height":738}},{"type":"caption","content":[{"text":"Figure 10: The feature WeightKG has its unit set in many languages","type":"text"}]}]},{"type":"paragraph","content":[{"text":"To output this to the Caption for the Field in Sana you could do a ","type":"text"},{"text":"SanaCaptionTemplate","type":"text","marks":[{"type":"em"}]},{"text":" as this: ","type":"text"},{"text":"%CAPTION% %UNIT%","type":"text","marks":[{"type":"strong"}]},{"text":". This will output “Weight kg” in English for the ","type":"text"},{"text":"WeightKg","type":"text","marks":[{"type":"em"}]},{"text":"-feature. You can also add literals to the tags and even put these literals within the tag, so that if tag is not filled out the literals will also not be output. Table 2 shows different combinations of templates, captions and units.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"6251aca4-5b73-4d68-a8ce-1d5daef3d771"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[260.0]},"content":[{"type":"paragraph","content":[{"text":"Template","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Caption","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Unit","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Output to Sana","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Note","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":4,"colwidth":[260.0]},"content":[{"type":"paragraph","content":[{"text":"%CAPTION% %UNIT%","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space added after weight","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space added before kg","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space output","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":4,"colwidth":[260.0]},"content":[{"type":"paragraph","content":[{"text":"%CAPTION% (%UNIT%)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight (kg)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space added after weight","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" (kg)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space added before kg","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ()","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Space and parenthesis output","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":4,"colwidth":[260.0]},"content":[{"type":"paragraph","content":[{"text":"%CAPTION%% (UNIT)%","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight (kg)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"(kg)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Nothing output","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":4,"colwidth":[260.0]},"content":[{"type":"paragraph","content":[{"text":"%CAPTION (UNIT)%","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight (kg)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Weight","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Nothing output","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"kg","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Nothing output","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":" ","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[227.0]},"content":[{"type":"paragraph","content":[{"text":"Nothing output","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Table 2: Different templates outputting Captions and units depending on their values.","type":"text"}]},{"type":"paragraph","content":[{"text":"As can be seen from Table 2, the third template counting from the top seems to be the best template of the four, since it outputs something sensible regardless of which of the combinations of features are used.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: TimeZone (requires Perfion 4.7 and later)","type":"text"}]},{"type":"paragraph","content":[{"text":"If you have Perfion 4.7 or later, the ECommerce API setting TimeZone should be used and set to “utc” (Coordinated Universal Time). This will make the ECommerce API use the exact same time zone as Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"When doing this make sure that the setting SanaTimeDifference is either deleted or simply set to 0 since there is no need to “convert” between times in Perfion and Sana.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting: SanaDefaultCultureId","type":"text"}]},{"type":"paragraph","content":[{"text":"As part of how the connector works, the ERP part of Sana tells the web part the LCID of which culture Sana recognizes as the default culture. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The connector picks that culture up, since it tells the web-part of Sana how it can expect xml-results to be formatted, and since the connector also produces XML for the Sana web part, it must adhere to those rules as defined by Sana. ","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two “things” that need to take the default culture into account, when xml is produced for Sana. These are: ","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Field Naming:","type":"text","marks":[{"type":"strong"}]},{"text":" How localizable fields should be named. Non-default cultures should have the LCID of the culture post fixed, i.e. ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":", if 1033 is not the default culture. For the default culture the localizable field for Description should simply be ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Value formatting:","type":"text","marks":[{"type":"strong"}]},{"text":" How dates and numbers are formatted. Here numbers and dates should be formatted as Microsoft defines \"NumberFormat\" and \"ShortDatePattern\", respectively, using the default culture.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"In some cases, Sana ERP reports a wrong Culture Id to the web-part of Sana, and hereby also the connector. In that case, you can choose to override whatever culture Sana ERP says. To do that, you can set the setting SanaDefaultCultureId to whatever LCID you would like. This will make the Connector produce its Xml using whatever id supplied in SanaDefaultCultureId instead of the one returned by Sana ERP.","type":"text"}]},{"type":"paragraph","content":[{"text":"In Figure 8 you can see this setting is commented out, since it normally is not necessary to set.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Settings: SanaDefaultCultureId_FieldNaming and SanaDefaultCultureId_ValueFormatting (Requires Connector 3.2.1)","type":"text"}]},{"type":"paragraph","content":[{"text":"The above described setting, SanaDefaultCultureId, controls both how fields are named and how numeric and date values are formatted. In Connector 3.2.1, however, it is possible to control the culture id used by each of these individually. On rare occasions that is needed. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The two introduced settings are:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SanaDefaultCultureId_FieldNaming:","type":"text","marks":[{"type":"strong"}]},{"text":" As the name implies this setting controls ","type":"text"},{"text":"Field Naming","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SanaDefaultCultureId_ValueFormatting:","type":"text","marks":[{"type":"strong"}]},{"text":" As the name implies this setting controls ","type":"text"},{"text":"Value Formatting","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If, say, SanaDefaultCultureId_FieldNaming is set, this setting will take precedence over SanaDefaultCultureId that again takes precedence over what Sana ERP tells the connector/Sana web part. Similarly precedence rules applies to SanaDefaultCultureId_ValueFormatting.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note: The above settings are not shown in Figure 8.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"A few more settings are available","type":"text"}]},{"type":"paragraph","content":[{"text":"There are a few more settings in the ECommerce API than shown above. One of them, ","type":"text"},{"text":"VariantSupportEnabled","type":"text","marks":[{"type":"em"}]},{"text":". For information in the remaining settings, please check ECommerce API-manual.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note how we for all settings have picked “*” as Channel name, despite that we in earlier section, created the “SanaStore” channel. We could indeed have picked that channel on all settings, but by picking the * we simply mean “all channels”. So if we at any later moment create another channel, the settings with a * are already set for that channel.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Important note: ","type":"text","marks":[{"type":"strong"}]},{"text":"It is considered an error if you set the same setting both for the *-channel and for some other channel, because the current ECommerce API reckons this as setting the same setting twice for that channel. This might be relaxed in a future version of the ECommerce API (where the setting set explicitly on the channel would override the *-channel setting).","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The *-channel works the same for the entire ECommerce API most notable also for mappings, which is described in the next sections.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ECommerce Mappings – Getting the cultures right for Sana","type":"text"}]},{"type":"paragraph","content":[{"text":"As noted earlier, Perfion works with Languages designated using the ISO 639-2 standard (with a few exceptions).","type":"text"}]},{"type":"paragraph","content":[{"text":"On the other hand, Sana uses cultures denoted by a LCID (Language. To make matters a bit more complicated, the ECommerce API uses cultures as well, but is using the RFC 1766-standard for naming them. See Table 3 below for a few examples:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"3c28d112-a15f-4e46-9e58-01a95da5637e"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[310.0]},"content":[{"type":"paragraph","content":[{"text":"Language","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Perfion Language","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"ECommerce API","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#bfbfbf","rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"Sana","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[310.0]},"content":[{"type":"paragraph","content":[{"text":"English (America)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"EN or ENU","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"en-US","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"1033","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[310.0]},"content":[{"type":"paragraph","content":[{"text":"German (Germany)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"DE or DEU","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"de-DE","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"1031","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[310.0]},"content":[{"type":"paragraph","content":[{"text":"Danish (Denmark)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"DAN","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"da-DK","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"1030","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#d9d9d9","rowspan":1,"colwidth":[310.0]},"content":[{"type":"paragraph","content":[{"text":"Dutch (The Netherlands)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"NLD","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"nl-NL","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[286.0]},"content":[{"type":"paragraph","content":[{"text":"1043","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Table 3: Examples of Perfion languages and their equivalent ECommerce API- and Sana -cultures.","type":"text"}]},{"type":"paragraph","content":[{"text":"The solution is simple. In order to configure the ECommerce API to use other culture designators we, for each Perfion Language, define a mapping and categorize it as a so-called “Language Deviation”. As we remember we specified the languages “EN” and “DE” so it is exactly these two that needs to get mapped to a designator suitable for Sana. This is done in Figure 11 below:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":528,"id":"1b1d7ac9-b9ce-4ca3-a22e-9d0e192e16f3","collection":"contentId-244338214","type":"file","height":144}},{"type":"caption","content":[{"text":"Figure 11: Note the two Language Deviations at the bottom","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ECommerce Mappings – For Products","type":"text"}]},{"type":"paragraph","content":[{"text":"Mappings are the single most important thing in the ECommerce API. Mappings is the place where you tell the connector with what data each entity (Product, Variant and Category) in Sana should be augmented with.","type":"text"}]},{"type":"paragraph","content":[{"text":"In this section we look at mapping data on products.","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to go into detail on what the ECommerce API can output, the ","type":"text"},{"text":"ECommerce API documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://perfion.atlassian.net/wiki/spaces/PIM/pages/244331086"}}]},{"text":" will tell you all there is to know about that. Here it should be noted, that not everything that can be done in the ECommerce API makes sense for the Sana Connector, but most actually does.","type":"text"}]},{"type":"paragraph","content":[{"text":"To start creating mappings for our demo-products we use the “Coffee demo-database” and considers the two products shown in Figure 12 below found in that database:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":601,"id":"7c8dfedc-bcc0-4164-9895-b6e6ce0a1c38","collection":"contentId-244338214","type":"file","height":96}},{"type":"caption","content":[{"text":"Figure 12: Two products in Perfion whose data we would like to map to Sana","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The 6 mappings shown in Figure 13 below will map exactly the products with the features shown in Figure 12 to Sana. This section will continue explaining how these 6 mappings work.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":452,"id":"fb31b900-3b11-4033-ad06-fa3bca694e34","collection":"contentId-244338214","type":"file","height":112}},{"type":"caption","content":[{"text":"Figure 13: The first 6 mappings made for all channels on the Product-entity","type":"text"}]}]},{"type":"paragraph","content":[{"text":"First thing worth mentioning is that a mapping should be read from left to right. In that order the features on a mapping are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Base value (often called “From”):","type":"text","marks":[{"type":"strong"}]},{"text":" Here you write what should be fetched from Perfion. In most cases you would here have a feature name, but other options are available. ","type":"text"},{"text":"“Please note that feature names in the “From” column are case sensitive, and must match the feature definition exactly.”","type":"text","marks":[{"type":"textColor","attrs":{"color":"#bf2600"}},{"type":"strong"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Output Kind: ","type":"text","marks":[{"type":"strong"}]},{"text":"Here you describe how you want the “From” output. The examples later this chapter, will describe exactly what to pick here in order to product the wanted output for Sana.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To: ","type":"text","marks":[{"type":"strong"}]},{"text":"This is the name of the output made. This name might be recognized by Sana (Sana, for example, knows what an Id and a Title is, but does not know what Brand is and hereby reckons that as a custom field).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Entity: ","type":"text","marks":[{"type":"strong"}]},{"text":"The","type":"text"},{"text":" ","type":"text","marks":[{"type":"strong"}]},{"text":"entity on which this mapping belongs (Category, Product or Variant for Sana).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Channel: ","type":"text","marks":[{"type":"strong"}]},{"text":"The channel on which this mapping belongs. Here the *-mapping is used meaning all channels","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Let us as an example read the 4","type":"text"},{"text":"th","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]},{"text":" mapping in Figure 13: The value of the feature named ","type":"text"},{"text":"GroupName","type":"text","marks":[{"type":"em"}]},{"text":" should go to a ","type":"text"},{"text":"Field","type":"text","marks":[{"type":"em"}]},{"text":" named ","type":"text"},{"text":"Title ","type":"text","marks":[{"type":"em"}]},{"text":"for entity ","type":"text"},{"text":"Product","type":"text","marks":[{"type":"em"}]},{"text":" for all channels. ","type":"text"}]},{"type":"paragraph","content":[{"text":"You can also see it as a mapping is answering 3 questions:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Where can I get the data","type":"text","marks":[{"type":"em"}]},{"text":"?","type":"text"},{"type":"hardBreak"},{"text":"Answer:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Feature GroupName","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"How should the data be output?","type":"text","marks":[{"type":"em"}]},{"type":"hardBreak"},{"text":"Answer:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"As a Field","type":"text","marks":[{"type":"em"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"How should it be named","type":"text","marks":[{"type":"em"}]},{"text":"?","type":"text"},{"type":"hardBreak"},{"text":"Answer:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Name it Title","type":"text","marks":[{"type":"em"}]}]}]}]},{"type":"paragraph","content":[{"text":"For those familiar with the ECommerce API will know that the ","type":"text"},{"text":"ECommerce","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Output Kind","type":"text","marks":[{"type":"strong"}]},{"text":", or simply Output Kind, tells the ECommerce API how some data should be ","type":"text"},{"text":"interpreted","type":"text","marks":[{"type":"em"}]},{"text":". Very often, this boils down to how some data should ","type":"text"},{"text":"output","type":"text","marks":[{"type":"em"}]},{"text":", but in a few cases, the feature simply holds some information that guides the ECommerce API without necessarily outputting them.","type":"text"}]},{"type":"paragraph","content":[{"text":"Back to the 6 mappings in Figure 13. ","type":"text"},{"text":"The first mapping","type":"text","marks":[{"type":"strong"}]},{"text":" is indeed a mapping that tells the ECommerce API something, without anything being output. This mapping tells the ECommerce API, that you will find Products in Perfion on the feature named ","type":"text"},{"text":"Product","type":"text","marks":[{"type":"em"}]},{"text":". This sounds abstract, but it makes good sense. Perfion can be set up in many ways and, as an example, hold many features that carries a configuration. In this first mapping we use the Output Kind ","type":"text"},{"text":"Context","type":"text","marks":[{"type":"em"}]},{"text":" and that a Context-mapping is used to tell the ECommerce API in which feature the entities (here products) can be found. That feature name is found in the left most column (the From-column), and here you indeed see ","type":"text"},{"text":"Product","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The second mapping","type":"text","marks":[{"type":"strong"}]},{"text":" tells the ECommerce API that the feature ","type":"text"},{"text":"Value ","type":"text","marks":[{"type":"em"}]},{"text":"holds the unique Id for all products. For a connector it is crucial to know which feature identifies a product uniquely. Those familiar with Perfion would know that ","type":"text"},{"text":"Value","type":"text","marks":[{"type":"em"}]},{"text":" refers to the base value of (here) a Product. Note further, that it is mapped to the “similar” field in Sana, namely the Id-field. Sana indeed uses “Id” as the unique identifier. So this mapping tells the connector which feature contains the unique id of the products. When Sana asks for products it will ask for products by their Id, so the connector now knows which products to fetch. As can be seen in Figure 15 the two products indeed holds a value that could resemble a unique id, namely ","type":"text"},{"text":"1923-16","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"1923-18","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Both the above mapping does not bring any data from Perfion to Sana, which that Sana did not already get from the ERP-system. They are both simply setting the scene. The final four mappings change that. They will all produce an output.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"third mapping","type":"text","marks":[{"type":"strong"}]},{"text":" tells that the value of the Image-feature should be mapped to Image in Sana, and that it should be output as an ","type":"text"},{"text":"Image(Url)","type":"text","marks":[{"type":"em"}]},{"text":". This means that the ECommerce API constructs an Image-element in the output holding (among other data) and outputs that to Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"fourth mapping","type":"text","marks":[{"type":"strong"}]},{"text":" maps from the ","type":"text"},{"text":"GroupName","type":"text","marks":[{"type":"em"}]},{"text":" feature to a feature Field named ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":" while the ","type":"text"},{"text":"fifth mapping","type":"text","marks":[{"type":"strong"}]},{"text":" maps the ","type":"text"},{"text":"Description","type":"text","marks":[{"type":"em"}]},{"text":"-feature to a Field named the same in Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"One thing worth noticing above all the mappings 2 – 5: They all map to something known to Sana. Sana knows what the ","type":"text"},{"text":"Id","type":"text","marks":[{"type":"em"}]},{"text":" of a product is, and what its ","type":"text"},{"text":"Image","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Description","type":"text","marks":[{"type":"em"}]},{"text":" is. When addressing such “known names” in Sana, Perfion will override the information coming from the ERP-system. Table 4 contains a table of all names that the Perfion Connector considers known.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"59beb76d-4a75-486c-a97e-491e33f35ab8"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#a6a6a6","rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"Id","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"Title","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"SortId","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[1168.0]},"content":[{"type":"paragraph","content":[{"text":"Visible","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Table 4: Field names reckoned as known to Sana by the connector.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"sixth mapping","type":"text","marks":[{"type":"strong"}]},{"text":" maps the feature ","type":"text"},{"text":"BrandName ","type":"text","marks":[{"type":"em"}]},{"text":"(the feature behind the Caption ","type":"text"},{"text":"Brand","type":"text","marks":[{"type":"em"}]},{"text":" shown in Figure 12) to a Field named ","type":"text"},{"text":"Brand","type":"text","marks":[{"type":"em"}]},{"text":". ","type":"text"},{"text":"Brand ","type":"text","marks":[{"type":"em"}]},{"text":"is not a known field name in Sana, so the Connector will not override data coming from the ERP-system but augment the product with a new field. This new Field is not named ","type":"text"},{"text":"Brand, ","type":"text","marks":[{"type":"em"}]},{"text":"as one might expect, but ","type":"text"},{"text":"Perfion__Brand ","type":"text","marks":[{"type":"em"}]},{"text":"(Note that there are two underbars between “Perfion” and the name typed in Perfion, here ","type":"text"},{"text":"Brand","type":"text","marks":[{"type":"em"}]},{"text":"). This prefixing is done in order for Sana to be able to distinguish fields coming from Perfion from other fields mainly to help the user of the Sana Admin interface to recognize Fields coming from Perfion.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Testing the result – For products","type":"text"}]},{"type":"paragraph","content":[{"text":"With the settings and mappings of languages and products in place, we can go to the Sana Admin interface and test the result of our effort.","type":"text"}]},{"type":"paragraph","content":[{"text":"Just before we do this, two things must be done prior to testing.","type":"text"}]},{"type":"paragraph","content":[{"text":"First of all we need a product in the ERP-system with an Id that matches one of the products we have in Perfion in Figure 12. This can either be done in the ERP-system by making a new product with an id matching a product in Perfion. Or maybe you have a product in the ERP-system, then just change the Id (the base value in our case) in Perfion.","type":"text"}]},{"type":"paragraph","content":[{"text":"For this manual Sana has provided a cloud based-ERP system, in which I have created a few products matching a few of the products in our “Coffee show” demo database. Matching ids of products is simple but crucial for the connector to work correctly.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":347,"id":"610a2666-1ae6-4ee2-a338-399f84367351","collection":"contentId-244338214","type":"file","height":518}},{"type":"caption","content":[{"text":"Figure 14: The matching of unique identifiers starting in ERP-system ending up on the Sana frontend","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The second thing we need to do before testing is that Sana needs to know what it can expect of Fields from Perfion on products. Sana gets that information through the connector by running the scheduled Task “Get information import”. Simply go to Tools -> Scheduled tasks and hit the Start-button for that task as shown in Figure 15:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":434,"id":"cc3c50ee-4623-4f34-8fa4-1fbe8e0ecd1d","collection":"contentId-244338214","type":"file","height":283}},{"type":"caption","content":[{"text":"Figure 15: The “Scheduled Tasks”-list as shown in Sana","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Finally, we can test the result of all our efforts. To do this, it requires that your Sana-installation has “Debug Erp-request”-enabled in its web.config. Check Sana documentation on how to do that. This is a highly recommended way of testing the results.","type":"text"}]},{"type":"paragraph","content":[{"text":"If enabled you can go to Tools -> ERP connection -> Debug ERP request. Here you select the “GetProducts”-request template and modify the following request parameters:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove ExtraFields-element (with sub-elements).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove MultiCurrency-element (just to avoid the many prices otherwise added in different currencies).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove the AccountId-element","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Filter by a single Id (We have for example 1923-16 as shown in Figure 8).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Change WebsiteId-element so that it holds the correct name for your store. In this case, the demo data is using a store named ","type":"text"},{"text":"AllisonNav","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Having done the above you can hit the “Send request” and get a result looking like this:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":50.0},"content":[{"type":"media","attrs":{"width":328,"id":"5cb1310a-921e-4954-abbf-49de80dd87cc","collection":"contentId-244338214","type":"file","height":384}},{"type":"caption","content":[{"text":"Figure 16: Debugging a Sana-request as shown in Perfion","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Let us take a look at the result shown here:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n 1\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"Note first the field named ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":". There are two such fields: ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Title_1031","type":"text","marks":[{"type":"em"}]},{"text":". Since installation of Sana used is set up to use US English (LCID 1033) as default language localizable fields output in this language will be output using simply the fieldname, i.e. ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":". All other languages (cultures) will be output with the fieldname post fixed by an underbar followed by the LCID of the language. Here we have ","type":"text"},{"text":"Title_1031","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Description_1031","type":"text","marks":[{"type":"em"}]},{"text":" for outputting Title and Description-fields in German.","type":"text"}]},{"type":"paragraph","content":[{"text":"Since ","type":"text"},{"text":"Id","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Description","type":"text","marks":[{"type":"em"}]},{"text":" are all known Sana fieldnames, they are just output (and maybe overriding other values coming from the ERP). However, ","type":"text"},{"text":"Brand","type":"text","marks":[{"type":"em"}]},{"text":" is not known, so this name is prefixed by ","type":"text"},{"text":"Perfion__","type":"text","marks":[{"type":"em"}]},{"text":" before being output.","type":"text"}]},{"type":"paragraph","content":[{"text":"Finally notice the absence of ","type":"text"},{"text":"Image","type":"text","marks":[{"type":"em"}]},{"text":". Images are output as part of the GetProductImages-request, and hereby not part of the GetProducts-result.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ECommerce Mappings – For Product Categories","type":"text"}]},{"type":"paragraph","content":[{"text":"Now with product-mappings in place, we are ready to turn our attention to Product Categories or just Categories.","type":"text"}]},{"type":"paragraph","content":[{"text":"In versions previous to 3.0.1, the Perfion Connector will never use the ERP-system for getting Product Categories, but always rely on getting them from Perfion. While this is usually the wanted way, since organizing data in some categorization in Perfion is often easier than doing it in an ERP-system.","type":"text"}]},{"type":"paragraph","content":[{"text":"From Perfion 3.0.1 you can choose between getting categories either from ERP-System or Perfion using the SanaCategoriesSource-setting.","type":"text"}]},{"type":"paragraph","content":[{"text":"This section will assume that you retrieve categories from Perfion and guide you through mapping any categorizing feature to Sana. In the examples in this section, we use a feature appropriately named ","type":"text"},{"text":"SanaWebsite","type":"text","marks":[{"type":"em"}]},{"text":". This feature is defined as a typical categorizing feature as shown in Figure 20.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":559,"id":"69e97a9f-187a-4ac6-be42-de5d7c13cb48","collection":"contentId-244338214","type":"file","height":738}},{"type":"caption","content":[{"text":"Figure 17: The definition of the SanaWebsite-feature which will be used for categorization in Sana","type":"text"}]}]},{"type":"paragraph","content":[{"text":"When created it can be given a configuration, but this is strictly not needed. In order to assign product to the various categories it must be added to a Section in the Section Designer in Perfion. When done you can start creating the wanted structure. Figure 20 below shows a sample structure entered in Perfion:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":989,"id":"143cc5d1-18d6-4ed5-935b-71123f35ea80","collection":"contentId-244338214","type":"file","height":589}},{"type":"caption","content":[{"text":"Figure 18: The categorizer structure entered in SanaWebsite-feature","type":"text"}]}]},{"type":"paragraph","content":[{"text":"This feature is to be used for Product Categories in Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"In Figure 18, you note a small hierarchy with ","type":"text"},{"text":"Coffee Shop","type":"text","marks":[{"type":"em"}]},{"text":" as the root node and that it has 4 sub-categories: ","type":"text"},{"text":"Brewing","type":"text","marks":[{"type":"em"}]},{"text":", ","type":"text"},{"text":"Keeping warm, Accessories","type":"text","marks":[{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Cups","type":"text","marks":[{"type":"em"}]},{"text":" . The ","type":"text"},{"text":"Brewing","type":"text","marks":[{"type":"em"}]},{"text":"-category is selected, and you can therefore see the two products assigned to that.","type":"text"}]},{"type":"paragraph","content":[{"text":"Having categorizing structure in place, we can turn to mappings of these to meet the requirements for Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"Figure 19 shows the necessary mappings:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":65.0},"content":[{"type":"media","attrs":{"width":454,"id":"9cb27c4a-d974-4042-b944-8e316ae41605","collection":"contentId-244338214","type":"file","height":96}},{"type":"caption","content":[{"text":"Figure 19: The mappings needed to import Product Categories from Perfion to Sana","type":"text"}]}]},{"type":"paragraph","content":[{"text":"First mapping","type":"text","marks":[{"type":"strong"}]},{"text":" is the Context-mapping simply tells the connector, that it is the feature ","type":"text"},{"text":"SanaWebsite","type":"text","marks":[{"type":"em"}]},{"text":" that holds the Product Categories (in ECommerce API they are called Categories).","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"second mapping","type":"text","marks":[{"type":"strong"}]},{"text":" requires a small bit of explanation. We did not create a configuration for SanaWebsite. If we had done that, we could have made some feature holding the unique id of each category and, of course, filled it out appropriately. Instead, we rely on the fact that Perfion numbers all items with a unique integer. To get to that id we do not simply write ","type":"text"},{"text":"id","type":"text","marks":[{"type":"em"}]},{"text":", since that would denote a feature named ","type":"text"},{"text":"id","type":"text","marks":[{"type":"em"}]},{"text":". Instead we write ","type":"text"},{"text":".id","type":"text","marks":[{"type":"em"}]},{"text":" (dot id) meaning the value of the attribute id. This is a so-called attribute mapping. Here it is enough to know that it simply supplies a unique identifier for the Context feature, here ","type":"text"},{"text":"SanaWebsite","type":"text","marks":[{"type":"em"}]},{"text":", and hereby can provide a unique ","type":"text"},{"text":"Id","type":"text","marks":[{"type":"em"}]},{"text":" for Sana. The second mapping is therefore is marked as a KeyField and mapped to the field named ","type":"text"},{"text":"Id","type":"text","marks":[{"type":"em"}]},{"text":" recognized by Sana as the unique id.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"third mapping","type":"text","marks":[{"type":"strong"}]},{"text":" is also an attribute mapping. The order-attribute contains the position of the item among its siblings. This means that if you order your categories (that is ","type":"text"},{"text":"SanaWebsite","type":"text","marks":[{"type":"em"}]},{"text":"-items) in Perfion, the ordering will be reflected in Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"fourth mapping","type":"text","marks":[{"type":"strong"}]},{"text":" takes the base value containing the name of each category and map it to the ","type":"text"},{"text":"Title","type":"text","marks":[{"type":"em"}]},{"text":"-field in Sana. Note that the ","type":"text"},{"text":"SanaWebsite","type":"text","marks":[{"type":"em"}]},{"text":"-feature was created as a localizable and hereby contains a name for each language. The connector automatically makes sure that all appropriate languages (as defined in settings) are sent to Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"The result of the Category-mappings can be checked in Sana by","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Testing the result – For Product Categories","type":"text"}]},{"type":"paragraph","content":[{"text":"With the mappings of categories in place, we can now go to the Sana Admin interface and test the result of our effort.","type":"text"}]},{"type":"paragraph","content":[{"text":"Using the Request XML below:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n GetProductCategories\n \n 1\n AllisonNav\n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"You should get the following result back containing the 4 categories in the 2-level hierarchy seen in Figure 22.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Using the Perfion API Tool to debug instead","type":"text"}]},{"type":"paragraph","content":[{"text":"The output from the ECommerce API is not matching exactly matching the Response XML needed by Sana. It has to be “slightly changed” by the connector, before being passed on to Sana.","type":"text"}]},{"type":"paragraph","content":[{"text":"As mentioned earlier, however, the ECommerce API is inspired by Sana, so its output can actually to some extend be used as-is for implementation/debugging purposes. This is not as good, as doing it directly from the Sana Admin interface, since the final modifications done by the connector are not carried out. But in case you for some reason does not (yet) have access to Sana Admin, going straight to the ECommerce API can be beneficial, since it can be done directly in the Perfion Client.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ECommerce API-manual can guide you to do that. Here in this manual we will just show you how the above query looks natively within the ECommerce API.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is the GetProducts-method that you would need to use in order to fetch a product by its KeyField:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"And the result you get from the ECommerce API looks like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n \n 1\n \n \n \n 1923-16\n Chambord Coffee maker\n Chambord kaffebereicher\n CHAMBORD is the true ...\n Der CHAMBORD Kaffeebereiter ...\n Bodum\n \n \n \n 1c07ad18-d775-475c-9694-be64e8415163\n 1923-16.jpg\n http://localhost:8100/Perfion/Image.aspx?id=1c07ad18-d775-475c-9694-be64e8415163&format=jpg&size=1024x1024\n \n \n \n \n \n \n","type":"text"}]},{"type":"paragraph","content":[{"text":"The resemblance to a Sana response is striking. The attentive reader will notice, however, the small changes done by the connector before leading this to Sana as a Sana response. Most notably, we have:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Elements are named and structured slightly different (i.e. element name used is ","type":"text"},{"text":"Field","type":"text","marks":[{"type":"em"}]},{"text":" as opposed to ","type":"text"},{"text":"field","type":"text","marks":[{"type":"em"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Culture is in ECommerce API is an attribute named ","type":"text"},{"text":"culture","type":"text","marks":[{"type":"em"}]},{"text":", not a postfix to the field name.","type":"text"},{"type":"hardBreak"},{"text":"The ECommerce API has no notion of a default language so all localizable data is output with a culture.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The prefixing of known Sana names with “Perfion__” is absent in the ECommerce API. You can see that the Field is named ","type":"text"},{"text":"Brand","type":"text","marks":[{"type":"em"}]},{"text":" and not ","type":"text"},{"text":"Perfion__Brand","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The removal of images. In ECommerce API all mappings are output on GetProducts. On the other hand, images are passed to Sana when Sana calls the GetProductImages-request, not when calling GetProducts.","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"Congratulations! Your first very small and simple configuration of the Perfion Connector has been completed.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Figure 20 shows a complete overview of how feature values are carried on using mappings until they end up on the product detail page in Sana front end:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":81.0},"content":[{"type":"media","attrs":{"width":468,"id":"837605dc-3c9b-4b81-b1a6-c421aa2692b7","collection":"contentId-244338214","type":"file","height":416}},{"type":"caption","content":[{"text":"Figure 20: All the way from the feature value to content on the product detail page","type":"text"}]}]}]},{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"baf1e93e-60ab-4355-8cae-1d513e642197"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"85245d56-49a8-4b7e-bfa4-33141eb5e1a4"}}]}]}],"version":1}