GuidesAPI DocsLatest NewsStatusCreate Support RequestReturn to zoey.com
Guides

Data Mapper Integrations

Data Mappers provide Import/Export connections to FTP/SFTP servers, Dropbox, and direct to email, to optimize your data management.

Suggest Edits

👍

Zoey Data Mappers can be used to Import or Export data on a schedule.

The Data Mapper tool has widespread application! Read on to learn why, and how to use them.

Data Mappers Explained

Zoey Data Mappers serve crucial roles in sending and receiving data from external systems. But, they can also be used to simply send a CSV file report to your email on a routine bases.

To set up a Data Mapper means to create a Connection and then the Data Mapper.

  • The Connection is responsible for deciding where to send/receive the data for your mapper.
  • The Data Mapper is where you configure all the mapper settings and choose which data columns are exported or imported.

📘

Below we explain general Data Mapper concepts and the basic steps for setup.

Click here for specific Data Mapper examples based on the data you are looking to export!

Check the sidebar for a list of related resources and take advantage of our AI search to ask questions about mapper exports and imports!

Connections

Navigate to Integrations >Zoey Data Mappers > Manage Connection > Add Connection.

Setting up a Connection

In order to use a Zoey Data Mapper, a Connection to an external system must first be made. All Connections require a Connection Name to help identify the Connection within your Zoey Store

The available Connection types and associated fields are listed below:

Dropbox - Import & Export

Email - Export Only - Sends an email with files attached to the specified email addresses.

  • Email Recipients: Specify who should receive emails for this connection. One email per line, maximum 10 emails.
  • Sender: The email address that "sends" the email. The list of Senders is populated by the "Sender Email Addresses" within your Zoey Store under Settings > Emails

FTP - Import & Export - Upload File to or Download files from an FTP Server

  • Host URL: Either the IP Address or HTTPS URL of the FTP Server
  • Port: Port used when making the FTP connection. Defaults to 21
  • Username: User to log into the FTP server
  • Password: Password for the User logging into the FTP server
  • File Transfer Mode: ASCII or Binary. This value depends on your FTP server's settings.
  • Default Directory: The default directory the user has access to after Logging In

HTTPS - Export Only - Submit HTTPS POST Requests to a Specified URL

🚧

Security on your webserver may prevent the file from being posted.

If you receive Status Code 406, it may be security modules such as ModSecurity causing it.

  • URL Endpoint: The HTTPS URL destination for the POST requests. Requests will automatically timeout after 60 seconds. URL must start with https://
  • Test URL Endpoint: Zoey will execute a sample request with an empty body to this URL when testing the connection and check for the HTTP response code defined below. You may use the URL Endpoint defined above or a separate URL (belonging to the same domain) if the URL Endpoint is not configured to receive an empty body. URL must start with https://
  • HTTPS Method: The HTTP Method used when submitting the request
  • HTTPS Success Code: Zoey will check for this HTTP response code to verify the HTTPS request was successfully sent.
  • Additional HTTPS Headers: Additional Header Names/Values to be sent in the Request

👍

The HTTPS Authentication is used to ensure that the data you are receiving is properly signed so that you can authenticate it.

This is a security best practice to ensure your endpoint is not accepting arbitrary data.

