Skip to main content

Voyado Engage

Import points history

To get your points data into Engage, you will need to migrate it. This migration is done by importing the points history, row by row, in a CSV or XML file.

If you want to keep track of the entire points history for each of your contacts, this import allows you to do that. You can also choose to just import the current balance for a contact as a single row, without the history. Both negative and positive points values can be migrated in this way.

For a successful import:

  • Do not exceed 20,000 rows in your CSV file (or pointtransaction nodes in your XML) - split into several files if needed

  • Be sure to include all the mandatory fields listed on the table below

  • If using a CSV make sure it's UTF-8 encoded and with semicolon separated values

  • As the transactionType value, use only "purchase", "return", "adjustment" or "rewardvoucher"

  • As the keyType value, use only "memberNumber", "externalId" or "contactId"

Warning

Do not mix different keyType values in the same file as the importer takes the first one it finds and then uses that keyType for all the subsequent rows in the import file.

Structure of the import file

This is what each row in your CSV or each pointtransaction node in your XML should contain.

Name

Description

*key

The contact identification string (this can’t be empty).

*keyType

What key represents, which can be either "memberNumber", "externalId", or "contactId".

*transactionType

This must be either "purchase", "return", "adjustment" or "rewardvoucher".

*transactionDate

The timestamp of the points transaction. Must be in UTC DateTime. Replaces the older "createdOn".

*pointDefinitionId

A positive value in the PointDefinition database table. The default is 1. A value that doesn't exist in the PointDefinition table will cause a validation error.

*amount

The number of points added (positive) or removed (negative).

description

Optional string

validTo

Optional string

createdBy

Optional string

source

Optional string

Mandatory fields are marked with *. The other fields are optional but recommended.

Note

The names in the column "Name" can start with a lower-case or upper-case letter.

Example of values

key

keyType

pointDefinitionId

transactionType

amount

transactionDate

description

1567

memberNumber

1

purchase

100

2021-08-21T08:16:59+02:00

Trousers

1839

memberNumber

1

purchase

100

2022-10-17T20:36:26+02:00

Hat

1544

memberNumber

2

return

-100

2021-12-23T14:05:25+01:00

Gloves

1356

memberNumber

2

purchase

100

2022-03-02T00:47:20+01:00

Pauldrons

1644

memberNumber

2

rewardvoucher

-100

2021-05-21T11:17:54+02:00

Converted to voucher

1567

memberNumber

2

rewardvoucher

-100

2021-11-24T01:04:38+01:00

Converted to voucher

2135

memberNumber

1

purchase

4210

2022-01-01 00:00:00:000

Accumulated points

Note that for the contact with key of 2135, all their points are imported as one entry, without history.

You can download an example CSV and XML file on the example files page.

Caution

Keep your CSV to 20,000 rows or less, and your XML to 20,000 pointtransaction nodes or less.

Importing the file

Your CSV or XML file / files must now be placed on your FTP inside a folder named Integration/PointTransactionImport

The actual processing of your files must be manually triggered by your Voyado Engage team.

The result of the integration, including the validation check, will be shown in the integration log as type Data migration.

File validation

Each file is validated before it is processed. If any error is found during the validation of a file, it will be logged in the integration log and the whole file will be skipped. This is a safety feature since unique IDs are not used for the rows inside the files. Validation will then continue with the next file.

The following validations are applied to all mandatory fields in your files:

  • All returns must have a negative value

  • All purchases must have a positive value

  • The amount value must be a number, either integer or decimal

  • If even a single contact in a file can't be found in the contact database, that file fails validation

  • The PointDefinitionId value has to be a positive integer value and must exist in the "PointDefinitionId" database table

  • The transactionDate value must be a valid UTC datetime value

  • The transactionType value must be either "purchase", "return", "adjustment" or "rewardvoucher"

Performing the import

After your files pass the validation, they will be imported to a blob storage and remain there until all files in the batch are imported.

The system will then read the files from blob storage and start importing all rows to the database.

When that is done the system will update PointAmountLeft for all your contacts so that the value matches the newly imported data.