Example: Biological hierarchy

We explain how to build a hierarchy by working through an example. The example is to create a hierarchy to model the scientific classification of living things (biological taxonomy). The top three levels of this hierarchy are built with records created from business objects named Kingdom, Phylum, and Class.

Begin by creating a hierarchy module named Living Thing. The properties for the Living Thing module look like the following figure.

In the Living Thing module, create stand alone business objects named Living Thing, Kingdom, Phylum, and Class. Each of these business objects has a Text field named Name. In each business object's mapping information, the Name field is identified as containing the name of records that are created from the business object.

The permissible structure of the hierarchy is that Kingdom records can be under a Living Thing record, Phylum records can be under a Kingdom record, and Class records can be under a Phylum record. To specify this structure, specify the associations that are shown in the following figure.

As you are creating these associations, the Association Properties panel in the Data Modeler looks like the following figure.

The form for specifying an association's properties treats an Is Parent Of association specially. If you specify that the name on the near side of the association is Is Parent Of , the module of the business object on the other side of the association is forced to be the same as the module on the near side of the association. Also, the name on the far side of the association is forced to be Is Child Of.

After you save an Is Parent Of association, the Associate Business Object form is replaced with an Includes in Hierarchy form that looks like the following figure.

After you finish creating the business objects and associations, the next step is to create the forms you will use to edit records in the LivingThing hierarchy. Begin by creating a form to edit Class records, which is at the bottom of the hierarchy.

Phylum records will appear in the hierarchy as parents of Class records, so the next form to create is a form to edit Phylum records. After we have laid out the Phylum form in the Form Wizard's Layout tab, the next step is to specify what form will be used to create child records for a Phylum record.

To specify that the Class form that is used to edit Class records will be used to create and edit records under a Phylum record, navigate to the Includes/Forms tab of the Form Wizard. Initially, the Includes section of the Includes/Forms tab is empty and looks like the following figure.

To add a form to the Includes section, click the Add action on the Includes section bar. When you click the Add action, a panel pops up that allows you to select existing forms that can edit records that are allowed to appear in the hierarchy under the kind of record this form edits. The panel looks like the following figure.

In order to create records for this hierarchy, you will need to create a couple more items. First, you should create a manager query definition for a hierarchy using the Report Builder. Then you will need to create a navigation item for a master/detail hierarchy.

To create the manager query, navigate to My Reports. Select the System Reports sub-tab. Click New to create a new System Report. Click the Add Business Object link. Select the Living Thing Module, -All- Business Objects, and -All- Forms. Click Ok. Fill the remaining fields as shown in the following figure.

Select the Columns tab. Add the Name (triNameTX) field to the Display Columns. Select the Advanced tab. Click the Add action in the Association Filters section. Set the Module to -Any-, Business Object to All, Association Type to Is Parent Of, Reverse Association to No, and Filter Type to Record. Then type $$RECORDID$$ in the Record/Query field, as shown in the following figure. Click OK. Click Save & Close to save the query.

The final step is to add a navigation item to your menu so that you can create new records in your hierarchy. Before you do this, check your menu by going to the People record > Profile tab, as shown in the following figure. This will be the menu, also known as a navigation item collection, to modify. Note: Any change you make to this navigation item collection will affect all other users who have the same navigation item collection set as their menu. Make sure you are working in your own environment, or undo all changes at the end, or create a custom navigation item collection for this example. For more information, see Configuring the user experience.

.

Go to Tools > Navigation Builder. Select your menu and click Edit as shown in the following figure.

Now click Navigation Items Library on the bottom of the page. Click Add to create a new navigation item. Set the Name to Hierarchy - Living Things and Label to Living Things. Now set the Target Type to Master/Detail Hierarchy. Make sure to check the Modify Hierarchy check box. Then set the Hierarchy to Living Thing, the Query Module to Living Thing, and the Report to the query you just defined, as shown in the following figure. Click Save & Close.

The last step is to add the navigation item to your menu. Select your navigation item on the left panel and Landing Page - Portfolio on the right panel. Click Add to collection. If you now expand Landing Page - Portfolio, the new navigation item is there. Now click Save and Close, as shown in the following figure (the left side of the Navigation Builder).

And as shown in the following figure (the right side of the Navigation Builder), to save the changes to your menu. To update your menu, either refresh the browser, or sign out and sign back in.

Navigate to Portfolio > Living Things. As shown in the following figure, the Hierarchy is displayed in the left panel. It only contains the record that is the root of the hierarchy. The right panel displays all the records that the root Living Thing is a Parent of, currently none. Note that if you had not defined the query earlier and set it as the query for the navigation item, the right panel would show No queries defined; you would still be able to use the hierarchy to create and open records, however.

IBM Maximo Real Estate and Facilities automatically creates the root record of a hierarchy. The way that root records are created is unique. No pre-create workflow is run. Both the name and the state of the record is initially null, yet the record is saved in the database.

If you wanted to edit the record that is the root of the hierarchy, click the Open action. You should edit the root record of a new hierarchy if only to just set its name.

To add additional records to the hierarchy, click the New action. Clicking the New action causes a menu to appear that contains a list of the different kinds of records that can be added to the hierarchy. The menu looks like the following figure.

The kinds of records that appear in the menu are determined by the Is Parent Of associations you created in the Data Modeler and the Includes defined in the Form Builder. The LivingThings business object has an Is Parent Of association with only the Kingdom business object, so Kingdom is the only choice in the menu.

At this point, you can click Kingdom in the menu to create a new Kingdom record under the root of the hierarchy. If you change your mind about wanting to create a new Kingdom record under the hierarchy's root, click the x on the list to get rid of the list.

When you click Kingdom, a form appears in the details view for you to enter in the values of the new Kingdom record. After you click the form's Create action, the new Kingdom record appears in the hierarchy. Repeat this four times, to create records for all five of the biological kingdoms. The hierarchy now looks like the following figure.

You can add Phylum records under the Kingdom records in the hierarchy. To do this, first click the name of the Kingdom record you want the Phylum record to appear under. This causes the Kingdom record to become the selected record. If any record other than the root is selected, its name becomes red.

When you click the New action in the Hierarchy panel, it means that you are trying to create a new record under the selected record.

If you make the mistake of putting a record under the wrong member of the hierarchy, it is easily to fix the mistake by following these steps:

• Select the record you want to move to a different place in the hierarchy.
• Click the Cut action.
• Select the member of the hierarchy that you want the record to appear under. This has the effect of replacing the Cut action with a Paste action.
• Click the Paste action.