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 [2015/07/22 13:24] – 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. +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:
  
 +{{ :moneyworks:connector_menus.jpg?600 |}}
  
- +There are also some customised versions of the Connector which connect to MySQL databases, either directly or via an API. It can also be customised to support other ecommerce platforms e.g. Prestashop. Please contact us for more details if you're interested.
- +
- +
-{{ :moneyworks:connector_menus.jpg?600 |}}+
  
 =====Entering the customisation code===== =====Entering the customisation code=====
Line 27: Line 25:
 Available from the //Sync -> Customisation code// menu item. This code determines which options are available and must be entered first to enable the other menu items.  Available from the //Sync -> Customisation code// menu item. This code determines which options are available and must be entered first to enable the other menu items. 
  
-By default, the connector works on the basis that all customers and products have the same codes in Magento and in Moneyworks. However, it is also possible to allow customers to be automatically created in Moneyworks if they don't already exist. By default, the connector uses both name and code to determine if there's a match for either.+By default, the Connector works on the basis that all customers and products have the same codes in Magento and in Moneyworks. However, it is also possible to allow customers to be automatically created in Moneyworks if they don't already exist. By default, the Connector uses both name and code to determine if there's a match for either.
  
 =====Setting up the sync parameters===== =====Setting up the sync parameters=====
  
-Available from the //Sync -> Setup// menu item. This consists of four tabs with settings for the Moneyworks connection and Magento connection parameters, and also some Moneyworks-specific options and advanced options to control the sync process.+Available from the //Sync -> Setup// menu item. This consists of five tabs with settings for the Moneyworks connection and Magento connection parameters, and also some Moneyworks-specific options and advanced options to control the sync process.
  
 ====Moneyworks connection==== ====Moneyworks connection====
  
-This tab controls how the Moneyworks Connector connects to Moneyworks:+This tab controls how the Connector connects to Moneyworks:
  
-{{ :moneyworks:connector_setup_moneyworks_connection.jpg |}}+{{ :moneyworks:connector_MW_connection.png |}}
  
 +It allows you to enter the parameters for the Moneyworks connection:
  
-The left hand side of the tab allows you to enter the parameters for the Moneyworks connection: +  * The connection type can be Local file, Gold client, Datacentre client, or Datacentre REST client (e.g. Moneyworks NOW).
- +
-  * The connection type can be Local file, Gold client, or Datacentre client.+
   * The datafile location or filename must be entered (full path must be entered if a local file).   * The datafile location or filename must be entered (full path must be entered if a local file).
-  * The location of the Moneyworks executable must be entered.+  * The location of the Moneyworks executable must be entered, unless the connection is via REST.
   * Enter the document user name and password (even if blank) in all cases.   * Enter the document user name and password (even if blank) in all cases.
   * The Gold client license key is only needed if connecting to a Gold server.   * The Gold client license key is only needed if connecting to a Gold server.
   * The server IP address and port number are not needed for connecting to a local file.   * The server IP address and port number are not needed for connecting to a local file.
-  * The DC user name and password should be entered (even if blank) if connecting to a Datacentre server, and the operating system of the Datacentre server must also be selected in this case.+  * The DC user name and password should be entered (even if blank) if connecting to a Datacentre or Datacentre REST server. If it's a Datacentre REST server connection, you can specify if the connection is secure or not; if it's a regular Datacentre server connection, the operating system of the Datacentre server must be selected.
  
-The right hand side of the tab allows you to send commands to Moneyworks (see the Moneyworks manual for details), and you can use the examples in the //Input// drop-down menu to check that the connection is setup correctly e.g. selecting //evaluate expr="documentpath"// and then clicking on the //Execute// button should return the Moneyworks document name/path in the //Output// box (and nothing in the //Errors// box). Clicking on //OK// will save the current connection settings, and //Cancel// will discard any changes made.+{{ :moneyworks:connector_MW_connection_REST.png |}} 
 + 
 +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==== 
 + 
 +The second tab allows you to send commands to Moneyworks (see the [[http://cognito.co.nz/developer/cli-manual|Moneyworks CLI manual]] for details), and you can use the examples in the //Input// drop-down menu to check that the connection is setup correctly e.g. selecting //evaluate expr="documentpath"// and then clicking on the //Execute// button should return the Moneyworks document name/path in the //Output// box (and nothing in the //Errors// box). Clicking on //OK// will save the current connection settings, and //Cancel// will discard any changes made. Note that you should avoid using normal single quotes here as these are used internally to pass the commands to Moneyworks. 
 + 
 +{{ :moneyworks:connector_MW_test_CLI.png |}} 
 + 
 +For REST connections, the commands need to be formatted appropriately using the correct URL structure and using standard HTTP escape sequences - see the [[http://cognito.co.nz/developer/moneyworks-datacentre-rest-api/|Moneyworks REST documentation]] for details. 
 + 
 +{{ :moneyworks:connector_MW_test_REST.png |}}
  
 ====Magento connection==== ====Magento connection====
  
-This tab controls how the Moneyworks Connector connects to Magento:+This tab controls how the Connector connects to Magento:
  
-{{ :moneyworks:connector_setup_magento_connection.jpg |}}+{{ :moneyworks:connector_Magento_connection.png |}}
  
   * Enter user name and password (API key) as supplied by the Magento site administrator.   * Enter user name and password (API key) as supplied by the Magento site administrator.
Line 63: Line 75:
  
 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 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 68: Line 82:
 This tab allows you to customise how imported records appear in Moneyworks. When it is selected, the system attempts to read tax codes and shipping codes from the Moneyworks data file: This tab allows you to customise how imported records appear in Moneyworks. When it is selected, the system attempts to read tax codes and shipping codes from the Moneyworks data file:
  
-{{ :moneyworks:connector_setup_moneyworks_settings.jpg |}}+{{ :moneyworks:connector_MW_settings.png |}}
  
   * //Highlight colour// controls how the imported records are coloured in Moneyworks.   * //Highlight colour// controls how the imported records are coloured in Moneyworks.
   * //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 required, you can define a mask for the order/invoice sequence numbers e.g. "W00000000" means that the first transaction will be assigned a sequence number of "W00000001", and so on. If left blank, Moneyworks will assign the next sequence number automatically. Depending on the customisation code entered, the same facility is available for assigning new customer codes.+  * 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 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.  
 +    * 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. 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, and a customised import map, 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 83: Line 102:
 This tab controls the sync process itself: This tab controls the sync process itself:
  
-{{ :moneyworks:connector_setup_other_settings.jpg |}}+{{ :moneyworks:connector_other_settings.png |}}
  
   * 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 101: 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 108: 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