Magento Integration Suite:UPS WorldShip Integration

Contents 1 Overview 2 Setting up the Integration 2.1 Order Export / Shipment Import 2.1.1 Preparing Magento for Export 2.1.2 Automatic shipment import into UPS WorldShip 2.1.3 Setting up the WorldShip Shipment Import 2.1.3.1 Preparing the data source 2.1.3.2 Setting up the import format in WorldShip 2.1.3.3 Setting up the keyed import (WorldShip 2013 and older) 2.1.3.4 Setting up the keyed import (WorldShip 2014 and newer) 2.1.3.5 Using Batch Import 2.2 Tracking Information Export / Magento Import 2.2.1 Preparing Magento for Import 2.2.2 Automatic tracking number export to Magento 2.2.3 Setting up the WorldShip Tracking Number Export 3 Troubleshooting 3.1 Going live 3.2 Synchronization stops working 4 Questions

Overview

The XTENTO UPS WorldShip connector provides a bidirectional connection between Magento and UPS WorldShip. The connector consists of two packages:

• Order export out of Magento - shipment import into UPS WorldShip
• Tracking number export out of UPS WorldShip - import back into Magento (Optional Add-On)

Using these two packages, you will be able to import your orders into WorldShip, and later on after shipping the parcels, you will be able to import the tracking information (parcel number, tracking link) back into Magento to provide the customer with the tracking number to track their order, and you'll also be able to notify the customer that their order has been shipped, making shipping using UPS WorldShip a breeze.

Exporting shipments into UPS WorldShip and importing tracking information back into Magento has never been easier.

Got questions? Feel free to contact us! Contact Form

Interested in this Magento integration?

Head over to our store to purchase this integration: Magento UPS WorldShip Integration

Setting up the Integration

This guide will help you setting up the UPS WorldShip integration.

Order Export / Shipment Import

Preparing Magento for Export

1. Open the connector ZIP file downloaded after your purchase. (Located in our store at My Account > My Downloadable Products)
2. Set up the Order Export Module (located inside the OrderExport folder) following our "Setup & Configuration" guide (see menu bar on the left, either Magento 1 or Magento 2 based on your environment)
3. Log into the Magento backend and go to System > XTENTO Extensions > Sales Export Configuration and enter the license keys you received via email.
4. After activating the module in the configuration, go to Sales > Sales Export > Tools and import the "UPS_WorldShip_Configuration.json" file.
5. The export has been configured now and is ready to use. Again, make sure to set up the Magento cronjob.

Please make sure the Magento cronjob has been set up for the Magento instance you're installing the extension in. If the Magento cronjob hasn't been set up, you won't be able to automatically export your UPS WorldShip orders. You can still manually export orders by going to Sales > Sales Export though, just select the export profile and press "Export" without changing anything.

Automatic shipment import into UPS WorldShip

If you want exported orders to be downloaded from Magento to the UPS WorldShip import directory automatically, follow these steps.

You can also manually download exported orders by going to Sales > Order Export and click on Download after exporting orders. If you want to download orders manually, please still create a directory somewhere on your hard drive which will be used for the Import into WorldShip. We'd suggest to use C:\XTENTO\MagentoToUPS\data\.

1. Extract the contents of the MagentoToUPS directory (inside the connector ZIP file) to a local directory on the WorldShip computer. We'd suggest placing the files in C:\XTENTO\MagentoToUPS\.
2. Open the folder where you extracted the files to and run the init_configuration.bat file to create the configuration and synchronization files. A couple new files and one new folder will be created. The newly created folder called data will contain the files which will be imported into WorldShip. This folder will be also used if you want to manually download files from Magento to WorldShip.
3. Open the newly created sync.ini file using a text editor and enter the credentials (server address, username, password, path) of the FTP server where Magento is installed on. Make sure to use the absolute path when entering the path. The path should be the absolute path to the /export/ directory inside the Magento root directory. For example, this could be: /export/ or, depending on the FTP home directory, for example: /domains/mydomain.com/html/export/. To find out the absolute path, use your FTP client and log in using the credentials you're using for the synchronization and navigate to the export directory inside the Magento root folder. Then, copy the path you see in your FTP client. Be careful: Entering the wrong path could lead to deleted / synced files. Enter the right path with /export/ appended.
4. Click on batch_sync_debug_mode.bat to test-run the synchronization and to see if the synchronization fails/succeeds. If necessary, adjust the configuration inside the sync.ini configuration.
5. Run the init_windows_task_creation.bat file (right click and "Run as administrator") to set up the automated synchronization. The synchronization task will be run every 15 minutes in the background from now.

