Backend Points

There is often a need to adjust the balances of a set of customer's points accounts in bulk. This may be due to a reward calculated outside of AIR or as a part of the loyalty scheme where points are allocated at the end of a period when a customer has met a given set of criteria.

To achieve this, AIR has a file-based ingestion built to allow a CSV file to be delivered and AIR ingests that file, awarding the points to the customer.

File Format

The below table outlines the file structure required for this process/

Wallet Transaction Reference

If no reference value is provided in the file the below formatting is used for the wallet transaction reference that is automatically calculated by AIR.

<prefix><hash of the requesturl and payload>

The prefix is either eesbep (EagleEye Solutions Backend Points) if a walletId is provided or eesbepi (Eagle Eye Solutions BackEnd Points Identity) if an identity value is provided.

This format of reference allows a degree of duplicate processing protection as if the same row in the file is provided more than once, the second instance will fail.

File Encoding

All files must be encoded with Linux line endings rather than Windows.

Field Encapsulation and Escaping

It is advised to wrap all fields in double quotes to avoid any issues with commas inside fields (E.g. the transaction description field). Because of this, if you want to use any double quotes inside the fields, they need to be escaped themselves. This can be done by adding a \ character before the " character.

File Naming

There is no restriction on the file name setup for this job other than a file extension of .csv. It is advised however to include some data points in the file name for easy identification and troubleshooting. For example, a file name structure similar to this is recommended: YYYYMMDDHHMMSS_points_adjustment.csv

This format will mean files are ordered in date/time order when listed in an SFTP client, it's clear the file is a points adjustment file. An element of random could be added to the file name if required.

Record Ordering

The ingestion process takes advantage of the caching of records. As such the job is faster and more efficient if the input file is sorted by the walletId or identityValue columns. For example, all the adjustments for a wallet with an ID of 1234 should be placed together in the file.

Example File

The below example shows a very simple file specifying the mandatory fields and one of the optional fields.

walletId,identiyValue,pointsValue,schemeId,schemeReference,storeId,parentStoreId,reasonCode,walletTransactionType,walletTransactionState,walletTransactionDescription,walletTransactionReference,walletTransactionDate,walletTransactionMeta,accountTransactionMeta
"1234",,"1000","4321",,,,,"CHALLENGE_REWARD",,,,,,
"2345",,"1000","4321",,,,,"CHALLENGE_REWARD",,,,,,

Items to note in this file

It's possible to have some rows using walletId and some using identityValue. It's advised to be consistent however and only use one. The same is true for schemeId and schemeReference.

All fields are encapsulated in " characters

All the column headers are included in the file even though several of them are empty values.

The order of the columns is important and matters to the ingestion process.

SFTP Folder Setup

Your Eagle Eye onboarding team will get the sftp folders set up for you during the onboarding process. The folders created for this job will be as below:

• /backend-points/outbound/
• /backend-points/inbound/
• /backend-points/processed/
• /backend-points/error/

To ingest a file, it needs to be placed in the inbound folder. The first thing the job does is move this file into the processed directory before downloading the file. This is to prevent any duplicate processing or race conditions as the same file name can not be processed more than once.

When the job is completed, an output file will be placed in the outbound directory. This file contains all the same fields as the input file but with three extra columns, a success field (Y/N), an errorCode field holding the errorCode returned from the API request and errorMessage that holds the error message from the API. If there is any error in ingesting a single record, the success column will have a value of N and the errorCode and errorMessage columns will contain the details of why the record has failed.

Example output file

walletId,identiyValue,pointsValue,schemeId,schemeReference,storeId,parentStoreId,reasonCode,walletTransactionType,walletTransactionState,walletTransactionDescription,walletTransactionReference,walletTransactionDate,walletTransactionMeta,accountTransactionMeta,success,errorCode,errorMessage
"1234",,"1000","4321",,,,,"CHALLENGE_REWARD",,,,,,Y,,
"2345",,"1000","4321",,,,,"CHALLENGE_REWARD",,,,,,N,NF,"Wallet Not Found"

Ingestion Speed and Timing

As the AIR platform is multi-tenanted, your onboarding team will work with you to find a time at which the file processing can be run uninterrupted and complete the job at a time of day to meet your business needs.

This ingestion process is built for scale. We can handle files with hundreds of millions of records in them. It's worth noting that the larger the file the longer the job will take to complete.