File Format - Employee
Employee File Format
The first line of an Employee CSV file must be the header row.
An employee instance is a group of rows in the CSV file that are sequential and include the same required fields. Data relating to fields specified under Base Headers and Multi-Column Headers must be specified in the first row of an employee instance. Additional rows of an employee instance may only include fields specified under Multi-Row Headers.
Required Headers
To successfully import an employee CSV file, the following columns must be included in the header row:
| Column Name | Description | Type |
|---|---|---|
Employee ID (Required) | Identification string for an employee. This employee identifier is referenced by other entities such as stores, order, customers, tasks, etc. Must be unique for each employee | string |
Store ID (Required) | ID of the store in which the employee belongs to. Must map to a store that exists in the store data. | string |
Display Name (Required) | Display Name of the employee | string |
First Name (Recommended) | Employee’s first/given name | string |
Last Name (Required) | Employee’s last/family name | string |
Mobile Number (See Note) | Employee’s cell phone number | string (E164 format) |
Image | URL to an image to be used with this employee | string |
Email (Required) | Employee’s email | string |
Disabled (Required) | Whether or not this employee is disabled | boolean |
| Groups | May Be Required | See below |
| Custom Attributes | See below |
Note: If in two or more sequential rows Store ID, Display Name, and Employee ID are not the same, each row will be considered and processed as different employees. All three must be the same throughout multiple rows in order to ensure they are treated as one employee instance.
Note: If no mobile number is provided but exists in Tulip for the employee already, then the mobile number will NOT be erased. You are not able to unassign a mobile number for an employee through File Importer. You are able manage the employee mobile number via Admin Console.
Groups
A group is a class of headers that relate to one another. Groups may allow for multiple pieces of information to be presented. For example, a customer can have multiple emails, addresses, phone numbers, and more.
Employee groups include the following – see below for details:
Authorized User (Required)
An Authorized User includes four headers, two of which are required if an authorized user is specified. Three of these headers are similar to Base Fields in nature, in that they may only be specified once in the first row of a new employee instance. However, there are two ways of formatting the fourth row: using a Multi-Row Approach, or a Multi-Column Approach.
Multi-Row Approach
In this approach, one column header is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, one column header may be used many times alongside one row (the first row) of an employee instance. To use this column multiple times, an identifying number must exist for N and be unique for each new column.
These three columns may only be specified once for an Authorized User:
| Column Name | Description | Type |
|---|---|---|
Authorized User Username (Required) | Username for the authorized user. This is required if an authorized user is specified | string |
Authorized User Password (Required) | DO NOT SEND PASSWORDS. Send a blank for this value. Passwords can be reset via Tulip Self-Serve Tools. | string |
Authorized User Disabled (Required) | Whether or not the authorized user is disabled. Send False when the user should be allowed to login. | boolean |
This is the fourth column, which may use a Multi-Row Approach, or a Multi-Column Approach:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Authorized User Role ID | Authorized User Role ID N | Internal Role IDs associated with the authorized user. 1 - Associate and 2 - Manager | integer |
Where N is some positive integer
Localized Data (Optional)
There are two ways that localized data can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of an employee instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Localized Data group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Localized Job Title | Localized Job Title N | Description of the employee job title localized to the specified language | string |
Localized Language ID | Localized Language ID N | ID of the language in which the record appears. Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
Custom Attributes (Optional)
There are two ways that custom attributes can be formatted in your CSV file: A Multi-Row Approach or Multi-Column Approach.
Multi-Row Approach
In this approach, one set of column headers is used alongside multiple rows of data. To allow for multiple rows of data, additional rows must include the same Required Headers fields.
Multi-Column Approach
In this approach, multiple sets of column headers may be used alongside one row (the first row) of an employee instance. To use these columns multiple times, an identifying number must exist for N and be unique for every new set of columns.
Columns from the Multi-Row Approach cannot be mixed with columns from the Multi-Column Approach in a CSV file for the Custom Attributes group.
The following columns may be included:
| Multi-Row Approach Column Name | Multi-Column Approach Column Name | Description | Type |
|---|---|---|---|
Custom Attribute ID | Custom Attribute N ID | Identifier of the custom attribute | string |
Custom Attribute Value | Custom Attribute N Value | Value of the attribute | string |
Custom Attribute Language ID | Custom Attribute N Language ID | Language of the attribute. Integers will be resolved to internal identifiers | integer, string |
Where N is some positive integer.
Employee CSV Example
See the following Employee CSV sample file.