7 Processes, Update Policies, and Field Validations

This chapter provides information and procedures to filter default values from processes, configure update policies, and define custom field validations.

This chapter includes the following sections:

"Filtering Default Values From Master Person Index Processes"
"Configuring Master Person Index Update Policies"
"Defining Custom Field Validations for the Master Person Index"

Filtering Default Values From Master Person Index Processes

You might want to prevent certain default values from being used in the match process or from being populated into the single best record (SBR). For the blocking query, default values result in a large number of non-matching records being returned for a match query. For the match process, default values result in inaccurately high match weights. Finally, you do not want invalid values to appear in the SBR when it is possible to remove them.

The master person index application provides a configuration file, filter.xml, in which you can define filtering rules. You can specify fields and values to filter directly in this file, and you can create exclusion lists in a flat file. Exclusion lists contain all the values to filter for a specific field.

To Filter Default Values From the SBR, Blocking Query, or Match Process

To use flat files to define values to filter, create a flat file for each field to be filtered.
In this file, list each value to exclude for each filter definition you will create and separate each value by a delimiter.
In the Projects window, expand the master person index application and then expand Filter.
Open filter.xml.
For each field to be filtered, define the elements and attributes described in "Filter Definition Elements".

Save and close the file.

Example 7-1 Filter Definitions

<exclusion-List module-name="ExclusionFilter" 
parser-class="com.sun.mdm.index.configurator.impl.ExclusionFilterConfig">
  <field sbr="true" matching="false" blocking="false">
    <name>Person.FirstName</name>
    <value
      <field-value>Baby</field-value>
      <field-value>Baby Boy</field-value>
      <field-value>Baby Girl</field-value>
    </value>
  </field>
  <field sbr="true" matching="true" blocking="true">
    <name>Person.SSN</name>
    <value>
      <file delimiter="|">
        <file-name>SSN.txt</file-name>
      </file>
    </value>
</exclusion-List>

The filter.xml file provides a simple format for you to define filters for survivor calculation, blocking queries, and matching. The following sample defines a rule that filters out the listed values from the FirstName field in the SBR. It defines a second rule that filters out the values listed in FirstNameFilters.txt from the SSN field.

The filter values file for the SSN field in the above example would look similar to the following:

000000000|111111111|222222222|333333333|444444444|555555555|666666666|777777777|
888888888|999999999

Filter Definition Elements

The following table lists and describes the XML elements and attributes that define the filters to be used for the SBR, blocking query, or match process. You can either define the exclusion lists directly in filter.xml or in a flat file that is referenced from filter.xml.

ElementDescription	Attribute
field	A filter definition for one field. The definition includes the following elements and attributes. You can define multiple filter definitions, and each can define filters for the SBR, blocking, matching, or any combination of the three.
sbr	An indicator of whether to apply the filter to the SBR. Specify true to apply the filter to the SBR; otherwise specify false.
matching	An indicator of whether to apply the filter to the blocking query. Specify true to apply the filter to the blocking query; otherwise specify false.
blocking	An indicator of whether to apply the filter to the matching process. Specify true to apply the filter to the matching process; otherwise specify false.
name	The qualified name for the field; for example, Person.SSN or Person.Address.PostalCode. For more information about qualified field names, see "Learning About Master Person Index Field Notations" in Oracle Healthcare Master Person Index Configuration Reference (Part Number E18592-01).
value	A list of field-value elements that specify the values to filter.
field-value	A value to filter from the SBR, blocking query, or matching process. You can define multiple field values. To use values listed in a flat file, define a file element instead of a field-value element.
file	A definition of the file that contains the list of values to filter.
delimiter	The character that delimits the values listed in the exclusion list flat file.
file-name	The path and name of a file that contains the list of values to filter. Be sure the values in this file are delimited by the character specified above.

Configuring Master Person Index Update Policies

When update.xml is generated, no Java classes are defined for the update policies. You can create custom update policy classes and specify that the custom classes be used instead. Custom update policies must implement com.sun.mdm.index.update.UpdatePolicy and must be defined as custom classes in the Oracle Healthcare Master Person Index project to be recognized as an update policy. The names of the custom plug-ins you create are the values you enter for the update policies. You can also set the update policy flag to specify whether the policies are performed when no changes are made to an existing record.

Perform the following tasks to configure the update policies:

"Defining Master Person Index Update Policies"
"Setting the Master Person Index Update Policy Flag"

Defining Master Person Index Update Policies

You can define update policies for any of the seven update policy elements. You do not need to specify a policy for each element.

