End user guide: Automatic Product import from Acme Warehouse for Magento Introduction Current end user guide is about the module for Magento, which adds the following functionality to Magento e- store: Imports products to Your Magento e- shop from http://www.acme.lt/index_en.html warehouse in form of the regular jobs or by user initiative. Updates prices and stock levels based on the information from the warehouse in form of the regular cron jobs or by user initiative. Gives Magento administrator the ability to automatically send product order details to the warehouse right after the client has completed the order and the order contains products from Acme warehouse. Allows Magento administrator to replicate Warehouse catalog structure with single mouseclick Allows Magento administrator to define which product classes to import or allow to import all product classes. (Available only with the Catogory mapper add-on) Allows Magento administrator to create custom category mapping in one single easy to use control if he/she is does not want to use replicated warehouse catalog structure. Allows Magento administrator to map local product attributes to remote product attributes with easy to use control. Supported local attribute types are text, textarea, select. If the desired value is missing, it is created automatically. (Available only with the Product mapper add-on) Can easily understand which products are removed from the warehouse and initiates callback onremoteproductdeleted, in wheremagento administrator can define what to do in that case. Can set up cron jobs for the processes like: Import new products, update product prices and stock levels, update product specifications and pictures. Call functions with a mouse click: Creating the attribute set, replicate warehouse catalog structure, delete all the imported products, etc and monitor the state of those processes when they are running. Monitor if there is any process running at the moment, measure the amount of memory the script consumes and information about last error or last activity. Running processes can also be halted. Magento administrator can define margin amount and margin type for each product individually. Negative margin can also be set. Can remove some of the products from the update process. Licencing This software is Licenced by Aktsiamaailm OÜ and contains one time online activation. This software is open source and contains licencing logic. You are not allowed to remove or alter any of the licencing logic. In fact altering the licence code may result in software crash and removes the right for
technical support. If you have found a bug, which conflicts with the licencing logic, you should report it to the developer. For the most part you should be able to easily alter the code for your needs. Licencing ties software by the hostname, Magento installation directory, special hash, signed date, expiration date. Altering any of those variables may result in software malfunction. Licence will be valid for 20 years and 1 year for the test server. Licence terms can be read here (Estonian): http://www.e-abi.ee/litsents You should licence your copy right away after installation (copying files to the server and navigating to the setup panel), prepare yourself with the Order number and order email for this process. After installation you should log in to Magento admin panel, navigate to System -> Configuration -> E- Abi moodulid -> Acme XML import From this view there should be notification about the licence, click on the link to start activation process. You will be redirected to http://www.e-abi.ee/ page asking for details such as Order number and email used in the order. If you have licenced your copy before then you will be asked for the reason of re-licencing. Type the reason eq. new domain or new testserver (it is allowed to use this software on multiple domains as long as you are the main beneficiary for the domain). Failing to provide accurate reason may result in licence being revoked later. If all is successful, you will be asked to insert licence details to your server do so and you will be greeted with the confirmation message that licence was successful. Close the window and reload your module configuration page. It should not ask any more you to licence. You can review your licence status from here: http://www.yourpage.com/<magento>/acme/index/state or http://www.yourpage.com/<magento>/<store-code>/acme/index/state This page displays unique hash, which is used to idendify the licence, this page should be available at all times, when this module is installed. Requirements for using this module This module requires contractual relationships with Acme warehouse, if you do not have them, then only test environment can be used and automatic product ordering function is not usable. In addition to the contract there are few more requirements: Installed and configured Magento instance 1.3 or greater. Magento admistrator usename and password
FTP login details PHP5 or greater and SOAP extension must be enabled Ability to raise memory limit that script is allowed to consume. Perfomance tests indicate peak memory usage of 180-200MB with basket size of 5500 products. Cron has to be properly set up, otherwise automatic processes will not run. Systematic changes to Magento when installing this module This module creates new Product attribute set Acme_Acc, which is based on the default attribute set and inserts the following attributes to General tab: eabi_mpn eabi_manufacturer eabi_warranty eabi_dateexpected eabi_disableremoteupdate eabi_margin eabi_margintype eabi_warehouse All the imported products will be assigned to the type of Acme_Acc attribute set. Optionally this module creates categories, which reflects the category map of the remote warehouse and inserts the following attribute to each imported category: remoteid This module uses namespace Eabi_Acme Take caution, if your system is using any of those properties noted here and you have not installed this module before. Contact developer if you have any doubts. This module works best with default Magento installation where there are not custom attributes defined yet and no products imported. Installation Prepare yourself with the following information: FTP login details Magento admin login details Unzip your freshly purchased module (if you have not done so) and open the install directory. You notice that contents of the directory resemble the Magento directory structure and all of them should be installed right to the Magento installation directory. Do not replace any file, and when there is directory conflict, then use merge command not overwrite command. Successful install results in no files being overwritten.
After copying files log to Magento admin and clear the Magento cache Now navigate to Admin -> System -> Configuration -> E-Abi moodulid -> Acme XML import Licence your copy and then you may start setting it up. Setting it up Log in to Magento administration and navigate: System - > Configuration- > E- abi Moodulid - > Acme Import Now you should be presented with the view, which is all you need to set up product import from the warehouse. Each field is being explained in detail below: Current state (Hetkestaatus) Displays information about the currently running process, which are initiated by this module. To display the view, click on the Kuva hetkestaatus row and additional information will be displayed Operatin name Name of the currently running process or name of the process that was run last time. Operation status State of the recent process, possible values are: o Running Process is currently running o Finished Process has finished its work o Failed Process has failed to run, if possible last error will be shown. Completion Displays number of units the process has done and the amount of total units. Last activity Datetime when process last time responded. If the process is running and has not been responding for reasonable amount of time, it may be assumed that the process has been left stuck Operatin started Datetime when was the last process started. Can be used to measure how long single process runs Memory used Amount of memory which the process was using when it last reponded.
Last error If last process produced an error, then this error will be displayed here. Halt running process Stop the process that is currently running. If there is no running process, then this button will not be displayed. Also take a note that process can only be stopped, when it responds. Enabled (Lubatud) If module is enabled all the procedures should run without problems, if this module is disabled, then running all the processes will end up with an error indicating to enable the module. Create actions (Käivita importimise operatsioone) Create Attribute set Creates attribute set with name of Acme_Acc based on the Default attribute set. Each imported product will be treated as type of Acme_Acc and this process needs to be run once before the very initial product import. This function also adds the following attributes to the Acme_Acc attribute set (Initially newly created attributes are inivisible to the frontend and Magento administrator has to make them manually visible if he/she wishes so): o Eabi_mpn Manufacturer product number o Eabi_manufacturer Manufacturer name, select attribute, can be made filterable. o Eabi_warranty Warranty (Months). o Date Expected Expected date when the product arrives to warehouse. o Disable remote update If this field is filled, this product will not be updated during running update processes o In Warehouse Contains information about in which warehouse this product is located at (This field is intended for the system use only and front end users should not see this field) o Margin amount Amount of margin which will be added to the warehouse price can be expressed in percent or in absolute value, refer to the Margin type also. o Margin type Choices are percent or currency, First case corresponding percentage will be added to the warehouse price in another case corresponding amount will be added to the warehouse price. Create categories Creates copy of the remote warehouse category tree to your Magento e- shop. Make sure that you have set up parent category under which the result will be created. If you do have categories previously set up, then you do not need to do this process. Also you can call this process over and over, and on each call new categories will be added, if any. Initial import products This process sends request to the warehouse and imports all the products that are in the warehouse and are not present in your e- shop. It also takes into
account if you have somehow limited categories that you do not wish to import. This process can be run as many times as you like. Update product prices Updates prices and stock levels for all of the imported products. This process can be run repeatedly. Update products Updates product specifications and imports new pictures for them if any. This process can be run repeatedly. Import related products Imports all the product upsell relations, which can be fetched from the remote server. If the product already contains upsell relations, then this product will not be updated. Remove actions (Käivita kustutamise operatsioone) Contains actions necessary to remove traces of the import. If you wish to run these actions, you should consider the fact that you cannot remove categories or attributes if any products are using them. So consider removing products first and categories next. Delete products Deletes all the products that have been imported by this module. Delete categories Deletes all the categories that have been created by this module Delete attribute set and attributes Deletes the attribute set of Acme_Acc and attributes: eabi_mpn, eabi_manufacturer, eabi_dateexpected, eabi_warranty, eabi_disableremoteupdate, eabi_margin, eabi_margintype. Removal will succeed only if there are no products left using them. Licence key If you have established contractual relationships with the warehouse you will be supplied with the licence key, this key needs to be pasted here. If You do not have contractual relationships you can settle with the test licence key: 498ec72c- e8e7-48f2- b300- d95666aeb141 Language (Keel) All the product specifications and descriptions will be imported in the language specified here. Currently supported are English and Lithuanian language. On change of the language you should run updateproductspecifications process to reflect the changes in your store. Currency (Valuuta) Currency in which the products will be be imported. If your store base currency is not in the supported list (currently supported are EUR and LTL) then it will be converted to your store s base currencly. Make sure that currency rate has been set up properly.
Tax Class (Maksuklass) Apply this tax class to every imported product. Margin amount (Tootemarginaal) Default amount of margin which will be added to the warehouse price can be expressed in percent or in absolute value, refer to the Margin type also. Negative value is also accepted Margin Type (Marginaali tüüp) Margin type Choices are percent or currency, First case corresponding percentage will be added to the warehouse price in another case corresponding amount will be added to the warehouse price Product enabled by default (Uued tooted vaikimisi lubatud?) Specifies whether newly imported products should be enabled or disabled Allow Other warehouses set this product to stock (Luba teistel ladudel käesolevat toodet lattu panna) If enabled and same product is in another warehouse then this product will be set to stock, if it is in stock at another warehouse. Also it should be noted that price of the product will not be changed. Missed Category (Möödapandud kategooria) If system is unable to properly assing category for the imported product, then product will be assigned to category defined in this fields. Parent Category (Ülem Kategooria) If Magento e- shop administrator wishes to replicate remote warehouse category structure, then it should assign the parent category under which the whole category tree will be replicated. Import all the products from the warehouse If enabled, all the products will be imported to Magento e- shop, if disabled, then please use the form below to specify which product classes to import. Choose product classes to import (Vali tooteklassid importimiseks) Attention Using this control is very javascript intensive and may slow down the browser. Please do save your work in other tabs and use high quality browsers such as Firefox or Safari. I know this is pain, but this is caused because of the sheer amount of information that this control handles and I hope that once slow loading can be forgiven in comparison to setting the same thing up with high multiple of page reloading. Click on the row Vali kategooriad importimiseks and you will be presented with the following display:
Mark the checkboxes on all categories that you wish to import. Also take a note, that if parent category is checked, all the child categories will be imported with the parent category so checking the child categories will be disabled. Yellow color indicates that you have made a selection in the subcategories. Use category layout from the warehouse (Kasuta Lao kategooriastruktuuri) If enabled, then system assumes that you have replicated the category structure from the warehouse and products will be mapped accordingly. However there still are cases when category cannot be assigned and thus will be set to missed category If this setting is disabled, then please map the categories using the control below. Map product classes to Categories (Seo lao kategooriad e-poe kategooriatega) Attention Using this control is very javascript intensive and may slow down the browser. Please do save your work in other tabs and use high quality browsers such as Firefox or Safari. I know this is pain, but this is caused because of the sheer amount of information that this control handles and I hope that once slow loading can be forgiven in comparison to setting the same thing up with high multiple of page reloading. Click on the row Ava kategooriate sidumise vorm and you will be presented with the following display:
Pay attention to three different sections: 1. Category tree from remote warehouse 2. Category tree from Magento e-shop 3. Information display Also we can only select one remote category at the time, which we call active remote category. If there is nothing selected, then there is no active remote category. Setting up the category mapping goes as the following: 1. We pick active remote category and make sure that it is checked. 2. Now we notice that some of the local categories turned red those are the categories, which name matches name of the currently selected category. You do not have to check these categories, but it is done to help you with finding proper matching category. 3. We choose one to many local categories that match the remote active category by checking them with checkbox and as we do that we see that green check icon will appear next to the active remote category. This icon indicates, that local categories have been mapped to that remote category. 4. To map next remote category, we mark the next remote category as active by checking it with the checkbox and as previously we mark the corresponding local categories with the checkbox. 5. All the child categories of remote category will also be mapped to the the same categories as was selected in the parent remote category. Map child remote child categories only if they should be mapped differently from the parent categories. 6. All the remote categories that have been mapped we can see the mapped local categories by hovering mouse over the remote category. If we want to change the mapped categories, then we mark the remote category active by checking the checkbox and change the selected categories. 7. If we are done mapping, then we save the settings and verify if they got saved correctly. Enable attribute mapping (Luba atribuutide sobitamine) If enabled then you can use the control below to map remote attributes to local attributes.
Map remote attributes to local attributes (Hulgilao atribuutide sobitamine Magento e-poe atribuutidega) Attention Using this control is very javascript intensive and may slow down the browser. Please do save your work in other tabs and use high quality browsers such as Firefox or Safari. I know this is pain, but this is caused because of the sheer amount of information that this control handles and I hope that once slow loading can be forgiven in comparison to setting the same thing up with high multiple of page reloading. Click on the row Ava atribuutide sidumise vorm and you will be presented with the following display: Pay attention to three different sections: 1. Attributes from remote warehouse 2. Attributes from Magento e-shop which belong to Acme_Acc attribute set and have type of select,text,textarea 3. Information display Also we can only select one remote attribute at the time, which we call active remote attribute. If there is nothing selected, then there is no active remote attribute. Setting up the attribute mapping goes as the following: 1. We pick active remote attribute and make sure that it is checked. 2. Now we notice that some of the local attributes turned red those are the local attributes, which name matches name of the currently selected active remote attribute. You do not have to check these attributes, but it is done to help you with finding proper matching attribute. 3. We choose one to many local attributes that match the remote active attribute by checking them with checkbox and as we do that we see that green check icon will appear next to the active remote attribute. This icon indicates, that local attribute(s) have been mapped to that remote attribute. 4. To map next remote attribute, we mark the next remote attribute as active by checking it with the checkbox and as previously we mark the corresponding local attribute(s) with the checkbox.
5. All the remote attributes that have been mapped we can see the mapped local attributes by hovering mouse over the remote attribute. If we want to change the mapped attributes, then we mark the remote attribute active by checking the checkbox and change the selected attributes. 6. If we are done mapping, then we save the settings and verify if they got saved correctly. Run product import from and repeat every (Käivita uute toodete import alates kuupäevast ja korda iga x aja tagant) Set system to run initial product import process at regular interval starting from the specified date and time. It is advised to run this process not more often than once a day. Also this function requires that cron has been configured. Update product prices from and repeat every (Uuenda toodete hindu ning laoseisu alates x kuupäevast ja korda iga y aja tagant) Set system to run product price and stock level updates at regular intervals starting from the specified date and time. It is advised not to run this process not more often than once in an hour. Also this function requires that cron has been configured. Update product specifications from and repeat every (uuenda tootekirjeldused ning pildid alates kuupäevast x ning tee seda edaspidi y aja tagant) Set system to run process that updates product specifications and imports new pictures at regular intervals starting from the specified date and time. It is advised not to run this function more often than once a week. Also this function requires that cron has been configured. Send order details to warehouse (Saada tellimuse andmed hulgilattu) If this feature is enabled, then each time customer completes the order and order contains products imported from the warehouse, ordered product details are sent to the remote server. Method that is being called is OrderProducts. This function does not work with the test licence key, resulting in an error that user has no permissions. This function requires some of the fields to be set below such as Preferred delivery type. Success of failure of the function is put to the order comments log. Preferred delivery type (Eelistatud kohaletoimetamise viis hulgilaost) In here are displayed list of preferred delivery types, which are based on you contractual relationships with the warehouse. This setting is not required if you do not wish to send order details to the warehouse automatically. Ordering Branch Address Id (Poe halduri aadress, kuskohast tellimus teele saadeti) This field is to indicate which shop created the order, for example if you have many Magento stores. This field is not mandatory. Customer Address Id (Kliendi aadress) If you leave this field empty, customer address will be created from the details which were entered into the order. Otherwise each order will get the address marked here.
Note (Tellimuse kommentaarid kliendi poolt) Since Magento has no order comment capability, then this field only sends out information that is written here. Delivery Note (Kommentaarid kojutoimetajale) Since Magento has no order comment capability, then this field only sends out information that is written here. Tellija kontaktandmed (Eesnimi, Perenimi, E-post, Telefon) If those fields are left empty, they will be filled with details from the order when automatically sending order details after the order completion. Otherwise order contact details will be set by the fields marked in here. Enable logging (Logimise lubamine) This setting is not dependent of the Magento s own loggin settings and it s task is to make easier to track errors with this module. When first time setting up this module, it is advised to turn on logging, this way developer can help you with your problems more operative way. Log files are created into the /var/log folder and have a pattern of eabi_acme_dd.mm.yy.log Performance This system has been tested with Magento 1.3 and 1.5 Used computer has 4GB Ram and Core2Duo 2,66Ghz processor. Number of imported products is 5500 and available internet bandwith was 30Mbit /sec Magento 1.3 Initial product import: 4,5hours Update of prices and stock statuses: 2 minutes Update of product specs and images: 2 hours Removal of all products: 1 hour Magento 1.5 Initial product import: 2 hours Update of prices and stock statuses: 5 minutes Update of product specs and images: 1 hour Removal of all products: 1 hour As you can see the computer used to test is rather old, so on the real server actual results should be faster.
Problems In case you run into trouble If you have a problem that requires technical support, then please do enable logging and send the log file with the most accurate description as you can possibly do. Being detailed means the faster the developer is able to solve the problem. You can get the technical support by email info@e-abi.ee or by using the contact form on the http://www.e-abi.ee/ webpage. Memory and time limits. Open up Eabi_Acme_Work_Main class constructor and place set_time_limit() and ini_set( memory_limit ) definitions in there. Do that only when you feel that default values are not sufficient. Running process does not seem to respong, it s state is running and last activity was more than half an hour ago. Restart your webserver and remove the file: /var/eabi_acme_status.txt Try to re-run the process. If process keeps hanging, contact the developer for the solution. Links This module complies to the specs listed here: http://www.scribd.com/doc/15667059/acme-api-specification-enus#archive Or the pdf version: http://s4.acme.eu/shop/glo/documents/en-us/acme_api_specification.pdf