Skip to main content
Data Format and Requirements
Tina Chan avatar
Written by Tina Chan
Updated this week

Here are all the fields in the template or downloaded CSV file. To learn more about their definitions, please click on the Field Name.

Prepare your data according to the examples in the template and the formatting requirements listed here.

You can click on the Table of Contents on the right to jump to any section anytime.

People

Roles, Default Rates and Costs CSV

Field Name

Description/ Formatting Requirement

Role Name (Required)

  • Each Role Name has to be unique

(Required)

  • Only a numeric value is accepted e.g. 100

  • Do not input symbols e.g. $

Default Rate (Required)

  • Only a numeric value is accepted e.g. 100

  • Do not input symbols e.g. $

People CSV

Person Details

Field Name

Description/ Formatting Requirement

First Name

(Required)

  • Special Characters are supported

Last Name

(Required)

  • Special Characters are supported

Email

(Required)

  • This is a unique identifier in Runn

  • Ensure there are no duplicated emails

(Optional)

  • This is the person's Job Title in the organization's HR system.

  • If added, you can choose to view Job Title on the People Planner.

(Required)

  • The Default Role Name is the default project role when a person is assigned to a project.

  • If you add new Role Names that don't exist in Runn, a new role will be automatically created. The default rates and costs of the new role will be set as $0. You can update them later.

(Optional)

  • Each person can only belong to one Team

Cost to Business (per hour)

(Required only if you are using Custom Hourly Cost, otherwise Optional)

  • If you have a custom hourly cost for each person (or salary based on Job Title/seniority), you need to enter the custom hourly cost for the person

  • If you don't need Runn to calculate the cost, you can enter 0 for each person.

  • If this is left blank, the person's cost-to-business will default to the Role Default Cost according to the Default Role Name assigned.

Start Date

(Optional)

  • Format: YYYY-MM-DD

  • The dates have to be within 5 years from the date you create the contract.

  • If you did not add a Start Date, Runn will add an assumed start date for the person

End Date

(Optional)

  • Format: YYYY-MM-DD

  • If the person's contract does not have an End Date e.g. permanent employee, you can leave this blank.

Employment Type

(Required)

  • Enter Employee or Contractor

Tags, Skills and External References

(Optional)

  • If you would like to add Public Holidays to your people based on their locations, please add their locations as tags.

  • If you want to add multiple tags to a person, use a comma as the separator

    • e.g. US, Germany, Malaysia

  • If your tag names contain a comma, and you need to add multiple tags to a person, add quotation marks to each tag

    • e.g. "New York, US", "Berlin, Germany"

(Optional)

  • The format required is Skill Name, or Skill Name=Skill Level

  • Each skill name has to be unique

  • Skill Level can be 0 to 4, 4 is the highest level

  • You can just enter the Skill Name if you don't need to define the Skill Level

  • If your source file has Skill Names and Skill levels separated into different cells, the format in the Skills & Levels Importer might be easier for you

External References

(Required if you need to use the API or integrations, otherwise Optional)

  • If you need to use the API or integrations to maintain people data, please enter the relevant ID here.

  • The format required is Field Name=ID Number

  • If you want to use Employee ID as the Person Identifier in future CSV imports, you can enter the Employee ID here e.g. Employee-ID=45656

  • Runn does not validate whether the ID is unique in the field

People Custom Fields CSV

Field Name

Description/ Formatting Requirement

Person Identifier

(Required)

  • The unique email address of each person, or

  • The unique Employee ID you have added in the External References field in the People CSV file, or

  • Runn's Person ID (from CSV Export)

Person First Name

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Person Last Name

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Custom Field Name

(Optional)

  • Enter the custom field option/data for the person

  • Example: If the Custom Field Name is Location, and the person is based in Canada, enter Canada in this field

  • If it is a Single-select or Multi-select custom field, the value MUST be one of the custom field options you set up from the Custom Field page

  • If it is a Multi-select custom field, use a comma as the separator

    • e.g. US, Germany, Malaysia

    • If the custom field option contains a comma, and you need to add multiple options to a person, add quotation marks to each option

    • e.g. "New York, US", "Berlin, Germany"

  • If it is a Checkbox custom field, enter Y or N to indicate Yes or No

  • If you don't need to add the custom field data to the person, leave it blank

