Recommendation Ingestion

Eagle Eye AIR allows for a list of recommendations to be uploaded, to feed new recommended offers into customers' wallets. To create recommendations in the AIR platform, a file-based ingestion exists which takes an input file and turns those into recommendations.

Ingestion Concepts

Recommendations in the AIR platform live inside a construct called a catalogue. Every file that is ingested creates a new catalogue for data. These catalogues have start and end dates on them allowing different catalogues to become active at different points in time. It is possible to have catalogues which overlap each other if necessary.

Inside each of these catalogues live the recommendations themselves. A recommendation can have a few different data points against them as described in the table below. These data points are also the same data used in the ingestion file.

Field Name	Description	Validations	Examples
reference	A unique reference for this recommendation. If none is provided a unique reference is generated upon ingestion. It is advised to allow the system-generated recommendation to be used.	Alphanumeric, empty is allowed
subject	The target customer for this recommendation. Can use `walletId` or `identity`	Alphanumeric	`walletId:1234` `identity:A123456`
target	The AIR `campaignId` to which this recommendation record is pointing.	Alphanumeric	`campaignId:456789`
validFrom	The start date for this recommendation. Validity dates can be specified at both the catalogue level and the recommendation level. The catalogue dates are hard limits and the recommendation level dates can be flexible. Dates must be formatted in ATOM format	Date in the format: YYYY-MM-DDTHH:MM:SS+XX:XX	`2023-05-03T00:00:00+00:00`
validTo	Similar to the validFrom field recommendations can have an end date set on them directly.	Date in the format: YYYY-MM-DDTHH:MM:SS+XX:XX	`2023-06-02T23:59:59+00:00`
weight	The weight column allows recommendations to be ordered. The recommendation with the lowest weight value will appear at the top of the list and the ones with the highest value at the bottom.	Integers with a max value of 999999999	1
channel	Channels allow recommendations to be separated into different use cases. For example, you may wish to have a set of recommendations for Message At Till and another set for your mobile App. It's possible to specify multiple channels for the same recommendation. To do this, we need to separate the values with a pipe character `\|`. Values should be alphanumeric and not contain spaces.	Alphanumeric with no spaces. Can contain `-`or `_`characters.	`MESSAGEATTILL`-`APP` `MESSAGEATTILL\\|APP`
meta	The meta field holds metadata about the recommendation itself. This data exists only on the recommendation and does not move anywhere else.	Single level JSON Object with simple key/value pairs.	`{""key1"":""value1""}`
data	The values in the data field form the payload used to create the account when accepting a recommendation. For example account start/end dates, overrides, account metadata etc. Most data points in this field can be configured as defaults on the campaign. Because of this the field can remain empty `{}`	JSON Data. Values entered here must align with a coupon creation payload as defined here	`{""state"":""LOADED""}`

File Encoding

All files must be encoded with linux line endings rather than Windows

Field Encapsulation and Escaping

The data and meta fields are JSON-encoded fields and therefore need to be encapsulated inside double quotes. It is advised to wrap all fields in double-quotes. Because of this, the double quotes inside the field need to be escaped themselves. This can be done by adding a \ or second " character before the " character.

An example of this is shown in the sample file below.

File Naming

The file name is very important for this ingestion as it has data points embedded within the file name. The below format creates the structure of the file name:

{uniqueness}-{Service}-{validFrom}-{validTo}.csv

The fields are explained in the table below:

Field	Description	Example
`uniqueness`	This value can be alphanumeric as well as including the `_` character. This can be set to meet the requirements of the client. A good suggestion is to use the date/time that the file was created.	`20230503160400`
`service`	Currently, the only service supported is `PROMOTE`	`PROMOTE`
`validFrom`	This date determines the start date (in UTC time) for the catalogue itself. If you work in different time zones, it's important to set this date to the appropriate UTC time. The format of the date must be in the format: `YYYYMMDDHHMMSS`	`20230501000000`
`validTo`	This date determines the end date (in UTC time) for the catalogue itself. If you work in different time zones, it's important to set this date to the appropriate UTC time. The format of the date must be in the format: `YYYYMMDDHHMMSS`	`20230531235959`

An example file name would be: EAGLEEYE_20230503000000-PROMOTE-20230501000000-20230531235959.csv

Example File:

reference,subject,target,validFrom,validTo,weight,channel,meta,data
,identity:A0000000010037,campaignId:791899,2023-05-01T00:00:00+00:00,2023-05-31T23:59:59+00:00,1,APP|MESSAGEATTILL,"{}","{}"
,identity:A0000005247445,campaignId:791899,2023-05-01T00:00:00+00:00,2023-05-31T23:59:59+00:00,2,APP|MESSAGEATTILL,"{}","{}"
,identity:A0000000001715,campaignId:791899,2023-05-01T00:00:00+00:00,2023-05-31T23:59:59+00:00,3,APP|MESSAGEATTILL,"{}","{}"
,identity:A0000005247440,campaignId:791899,2023-05-01T00:00:00+00:00,2023-05-31T23:59:59+00:00,4,APP|MESSAGEATTILL,"{}","{}"

SFTP Folder setup

Recommendation files need to be dropped to an SFTP location. The locations in the SFTP need to be as below:

/recommendations/inbound/
/recommendations/outbound/
/recommendations/processed/
/recommendations/error/

The input file needs to be placed in the inbound directory. Once dropped the files are picked up within a few seconds and the ingestion of the data will begin.