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 module by typing ‘Imports’ into the search bar of the Modules menu. The page will open to the list of files that have already been uploaded.

The columns represent the following information:

• Created at – date of the imported file upload

• Created by – Backoffice user who uploaded the import file

• Model – the type of data set imported (coupon, coupon pool, event, customer, reward, store, challenge, customer field, customer mapping rule, product, user group)

• Status

  • Uploaded – the import file has been uploaded successfully, but the import settings have not been configured yet

  • Pending – the import file is uploaded successfully, and the import settings are configured, but the import process has not started yet

  • Processing – the import process is in progress

  • Preloaded -the data has already been loaded, and the import of the records will begin shortly

  • Finished – the import process has been finished
    Please note, that the status of the import is still ‘Finished’ if the file has been processed, but some of the records were not imported due to errors described on the Import details page.

  • Failed – the import process has failed
    If the issue persists, please contact the Antavo Service Desk.

  • Active - the import configured with repeated scheduling will trigger an import on the next scheduled time

  • Inactive - the import configured with repeated scheduling will not trigger an import on the next scheduled time

• Filename

• Filesize
  The size of the import file is in bytes.

Open

Creating a new import

Imports can be used to create new or modify pre-existing entities in Antavo. In case 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 (upon a successful match) of the specific entity.

To start 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 on the GUI afterward, to be able to display it on the membership site properly.

• Coupons
  Import coupons to be used as uploaded coupons of rewards, friend referral coupons or coupon pools.
  Coupon imports to coupon pools can also be initiated through the Coupons module, please find further information here.

• 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, make sure to upload them through an aforementioned Coupon import.

• 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, in case you need to insert such values contact the Antavo Service Desk.

• Events
  When creating an event import file, please make sure you always add the customer and action columns that include the ID of the customer and the event in the data rows of the import files respectively.

• Products
  Add new or updated existing products that have been added in the Product Catalog module.

• Stores
  Add new stores or update the existing store that is set up in the Stores module.

• Rewards
  Create new or update existing rewards that are set up in the Reward module.
  Please note, that reward import is executed without including the image of the reward to facilitate imports more effectively. Make sure you upload the reward image(s) on the reward editor interface to be able to display it on the membership site properly.

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

Open

Data Source

In the second step, define the source where Antavo can access the import file. The following options are available:

• Upload – upload the CSV or JSON file in the Filename field by clicking the ‘Choose file’ button
  You have the option to populate the uploadable CSV file based on a template. This file contains all the fields that are listed on the page, including the custom fields of the entity.
  Obtain this by clicking the ‘Download’ button.

• URL
  Insert the URL where the import file is accessible in the ‘Url’ field.

• SFTP or FTPS file transfer protocols
  Define the Host, Port, User, Pass, and Path connection details in the corresponding field. Also, a Cleanup method can be selected to rename or delete the import file after it has been processed.

Fields

Under the next section, you can view the fields that the system expects to be filled depending on the data model, indicating the data type (text, date, select, numeric, etc.) and whether they are mandatory. Both factory and custom fields are importable and added to the list of fields.

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

When importing coupons, please make sure 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.

After you have updated the import file with all the field values, don’t forget to click the ‘Upload’ button at the bottom of the page.

Import setup

In case the upload is successfully processed, you’ll first find a success message at the top of the page, which means you can continue the data import configuration.

Once the import file has been uploaded, the import is added to the list of imports on the Imports page with ‘uploaded’ status. If you don’t want to complete the import configuration right after the upload, you can come back anytime through the 'Setup' button that appears next to the import in the list.

Field Settings

Click the ‘+’ button next to ‘Fields’ to change the headers of your CSV or JSON file to match the name of the field within Antavo. This step is optional.

• From – the column header in your import file

• To – the name of the target field that should be populated by the ‘From’ column values of the import file.
  Please contact the Antavo Service Desk if you need help defining the name of the field.

• Format – the format of the date values in the data column
  The format must be defined by using PHP date format, you can learn more about it here: https://www.php.net/manual/en/datetime.format.php.

• Default – empty values of the file will be filled in 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 Antavo data fields
  Contact the Antavo Service Desk if you need help in adding values that are acceptable to the specific Antavo data field (eg. woman/man values can be mapped in a way that female/male values will be imported into the Antavo gender field).

Scheduling

Scheduling allows running the imports in a specified time or setting them as recurrent based on UTC timezone.

By default, the CSV or JSON files will be imported right away (‘None’ option), however, importing can be scheduled by selecting the ‘On-date’ or ‘Repeated’ values in the dropdown list. Please make sure you enter the date in a valid format; otherwise, the import cannot not be executed.

• On-date
  The import will start on a predefined date and time.
  Use the date and time selector to specify the scheduled time by clicking on the icons in the Date and Time fields or enter the details manually.

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

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

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

  • Monthly
    Select the day(s) of the month and set the time of the day.
    You can use the ‘Last’ value to make sure the import is started on the last day of the month, regardless of the number of days in a given month.

     

Preload

Enabling the preload 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

• 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 use, a semicolon, pipe, or tab as well.

• Enclosure – currently, the double quote is the only option to indicate that a delimiter character is used within a single field value
  Eg. if a comma is used as the delimiter, the value news, entertainment will be processed as two values of two separate data fields (news and entertainment), however, if you use double quotes as “news, entertainment“, it will be processed as the value of one data field.

Module options

• Duplication handling – you can decide how to handle data rows that include entities that Antavo stores in the database already

  • Skip – the data rows of existing entities will be skipped, and the entity will be left unchanged

  • Update – the data rows of existing entities will be processed and the entity will get updated according to the CSV file data

    • Please 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 select 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 select 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 start the import process. Once the import has been started, the settings (except for scheduling settings) are non-modifiable.

Import summary

Once the process has been initiated, the ‘View’ tab is added for monitoring 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.

The example below shows how the header of a reward import would potentially look in the import file without mapping.

When importing events, don’t forget to add the customer and action columns otherwise your import will fail.

Rows

As soon as the headers are ready, add the data values in subsequent rows, each row representing one item to register.

The example below shows the content of the reward import file with the headers and the rewards to import.

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

Import details

After the import has been created, you are automatically navigated to the View tab of the import page to track the status of the import which is visible in the upper right corner. In the ‘Log’ section, you can find the list of errors that may have been encountered during the import process.

The ‘Result’ section gives you the following insights:

• Inserted - number of records that were inserted during the import process

• Uploaded - number of data values that were updated during the import process

• Duplication - number of data values that were already registered in the field

• Errors - number of records that were not processed due to an error indicated in the ‘Log’ section of the page

You can reach the Import details page anytime from the Imports list by clicking the ‘Details’ button of the import.

Downloading import files

There is a possibility to download previously imported files by following these steps:

• Navigate to the Imports module page

• Click the ‘Details’ button in the corresponding row

• Navigate to the View tab that will show you the ‘File info' section on the right-hand side

• Click the name of the import file

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' action button on 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 that you can use when you decide to reactive 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 preload 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 possibly 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, you can find a ‘Download’ button to download the import file.

If you choose the turn on the preload option during import setup, you can browse the preloaded data of each import occurence by clicking the corresponding 'Preloaded data' button.