If you do not plan on authenticating the request on your end (or the third party you're using) then you can put any value you want in these fields as you aren't checking them.

🚧

The following are not required unless using HTTPS Authentication.

  • HTTPS Signature Header: The HTTPS Header Name for the HTTPS Signature. This value will be a 64 character randomly generated string for each request. Hash this value using the HTTPS Signature Key to verify the HTTPS Signature Hash.
  • HTTPS Signature Hash Header: The HTTPS Header Name for the hashed HTTPS Signature. This is the hashed value of the HTTPS Signature using the HTTPS Signature Key.
  • HTTPS Signature Key: The key used for hashing the HTTPS signature. Use this signature when validation the HTTPS Signature Header and HTTPS Signature Hash Header.
    The HTTPS Key must be 16 characters or more.
  • HTTPS Signature Method: The hashing algorithm used for the HTTPS Signature Hash.

SFTP - Import & Export - Upload File to or Download files from an SFTP Server

  • Host URL: Either the IP Address or HTTPS URL of the SFTP Server
  • Port: Port used when making the SFTP connection. Defaults to 22
  • Authentication Type: Specify whether to use Username/Password or Private Key authentication
  • Server Type: Specify either Unix or Windows depending on your SFTP server
  • Username: User to log into the SFTP server
  • Password: If Username/Password Authentication is selected, the password for the User logging into the SFTP Server.
  • Private Key: If Private Key Authentication is selected, the Private Key for the User logging into the SFTP Server

SSH - Import & Export - Upload File to or Download files from an SSH Server

  • Available Connection Fields for the SSH connection are the same as SFTP Connections defined above.

Creating a Data Mapper

Navigate to Integrations >Zoey Data Mappers > Manage Connection > Add Data Mapper.

Configuration

  • Name: Provide a name to help identify the Data Mapper and distinguish it from others. This is for reference only.
  • Connection: Select a previously created Connection to use for the Data Mapper.
  • Enabled: A Yes/No flag to determine if the Data Mapper will be run automatically.
  • Priority: Numerical value to determine the order in which this Data Mapper will run. Data Mappers will run from lowest priority to highest priority (Priority 1 will run before Priority 2)
  • Use Schedule: Configure how often this Data Mapper will run in the background.

👍

Pick the right Zoey Object for the report or process you are automating!

We have some Data Mapper Templates you can use for common import/export practices.

Find those Data Mapper Templates here.

📘

HTTPS Data Mappers

Data Mappers with HTTPS connections will not use a schedule and will always run automatically every two minutes if Enabled.

🚧

Export and Import Notes

Export Action "CSV File with Customizable Fields" is only available to Non HTTPS Connections

Export Action "HTTPS POST Request with Customizable Fields" is only available to HTTPS Connections

Importing is only available for the following Connections: Dropbox, FTP, SFTP, SSH

Zoey Objects

The Zoey Object is the type of data you are exporting. The object cannot be changed after it has been selected and the Data Mapper has been saved.

📘

The Zoey Object you are exporting will determine what fields are available to export.

The following objects are available for use with for the listed operations:

Contacts (formerly Customers)

  • Export
    • CSV File or HTTPS POST with Customizable Fields

Invoices

  • Export
    • CSV File or HTTPS POST with Customizable Fields

Payments

  • Export
    • CSV File or HTTPS POST with Customizable Fields
    • Can be Grouped by Order

Invoices

  • Export
    • CSV File or HTTPS POST with Customizable Fields

Quotes

  • Export
    • CSV File or HTTPS POST with Customizable Fields

Quote Items

  • Export
    • CSV File or HTTPS POST with Customizable Fields
    • Can be Grouped by Quote

Orders

Order Items

  • Export
    • CSV File or HTTPS POST with Customizable Fields
    • Can be Grouped by Order
    • Bundled product mappings are controlled by two settings:
      1. Export Bundle Selections - Includes the bundle's items in export.
      2. Remove Bundle Parent - Removes line item for the bundle itself, leaving just the bundle items.

Products

Shipments

Shipment Items

  • Export
    • CSV File or HTTPS POST with Customizable Fields

Importing / Exporting Files

File Export

  • Export Mode:
    1. All Objects To One File
      • When either File Export or HTTP Export is selected, specify whether to export each Zoey Object to an individual file or request or combine all Zoey Objects into a single file or request.
    2. Each Object To Its Own File
      • Object Grouping: When Export Mode is "Each Object to its own File" certain Zoey Objects that are child objects of other objects can be specified to be grouped together by the Parent Object. For example, if exporting Order Items, the Order Items can be grouped together by the Order they belong to.
        1. One Per File - Each exported Object is exported in its own file/request
        2. Group By [Parent] - The exported Objects are grouped by the parent Object (ex.. Order Items are grouped by Order)
          • Merge Grouped Files - When Group by [Parent] is chosen: Merge the separate Files/Requests back into a single File/Request before it is exported. This is useful when objects are Grouped By [Parent] but a single exported File is needed.
    3. Use Variation Attributes (Only available for Order Items and Quote Items) - When set to Yes, Configurable Products will use the value from its Variation for Variation Attributes (color, size, etc..)

File Import

  • Import Mode:
    1. Import Based on File Name - Import just the file matching the File Name.
    2. Import All Directory Files - Imports all files from the specified directory.

File Settings

Export File Settings

  • File Name - The name of the file to be exported. Variables can be added to the filename such as timestamp and the Order Number being exported.
  • Conditional File Names - The file name that is exported can be changed based on conditions of the Zoey Object being exported. For example, if exporting Orders, the filename can change based on the Customer Group of the Customer who placed the order.
    • Conditional File Name - The name of the file to upload if the conditions are met.
    • Priority - The order in which conditions will be checked. Conditions with a lower priority are processed first.
    • Condition - The field of the Zoey Object on which the condition is based.
    • Type - The operation that the condition will check:
      1. Is Equal To - If the "Condition" value is equal to the value provided the condition will be true.
      2. Is Set - If ANY value is set on the Zoey Object the condition will be true.
  • File Format - Defaults to CSV
  • Line Endings - Specify the type of line endings for the file. By default, UNIX line endings will be used, but Windows (CRLF) can be specified.
  • Export Format - Default Format expects one object per row based on selected fields. Header Detail Format allows for specific fields to be placed on top of the file before additional Zoey Object rows are added.

    🚧

    Header Detail Format has been deprecated and Default Format should be used.

    To add specific fields on top of the file before Objects are exported, use Custom Rows instead.

  • Remove CSV Column Names - When set to Yes, Column Names will not appear in the exported file.
  • Enclosure - When set to Quote ", string values in your export will be wrapped in quotes " ". For example, the City will appear as "New York" in the export CSV.
    When set to No Enclosure, quotes will not wrap the exported string. For example, the City would appear as New York.

Import File Settings

  • File Name - The name of the file to import (only available if Import Based on File Name is selected)
  • File Format - Defaults to CSV
  • File Import Folder - Directory location of the file(s) to import. This value should always start with a /
  • File Action after Processing - Allows you to choose what happens to the file after it is imported:
    1. None: Do nothing after importing the file(s).
    2. Move File - Moves file(s) to specified location after they are imported.
    • File Folder After Processing - Directory location the files will be moved to after processing. This directory must already exist. This value should always start and end with a /
      • Add Timestamp - When set to Yes, a timestamp will be added to the filename after it is moved.
  • Enclosure - When set to Quote ", string values in your import will expect to be wrapped in quotes " ". Meaning that the quotes will get stripped out upon import so the string set is without quotes.
    When set to No Enclosure, no enclosure for your strings will be expected. If quotes wrap the string, they will be set into the value.

Export Using Advanced Filters

Advanced Filters can be used to filter out unneeded data from your export.

📘

Export Filters are only available to File Export and HTTP Export Mapper Types

  • Use Advanced Filters - Yes/No flag to only export Zoey Objects that meet certain criteria. For example, you can specify orders to only be exported based on their status. Only certain Objects are eligible for Advanced Filters.
  • Apply Advanced Filters Only Once:
    1. When set to No, objects will always be exported if they meet the filter conditions.
    2. When set to Yes, objects will only be exported once if they meet the filter conditions (unless manually exported from Preview). This means that once an object has been exported, it will not be exported again even if it meets the conditions of the filter.

      🚧

      After an object has been exported once, or prevented from exporting initially, it will not be included in future exports.

  • Last Run Time - The date/time of the last time the Data Mapper was executed. When Use Advanced Filters is set to No, only Zoey Objects that have been modified or created since this Last Run Time will be exported.

Custom Rows (Export Only)

Add Custom Rows to either the top or bottom of the Zoey Objects being exported.

  • Position - The order in which the custom rows will appear.
  • Is Empty Row - Yes/No flag if the row should be empty and not contain any data.
  • Render Mode:
    1. Once per Exported Object - The custom row will appear in the file once for every exported object.
    2. Render Only Once - The custom row will appear only once regardless of the number of objects exported.
  • Location - Specify if the custom row will appear above or below the exported objects.
  • Add Custom Row Column - Specify the value to be displayed in each column. Can specify Custom Values or use values from the Zoey Object being exported.

Field Mapping

Field Mapping is how individual fields are set to be included in any exported files or HTTPS requests. There is no limit to the number of fields that can be included in the export. For CSV exports, each added field is a column in the CSV file. For HTTPS exports, each field is included in the data sent in the HTTP Request.

  • There are three types of fields that can be exported:
    • Use CSV Column Value - The name of the CSV column will be used to find the data for each row in this column.
    • Use Custom Value - Specify a custom value to be exported in each row.
    • A field associated with the Object being exported - For example, if Order Items are being exported, then all fields available on the Order Item are available, such as Row Total, Quantity Ordered, and Product SKU. Exported Objects also have access to all fields of an associated related Object. Related fields are identified with format [Related Object] Field Name (field_name)
      • Order Items can reference order fields by searching for fields like [Order] Increment ID (increment_id) or [Order] Created At (created_at)
      • These options will be populated into the Zoey Value drop-down menu

Exporting Orders Manually using a Data Mapper

You can export the file configured in your Data Mapper at any time for any selected orders. To do this, go to your Orders Grid. From there you can select each order that will be included in the export file. Then open the Bulk Actions drop-down, and click Data Mapper Templates.

Orders to Export - Within the Data Mapper Export pull-out menu, you can see which orders were selected for export and add more by typing in their Order #.

Data Mapper - If you have multiple Data Mappers, you will be able to choose between them. The one you use will be the new default selection.

Export Type - You can choose Direct Download to immediately download the file. Or Send Email to specify who this file should be sent to. Other established Connections will also be available for selection.

Mapper Templates for your Workflow

👍

We have some Data Mapper Templates you can use for common import/export practices.

Find those Data Mapper Templates here.

Workflow Example with Data Mappers

Check out the graphic below to see how Zoey with Data Mappers can be used to automate your business!

Updated about 2 months ago