View Configuration

Define a New Field

If after examining the schema for existing fields in the Buildings, Floors, Rooms, Equipment, Equipment Standards, and Employees tables and finding that the stock schema does not meet your needs, you can create certain types of fields yourself. Fields that you create are known as user-defined fields. Within a view, user-defined fields operate the same as any field of its type; you can edit it, search on its values, hide and display it, and so on just as you would any stock field. This also applies to system administrator tasks, such as implementing REST API and Connectors; that is, any generic feature for Archibus fields is valid also for user-defined fields.

The following summarizes the tables and views that support user-defined fields.

Note: For information on users who have access to creating and editing user-defined fields, see View Configuration Overview: Security Groups for Configuring Fields.

Create or promote fields in this table	Using these views	Work with the user-defined and promoted fields in these views
Buildings	Define Locations	Define Locations
Floors	Define Locations	Define Locations
Rooms	Define Locations BIM Viewer	Define Locations Space Console
Employees	Define Employees	Define Employees Space Console
Equipment	Manage Equipment and Standards	Manage Equipment and Standards
Equipment Standards	Manage Equipment and Standards	Manage Equipment and Standards

Note: The Manage Equipment and Standards view enables you to create and promote fields, as well as access these fields in the view's grid. Other equipment-related consoles, such as the Asset Lifecycle Console, offer the Configure Fields button in the tabbed Equipment form and the ability to edit the newly created or promoted field from the Other Fields tab; however, you cannot access these fields in the Consoles' grids.

Defining a new field

The Add User-Defined Field form (below) presents the options required for defining a new field. First, you specify the Field Type. Depending on the type of field you specify, the form displays the appropriate options. You can specify the following types of fields, which are a subset the available field types and will not disrupt the existing Archibus database schema.

Field Type	Description
Enumeration	Provides a restricted list of values from which the user can choose a value to complete the field.
Text	The user completes with free-form text, up to the number of characters you specify in Size.
Number	An exact precision decimal number. You complete "Size" with the total digits and "Decimals" with the number of digits after the decimal point.
Integer	A whole number.
Date	A calendar date having a year, month, and date (ranging from the year 0001 to the year 9999).
Time	A time of day with hour, minute, second, and fractional seconds.

Complete the form, and Archibus creates a field definition in the Archibus Fields table. Archibus uses the value of the Field Heading that you entered to create a unique identifier, omitting spaces in the Field Heading and adding the prefix "udf." For example, if you enter "My Test" for the field heading, Archibus creates a field whose Field Code value is udf_mytest. As Archibus adds the field to the schema, it presents a message that the table is being updated.

If the options available from the Add User-Defined Field form do not meet your needs, you must define fields by working directly with the schema tables. For information, see Archibus Fields Table (System Management Help).

To add a new field to a database table

1. Load the Define Locations, Manage Equipment and Standards, or Define Employees view.
2. Use the view's tab to load the table to which you want to add a field.
3. Click on a field to access the Define form in the right panel.
4. In the right panel, click the Configure Fields button.
5. The view presents the Configure Fields form.
6. Click Add User-Defined Field
7. In the Add User-Defined Field form, enter the type of field by completing Field Type. See the above discussion of the field types.
8. Depending on the Field Type you choose, complete the following options on the Add-User Defined Field form:
   

   Option	Description	Option Applies to this Field Type
   Field Type	Choose from: Enumerated Text Number Integer Date Time The field types are described above.	All
   Field Heading	Enter the text that views use to display this field.	All
   Comments	Archibus automatically creates a comment by entering the current user who created this field and the current system date. You can add your own notes to this comment, such as the purpose of this field, why it was created, and so on. This type of documentation can be important for others working with the database. Users with access to viewing the entire afm_flds table can review the comment to understand the purpose and background of a field.	All
   Enumeration List	If you chose Enumerated for Field Type, complete this field withe the enumerated values that the user can select when completing the new field. For example, if you define an enumerated field of Room Pressure, you could enter values of Low, Medium, High. Separate each value with a semi-colon such as entering: Low;Medium;High The order in which you enter the values is the order they will display to the user in the pick list. After Archibus creates an enumerated field, you will notice in the Configure Fields form that the Enumeration List field value has duplicates of the values that you entered. For example, entering Low;Medium;High produces a value of Low;Low;Medium;Medium;HighHigh in the Enumeration List field. This is because the value reflects both the displayed value and the stored value. Unlike other Archibus tools for defining enumeration lists, such as the questionnaire features, you do not need to enter both the display value and stored value when working with user-defined fields; you enter only the display value and the view configuration logic automatically creates the corresponding stored value.	Enum
   Allow Null	If the user does not need to complete this field and is able to leave it empty, set this to Yes. If you want the user to complete this field in order to continue, set to No.	All
   Default Value	Enter the value that will serve as the default value. If you do not require a default value, leave this field empty.	Enum Text Number Integer
   Size	Enter the maximum number of characters this field can hold. For text fields, the maximum size is 512. For number fields, enter the number of characters for the field, including its decimal places. For example, if you want the user to be able to enter values up to 999.999, enter 6 and then enter 3 for Decimals, below.	Text Number
   Decimals	For number fields, enter the number of decimal places values can hold. For example, enter 4 if you want the user to be able to enter a value of 8.0375. The maximum value for this field is 4.	Number

9. Click Save. The system creates a new field in the Archibus Fields table with the properties you defined.
10. You are returned to the Configure Form, where your new field is automatically promoted and appears at the top of the grid.
11. Click Close to close the Configure Fields form.
12. To see your new field, reload the view. The view presents the field at the far right of the grid. If you click Add New or click on a record to edit it, you will see that the new field is listed at the bottom of the Define panel, displayed on the right.
    
    
    

Usage notes

• If an administrator does not have SYS-USRMGR, the interface will still present the Add User-Defined Field form; they can complete the form, but will not be able to save it.
• For cloud environments deployed on multiple servers, the System Administrator might need to restart the application server in order for the new user-defined field to appear on all instances.
• You may want to search for user-defined fields. For example, if you have sorted the Available Fields grid and your user-defined fields are no longer at the top, you might want to locate all of your user-defined fields. To do so, use the smart search console in the Available Fields grid. In the Is User Defined? column, choose User from the drop-down list. Choosing any other value for this column returns fields that are not user-defined. Although the grid displays Yes/No as the values, when using the smart search console, you search on User.
  

See Also

View Configuration: Overview

Modify a User-defined Field

Space Console: Working with User-Defined and Promoted Fields

Equipment: Other Fields tab