Linking Facilities and Departments

In iHRIS Manage, the module ihris-manage-PersonPosition defines the position form which contains the field department and the required field facilty which are both independent lists. In this tutorial, we will discuss how customize iHRIS Manage so that, when editing a position, the departments displayed are dependent on the facility chosen.

This tutorial applies to iHRIS Manage 4.0, although the concepts involved can be applied to iHRIS Qualify as well. Please refer to these articles:

• Defining Forms
• Forms and Form Classes

for background information on forms. You can see these changes in the Zanzibar-position module.

Overview

Our goal is to have the departments for a position to depend on the facility chosen for the position. There are two ways that one could do this.

Option A

To the department form, we could add a required field facility which links to the facility form. In this, way we would now have every department associated to a facility.

There are a few issues with this option:

• Suppose you have to hospitals, Central Hospital and Coastal Hospital. Each would presumably have a department such as Emergency. In this option, you would have to create an Emergency Department for each of the Hospitals. It would then make it difficult to run a report such as "list all employees in all facilities which work in the emergency department" because it really is "list all employees in all facilities which work in a department with the name Emergency." In particular, since we are entering "Emergency" multiple times, there is an increased potential for a spelling mistake which would affect data quality.
• At least for the moment, there is no built in way to first select a facility and then select a department within a form.

Due to these weaknesses, we will not implement Option A in this tutorial.

Option B

We could create a new list form facility_department which contains two required fields, facility and department which map the for lists of the same name. Then in the position form, we no longer link to the list facility or department but to the list facility_department. This has the following advantages over Option A:

• We only have to enter the department Emergency once as we can associate it to many facilities via the facility_department form
• As facility_department is a tiered list (first select a facility, and the select a department) we can use in the built in display methods when selecting the department in the position.

We will implement option B in this tutorial.

Turning off the existing fields

Let us first look at the changes to "turn off" the facility and department fields in the position form.

The position form is implemented by the class iHRIS_Position in the ihris-manage-PerosnPosition module. Instead of removing them from the existing iHRIS_Position form, we will specify them as not being required and not saved in the database. We also remove the reference to them in the html template files for position.

Magic Data/Configuration Changes

We will create a new form class My_Position which extends the iHRIS_Position form class and set the position form to use this class: <source lang='xml'>

<configurationGroup name='forms' path='/modules/forms/forms'>
  <configurationGroup name='position'>
       <displayName>Position</displayName>
       <description>The Position Form</description>
       <configuration name='class' values='single'>
         <displayName>Class Name</displayName>
         <description>The name of the class providing the form</description>
         <value>My_Position</value>
       </configuration>
     </configurationGroup>
</configurationGroup>
<configurationGroup name='forms' path='/modules/forms/formClasses'>
     <configurationGroup name='My_Position'>     
       <configuration name="extends">
         <displayName>The class this form extends</displayName>
         <value>iHRIS_Position</value>
       </configuration>
       <configurationGroup name="fields">
         <configurationGroup name="department">
           <displayName>The field 'department'</displayName>
           <configuration name='required' type='boolean'>
             <value>false</value>
           </configuration>
           <configuration name='in_db' type='boolean'>
             <value>false</value>
           </configuration>
         </configurationGroup>
         <configurationGroup name="facility">
           <displayName>The field 'department'</displayName>
           <configuration name='required' type='boolean'>
             <value>false</value>
           </configuration>
           <configuration name='in_db' type='boolean'>
             <value>false</value>
           </configuration>
         </configurationGroup>
     </configurationGroup>
</configurationGroup>

</source>

Reporting and Form Relationship

Because the form relationships have changed:

• Old: the position form links to the facility and department forms.
• New: the position form links to the facility_department form which in turn links to the facility and department forms.

our form relationship used to define the staff reports need to be changed. Rather than detailing these changes in this tutorial you may look at them here