Overview

Generally, the CMMS Configuration is performed during your implementation, but administrators may make changes to field configurations so the integration stays aligned to changes made within Virtual Facility or their CMMS.

System connectivity must be performed by the onboarding engineer. Once configured, the integration will be visible under the system list displayed when the Integration icon is clicked. This can be found at the top right on any page in the app (excluding the settings page) to the right of the search bar and looks like an electrical plug icon. Once you click on the icon, a list of all the systems that have been integrated will appear. The CMMS will be listed in addition to any alarm sources. Each system is shown with their current connectivity status.

CMMS field configurations are visible under the Settings page for any user with the role of Admin. Clients with multiple CMMS integrations can select the specific integration they want to configure using the selector field found at the top left of the field table.

Field Configuration

CMMS Fields must be configured so users can enter them as part of work creation or view them on created work tickets. Some configurations are common to every field type and some are specific to certain field types. In this section of the article, we will go through those common, or general, configurations first before we address the specifics of each field type.

General Field Configurations

Referencing the image at the end of this section, the primary attributes of a field are as follows:

• Name: This is the name of the field used by the API. It may not be the same as the display Title. The name is set by the API and can not be changed.
• Title: This is the name of the field as displayed in Virtual Facility. Usually, this attribute will populate automatically by the API during the initial integration process. However, it is best practice to align this title to the field title displayed in the CMMS interface if it is not the same already. This helps the user to understand what the field represents when they are working in Virtual Facility.
• Data Type: The field data type is usually set by the CMMS and often determines the specific configuration steps for each field. More details about the field data type can be found in the next section.
• Description: This is a plain English description of the field and possibly how to use it within the CMMS. If this is not set by the CMMS, it can be updated in Virtual Facility to provide some amount of documentation about the field.
• Display Template: This how the display of the field domain values are controlled within Virtual Facility.
• Default Value: The default value of a field. This makes the creation of the work ticket easier and faster for the user.
• Max Length: For certain field data types, there is a limit on the number of characters that the API will accept as valid values for the field. This will be addressed in more detail under the applicable field data types in the next section.
• Create Display Order: This is the relative position of the field as it is displayed within work creation slideout in the VF app. Field positions are labeled from left to right, top to bottom. In other words, the top left position is 1, the top right is 2. Second row, left position is 3, right position is 4. And so on.
• Normalized Field: This is used to map a CMMS field to a normalized Virtual Facility work field. This is used to make standardized report configurations possible regardless of the CMMS platform(s) used by a client. For more information, contact your Client Success Manager.
• View Display Order: This is the relative position of the field as it is displayed within view work slideout (i.e., once the work ticket is already synced with the CMMS) in Virtual Facility. Field positions are labeled from left to right, top to bottom. In other words, the top left position is 1, the top right is 2. Second row, left position is 3, right position is 4. And so on.
• Show in Create Work: This determines if the field is shown (visible) in the work creation slideout (or automation rules). This is one of the two settings that will determine if a field is sent to the CMMS during work creation. You should only have one of these two settings enabled for each field. Enabling this setting also enables the Create Display Order configuration.
• Hidden Create Work Field: If this is selected, the field will be hidden (not visible) in the work creation slideout. This is one of the two settings that will determine if a field is sent to the CMMS during work creation. You should only have one of these two settings enabled for each field.
• Required: If this is selected, the field will be required to be filled out before Virtual Facility will sync the work ticket to the CMMS. This applies to the work creation slideout and automation rules. Sometimes this will be enabled due to field attributes as defined by the API during initial integration. It is best practice to enable this setting if the field is to be used and the field is required in the CMMS UI. Optionally, it can be enabled for any other field that the client wants to require of the users (i.e., process requirement vs software requirement).
• Readonly: Selecting this restricts the user from being able to edit the field's value in the work creation slideout or automation rules. This setting only has purpose when used in conjunction with Show in Create Work which will display the default value (or mapped values) to the user but will not permit editing.
• Show Field: This enables the field to be displayed in the view work slideout. Enabling this setting also enables the View Display Order configuration.
• Save on Create Work: This setting controls whether an entered value during work creation will be saved as the mapped value for this CMMS field for the alarm(s) that the work was created from. However, in order for this configuration to work, the global setting must also be enabled. Contact your Client Success Manager for more details.
• Delete: If enabled, this will treat the field as deleted (without actually deleting it from the CMMS admin settings) and will not display it in the VF app. 
• Automatically Sync Field Values: This setting only affects the List field data type and enables the automatic (daily) sync with the API to update the domain values for the field. More details on the domain values can be found in the Specific Field Type Configurations for the List type below.
• Additional settings become available when a field is mapped. Contact your Client Success Manager for more information.