If you want to initiate the download manually - for example if you're ready to process orders but don't want to wait for the synchronization task to run - simply run the sync.bat file manually. You can also create a shortcut on your desktop for it.

Setting up the WorldShip Shipment Import

Preparing the data source

To set up the data source for the import files, please run the Launch ODBC Admin.bat file (Important: If you are using 64-bit Windows 7 or newer, use Launch ODBC Admin - Windows 7.bat instead) located in the connector ZIP file. The ODBC Administrator will open.

1. Select the System DSN tab
2. Click Add...
3. Select the Microsoft Text Driver (*.txt; *.csv)
4. Click Finish. A new window called ODBC Text Setup will open. Enter: Data Source Name: MagentoToUPS Description: MagentoToUPS
5. Uncheck Use Current Directory.
6. Click Select Directory and select the data import directory in the MagentoToUPS folder you just created a step above. Example: C:\XTENTO\MagentoToUPS\data. Click Ok.
7. Click Options>>.
8. Click Define Format..
9. Select the worldship_export.csv file to the left, check the Column Name Header checkbox, select ANSI for Characters, for the Format select Custom, for the Delimiter enter ; (a semi-colon) and then click on Guess at the top right. Click OK. If an error occurs saying "Failed to save table attributes of (null) into (null)", just ignore it.
10. Click OK to close the ODBC Text Setup. You can now close the ODBC Administrator.

Hint: If you can't find the "Microsoft Text Driver" in the drivers dropdown, you're probably using Windows 7. Click here (Microsoft Access Database Engine 2010 Redistributable) to download the required drivers.

Hint: If you receive an error message when you try to configure the text driver saying "Ini File is corrupt" OR if no fields are displayed when trying to map the fields in WorldShip, please apply this patch and add the ODBC source once again: Patch

Setting up the import format in WorldShip

1. Open WorldShip
2. Select Tab Import/Export > Tools > Connection Assistant
3. Select Create a new map for Import. Click Next.
4. Select Shipment for the Import Data Type. Click Next.
5. Select By Known ODBC Source and select the MagentoToUPS ODBC source from the ODBC sources. Click Next.
6. Select New Map and enter MagentoToUPS for the New Map Name. Click Next.
7. Click Finish. A new window to edit the import map will be opened.
8. Select Worldship_Export.csv from the ODBC Tables to the left.
9. You will now have to map the Magento fields to the WorldShip fields. Below is a mapping describing how to map the fields. Just click Connect to "connect" two fields. Note: UPS tends to change the Field IDs often. The fields may have changed the ID, the name will remain the same though. The field should be somewhere in the region around the ID if the ID changed. You can also sort the fields alphabetically in Worldship for a better orientation.

Left Side (ODBC Tables, Worldship_Export.csv)	Right Side (WorldShip Fields)
REFERENCENR	Shipment Information -> Reference 1 (Field ID: 146)
NAME	Ship To -> Attention (Field ID: 3)
COMPANY	Ship To -> Company or Name (Field ID: 2)
STREET1	Ship To -> Address 1 (Field ID: 5)
STREET2	Ship To -> Address 2 (Field ID: 6)
ZIP	Ship To -> Postal Code (Field ID: 9)
CITY	Ship To -> City or Town (Field ID: 10)
REGION	Ship To -> State/Province/County (Field ID: 11)
COUNTRY	Ship To -> Country/Territory (Field ID: 8)
TELEPHONE	Ship To -> Telephone (Field ID: 12)
FAX	Ship To -> Fax Number (Field ID: 13)
EMAIL1	Ship To -> E-mail Address (Field ID: 14)
TAXNR	Ship To -> Tax ID Number (Field ID: 15)
WEIGHT	Shipment Information -> Actual Weight (Field ID: 110)
GRANDTOTAL	Shipment Information -> C.O.D. Amount (Field ID: 15)
SHIPPINGMETHOD	Shipment Information -> Service Type (Field ID: 3)
ISCOD	Shipment Information -> C.O.D. Option (Field ID: 14)
CASHONLY	Shipment Information -> C.O.D. Cash Only (Field ID: 17)
ORDERCURRENCY	Shipment Information -> C.O.D. Currency Code (Field ID: 16)
COMMERCIALINVOICE	Shipment Information -> Commercial Invoice Removal Option (Field ID: 37)
SIGNATUREREQUIRED	Shipment Information -> Delivery Confirmation Adult Signature (Field ID: 116)
BILLINGOPTION	Shipment Information -> Billing Option (Field ID: 5)
PACKAGETYPE	Shipment Information -> Package Type (Field ID: 120)
DESCRIPTIONOFGOODS	Shipment Information -> Description of Goods (Field ID: 104)

