Store Ingestion

Introduction

Eagle Eye AIR allows for a list of retail outlets to be uploaded automatically as a
one-off process during the on-boarding process, or done on a continual basis, to
ensure outlet information within the platform is kept up to-date.

Store Structure

Every entity within the AIR platform that represents an outlet or a company entity
is known as a ‘Unit’. The most common type of Units are ‘Company’ and ‘Outlet’. A
company outlet represents a trading entity, and an outlet is used to represent a
store. A store can be a physical location, or an online location.

All Unit entities within the platform can have related Units, and this is used to
build a hierarchy of companies and outlets. Relations can be either parent or children
when operating with outlets.

Basic Structure

The basic structure shows a parent company of ‘Fresh Coffee Co’ and this company has
three children outlets. There is no limit to the number of outlets that can be placed
under a parent Unit.

With this type of structure, the outlet ingestion file is loaded against the
‘Fresh Coffee Co’ company, and the system automatically creates, updates and removes
outlets that belong to this company.

Advanced Structure

The advanced structure shows a parent company acting as a holding company, and this
company having a number of child companies. The outlets within this organisation
are all owned by the companies in the second level of this hierarchy

With this type of structure, the outlet ingestion can be completed in one of two ways:

One file is supplied containing each outlet within the group as a single row,
and each outlet row references the parent company that the outlet belongs to
One file is supplied for each sub-company, containing only the outlets that
belong to that company. In the example above this would mean two files are produced
and ingested into the AIR platform

Alternative Structures

If your corporate structure doesn't match the two examples above your professional
services team will work with you to build a structure that is the most compatible
with Eagle Eye standard ingestion and meet the required use cases.

Outlet Attributes

The AIR platform allows for the following attributes to be added to an outlet

External Reference: The external reference can be used to easily identify a
Unit in the dashboard. This field can be populated with a value or friendly name
easily recognisable to a Dashboard user, allowing them to easily search for and
select the Outlet they need
Name: The name of the outlet that is stored and used in reporting and outlet
picker lists. Make this name as clear as possible
Status: Outlets within the platform have the following statuses: ACTIVE,
INACTIVE or DELETED. It is possible to search for Active and Inactive outlets
in all areas of the Dashboard including reporting filters, exports and within the
Unit management area. Only Active outlets will display in the Store Picker within
Campaign creation. Deleted outlets cannot be searched for or viewed in the Dashboard.
These outlets will not appear in reports or exports and cannot be transacted against.
Address & Phone Fields: Outlet address and phone fields are stored for
reference only and are not used for any processing within the platform.
Incoming Identifier: This is the value that is passed in from any POS system
through our API’s. This number must be unique to the parent company. If your POS
systems authenticate at a higher level than the parent of the outlet, this value
must be unique from that higher level and below. Once set, this value cannot be
changed.
Outgoing Identifier: This value is the reference that you would like to appear
on any reporting or references to this outlet within the dashboard. This field is
useful if your POS vendor uses a different reference for the outlet than you do in
your reporting or audit processes. If this field is not provided, it is defaulted to
the Incoming Identifier.
Tags: Each outlet can be tagged to make searching and reporting easier.

Initial Setup

Before any ingestion is completed an initial setup of company Units is required
within the AIR dashboard. Each company within the structure should be created,
starting from the top of the structure and working down, adding ‘children’ companies
to the parent above it. Each company that is set up should be given a unique
reference as Incoming Identifier when setup in the dashboard. This reference must
be unique within your whole hierarchy including avoiding clashes with any outlet
references.
TIP:THE VALUE SUPPLIED AS AN INCOMING IDENTIFIER FOR THE COMPANY MAY BE
REQUIRED IN THE OUTLET INGESTION FILE

Outlet File

Once the initial setup has been completed the AIR platform will be ready to accept
outlet files in the format that is defined within this section.

Some of the details below will vary depending on the if you require a basic or
advanced structure to be represented within the AIR platform.

Delivery

The outlet file should be uploaded to your Eagle Eye SFTP account with a CSV file
extension. The file should initially be uploaded with a .csv.tmp extension during
upload. Once successfully uploaded the .tmp extension should be removed.
This prevents the system from ingesting a file that is partially uploaded.