Field Data Types

Data types are generally determined automatically during configuration. Each type is described below.

Boolean

Booleans are a field type that can only have the values of TRUE or FALSE. These will be represented on the work creation slideout as a checkbox.

Date Time

This field type is used to pass date and time data to/from the CMMS. Typically, a dynamic template variable will be defined as the default value for this field instead of requiring the user to enter the data. This ensures that the date-time data gets sent over in the correct format for the CMMS.

Number

This is the least common field type to be used. It is a form of a free text field that only accepts numerical values and will have a defined maximum length specified by the CMMS. Typically, these fields are used for cost entries or labor hours when the work is completed and are not often used during work creation.

String

A string is a free text field that can accept any combination of letters, numbers, and symbols. However, it is limited to no more than 255 characters, depending on the specific field.

Text Area

This field type is the least restrictive free text field. Just like a string, it can accept any combination of letters, numbers, and symbols. The specific character limit for a given field will be determined by the CMMS, but these fields will typically accept thousands of characters.

List

This is the most commonly used field type. This type is used when multiple, specific values are required to be selected from by the user. The data in this field type will appear in a table in the admin app under the main configuration section for the field. This data will typically be synced from the CMMS, but may also be uploaded manually. The data may also be configured to sync automatically on a nightly basis to ensure the most up-to-date values are available to the user.

When creating a work ticket in the solution, these field values will appear in the respective field's drop-down list for the user to pick from. No other data entry (i.e., free text entry) is permitted in these fields.

Specific Field Type Configurations

Boolean

When configuring a Boolean field, it is best practice to define a Default value. This eliminates the chance that the CMMS may misinterpret a null value, or reject the ticket creation altogether.

TRUE and FALSE are the only default values that can be used in a Boolean field. (In the UI, the field will appear as a check-box.)

Date Time

Generally, a dynamic template variable will be defined as the default value for a field of this field type instead of requiring the user to enter the data. 

• Date-time data are structured in the ISO format (YYYY-MM-DDTHH:mm:ss.sssZ).
• Date data are structured in the following format: YYYY-MM-DD
• Time data are structured in 24-hour format (HH:MM). Some fields will accept only local time. Some fields will only accept UTC. This is CMMS and field specific.

Number

The max length will generally be defined by the CMMS for any field of this field type. In cases where cost is entered into the field, some systems will accept a decimal point in the value, but others will not. Because these fields are not often used during work creation, a default value will seldom be configured.

String

The max length for a field of this field type will generally be 255 characters or less, unless specifically limited further by the CMMS. Default values will often be configured for this field type because of its diverse usage.

Text Area

The max length will be defined by the CMMS for any field of this type. Typically, it will be several thousand characters. All types of characters are accepted in a Text Area. 

As a best practice, if the API doesn't provide a Max Length when the field is pulled (which is a common problem), you should test the field's character limit within the CMMS UI and then define that limit in the field configuration. This will prevent a user from entering too much data in the VF interface without realizing it and then have the API truncate the text in the CMMS.

List

A list field will often have default value configured, but this is very dependent on the specific usage of the field. Max character length is not utilized by this field type and will never be set by the CMMS API, unlike some other field types.