Contracts CSV

Field Name

Description/ Formatting Requirement

Contract ID (Required when updating existing contracts)

  • If you are adding a new Contract, leave this field blank

  • If you are updating an existing Contract, keep the Contract ID same as the one exported from Runn.

Person Identifier (Required)

  • This is the Person's email address. It should be exactly the same as the email added in Runn.

  • You must have the person created in Runn before adding a new contract.

Person First Name (Optional)

  • This field is for reference only and will not be updated.

Person Last Name (Optional)

  • This field is for reference only and will not be updated.

(Optional)

  • This is the person's Job Title in the organization's HR system.

  • If added, you can choose to view Job Title on the People Planner

  • The Default Role Name is the default project role when a person is assigned to a project

  • The role names should match those already created in the Roles template, otherwise, it will create a new role.

  • If you add new Role Names that don't exist in Runn, the default rates and costs of the new role will be set as $0. You can update them later

Employment Type (Required)

  • Enter Employee or Contractor

Start Date (Required)

  • Format: YYYY-MM-DD

  • The dates have to be within 5 years from the date you create the contract.

End Date

(Optional)

  • Format: YYYY-MM-DD

  • When entered, the person'as availability on the People Planner will be shown as No Contract

  • If the person's contract does not have an End Date e.g. permanent employee, you can leave this blank

Work Days (Optional)

  • If the person works Monday to Friday, the default state is 1,1,1,1,1

  • You can leave this field if the person works Monday to Friday

  • If the person has a rostered day off, enter 0 for that day

  • For example, if the person is off on Wednesday, enter 1,1,0,1,1

Minutes per day

(Optional)

  • If the person is a FTE staff, you can leave this blank

  • If the person is a part-time employee, please enter the working hours per day in minutes

  • Example: If the person works 4 hours per day, please enter 60 minutes * 4 = 240 minutes

  • Runn does not support different minutes per day worked for each day

Cost to Business (per hour)

(Optional)

  • If you have a custom hourly cost for each person (or salary based on Job Title/seniority), you need to enter the custom hourly cost.

  • If you don't need Runn to calculate cost, you can enter 0 for each person

  • If this is left blank, the person's cost-to-business will default to the Role Default Cost according to the Default Role Name assigned

Skills & Levels CSV

Field Name

Description/ Formatting Requirement

Person Identifier

(Required)

  • The unique email address of each person, or

  • The unique Employee ID you have added in the External References field in the People CSV file, or

  • Runn's Person ID (from CSV Export)

Person First Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Person Last Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Role Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Skill Name

(Required)

  • Each skill name has to be unique

Level

(Optional)

  • Enter a numeric value from 0 to 4

  • 4 is highest and 0 is lowest

Time Off CSV

Field Name

Description/ Formatting Requirement

Person Identifier

(Required)

  • The unique email address of each person, or

  • The unique Employee ID you have added in the External References field in the People CSV file

Person First Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Person Last Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Start Date

(Required)

  • Format: YYYY-MM-DD

End Date

(Required)

  • Format: YYYY-MM-DD

Note

(Optional)

  • Add a note to indicate what type of time off this is e.g. Annual Leave


Projects

Projects CSV

Field Name

Description/ Formatting Requirement

Project Name

(Required)

  • The Project Name has to be unique

Client ID

  • Please leave this column blank or delete the column

Client Name

(Required)

  • The Client Name has to be unique

Client Website

(Optional)

  • If you include your client's website, Runn will display your client's company logo on the planner.

Status

(Required)

  • Confirmed or Tentative

  • If you would like to add customized project statuses, you can add them as Project Custom Fields later

Primary Team

