[A companion article to CMMS Integration Field Configuration. This article covers only how to map/translate Virtual Facility (VF) values to CMMS values. For setting up the CMMS Configuration tab and syncing a field's Domain Values, see the main article.]
Overview
Many CMMS platforms require specific status codes, priorities, categories, shops, or other field values. Because those values may differ from the values used within Virtual Facility, administrators can configure mappings and translations to automatically convert VF values into the values expected by the CMMS.
Together, mappings and translations allow Virtual Facility to transform internal values into CMMS-compatible values during ticket creation and synchronization.
Understanding the Difference Between Mappings and Translations
A common point of confusion is the relationship between a mapping and a translation:
- A mapping is the overall configuration that connects a VF field to a CMMS field, and contains a collection of one or more translations for the CMMS field domain value(s).
- A translation is an individual conversion rule within that mapping.
Translation
A translation is a single value conversion rule. The purpose of a translation is to associate an internal VF value with a specific external CMMS value.
Examples of Individual Translations
| Virtual Facility Value | CMMS Value |
|---|---|
| OPEN | Open Work Order |
| CLOSED | Complete |
| HVAC Shop | HVAC |
| Electrical Shop | ELEC |
Each row above represents a single translation rule. When an administrator selects Add Translation, they are creating one translation entry under the mapping.
Translations are configured to go one of two directions: Internal to External (the most common direction), or External to Internal.
Mapping
A mapping is the complete collection of translations configured for a field. It also defines which VF attribute/field corresponds to the CMMS field.
The Mappings section within a CMMS Field Configuration is where all translations for a field are maintained.
Note: Only one mapping can be defined per CMMS field.
How They Work Together
Whenever Virtual Facility sends information to a CMMS:
- VF identifies the Internal VF Value based upon the defined mapping.
- VF searches the field's mapping for a matching translation.
- The appropriate CMMS value is retrieved.
- The translated value is sent to the CMMS.
Example
| Component | Example |
|---|---|
| Mapping | Shop Mapping |
| Translation #1 | HVAC Shop → HVAC |
| Translation #2 | Electrical Shop → ELEC |
| Translation #3 | Plumbing Shop → PLMB |
In this example, Shop is the mapping to the CMMS field, while each individual value conversion represents a translation contained within that mapping.
Simple Analogy
Think of it like a dictionary:
- Mapping = a single dictionary entry
- Translation = a single definition found under that entry
Administrators build mappings by creating translations one at a time. Virtual Facility then evaluates the complete mapping whenever it needs to determine what value should be transmitted to the CMMS.
Internal Values vs. CMMS Values
Mappings always consist of two value types:
Internal (VF) Values
Internal values are the alarm/asset values recognized and stored by Virtual Facility.
For example, Virtual Facility provides two built-in values for work state:
- OPEN
- CLOSED
As with all VF and CMMS values, these values are case-sensitive. They should be entered in all capital letters when configuring status mappings. Other values may not be all capital letters, so careful attention should paid to the values when building the translations.
External (CMMS) Values
External values are the corresponding values expected by the target CMMS.
Once again, these values are case-sensitive.
Sources of Internal Values
Alarm Attribute Mappings
For most other field types, the Internal Value is derived from alarm attributes within Virtual Facility.
Examples include:
- Shop
- Category
- Priority
- Building
- Other alarm-derived attributes
The available values depend on the alarm data present within the customer's Virtual Facility environment.
CMMS Attribute Mappings
On rare occasions, it may be helpful to map one CMMS field to another. This is configured in the same way as the other mappings.
Work State Mappings
Work state mappings use Virtual Facility system values:
- OPEN
- CLOSED
These mappings are used to synchronize ticket status information between the CMMS and Virtual Facility. No other values of work state are recognized.
Configuring a Mapping
- Navigate to the CMMS Configuration tab on the Settings page.
- Select the CMMS field that requires value translation.
- Verify that the field is configured as a List data type.
- Synchronize domain values from the CMMS, if supported by the integration, so that the latest CMMS values are available.
- Scroll down to the Mappings section for the selected field.
- Click on Add Mapping. This will open a modal to interact with in the middle of the screen.
- Select Alarm Attribute (r one of the other choices) from the Internal Type drop-down.
- Review the available alarm attributes and select one for the mapping.
- Save the mapping configuration by clicking on the Add Mapping button at the bottom right of the modal.
Mapping Configuration Example
Consider a Priority field where Virtual Facility uses descriptive values but the CMMS requires abbreviated codes.
| Internal VF Value | CMMS Value |
|---|---|
| High Priority | P1 |
| Medium Priority | P2 |
| Low Priority | P3 |
The table above represents a mapping for the VF Alarm Priority field to CMMS Priority field. Each row is an individual translation, while the complete set of translations represents the mapping configuration.
Configuring a (Standard) Translation
Once a mapping has been identified for a field, administrators can create individual translations within that mapping. Each translation defines how a single Virtual Facility value should be converted into a corresponding CMMS value.
To create a translation (skip to step 6 if you are simply continuing from creating the mapping):
- Navigate to the CMMS Configuration tab on the Settings page.
- Select the CMMS field that requires value translation.
- Verify that the field is configured as a List data type.
- Synchronize domain values from the CMMS, if supported by the integration, so that the latest CMMS values are available.
- Scroll down to the Mappings section for the selected field.
- Select Add Translation. This will open a modal to interact with in the middle of the screen.
- Specify Translation Direction. Typically, this will be "Internal to External" unless translating CMMS work status to VF work state.
- Specify the Operator. Typically, this will be "Equals".
- Specify the Internal Value (VF value).
- Select the corresponding CMMS value. If no value is displayed in the drop-down, repeat step 4.
- Save the translation by clicking on Add Value button at the bottom right of the modal.
Once created, translation entries can be modified directly within the mapping table if updates are required.
There is one caveat to the standard translation configuration. You can configure dynamic template variables as the external value for date fields. As this is a hybrid configuration that requires a very specific configuration for the domain values as well as the translations, please speak with your Client Success team for support with setting this up.
Configuring a Direct Translation
In some situations, it is easier to configure a direct translation than a standard translation. A direct translation can be used only when one of the following is true:
- The VF alarm attribute values are the same as the CMMS domain values for a given CMMS field.
- The VF alarm attribute values are the same as the names of CMMS domain values for a given CMMS field.
When one of these is true of the data, then a direct translation to names or values can be configured using one of the checkboxes shown below. If the VF alarm data does not conform to one of these two scenarios, you must use the standard translation process as described in the previous section.
If you are considering using this feature, please review the guidance for creating inventories and uploading inventories. This is the most efficient way to align the VF alarm data to the CMMS values.
Please note: The mapping must be set up first before the direct translation checkboxes will even become visible/enabled in the slideout for you to utilize.
Bulk Upload of Translations
Up to this point in the article, we've discussed how to create translations with the manual configuration process. You can also use the upload feature to configure the translations in bulk. To do this, create a CSV file with the column headers in the following order:
- internalValue - put the VF value in this column
- externalValue - put the CMMS value in this column
- translationDirection - use one of the following values for each translation: INTERNAL_TO_EXTERNAL or EXTERNAL_TO_INTERNAL
Each row of the CSV file will represent one translation. As with the prior instructions, be sure that you pay attention to the case of each value.
After you set the mapping, then you can upload the translations using the Upload Mappings button. After you receive the confirmation toaster (bottom left of the browser window), exit out of the CMMS field slideout and then back in to refresh the translations table. At this point, you can confirm the translations in the table. You are still able to edit translations in the table, or add additional translations manually in the manner described in the previous sections.
Exporting Translations
In some circumstances, you may want to export a copy of your translations. You can easily do so by utilizing the Export Translations button under the mapping section. This button can be seen in the image above.
Deleting Translations
If for any reason you want to delete the translations, there are two ways to do this.
- To delete an individual translation, click on the trash can icon found on the right end of the table row corresponding to the translation.
- To delete all translations for that CMMS field, click on the red button labeled Delete Translations.
Populating Mapped Fields within Automated Work Tickets
Mappings are commonly used together with automation rules.
When a field is configured to populate from an alarm attribute in an automation rule:
- Virtual Facility retrieves the alarm attribute value.
- The mapping is evaluated.
- The matching translation is identified.
- The translated CMMS value is applied.
- The translated value is included in the outgoing work order.
This process helps ensure consistent CMMS data while minimizing manual data entry.
Best Practices
Configure Work State Mappings Early
Ensure OPEN and CLOSED mappings are configured and validated before testing ticket creation and ticket closure workflows.
When supported by the integration, synchronize domain values before creating translations so that the latest CMMS values are available.
Validate Every Translation
After creating translations:
- Use the CMMS Config tab on the alarm slideout to preview the effect(s) of the translation(s).
- If you feel a more thorough validation is required, create a test work ticket.
- Then verify translated values within the CMMS.
- Confirm that building, status, category, shop, priority, and/or other mapped values are received correctly.
Use the Bulk Upload Feature for Translations
If you have more than a handful of translations to configure, it is much easier to create the CSV to upload than it is to create each one manually.
Standardize Alarm Attributes
Consistent alarm attribute values improve translation accuracy, simplify administration, and reduce mapping maintenance requirements.
Troubleshooting
OPEN or CLOSED State Is Not Translating from CMMS Status
Verify that:
- OPEN and CLOSED are entered using the expected VF values.
- A translation exists for each CMMS status and uses the translation direction of "EXTERNAL_TO_INTERNAL".
- The CMMS status value(s) is/are valid.
Expected Value Does Not Appear in the Mapping List
Verify that:
- Domain values have been synchronized.
- The value is not marked as deleted.
- The field is configured as a List type.
Incorrect CMMS Value Is Received
Verify that:
- The appropriate translation exists.
- The translation is associated with the correct internal VF value.
- CMMS domain values have not changed since the mapping was configured.