This section describes the artifacts that need to be developed in order to process the data submitted from a Life Event script. This section describes:
Just as the Citizen Data Hub has a notion of Data Hub Context for reading so also does it have Data Hub Contexts for updating. Life Events will typically use the same Data Hub Context name for the read and updates associated with the same Life Event, so the "CitizenBoughtCar" context describes, not only, a set of artifacts for pre-populating a "CitizenBoughtCar" Life Event script but also a set of artifacts for handling updates to the Citizen's data when the "CitizenBoughtCar" Life Event script is complete.
An update operation for a given Citizen Data Hub Context can lead to many different individual entities being updated in a single transaction. The artifacts, provided to a Data Hub following a script submission are:
The Data Store root entity is the root of the data store that has been updated via the Life Events IEG script. The Difference Command is an entity that describes how this data store is different to the one that was passed to the IEG script before it was launched. In other words it describes how the user has changed the data as a result of executing the Life Event Script. These differences are broken down into three basic types:
Of these three, Creations and Updates are the most common. Allowing users to remove items in Life Events scripts should generally be considered bad practice. Standard Life Events tend to be characterized by a number of Creations whereas Round Tripping Life Events tend to be a mixture of Creations and Updates. The Difference Command is generated automatically by the Life Event Broker after a Life Event is submitted.
To turn a Data Hub Update Operation into automatic updates to evidence entities on the Holding Case we need to specify a Data Hub Update Transform. In cases where there is a requirement to update non-evidence entities, an Update Processor must be developed. These Update Processors involve Java code development.
Update Transforms, like Read Transforms are specified using a simple XSLT syntax. In order to write update Transforms, the author must understand both the input XML, and the output Evidence XML format. The following examples are built around a "CitizenHavingABaby" Life Event. This Life Event allows the user to report that they are due to have a baby. They can enter a number of unborn children to indicate, for example, that they are expecting twins. The user can also enter a due date and they can nominate a father for the unborn child. The father can be an existing case participant or someone else entirely. In the latter case they must enter name, address, Social Security Number etc. This Life Event is not a "Round Tripping" Life Event, it is concerned with the creation of new Evidence rather than the update of existing Evidence. The input to an Update Transform is an XML-based description of the Data Store Difference Command. A sample difference command XML for the "CitizenHavingABaby" is depicted below:
<update>
<diff diffType="NONE" entityType="Application">
<diff diffType="NONE" entityType="Person" identifier="102">
<diff diffType="CREATE" entityType="Pregnancy">
<attribute name="numChildren">1</attribute>
<attribute name="dueDate">20110528</attribute>
<attribute name="curamDataStoreUniqueID">385</attribute>
</diff>
</diff>
<diff diffType="UPDATE" entityType="Person" identifier="101">
<attribute name="isFatherToUnbornChild">true</attribute>
<attribute name="curamDataStoreUniqueID">399</attribute>
</diff>
</diff>
</update>
The difference command XML corresponds node-for-node with the data store XML. Each diff node describes how the corresponding data store entity has been modified by the execution of the IEG script. The curamDataStoreUniqueID attribute identifies which data store entity has changed. The diffType attribute identifies the nature of the change, for example CREATE, UPDATE, NONE or REMOVE. Attributes that are listed are those that have changed or been added to each data store entity. In the above example, the user has registered a pregnancy to Linda Smith (concern role ID 102) with one unborn child, due on May 28 th 2011. The father is listed as being James Smith (concern role ID 101). For more information on difference command XML please see the schema in Difference Command XML Schema section. There are a couple of additional attributes and elements used when updating XML that are illustrated below:
<?xml version="1.0" encoding="UTF-8"?>
<client-data>
<client localID="102">
<evidence>
<entity type="ET10074" action="CREATE" localID="">
<attribute name="numChildren">1</attribute>
<attribute name="dueDate">20110528</attribute>
<entity-data entity-data-type="role">
<attribute type="LG"/>
<attribute roleParticipantID="102"/>
<attribute
entityRoleIDFieldName="caseParticipantRoleID"/>
</entity-data>
<entity-data entity-data-type="role">
<attribute type="FAT"/>
<attribute roleParticipantID="101"/>
<attribute participantType="RL7"/>
<attribute
entityRoleIDFieldName="fahCaseParticipantRoleID"/>
</entity-data>
<entity type="ET10125" action="CREATE">
<attribute name="comments"> Unborn child 1</attribute>
<entity-data entity-data-type="role">
<attribute type="UNB"/>
<attribute roleParticipantID="102"/>
<attribute
entityRoleIDFieldName="caseParticipantRoleID"/>
</entity-data>
</entity>
</entity>
</evidence>
</client>
</client-data>
Note the use of the action attribute which describes the action to be taken to the underlying evidence, for example, to create the evidence or to update existing evidence. The next section will discuss the meaning of the <entity-data> element. An example of the XSLT used to transform the above difference XML into the above Evidence XML is depicted below:
<?xml version="1.0" encoding="UTF-8"?>
<!-- This script plucks out and copies all resource-related -->
<!-- entities from output built by the XMLApplicationBuilder -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:x="http://www.curamsoftware.com/
schemas/DifferenceCommand"
xmlns:fn="http://www.w3.org/2006/xpath-functions"
version="2.0">
<xsl:output indent="yes"/>
<xsl:strip-space elements="*"/>
<xsl:template match="update">
<xsl:for-each select="./diff[@entityType='Application']">
<xsl:element name="client-data">
<xsl:apply-templates/>
</xsl:element>
</xsl:for-each>
</xsl:template>
<xsl:template match="diff[@entityType='Person']">
<xsl:element name="client">
<xsl:attribute name="localID">
<xsl:value-of select="./@identifier"/>
</xsl:attribute>
<xsl:element name="evidence">
<xsl:apply-templates/>
</xsl:element>
</xsl:element>
</xsl:template>
<xsl:template match="diff[@entityType='Pregnancy']">
<xsl:element name="entity">
<xsl:attribute name="type">ET10074</xsl:attribute>
<xsl:attribute name="action">
<xsl:value-of select="./@diffType"/>
</xsl:attribute>
<xsl:attribute name="localID">
<xsl:value-of select="./@identifier"/>
</xsl:attribute>
<xsl:for-each select="./attribute">
<xsl:copy-of select="."/>
</xsl:for-each>
<xsl:element name="entity-data">
<xsl:attribute name="entity-data-type">
role
</xsl:attribute>
<xsl:element name="attribute">
<xsl:attribute name="type">LG</xsl:attribute>
</xsl:element>
<xsl:element name="attribute">
<xsl:attribute name="roleParticipantID">
<xsl:value-of select="../@identifier"/>
</xsl:attribute>
</xsl:element>
<xsl:element name="attribute">
<xsl:attribute name="entityRoleIDFieldName">
caseParticipantRoleID
</xsl:attribute>
</xsl:element>
</xsl:element>
<xsl:element name="entity-data">
<xsl:attribute name="entity-data-type">
role
</xsl:attribute>
<xsl:element name="attribute">
<xsl:attribute name="type">FAT</xsl:attribute>
</xsl:element>
<xsl:for-each select=
"../../diff[@entityType='Person']/attribute[
@name='isFatherToUnbornChild'
and ./text()='true']">
<!-- Copy the participant id if a family -->
<!-- member is the father -->
<xsl:element name="attribute">
<xsl:attribute name="roleParticipantID">
<xsl:value-of select="
../@identifier"/>
</xsl:attribute>
</xsl:element>
</xsl:for-each>
<!-- Copy details of absent parent -->
<xsl:call-template name="absentFather"/>
<xsl:element name="attribute">
<xsl:attribute name="entityRoleIDFieldName">
fahCaseParticipantRoleID
</xsl:attribute>
</xsl:element>
</xsl:element>
<xsl:variable name="numBabies">
<xsl:value-of select="attribute[
@name='numChildren'
]/text()"/>
</xsl:variable>
<xsl:call-template name="unbornChildren">
<xsl:with-param name="count" select="$numBabies"/>
</xsl:call-template>
</xsl:element>
</xsl:template>
<xsl:template name="unbornChildren">
<xsl:param name="count" select="1"/>
<xsl:if test="$count > 0">
<xsl:element name="entity">
<xsl:attribute name="type">ET10125</xsl:attribute>
<xsl:attribute name="action">
<xsl:value-of select="./@diffType"/>
</xsl:attribute>
<xsl:element name="attribute">
<xsl:attribute name="name">
comments
</xsl:attribute>
Unborn child <xsl:value-of select="$count"/>
</xsl:element>
<xsl:element name="entity-data">
<xsl:attribute name="entity-data-type">
role
</xsl:attribute>
<xsl:element name="attribute">
<xsl:attribute name="type">
UNB
</xsl:attribute>
</xsl:element>
<xsl:element name="attribute">
<xsl:attribute name=
"roleParticipantID">
<xsl:value-of select="
../@identifier"/>
</xsl:attribute>
</xsl:element>
<xsl:element name="attribute">
<xsl:attribute name=
"entityRoleIDFieldName">
caseParticipantRoleID
</xsl:attribute>
</xsl:element>
</xsl:element>
</xsl:element>
<xsl:call-template name="unbornChildren">
<xsl:with-param name="count" select="$count - 1"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<xsl:template name="absentFather">
<xsl:element name="attribute">
<xsl:attribute name="participantType">
<xsl:text>RL7</xsl:text>
</xsl:attribute>
</xsl:element>
<xsl:if test="attribute[@name='fahFirstName']">
<xsl:element name="attribute">
<xsl:attribute name="firstName">
<xsl:value-of select="attribute[
@name='fahFirstName'
]/text()"/>
</xsl:attribute>
</xsl:element>
</xsl:if>
<!-- etc. map other personal details such as -->
<!-- SSN, date of birth -->
<xsl:if test="diff[@entityType='ResidentialAddress']">
<xsl:if test="diff[
@entityType='ResidentialAddress']/attribute[
@name='street1']">
<xsl:element name="attribute">
<xsl:attribute name="street1">
<xsl:value-of select=
"diff[
@entityType='ResidentialAddress']
/attribute[
@name='street1']/text()"/>
</xsl:attribute>
</xsl:element>
</xsl:if>
<!-- etc. map other parts of residential address -->
</xsl:if>
</xsl:template>
<xsl:template match="*">
<!-- do nothing -->
</xsl:template>
</xsl:stylesheet>
Readers who are familiar with Evidence will know that Evidence Entities frequently refer to third parties. For example, Pregnancy evidence refers to the father via a Case Participant Role. The associated father can be a Person or a Prospect Person. Other evidence types such as Student may refer to a School which is entered as a Representative Case Participant Role.
The Evidence XML schema provides a generic element called <entity-data> which can be used to provide special handling instructions to the Citizen Data Hub. The type of handling depends on the <entity-data-type> specified. Cúram provides a special processor for the entity-data-type role. This role entity data processor can be used to create new Case Participant Roles or reference existing Case Participant Roles for existing Case Participants. Referring to the Evidence XML output in listed in the previous section the attribute denoted by type is used to denote the Case Participant Role Type e.g. FAT for Father or UNB for Unborn Child. The value provided here should be a codetable value from the CaseParticipantRoleType code table. The roleParticipantID denotes the ConcernRoleID of an existing participant on the system. If this is supplied then the system will not attempt to create a new Case Participant, rather it will reuse a case participant with this id. The entityRoleIDFieldName is the field name in the corresponding Evidence Entity. In the case of the Pregnancy evidence entity for example, the name of this field is fahCaseParticipantRoleID. In the case where a new participant needs to be created the following fields are supported by the Role Entity Data Processor.
Previous Sections have illustrated how it is possible to configure Life Events to automatically map updates through to Evidence Entities on multiple integrated cases. Sometimes Life Events will be required to update non-Evidence entities such as a Residential Address, Employment or some other customer specific non-Evidence entity. Typically these entities will be shared across multiple cases. It is also typical that these entities would not follow the same controlled Life Cycle as evidence entities. Evidence has many advantages:
Non evidence entities have none of these advantages and safeguards. A decision by Analysts to update non Evidence entities based on Life Events should be made with due care, especially if the changes can be applied simultaneously across multiple cases. It is possible to update non Evidence entities but this will always involve custom code. It is strongly recommended that the design of such functionality includes safeguards to ensure that at least one Agency worker gets to manually approve the changes before they are applied to the system.