Data Interoperability

This article describe the data-interoperability features present in version 3.2 and later.

Data Structure

Forms and Fields

The individual data elements of the system are called fields, all of which are associated to a sub-class of I2CE_FormField. This class describes how the data defined for this field should be represented as a string as well as how it should be displayed to the end-user in either a read-only or edit context. Examples include dates, times, integers, mapped values (see below), strings, multi-line strings, currencies, and binary data.

Individual data elements, or fields, are collected together in forms. An instance of a form are the values associated with a particular unique ID. You may think of a form as a row in database table, and a field as a column of that table. For example a person form may be defined as:

• person
  • firstname (string)
  • surname (string)
  • date_of_birth (date -- month/day/year)

while an instance would be:

• person
  • id=9234
  • firstname := 'Jill'
  • surname := 'Schwartz'
  • date_of_birth := '04/04/1974'

Mapped Fields

There are special fields, which subclass I2CE_FormField_MAPPED, whose values are references to other forms which subclass I2CE_List. For example, we could amend the above 'person' form to include a field 'place_of_birth' which take values in any of the following list forms (and their fieldss):

• country
  • name (string)
• region
  • name (string)
  • country (map, with values in 'country')
• district
  • name (string)
  • region ((map, with values in 'region')
• county
  • name (string)
  • districy (map, with values in 'district')

Parent/Child Relationship

A second type of relationship between forms is the parent/child relationship. You may specify a form has having one or more forms as a child. For example, suppose we defined the 'salary' form as follows:

• salary
  • start_date (date -- month/day/year)
  • end_date (date -- month/day/year)
  • amount (currency)

then an instance of a 'person' form may many instances of the 'salary' form as children which reflects their change in salary over time.

Importing Data

One fundamental means available to the system of importing data from other information systems is through defining various storage mechanisms for the form data. A storage mechanism is defined by subclass I2CE_FormStorage_Mechanism which provides the methods to read, and possibly write, the data for any form with the given mechanism. If the data is stored in a database, it can sub-class I2CE_FormStorage_DB and provide read access to the data as a form by only defining one method, getRequiredFieldsQuery(). To make a storage mechanism writable, you only need to write a method which defines how to store a data field.

Once a storage mechanism is written, the data for that form can be queried via searches with [[Technical Overview: Limiting Forms |limits].

The currently (or soon-to-be) available storage mechanisms are:

• entry: A vertical database storage mechanism which keeps a history of when and by who individual fields (data elements) were changed. This is the default storage mechanism, and the storage mechanism that was used in version prior to 3.2.
• flat: A horizontal database storage mechanism, where a row of a table corresponds to an instance of a form. The columns, or any SQL function, of the table are used to define the fields.
• multi_flat: A horizontal database storage mechanism similar to the flat storage mechanism but combining several identically structured tables. It is primarily intended for data collation.
• magic_data: A locale aware storage mechanism primarily intended for centrally maintained lists of data.

Storage mechanisms are easy to write, and some other possibilities for storage mechanisms which could be added are for:

• Data stored in XML files.
• Data stored in a CSV file.

Exporting Data

The essential means by which data can be made to other systems is through the custom reporting system, which consists of two major components, the form relationship and the report.

Form Relationships

A form relationship describe the basic relationships of the various forms within the system. A form relationship begins by choosing a primary form for the relationship. Once a primary form has been chosen for the relationship, you may limit the instances of the forms chosen by describing a limit as in Technical Overview: Limiting Forms.

For any form in a form relationship, you can adjoin an additional form which somehow links to that form. That link can either be either through the parent/child relationship or through the mapped values relationship. Any joined form can then be limited as the primary form was.

Form relationships can either be defined using configuration (XML) data, or via the on-line GUI tool.

Example

You may wish to create a form relationship in iHRIS Manage that describes all current employees, their salaries, and their supervisors. Here is an outline of how to define this relationship:

• Start with the primary form 'person_position' and limit to those positions which the 'end_date' field is not null.
• Join to the primary form the 'person' form where the 'person' form is a parent of the 'person_position' form
• Join to the primary form the 'salary' form where 'salary' is a child of 'person_position' and where the 'start_date' field for 'salary' is maximal
• Join to the primary form the 'position' form where the field 'position' of the primary 'person_position' form maps to that position. Call this the 'employee_position' form.
• Join to the 'position' form the 'person' form where the 'supervisor' field of the 'position' form maps to that position. Call this joined form the 'supervisor_position' to distinguish it from the 'employee_posititon' form.
• Join to the 'supervisor_position' the 'person_position' form whose 'position' field is the value of 'supervisor_position' form. Call this the 'supervisor_person_position'
• Join to the 'supervisor_person_position' form the 'person' form which is a parent of the form.

Custom Reports

Once a form relationship has been defined, a report can built by selecting the data fields which are relevant to this report. The system will then create a table in the database which holds the data in the report, the columns of which are the selected fields, and the rows of which are each the collection of forms satisfying the form relationship.

Currently, this data can be view through the web browser, exported to a CSV file, exported to a HTML file, printed as PDF, and viewed with charting software. There are plans to make available the data via other formats, such as the Indicator Exchange Format (IXF). The various exports of the data are defined by subclassing I2CE_CustomReport_Display as appropriate.