IHRIS XML Import Export

This described the XML import and export present in iHRIS 4.2.

The XML used for import and export uses the same structure which is based on the form relationship.

Forms, Fields

iHRIS data is structured as forms with data fields. You can see these forms and fields here:

• iHRIS Manage Form Fields
• iHRIS Qualify Form Fields

The data fields can be one of several data types, for example STRING_LINE, MAP, FLOAT, or INT.

Some forms are related to each other. There are two main ways forms are related together:

• A form can have child forms. For example, the person form has one child person_contact_work and many person_scheduled_training_course forms, one for each training event that person attended. The parent to child form relationship is used to indicate when data is "owned" by another form.
• A form can use a MAP field to link to another form. This could be example the residence field in the person form which links to the country or district form.

Exporting XML Data

Exporting data is a two step process.

Creating a Form Relationship

To export data in XML the first step is to create a form relationship which contains all of the information desired.

There are many ways that forms can be related to each other. These form relationships are described here and can be built using the iHRIS web interface. You can all see the video demo below for more details.

Creating an Export Page

Once you have create a form relationship, you will want to create a new page in iHRIS to create the export. Using the "Page Builder" under "Configure System" you will want to create a "I2CE_PageXMLRelationship" page. Once the page has been created, you will want to "Edit" the page and specify:

• The form relationship that will be used for export. This will be the form relationship you created in the last step.
• The data fields to include in the export. You can select fields by form or select to include all the data fields

See the video demo below for more details.

XML Import

The XML import process uses the same XML form relationship format. Imported data is validated according to the forms validation rules before being imported -- invalid forms are not saved to the system. Any forms linked via a MAP field (such as a cadre list) will be added if they are not already there.

With the XML import there are a few options:

• Preserve IDs. Optionally a form relationship can put the IDs of the form. When importing data, you can chose to preserve or not to preserve the iHRIS form id's of the primary form in the relationship as well
• Ignore invalid forms: You can choose to ignore the validation checks for forms before saving. This could be used for example if you are importing a person and know you will have duplicate names.

The URL to access the form relationship import is:

 http://localhost/ihris-manage/form_relationship_import

You can submit the data as an HTTP POST with the XML content encoded as multipart/form-data. You can also set the 'ignore_ids' to 1 if you want the IDs ignored, if present.

You can also run the import on command line with:

 php index.php --page=/I2CE/form_relationship_import --file=<filename> [--ignore-ids=1]

Video Demo

Here is a video demo of an export of Jobs and Cadres from one iHRIS system to another. https://youtu.be/UbgawQKywz0

Here is a video tutorial of taking an Excel spreadsheet and exporting it into XML. www.youtube.com/watch?v=9bat12gH3Qs

XML Data Structure

The XML data structure of a form relationship is structured as follows:

• A <relationshipCollection/> This is the root element which contains all of the form relationship instances
  • A <relationship/> This child element contains the data for a form relationship instance
    • <form/> This contains the form data for the primary form in the relationship
      • <field/> This data for the field in the form. There is more explanation here for each of the data types.
    • <joinedForms/> This child element contains any forms joined into the relationship under the primary form
      • <joinedForm/> There is a child element for each joined form type.
        • <form/> There is a child element for each form instance of the designated type that is in the relationship. This has the same structure as the <form/> above
        • <joinedForms/> This child element contains any forms joined into the relationship under the joined form

XML Data Structure Example

Here is an example of a single form relationship instance represented as XML. Here we have the "person" form which is joined with one child form, "dependent."

In the <relationshipCollection/> element, there are two optional attributes that you can add:

• invalid This is a comma separated list of forms that you do not want to check the validity of. This is useful, for example, if you want to import people that have the same name. Example: <relationshipCollection name='test' invalid='person,person_id'/>
• ignoreids If you set this value to 1 if you want to ignore any ids that are associated to a form

<relationshipCollection name="test">
  <!-- Contains 1 records -->
  <!-- Record #: 1-->
  <relationship form="person" name="test" id="10373">
    <form id="10373" name="person" created="2013-10-06 12:06:11" modified="2014-12-04 14:08:58">
      <field type="STRING_LINE" name="csd_uuid">45276201-c510-3971-8950-427a80fb3b79</field>
      <field type="STRING_LINE" name="firstname">A.</field>
      <field type="MAP" name="nationality"><value form="country">1</value></field>
      <field type="STRING_LINE" name="othername">Sede</field>
      <field type="STRING_LINE" name="surname">Lessman</field>
      <field type="YESNO" name="naturalized">0</field>
    </form>
    <joinedForms>
       <joinedForm join_style="child" report_form_name="dependent" form="dependent">
          <form id="75384" name="dependent" created="2014-06-18 09:31:30" modified="2014-06-18 09:31:30">
            <field type="YESNO" name="beneficiary">1</field>
            <field type="DATE_YMD" name="date_of_birth"><day>18</day><month>01</month><year>1967</year></field>
            <field type="STRING_MLINE" name="dep_address">Caldwell, Old Georgia</field>
            <field type="MAP" name="gender"><value form="gender">F</value></field>
            <field type="STRING_LINE" name="name">Juah W. Lessman</field>
            <field type="STRING_LINE" name="relationship">Wife</field>
          </form>
       </joinedForm>
     </joinedForms>
   </relationship>
</relationshipCollection>

Here is an example of loading a facility list with a facility_type which has not been pre-loaded.

<relationshipCollection name="facility_export" >
  <relationship form="facility" name="facility_export" >
    <form  name="facility" created="0000-00-00 00:00:00" modified="0000-00-00 00:00:00">
      <field type="STRING_LINE" name="name">Agbons Primary Health Center 7</field>
    </form>
    <joinedForms>
      <joinedForm report_form_name='facility_type' form='facility_type' join_style='parent_field' join_field='facility_type'>
        <form  name="facility_type" >
          <field type="STRING_LINE" name="name">Test Facility Ownership</field>
	</form>
      </joinedForm>
    </joinedForms>
  </relationship>
</relationshipCollection>