Migrating to Service-Enabled Oracle Java CAPS Master Index

If you create a master index project using Oracle Java CAPS Master Index (Repository) or if you upgrade a master index to the Repository version, you can migrate that project to the service-enabled version in order to take advantage of the new features and tools.

Follow these steps in the order given to migrate to a service-enabled master index:

Step 1: Create the Service-Enabled Master Index
Step 2: Migrate any Custom Plug-ins
Step 3: Update the Object Definition
Step 4: Update midm.xml
Step 5: Update the Master Controller
Step 6: Update the Matching and Standardization Configuration
Step 7: Update Query Definitions
Step 8: Update the Survivor Calculator
Step 9: Update Field Validations
Step 10: Validate the Configuration Files
Step 11: Update Match and Standardization Engine Files
Step 12: Upgrade the Database Connection and Security
Step 13: Finalizing the Upgrade
Step 14 (Optional): Update the Master Index API in Client Projects
Troubleshooting

Step 1: Create the Service-Enabled Master Index

The first step to migrating a master index project is to create a service-enabled master index project. This project should be similar to the project being upgraded, but does not need to be identical because you will copy over the configuration of the project you are upgrading before you generate the new master index application.

To Create the Service-Enabled Master Index

If you are migrating from version 5.1.3 or earlier, export the master index client and server projects from your 5.1.3 Repository and import them into your Java CAPS 6 Repository.
This is described in Upgrading to Oracle Java CAPS 6.3. You can export and import the Environments along with the projects.
If you are upgrading from a version earlier than 5.1.3, update the master index project as required for the version from which you are upgrading.
These updates are described in the Sun SeeBeyond eView Studio Upgrade Guide, Release 5.1.3, available at http://download.oracle.com/docs/cd/E19336–01/820–0965/820/0965.pdf.
Create a new, service-enabled master index application using the wizard, as described in Creating a Master Index Application in Oracle Java CAPS Master Index User’s Guide.
Tip - Follow these guidelines when creating the new master index application:
- The application name and parent object name need to be the same for the new service-enabled master index as for the Repository–based master index. They also need to be the same as each other.
- You can accept the defaults for the deployment environment in the wizard since these values will be populated when you update the configuration files.
- To make it simpler, you can create the object structure using one of the predefined templates.
- For the final step of the wizard, you do not need to generate all remaining files.
After you create the master index application, make backup copies of the configuration files. They are located in NetBeansProjects/ProjectName/src/Configuration.

Step 2: Migrate any Custom Plug-ins

If any custom plug-ins were created for the project you are upgrading, you need to migrate those Java classes to the service-enabled project. You create the new custom plug-in files manually in the ProjectName-ejb project, and then copy the text of the existing custom plug-ins into the new files. Minor text changes are also required.

To Migrate Custom Plug-ins

For each Java package used for the custom plug-ins in the master index project you are migrating, do the following:
1. In the Projects window, expand the ProjectName-ejb project associated with the new service-enabled master index project.
2. In the ProjectName-ejb project, right-click Source Packages, point to New, and then select Java Packages.
3. On the New Java Package Wizard, enter the name of the Java package for the custom plug-in.
  Note - In Repository-based master index projects, Java package names begin with “com.stc.eindex”. In the service-enabled projects, they begin with “com.sun.mdm.index”. You should update the custom plug-in package names accordingly.
4. Click Finish.
For each custom plug-in to be migrated, do the following:
1. Under Source Packages, right-click the Java package to which the custom plug-in belongs.
2. Point to New and then click Java Class.
3. On the New Java Class Wizard, enter the name of the Java class for the custom plug-in.
4. Click Finish.
5. Delete the default text in the new file.
6. Copy the text of the corresponding custom plug-in from the Repository-based project to the new file.
7. In the new file, update the package name for the new custom plug-in.
8. In the new file, update any package names by replacing all instances of “com.stc.eindex” with “com.sun.mdm.index”.
Note - When you first create the custom plug-ins, there will be several context errors. They should be resolved once you generate and build the master index application later in the migration process.

Step 3: Update the Object Definition

To ensure that the object definition does not change between versions, you need to copy the text of the Object Definition file in the Repository-based project to the object.xml file in the service-enabled project and then make certain updates to the text.

To Update object.xml

In the service-enabled project, delete the text of object.xml.
Copy and paste the text of the Object Definition file from the Repository–based master index application into object.xml in the service-enabled application.
Change the name of the eview element to Configuration (be sure to capitalize the 'C'). Change both the opening tag near the beginning of the file and the closing tag near the end of the file.
In the newly named Configuration element, change "sbyn:SeeBeyond/eView/schema/eIndex.xsd" to "schema/object.xsd".
Save and close the file.

