Loading Field Domain Values Using CSV Import

[A companion article to CMMS Integration Field Configuration. This article covers only how to manually load domain values for CMMS fields in Virtual Facility (VF). For setting up the CMMS Configuration tab and syncing a field's Domain Values, see the main article.]

Overview

Virtual Facility supports the bulk import of domain values through a CSV file. This allows administrators to quickly create or update large lists of values used by CMMS field mappings without manually entering each value.

CSV imports are commonly used when:

• A CMMS field requires a large number of selectable values.
• Domain values are managed outside of a CMMS integration.
• Values need to be loaded before a CMMS connection is established.
• Existing domain values need to be updated in bulk.
• Parent-child domain value relationships must be maintained.

Before You Begin

• Verify that the target CMMS field has already been created.
• Ensure you have administrative permissions to manage domain values.
• Confirm that the CSV file follows the required template structure.
• Review existing domain values to avoid creating duplicate entries.
• If parent-child relationships are required, ensure parent values already exist or are included in the import.

Important: CSV imports can create or update matching values based on the imported data. Always review the file carefully before importing.

Accessing Domain Values

Before importing domain values, navigate to the Domain Values section for the CMMS field you want to manage. The Settings and CMMS Config view shown below is the starting point for user administrators.

1. Navigate to Settings.
2. Open CMMS Config.
3. Verify that the correct CMMS integration is selected. The system automatically loads the default CMMS integration when the page opens.
4. Locate and select the CMMS field you wish to manage.
5. Scroll down to the Domain Values section of the field configuration.

The screenshot below shows the Settings page with CMMS Config selected, the CMMS integration selector, and the CMMS field list. Use this view to confirm the correct integration before selecting the field to manage.

The Domain Values section displays all values currently associated with the selected CMMS field and provides options to:

• Synchronize values from the connected CMMS.
• Export existing domain values.
• Import domain values from a CSV file.
• Add individual domain values manually.
• Delete selected domain values.

Note: If your environment contains multiple CMMS integrations, always confirm the correct integration is selected before making changes. Domain values are managed independently for each CMMS integration.

Downloading the CSV Template

If you do not already have a template:

1. Navigate to the field's Domain Values section.
2. Select Export Domain Values.

The exported file can be used as:

• A template for new imports.
• A backup of existing values.
• A starting point for bulk modifications.

CSV File Structure

The import file contains five columns. The name and value columns are required for all domain values. The external_value column should be populated as a best practice and may be required by certain CMMS integrations. The remaining columns are optional and should be populated only when needed.

name,value,external_value,parent_value,is_deleted

Required and Optional Columns

All column headers must be included in the CSV file, even when some values are blank.

Important: While only name and value are required for all records, it is strongly recommended that external_value always be populated. Some CMMS integrations depend on this value during field mapping and work order creation. When no alternate CMMS value is known, set external_value to the same value contained in the value column.

Column Definitions

Name

The label displayed to users throughout Virtual Facility.

Critical,Critical,Critical,,false

Value

The internal value stored by Virtual Facility. This is typically going to be the Primary Key (PK) value found in the CMMS database. In most cases, this matches the External Value field. 

Critical,Critical,Critical,,false

External Value

The value expected by the CMMS. This is typically going to be the Primary Key (PK) value found in the CMMS database. Unless otherwise known, set external_value equal to value.

Critical,Critical,PRIORITY_1,,false

Parent Value

Used when creating dependent or hierarchical domain values. It is used in conjunction with a defined Relationship.

Building A,Building A,BLDG_A,,false 
Floor 1,Floor 1,FLOOR_1,Building A,false

Is Deleted

Controls whether a value is available for use. Accepted values are true and false. This is a soft-delete and can be undone by simply setting this column to the opposite Boolean value, or changing the corresponding check box in the Domain Values table in the UI.

Legacy Status,Legacy Status,LEGACY,,true

Creating New Domain Values

1. Open the CSV template.
2. Add a row for each domain value.
3. Populate the required columns.
4. Populate external_value wherever possible. Unless a different CMMS value is required, set external_value equal to value.
5. Save the file in CSV format.

Example:

name,value,external_value,parent_value,is_deleted 
Critical,Critical,Critical,,false 
High,High,High,,false 
Medium,Medium,Medium,,false 
Low,Low,Low,,false

Importing the CSV File

The screenshot below shows the Domain Values section and highlights the Import Domain Values button used to upload the completed CSV file.

Tooltip note: An information tooltip icon appears next to the Domain Values action buttons near Import Domain Values. Hover over this icon to view summary guidance about the column headers when importing domain values.

1. Open the Domain Values section for the desired CMMS field.
2. Select Import Domain Values.
3. Browse to the completed CSV file.
4. Upload the file.
5. Review any validation messages.
6. Complete the import.

After the import finishes, the Domain Values grid refreshes and displays the imported values.

Updating Existing Domain Values

To modify existing values:

1. Export the current domain values.
2. Make the required changes in the CSV file.
3. Save the updated file.
4. Re-import the file using Import Domain Values.

This approach is recommended when updating many values simultaneously.

Working with Parent-Child Relationships

Parent-child relationships can be established through the parent_value column.

Example hierarchy:

name,value,external_value,parent_value,is_deleted 
Building A,Building A,BLDG_A,,false 
Floor 1,Floor 1,FLOOR_1,Building A,false 
Room 101,Room 101,RM101,Floor 1,false

Resulting structure:

Building A 
  Floor 1 
    Room 101

When importing hierarchical values:

• Parent values should exist before child values reference them.
• Parent values must match exactly.
• The referenced parent value must not be marked as deleted.

Validating Imported Values

After importing:

1. Refresh the Domain Values section.
2. Review the imported records.
3. Confirm parent-child relationships display correctly.
4. Verify that expected values appear in field mappings and configuration screens.

If values are missing or appear incorrectly, export the domain values and compare them against the source CSV.

Troubleshooting

Import Fails

Verify the following:

• The file is saved in CSV format.
• All required column headers exist.
• Column headers match the template exactly.
• No special formatting or hidden columns were introduced by spreadsheet software.

Parent Values Are Not Linked

Verify the following:

• The parent value exists.
• Parent values must match exactly.
• The parent value is not marked as deleted.

Duplicate Values Appear

Verify the following:

• Differences in capitalization.
• Extra spaces.
• Duplicate rows.
• Mismatched internal and external values.

Values Are Not Available in Mappings

Verify the following:

• The import completed successfully.
• The values are not marked as deleted.
• The correct CMMS integration and CMMS field were updated.
• Any required synchronization or refresh process has completed.