Capturing Associated Data

IEG allows association relationships to be created between entities. This is useful because a restriction applies to nested entities and nested lists that they can only be nested to two levels. The use of associated relationships provides an effective alternative to nesting entities to three levels.

For example, suppose there is a requirement to record employment information for the people in a household. Employment information may be gathered independently of Income information as there may be multiple incomes for a given employment.

Once the Income and Employment information is gathered and the entities have been created, the association between the entities can be made. The association is made by creating a "relationship" entity. The relationship entity is normally "owned" by one of the entities participating in the relationship and is represented as a sequence as with other relationship types.

Defining a relationship entity requires being able to identify the related entity therefore a key must be defined in the related entity. To apply this to the Income/Employment example, the Employment entity type will have a key, an EmploymentRelationship entity type will be defined and the Income entity will own a sequence of EmploymentRelationships, as follows:

Figure 1. Associated Entity Schema

<xsd:element name="Employment">	
  <xsd:complexType>
    <xsd:attribute name="employmentID" type="d:SVR_KEY" />
    <xsd:attribute name="employer" type="IEG_STRING" />
    <xsd:attribute name="employmentType" type="IEG_STRING" />
  </xsd:complexType>
  <xsd:key name="Employment_Key">
    <xsd:selector xpath="./Employment" />
    <xsd:field xpath="@employmentID" />
  </xsd:key>
</xsd:element>
<xsd:element name="Income">
  <xsd:complexType>
    <xsd:sequence minOccurs="0">
      <xsd:element ref="EmploymentRelationship" minOccurs="0" 
                maxOccurs="unbounded" />
    </xsd:sequence>
    <xsd:attribute name="type" type="IEG_STRING" />
    <xsd:attribute name="amount" type="IEG_MONEY" />
  </xsd:complexType>
</xsd:element>
<xsd:element name="EmploymentRelationship">
  <xsd:complexType>
    <xsd:attribute name="employmentID" type="d:SVR_KEY" />
  </xsd:complexType>
</xsd:element>

The association can then be captured in the script by defining a list-question and specifying a link-entity attribute which refers to the key of the related entity. Continuing our example, on a page mapped to the Income entity a list-question can be defined specifying the key from the EmploymentRelationship used to identify the Employment entity.

List questions are constructs that allow the user to choose from a list of entities. For more details, see List Questions.

Figure 2. Creating Association Relationships

<question-page id="IncomePage" entity="Income"  ...
  <cluster>
    <layout>
      <label-width>0</label-width>
    </layout>
    <list-question link-entity="EmploymentRelationship.employmentID"
        entity="Employment" single-select="true">
      <label id="SelectEmployer.Label">
        <![CDATA[Select Employer]]>
      </label>
      <item-label>
        <label-element attribute-id="employer" />
      </item-label>
    </list-question>
  </cluster>
</question-page>