GuidesAPI DocsLatest NewsStatusCreate Support RequestReturn to zoey.com

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

Connections

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
    • 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.
    • 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
    • HTTPS Signature Method: The hashing algorithm used for the HTTPS Signature Hash.
    • Additional HTTPS Headers: Additional Header Names/Values to be sent in the Request
  • 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.

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.

📘

HTTPS Data Mappers

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

Mapper Settings

  • Zoey Object

    The type of object to be either exported or imported by the Data Mapper.

🚧

Zoey Object Note

In order to maintain data integrity for a Data Mapper, the Zoey Object CANNOT be changed after a Zoey Object has been selected and the Data Mapper has been saved.

The following objects are available for use with the Data Mapper

📘

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

Imports are only available for the following Connections: Dropbox, FTP, SFTP, SSH

  • Contacts (formerly Customers)
    • Export
      • CSV File or HTTPS POST with Customizable Fields
  • Invoices
    • Export
      • CSV File or HTTPS POST with Customizable Fields
      • Can be Grouped by Order
  • 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
  • Products
  • Shipments
  • Shipment Items
    • Export
      • CSV File or HTTPS POST with Customizable Fields

  • Type

    • File Export
      • Export Mode: 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.
      • Object Grouping: When Export Mode is "Each Object/Requesr 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.
        • One Per File - Each exported Object is exported in its own file/request
        • 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.
      • 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:
        • Import Based on File Name
        • Import All Directory Files

  • 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:
          • Is Equal To: If the "Condition" value is equal to the value provided the condition will be true.
          • 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.
    • 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
        • None: Do nothing after importing the file(s)
        • Move File: Move imported files to a specified location
          • 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.

  • Export Filters

    This section determines which of the selected Zoey Objects will be exported.

    📘

    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:
      • When set to No, objects will always be exported if they meet the filter conditions.
      • 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.
    • 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:
      • Once per Exported Object: The custom row will appear in the file once for every exported object.
      • 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 columns that can be exported:
    • Use CSV Column Value: The name of the CSV column will be used in each row.
    • Use Custom Value: Specify a value to be used 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)

Mapper Templates

📘

Mapper Templates are predefined templates created by Zoey that will either automatically include certain fields based on the action the template is performing or allow for automating and existing Import/Export tool provided by Zoey.

Orders

  • Order State / Status Update (Export)

🚧

HTTPS Connections Only

The Order Status / Status Update Mapper Template is only available to HTTPS Connection

The Order State / Status Update will automatically send updates for the chosen HTTPS Connection whenever an Order's State or Status is changed. Examples of when an Order's State or Status may change is when an Order is Invoiced or Shipped.

  • The following fields are automatically included in the Order State / Status Export

    📘

    Change the values in the Field Name column to update the field names sent in the Export.

    Additional Order Fields can be added by clicking the Add Field button.

  • Order Number: The Zoey Order Number

  • Old State: The state of the Order before the change occurs.

  • New State: The state of the Order after the change occurs.

  • Old Status: The status of the Order before the change occurs.

  • New Status: The status of the Order after the change occurs.

  • Created At: The Date/Time when the status/state change occurred. This Date/Time will use the time zone of your Zoey Store.

    • The Date/Time format of Created At can be changed after the Data Mapper has been saved.

Update Order Status and Comments (Import)

🚧

Connection Limits:

Update Order Status and Comments is only available to Dropbox, FTP, SFTP, and SSH Connections

The Update Order Status and Comments template will import a CSV file that adds a comment to the specified Order(s) and optionally change the Order status and optionally alert the Contact who created the Order of the comment.

📘

Change the value in the CSV Column field to match the column name to the CSV file being imported.

  • The following fields should be included in the CSV file being imported
    • status: The Status Code for the Order. This value must be the Status Code and not the Status Label. Status Codes can be found under Orders > Order Status Settings in your Zoey Admin. To not change the Status of the Order, use the status_code the Order currently belongs to.
    • comment: The comment to add to the Order
    • order_number: The customer facing Order Number of the Zoey Order
    • notify_customer: Specify if the customer should be notified of the comment. Use values "yes", "y", or "1" (without quotes) to notify the Customer
    • attachment_path (optional): The column name for any attachments to be added to the Order

  • Attachment Settings (Optional)

    Additional Settings if attachments should be added to the Order when the CSV file is imported.
    • Download: When enabled, attachments will be downloaded and processed based on the Mapper Template
    • Folder: Directory location of attachments for import. This value should always start with a /
    • Columns: List of CSV column names that contain attachment paths. One per line.
    • File Action after Processing
      • None: Do nothing with attachments after they are added to the Order
      • Move File: Move the file to a separate directory after they are added to the Order
        • 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 attachment filename after it is moved.

Products

  • Zoey Product Inventory (Export)

    • Mapper Settings

      • Zoey Object = Products
      • Type = File Export
      • Export Mode - All Objects To One File

  • File Settings

    • File Name:
    • Type = File Export
    • Export Mode - All Objects To One File

  • Export Filters

    • Use Advanced Filters: When enabled, specific fields can be set to determine which Zoey objects are exported.
      When disabled, Zoey objects are exported if they were created after the Last Run Time.

    Example for an out of stock inventory report, when set to Yes, Qty Is Equal To, Zero

    • Always Export All Data: When set to Yes, the Data Mapper will export all data. When set to No, the Data Mapper will
      only export data that has changed since the Last Run Time.

  • Field Mapping

  • Zoey Product CSV (Import)

    🚧

    Connection Limits:

    Zoey Product CSV Import is only available to Dropbox, FTP, SFTP, and SSH Connections

    The Zoey Product CSV Import template automates the Zoey Import Products Append tool found within the Zoey Admin under the Import & Export Menu >Import Products in the left vertical navigation bar.