Step 4: Update midm.xml

The upgrade from the Enterprise Data Manager file in the Repository-based project to midm.xml in the service-enabled project is partially automated. A few updates to the text need to be performed manually, but the bulk of the update is done through the Configuration Editor.

To Update midm.xml

In the service-enabled project, delete the text of midm.xml.
Copy and paste the text of the Enterprise Data Manager file from the Repository–based master index application to midm.xml in the service-enabled application.
In the edm element near the top of the file, change the name of the element from “edm” to “midm”, and change “sbyn:SeeBeyond/eView/schema/EDM.xsd" to "schema/midm.xsd". Be sure to change both the opening and closing edm tags.
These are the lines you need to change:
```
<edm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="sbyn:SeeBeyond/eView/schema/EDM.xsd">
...
</edm>
```
When you are done, the lines should look like this:
```
<midm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="schema/midm.xsd">
...
</midm>
```
Change all instances of "com.stc.eindex" to "com.sun.mdm.index".
Save and close the file.
In the service-enabled project, right-click the Configuration node and then select Edit.
The Configuration Editor appears.
Enable the Save button by making a small change to the master index configuration and then changing it back.
Note - This change is just to enable the Save command so you can save midm.xml in the new format. For example, you can change the data type for one of the fields and then change it back to its original value.
Click Save on the Configuration Editor toolbar, and then close the Configuration Editor.

Open midm.xml again, and perform the following steps:

Check whether any date fields have a max-length element with a value of –1. If you find fields with this value, change it to the correct value.
Tip - An easy way to check for these values is to right-click in the text of the file and then click Validate XML. If you get errors similar to The value '–1' of element 'max-length' is not valid., click on the error and the cursor will move to the errant text in the file.

Reformat the Reports page. Near the end of the file, delete the reports element and all of its contents, and then replace it with the following text.

<reports>
   <root-object>Person</root-object>
   <tab-name>Reports</tab-name>
   <screen-id>6</screen-id>
   <display-order>5</display-order>
   <search-pages/>
   <search-result-pages/>
   <subscreen-configurations>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Potential Duplicate Report</tab-name>
           <report-name>Potential Duplicate</report-name>
           <screen-id>0</screen-id>
           <display-order>5</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
                   <field-group>
                       <description/>
                       <field-ref>Person.FirstName</field-ref>
                       <field-ref>Person.LastName</field-ref>
                       <field-ref>Person.SSN</field-ref>
                       <field-ref>Person.DOB</field-ref>
                       <field-ref>Person.Gender</field-ref>
                   </field-group>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Deactivated Record Report</tab-name>
           <report-name>Deactivated</report-name>
           <screen-id>1</screen-id>
           <display-order>1</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Merged Transaction Report</tab-name>
           <report-name>Merged</report-name>
           <screen-id>2</screen-id>
           <display-order>0</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
                   <field-group>
                       <description/>
                       <field-ref>Person.FirstName</field-ref>
                       <field-ref>Person.LastName</field-ref>
                       <field-ref>Person.SSN</field-ref>
                   </field-group>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Unmerged Transaction Report</tab-name>
           <report-name>Unmerged</report-name>
           <screen-id>3</screen-id>
           <display-order>2</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Updated Record Report</tab-name>
           <report-name>Update</report-name>
           <screen-id>4</screen-id>
           <display-order>3</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
                   <field-group>
                       <description/>
                       <field-ref>Person.FirstName</field-ref>
                       <field-ref>Person.SSN</field-ref>
                       <field-ref>Person.Address.AddressLine1</field-ref>
                   </field-group>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
       <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Activity Report</tab-name>
           <report-name>Transaction Summary</report-name>
           <screen-id>5</screen-id>
           <display-order>4</display-order>
           <search-pages>
               <simple-search-page>
                   <screen-title>Weekly Activity</screen-title>
                   <report-name>Weekly Transaction Summary Report</report-name>
                   <search-result-id>0</search-result-id>
                   <search-screen-order>1</search-screen-order>
                   <field-group/>
               </simple-search-page>
               <simple-search-page>
                   <screen-title>Monthly Activity</screen-title>
                   <report-name>Monthly Transaction Summary Report</report-name>
                   <search-result-id>0</search-result-id>
                   <search-screen-order>2</search-screen-order>
                   <field-group/>
               </simple-search-page>
               <simple-search-page>
                   <screen-title>Yearly Activity</screen-title>
                   <report-name>Yearly Transaction Summary Report</report-name>
                   <search-result-id>0</search-result-id>
                   <search-screen-order>3</search-screen-order>
                   <field-group/>
               </simple-search-page>
           </search-pages>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
                   <field-group/>
               </search-result-list-page>
           </search-result-pages>
        </subscreen>
        <subscreen>
           <enable>true</enable>
           <root-object>Person</root-object>
           <tab-name>Assumed Matches Report</tab-name>
           <report-name>Assumed Match</report-name>
           <screen-id>6</screen-id>
           <display-order>6</display-order>
           <search-pages/>
           <search-result-pages>
               <search-result-list-page>
                   <search-result-id>0</search-result-id>
                   <item-per-page>10</item-per-page>
                   <max-result-size>2000</max-result-size>
                   <field-group>
                       <description/>
                       <field-ref>Person.FirstName</field-ref>
                       <field-ref>Person.LastName</field-ref>
                       <field-ref>Person.SSN</field-ref>
                   </field-group>
               </search-result-list-page>
           </search-result-pages>
       </subscreen>
   </subscreen-configurations>
