# Import Jobs

Import jobs are a type of automated task that allows you to import data from "record-identifiers" files directly into Orderwave. This is only one method of getting data into Orderwave. You can also directly post data to our JSON API.

Terminology ⚡

A "record-identifiers" file is a text-based flat file that has a first column for each row that identifies what that record represents. See examples of these types of files in the feeds documentation. Do not include a header row in your files.

To setup an import job, you will need:

  • Import Mappings
  • Data in a text-based, "record-identifiers" file that matches the import mapping i.e. TAB, CSV, delimited file(s)
  • A File Transfer Location

TIP

Some import mappings are pre-created for you for feeds, such as Inventory Items, Inventory Syncs, Product Items, and Shipment Updates. Also, core integrations like Magento automatically interface with feed data to import data.

# File transfer location

Import jobs look for files that you have configured under file transfer locations. Make sure you have an FTP or SFTP site configured as a file transfer location where Orderwave can look for this file.

# Import mappings

Import mappings are definitions of mappings between your text-based files and the data in Orderwave. With an import mapping, you define how fields/columns should map to records in Orderwave.

# Create a new import mapping

To create a new import mapping, navigate to Admin > Import Mappings and click the ➕ button. You will be presented with the following fields:

Field Description
Mapping Code This is the unique identifier for this import mapping. You will use this code to help identify this import mapping definition in automated tasks.
Mapping Description This is your field for describing this import mapping. Be descriptive so that other team members will know what this is for.
Bucket Choose the bucket you will import data into with this import mapping.

# Configuring an import mapping

To configure the import mapping, click the Edit Mapping button at the top of the screen. You will be presented with a window that lets you choose the fields and mappings.

The first part of the configuration is the File Details section. These are options that specify general settings for the file.

Field Description
Source file-type This is the type of data that is going to be mapped. Record-Identifiers is the data-type that is supported for import mappings.
Columns separated by Choose the delimiter that you will pass in your files to separate the data columns. If you need a specific delimiter, besides tab or comma, simply type-in your delimiter string into this box.
Fields enclosed by If you are enclosing your column data in a specific string, like a " (which is very common for CSV files), choose it here. This is an optional enclosing character, so even if you're not enclosing the data, you can leave the default of ".
Line Endings Choose the type of line endings Orderwave should expect in the file. Windows line endings are \r\n, and Linux line endings are \n.
Update on duplicates Should you be passing a field that has enforced uniqueness, and we're unable to create a record because of a duplicate, you can tell Orderwave to update the matching record based on your file data.

The next series of sections will describe the actual record mappings from your "record-identifiers" file to the fields in Orderwave buckets.

# Record identifier

The first column in your files will always be a code that identifies the record. Commonly, it is a single character code that matches the data bucket name. For example, if your chosen bucket is wms/inventory, the default record identifier is I for "Inventory".

Field Description
Record Identifier The string/code that will identify the record contents (this is the first column of your file).
Bucket The bucket that the data will import into.
Buckets in Orderwave can be very complex with nested relationships. Your first record should be the top-most bucket in the bucket relationships (the default). As you add record identifiers for nested data relationships, choose the bucket that maps to the sub-data.
Data Mapping Location After you have chosen your bucket, choose where to map this data to. If this is a sub-relationship, you will be given options that match where that bucket is nested in the bucket data. Generally, you will "work your way down", populating data in nested relationships from the outside in.
Column (column number) Section that describes the individual mappings. To add another column mapping for a record, click the "Add field mapping" button.
Column The numeric column number that contains the data you are importing. Column numbers are zero-based, meaning that the "0" column is your record identifier, the "1" column is your second column, and so on.
Map to The field in Orderwave to map to your column data.

To add a new record type definition to this configuration, click the "Add record type" button at the bottom of the window.

When you are done with your configuration, click the "Save config" button to save it.

# Create an import job

An import job is just an Automated Task that is configured as an import job. Navigate to Admin > Automated Tasks and click the ➕ button to create a new automated task.

Your Automated Task should have the recurrence properties you need. For example, you can set this task to run with a frequency of 1 and a recurrence of Day; set the start-on field to the date and time that the task should start running. After you create the Automated Task, set the task properties by choosing Import job as the task type.

Next, choose the bucket that will import data — choose the same bucket that you configured your import mapping for. Also choose the file transfer location (FTP or SFTP site) that will have your file data.

Choose the import mapping that you have created.

If your (S)FTP server has a folder path where your file will reside, specify that in the Folder path field. If your file is in a set of folders like this:

/Orderwave-Files/
	/Shipment/
		/Tracking/
------------^ (files in this folder)

Then you would specify the folder path as Orderwave-Files/Shipment/Tracking/.

Next, specify the file name pattern that Orderwave should look for to import files. Orderwave will only import files that match this file naming pattern. File naming patterns support regular expressions, so you can have dynamic file names that include timestamps, etc. A simple file name pattern that matches a file name such as trackingdata_2021-07-18.csv would be trackingdata_.+\.csv. The first period (.) matches any character, the + matches any more of the previous matching characters, the \. is a literal period (not a matcher), and the csv is the matching file-extension. This is a simple example, but you can be more specific in your regular expressions if needed.

Finally, choose what to do with the file after it has been retrieved. You can configure the import job to delete the file from the (S)FTP server, or attempt to move it to an archives/ folder in the same location as the file.

After files are retrieved

After Orderwave gets the file from your server, Orderwave can attempt to move the file to a directory called archives/ that is in the same directory as the file that was retrieved. If the archives/ directory does not exist, or we are unable to move the file there due to permissions, the remote file will be deleted, so that Orderwave will not attempt to re-import it. If Orderwave cannot delete the file due to you not giving Orderwave the proper permissions, the file will be available to be re-imported, and could cause duplication.