To Define Update Policies

In the Projects window, expand the Configuration node in the project you want to modify, and then double-click update.xml.

The file opens in the NetBeans XML editor.
Scroll to the UpdateManagerConfig section of the file.
Do any of the following:
- To modify the merge policy for enterprise objects, change the value of the EnterpriseMergePolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<EnterpriseMergePolicy>com.sun.mdm.index.user.MyEntMergePolicy
   </EnterpriseMergePolicy>
```
- To modify the unmerge policy for enterprise objects, change the value of the EnterpriseUnmergePolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<EnterpriseUnmergePolicy>com.sun.mdm.index.user.MyEntUnmergePolicy
   </EnterpriseUnmergePolicy>
```
- To modify the update policy for enterprise objects, change the value of the EnterpriseUpdatePolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<EnterpriseUpdatePolicy>com.sun.mdm.index.user.MyEntUpdatePolicy
   </EnterpriseUpdatePolicy>
```
- To modify the create policy for enterprise objects, change the value of the EnterpriseCreatePolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<EnterpriseCreatePolicy>com.sun.mdm.index.user.MyCreatePolicy
   </EnterpriseCreatePolicy>
```
- To modify the merge policy for system objects, change the value of the SystemMergePolicy element to the fully qualified name of the new merge policy Java class.
  
  For example:
```
<SystemMergePolicy>com.sun.mdm.index.user.MySysMergePolicy
   </SystemMergePolicy>
```
- To modify the unmerge policy for system objects, change the value of the SystemUnmergePolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<SystemUnmergePolicy>com.sun.mdm.index.user.MySysUnmergePolicy
   </SystemUnmergePolicy>
```
- To modify the assumed match policy, change the value of the UndoAssumeMatchPolicy element to the fully qualified name of the new Java class.
  
  For example:
```
<UndoAssumeMatchPolicy>com.sun.mdm.index.user.MyUndoAsmMatchPolicy
   </UndoAssumeMatchPolicy>
```
Save and close the file.

Setting the Master Person Index Update Policy Flag

The update flag determines whether update policies are performed against a record when a transaction does not cause any changes to the record's data.

To Set the Update Policy Flag

In the Projects window, expand the Configuration node in the project you want to modify, and then double-click update.xml.

The file opens in the NetBeans XML editor.
Scroll to the UpdateManagerConfig section of the file.
To specify that update policies are not performed when no updates are made, set the SkipUpdateIfNoChange element to true.

For example:
```
<SkipUpdateIfNoChange>true</SkipUpdateIfNoChange>
```
To specify that update policies are performed even though no updates are made, set the SkipUpdateIfNoChange element to false.

For example:
```
<SkipUpdateIfNoChange>false</SkipUpdateIfNoChange>
```
Save and close the file.

Defining Custom Field Validations for the Master Person Index

By default, validation.xml defines one validation rule named "validate-local-id". This rule defines certain validations to perform against local ID and system fields before they are entered into the database. The local ID validator verifies that the system code is valid, the local ID format is correct, the local ID is the correct length, and that neither field is null.

You can define additional validations for your data by creating the Java class and appropriate methods. Create the custom class in the Source Package folder of the master person index EJB project so you can include the custom validation rule in the master person index application code package. The custom validation classes must implement com.sun.mdm.index.objects.validation.ObjectValidator. The exception thrown is com.sun.mdm.index.objects.validation.exception.ValidationException.

To Implement a Validation Rule

Create the custom validation rules in the Source Package folder of the EJB project.
In the Projects window, expand the Configuration node in the project you want to modify, and then double-click validation.xml.

The file opens in the NetBeans XML editor.
Create a new rule element in the rules element.
In the new rule element, create the following attributes:
- name - A unique name for the validation rule.
- object-name - The name of the master person index Java class that defines the object to which the validation rule is applied, such as SystemObject or Parent_NameObject (where Parent_Name is the name of the parent object in the object definition)
- class - The complete path of the Java class to call for the validation rule.
  
  For example:
```
<ValidationConfig module-name="Validation" parser-class= 
 "com.sun.mdm.index.configurator.impl.validation.ValidationConfiguration"
   <rules>
      <rule name="validate-auxiliary-id" object-name="PersonObject"
       class="com.sun.mdm.index.user.AuxiliaryId"/>
      <rule name="validate-birth-date" object-name="PersonObject"
       class="com.sun.mdm.index.user.BirthDate"/>
   </rules>
</ValidationConfig>
```
Save and close the file.