📘

Click here to view the expected CSV Column names for a Zoey Product CSV Import

  • Mapper Settings

    • Remove SKUs not in Zoey: When set to Yes, any rows with SKUs that do not exist in Zoey will be removed from the Product Import CSV. This is useful when only performing product updates (such as inventory quantity) and the imported file contains SKUs that do not exist in Zoey.

  • Image Settings

    Optional settings if Images should be imported and set on the Zoey Products
    • Download: When enabled, images can be downloaded and associated to the Zoey object.
    • Folder: Directory location of images for import. This value should always start with a /
    • Columns: List of column names that contain image paths. One per line.

  • Header Mapping

    Use the Header Mapping tool to map the expected Zoey CSV Column Names to the CSV column names in the CSV file being imported. CSV Column is the column name in your CSV file, and the Zoey Header Column is the expected Zoey Column Name.

  • Group and Tier Prices (One File per Group) (Import)

    🚧

    Connection Limits

    Group and Tier Prices (One File per Group) is only available to Dropbox, FTP, SFTP, and SSH Connections

    The Group and Tier Prices (One File per Group) template will import a CSV file that sets Group and Tier Prices for Zoey Products with a separate CSV file being processed for each Customer Group.

    📘

    Change the value in the CSV Column field to match the column name to the CSV file being imported.

  • The following fields are expected for this mapper template:

    • Product SKU: The SKU of the Zoey Product to assign Group and Tier Prices
    • Customer Group Name: The name of the Customer Group for the Group and Tier Prices
    • Group Price: The Price for the specific Customer Group
    • Quantity Step: How much of each Quantity the Customer must add to their Cart to be eligible for the associated Price Step
    • Price Step: The Tier Price for the Customer if the associated Quantity Step is added to the Cart

    • 📘

      Quantity / Price Step Details

      To define Tier Prices of:

      • $20 for a quantity of 5 or more
      • $10 for a quantity of 10 or more
      • $5 for a quantity of 15 or more

      Configure your CSV file as follows:

      sku,group_name,group_price,qty_step1,qty_step_2,qty_step3,price_step1,price_step_2,price_step3
      mysku,General,50,5,10,15,20,10,5

      Adding {{COUNT}} to the defined CSV column in the screenshot above indicates to the Data Mapper to replace {{COUNT}} with the current qty_step or price_step being processed.

  • Group and Tier Prices (One File for All Groups) (Import)

    🚧

    Connection Limits

    Group and Tier Prices (One File for All Group) is only available to Dropbox, FTP, SFTP, and SSH Connections

    The Group and Tier Prices (One File for All Groups) uses the exact same configuration as Group and Tier Prices (One File per Group) configured above, except all Customer Groups to be imported will be defined in the same file.

Shipments

  • Tracking Number Updates (Export)

    🚧

    HTTPS Connections Only

    Tracking Number Updates is only available to HTTPS Connections

    The Tracking Number Updates template will automatically send updates for the chosen HTTPS Connection whenever a Tracking Number is added to a Zoey Shipment.

    • The following fields are automatically included in the Tracking Number Updates Export

      📘

      Change the values in the Field Name column to update the field names sent in the Export.

      Additional Shipment Fields can be added by clicking the Add Field button.

    • Title: The Carrier Title for the Tracking Number (Ground, AIR, Custom, etc...)

    • Shipment Number: The Customer facing Zoey Shipment Number

    • Carrier Code: Carrier used for the Tracking Number (FedEx, UPS, USPS, Custom, etc...)

    • Tracking Number: The Tracking Number added to the Shipment

    • Created At: The Date/Time when the tracking number was added. This Date/Time will use the time zone of your Zoey Store.

      • The Date/Time format of Created At can be changed after the Data Mapper has been saved.

  • Comment Updates (Export)

    🚧

    HTTPS Connections Only

    Comment Updates is only available to HTTPS Connections

    The Comment Updates template will automatically send updates for the chosen HTTPS Connection whenever a comment that is visible to the Customer who placed the Order is added to a Zoey Shipment.

    • The following fields are automatically included in the Comment Updates Export

      📘

      Change the values in the Field Name column to update the field names sent in the Export.

      Additional Order Fields can be added by clicking the Add Field button.

      • Comment: The comment added to the Shipment
      • Shipment Number: The Customer facing Zoey Shipment Number
      • Created At: The Date/Time when the tracking number was added. This Date/Time will use the time zone of your Zoey Store.
        • The Date/Time format of Created At can be changed after the Data Mapper has been saved.

  • Zoey CSV Shipment Import

    🚧

    Connection Limits

    Zoey CSV Shipment Import is only available to Dropbox, FTP, SFTP, and SSH Connections

    The Zoey CSV Shipment Import template automates the Zoey Shipment Products tool found within the Zoey Admin under the Import & Export Menu >Shipment menu in the left vertical navigation bar.

    BB

    📘

    Click here to view the expected CSV Column names for the Zoey Shipment CSV Import

  • Mapper Settings

    • Auto-Invoice Shipped Items: When set to Yes, the Qty to Ship will also be Invoiced for items in the Shipment CSV. Once all items have been Shipped and Invoiced the Order status will be set to Complete
    • Send Invoice Email for Auto-Invoiced Items: When set to Yes, an Invoice Email will be sent when Items are Auto-Invoiced by the Shipment Import

  • Header Mapping

    Use the Header Mapping tool to map the expected Zoey CSV Column Names to the CSV column names in the CSV file being imported. CSV Column is the column name in your CSV file, and the Zoey Header Column is the expected Zoey Column Name.

Updated about 1 month ago