(Optional)

  • Add the Primary Team assigned to the Project

  • If the Primary Team Name does not exist in Runn, a new Team will be created

  • A project can only have one primary team

  • This will NOT automatically add all the team members to the project, you will still have to add the project team members manually in Runn

Pricing Model

(Required)

  • Time and Materials, Fixed Price or Non-billable

(Optional)

  • You must create Rate Cards manually in Runn first

  • Only add Rate Card Names that exist in Runn

  • If you don't need to use rate cards, leave this field blank

  • Updating the Rate Card Name doesn't update the Project Rates automatically

(Optional)

  • Only numeric values are accepted e.g. 10000

  • Add the financial budget for Time and Materials and Fixed Price projects

  • For Non-billable projects, you cannot add the time budget via the CSV tool here

(Optional)

  • If you want to add multiple tags to a project, use a comma as the separator

    • e.g. US, Germany, Malaysia

  • If your tag names contain a comma, and you need to add multiple tags to a project, add quotation marks to each tag

    • e.g. "New York, US", "Berlin, Germany"

External References

(Required if you need to use the API or integrations, otherwise Optional)

  • If you need to use the API or integrations to maintain projects data, please enter the relevant ID here.

  • The format required is Field Name=ID Number

  • If you want to use your internal Project ID as the Project Identifier in future CSV imports, you can enter the internal Project ID here e.g. Project-ID=45656

  • Runn does not validate whether the ID is unique in the field

Project Manager IDs

(Optional)

  • If you need to bulk add Editors (Specific Projects) to your projects, you can enter their User IDs here

  • If this is your first time setting up the account, please leave this field blank first.

  • Read this help article to learn more

Workstreams

(Optional, available for Enterprise Accounts only)

  • If you want to add multiple workstreams to a project, use a comma as the separator

    • e.g. Research, Design, Build

  • If your tag names contain a comma, and you need to add multiple tags to a project, add quotation marks to each tag

    • e.g. "Interview, Research", "Flow Chart, Design"

Projects Custom Fields CSV

Field Name

Description/ Formatting Requirement

Project Identifier

(Required)

  • Runn's Project ID (from CSV Export), or

  • Your organization's unique Internal Project ID you have added in the External References field in the Projects CSV file

Project Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Client Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Custom Field Name

(Optional)

  • Enter the custom field option/data for the project

  • Example: If the Custom Field Name is Region, and the project is happening in Canada, enter Canada in this field

  • If it is a Single-select or Multi-select custom field, the value MUST be one of the custom field options you set up from the Custom Field page

  • If it is a Multi-select custom field, use a comma as the separator

    • e.g. US, Germany, Malaysia

    • If the custom field option contains a comma, and you need to add multiple options to a project, add quotation marks to each option

    • e.g. "New York, US", "Berlin, Germany"

  • If it is a Checkbox custom field, enter Y or N to indicate Yes or No

  • If you don't need to add the custom field data to the project, leave it blank

Phases CSV

Field Name

Description/ Formatting Requirement

Phase ID

(Required only when updating existing phases)

  • If you are adding a new Phase, leave this field blank

  • If you are updating an existing Phase, keep the Phase ID same as the one exported from Runn.

Project Identifier

(Required)

  • Runn's Project ID (from CSV Export), or

  • Your organization's unique Internal Project ID you have added in the External References field in the Projects CSV file

Project Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Client Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Phase Name

(Required)

  • It is recommended to have unique phase names within each project

Color

(Required)

  • Define the Phase Color:

    • aqua

    • mint

    • canary yellow

    • peachy orange

    • classic pink

    • lavender

    • reef green

    • leaf green

    • sand

    • terracotta

    • lilac

    • sea blue

  • Refer to the Phase Color Index below

Start Date

(Required)

  • Format: YYYY-MM-DD

  • The date cannot fall on a weekend

End Date

(Required)

  • Format: YYYY-MM-DD

  • The date cannot fall on a weekend

Phase Color Index

Number

Name

HEX

1

Aqua

