getSimilarObjects in SOAP API

Before creating new objects in STEP, matching algorithms can be used to search for similar existing objects, ensuring duplicates are not created.

Matching logic can be applied to three different 'search before create' methods:

  • The 'Duplicate Handler' on an 'Initiate Item' workflow screen in Web UI. For more information, refer to the Initiate Item Screen topic in Web User Interfaces documentation here.
  • The 'Find Similar' search on an 'Add Reference' action in Web UI. For more information, refer to the Add Reference Action topic in the Web User Interfaces documentation here.
  • 'getSimilarObjects' SOAP web service request. For more information, refer to the Find Similar (getSimilarObjects) topic in the Customer MDM Solution Enablement documentation here.

For use case examples, refer to the Find Similar Web Service topic in Customer MDM Solution Enablement documentation here.

The key to Find Similar getSimilarObjects functionality is the matching setup that the customer creates and uses for duplicate handling. Every time a user enters data into the search fields and clicks OK, the Find Similar search checks the match code values involved, executes the relevant matching algorithm, and provides a set of results, if any are found. If a user is not getting the expected results, one area to assess is the algorithm configured in the 'Duplicate Handler' parameter in the 'Add Reference Action' properties. Two bind types work with the Find Similar functionality:

  1. First Match Object
  2. Second Match Object

A relevant match code and matching algorithm needs to be set up before attempting to use the Find Similar Search tab. For more information about setting up and using matching algorithms, refer to the Configuring Matching Algorithms topic of this documentation here.

The matching logic is applied by comparing potential new objects with that of existing objects. More specifically, match codes are generated for the incoming objects, compared to existing objects with similar match codes, and if matches are found, a list is returned of all matched objects with match scores (also called the 'rank score' in Web UI) that met or exceeded the configured threshold in the request. Using this list, the user can decide whether to create a new object or use an existing one.

Request

The 'getSimilarObjects' request defines the criteria for the match and the information to be returned. The following should be supplied in the call.

  • Access Context - This parameter contains the username and password for the user accessing the system. It may optionally contain the context and workspace as well.
  • Values - The values supplied are used by the matching engine for comparison. The property URL points to the URL of the attribute ID in the system that the value should be associated with for comparison.
  • Object Type URL - This parameter is the URL of the object type in the system which will be used as a base for comparison.
  • Matching Algorithm URL - The URL of the matching algorithm in the system to perform the comparison.
  • Export Configuration XML - This optional section defines the information in XML format of the potential duplicates to be returned in the response. If excluded from the request, the STEP ID, STEP URL, Title, Super Type, Object Type URL, and Score will be returned. The records will be returned in order of highest score to lowest score.
  • Search Threshold - The score threshold of potential duplicates to be returned. If the search threshold is 70, only records that match the supplied values with a score of 70 or above will be returned in the response. The Clerical Review Threshold and the Auto Threshold defined in the matching algorithm are ignored. Refer to the Configuring Matching Algorithms topic for details here.
  • Max Count - The maximum number of potential duplicates to return. If the matching algorithm identifies 100 records that score above the Search Threshold and the Max Count is set to 10, only the top 10 scoring records will be returned in the response.

Match Algorithm Configuration

The 'getSimilarObjects' request relies on the match algorithm to search. For a successful match, the match codes must exist and be up to date on the records and match criteria must be set up in the system. For information on a match code formula that can access the Find Similar values, refer to the getSimilarObjects Node Binds topic here.