Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
moneyworks:magento_integration [2016/10/06 14:01] – Adrian Boonemoneyworks:magento_integration [2024/03/20 15:20] (current) – Fix broken link for component and typo Adrian Boone
Line 13: Line 13:
 =====Introduction===== =====Introduction=====
  
-This is a standalone application (Windows or Mac) using our [[:4d_moneyworks_component|Moneyworks component]] which is designed to periodically (or manually) connect to Magento and import transactions into Moneyworks. Transctions may be imported as sales orders, sales invoices or receipts, depending on the customisation code entered and/or the import map used.+This is a standalone application (Windows or Mac) using our [[:moneyworks:4d_moneyworks_component|Moneyworks component]] which is designed to periodically (or manually) connect to Magento and import transactions into Moneyworks. Transactions may be imported as sales orders, sales invoices or receipts, depending on the customisation code entered and/or the import map used.
  
 We call this process 'syncing', and it is controlled by the //Sync// menu items: We call this process 'syncing', and it is controlled by the //Sync// menu items:
Line 49: Line 49:
 {{ :moneyworks:connector_MW_connection_REST.png |}} {{ :moneyworks:connector_MW_connection_REST.png |}}
  
-By default, there is a single connection to the Magento database, but for some customisations of the Connector it is possible to have multiple Magento connections e.g. you may want to apply different rules and settings for different Magento stores and/or sync them to different Moneyworks data files. If this is the case, you'll be able to switch connection settings using the drop-down list at the top right. Please contact us for more details if you're interested.+By default, there is a single connection to the Magento database, but it is now possible for a single instance of the Connector to have multiple connections e.g. you may want to apply different rules and settings for different Magento stores and/or sync them to different Moneyworks data files. Apart from the synchronisation interval, all other settings can be different for each connection: 
 +  * Switch connection settings using the drop-down list at the top right. 
 +  * Add a new one (which will duplicate the existing connection settings) using the //+// button to the left of the drop-down list 
 +  * Remove the last one using the //-// button to the right of the drop-down list - obviously, you can't delete Connection1!
  
 ====Moneyworks test==== ====Moneyworks test====
Line 73: Line 76:
 Click on the //Test// button to verify the connection. Clicking on //OK// will save the current connection settings, and //Cancel// will discard any changes made. Click on the //Test// button to verify the connection. Clicking on //OK// will save the current connection settings, and //Cancel// will discard any changes made.
  
-If your customisation allows multiple connections, you'll be able to select which stores are synced for each connection. Clicking the //Reload// button will reload the list of stores from Magento.+If you have multiple connections, you'll be able to select which stores are synced for each connection. Clicking the //Reload// button will reload the list of stores from Magento.
  
 ====Moneyworks settings==== ====Moneyworks settings====
Line 84: Line 87:
   * //Base currency code// should correspond to the base currency in the Moneyworks data file.   * //Base currency code// should correspond to the base currency in the Moneyworks data file.
   * The default and shipping tax codes are applied to orders which have a non-zero tax amount in Magento, otherwise the tax code is set to blank.   * The default and shipping tax codes are applied to orders which have a non-zero tax amount in Magento, otherwise the tax code is set to blank.
-  * If //Use Moneyworks address for business customers// is checked, then the mailing and delivery addresses are not passed across from Magento for customers which have a company name.+  * //Default customer code// specifies which customer code in Moneyworks should be used for generic/casual orders which don't have their own customer code in Magento. Obviously, this customer code should already exist in Moneyworks. 
 +  * If //Use Moneyworks address for existing customers// is checked, then the mailing address is not passed across from Magento for customers which have their own customer code. If the customer is defined as a company in Magento, then the delivery address is not passed across either.
   * If required, you can define a mask for the order/invoice sequence numbers e.g. "W00000000" means that transactions will be assigned a sequence number of "W00000001" and so on, depending on the numeric value of the Magento ID.   * If required, you can define a mask for the order/invoice sequence numbers e.g. "W00000000" means that transactions will be assigned a sequence number of "W00000001" and so on, depending on the numeric value of the Magento ID.
     * If left blank, Moneyworks will use the ID assigned by Magento.     * If left blank, Moneyworks will use the ID assigned by Magento.
     * Depending on the customisation code entered, the same facility is available for assigning new customer codes.      * Depending on the customisation code entered, the same facility is available for assigning new customer codes. 
     * Note that there is a limit of 11 characters in Moneyworks for transaction and customer codes, so this determines the maximum length of the mask.     * Note that there is a limit of 11 characters in Moneyworks for transaction and customer codes, so this determines the maximum length of the mask.
