Provider Registry -- Adding an e-mail field

From IHRIS Wiki
Jump to navigationJump to search

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

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.

This is accomplished by defining the LDAP Form Storage which is one of the several Form Storage Mechanisms in I2CE.

The LDAP storage options for the person form are located under the magic data node: /modules/forms/forms/person/storage_options/LDAP and can be found in the configuration file at line 213.


Linking LDAP and I2CE (Read)

To be able able to read data from LDAP into the "person" form, we need to define how each field of the person form gets populated from LDAP. These are defined in magic data under /modules/forms/forms/person/storage_options/LDAP/list/populate which starts at line 321 of revision 73.


We will need to add a definition for the reading the I2CE email form field from the LDAP mail attribute. This can be done by adding the following just after line 337 of revision 73: <source lang="xml"> <configuration name="email">

 <version>4.1.0.83</version>
 <value>mail</value>

</configuration> </source>

Linking LDAP and I2CE (Write)

To be able to save data into LDAP, we need to define how the data from the I2CE person form get turned into attributes for LDAP. This is defined in magic data under /modules/forms/forms/person/storage_options/LDAP/save which starts at line 220 of revision 73.

On line 243 we see the section where the LDAP attributes begin, and we will want to define a mapping for the "mail" attribute by adding the following: <source lang="xml"> <configurationGroup name='mail'>

 <verison>4.1.0.83</verison>
 <configuration name='printf'>
   <value>%1s</value>
 </configuration>
 <configuration name='printf_args' type="delimited" values="many">
   <value>1:email</value>
 </configuration>

</configurationGroup> </source> just after line 243.

Here we are making use of printf / sprintf to define the mail attribute from the email data field.

HTML Template File

There are two main .html template files that we will need to modify to view and edit the new person form in the provider registry.


HTML Template File (View)

The provider is viewed using the [view.html] html template.

In this template, you will see that the person data fields are displayed at lines 27-34.

We just need to add one line to display the email address. We will put it after line 34: <source lang="xml"> </source>

HTML Template File (Edit)

The edit page for the provider uses the form_person.html html template.

This template is setup to edit and display the data in a two column table, and we just need to insert a reference to the email field of the person form. In this case, we need to add a new table row and so we insert the following: <source lang='xml'>

   

</source> just after line 37

Committing Code

After we have tested that all our changes were made correctly, we can commit the changes with something like: <source lang='bash'> litlfred@thyme:~/rhea-pr/UserInterface$ bzr update

M  UserInterface/translations/templates/provider-registry-site-rwanda/fr.po                                                                                                           
M  UserInterface/translations/templates/rwanda-facility/fr.po
M  UserInterface/translations/templates/rwanda-geography/fr.po
M  UserInterface/translations/templates/rwanda-pr-provider-reports/fr.po
M  UserInterface/translations/templates/rwanda-pr-search-provider-report/fr.po

All changes applied successfully. Updated to revision 73 of branch bzr+ssh://bazaar.launchpad.net/+branch/rhea-pr litlfred@thyme:~/rhea-pr/UserInterface$ bzr status modified:

 UserInterface/Provider-Registry-Rwanda.xml
 UserInterface/templates/en_US/form_person.html
 UserInterface/templates/en_US/view.html

litlfred@thyme:~/rhea-pr/UserInterface$ bzr commit -m "added email data field to provider registry user interface" Committing to: bzr+ssh://bazaar.launchpad.net/+branch/rhea-pr/ modified UserInterface/Provider-Registry-Rwanda.xml modified UserInterface/templates/en_US/form_person.html modified UserInterface/templates/en_US/view.html Committed revision 74. </source> You may wish read to one of the many bzr tutorials:

Note, you should always do "bzr update" before you start editing code.

The result

Once we committed the code, we changed from revision 73 to revision 74. You can see all the changes for this revision here. You can see all the changes we made to each file.