#67D0D5

2

Mint

#84DBA0

3

Canary Yellow

#FDCD4F

4

Peachy Orange

#FFB077

5

Classic Pink

#F191CC

6

Lavender

#B19DE6

7

Reef Green

#9CC5BF

8

Leaf Green

#9CE277

9

Sand

#E8C681

10

Terracotta

#DDAE9F

11

Lilac

#CD97DA

12

Sea Blue

#6899F1

Milestones CSV

Field Name

Description/ Formatting Requirement

Milestone ID

(Required when updating existing milestones)

  • If you are adding a new Milestone, leave this field blank

  • If you are updating an existing Milestone, keep the Milestone ID same as the one exported from Runn.

Project Identifier

(Required)

  • Runn's Project ID (from CSV Export), or

  • Your organization's unique Internal Project ID you have added in the External References field in the Projects CSV file

Project Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Milestone Name

(Required)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Note

(Optional)

  • Add a description to a milestone, if any

Date

(Required)

  • Format: YYYY-MM-DD

  • The date can fall on a weekend

Icon

(Required)

  • Define the Milestone Icon to appear on the Project Planner:

    • Start

    • End

    • Dollar

    • Warning

    • Flag

  • Emoji icons are not supported in the CSV importer

Users and Permissions CSV

Field Name

Description/ Formatting Requirement

Email

(Required when inviting new users, optional when updating permissions)

  • This is the unique identifier of the user

  • If the user is also a person managed in Runn, please to use the same email address

Account Type

(Required)


Please add one of the following:

  • admin

  • editor

  • viewer_all

  • viewer_basic

  • timesheet_only

Financial Type

(Required)

  • If the Account Type is admin, please add all in this field

  • If the Account Type is editor or viewer_all, please choose one of the following:

    • all

    • restricted

    • none

  • If the Account Type is viewer_basic or timesheet_only, please add none

Editor Type

(Required)

  • If the Account Type is admin, please add all projects and people in this field

  • If the Account Type is editor, please choose one of the following:

    • all projects and people

    • all projects

    • restricted projects

  • If the Account Type is viewer_all, viewer_basic or timesheet_only, please add none

Assignments CSV

Field Name

Description/ Formatting Requirement

Project Identifier

(Required)

  • Runn's Project ID (from Projects CSV Export), or

  • Your organization's unique Internal Project ID you have added in the External References field in the Projects CSV file

Project Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Client Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Person Identifier

(Required)

  • The unique email address of each person, or

  • The unique Employee ID you have added in the External References field in the People CSV file, or

  • Runn's Person ID (from CSV Export)

Person First Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Person Last Name (ref)

(Optional)

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Role Name

(Required)

  • The person's Project Role in this assignment, this can be different from their default Project Role

  • You must have the role created in Runn before adding assignments

  • The Role Name must be the same as the role names exported from the Roles, Default Rates and Costs CSV

Start Date

(Required)

  • Format: YYYY-MM-DD

  • The date cannot fall on a scheduled leave

  • The date cannot fall on a weekend or public holiday (unless it is a non-working day assignment)

End Date

(Required)

  • Format: YYYY-MM-DD

  • The date cannot fall on a scheduled leave

  • The date cannot fall on a weekend or public holiday (unless it is a non-working day assignment)

Minutes Per Day

(Required)

  • The daily effort of the assignment

  • Example: If you want the person to work 4 hours per day on this assignment, add 60 minutes * 4 = 240 minutes

Existing Phase ID

(Optional)

  • If you would like to add the assignment to an existing Phase, add the Phase ID here

  • To find out the Phase ID, go to CSV > Projects > Phases > Download Existing Phases CSV

New Phase Name

(Optional)

  • If you would like to link the assignment to a new phase that has never been created within the project, enter the Phase Name here

  • The duration of the phase is the same as the duration of the first linked assignment

Billable

(Required)

  • If it is a billable assignment, enter Y

  • If it is a non-billable assignment, enter N

Non-Working Day

