public interface MatchingOperations

Provides matching operations for the EBXâ„¢ Match and Merge Add-on. These operations must be called within a different EBX context, such as a: user service, script/user task, or trigger.

All the matching operations are required to have an activated matching configuration for the table.

The operations allow matching records or values against existing table records. Records that are in a merged or deleted state are not considered. The dataspace is locked during the execution a matching operation to prevent concurrent modification of the data.

Using this class

In order to create an instance of this class, the external program must provide an authenticated session:

  MatchingOperations.getMatchingOperations(session);

Performance

To ensure the best performance when matching, please review the Matching performance topic in the Administrator Guide. //

Code Sample

 public class CustomMatchingUserServiceSample implements UserService {

     public void setupDisplay(UserServiceSetupDisplayContext context, UserServiceDisplayConfigurator configurator) {

         Session session = context.getSession();
         AdaptationHome dataspace = context.getRepository().lookupHome(HomeKey.parse("BMAME-TEST"));
         Adaptation dataset = dataspace.findAdaptationOrNull(AdaptationName.forName("testMame"));
         AdaptationTable table = dataset.getTable(Path.parse(PathPerson._People.getPathInSchema().format()));

         MatchingOperations matchingOperations = OperationsFactory.getMatchingOperations(session);

         // execute a synchronous matching process to match an EBX record only
                  PrimaryKey myPk = PrimaryKey.parseString("1");
            matchingOperations.matchRecord(table, myPk, "matchingPolicyCode_NameComp");

         // execute an asynchronous matching process to match an entire EBX table
           MatchingProcess matchingProcessTable = matchingOperations.matchTable(table, null);

         // execute an asynchronous matching process to match an entire table
           Request request = table.createRequest();
           RequestSortCriteria sortCriteriaOnPersonFirstName = new RequestSortCriteria();
           sortCriteriaOnPersonFirstName.add(PathPerson._People._FirstName);
           request.setSortCriteria(sortCriteriaOnPersonFirstName);

           MatchingProcess matchingProcessRecords = matchingOperations.matchRecords(table, request, "matchingPolicyCode");

         // execute simulate match on a record
           Adaptation record2 = table.lookupAdaptationByPrimaryKey(PrimaryKey.parseString("2"));

           SimulationResult simulationResult = matchingOperations.simulateMatch(record2, null);

         // execute simulate match on a field node with specific a specific value
           Map <SchemaNode, Object> myMap = new HashMap<>();
           SchemaNode schemaNode = table.getTableNode().getNode(PathPerson._People._LastName);
           myMap.put(schemaNode, "test");

           SimulationResult simulationResultForSpecificValues = matchingOperations.simulateMatch(table, myMap, null);

         // execute evaluate matching between two records
         // that using default matching policy
           Adaptation record3 = table
                   .lookupAdaptationByPrimaryKey(PrimaryKey.parseString("3"));
           EvaluateMatchingResult evaluateMatchingResult = matchingOperations
                   .evaluateMatching(record2, record3, null);

           // gets result of pre-processing
           PreProcessingResult preProcessingResult = evaluateMatchingResult
                                                    .getPreProcessingResult();

           // gets result of decision tree execution
           MatchingResultType matchingResult = evaluateMatchingResult
                                                         .getMatchingResult();

           // gets and travels decision tree nodes in the decision
           // from the root node to the last node
           Iterator<DecisionNode> decisionNodes =
                                          evaluationMatchingResult
                                                  .getDecisionNodes()
                                                  .iterator();

           MatchingResultType matchingResult;
           while (decisionNodes.hasNext()) {
               DecisionNode currentNode = decisionNodes.next();
               if (currentNode.isLastNode()) {
                   matchingResult = currentNode.getMatchingResult();
               } else {
                   System.out.println("Decision node name: "
                                                     + currentNode.getName());
                   Collection<DecisionField> decisionFields =
                                      currentNode.getDecisionFields();
                   for (DecisionField field : decisionFields) {
                       System.out.println(
                          String.format("Field %s - Score %f",
                                                  field.getLabel(),
                                                  field.getComparisonScore())
                       );
                   }
               }
           }
      }
 }

Method Summary

Modifier and Type

Method

Description

EvaluateMatchingResult

evaluateMatching(com.onwbp.adaptation.Adaptation record1, com.onwbp.adaptation.Adaptation record2, String policyCodeOrNull)

Executes an evaluate matching operation on two records.

MatchingComparator

getComparator(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull)

Creates a comparator to compare records based on decision tree configured in matching policy.

void

matchRecord(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.PrimaryKey recordPrimaryKey, String policyCodeOrNull)

Executes a matching operation on a record against an EBX table.

MatchingProcess

matchRecords(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.Request request, String policyCodeOrNull)

Executes a matching operation with a specific request on a EBX table.

MatchingProcess

matchTable(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull)

Executes a matching operation on an entire EBX table.

SimulationResult

simulateMatch(com.onwbp.adaptation.Adaptation record, String policyCodeOrNull)

Simulates a match record operation.

SimulationResult

simulateMatch(com.onwbp.adaptation.AdaptationTable table, Map<com.orchestranetworks.schema.SchemaNode,Object> values, String policyCodeOrNull)

