Importing points - the two methods
Importing points by file in the new points system works differently depending on whether the Engage tenant is being configured for the first time, or if the Engage tenant is already up and running.
Caution
The folders where the files are placed have similar names, which are not totally clear, so take care to put them in right place depending on which of the two cases you are doing.
Each import is done by running a different scheduled job.
There is a difference in how contacts are identified in the two imports.
The initial setup import will allow you to choose from a range of key types and keys (for example “memberNumber”), while in the ongoing points import you'll need to use the internal contact ID.
Case 1 - When setting up the tenant
Your CSV or XML file, formatted in the correct way, should be placed in this FTP folder:
integration\pointTransactionImport
The job to run is ImportHistoricalPointsFromFileJob. It will validate, read and import historical point files and store them in database. See more here.
An example file:
Key;KeyType;PointDefinitionId;Amount;TransactionType;TransactionDate;CreatedOn;ValidTo;CreatedBy;Description;Source ABC123;MemberNumber;1;100;Purchase;2023-01-01T08:14:00.829Z;2023-01-01T08:14:00.829Z;2024-01-01T08:14:00.829Z;test@voyado.com;Test description;Test source ABC123;MemberNumber;1;100;Purchase;2023-02-01T08:14:00.829Z;2023-02-01T08:14:00.829Z;2024-02-01T08:14:00.829Z;test@voyado.com;Test description1;Test source1 ABC123;MemberNumber;1;-100;Return;2023-03-01T08:14:00.829Z;2023-03-01T08:14:00.829Z;2024-03-01T08:14:00.829Z;test@voyado.com;Test description2;Test source2
Caution
For the setting-up case, it's important that no other point calculation are going on at the same time, such as points being added by API or automations. This import must be the only point job that is running. For the second job (see Case 2 below) it's not a problem to have several points calculations going at once.
Case 2 - When the tenant is already active
When the tenant is already active, another job is used. This is a bit slower but more safe and ensures that no data is modified incorrectly.
Your CSV or XML file, formatted in the correct way, should be placed in this FTP folder:
integration\pointTransaction
CSV files should have a maximum of 20 000 rows. Multiple files can be imported in the same run.
The job to run is ImportPointsFromFileJob and this validates, reads and imports the points.
Procedure
Create a file, and add it to the folder specified. Then run the scheduled job mentioned in the information. When the job runs it will handle all files added to the folder.
The import will add points in the same way as points are usually added in the system. To have the correct balance for point accounts after the import, the Update Balance job needs to run.
File structure
Field | Type | Limitations |
|---|---|---|
ContactId | GUID | Must be an existing, not deleted, approved contact of type Member |
Amount | Decimal | Cannot be 0 |
DefinitionId | Integer | Definition must exist in Engage |
TimeStamp | DateTimeOffset, can be NULL, default = UTC Now Offset | |
Source* | String, default is NULL | Should not be empty |
Description | String, can be NULL, default is NULL | Should not be empty |
ValidFrom | DateTimeOffset, can be NULL, default = UTC Now Offset | |
ValidTo | DateTimeOffset, can be NULL, default = UTC Now Offset |
*If points-based member levels are used, and you want to exclude some points, only use the predefined values of Source, which are:
Purchase
Adjustment
BonusBalanceAdjustment
Return
RewardVoucher
UpdateBalance
BonusPromotion
BonusPromotionReturn
Automation
These settings currently only work with predefined legacy fields that can translate to the new predefined ones.
Here is an example file:
ContactId;DefinitionId;Amount;ValidFrom;ValidTo;Description;Source;TimeStamp a20fe4f3-5cca-491f-ba2a-e6f04ff0d4d8;1;100;2023-01-01T08:14:00.829Z;2024-01-01T08:14:00.829Z;Test description;Purchase;2023-01-01T08:14:00.829Z db9b702c-9087-4c22-82a3-f133771a6c5f;1;100;2023-02-01T08:14:00.829Z;2024-02-01T08:14:00.829Z;Test description1;Adjustment;2023-02-01T08:14:00.829Z 1dc891cb-ae93-492e-9d4d-aa985f3d781d;1;-100;2023-03-01T08:14:00.829Z;2024-03-01T08:14:00.829Z;Test description2;Return;2023-03-01T08:14:00.829Z
Validation rules and handled errors
Here are the errors you could get and what they mean.
Type | Reason + result | Error message |
|---|---|---|
Missing Field Exception | Import file does not define all fields used. File will be skipped and the error logged. | PointTransaction file import missing mandatory columns, will skip file: {{FileName}} |
Missing Contact ID | Contact ID not an existing, not-deleted and approved contact of type “Member”. File line will be skipped and the error logged. | Missing contactId: {{contactId}} In data that was not valid: {{notAccepted}} |
Missing Definition ID | Definition ID does not have a corresponding point definition in the database. File line will be skipped and the error logged. | Missing PointDefinitionId: {{definitionIds}} In data that was not valid: {{notAccepted}} |
Source is empty | Source does not have a value. File line will be skipped and the error logged. | Other error message: {{error}} In data that was not valid: {{notAccepted}} |
Description is empty | Description does not have a value. File line will be skipped and the error logged. | Other error message: {{error}} In data that was not valid: {{notAccepted}} |
Amount is 0 | Points value given is zero. No points added, no logs or errors created. | N/A |
Point account is not found or exists more than once. | Point account with the specified definition does not exist, or exists several times. Creation of new account is not working as intended. An exception is created. | N/A |