Important: You're almost done with mapping the fields. The last step is to select the REFERENCENR field from the left side and to click on Define Primary Key for Import. Click OK to save the mapping.

Setting up the keyed import (WorldShip 2013 and older)

1. In the main window of WorldShip, click on Tools -> Toolbar Editor... Select Start Keyed Import from the left and click Add -->.
2. Select the MagentoToUPS Map for the keyed import. You can now assign a text or image for the import button. Click on OK to save the button.
3. Select the newly created button from the Selected Buttons list and check both the Enable Toolbar as well as Dock Toolbar buttons.
4. Click on OK to save your changes. A new button will show up at the very right in WorldShip. Click on it and the Keyed Import window will open.

You're done with setting up the import! Simply click the Keyed Import button, enter the ID of an not yet completed order in Magento, and press Enter - the shipment details will be shown automatically.

Setting up the keyed import (WorldShip 2014 and newer)

1. In the main window of WorldShip, select the Import-Export tab and look for the "Quick Commands" box. Click Create New.
2. Select Start Keyed Import from the available commands and click Add. Select the MagentoToUPS Map for the keyed import. You can now assign a text for the import button in the "Command Caption" field. Click on OK to save the button.
3. Click on OK to save your changes. A new button will show up in the "Quick Commands" section. Click on it and the Keyed Import window will open.

You're done with setting up the import! Simply click the Keyed Import button, enter the ID of an not yet completed order in Magento, and press Enter - the shipment details will be shown automatically.

It is also possible to set up full automatic imports. Please note a full automatic import will only work if your products have the correct weight associated. Please get in touch for a quote if required.

Using Batch Import

If you don't want to use the "Keyed Import" method, you can also use the "Batch Import" functionality of WorldShip to import multiple orders at the same time. You would select the orders to ship at Sales > Orders in Magento, select the "Export orders" action from the "Actions" dropdown, and save the file in the C:\XTENTO\MagentoToUPS\data\ directory using EXACTLY the filename "WorldShip_Export.csv" (without quotes). Then, click on Import/Export in WorldShip and run a "Batch Import" - the previously selected orders will now all be imported into WorldShip.

Before using the batch import method described above, please open the "Windows Task Scheduler" and disable the "XTENTO-Download Job" task. Also, in the export profile at Sales > Sales Export > Export Profiles, in the "Automatic Export" tab disable automatic exports and in the "Filters / Actions" tab remove any filters.

Tracking Information Export / Magento Import

Provided you have purchased the tracking number import add-on as well, follow this guide to set up the tracking information export from WorldShip to Magento.

It is also possible to use just the tracking addon without the order import addon. You would just need to enter the Magento order number into the "Reference 1" field when shipping an order in WorldShip then. This is required so Magento knows to which order the tracking number belongs.

Preparing Magento for Import

1. Open the connector ZIP file downloaded after your purchase. (Located in our store at My Account > My Downloadable Products)
2. Set up the Tracking Number Import Module (located inside the Xtento_TrackingImport ZIP file) following our "Setup & Configuration" guide (see menu bar on the left, either Magento 1 or Magento 2 based on your environment)
3. Log into the Magento backend and go to System > Configuration > XTENTO Extensions > Tracking Import Configuration
4. Please make sure the Magento cronjob (cron.php inside the Magento root directory) has been set up to be called every 5 minutes. This is important. Follow this guide if you don't know how to set up the cronjob: Magento cronjob
5. Enter your "License Key" in the license key field and set the module to "Enabled".
6. Go to Sales > Tracking Import > Tools and upload the "xtento_trackingimport_configuration.json" file that can be found in your installation ZIP. A success message should confirm that 1 new profile and 1 new import source were added.
7. You've successfully installed the tracking number import module.

Automatic tracking number export to Magento