-    * Note that the numeric part of the Magento ID must not be longer than the number of trailing zeroes in the mask, otherwise it won't fit into the space available. The Connector will attempt to append extra trailing zeroes up to the maximum length of the mask - if that fails, then it reverts back to the original Magento ID.+    * Note that the numeric part of the Magento ID must not be longer than the number of trailing zeroes in the mask, otherwise it won't fit into the space available. If it doesn't fit, the Connector will attempt to append extra trailing zeroes up to the maximum length of the mask - if that fails, then it reverts back to the original Magento ID.
   * If set, the //Shipping code// is applied to all orders which have a non-zero shipping amount in Magento. This will normally be shown as an extra line in the invoice.   * If set, the //Shipping code// is applied to all orders which have a non-zero shipping amount in Magento. This will normally be shown as an extra line in the invoice.
  
-Note that most of these settings can be overridden by using a customised Moneyworks import map e.g. it may be necessary to have different tax codes for different transaction currencies, different types of product or different shipping destinations. In this case, the tax codes should be left blank here, and the connector will use the tax amounts as entered in Magento to work out which tax code to apply on a per-line basis. +Note that most of these settings can be overridden by using a customised Moneyworks import map e.g. it may be necessary to have different tax codes for different transaction currencies, different types of product or different shipping destinations. In this case, the tax codes should be left blank here, and the Connector will use the tax amounts as entered in Magento to work out which tax code to apply on a per-line basis. 
  
 ====Other settings==== ====Other settings====
Line 101: Line 105:
  
   * The Magento and Moneyworks sync timestamp fields control which records are imported into Moneyworks (and can be manually edited if needed e.g. to ignore failed records before a certain date):    * The Magento and Moneyworks sync timestamp fields control which records are imported into Moneyworks (and can be manually edited if needed e.g. to ignore failed records before a certain date): 
-    * Both refer to the local time on the Magento and Moneyworks server respectively (they can be in different time zones).+    * Both refer to the local time on the Magento and Moneyworks server respectively (they can be in different time zones). By default, Magento runs on the UTC time zone.
     * When a sync process has completed without errors, both timestamps are updated so that the records are not re-imported the next time (records imported into Moneyworks store the corresponding Magento timestamp in one of the user/custom fields).     * When a sync process has completed without errors, both timestamps are updated so that the records are not re-imported the next time (records imported into Moneyworks store the corresponding Magento timestamp in one of the user/custom fields).
     * If there is an error, then the sync timestamps are not updated, and the next sync will retry to import the failed record(s), and skip any which have previously been imported successfully.     * If there is an error, then the sync timestamps are not updated, and the next sync will retry to import the failed record(s), and skip any which have previously been imported successfully.
-  * If the //Sync interval// is set to any value other than zero, the connector will automatically attempt to perform a sync every X minutes. In this case, error messages are redirected to the log file (in the //Logs// folder) instead of popping up on the screen.+  * If the //Sync interval// is set to any value other than zero, the Connector will automatically attempt to perform a sync every X minutes. In this case, error messages are redirected to the log file (in the //Logs// folder) instead of popping up on the screen.
   * If //Generate CSV import files// is checked, the connector won't delete the temporary CSV import files that it generates (in the //Database/Resources/Moneyworks_import// folder). These can be useful to diagnose problems as you can manually import them into Moneyworks (using the corresponding import maps in the //Resources// folder).   * If //Generate CSV import files// is checked, the connector won't delete the temporary CSV import files that it generates (in the //Database/Resources/Moneyworks_import// folder). These can be useful to diagnose problems as you can manually import them into Moneyworks (using the corresponding import maps in the //Resources// folder).
   * In some circumstances, it is possible for the same record to have been modified both on Magento and in Moneyworks since the last time it was synced. You can choose to automatically use the Magento changes or the Moneyworks changes, or to be prompted each time there is a conflict.    * In some circumstances, it is possible for the same record to have been modified both on Magento and in Moneyworks since the last time it was synced. You can choose to automatically use the Magento changes or the Moneyworks changes, or to be prompted each time there is a conflict. 
 +  * If //Don't update existing Moneyworks records// is ticked, then an existing record will not be updated in Moneyworks even if it has been updated on Magento, regardless of the choice above, but a warning message will be generated in the log file.
 +  * If an email address has been entered in //Email address for notifications//, an automatic email containing the contents of the log file will be sent if there are any errors or warnings. 
 +    * If no email address has been entered, or the //Don't notify Sustainable Solutions// box has not been ticked, and there are errors, Sustainable Solutions will also get a copy of the email. 
 +    * Note that there is a throttle in place to prevent another error email being sent less than an hour since the previous one unless it also contains a warning.
  
 ===== Initial setup of Moneyworks datafile ===== ===== Initial setup of Moneyworks datafile =====
