Programmer's Guide:
Using Custom Fields

Custom Fields are customer-defined metadata which can be associated with Principal Items in a Facility. Facility administrators define the Custom Fields which are valid in a facility, and regular eRoom users can then assign values for those Custom Fields to any Principal Item in the Facility.

Defining Custom Fields

Custom Fields are defined at the Facility level. In SAAPI this is done by working with Custom Field Definition objects via the IERUCustomFieldDefManager interface of a Facility object. From this interface you can get the collection of current Custom Field Definitions, Create a new Custom Field Definition or adjust the ordering of the Custom Field Definitions.

A Custom Field Definition object stores schema information for a Custom Field. In SAAPI terminology, a Custom Field is a single metadatum value associated with a particular Principal Item. You can only assign a Custom Field value to a Principal Item if a corresponding Custom Field Definition has been created at the Facility level.

The following code creates a Custom Field Definition named "Priority", of type erCustomFieldDataTypeDropDown, with possible values "High", "Medium" and "Low".

Dim Facility as IERUFacility
Dim CFDManager as IERUCustomFieldDefManager
Dim CFDID as Long
Dim CFD as IERUCustomFieldDef
Dim Priorities(2)

' ...assume Facility has already been assigned
Set CFDManager = Facility.CustomFieldDefManager
Set CFD = CFDManager.CreateCustomFieldDef("Priority", _
   erCustomFieldDataTypeDropDown)
Priorities(0) = "High"
Priorities(1) = "Medium"
Priorities(2) = "Low"
CFD.Choices = Priorities

CFDID = CFD.ID 'remember the Custom Field Def ID for later use (see below)

Getting/Setting Custom Field Values on Principal Items

Custom Field values are stored in Custom Field Set objects. Every Principal Item has a Custom Field Set, and in each Custom Field Set, there is one Custom Field for each Custom Field Definition defined for the Facility. Note that this is true for all Principal Items regardless of whether anyone has explicitly assigned Custom Field values to them. If the Facility has three Custom Field Definitions, then each Principal Item has a Custom Field Set with three Custom Fields in it. If a Custom Field has not been assigned a value, it's HasValue property will be FALSE, otherwise, it's value will be stored in its Content property.

When assigning Custom Field values, you modify the Custom Field objects in a Custom Field Set as you wish, then commit the changes using the Update method of IERUCustomFieldSet. Until and unless you call Update, your changes are not applied. You can cancel pending changes and restore the original values into your Custom Field objects by calling the Revert method of IERUCustomFieldSet.

The following code sets the "Priority" Custom Field of a particular Principal Item to "Low".

Dim Room as IERURoom
Dim PrincItem as IERUPrincipalItem
Dim CFSet as IERUCustomFieldSet
Dim CF as IERUCustomField
Set Room = Facility.GetRoom("MyRoom")
Set PrincItem = Room.HomePage.Container("MyNote")
Set CFSet = PrincItem.CustomFieldSet
Set CF = CFSet.GetCustomFieldByID(CFDID) ' use saved ID from previous code sample
CF.Content = "Low"
CFSet.Update

Each Custom Field on a Principal Item has a reference to the Custom Field Definition that corresponds to it &endash; you can get to it via the CustomFieldDef property of IERUCustomField. Note also that you can look up a Custom Field in a Custom Field Set by using the ID of its corresponding CustomFieldDef, or by iterating through the collection of Custom Fields stored in the CustomFields property of IERUCustomFieldSet.

Searching based on Custom Fields

You can search for items in a Room or Facility based on the Custom Field values assigned to them. This is done through the IERUSearchCriteria interface of the Room Searcher or Facility Searcher objects. To add a custom field search criteria to a search, call the SetCustomFieldCriterion method. To clear the set of custom field criteria already stored in a Searcher object, use the ClearCustomFieldCriteria method. To get the list of custom field criteria stored in a Searcher object, get the CustomFieldCriteria property, which returns a collection of Custom Field Criterion objects, which implement the interface IERUCustomFieldCriterion.

The following code shows how to search for objects whose "Priority" custom field is set to "Low":

Dim RoomSearcher as IERURoomSearcher
Dim SearchCrit as IERUSearchCriteria
Dim Results as IERUCollection

Set RoomSearcher = Room.Searcher
Set SearchCrit = RoomSearcher
SearchCrit.SetCustomFieldCriterion("Priority", erOperEqual, "Low")
Set Results = RoomSearcher.Execute