</reports>

If necessary, customize the code above by replacing the values of the field-ref elements, replacing the value of the root-object elements, and configuring the items per page and maximum result size for each report.
Verify that the screen ID and display order in the above text is not the same as the screen ID or display order for any other of the primary MIDM pages.
Verify that there are no empty root-object elements. In each empty root-object element you find, insert the name of the parent object. For example:
```
<root-object>Person</root-object>
```
Validate midm.xml by right-clicking in the text and selecting Validate XML.

Step 5: Update the Master Controller

The Threshold file is upgraded by copying the text of the file to the service-enabled project and then updating certain portions of the file. There are only minor differences between the Threshold file in the Repository-based project and master.xml in the service-enabled project. In addition to updating the package name and XSD location, you can also update the file to take advantage of the new distributed transaction capabilities in Oracle Java CAPS Master Index.

To Update master.xml

In the service-enabled project, delete the text of master.xml.
Copy and paste the text of the Threshold file from the Repository–based master index application to master.xml in the service-enabled application.
In the Configuration element near the top of the file, change "sbyn:SeeBeyond/eView/schema/master.xsd" to "schema/master.xsd".
Change all instances of "com.stc.eindex" to "com.sun.mdm.index".
After the execute-match element, add a new element named transaction. Set the value of this element to LOCAL, CONTAINER, or BEAN.
- LOCAL means transactions are not distributed. Using this option gives you the same behavior as in previous versions.
- CONTAINER means transaction are distributed across applications.
- BEAN means transaction are distributed within the master index application.
Save and close the file.

Step 6: Update the Matching and Standardization Configuration

The Match Field file is updated by copying the text of the file to the service-enabled project and then updating certain portions of the file. To update the Match Field file in the Repository-based project to mefa.xml in the service-enabled project, you only need to change the location of the XSD file and the names of the Java packages accessed by the file.

To Update mefa.xml

In the service-enabled project, delete the text of mefa.xml.
Copy and paste the text of the Match Field file from the Repository–based master index application to mefa.xml in the service-enabled application.
In the Configuration element near the top of the file, change "sbyn:SeeBeyond/eView/schema/mefa.xsd" to "schema/mefa.xsd".
Change all instances of "com.stc.eindex" to "com.sun.mdm.index".
Save and close the file.

Step 7: Update Query Definitions

To update the query definitions of the Repository-based project, you need to copy the text of the Candidate Select file in the Repository-based project to query.xml in the service-enabled project and then update certain portions of the file. For this file, you only need to change the location of the XSD file and the names of the Java packages accessed by the file.

To Update query.xml

In the service-enabled project, delete the text of query.xml.
Copy and paste the text of the Candidate Select file from the Repository–based master index application to query.xml in the service-enabled application.
In the Configuration element near the top of the file, change "sbyn:SeeBeyond/eView/schema/query.xsd" to "schema/query.xsd".
Change all instances of "com.stc.eindex" to "com.sun.mdm.index".
Save and close the file.

Step 8: Update the Survivor Calculator

To update the Best Record file in the Repository-based project to update.xml in the service-enabled project, you need to copy the text of the Repository-based file to the service-enabled file and then update certain portions of the file. You only need to change the location of the XSD file and the names of the Java packages accessed by the file. If custom update policies are defined for the master index, you also need to update the Java package and class names for the policies.

To Update update.xml

In the service-enabled project, delete the text of update.xml.
Copy and paste the text of the Best Record file from the Repository–based master index application to update.xml in the service-enabled application.
In the Configuration element near the top of the file, change "sbyn:SeeBeyond/eView/schema/update.xsd" to "schema/update.xsd".
If update policies are defined, scroll to the bottom of the page and update the Java package and class names of the policies to the names you gave them in Step 2: Migrate any Custom Plug-ins.
Change all instances of "com.stc.eindex" to "com.sun.mdm.index".
Save and close the file.

Step 9: Update Field Validations

You only need to update the Field Validation file if you defined custom field validations in the Repository-based project. If you do need to update the file, you only need to copy the text to the service-enabled project and then change the location of the XSD file and the names of the Java packages accessed by the file.

To Update validation.xml

In the service-enabled project, delete the text of validation.xml.
If you have defined custom field validations, copy and paste the text of the Field Validation file from the Repository–based master index application to validation.xml in the service-enabled application.
In the Configuration element near the top of the file, change "sbyn:SeeBeyond/eView/schema/validation.xsd" to "schema/validation.xsd".
Change all instances of "com.stc.eindex" to "com.sun.mdm.index", and update the Java package and class names for any custom plug-ins.
Save and close the file.

Step 10: Validate the Configuration Files

Once you have updated all the configuration files and used the Configuration Editor to complete the process, you should validate each file against its corresponding schema file to ensure the project can be built.

To Validate the Configuration Files

Open the file in the XML editor.
Right-click in the text of the file, and select Validate XML.
If necessary, fix any validation errors and revalidate the file.
When the file passes validation, save and close the file.

Step 11: Update Match and Standardization Engine Files

The match engine configuration file has not changed since the previous release, and can be copied directly into the service-enabled project. Some of the standardization files were changed extensively. If you want to use the previous configuration for the person name standardization files, you will need to reformat the files.

To Update Match Engine Files

If matchConfigFile.cfg was customized in the Repository-based version, copy the text of the file into the service-enabled version, replacing all existing text. If the file was not customized for your implementation, you can skip this step.

To Update Standardization Engine Files

If any Address or Business Name files were customized in the Repository-based project, copy the text of those files and paste it into the corresponding service-enabled files, replacing the existing text.

File names have changed as indicated in the following table. Any Address or Business Name files not listed here have the same name in both versions. Make sure you when you update the files that you update the correct country set.

Repository-Based File Name	Service-Enabled File Name
addressClueAbbrev*.dat	clues.dat
addressMasterClues*.dat	masterClues.dat
addressPatterns*.dat	patterns.dat
addressConstants*.cfg	Obsolete
addressInternalConstants*.cfg	Obsolete
addressOutPatterns.dat	Obsolete
bizConstants.cfg	Obsolete
bizRemoveSpecChars.dat	Obsolete

If any Person Name files were customized in the Repository-based project, do one of the following:

Manually make the changes to the service-enabled version.

File names have changed for this release, as indicated in the following table. The following files are obsolete: personNamePatt.dat, personConstants.cfg, personFirstNameDash.dat, personRemoveSpecChars.dat, personThree*.dat, personTwo*.dat, personLastNamePrefix*.dat, and personConjon*.dat.

Repository-Based File Name	Service-Enabled File Name
personFirstName*.dat	givenNameNormalization.txt and givenName.txt
personGenSuffix.dat and person.OccupSuffix.dat	generationNormalization.txt and generation.txt
personTitle.dat	titleNormalization.txt and title.txt

Copy the text from the Repository-based files and paste it into the corresponding service-enabled files, replacing the existing text. Make sure to copy the text into the correct country files. Then reformat the file based on the new two-column format, as shown below:
```
STEVE|STEPHEN
STEWART|STUART
STEW|STUART
STU|STUART
SUE|SUSAN
SULLY|SULLIVAN
```
Note - For more information about the new standardization files, see FSM–Based Person Name Configuration, in Understanding the Master Index Standardization Engine.

You can customize the following new Person Name files: salutationNormalization.txt, salutation.txt, surnameNormalization.txt, and surname.txt.

Step 12: Upgrade the Database Connection and Security

When you migrate to service-enabled Master Index, you need to redefine the database connection pool in the application server Admin Console. You also need to set up security on the Admin Console.

Caution - As of Java CAPS Release 6 Update 1, you need to define two connection pools and two JDBC resources for Oracle Java CAPS Master Index. For more information and instructions, see Defining the Database Connection Pools in Oracle Java CAPS Master Index User’s Guide.

To Upgrade the Database Connection and Security

Start the application server and database.
In the application server Admin Console, create the JDBC connection pool and data source. This procedure is described in Defining the Database Connection Pools in Oracle Java CAPS Master Index User’s Guide.
Tip - For the connection pool, use the javax.sql.DataSource class for the same functionality as in previous versions. If you specified distributed transactions when you updated master.xml, use the javax.sql.XADataSource class. Once you create the Connection Pool, you can test the configuration by clicking Ping at the top of the Connection Pool page.
In the application server Admin Console, update security for existing users. Security is described in Defining Master Index Data Manager Security in Oracle Java CAPS Master Index Maintenance Guide.
Note - If you created any custom user roles or groups for the Repository-based version, you can create corresponding roles in midm-security.xml.

Step 13: Finalizing the Upgrade

Finalizing the project includes building the project, verifying the custom plug-ins, and finally deploying the project. You can also take advantage of the new query, matching, and SBR filtering feature described in Filtering Default Values From Master Index Processes in Oracle Java CAPS Master Index Configuration Guide. Note that adding this feature might cause inconsistencies with the way records were previously matched, but can also prevent the incorrect matching of records or flagging them as potential duplicates.

To Finalize the Upgrade

Right-click the Master Index project, and then click Generate Master Index Files.
Build the project.
Building will compile the custom plug-ins you added previously.
If you upgraded any custom plug-ins, go back to the custom plug-ins you created in the EJB Source Packages folder and verify that the Java code no longer has context errors.
If you are using an outbound Topic to broadcast master index updates, create a topic named ApplicationNameTopic (where ApplicationName is the name of the master index application) and set up the external systems to subscribe to this topic.
Note - For more information about this process, see Broadcasting Master Index Updates to External Systems.
If you created any new user roles in midm-security.xml or security.xml, add those roles to web.xml and sun-web.xml. These files are located in the ProjectName-war project under Web Pages > WEB-INF.
Deploy the master index project.

Step 14 (Optional): Update the Master Index API in Client Projects

Once you build the master index project, a set of dynamic API methods are generated for use in web services, Collaborations, and Business Processes. In order to make the API available to Repository-based client projects, you need to generate a WSDL file and then import the generated file into the client project that will access the new service-enabled master index. Alternatively, you can upgrade the client projects using JBI components and call master index services from BPEL processes, web services, and Java clients.

To Update the Master Index API in Client Projects

In the NetBeans Projects window, expand the ProjectName–ejb project and then expand Web Services.
Right-click ApplicationNameEJBService and then select Generate and Copy WSDL.
Specify a location to store the WSDL file and click OK.
Right–click the Repository-based client project, point to Import, and then select Web Service Definition.
Follow the steps in the Import WSDL(s) Wizard.
A web service OTD for the ProjectNameEJBService is created. You can use this OTD to access the operations of the migrated master index application.

Troubleshooting

If you use the Configuration Editor to modify the master index application once all of the Repository-based information has been copied over, there might be invalid XML code in update.xml and mefa.xml.

Standardization and Normalization

Standardization and normalization structures might get removed from mefa.xml. If you use the Configuration Editor, be sure the check mefa.xml for any discrepancies.

Survivor Strategy

The Configuration Editor might make changes to the survivor strategy in update.xml that prevent the project from being built. To fix the file, do the following:

Open update.xml.

If any candidate fields have a specific strategy defined, reformat the XML structure for that candidate field by removing the forward slash at the end of the candidate-field element and adding a closing candidate-field element after the survivor-strategy element.

For example, the following excerpt:

<candidate-field name="Person.Phone[*].*"/>
   <survivor-strategy>
      <strategy-class>com.sun.mdm.index.survivor.impl.WeightedSurvivorStrategy
      </strategy-class>
      <parameters>
         <parameter>
            <parameter-name>ConfigurationModuleName</parameter-name>
            <parameter-type>java.lang.String</parameter-type>
            <parameter-value>WeightedSurvivorCalculator</parameter-value>
         </parameter>
      </parameters>
   </survivor-strategy>

Would change to this:

<candidate-field name="Person.Phone[*].*">
   <survivor-strategy>
      <strategy-class>com.sun.mdm.index.survivor.impl.WeightedSurvivorStrategy
      </strategy-class>
      <parameters>
         <parameter>
            <parameter-name>ConfigurationModuleName</parameter-name>
            <parameter-type>java.lang.String</parameter-type>
            <parameter-value>WeightedSurvivorCalculator</parameter-value>
         </parameter>
      </parameters>
   </survivor-strategy>
</candidate-field>

Skip Navigation Links
Exit Print View
	Upgrading to Oracle Java CAPS Master Index Java CAPS Documentation