File rules and validation errors

In this article, we describe how your upload file needs to be formatted, and provide errors you might encounter while bringing data into the advanced insights app.

File and field rules

When any data row or column has an invalid value for any attribute, the entire upload might fail or produce warnings depending on whether Upload valid rows and exclude rows with invalid data under Advanced configuration is turned on or off.

If Upload valid rows and exclude rows with invalid data under Advanced configuration is turned off, the entire upload fails due to validation errors until the source file is fixed (or the mapping changes the validation type of the attribute in a way that makes the value valid).

If Upload valid rows and exclude rows with invalid data under Advanced configuration is turned on, it will only upload rows that include valid values, and will show warnings for the rows that weren't ingested due to errors. This setting is off by default.

Rules for the file

The data file needs to be in the .csv UTF-8 format, and it can’t be empty.

Rules for source and target field headers

All source and target field header or column names need to:

1. Only contain ASCII alphanumeric characters (letters and numbers, for example, Date1), or underscore (_). Special nonalphanumeric characters such as @, #, %, &, or other characters aren’t supported.
2. Contain a value.
3. Be unique.

Rules for custom target field headers

All custom target field headers or column names need to:

1. Have no leading, middle, or trailing blank spaces.
2. Contain no system fields, which are:
   • PeopleHistoricalId
   • StartDate
   • EndDate
   • Domain
   • PopulationType
   • TimeZone
   • StandardTimeZone
   • WorkdayStart
   • WorkDayEnd
   • WeekendDays
   • InferredTeamSize
   • ObjectId
   • IsActive
   • Starting with "Microsoft_"
   • MetricDate
   • PrimaryCollaborator_PersonId
   • SecondaryCollaborator_PersonId

Required fields need to have a value for every row.

After you upload your file, you can only map one column header to each Viva Insights data field.

Rules for field values

Field values need to be provided in the correct data type. Refer to Attribute reference.

Rules for characters in field values

• The character length of field values in rows can't exceed 128 KB, which is about 1024 x 128 characters.
• “New line” (\n) characters aren't permitted in field values.

Rules for values in the ManagerId field

Each PersonId needs to have a unique ManagerId. In other words, there can't be multiple managers for one person.

There can't be loops where:

• Managers and employees report to each other.
• Managers report back to employees.

Let’s say Dylan is Kris’s manager. The organizational data couldn’t show:

• Kris reporting to Dylan and also Dylan reporting back to Kris.
• Dylan reporting to Kris.

Both of the following hierarchies would produce errors in end-user experiences:

Example .csv export file

Here's an example snippet of a valid .csv export file:

PersonId,EffectiveDate,HireDate,ManagerId,LevelDesignation,Organization,Layer,Area [email protected],12/1/2020,1/3/2014,[email protected],Junior IC,Sales,8,Southeast [email protected],11/1/2020,1/3/2014,[email protected],Junior IC,Sales,8,Southeast [email protected],12/1/2020,1/3/2014,[email protected],Manager,Sales,7,Northeast [email protected],10/1/2020,8/15/2015,[email protected],Support,Sales,9,Midwest [email protected],11/1/2020,8/15/2015,[email protected],Support,Sales,9,Midwest [email protected],12/1/2020,8/15/2015,[email protected],Support,Sales,9,Midwest

Validation errors and warnings

Here are validation errors you might encounter while uploading data to the advanced insights app. In most cases, you need to correct the errors and upload your file again. Review our Prepare organizational data article to learn how to format and get your data ready for upload.

Below are the validation errors and warnings related to field values. If Upload valid rows and exclude rows with invalid data under Advanced configuration is turned off, it creates errors and fail validation. If it's turned on, it will only upload rows that include valid values, and will show warnings for the rows that weren't ingested due to errors. This setting is off by default.