Envizi Config Connector Design

File Processing and Validation

File Recognition
Connectors validate incoming files by analyzing the file name, file
extension and column headings. No validation occurring in this
connector is case sensitive.

File Name and Tab Name

A file must match the following criteria in order to be processed
and loaded by this connector:
• File name = Envizi_SetupConfigXXXX
o XXXX = any character(s) (including spaces)
o File type = xls or xlsx
o Tab Name = Setup
o A typical valid file name could look like
"Envizi_SetupConfig_DemoCorp Locations_1.xlsx"

If any of the above criteria is not met, an error will occur and
the file will not be loaded.
Connector Introduction

Connector Introduction
An Envizi data connector is a program that has been written in order
to extract specific data points from a text-based file. The connector is
written based on the data file provided [Appendix 1] by you or your
supplier, and the documentation following provides details on the
logic used. Connectors validate incoming files by analyzing the file
name, file extension and column headings in the file.

The Connector Function

• Create and update locations (addresses, lat/long values &
location closed dates)
• Trigger the Location Region to be updated based on provided
data
• Create grouping structure (up to 3 levels) either portfolio or
classification Set and move location group memberships
within the structure above
 • No internal IDs are present in the file. All updates and location
validation occur using Location reference first and then
Location Name

The connector reads a maximum of 17 columns spanning columns A

through Q.

File Loading
Files can be loaded by using the upload function in Envizi under the
menu "Manage" > "Upload Files".
The data processing results are available within Envizi under the
menu "Manage" > "Files Processed - Accounts & Setup".
If a connector fails due to a critical error such as the filename being
incorrect, organization name not matching, then the file will not
appear on the ‘Files processed’ page above.

The connector will search within the file to match on the following
headings in the columns identified below:

Column and Column and Heading

Heading
A ORGANIZATION
B GROUP TYPE
C GROUP HIERARCHY NAME
D GROUP NAME 1
E GROUP NAME2
F GROUP NAME 3
G LOCATION
H LOCATION REFERENCE
I LOCATION REF NO
J STREET ADDRESS
K CITY
L STATE PROVINCE
M POSTAL CODE
N COUNTRY
O LATITUDE Y
P LONGITUDE X
Q LOCATION CLOSE DATE

D If the column headings are not matched exactly as stated

above, the file will not be loaded.
Data Rows

Once incoming files have passed all the validation criteria above,
each row of data is checked to see whether it is valid for loading into
Envizi.
The connector identifies data rows as follows:
File Sorting
• No sorting is applied
Rows Skipped
• Any blank rows will be automatically skipped
Rows Read
• All other rows will be considered data rows to be loaded

If the row is not identified as a data or skip row, then it will be

returned as an error.
Monthly Target Data – navigates to a browse grid showing the target

Data Field Mappings

Once a data row is identified, data row handlers determine what

happens with the data and where it is stored in Envizi.

Organization

Envizi Source File Column and Name Notes and

Column Assumptions
Organization A Organization
Name

The following is broken up into the various configuration areas

including

• Group
• Location
• Address
• Region
• Latitude / Longitude
• Location
• Closed Date
• Location to Group Memberships
 Group Configuration

FUNCTION
• Create a group structure up to 3 levels deep using Columns D,
E & F.
• Groupname 3 is the lowest level in the hierarchy where the
location is a member.
• Parent child relationships will be established between the
groups to ensure nesting as in example below.
• Without group IDs in the file, the group description is used to
set a primary key to ensure no duplication of created groups
and the correct group memberships can be established if the
same group names are used across various group structures.

Example GROUPNAME1 GROUPNAME2 GROUPNAME3 Envizi Grouping RESULT

1 tier Location list • Location List (group)
structure o Locations
2 tier Australia New South Wales • Australia (group)
structure o New South Wales (group)
o Locations
3 tier Asia Pacific Australia New South Wales • Asia Pacific (group)
structure o Australia (group)
▪ New South Wales (group)
• Locations
No groups N/A - No group created
defined