As the most commonly used field type, Lists are very important to configure correctly. However, they are often the most complex to configure. To properly configure a List field, there is at least one additional step that other field types don't require.

Domain Values

A List field functions off a list of domain values, or the possible values the field can accept. These are displayed in a table, and can be filtered and reconfigured similar to most other tables found within the solution. Pagination controls are found at the bottom right of the table. Above the domain values table and the buttons can be found a sync monitor. This will list the last time the domain values have been updated and who it was done by.

There are three possible ways to get these domain values loaded. The first method is the preferred method and is to get the values from the CMMS directly through the API. This can be accomplished by clicking on the "Sync Domain Values" button on the left side of the slideout. Depending on the number of domain values and the connection speed between the API and the VF server, this could take as much as a few minutes to complete. (If you don't see the values after a few minutes, close the slideout and re-open it. This will refresh the table of domain values.)

The second method is to Import Domain Values using a CSV upload file. This method should only be used if there is no way to use the Sync Domain Values function, or you need to configure a Parent Value for filtering (restricting) the values shown within the field's drop-down list in the work creation slideout of the app. This method will cause the "Is Manually Added?" column in the table to be checked for each domain value uploaded. For more on Importing Domain Values, contact your Clients Success Manager. 

The third method is to add the domain values manually. This method should only be used under the same conditions as the Import method (CSV upload). The best practice for this method is to only use it when there are only a few domain values to add. Otherwise, it is much more efficient to use the Import method. This method will cause the "Is Manually Added?" column in the table to be checked for each domain value manually added.

If for some reason you need to delete the domain values you've loaded, there are two methods. First, if you want to get rid of all the domain values, then click the red "Delete Values" button. If you only need to get rid of some values, then check the box under the "Is Deleted?" column on the value's row. This will remove the value from the drop-down list in the work creation slideout, but retains the value within the field's domain. This permits the ability to add the value back (by unchecking the box) and prevents the value from being added back during the daily auto-syncs.

Parent Relationships

Parent Relationships are used to link one CMMS field to another for the purpose of filtering down domain values. An example of this is shown in the image above. The parent value column for each domain value contains "Air Handler". Whenever the linked field contains the value of "Air Handler", only the corresponding domain values will be shown as options in this field's dropdown list in the work creation slideout.

In order to link the two CMMS fields together, the relationship needs to be defined. At the bottom of the field configuration slideout is a short section called "Relations". Click on the blue button labeled "Add Relation".

This will open a modal in which the Parent Field can be defined. Click into the empty field and a dropdown list of all available CMMS fields will be shown.

Select the appropriate Parent Field. Once this is done, the blue "Add Relation" button below will activate. Click on the button to complete the relationship definition and return you to the main CMMS field slideout.

Once you are back on the slideout, you will see the Parent Field displayed under the Relations section. Beside the Parent Field is a trashcan icon. If you need to delete the relationship for any reason, click the trashcan icon and confirm your deletion.

Mappings & Translations

A CMMS field mapping is configured when the CMMS field value is dependent upon the value of another data field in the VF solution. This could be another CMMS attribute, an alarm attribute, or the state of a work ticket. Once the mapping from an attribute to the CMMS field is established, then translations are required to define what each specific attribute value means for the CMMS field. Translations can be uploaded in bulk with a CSV file or they can be manually added one at a time in the slideout translations interface.

The "Mappings" section can be found at the bottom of the field configuration slideout just above the "Relations" section. 

Once a mapping is configured, additional settings become available above the domain values table to further control the mapping. For more on Mapping & Translations, contact your Client Success Manager.

Template Variables

Template Variables are used to dynamically link data from the alarm or the VF work ticket to the CMMS field. They can only be used in field types Date Time, String, and Text Area. Multiple Template Variables can be used within a single field. While they can be added manually within a field during manual work creation or in an automation rule, typically they will be used in the Default Value for a field. See examples below.

For a detailed list of the available Template Variables, contact your Client Success Manager.