Miva’s ODBC driver for Windows allows you to push and pull data from Miva to any Windows based application which uses the ODBC API. ODBC (Open Database Connectivity) is an open standard API for accessing a database. Miva’s implementation of ODBC translates the API calls into our JSON API so it’s able to securely push and pull data from Miva without giving the external system direct access to Miva’s database, which is a much more secure method of data transfer.
In addition to the ODBC driver which UPS WorldShip uses, we also have a companion app that plugs into Miva and allows WorldShip to push back tracking numbers and shipment information to Miva.
Video Walkthrough
Windows Support
The ODBC driver for Miva is supported on the latest version of Windows and comes in a 32-bit and 64-bit versions.
Note: WorldShip only supports 32-bit, so even if you are on 64-bit version of Windows, you’ll want to install the 32-bit version of the driver if you are going to be using this to connect to WorldShip.
Driver Dependencies
As part of the Driver installation process there are three dependencies that will automatically get installed (if they don’t already exist on your Computer already)
MivaOdbcDriver_x86.msi – Install Package for Windows
Worldship.mvc – Optional app, used to help push tracking numbers back to Miva when using WorldShip
These files should be downloaded on the Windows computer which has the application you wish to connect to Miva via ODBC.
Install the Driver
To initiate the installer, double click on the setup.exe file. This will start the installation process starting with installing the required dependencies. Follow the prompts to complete the installation.
Important: One of the files will require the computer to be restarted to install. This is normal and required for the installation to be completed.
Once the dependencies have been installed, the Installer will run to install the ODBC Driver.
Follow the prompt from the installer to complete the installation.
Create ODBC Data Source Name (DSN)
Once the driver is installed on the computer the next step is to create the Data Source Name. This is the symbolic name that represents the connection. It stores the connection details such as the Miva JSON API keys.
In Windows search for “ODBC Data Sources”. This should bring up the Data Sources Administrator.
Click Add to add a new Source. From the list select Miva ODBC Driver.
This will bring up a new configuration window where you can add the connection details to the Miva JSON API.
Create JSON API Token in Miva
Since the Miva ODBC Driver translates an API call into Miva JSON API calls you need an API token setup in Miva for it to use. API Tokens can be created under Settings -> User Management -> API Tokens.
API Token Group Permissions
You will need to assign the API Token the correct group permissions based on the functions the API token will need to use. In most cases assigning the API token to the Order Processing Group should be sufficient.
To assign a token to a group, select the API token from the list, click the more menu (…) then select Groups.
Once the API Token is created, populate the DSN with API Credentials.
Fetch Count: This is a setting to determine how many orders/shipments are pulled in a single API request. The default is 100, but this can be increased or decreased as needed.
Record Wait Timeout: The default timeout is 2000ms (2 seconds) in the event the connection cannot talk to Miva.
UPS WorldShip Module Support: This should be checked if you are using the ODBC connection to connect to Worldship and you wish to push tracking numbers back to Miva.
Note: An app/module (worldship.mvc) for Miva is required in addition to this setting being enabled to push tracking numbers back to Miva.
Request Log Path: Optional path to where a log file should be created for debugging.
Debug Log Path: Optional path to where a log file should be created for debugging.
Once completed, click Test Connection to verify everything is correct. If successful it will return the Miva Merchant version, it is connecting to.
Data Available via the ODBC Driver
The ODBC Driver for Miva only enables Miva to talk to Worldship via an ODBC connection.
The following Miva Database tables and actions are made available via the Driver.
AvailabilityGroups
Select
Insert
Update
Delete
BusinessAccounts
Select
Insert
Update
Delete
Customers
Select
Insert
Update
Delete
Coupons
Select
Insert
Update
Delete
Notes
Select
Insert
Update
Delete
PriceGroups
Select
Products
Select
Insert
Update
Delete
URIS
Select
Categories
Select
Insert
Update
Delete
Orders
Select
OrderShipments
Select
Insert
Update
CustomerAddresses
Select
Insert
Update
Delete
CustomerCreditHistory
Select
Insert
Delete
Stores
Select
WorldShipOrderShipments
Insert
Update*
* Update only available if setting for "UPS Worldship Module Support" is checked.
Installing Worldship.mvc Plugin for Miva
If you’re going to be using this driver to connect Worldship to Miva and you wish to push back up tracking numbers to Miva for each label generated in WorldShip, there is a separate app you need to install from the app store.
You can download the app here:
This download will contain a file named worldship.mvc. To add to Miva navigate to: Settings -> Domain Settings -> Modules -> Add Module.
Here you can upload the module file.
Next we need to add it to the store. Go to Settings -> Modules and search for the module.
Click Install to install it to the store.
This module opens up new API functions which the ODBC connector uses to create shipments and add tracking numbers in Miva. There is no configuration for this module in Miva. Once it's installed in the store, WorldShip will be able to use it to send up tracking numbers.
WorldShip Setup and Configuration
WorldShip is a Windows desktop application created for high-volume UPS shippers used to create shipping labels and help automate shipping processes.
UPS WorldShip is available to any UPS shipper. More information can be found here:
UPS WorldShip must be installed on a desktop computer utilizing a Windows-based operating system. The latest version of WorldShip supports Windows 8.1 and Windows 10. WorldShip will not function on non-Windows systems such as MAC or Linux, tablets, or mobile devices. Click here for the full WorldShip system requirements.
Importing Order or Shipments
The ODBC connector supports both importing Orders from Miva to WorldShip and/or Shipments.
Orders – The simplest and most common scenario to link WorldShip and Miva is to import orders from Miva into UPS WorldShip. This allows you to go into WorldShip, to type in an order number and have the ship to information and shipping method automatically get imported.
However, this has one big downside. You cannot split shipments. Since WorldShip does not import the items in the order there is nothing to Split. The entire order is treated as a single shipment.
Shipments – Alternatively (or in addition to Orders) you can also import Shipments. This allows you to first go into Miva and create the shipment for each order or split the order into multiple shipments. If you handle a lot of split Shipments, it may be better to setup WorldShip to import shipments however it does require an extra step of first going into Miva to create each shipment for each order.
Order Import Data Mapping
Once you have WorldShip installed, the first step to link it to Miva is to create a Data Map. This tells WorldShip where to pull the order (or shipment data) from Miva and how the order fields from Miva will be mapped to fields WorldShip needs to create the shipping label.
To create the Data Mapping, open up WorldShip and click “Create/Edit Map” from the top menu bar.
Under New Map, select the radio button for "Import from ODBC Database."
For Map Type, select Shipment.
Give the Data Mapping a name such as "Import Orders from Miva."
Click Create.
After you click create, WorldShip will prompt you choose a Data Source so it knows where it is pulling the order data from:
From this list choose the DSN you created when you installed and setup the ODBC Driver in earlier steps. An ID or Password is not required.
Click OK, which will bring up the Import Mapping Edit Screen where you can see available fields to Map in Miva and available locations they can get mapped to in WorldShip.
The left column (ODBC Tables) are the list of tables to pull data from in Miva. The Right Column (WorldShip Fields) where the values can be mapped to in WorldShip.
From the dropdown in the left column select Orders. The right column should be on Ship To.
Below is an example of how the fields should be mapped which can be customized for your specific use case. This example shows two-method mapping.
To create a mapping, select a value from the left column and another from the right column then click Connect. This will add it to the bottom section showing you what you have mapped so far.
When finished with all your mappings, click OK to save.
Mapping Shipping Method/Service Type
In order for UPS WorldShip to know how to map the name of your shipping methods to its methods, you need to explicitly map each method in your store to a valid method is WorldShip.
After you have linked the ship_method to the Service Type above, select the field mapping and click Edit. From here click Translations then select Service.
Here you can enter in the Miva Shipping Method and the WorldShip Shipping method then click Add.
You will need to do this mapping for each UPS shipping method you offer on your Miva website.
Keyed Import
Once you have the data mapping complete the final step is to use this mapping to create a keyed import. This allows you to enter in the order number (the value you set as the primary key in the step above) and it will pull in all the Ship To information including the service type.
In the top menu bar under Import/Export click Keyed Import and select the data mapping you created previously.
This will bring up a prompt where you can enter in the Order ID.
If you enter in a correct Order ID and click enter all the fields you mapped should be brought over including the Service Type (shipping method).
Batch Import
Some merchants may wish not to enter in each order one by one. UPS WorldShip also has a Batch Import feature where it can import orders in Bulk.
Note: Merchants with many orders may experience considerable lag when using the bulk import, because it does not apply any searching to the query executed and just selects all rows.
Push Tracking Numbers to Miva
The WorldShip integration with Miva also has the ability to push shipment information and tracking numbers back to Miva once the label has been generated in WorldShip. To do this we first need to create an Export Map.
Create Export Data Mapping
Go to Create/Edit Map.
Choose Export to ODBC Database.
Map Type should be Shipment
Give the Data Mapping a name such as "Export Tracking Numbers to Miva."
Click Create, then choose your ODBC Source.
Here are the data mappings you will need to setup.
Important: You need to have “Use WorldShip Module Support” checked in order to see the WorldShipOrderShipments table.
Click Save to save the Mapping.
Setting Up Automatic Tracking Number Export
WorldShip has the ability to automatically push back tracking numbers to Miva after the shipment has been processed and the label has been generated in WorldShip.
To configure this under the Import/Export tab, click the Automatic Export Button.
Select the Mapping you created in an earlier step and select Export.
With this setup any time an order/shipment is processed in WorldShip it will automatically push the tracking number back to Miva and trigger Miva’s order confirmation emails (if these are setup in Miva).
Voiding a Label/Shipment
If you need to void a shipping label in WorldShip, it will also remove the tracking number from Miva and change the order status from Shipped to Processing.
To void a label In WorldShip click the History button under the Home tab. From here expand the left menu to find the shipment. Then right click and select Void/Delete Marked.
This will void the label in WorldShip and update the order status in Miva to be processing (vs Shipped).
Orders in a Processing State
WorldShip is only able to create shipments for entire orders that are in a pending state. If you are getting an error pushing the tracking number back to Miva, verify the order is in a pending state (not Processing).
Keep in mind if you void a shipment you’ll then need to go into Miva and remove it from a shipment to return it back to a pending state to be able to Ship it again via WorldShip.
Importing Shipments from Miva
Instead of (or in addition to) importing Orders into WorldShip, you can also choose to import Shipments. Importing Shipments from Miva instead of orders allows you to first split the order into multiple shipments in Miva and then import each shipment individually. This would be useful if you have a lot of orders where there are multiple shipments on different dates/times.
This import method is required if you want to be able to support multiple shipments per order with WorldShip.
The configuration for Importing Shipments is the same as Orders outlined above with the following important changes:
When creating your data mapping, you will pull data from the OrderShipments table not the Orders table. Keep in mind that for a Shipment to exist in this table you have to manually create the shipment(s) for each order in Miva.
Your Primary Key mapping in WorldShip should be the Shipment Code not the Order ID. This allows you to use the Keyed Entry in WorldShip to copy and paste in the Shipment code from Miva.
You’ll want to store the Shipment ID in the ShipmentInformation:Reference 1 Field. This is used to mark the shipment as shipped in Miva when a label has been generated from WorldShip.
When creating the Export Map to push tracking numbers back to Miva you will need to map the Reference 1 field (which contains the shipment id) to the WorldShipOrderShipments:shipment_id field. The rest of the mappings outlined above should be the same.