PRE-CONDITION
• To create a new group there must be no existing group with
the same group description (See table below for derivation).

ERRORS
The row will error and no further actions will be performed if the
following conditions are met
• If group name value exceeds 50 characters
• If group description value exceeds 250 characters
 DATA FIELD MAPPING

Envizi Column Source File Column and Data Notes and Assumptions
(Internal Use Name (Location of Data in Format
Only) File)
Group Type B GROUP TYPE String Supported Values
To represent the classification group
structure
• Classification
• Primary
To represent the portfolio group structure
• Portfolio
• Secondary
Group D GROUP NAME 1 String
Group E GROUP NAME 2 String
Group F GROUP NAME 3 String
Group C GROUP String The group path provides a unique identifier
Description HIERARCHY for the group and it's position in the group
NAME path by only including the group parents up
A GROUP NAME 1 to the relevant entity.
B GROUP NAME 2
C GROUP NAME 3 The group description will be set using the
following convention

GROUPNAME1 Group Description =

'GROUP HIERACHY
NAME'_'GROUPNAME1'>
GROUPNAME2 Group Description =
'GROUP HIERACHY
NAME'_'GROUPNAME1'>'GROUPNAME2'>
GROUPNAME3 Group Description =
'GROUP HIERACHY
NAME'_'GROUPNAME1'>'GROUPNAME2'>'
GROUPNAME3'>

Manually overwriting the group path in the

interface will result in duplicate groups
being created by this process.
 Location Configuration

FUNCTION
• Create a new location
• Update an existing location

PRE-CONDITION
• To create a new location, an existing location must not exist
o Column H 'Location Reference' does not match the
Location Reference field of an existing Envizi location
AND Column G 'Location' does not match the Location
field of an existing Envizi location.
• To update an existing location,
o Column H 'Location Reference' does match the Location
Reference field of an existing Envizi location
o Column H 'Location Reference' does not match the
Location Reference field of an existing Envizi location
AND Column G 'Location' does match the Location field
of an existing Envizi location

ERRORS
• The row will error and no further actions will be performed if
the following conditions are met
o If the location name is NULL (empty)
o If the location name exceeds 100 characters
o If Location Ref No or Location Reference exceeds 50
characters

DATA FIELD MAPPING

Envizi Column Source File Column and Data Notes and Assumptions
(Internal Use Only) Name (Location of Data Format
in File)
Location Type N/A N/A String Default to ‘Other’
Location Name G LOCATION String
Location Reference H LOCATION String Location Reference is only set
REFERENCE upon Location create as it's a
primary field used for location
identification. It will not be
updated when matching on an
existing location by location
name.
Location Ref No I LOCATION REF String
NO

Address Configuration

FUNCTION
• Create an address for a location as it's created.
• For existing locations,
o If no address exists with Address Type 'Physical', create
an address.
o If an address exists with Address Type 'Physical',
update the address fields below. In the case the
multiple physical addresses exist only the most recent
address will be updated.

PRE-CONDITION
• To update an address for an existing location, a location must
exist
o An existing address exists with Address Type 'Physical'
AND
o Column H 'Location Reference' must match the
Location Reference field of an existing Envizi location
OR
o Column G 'Location' must match the Location field of an
existing Envizi location

ERRORS
• The row will error and no further actions will be performed if
the following fields exceed 50 characters
o City
o State
o Postal Code
o Region
• The row will error and no further actions will be performed if
Address exceeds 255 characters
 DATA FIELD MAPPING

Envizi Column and Source File Column and Data Notes and Assumptions
Name (Internal Name (Location of Data Format
Use Only) in File)
Address Type N/A N/A String Default to ‘Physical’
Address J STREET String
ADDRESS
City K CITY String
State L STATE String
PROVINCE
Postal Code M POSTAL CODE String
Country Region N COUNTRY String

Region Configuration

