Overview of the Forms Infrastructure and the Generic Form

This blog post is intended for developers and people doing advanced customizations in Service Manager.

An earlier blog post illustrated how to use the <Form> element in Service Manager's management pack infrastructure to create rich, custom forms for classes and relationships in the CMDB. Custom forms offer complete flexibility in displaying class and relationship information to end users, and they are well-suited to displaying data that spans multiple classes and relationships or requires unique UI elements.

When the data that needs to be displayed originates in an object of one class, presenting an editable table of property-value pairs is often sufficient. To prevent customers from having to develop these simple forms for each class added to a Service Manager installation, Service Manager ships with a Generic Form that renders a property-value display for any class that does not already appear in a custom form.

This blog post will provide background on the forms infrastructure used in our product and the options available to customize the Generic Form.

Part 1: Understanding the forms infrastructure

Let's take a look at the <Form> element tag in the ServiceManager.ConfigurationManagement.Library management pack that causes the computer form to display for computer objects in the console.

Each attribute in the Form tag indicates the following:

The Target attribute of the form tag links the form to a class or a type projection. When the user selects the "Create" task associated with a view or the "Edit" task associated with an object or object projection, the class to be created or edited is determined. Our UI code then looks for a form that is either (1) targeted to that class or (2) targeted to a type projection that has a seed that is that class. If a form is found, it is displayed. If a form is not found, the check is repeated on each of the parent classes until a form is found.

This logic is summarized in the Figure 1 below:

Figure 1: Form selection process

Note that a form is designated to appear in one of two modes:

1. Pop-out mode, the default, indicates that the form will surface when the "Create" task or the "Edit" task is clicked.

2. Preview mode, which is enabled by adding a category with a special enumeration value and targeting it to the form, indicates that the form will display in the details pane when an item in a grid view is selected.

The search that is performed to find a form for a given object (as depicted in Figure 1) is limited to forms in the desired display mode. For example, when a grid view item is selected, it is determined that a form in preview mode is needed and a search for a form is performed using only the set of forms categorized as preview forms.

The enumeration value used to demarcate a preview form resides in the Microsoft.EnterpriseManagement.ServiceManager.UI.Console management pack. The following category definition, for example, would mark the form named "ClassForm" as a preview form.

<Category ID="someuniqueID" Target="ClassForm" Value="Console!Microsoft.EnterpriseManagement.ServiceManager.UI.Console.OverviewForm" />

Preview and pop-out forms will always be found for a given class because preview and pop-out versions of the Generic Form are targeted to System.Entity, the root class in Service Manager's class model.

Part 2: The Generic Form

The Generic Form is a WPF UserControl that consists of up to three tabs:

1. A General tab displays all of the properties of the object that serves as the form's data context. If the data that underlies the form is a projection object, properties are displayed for the seed class object in that projection. Properties in the tab are grouped under their respective classes starting from the top of the class hierarchy (System.Entity) and moving down.

When the object displayed in the form inherits from System.ConfigItem or System.WorkItem:

2. A Related Items tab presents an updatable display of objects related to the object, and

3. A History tab chronicles the changes that have been made to properties on the object and the object’s relationships to other objects.

There are two display modes for the Generic Form. The Generic Preview Form displays property information for the currently selected object in a grid view. Alternatively, the Generic Pop-Out Form displays property information when a class object or projection object is displayed within a form window. These two display modes are juxtaposed below (click to enlarge):

Figure 2: Generic Form displaying a Software Item object in preview mode (left) and pop-out mode (right)

Note that in preview mode, no related items tab or history tab is shown, and the properties in the form are not editable.

The Generic Form appears in four management pack form element (i.e.: <Form> tag) definitions. A preview form and a pop-out form are targeted to the System.Entity base class, one pop-out form is targeted to a type projection with seed class System.ConfigItem, and one pop-out form is targeted to a type projection with seed class System.WorkItem. The pop-out form definitions targeted to the Configuration Item and Work Item type projections are used to populate the Related Items Tab with a standard set of related objects on Configuration Item and Work Item classes.

This is summarized in Figure 3 below.

Figure 3: Occurrence of Generic Form <Form> elements in the class model

Part 3: The Extension Tab

When a pop-out form is displayed in a form window using the Create task or the Edit task, a check is made to determine:

1. The class of the object being displayed, and

2. The class to which the form that is being displayed is targeted.

These classes can differ if the form that was selected to display an object is targeted to one of the parent classes of that object (e.g.: displaying an object of a class derived from Change Request in the Change Request form).

If the form that is being displayed is a custom form and is not the Generic Form (which, by default, displays all of an object's properties in the General tab), and classes 1 and 2 differ, an Extension tab is added to the custom form. This tab displays property-value pairs for all classes in the object's class hierarchy that inherit from the form's target class.

The tab also displays (again, only for custom forms) all of the properties of any extension classes in the class hierarchy of the object. These properties are grouped under the extended class.

Suppose, for example, that a sealed MP were imported with class definitions below: