2 Master Person Index Structure, Properties, and Restrictions

This chapter provides conceptual information and procedures for configuring Oracle Healthcare Master Person Index (OHMPI) object structures. It also provides information on field properties and field name restrictions.

This chapter includes the following sections:

"Configuring the Master Person Index Object Structure"
"Defining Master Person Index Field Properties and Understanding Name Restrictions"

Configuring the Master Person Index Object Structure

After you create the master person index framework and create the configuration files, you can modify the object structure that you defined. The properties for the objects and fields you will store in the master person index database are defined in object.xml. For more information about this file and the configurable options, see "Master Person Index Object Definition Configuration" in Oracle Healthcare Master Person Index Configuration Reference.

The object tree in the OHMPI Configuration Editor corresponds to object.xml in the master person index application. Any changes you make to the object structure in the Configuration Editor are reflected in object.xml, and MIDM field property changes are also reflected in midm.xml. If you modify the XML file directly, you need to update midm.xml manually.

Changing the object structure might also require that you make corresponding changes to the other configuration files. For example, if you add a new field to object.xml that you want to include in queries and matching, you need to make the corresponding changes to query.xml, mefa.xml, and update.xml. Only changes made before generating the project take effect for the new application.

You can configure the object structure either through the OHMPI Configuration Editor or by modifying the XML file directly. Both methods are described here. Perform any of the following actions to configure the object structure.

"Adding an Object to the Master Person Index Object Structure"
Modifying an Object's Name In the Master Person Index Object Definition
"Deleting an Object From the Master Person Index Object Structure"
"Adding a Field to the Master Person Index Object Structure"
"Deleting a Field from the Master Person Index Object Structure"
"Modifying Master Field Properties"
"Defining Relationships Between Master Person Index Objects"

Adding an Object to the Master Person Index Object Structure

You can add new objects to the object structure as needed. Note that the object structure can contain only one parent object but multiple child objects. If you use the Configuration Editor, you can either create an undefined object or create an object from a predefined template. A predefined object includes a set of predefined fields with default configurations.

Note:

Due to database naming constraints, the length of the name of the parent object plus the length of any child object names must be 21 characters or less.

To Add an Undefined Object (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Select the parent object, and then click Add Sub Object Node on the Configuration Editor toolbar.

The object structure expands, and a new child object appears at the bottom of the object structure.
Type a new name for the object, and then press Enter.
Define the fields for the new object, as described in "Adding a Field to the Master Person Index Object Structure".
On the Configuration Editor toolbar, click Save.

To Add a Predefined Object (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Select the parent object, click Templates in the toolbar, and then select the template you want to use.

The new child object and any defined fields appear in the object tree.
To change the name of the new object, double-click the object name, type the new name, and then press Enter.
Do any of the following:
- Add fields to the new object, as described in "Adding a Field to the Master Person Index Object Structure".
- Delete fields from the new objects, as described in "Deleting a Field from the Master Person Index Object Structure".
- Modify the properties of the fields in the object, as described in "Modifying Master Field Properties".
On the Configuration Editor toolbar, click Save.

To Add an Undefined Object (XML editor)

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

The file opens in the NetBeans XML editor.
Scroll to the location where you want to create the new object (after the database element but before relationships).
Create a nodes element.
Create and name a tag element within the new nodes element (the value of the tag element is the name of the object you are defining).

Make sure the new nodes element does not fall within any existing nodes elements. For example:
```
<nodes>
   <tag>Person</tag>
   ...
</nodes>
<nodes>
   <tag>Address</tag>
</nodes>
        
```
Define the fields for the new object, as described in "Adding a Field to the Master Person Index Object Structure".
Define the relationship of the new object to the existing objects, as described in "Defining Relationships Between Master Person Index Objects".
Save and close the file.

Modifying an Object's Name In the Master Person Index Object Definition

You can modify the name of an object in object.xml, but you must also make the corresponding changes to the remaining configuration files.

To Modify an Object's Name (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Click the plus sign next to the parent object to expand the object structure.
Click twice on the name of the object you want to change.
Type in the new name, and then press Enter.
On the Configuration Editor toolbar, click Save.

To Modify an Object's Name (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the tag element defining the object you want to modify.
Change the value of the tag element.
Modify the object name in the relationships definition, as described in "Defining Relationships Between Master Person Index Objects".
Save and close the file.

Deleting an Object From the Master Person Index Object Structure

If you define an object in error, you can remove the object from object.xml. If you modify the XML file directly, you must also remove the relationship definition for the object. Remember to make the corresponding changes to the remaining configuration files.

To Delete an Object (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Expand the object structure by clicking the plus sign by the parent object.
Do any of the following:
- Right-click in the object tree panel, and then click Delete.
- Press the Delete key.
- In the Configuration Editor toolbar, click Delete.
On the confirmation dialog box, click Yes.

The object and any fields associated with that object are deleted. If you remove the parent object, all child objects are also removed.
On the Configuration Editor toolbar, click Save.

To Delete an Object (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the nodes element containing the object you want to delete.
Delete all text between and including the nodes tags that contain the object tag.

For example, to delete the Address object below, delete the boldface text.
```
<nodes>
   <tag>Person</tag>
</nodes>
<nodes>
   <tag>Address</tag>
</nodes>
        
```
Remove the object name from the relationship list, as described in "Defining Relationships Between Master Person Index Objects".
Save and close the file.

Adding a Field to the Master Person Index Object Structure

Once you define an object in object.xml, you can add new fields to the object and configure the properties for those fields. Be sure to add the field to any relevant structures in the remaining configuration files. For information about field naming restrictions, see "Master Person Index Field Name Restrictions".

To Add a Field (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Expand the object structure until you see the object to which you want to add a field.
In the object tree panel, do one of the following:
- To add the field to the end of the object's field list, select the name of the object to which you want to add a new field and then click Add Field in the toolbar.
- To add the field immediately following an existing field, select the field after which you want to add the new field and then click Add Field in the toolbar.
  
  The tree expands and a new field is inserted.
To change the field name, double-click the new field, type the new name, and then press Enter.
Continue to "Modifying Master Field Properties".

To Add a Field (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the tag element defining the object to which you want to add a field.

Under the tag element, create a new fields element.

For example:

<nodes>
   <tag>Address</tag>
   <fields>
   </fields>
<nodes>

Specify the field properties described in "Master Person Index Field Property Elements" within the new fields tags.

For example:

<fields>
   <field-name>AddressType</field-name>
   <field-type>string</field-type>
   <size>8</size>
   <updateable>true</updateable>
   <required>true</required>
   <code-module>ADDRTYPE</code-module>
   <pattern/>
   <key-type>true</key-type>
</fields>

Save and close the file.

Deleting a Field from the Master Person Index Object Structure

If a field is defined for an object but does not belong to that object, you can delete the field from the object structure. Make the corresponding changes to the remaining configuration files.

To Delete a Field (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Expand the object structure until the field you want to delete is visible.
Select the field and do any of the following:
- Right-click in the object tree panel, and then click Delete.
- Press the Delete key.
- In the Configuration Editor toolbar, click Delete.
On the confirmation dialog, click Yes.

The field is removed from the object tree.
On the Configuration Editor toolbar, click Save.

To Delete a Field (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the tag element defining the object from which you want to delete a field.

Scroll to the fields element containing the field to delete, and then delete all text between and including the fields tags defining that field.

For example, to delete the AddressLine1 field below, delete all text in the sample.

<fields>
   <field-name>AddressLine1</field-name>
   <field-type>string</field-type>
   <size>5</size>
   <updateable>true</updateable>
   <required>false</required>
   <key-type>false</key-type>
   <code-module/>
   <pattern/>
   <key-type/>
</fields>

Save and close the file.

Modifying Master Field Properties

Every field in the object structure has a set of properties that must be configured before deploying the master person index application. When a field is created, a set of default properties are defined for that field. You can modify the property configuration for each field to suit your data processing, storage, and display requirements. Field properties include general field attributes, such as the name, length, and data type, and MIDM field properties, such as the display name for the field and display formatting.

Note:

On the Configuration Editor, the fields in the MIDM section cannot be configured if the field is not defined to appear on the MIDM (that is, it does not appear in midm.xml).

To Modify Field Properties (Configuration Editor)

In the Projects window, right-click the Configuration node in the project you want to modify, and then click Edit.

The Configuration Editor appears.
Expand the object structure until the field you want to configure is visible.
In the object structure, select the field to configure.

The General Properties page appears.
On the Properties page in the right side of the window, modify the value of any of the properties listed in "Master Person Index Configuration Editor Field Properties".

Note:
After you modify a property value, press Enter to apply the change.
To view or modify matching properties, click the Matching tab and configure the properties as described in "To Configure the Comparison Functions (Configuration Editor)".

This tab is only visible for fields that have a value in the Match Type field.
On the Configuration Editor toolbar, click Save.

To Modify Field Properties (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the tag element defining the object to modify, and then to the fields element containing the field to modify.
Modify the value of any of the elements described in "Master Person Index Field Property Elements".

Note:
If you modify the name of a field, make the corresponding changes to the remaining configuration files. Some property elements might not exist for a field; add any necessary elements to the field definition to configure the field.
Save and close the file.

Example 2-1 Field Properties in object.xml

The following example defines an address type field that is required in order to enter a record, and that uniquely identifies each address object in a record. It also defines a list, named ADDRTYPE, from which MIDM users can select a value to enter into the field.
```
<field-name>AddressType</field-name>
<field-type>string</field-type>
<size>8</size>
<updateable>true</updateable>
<required>true</required>
<pattern></pattern>
<code-module>ADDRTYPE</code-module>
<key-type>true</key-type>
```
The following example defines an employee ID field where the <minimum value> must be equal to or greater than 100001 and less than or equal to 199999. Only the characters 0-9 are allowed.
```
<field-name>EmployeeID</field-name>
<field-type>string</field-type>
<size>6</size>
<updateable>true</updateable>
<required>true</required>
<minimum-value>100001</minimum-value>
<maximum-value>199999</maximum-value>
<pattern>[0-9]{6}</pattern>
<key-type>false</key-type>
```

Defining Relationships Between Master Person Index Objects

Once all objects are customized, you must define relationships between those objects if you are modifying the XML file directly. If you are using the Configuration Editor, the relationships are automatically defined in the object tree.

To Define Object Relationships (XML Editor)

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

The file opens in the NetBeans XML editor.
Scroll to the relationships element near the end of the file.
To specify a new parent object, modify the value of the name element.

For example:
```
<name>Individual</name>
```
Note:
This is not recommended. Changing the parent name requires changing all instances of the name in all configuration files. To change the parent object name, use the Configuration Editor, which automatically propagates the change.
To change the name of a child object, modify the value of the appropriate children element.
To add a child object, create and name a new children element.
To delete a child object, delete all text between and including the appropriate children element.
Save and close the file.

Note:
You can only specify one name element. The values you specify for the name and children elements must match an object name specified in the nodes elements earlier in the file.

Defining Master Person Index Field Properties and Understanding Name Restrictions

Once you create the object structure of the master person index application, you can customize several properties for each field, such as whether the field is required, will include a drop-down menu on the MIDM, will be used in a blocking query, and so on. There are also some restrictions for how fields can be named and how the properties are defined on the Configuration Editor and in the configuration files.

The following sections provide information about the naming restrictions and about the field properties of the wizard.

"Master Person Index Field Name Restrictions"
"Master Person Index Configuration Editor Field Properties"
"Master Person Index Field Property Elements"

Master Person Index Field Name Restrictions

When you name the fields in your object structure, be sure to keep the following guidelines in mind to avoid errors when compiling or running the master person index application.

Oracle Healthcare Master Person Index automatically creates a field for each object named objectId, where object is the name of an object or sub-object. You cannot create fields with those names. For example, you cannot create a field named "AddressId" if there is an Address object in the object structure.
If you enter a field name longer than 20 characters, a warning dialog box appears. While most databases can handle names up to at least 30 characters, Oracle Healthcare Master Person Index appends text to the end of fields defined for phonetic encoding or standardization. For fields that will be parsed, normalized, or phonetically encoded, make sure the name of the original field does not exceed 20 characters. Any other field can have a name up to 30 characters long. For information about the names of the fields automatically created by the wizard, see Appendix A, "Match Types and Field Names" in Understanding Sun Master Index Processing.
In field names, do not use characters or names restricted by Java, XML, or the database platform you are using.

Master Person Index Configuration Editor Field Properties

The following table lists and describes the properties you can define on the Field Properties page of the Configuration Editor.

Property	Description
Name	A name for the field. See "Master Person Index Field Name Restrictions". for information on valid field names.
Data Type	The data type fro each field. Possible data types are: string - Field of this type contain a string of characters. date - Fields of this type contain a date value. float - Fields of this type contain a floating point integer. int - Fields of this type contain an integer. char - Fields of this type contain a single character. boolean - Fields of this type can contain either true or false.
Match Type	The type of matching to be performed against the field, if the field is to be used for match weight generation. You must define at least one field for matching or no weights will be generated.Note: The match types you specify here define the structure of mefa.xml, including the match string. The match types in mefa.xml might differ from the match types specified here. See Appendix A, "Match Types and Field Names," in Understanding Sun Master Index Processing for information about the available options for this field.
Blocking	An indicator of whether the field will be used in the blocking query. Select this option to add the field to the blocking query; deselect this option to omit the field from the blocking query.
Key Type	An indicator of whether the field is used to identify unique objects. For example, a business index might store several addresses for each business. Each address is assigned an address type and each business can only have one address of each type. Select this option if the field is a unique record identifier; otherwise, deselect it.Key type fields should also be required fields unless a combination of fields are specified as key types for an object.Note: It is recommended that each child object contain a key type field, but this is not required. If child objects do not contain one or more key type fields, each enterprise object might accumulate a very large number of child objects depending on the survivor strategy used.
Updateable	An indicator of whether the field can be updated from the MIDM and external system messages. Select this option if the field can be updated; otherwise deselect it.
Required	An indicator of whether the field is required in order to save an enterprise object to the database. Select this option if the field is required; otherwise, deselect it.
Field Size	The number of characters allowed in each field. This determines the number of characters allowed in the database columns and defines the maximum number of characters that can be entered into each field on the MIDM.
Pattern	The required data pattern for the field. For more information about possible values and using Java patterns, see "Patterns" in the class list for java.util.regex in the Javadocs provided with the Java EE Platform. You might want to define patterns for date, telephone, or SSN fields. Note that for the MIDM, the pattern is further restricted by the value entered for the input mask described later in this table. If no input mask is specified, all regex patterns are supported.
Code Module	The identification code for the drop-down list that appears for this field in the MIDM.Note: This must match an entry in the code column of the sbyn_common_header database table and, by default, an entry for the code you enter is created in the Code List database script. You can further customize code lists directly in the Code List script.
User Code	The processing code for the drop-down list that appears on the MIDM for the fields defined by the constraint-by property, described below. These codes are used for non-unique IDs, such as account numbers, insurance policies, credit cards, and so on.Note: This must match an entry in the code_list column of the sbyn_user_code database table.
Copnstrained By	The name of the field that contains the corresponding User Code value (described above) used to validate the current field. The User Code and Constrained By properties are used in conjunction to define non-unique ID types, such as credit card numbers or account numbers. The first purpose is to define a drop-down list for the field that contains the User Code value. The second purpose is to validate the field that contains the Constrained By value against definitions for the field with the user code value.For example, if you store non-unique IDs such as credit card numbers or insurance policy numbers, you could create a field named ID Type with a User Code of CREDCARD (CREDCARD also needs to be defined as a code in the sbyn_user_code table). This gives the ID Type field a drop-down list based on the definitions for CREDCARD in the sbyn_user_code table. Definitions would be VISA, MASTERCARD, AMEX, and so on. You could then create a field named ID that would be constrained by the formats defined for the ID Type field. Any credit card numbers you enter would be validated against the format defined for the type of credit card you selected in ID Type.
Display Name	The name of the field as it will appear on the MIDM.
Input Mask	A mask used by the GUI to add punctuation to a field. For example, if users enter the date in the format MMDDYYYY, you can add an input mask to display the dates as MM/DD/YYYY. Use the value mask (described below) to strip the punctuation from the value before storing it in the database.To define an input mask, type a character type for each character in the field and place any necessary punctuation between the character types. For example, the input mask for the above date format is DD/DD/DDDD.Note that the value you enter can further restrict the data pattern for the field (this is the Pattern property). The following character types can be used. D - indicates a numeric character. L - indicates an alphabetic character. A - indicates an alphanumeric character.
Value Mask	A mask used by the index to strip any extra characters that were added by the input mask (see above). This mask ensures that data is stored in the database in the correct format.To specify a value mask, type the same value as is entered for the input mask, but type an "x" in place of each punctuation mark. For example, if an SSN field has an input mask of DDD-DD-DDDD, specify a value mask of DDDxDDxDDDD to strip the dashes before storing the SSN. A value mask is not required for date fields.

Master Person Index Field Property Elements

The following table lists and describes the properties you can define for each field in object.xml.

Element	Description
field-name	The name of the field. Follow the guidelines under "Master Person Index Field Name Restrictions" when naming fields.
field-type	The data type of the field. Possible values are: string - Fields of this type contain a string of characters. date - Fields of this type contain a date value. float - Fields of this type contain a floating point integer. int - Fields of this type contain an integer. char - Fields of this type contain a single character. boolean - Fields of this type can contain either true or false.
size	The number of characters allowed in each field. If you modify this element, be sure to modify the length of the corresponding database column accordingly.
undateable	An indicator of whether the field can be updated from the MIDM or by back-end messages. Specify true if the field can be updated, or specify false if it cannot.
required	An indicator of whether the field is required in order to save an enterprise object in the database. Specify true if the field is required, or specify false if it is not.
code-module	The identification code for the menu list that appears for this field in the MIDM. This must match a value in the code column of the sbyn_comment_header database table. This element is optional.
maximum-value	The maximum value allowed in the field. To specify a value for a date field, use the format YYYY-MM-DD. This element is optional.
minimum-value	The minimum value allowed in the field. To specify a value for a date field, use the format YYYY-MM-DD. This element is optional.
pattern	The required pattern for the field. For more information about possible values and using Java patterns, see "Patterns" in the class list for java.util.regex in the Javadocs provided with J2SE Platform. You might want to define patterns for date, telephone, or SSN fields. Note that for the MIDM, the pattern is further restricted by the value entered for the input mask. If no input mask is specified, all regex patterns are supported.This element is optional.
user-code	The processing code for the drop-down list that appears on the MIDM for the fields defined by the constraint-by property, described below. These codes are used for non-unique IDs, such as account numbers, insurance policies, credit cards, and so on.Note: This must match an entry in the code_list column of the sbyn_user_code database table.
constraint-by	The name of the field that contains the corresponding user-code value (described above) used to validate the current field. The user-code and constraint-by properties are used in conjunction to define non-unique ID types, such as credit card numbers or account numbers. The first purpose is to define a drop-down list for the field that contains the user code value. The second purpose is to validate the field that contains the constraint value against definitions for the field with the user code value.For example, if you store non-unique IDs such as credit card numbers or insurance policy numbers, you could create a field named ID Type with a user-code of CREDCARD (CREDCARD also needs to be defined as a code in the sbyn_user_code table). This gives the ID Type field a drop-down list based on the definitions for CREDCARD in the sbyn_user_code table. Definitions would be VISA, MASTERCARD, AMEX, and so on. You could then create a field named ID that would be constrained by the formats defined for the ID Type field. Any credit card numbers you enter would be validated against the format defined for the type of credit card you selected in ID Type.
key-type	An indicator of whether the field is used to identify unique objects. Specify true if the element is a unique object identifier; specify false if it is not. Key type fields should also be required fields unless a combination of fields are specified as key types for an object. This element is optional.Note: Each child object should contain at least one field that is a unique object identifier, but this is not required. If two or more fields are unique identifiers, the combined value of these fields must be unique in a given enterprise record.