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.
Spec
The following table shows the accepted CSV columns for the employees entity. Note that any columns including N denote a dynamic integer. A column specified as Field N signifies that you can use columns Field 1, Field 2, …, Field N to allow for multiple values per record of the given field, similar to an array.
| CSV Header | Data Type | Group | Required | Description |
|---|---|---|---|---|
Store ID | string | Yes | ID of the Store to which the Employee belongs (externalId resolvable) | |
Display Name | string | Yes | Employee’s display name to use in the Tulip Retail App | |
Mobile Number | string | No | Employee’s mobile phone number (using E164 format) | |
First Name | string | No | Employee’s first/given name | |
Last Name | string | No | Employee’s last/family name | |
Image | string | No | URL of the Employee to be uploaded into the Tulip Platform | |
Employee ID | string | Yes | External identifier of the record | |
Email | string | No | Employee’s email address | |
Disabled | boolean | No | Whether or not the Employee is disabled in the Tulip Platform | |
Localized Job Title | string | Localized Data | No | Description of the Employee Job Title |
Localized Language ID | integerORstring | Localized Data | No | ID of the Language in which the record appears (externalId resolvable) |
Localized Job Title N | string | Localized Data N | No | Description of the Employee Job Title |
Localized Language ID N | integerORstring | Localized Data N | No | ID of the Language in which the record appears (externalId resolvable) |
Custom Attribute ID | string | Attribute Values | No | Attribute to be used as key in the key/value pair (externalId resolvable) |
Custom Attribute Value | string | Attribute Values | No | Value to appear in this key/value pair |
Custom Attribute Language ID | integerORstring | Attribute Values | No | Language ID for the language in which this value appears; use 0 if it is not localized (externalId resolvable) |
Custom Attribute N ID | string | Attribute Values N | No | |
Custom Attribute N Value | string | Attribute Values N | No | |
Custom Attribute N Language ID | integerORstring | Attribute Values N | No | |
Authorized User Username | string | Auth User | Yes | Username for logging in as this Auth User (must be unique) |
Authorized User Disabled | boolean | Auth User | No | Whether or not this Auth User is disabled |
Authorized User Password | string | Auth User | Yes | Password for logging in as this Auth User (must be at least 3 characters) |
Authorized User Role ID | integerORstring | Auth User Roles | No | Array of EmployeeRole IDs that the Employee has |
Authorized User Role ID N | integerORstring | Auth User Roles N | No | Array of EmployeeRole IDs that the Employee has |
SAML Name ID | string | No |
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.
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.