Upload organizational data (first upload)
Administrators must first upload (import) organizational data before you can analyze insights about your company in the advanced insights app that's available with Microsoft Viva Insights. Complete the following steps after preparing data as described in Prepare organizational data.
Important
Only use the following steps if this is the first time you are uploading organizational data. If this is not your first upload, see Upload organizational data (subsequent uploads) to update previously uploaded data.
Import tasks
The task of importing organizational data has three parts:
After you prepare the source data, you can upload the .csv file and map fields. After you map fields, the app validates the data. When the data successfully validates, the overall data-import task is complete. If the data validation is not successful, you can choose from a few options that are described in Validation fails.
Video: Upload organizational data
File upload
After the initial processing of collaboration data is complete, the next time you open the app, the page automatically updates to let you know it's time to upload your organizational data as a .csv file, as follows:
In Upload, select Name your upload and enter a name.
Optionally, select Add an optional description and type a description.
Click Select a file, select the .csv file to upload, and then select Open after reviewing the following important upload considerations:
- The .csv file that you upload must be UTF-8 encoded.
- Confirm the .csv file is not open in a different program when you begin the upload process.
- After the upload process begins, the process is irreversible.
To complete a new upload, select Next. This displays the System fields table. Go to Field mapping.
Field Mapping
You need to map the fields (columns) for the source .csv file to the field names that the app recognizes. You map these fields during the Upload step, as indicated in the progress bar on the Setup page:
This page includes tables for System default fields and Custom fields for mapping the data for the upload file. These field types are described in the following sections.
System default fields
System default fields represent attributes that are known by Viva Insights and are used in specific calculations beyond grouping and filtering. A system default field can be either required or optional.
Required fields are identified in two ways. Their rows have dark shading and show as "Required" under the Source column header. These rows represent data that was found in the uploaded file. For the upload to succeed, you must map the required fields with a column in your .csv file that is the correct data type.
Important
Every required field must have a valid, non-null value in every row. This means that, even if the names of these attributes are not present in the uploaded .csv file, other columns must be present in the .csv file that are mapped to these attributes.
Optional fields appear below the required fields in rows that have lighter shading. These rows are commonly encountered system fields that the app suggests for use. You don't need to map these fields if your organization doesn't have data for them.
Custom fields
- Custom fields are displayed on this page below the optional fields. Custom fields are optional attributes you can create. Select a column from your source.csv file. Name the column, select the data type, and then select the report option.
Field column details
Source column corresponds to each of the fields in the uploaded file.
Workplace Analytics name is the name of your organization's advanced insights app.
Data type is the data type of the fields, such as Email or DateTime.
Note
If the data type is Boolean, the value for the Boolean field must be TRUE or FALSE.
Include in report lets you decide how to treat sensitive data in the report that will be generated about the import operation. If offers the following options for each of the columns in your source data:
- Show in report - Lets the actual data value display in the report just as it was imported in the organizational data file.
- Exclude from report - Prevents the data value from appearing in the report. For data-privacy reasons, some attributes (such as ManagerID) are automatically assigned the value "Exclude from report" and this value cannot be changed.
- Hash in report - De-identifies sensitive data. This option includes the data in the report that it generates about the import operation, but instead of displaying the actual value that was taken from the source file, it shows a hashed version of the value – a format that cannot be read.
To map fields
After you complete the steps in File upload, do the following to map the fields:
In Upload, map the required fields.
- Determine which of the columns in your .csv file correspond to the second column in the table.
- In Source column (the first column in the table), select the name that corresponds with the applicable attribute name.
- Select or enter the applicable values for the other columns, including the Data type and Report options.
- Repeat these steps for all the required system fields.
Note
See Field column details for more information.
Map the optional and custom fields, as applicable. You only need to map the columns in the source data (.csv) file that your organization considers important for analysis. For example, if StartDate is important and your data contains this field, map it.
- In Source column (the first column in the table), select the applicable names for the data you want to upload.
- Select or enter the values for the other columns in the table, such as the data type and report options.
- Repeat these steps for all custom fields that are important to your organization.
In Submit for validation, select the checkbox for I confirm that these mappings are correct, and then select Next. You'll then see a notice about "your file is uploading."
Important
You must stay logged in while the file is uploading or the upload will be canceled. The upload requires this page to be open in your web browser during the upload. If you close the browser (or this browser page), the upload will fail.
- The next step is Data validation.
Data validation
After you complete the steps in Field mapping, the Upload page shows the following message:
After the file has successfully uploaded, file validation starts:
In most cases, file validation should complete very quickly. If your organizational data file is very large, validation could take up to one or two minutes.
During this step, if you decide that the data you are uploading is not the correct data and that you want to upload a different data file instead, select Cancel.
After this phase completes, the file has either passed or failed validation. Go to the appropriate section:
Validation succeeds
If validation succeeds, in the Validation results section, the page displays the Succeeded notification, which reports information about the data that was successfully uploaded and validated:
After successful validation, Viva Insights processes your new data.
You can select Data sources > Organizational data to see the Upload history page. You can then select Successes to see the workflows that were successfully validated (and uploaded).
On this page, you have the following options:
- Select the View (eye) icon to see a summary of the validation results.
- Select the Mapping icon to see the mapping settings for the workflow.
- Select the Validation (download) icon to see a list of validation warnings.
Note
Each tenant can have only one upload in progress at a time. Therefore you need to complete the workflow of one data file, which means you either guide it to a successful validation or abandon it, before you begin the workflow of the next data file. The status or stage of the upload workflow is shown on the progress bar across the top of the Upload page.
Validation fails
If data validation fails, the Setup page shows a "could not be validated" notification in the Upload details area. This page also presents you with options of how to proceed.
Before you address the problem, you can select Download error log. This log file describes the problems in your data that might have caused the validation errors. Use this information to decide what to do next — fix the source data or change your mapping settings. The following section describes these options:
Options upon failed validation
| Nature of errors | Recommended selection | Description |
|---|---|---|
| Minor errors, small in number | Select Edit mapping | This displays the Field Mapping page, on which you can change how you map source-file fields to the attributes and then re-attempt validation. You can do this without changing and re-uploading the source file. This is best for minor errors such as having mapped the wrong column in the source file to a particular attribute. |
| Major errors | Select Upload file | This displays the first File upload page. Consider this option in the case of major errors in the originally uploaded data. First, edit the source-data file to fix those errors and then re-attempt the upload and validation process with the corrected file. |
Note
The app does not modify or fill in data that is missing from HR uploads, even for EffectiveDate or TimeZone. The administrator is responsible for correcting such errors or omissions.
Guidelines for correcting errors in data
This section contains help for correcting data in an uploaded source file that is causing validation errors.
When any data row or column has an invalid value for any attribute, the entire upload will fail until the source file is fixed (or the mapping changes the validation type of the attribute in a way that makes the value valid).
Rules for field headers
All field header or column names must:
- Begin with a letter (not a number)
- Only contain alphanumeric characters (letters and numbers, for example Date1)
- Have at least one lower-case letter (Hrbp); all uppercase won’t work (HRBP)
- Match exactly as listed for the Required and Reserved optional attributes, including for case sensitivity, such as PersonId and HireDate
- Have no leading or trailing blank spaces or special characters (non-alphanumeric, such as @, #, %, &); if spaces or special characters are included, which will be removed from the name
Rules for field values
The field values in data rows must comply with the following formatting rules:
- The required EffectiveDate and HireDate field values must be in the MM/DD/YYYY format
- The required PersonId and ManagerId field values must be a valid email address (for example, gc@contoso.com)
- The TimeZone field values must be in a supported Windows format
- The Layer field values must contain numbers only
- The HourlyRate field values must contain numbers only, which the app assumes are in US dollars for calculations and data analysis
Note
The app does not currently perform currency conversions for HourlyRate data. All calculations and data analysis assumes the data to be in US dollars.
Rules for characters in field values
The following field rules apply to characters in field values:
Double-byte characters, such as Japanese characters, are permitted in the field values
Limit the character length of field values in rows to a maximum of 128 KB, which is about 1024 x 128 characters
The following characters are not permitted in field values:
- tilde (~)
- "new line" (\n)
- Double quotes (" ")
- Single quotes (' ')