FUNCTION
• Set the location region at the most granular level matching
Envizi pre-defined region fields. This uses a combination of
latitude and longitude values and the Country of the address.
For United States, if postcode regions exist these will be used
first, otherwise suburb/state/city will be selected.
• Region is used for determining appropriate location-based
energy and emission factors.
o If latitude and longitude are provided, they will be used
to determine the most granular region in Envizi to
ensure accurate reporting.
o If latitude and longitude are not provided, the Country
will be used to attempt to match the predefined list of
regions in Envizi.
o If no match can be found, the region will be set to earth
as a default region to fall back on to ensure some
generic factors are still applied.

PRE-CONDITION
Latitude and Longitude values have been provided

ERRORS
N/A
 DATA FIELD MAPPING

Envizi Column and Source File Column and Data Notes and Assumptions
Name (Internal Name (Location of Data Format
Use Only) in File)
Country Region N COUNTRY String
Latitude O LATITUDE Y Decimal
Longitude Y LONGITUDE X Decimal

Latitude and Longitude Configuration

FUNCTION
• Set latitude and longitude (Location Setting) for a new location
• Update latitude and longitude (Location Setting) for an existing
location

PRE-CONDITION
• To update an existing location,
o Column H 'Location Reference' must match the
Location Reference field of an existing Envizi location
OR Column G 'Location' must match the Location field
of an existing Envizi location
o Latitude and/or longitude values must already exist

ERRORS
• N/A

DATA FIELD MAPPING

Envizi Column and Source File Column and Data Notes and Assumptions
Name (Internal Name (Location of Data Format
Use Only) in File)
Latitude O LATITUDE Y Decimal
Longitude P LONGITUDE X Decimal
 Closed Date Configuration

FUNCTION
• Set closed date (Location Setting) for a new location
• Update closed date (Location Setting) for an existing location

PRE-CONDITION
• To update an existing location,
o Column H 'Location Reference' must match the
Location Reference field of an existing Envizi location
OR
o Column G 'Location' must match the Location field of an
existing Envizi location

ERRORS
• If the date specified is not in the required format, the row will
error and the closed date will not be set.

DATA FIELD MAPPING

Envizi Column and Source File Column and Data Notes and Assumptions
Name (Internal Name (Location of Data Format
Use Only) in File)
Location Closed Q LOCATION Supported date formats
Date CLOSED DATE • YYYY-MM-DD
For example, 2023-12-30

Location to Group Memberships Configuration

FUNCTION
• Create location to group memberships to the nominated group
structure.
• If the location is already a member of the nominated group
structure this membership will be updated to reflect the
incoming data (essentially moving the location from one group
to another group within the same group structure)
 PRE-CONDITION
• To create a new group membership
o Location and group values have been provided in the
incoming file and there is no pre-existing group
membership to the nominated Group structure.
• To update an existing membership
o Location and group values have been provided in the
incoming file and there is a pre-existing group
membership to the nominated Group structure.

ERRORS
N/A

DATA FIELD MAPPING

Envizi Column and Source File Column and Data Notes and Assumptions
Name (Internal Name (Location of Data Format
Use Only) in File)
Group F GROUP NAME 3 String The group used to create
location to group membership.
Location Reference H LOCATION String Used to identify the location for
REFERENCE membership.
Location Name G LOCATION String If no location match is found
by LOCATION REFERENCE
above, Location name will be
used to identify the location for
membership with the group.
Group Description C GROUP String The group description provides
HIEARCHY a unique identifier for the
NAME group and it's position in the
group path by only including
D the group parents up to the
GROUP NAME 1 relevant entity.
E
GROUP NAME 2 The group description will be
F used to validate that the
GROUP NAME 3
GROUP being linked to is in
fact the GROUPNAME3 value,
nested in the existing 'Group
Hierarchy Name' structure.
GROUPNAME3 Group
Description = 'GROUP
HIERARCHY
NAME'_'GROUPNAME1'>'GRO
UPNAME2'>'GROUPNAME3'>

The group hierarchy name is

used to identify the group
hierarchy. For example,
Geographical
Region_'GROUPNAME1'>'GRO
UPNAME2'>'GROUPNAME3'>