The file (or files) should be placed in the relevant directory of your SFTP login.
The file will be picked up and processed from this location and placed into the
processed directory.

Where multiple files are being used, one file should be placed in the incoming
directory of every relevant parent company.

Status Interpretation

The processing of each outlet record in the file depends on the status of the
outlet:

ACTIVE: When a status of ACTIVE is provided, any store that has previously been
set to INACTIVE or DELETED will be reinstated and have its status set to ACTIVE.
If an outlet does not yet exist, a new Unit with a status of ACTIVE will be created.
INACTIVE: When a status of INACTIVE is provided and an Active outlet with the
corresponding Incoming Identifier already exists, it will be Inactivated. If this
store does not yet exist in the platform, a new one will be created with a status
of INACTIVE.
DELETED: When a status of DELETED is provided, the outlet will be deleted from
the platform.

Note:a full store list is expected on each ingestion; this is not a delta ingestion.
As such any active store in AIR that is absent from the file will be inactivated.

File Format

Column	Column Required	Allow Empty	Type	Description
parentIdentifier	N	N	String	The incomingIdentifier of the company that owns this outlet. This cannot contain special characters including spaces.
externalReference	N	Y	String	A reference to this outlet that is stored within the AIR platform. This cannot contain special characters including spaces.
unitName	Y	N	String	The name of the outlet
status	Y	N	String	This should be set to `ACTIVE`, `INACTIVE` or `DELETED`
address1	Y	Y	String	The first line of the address
address2	Y	Y	String	The second line of the address
address3	Y	Y	String	The third line of the address
country	Y	Y	String	The country the outlet is located in
postcode	Y	Y	String	The postcode for the outlet
phone	Y	Y	String	The phone nmber for the outlet
incomingIdentifier	Y	N	String	The incoming identifier of the outlet. See ‘Outlet Attributes’ for more information. This cannot contain special characters including spaces.
outgoingIdentifier	Y	Y	String	The outgoing identifier of the outlet. See ‘Outlet Attributes’ for more information. This cannot contain special characters including spaces.
tags	Y	Y	String	A pipe delimited list of tags to apply to this outlet

Note: The parent identifier is required if you have a three level unit hierarchy and are supplying one file for all outlets within the hierarchy.

File Specification

The outlet file should be provided as a CSV file, with the specification below
adhered to.

Content Encoding

EES AIR can import data files encoded withUTF-8 encoding. If for any reason file
contains non-UTF-8 or forbidden character the whole row will not be imported.
ASCII is a subset of UTF-8 encoding.

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

CSV Structure

We require CSV files to have a list of field names as file header (very first line
of the file). All other records (lines) should contain the data to be imported.
Data files may include additional columns (with empty or non-empty values), and we
will ignore them during import. For each supported import mechanism, mandatory
columns have to be present in the file to start ingestion process.

Field Delimiter

We require comma sign (, or U+002C) as CSV Field Delimiter by default. We require
a double quote sign (" or U+0022) as CSV Text Delimiter by default. We recommend
you use CSV Text Delimiter for all fields values, not just for string fields.

Data Escaping

For outlet files, we allow the use of special characters (double quotes, slash,
backslash, apostrophe, comma, etc.) as long as they are specially prepared.

a quotation mark (" or U+0022) should be represented by a pair of consecutive double quotes or prefixed with backslash sign in the CSV content.
other allowed special characters should be prefixed using backslash symbol (\or U+005C).
additional whitespace outside field values may corrupt CSV file; hence we will not be able to read and process it.

Forbidden Characters

We will not be able to process rows containing special, non-visual characters in
field values, examples include:

NUL (\0 or U+0000)
TAB (\t or U+0009)
LINE FEED (\f or U+000A)
NEWLINE (\n or U+005F)
CARRIAGE RETURN (\r or U+000D)

Warning – these characters maybe added by your CSV editor when compiling a list
of stores

File Name

Uploaded file name pattern is configurable and only files that match the agreed
pattern in the relevant SFTP folders will be processed.

Although configurable, Eagle Eye suggest a file name pattern as below:

outletIngestion-<dateGenerated>.csv

dateGenerated should be in the format YYYYMMDDHHMMSS