Imports

Antavo’s Imports module facilitates the configuration of various entities and mass enrollment of customers in the loyalty program by having settings and data fields imported from .csv or JSON files.

Find the configuration page of the Imports functionality by navigating to the Modules menu and searching for the Import module. The page will open to the list of files that have already been uploaded.

The columns represent the following information:

Creating a new import

Imports can be used to create new entity items or modify pre-existing ones in Antavo. If the entity or any of its field values in the input files already exist in the loyalty program, the input file will result in updating the specific entity upon a successful match.

To begin creating a new import, click the Create new import button on the left sidebar.

Data Model

First, select the data model to import and click Next. The available data models are:

• Challenges: Create new or update existing challenges that are set up in the Challenge module. Challenge import is executed without including the image of the challenge to facilitate imports more effectively. Please note that images still need to be added when editing a challenge afterward to ensure it can be displayed properly on the membership site.

• Coupons: Import coupons to be used as uploaded coupons of rewards, friend referral coupons, or coupon pools. Alternatively, coupon imports to coupon pools can also be initiated through the Coupons module.

• Coupon pools: Create or update coupon pools in the Coupons module. If the pool uses a set of uploaded coupons as the source of the coupons, ensure to upload them through the Coupon import feature mentioned earlier.

• Customer fields: Import new customer data attributes.

• Customer Mapping Rules: Create new mapping rules to update customers.

• Customers: Import new loyalty members or mass update customer data, including labels appended by third-party integrations. Please note, that calculated customer data cannot be imported. If you need to insert such values, contact the Antavo Service Desk.

• Events: When creating an event import file, ensure that you always include the customer and action columns, which should contain the ID of the customer and the event in the data rows of the import files respectively.

• Products: Add new products or update existing products added in the Product catalog module.

• Stores: Add new stores or update the existing stores configured in the Stores module.

• Rewards: Create new rewards or update existing rewards configured in the Reward module. Please note that when importing rewards, the process is executed without including the image of the reward to facilitate more efficient imports. Ensure that you upload the reward image(s) through the reward editor interface to properly display them on the membership site.

• User Groups: Add new groups to the User groups module.

Data Source

In the second step, you’ll need to define the source from which Antavo can access the import file. Here are the available options:

• Upload: You can upload the CSV or JSON file directly by selecting the file using the Choose file button in the Filename fields. You can download a template CSV file or JSON file containing all the necessary fields by clicking the name of the corresponding file extension.
  Please note, that the import of child events, like checkout_item, are only supported in JSON format.

• URL: If the import file is accessible via a URL, you can insert the URL into the Url field.

• SFTP or FTPS file transfer protocols: If you're using SFTP or FTPS, you'll need to define the connection details including Host, Port, User, Pass, and Path. Additionally, you can select a Cleanup method to rename or delete the import file after it has been processed.

Fields

If you click the Fields label, you’ll find the attributes that need to be filled based on the selected data model. The list includes the following details for each field: Key (ID), Name, Data Type (e.g., text, date, select, numeric), Required status, Computed status, Possible values (if applicable), and Description (if provided).

Both built-in and custom attributes are importable and will be added to the list of fields.
Use the Only required fields checkbox to display only the essential attributes of the entity that need to be imported.

If you translate the values of text attributes to different languages on applicable module interfaces, then translations should be imported in separate attributes. The name of translation attributes should be constructed from the ID of the parent attribute and the ISO 639-1 code of the specific language. For example, English, Spanish and French translations of the Name attribute should be added to the import file in attributes like name.en, name.es and name.fr.

When importing coupons, ensure that you add the parent column to the import file and populate the rows with the ID of the coupon pool in which the coupons should be imported.

Once you’ve updated the import file with all the necessary attribute values, remember to click the Upload button at the bottom of the page.

Import setup

If the upload is successfully processed, you’ll receive a success message at the top of the page, indicating that you can proceed with the data import configuration.

After uploading the import file, it will be added to the list of imports on the Imports page with uploaded status. If you prefer not to complete the import configuration immediately after the upload, you can return to it anytime using the Setup button that appears next to the import in the list.

Field Settings

Click the + button next to Fields to adjust the headers of your CSV or JSON file to match the attribute names within Antavo. This step is optional.

• From: The column header in your import file.

• To: The name of the target attribute to be populated by the From column values of the import file. Please contact the Antavo Service Desk for assistance in defining the field name.

• Format: The format of the date values in the data column. It must adhere to the PHP date format.

• Default: Empty values in the file will be filled with the default value

• Map values: You can replace the values of the data fields in your import file by mapping the current values with the values to be imported to the corresponding Antavo data fields. Contact the Antavo Service Desk if you need assistance in adding values acceptable to specific Antavo data fields (e.g., mapping woman/man values to female/male for importing into the Antavo gender field).

  

Scheduling

Scheduling allows imports to run at a specified time or be set as recurrent based on the UTC timezone.

By default, CSV or JSON files are imported immediately (None option), but importing can be scheduled by selecting the On-date or Repeated from the dropdown list. Ensure you enter the date in a valid format; otherwise, the import cannot be executed.

• On-date: The import starts at a predefined date and time.
  Use the date and time selector or enter the details manually in the Date and Time fields.

  

• Repeated: Select this option to set the data import to be triggered periodically.

  • Daily:  Set the time of day when the import should start.

    

  • Weekly: Select the day(s) of the week and set the time of day.

    

  • Monthly: Select the day(s) of the month and set the time of day. You can use the Last value to ensure the import starts on the last day of the month, regardless of the number of days in a given month.

    

