Generic File: Add a Store Using FTP
ShipWorks currently has integrations to more than 80 online marketplaces and sales channels. However, in some case it may be necessary to import orders from a source other than one of our integrations. For example, you may sell on a sales channel or store that ShipWorks is not directly integrated with, but you can export your order information from your sales channel into an Excel spreadsheet, CSV file, or a text file.
The good news is that ShipWorks allows you to easily grab data from your external file so that you can import the order information into the ShipWorks software. You then have all the ShipWorks tools available to you to easily and quickly ship your orders.
In this article, we will take a look at how to map your external order file to the ShipWorks software using an FTP account.
If you will be importing from a local directory on your PC or Network, click here for instructions.
If you will be importing your orders from an email account, click here for instructions.
We have provided a test .CSV file for you. It is attached to the end of this help article. It is the same file used in this tutorial. So, if you do not have an order file currently but still wish to learn the process, please feel free to download the attached Excel file and use it to learn the mapping process. The file also has a reference of all available, mappable fields.
So that you can be sure that you have access to all of the latest tools and features that ShipWorks has to offer and so that you can ensure the steps in this article will work for you, we recommend making sure that you are running the latest version of the ShipWorks software. For assistance with checking your version of ShipWorks or with upgrading to the latest version, please see this help article.
In addition, you will need the file that you wish to import into ShipWorks. The file will need to include at least one order.
Q: What are the requirements for the file?
A: Great question! ShipWorks can import from an Excel spreadsheet (.XLS or .XSLS file), a .CSV (comma delimited) or text file (.TXT), or from an XML file.
.CSV, .XLS, XSLX, or .TXT file: There is no set format or structure the file needs to be in because we will be defining what data is pulled from the file and to which fields in ShipWorks the data gets imported into. However, the file does need to have column headings.
The file needs to be an .XLS/.XSLX ( Excel spreadsheet), a .CSV (comma delimited) file, a .TXT (text delimited) file.
The file needs to have valid column headings.
The Order Number field is required.
The Order Number field can be numeric or alpha-numeric.
Here is a quick example of what an Excel file might look like. Note the valid column headings. We've also attached a sample .XSLX file for your reference to the end of this article.
XML File: Unlike Excel or text files, XML files must conform to the ShipWorks schema to be imported successfully. The ShipWorks schema .XSD file can be found here for your reference.
See the end of this article for an attached, sample .XML file that can be used for your reference. (This file does not contain all of the available fields that can be imported. It should be used only as a reference for a correctly formatted .XML file per the ShipWorks schema.)
Define Your Own Schema with an XSLT Stylesheet
If you have an existing XML format you can use it as-is by providing ShipWorks with an XSLT stylesheet to transform incoming XML files. You will be presented with an option to import your XSLT stylesheet in the store setup wizard.
You will need to have a unique folder or directory available in which you will place the files to be imported into ShipWorks. This directory needs to be used only for the importing of your orders into ShipWorks. For this example, we will be pulling our orders from an FTP (File Transfer Protocol) directory.
You may need to use an FTP client such as FileZilla in order to create the needed FTP directories and to transfer your order file to the FTP location. In addition to an FTP client you may need the FTP Host address, FTP username and password. If you are unsure of how to use an FTP client or if you do not have this information, please reach out to your local IT professional or network administrator.
Mapping your file to ShipWorks can be broken down into the following steps:
1. Creating the folders or directories from which you will import the file(s).
2. Selecting the type of file to import
3. Pointing ShipWorks to the folder or directory.
4. Selecting the import file you will use to create your mapping.
5. Mapping the fields in your file to the fields in ShipWorks.
6. Importing your orders.
ShipWorks can import from your PC, from a network location, FTP directory or even pull from an email. In this example we will be pulling our orders from a folder using an FTP (File Transfer Protocol) connection. This is useful if you are running multiple ShipWorks computers and would like for more than one of them to be able to import the order files from a remote location or server.
We want to have a unique directory from which only ShipWorks orders are imported. If any other files are placed in this directory you may encounter errors in ShipWorks and unexpected behavior may occur.
When using an FTP location, you may need to use an FTP Client such as FileZilla to connect to and maintain your FTP directories. In the below examples, we will be using FileZilla but you can use whichever FTP client works for you. If you have questions regarding FTP, please reach out to your resident IT professional.
1. Connect to your FTP directory using an FTP client such as FileZilla. If you are unsure of how to do this, please reach out to your local IT professional.
2. Once connected, navigate to the location from which you would like to import files into ShipWorks.
3. Create a new directory at this location and name it ShipWorksImport.
3. Inside of the ShipWorksImport directory create a new directory and name it Complete.
This folder is used to store the files that are successfully imported into ShipWorks so that you can refer back to them if needed.
4. Now, transfer your file containing your orders into the ShipWorksImport folder using your FTP Client.
The name of your file does not matter. It can be named whatever makes sense to you. Once the orders are imported into ShipWorks, ShipWorks will move the file into the Complete folderand append the file name with the import date and time.
You will also need a local copy of your order file available to you on the ShipWorks PC. This file will be used to create the Generic File Import map later in this article.
Great! Now, you are ready to begin working in the ShipWorks application.
3. Now, select the type of file you will be importing from the What type of file will ShipWorks be importing: option. Then, click Next.
For this example, we are importing from an Excel spreadsheet, so we have selected the Excel option.
4. Next, we need to tell ShipWorks from where we are pulling our data. From the Import the data from: menu select An FTP Folder.
1. On the Import the Data From: screen, click on the Configure button to the right of the FTP Server field.
2a. Enter the FTP account settings used to connect to your FTP server. You will need the following information:
If you are unsure of this information, please reach out to your local IT professional or network administrator.
2b. Once the information is entered, click Next.
2c. If prompted to select a directory from within your FTP location, select the root directory of your FTP. Typically, this is the first directory listed in the tree. Then, click Next.
Note: In our example the directory is named home however, yours may be named differently.
2d. Once you have connected to your FTP account successfully, click Finish.
Now, lets tell ShipWorks the specific directory from which we will be pulling our order file.
1. Click on the Browse button to the right of the Incoming Folder: field.
2. Navigate to the ShipWorksImport directory that we created in the above steps. Then, click OK.
You have options available for:
Only import file names that match this pattern - Used to tell ShipWorks to only import files that match a defined naming pattern.
Skip files names that match this pattern - Used to tell ShipWorks to skip importing any files that match a defined naming pattern.
We will not select either of these options since we are using this folder ONLY for files that will be imported into ShipWorks and the files will always be named the same.
Now, let's tell ShipWorks to where the successfully imported file should be moved. (Remember that we created the Complete folder earlier?)
1. Click on the Browse button located in the After a successful import: section.
2a. Navigate to the Complete folder that we created in the previous section. Then, click OK.
Note: You do have the option of having the file deleted after a successful import.
There are two options that you can select from for when an error occurs while importing an import file. Let's take a look at them:
Stop importing and display the error - When an error occurs, ShipWorks will not move the file, but instead will stop importing and pop up a message to help you determine the cause of the error.
Move the file and continue importing - ShipWorks will not stop importing the file and will move the file to the Complete folder once finished. However, this may cause orders to be missed in ShipWorks since it skips the order or data that caused the error.
1. From the If an error occurs while importing: drop-down menu, select the option that works best for you. In this example, we are leaving the default to stop and display an error.
Nice job! We are now ready to select the actual import file and to begin the mapping process.
2. Click Next.
Importing an XML File?
When importing an XML file you will not be presented with the steps to create an import map. This is because XML files define into which fields the data should be populated within the file itself. Please continue with the 'Test Your Setup' section at the end of this article.
Now, we are going to point ShipWorks to the actual order file that we wish to use for mapping. We placed the import file into our ShipWorks Import folder earlier on in this article. If you missed this step, no problem, just paste it into the folder now.
1. In the Import Map screen, click on the New Map button.
2. OK, now we have to navigate to and select an import file that is saved locally on your PC. So, click on Browse, navigate to your ShipWorks Import folder/file and then select the import file you will use to create your mapping. Then, click Open.
3. After selecting the import file, ShipWorks will display the data found in the file so that you can be sure that it looks correct. By default, ShipWorks will look to the first row of an Excel file (row A) for the column headers. However, you can modify this if your headers are located on a row other than the first row of your spreadsheet or data source. Once the data is correct, click Next.
If you have never mapped a file to an application or database before, it is super easy. What we will be doing is defining to ShipWorks exactly where ShipWorks should import your data to. For example, ShipWorks does not know that it should place the customer's first name into the First Name field. So, we are going to tell ShipWorks where to place our data.
The only field that is required in ShipWorks to be mapped is the Order Number field. All other fields are optional. So, if you only have a few fields in your import file, this is totally OK. You can map only the fields that you need to.
Before we begin mapping, take a look at the Map Setting section. it gives you the File Name, source information and Date format information. If the Date format is not correct, you can click on the Edit button to manually configure the date and time settings.
OK, let's begin mapping.
Notice that ShipWorks breaks the data down into 3 separate groups, Orders, Address, and Items. When you select one of the three groups, only the fields in ShipWorks that relate to this group are made available for mapping. This is done to help organize the mapping process.
In addition, the Column Mapping screen is divided into two columns. The ShipWorks Field column lists the available fields in the ShipWorks database while the Source Column allows you to select from your import file what data should be imported into the ShipWorks Field.
We will not go through mapping every single field in our file. That would make this article really, really long. So, instead we will map two or three columns for each group so that you can see how it is done.
1. Select Orders from the Column Mappings screen. Now, let's map the Order Number. In the Source Column click the drop-down menu to the right of Order Number. A list of all of the available columns in your source file will be displayed along with examples of the data from your import file.
2a. Click on the Column Name that houses your order number data. Notice that the OrderNumber source column is now mapped to the Order Number field in ShipWorks. This means that when you import your orders, ShipWorks knows where to place the order number in its' database.
2b. Let's map one more column from the Orders group. Sometimes, you will need to map to a field in ShipWorks based upon how your input file is formatted. For example, you will notice that ShipWorks has an Order Date and Time field AND separate Order Date and Order Time fields. Our sample import file only has an order date so we will only use the Order Date field. However, if you have both the order date and the order time in the same column, you may wish to use the Order Date and Time field in ShipWorks.
2c. Continue mapping all of the Order fields in your import file to the fields available to you in ShipWorks.
3. Select the Address group on the Column Mappings screen. Notice that the ShipWorks Fields change to show only the fields that relate to address information.
Note: ShipWorks allows you to import both Ship to and Bill to address information. Neither are required. You can import one or the other or both.
3a. In our sample import file, we only have one address. So, we will map our address columns to the Ship to fields in ShipWorks. Map your address columns to the available fields in ShipWorks.
Mapping the Ship First Name field
Mapping the Ship Last Name field
Mapping the Ship to Address1 field.
3. Continue mapping the address columns from your import file to the available fields in ShipWorks.
4. Select the Items group from the Column Mappings section. The screen changes to display only the ShipWorks fields related to items.
5. Make note of the Multiple Items section available to you now. You will use this section to define how the line items are listed in your import file. There are two options available to you. Let's take a look at both of these options.
All items are on the same line as the order - If all of the items are listed on the same row as the order information in your input file, then this is the option for you. Here is an example:
Click to enlarge the above image
With this option selected, you can select the max number of items you will need to map to ShipWorks and how many attributes are available for each item.
The order line is repeated for each item - If your import file has a separate row for each line item on the order, this option is for you. Here is an example: Notice that the OrderNumber is repeated on each row indicating that the items belong to the same order.
Click here to enlarge the above image.
With this option selected you can specify what column of your input file identifies each order and the number of attributes associated to your items. It is important to note that line items will be combined into a single order only when the unique identifier appears in contiguous lines of your import file. (For example: In the above image, OrderNumber 6000 appears on lines 2 and 3 for the import file. So, the line items will be combined into a single order.)
5a. Based upon the above examples, select the correct option for your import file. For this example, we will select the below options:
5b. Map the appropriate columns from your import file to the correct fields in ShipWorks.
6. When you have completed mapping all of your Order, Address, and Item fields, click Next.
Congratulations! You have completed the Generic File setup!
7. Click Finish. Then, click Close.
Once you have completed your Generic File setup you will be able to import the orders from your input file. To test your setup:
1. Ensure that your import file is placed into the ShipWorks import folder that you created in the above steps.
2. In ShipWorks, go to the Home tab and then click on the Download button.
If all goes well you will see your orders being imported into the ShipWorks software.
You will also notice that the import file was moved from the ShipWorks Import folder into the Complete folder you created in the steps above. It will also be appended with the date and time that it was imported into ShipWorks.
Still Need Help?
Please feel free to reach out to one of our awesome Technical Support Representatives in St. Louis. We are happy to help.
Have a comment to share about this article? We'd love to hear from you. You must be logged in to your Support Portal account to leave a comment.