Simulates a match table operation for specific values.

Method Details
- matchRecord
  
  void matchRecord(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.PrimaryKey recordPrimaryKey, String policyCodeOrNull) throws com.orchestranetworks.service.OperationException, com.orchestranetworks.addon.mame.common.InvalidStateException, com.orchestranetworks.addon.mame.common.InvalidParameterException
  
  Executes a matching operation on a record against an EBX table. Note that this method execute a synchronous matching process.
  
  Parameters:
  
  table - An EBX table
  
  recordPrimaryKey - The record on which you want to run matching
  
  policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy
  
  Throws:
  
  com.orchestranetworks.service.OperationException - When unexpected errors occurs
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive
- matchTable
  
  MatchingProcess matchTable(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull) throws com.orchestranetworks.service.OperationException, com.orchestranetworks.addon.mame.common.InvalidStateException, com.orchestranetworks.addon.mame.common.InvalidParameterException
  
  Executes a matching operation on an entire EBX table. Note that this method execute an asynchronous matching process.
  
  Parameters:
  
  table - An EBX table
  
  policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy
  
  Returns:
  
  MatchingProcess The information of a matching execution
  
  Throws:
  
  com.orchestranetworks.service.OperationException - When unexpected errors occurs
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When at least on of the parameters is not valid
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive 4. An asynchronous matching process is already running in the same table
- matchRecords
  
  MatchingProcess matchRecords(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.Request request, String policyCodeOrNull) throws com.orchestranetworks.service.OperationException, com.orchestranetworks.addon.mame.common.InvalidStateException, com.orchestranetworks.addon.mame.common.InvalidParameterException
  
  Executes a matching operation with a specific request on a EBX table. Note that this method execute an asynchronous matching process.
  
  Parameters:
  
  request - EBX Request from a table
  
  policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy
  
  Returns:
  
  MatchingProcess The information of a matching execution
  
  Throws:
  
  com.orchestranetworks.service.OperationException - When unexpected errors occur
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When no records are not found in the 'request' or the 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive 4. An asynchronous matching process is already running in the same table
- simulateMatch
  
  SimulationResult simulateMatch(com.onwbp.adaptation.Adaptation record, String policyCodeOrNull) throws com.orchestranetworks.addon.mame.common.InvalidParameterException, com.orchestranetworks.addon.mame.common.InvalidStateException
  
  Simulates a match record operation. When the simulate service is called, matching results are not persisted into the MatchResult table.
  
  Parameters:
  
  record - The record on which we want to perform the simulation to find matches or suspects
  
  policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy
  
  Returns:
  
  SimulationResult The information of the matching simulation.
  
  Throws:
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive
- simulateMatch
  
  SimulationResult simulateMatch(com.onwbp.adaptation.AdaptationTable table, Map<com.orchestranetworks.schema.SchemaNode,Object> values, String policyCodeOrNull) throws com.orchestranetworks.addon.mame.common.InvalidParameterException, com.orchestranetworks.addon.mame.common.InvalidStateException, com.orchestranetworks.service.OperationException
  
  Simulates a match table operation for specific values. When the simulate service is called, matching results are not persisted in the MatchResult table.
  
  Parameters:
  
  table - An EBX table
  
  values - A value represents an EBX schema node with a specific value
  
  policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy
  
  Returns:
  
  SimulationResult The information of the matching simulation.
  
  Throws:
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive
  
  com.orchestranetworks.service.OperationException
- getComparator
  
  MatchingComparator getComparator(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull) throws com.orchestranetworks.addon.mame.common.InvalidParameterException, com.orchestranetworks.addon.mame.common.InvalidStateException
  
  Creates a comparator to compare records based on decision tree configured in matching policy.
  
  Parameters:
  
  table - An EBX table
  
  policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy
  
  Returns:
  
  AdaptationComparator
  
  Throws:
  
  com.orchestranetworks.addon.mame.common.InvalidParameterException - The 'policyCode' is empty
  
  com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive
- evaluateMatching
  
  EvaluateMatchingResult evaluateMatching(com.onwbp.adaptation.Adaptation record1, com.onwbp.adaptation.Adaptation record2, String policyCodeOrNull)
  
  Executes an evaluate matching operation on two records.
  This operation runs a match on the given records, and provides an explanation of the result.
  Parameters:
  
  record1 - first record to evaluate
  
  record2 - second record to evaluate
  
  policyCodeOrNull - identifier of the matching policy. Specify null to apply the default matching policy
  
  Throws:
  
  IllegalArgumentException - When one of the following errors occurs:
  
  The policyCodeOrNull is empty
  
  One or both records are excluded by the matching policy
  
  The records do not belong to same table
  
  The records were confirmed as a false positive match
  
  IllegalStateException - When one of the following errors occurs:
  
  No matching policy conforms to the input policyCodeOrNull
  
  Matching on the current table is paused
  
  Matching policy is found, but inactive

Interface MatchingOperations

Using this class

Performance

Code Sample

Method Summary

Method Details

matchRecord

matchTable

matchRecords

simulateMatch

simulateMatch

getComparator

evaluateMatching