Provider Registry -- Adding an e-mail field: Difference between revisions

From IHRIS Wiki
No edit summary
No edit summary
Line 16: Line 16:
In addition to modifying the data store, we will need to modify the user interface. The user interface is based on the I2CE Framework and the iHRIS platform.&nbsp; <br>  
In addition to modifying the data store, we will need to modify the user interface. The user interface is based on the I2CE Framework and the iHRIS platform.&nbsp; <br>  


The I2CE&nbsp;form data model that we will be modifying is represented here:  
The I2CE&nbsp;form data model that we will be modifying is represented here (click to get the full size image):  


[[Image:Pr forms.gif|1200px]]  
[[Image:Pr forms.gif|1200px|Pr forms.gif]]  


<br>  
<br>


== LDAP  ==
== LDAP  ==

Revision as of 10:17, 4 September 2012

In this article, we explain how to add the e-mail field to the provider registry.

This article was written based on revision 73 of the RHEA Provider Registry source code

Before going through this tutorial, it is suggested that you are already familiar with the following material:


Overview

The provider registry is storing provider data in an LDAP server, openLDAP -- this is our "data store".

In addition to modifying the data store, we will need to modify the user interface. The user interface is based on the I2CE Framework and the iHRIS platform. 

The I2CE form data model that we will be modifying is represented here (click to get the full size image):

Pr forms.gif


LDAP

For LDAP we have a schema that describes how the data that is stored on the LDAP server. The provider registry has two main things defined in the schema, the providerPerson and providerPost.

In the above data model, the providerPerson is the "person" form and the providerPost is the "post"

As we want to add an e-mail address, we need to decide where we want to add the e-mail address in the data model.  As the e-mail address does not change depening on the posting, it makes sense to add it to the providerPerson


providerPerson schema

You should recall from the Provider Registry on-line course that the providerPerson objectclass has the following schema:

objectclass ( 2.25.128424792425578037463837247958458780699.1  
    NAME 'providerPerson'  
    DESC 'providerPerson'  
    SUP inetOrgPerson  
    STRUCTURAL  
    MUST  ( nid  )
    MAY  ( dateOfBirth $ mutuelle $ csr $ passport $ countryName   $ locationCode )   ) 

The line with "MUST" tells us that the providerPerson has a required field of national id (nid). The line with "MAY" some optional data fields (attributes in LDAP terminology). The line with "SUP" tells us that the providerPost inherits the definition of the "inetOrgPerson" objectclass.

Let us look at the inetOrgPerson (internet organizational person) object class:

objectclass     ( 2.16.840.1.113730.3.2.2
    NAME 'inetOrgPerson'
        DESC 'RFC2798: Internet Organizational Person'
    SUP organizationalPerson
    STRUCTURAL
        MAY (
                audio $ businessCategory $ carLicense $ departmentNumber $
                displayName $ employeeNumber $ employeeType $ givenName $
                homePhone $ homePostalAddress $ initials $ jpegPhoto $
                labeledURI $ mail $ manager $ mobile $ o $ pager $
                photo $ roomNumber $ secretary $ uid $ userCertificate $
                x500uniqueIdentifier $ preferredLanguage $
                userSMIMECertificate $ userPKCS12 )
        )

Looking through the optional fields for the inetOrgPerson, we see a an attribute "mail" that we may be able to use. So let's investigate this.

A good website for looking up LDAP documentation is www.zytrax.com. Here we can find the inetOrgPerson schema. If you click on the "mail" attribute on this page, you will be take to the definition of the mail attribute:

attributetype ( 0.9.2342.19200300.100.1.3
   NAME ( 'mail' 'rfc822Mailbox' )
   DESC 'RFC1274: RFC822 Mailbox'
   EQUALITY caseIgnoreIA5Match
   SUBSTR caseIgnoreIA5SubstringsMatch
   SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} )

We see here that the mail attribute is the same as a RFC 822 Mailbox, which is the standard for email addresses.

So we are in luck! There is an e-mail address attribute already in our LDAP providerPerson

Schema Locations

If you want to look in more detail at the LDAP schema files on your file system, then (on an Ubuntu system) the inetOrgPerson object class is defined in the file /etc/ldap/schema/inetorgperson.schema.

The providerPerson object class is defined in the prrovider registry source code here. Note, that with the installation instructions for the provider registry we have copied this file over to the /etc/ldap/schema directory.

I2CE Form Model

Now that we know we already have a place to store the email address in our LDAP data model, we need to make sure the email address available in the User Interface which is based on the I2CE and iHRIS platform.

In this section, we assume some familiarity with form and magic data.


RW_PRPerson Form Class

The form class, RW_PRPerson is used to define the provider's data model in the user interface. In the above diagram we see that there are the following fields:

  • firstname: It has a label (header) Anglo/French Name and is a STRING_LINE
  • surname: It has a label "Rwandan Name" and is also a STRING_LINE
  • othername: It has a a label "Other Names," is also a STRING_LINE, although it is not included in our .html templates (see below)
  • nationality: It has a label "Nationality" and is a MAP field, mapping to the country form
  • residence: It has a label "Residence" and is a MAP field, mapping to the county (Sector) or district forms

We also see the fields for the various identifiers such as NID, CSR, Mutuelle, and Passport number.

We will need to add one for e-mail address. An e-mail address will simply be a line of text for the purposes of the user interface. In the I2CE language, this is a STRING_LINE and we will use the header "E-Mail".

Configuration File

We need to define this email field in the provider-registry-site-rwanda module revision 73 of the configuration file. The version of this module is 4.1.0.82, so as we are adding new data, we will need to increase the version to 4.1.0.83 on 12.

Now we need to add the email field to the Rwanda_PRPerson form class which begins its definition on line 138. We will insert the following on line 144 <source lang="xml"> <configurationGroup name='email'>

 <version>4.1.0.83</version>
 <configuration name="formfield">
   <value>STRING_LINE</value>
 </configuration>
 <configuration name="headers" type="delimited" locale="en_US">
   <value>default:E-Mail</value>
 </configuration>

</configurationGroup> </source> We have now registered the new field with our I2CE/iHRIS data model.

Note that when you browse to your site, it will start to update the site loading in the above to magic data, but don't do that yet!

Linking LDAP and I2CE (Read)

In the above step, we added the email field to the I2CE data model. We still need to link the I2CE data model to the LDAP model and its email field. There are two places we need to do this -- one place to read the email address from the LDAP email attribute, and one place to save the email address from the User Interface into the LDAP data store.

Linking LDAP and I2CE (Write)

HTML Template File (View)

There are two main .html template files that we will need to modify to display and edit the new field

HTML Template File (Edit)