Queued row processing

Enabling the queued row processing option initiates the pre-processing of imported records before insertion into the database. Preloading accelerates the import procedure and highlights any records that cannot be imported.

File format options

CSV file imports

• Delimiter
  Use the dropdown list to select the value delimiter that is used in the file. The default option is the comma, but you can also choose a semicolon, pipe, or tab.

• Enclosure
  Currently, the double quote is the only option to indicate that a delimiter character is used within a single field value. For example, if a comma is used as the delimiter, the value "news, entertainment" will be processed as a single value in one data field, while wilthout quotes, it would be processed as two separate values

JSON file imports

• Object and value in one row

  When this option is enabled, only JSON files with object key-value pairs on the same row can be imported.

Module options

• Duplication handling
  You can decide how to handle data rows that include entities already stored in the Antavo database.

  • Skip: Data rows of existing entities will be skipped, leaving the entity unchanged.

  • Update: Data rows of existing entities will be processed, and the entity will be updated according to the CSV file data.
    Note that when updating a set of uploaded coupons, only unassigned coupons can be updated.

• Coupon pool
  Use the dropdown list to select the coupon pool previously configured in the Coupons module to which the coupons should be uploaded.

  • You can either select a coupon pool,

  • or choose the Based on the chosen file option if the ID of the coupon pool has been added as a data column in your import file.

• Reward
  This option is only applicable if you upload coupons directly from the reward configuration page instead of using a coupon pool created in the Coupons module. Use the dropdown list to select the coupon type-reward previously configured in the Rewards module to which the coupons should be uploaded.

  • You can either select a reward,

  • or choose the Based on the chosen file option if the ID of the reward has been added as a data column in your import file.

Click Start import to begin the import process. Once the import has started, the settings (except for scheduling settings) are non-modifiable.

Import summary

Once the process has been initiated, the View tab will be added to monitor the results of the import process.

While the Log details the output of the process, the File info summarizes the import file properties.

The Results section shows if the import file was successfully processed and displays the number of:

• Entities that were inserted or updated in the database

• Duplications handled

• Erroneous entries
  If the number of errors is a non-zero value, a red errors label is displayed in the Results section indicating that some of the records were not imported. Please check the Log sections to learn more about why the import failed.

Creating an import file

Header

In the first row of the CSV or JSON file, define the name of the data field as the headers of your data columns. You can use the name of the loyalty target fields, but you can map the fields of the import file with the loyalty fields during the import setup, through the Field Settings section.

Here is an example of how the header of a reward import appears in the import file without mapping.

When importing events, ensure that you include both the customer and action columns otherwise the import process will fail.

Rows

After preparing the headers, add the data values in subsequent rows, with each row representing one item to register.

Here is an example of the content of the reward import file, including the headers and the rewards to import.

There’s no limit on the number of items that can be included in an import file.

Import details

After creating the import, you’ll be automatically directed to the View tab of the import page to monitor its status, visible in the upper right corner. In the Log section, you can review any errors encountered during the import process.

The Result section provides the following insights:

• Inserted: Number of records that were added during the import process.

• Uploaded: Number of data values that were modified during the import process.

• Duplication: Number of data values that were already present in the field.

• Errors: Number of records that were not processed due to errors, indicated in the Log section of the page.

You can access the Import details page anytime from the Imports list by clicking the Details button next to the import.

Downloading import files

To download previously imported files, follow these steps:

• Navigate to the Imports module page

• Click the Details button in the corresponding row

• Navigate to the View tab which will display the File info section on the right-hand side

• Click on the name of the import file
  If there is no name, File not available anymore will appear in place of the file name, indicating that the file is no longer accessible in the database.

The file will be downloaded with the same filename and format as it was previously imported.

Inactivate and reactivate repeated imports

You can inactivate repeated scheduled imports anytime by following these steps:

• Click the Set inactive button located in the upper right corner

• Confirm your choice in the dialog that appears.

Once the import is inactivated, the button is replaced by a Set active action button, which you can use when you decide to reactivate the import again.

Change import schedule

The scheduling of previously created scheduled imports can be updated through the Import page by following these steps:

• Navigate to the Imports module page

• Click the Details button in the corresponding row

• Navigate to the Change Schedule tab

• Modify scheduling settings as needed
  Switching between On-date and Repeated schedule types is not possible.

• Click Update to save your changes

Preloaded data

If import queued row processing is enabled, preloaded records are displayed once the import process is initiated and pre-processing is completed.

The following information is displayed for each record:

• Row number: The ordinal number of the row.

• Status: Status of the record import (pending, finished, failed).

• Error: Error occurred during the import process, if any.

• Imported at: Date of the import execution.

By clicking the > icon at the beginning of each row, you can access detailed information about the preloaded record:

• Field name

• Field value

• Field target (the value provided in the To field under Field settings, if any)

Using the search bar on the top, items can be filtered by status and row number.

Logs

A Logs tab is automatically added if the import was created with repeated scheduling. The page lists all the runnings of the configured import with the date of running and the current status which can be:

• Processing: The import process is in progress.

• Success: The import process has finished.

• Failed: The export process has failed. Please contact the Antavo Service Desk for further information if the issue persists.

At the end of each row, there is a button to download the import file.

If you choose the turn on the queued processing option during import setup, you can view the preloaded data of each import occurrence by clicking the corresponding Preloaded data button.