Line 116: Line 124:
   * Make sure that the base currency in Moneyworks has been set correctly.   * Make sure that the base currency in Moneyworks has been set correctly.
   * Make sure that the tax codes in Moneyworks have been setup correctly, with the same rates as in Magento.   * Make sure that the tax codes in Moneyworks have been setup correctly, with the same rates as in Magento.
 +
 +===== Upgrading the Connector =====
 +
 +  - Make sure that the Connector is not currently syncing (or about to sync) with Magento. One way to check this is to look at the timestamp of the latest log file (in the //Logs// folder) and compare that with the next scheduled time.
 +  - Exit the Connector
 +  - Make a backup copy of the //Database// folder (unless it is a major upgrade, in which case backup the entire Connector folder)
 +  - Copy over the updated application files as directed (usually only //MoneyworksConnector.4DC// and //MoneyworksConnector.4DIndy// to the //Database// folder)
 +  - If an import map has been updated, then copy it to the //Database/Resources// folder 
 +  - Restart the Connector - if prompted for a data file, browse to the *.4DD Connector data file (usually //MoneyworksConnector.4DD// in the //Database// folder)
 +  - Check the Connector settings and set appropriate values for any which have been newly added since the previous version
 +
 +It is possible to run multiple Connector instances on the same machine as long as:
 +  * They are installed in different folders
 +  * They connect to different Moneyworks data files
 +  * They don't try to sync at the same time - either set their scheduling to be different, use a REST connection for at least one of them, or install multiple instances of the Moneyworks client
  
 ===== Common errors ===== ===== Common errors =====
Line 123: Line 146:
   * Mismatch between the item codes in Moneyworks and those in Magento   * Mismatch between the item codes in Moneyworks and those in Magento
  
-When an import fails, then the next sync will restart from the same point as the previous one, so any records deleted in Moneyworks may magically be resurrected! If the import error cannot be fixed, then it can be ignored by manually setting the timestamps on the //Other Settings// tab to a time after the timestamp of the offending record.+When an import fails, then the next sync will restart from the same point as the previous one, so any records deleted in Moneyworks may magically be resurrected! 
 +  * This will likely generate informational messages in the log file for any records which were successfuly imported the last time. 
 +  * Regardless of the sync interval setting on the //Other Settings// tab, there will not be more than one error email per hour, unless the log file also contains a warning. 
 +  * If the import error cannot be fixed, then it can be ignored by manually setting the Magento timestamp on the //Other Settings// tab to a time after the timestamp of the offending record.
  
 ==== Troubleshooting ==== ==== Troubleshooting ====
  
-  - Check log file created for each sync in the //Database/Logs// folder. +  - Check the log file created for each sync in the //Database/Logs// folder. Error messages, which prevent the timestamps from being updated, will be prefixed by "Error:", and warning messages will be prefixed by "Warning:". Error and/or warning messages will generate an email according to the notification settings on the //Other Settings// tab. 
-  - Switch on //Generate CSV import files// on the //Other Settings// tab - this creates CSV files in the //Database/Resources/Moneyworks_import// folder, which can then be manually imported into Moneyworks (using corresponding import map in the //Database/Resources// folder). +  - Switch on //Generate CSV import files// on the //Other Settings// tab. This creates CSV files in the //Database/Resources/Moneyworks_import// folder, which can then be manually imported into Moneyworks using corresponding import map in the //Database/Resources// folder. 
-  - If connecting to Magento, enable XML debugging (enter "debug_xml_on" as a customisation code, and "debug_xml_off" to switch it back off again) - creates XML files for each Magento API call in the //Database/Resources/Moneyworks_import// folder.+  - Enable XML debugging (enter "debug_xml_on" as a customisation code, and "debug_xml_off" to switch it back off again). This creates XML files for each Magento API call in the //Database/Resources/Moneyworks_import// folder.  
 +    - If the Connector is configured to use a REST connection, enabling XML debugging will also create XML import files in the //Components/Sussol_Moneyworks.4dbase/Resources/Moneyworks_import// folder. 
 +    - These XML files can then be manually imported into Moneyworks, either directly in Moneyworks or by making use of the //Execute// button on the //Moneyworks test// tab.
  
 ===== Appendix: Magento API fields used by Connector ===== ===== Appendix: Magento API fields used by Connector =====
Back to top