(Required)

  • If the assignment is scheduled on a regular work day, enter N (this is the most common use case)

  • If you would like to schedule work on a Public Holiday or weekend, you need to create a separate row for that day of assignment and enter Y

Note

(Optional)

  • Add a description to the assignment if needed

Workstream

(Optional)

  • If you want to link the assignment to a workstream, add the Workstream Name here

Timesheets CSV

Field Name

Description/ Formatting Requirement

Person Identifier

(Required)

  • The unique email address of each person, or

  • The unique Employee ID you have added in the External References field in the People CSV file, or

  • Runn's Person ID (from CSV Export)

Person First Name (ref)

(Optional)

  • Enter the Person's First Name here for your reference.

  • If the person's email is sufficient as an identifier, you can remove this column

Person Last Name (ref)

(Optional)

  • Enter the Person's Last Name here for your reference.

  • If the person's email is sufficient as an identifier, you can remove this column

Person Email (ref)

(Optional)

  • Remove this column when importing the CSV file

  • You will see this field populated with the person's email in the exported file

Project Identifier

(Required)

  • Runn's Project ID (from Projects CSV Export), or

  • Your organization's unique Internal Project ID you have added in the External References field in the Projects CSV file

Project Name (ref)

(Optional)

  • Enter the Project Name here for your reference.

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Client Name (ref)

(Optional)

  • Enter the Client Name here for your reference.

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Role Name

(Required)

  • The person's Project Role in this assignment, this can be different from their default Project Role

  • You must have the role created in Runn before adding timesheets

  • The Role Name must be the same as the role names exported from the Roles, Default Rates and Costs CSV

Phase ID

(Required if you need link the timesheet entry to a phase)

  • If you would like to add the timesheet to an existing Phase, add the Phase ID here

  • To find out the Phase ID, go to CSV > Projects > Phases > Download Existing Phases CSV

Phase Name (ref)

(Optional)

  • Enter the Phase Name here for your reference.

  • This is for your reference only. Changing the value in this field will NOT change any data in Runn.

Date

(Required)

  • Format: YYYY-MM-DD

  • The date can fall on a weekend

Minutes

(Required)

  • The number of minutes worked by the person

  • Example: If the person worked 4 hours on this day, add 60 minutes * 4 = 240 minutes

Billable

(Required)

  • If it is a billable work, enter Y

  • If it is a non-billable work, enter N

Note

(Optional)

  • Add a description to the timesheet entry if needed

Workstream

(Optional)

  • If you want to link the timesheet entry to a workstream, add the Workstream Name here

  • The Workstream Name must have been added to the Project

Custom Fields CSV

Field Name

Description/ Formatting Requirement

(Required)

  • Choose between Project or Person

  • This property CANNOT be updated once the field is created

(Required)

  • Enter one of the following:

    • Single Select

    • Multi Select

    • Text

    • Checkbox

  • This property CANNOT be updated once the field is created

Custom Field Name

(Required)

  • Name of Field as it will appear in Runn

Description

(Optional)

  • Add more info about the field if needed

Include in the Planner

(Required)

  • If you want to view the field on the Planner, enter Y

  • If you don't need to see it on the Planner, enter N (It will still be available on the Dashboard and in the Reports)

Filterable in Planner (Required)

  • If you want to filter the Planner by this field, enter Y

  • If you don't need to filter by this field, enter N

Options

(Required for Single Select or Multi Select Fields)

  • If the field type is Single Select or Multi Select, enter the options here

  • You can add unlimited options here. Each option has to be unique

  • Example: For a Single Select Field - Location, enter all the possible locations that you want to be added to the people/ projects: France, Australia, Japan

  • Use a comma as the separator

    • e.g. US, Germany, Malaysia

    • If the custom field option contains a comma, and you need to add multiple options to a person, add quotation marks to each option

    • e.g. "New York, US", "Berlin, Germany"

  • You can only add new options to an existing field, you cannot change or remove existing options

Did this answer your question?