You can also manually upload tracking number files into Magento by going to Sales > Tracking Import > Manual Import. Just click on Upload file manually and select the tracking number CSV file (which will be created in the next step) from the UPSToMagento\data\ directory. Example: C:\XTENTO\UPSToMagento\data\ Then click on Submit.

If you want to export tracking numbers from WorldShip to Magento automatically, follow these steps.

1. Extract the contents of the UPSToMagento directory (inside the connector ZIP file) to a local directory on the WorldShip computer. We'd suggest placing the files in C:\XTENTO\UPSToMagento\.
2. Open the folder where you extracted the files to and run the init_configuration.bat file to create the configuration and synchronization files. A couple new files and one new folder will be created. The newly created folder called data will contain the tracking number file which WorldShip exports. This folder will be also used if you want to manually upload tracking numbers from UPS to Magento.
3. Open the newly created sync2.ini file using a text editor and enter the credentials (server address, username, password, path) of the FTP server where Magento is installed on. Make sure to use the absolute path when entering the path. The path should be the absolute path to the /var/xtento/trackingimport/ directory inside the Magento root directory. Create this directory if it doesn't exist. For example, this could be: /var/xtento/trackingimport/ or, depending on the FTP home directory, for example: /domains/mydomain.com/html/var/xtento/trackingimport/. To find out the absolute path, use your FTP client and log in using the credentials you're using for the synchronization and navigate to the var/xtento/trackingimport/ directory inside the Magento root folder. Then, copy the path you see in your FTP client. Be careful: Entering the wrong path could lead to deleted / synced files. Enter the right path with /var/xtento/trackingimport/ appended.
4. Click on batch_sync_debug_mode.bat to test-run the synchronization and to see if the synchronization fails/succeeds. If necessary, adjust the configuration inside the sync2.ini configuration.
5. Run the init_windows_task_creation.bat file (right click and "Run as administrator") to set up the automated synchronization. The synchronization task will be run every 15 minutes in the background from now.

If you want to initiate the upload manually - for example if you're ready to import tracking numbers but don't want to wait for the synchronization task to run - simply run the sync.bat file manually. You can also create a shortcut on your desktop for it.

Setting up the WorldShip Tracking Number Export

1. Open UPS WorldShip
2. Select Tab Import/Export > Automatic Export > Automatic Export During End Of Day > More..
3. Click Create / Edit Map
4. Go to "New Map", select Export CSV and select Shipment from the dropdown below. Enter UPSToMagento for the Name. Click Create.
5. A new window called Edit UPSToMagento export to CSV map will open. You will now have to assign the fields which should be exported into the tracking number file. It is important you follow the order below in which you add the fields. This is important for the import into Magento.
6. Select the Shipment Information -> Void Indicator field and click Add
7. Select the Shipment Information -> Service Type field and click Add
8. Select the Shipment Information -> Lead Tracking Number field and click Add
9. Select the Package -> Reference 1 field and click Add
10. Select the Shipment Information -> Reference 1 field and click Add
11. For the Field Delimiter, select Semicolon
12. Select Append to existing file
13. Click OK to save the mapping. A Save As window will open. It is very important you now select the UPSToMagento\data\ directory now you created a step above. Example: C:\XTENTO\UPSToMagento\data\. Click Save.
14. Click "Close" to close the Create or edit an import or export map window
15. Select the UPSToMagento map from the list for export and click on Export at the bottom

You're done with setting up the automatic export. As soon as you run the End of Day action, your tracking numbers will be exported to Magento.

Troubleshooting

Going live

If you installed the integration in a development environment, once you go live, you will need to take care of a couple things:
- Go to System > XTENTO and update the license keys for the live domain in both extensions. The live license keys are in the "XTENTO: License Key" email sent to you when you purchased the extension.
- Make sure the Magento cronjob has been set up. If you go to Sales > Sales Export > Execution Log, a warning shows up if it's not set up. If it's set up, no warning.
- If you change the FTP server credentials (because of a new hostname/or new logins for the live site), adjust the credentials in the C:\XTENTO\MagentoToUPS\sync.ini and C:\XTENTO\UPSToMagento\sync2.ini files on the UPS WorldShip computer.

Synchronization stops working

• If you change the FTP server credentials and the synchronization/export/import fails, adjust the credentials in the C:\XTENTO\MagentoToUPS\sync.ini and C:\XTENTO\UPSToMagento\sync2.ini files.

Questions

Got pre-sales questions? Need to change anything in the connector or the output files? A field missing that you want to add? Feel free to contact us! Contact Form