searchPerson
- Description
- This transaction searches for a person party given a set of search criteria. A filter may be used with this transaction.
- Web Services
- Operation name: searchPerson
- Example
- Find a person party that uses the family name Troop and has the birth date January 6, 1981.
- Usage information
- Based on the search criteria provided, the search is performed
using a specific search strategy and execution path. The search is
executed based on the priority of the set of valid search criteria
provided using one of the strategies:
- ID search
- Address search
- Contact method search
- Name search
- Date of birth search
- AdminPartyId, an administration system primary key search
This transaction supports the Pagination feature.
- Preconditions
- Not applicable
- Mandatory input
- LastName or
- Address or
- IdentificationType and IdentificationNum or
- ContactMethodReferenceNumber and ContactMethodType or
- DateOfBirth or
- AdminPartyId
- Inquiry levels
- The search results returned in a search contain the basic details
of each party found. There may be times when additional details are
required. To facilitate this, the search transaction supports an InquiryLevelSource,
InquiryLevelType, and InquiryLevel.
An InquiryLevelSource dictates whether search result details are returned using product-defined behavior or an external rule. Valid values for InquiryLevelSource are:
- 0 or null – returns basic search results. InquiryLevelType and InquiryLevel are not applicable.
- 1 – returns additional party details based on product-defined behavior according to the values of InquiryLevelType and InquiryLevel.
- 2 – returns additional party details based on an externally defined inquiry (such as External Rule 9 – Search Party), according to the values of InquiryLevelType and InquiryLevel.
An InquiryLevelType describes what type of additional detail to retrieve and is coupled with an inquiry level and secondary inquiry level. InquiryLevelType is applicable only when the InquiryLevelSource value is 1 or 2. Valid values for InquiryLevelType are:
- 0 or null – returns basic search results. Any InquiryLevel provided will be ignored.
- 1 – If InquiryLevelSource is 1 (product-defined behavior), this returns additional party details based on the InquiryLevel value. If InquiryLevelSource is 2 (external rule driven inquiry), this returns additional party details as determined by the external rule and the provided inquiry levels.
An InquiryLevel is associated with an InquiryLevelType and determines the level of additional detail to be returned. The transaction can include up to two separate inquiry levels: InquiryLevel and SecondaryInquiryLevel.
- When InquiryLevelSource is 1 (product-defined behavior) and InquiryLevelType is 1, the InquiryLevel corresponds to the same party inquiry levels used in the getPerson transaction. If it is not set in the request, the default value of 0 is used. In this case, the SecondaryInquiryLevel is not used.
- When InquiryLevelSource is 2 (external rule driven inquiry) and InquiryLevelType is 1, the inquiry levels are dependent on External Rule 9 for search party. With the default rule, InquiryLevel is used as the contract inquiry level. In this case, a default value of 1 is used if not set in the request, since the getAllContractsByParty transaction requires an inquiry level of 1 or higher. SecondaryInquiryLevel is used as the party inquiry level. If not set in the request, the SecondaryInquiryLevel uses the default value of 0.
Note: For details on party inquiry levels and contract inquiry levels, see the getPerson, getOrganization and getContract transaction documentation. - Filter values
- A filter value can be supplied. Valid values are:
- ACTIVE – returns only active person records, including active child objects according to the inquiry level.
- INACTIVE – returns only inactive person records, including active child objects according to the inquiry level.
- ALL – returns all records matching the search criteria, both active and inactive. Only active child objects are returned.
If the filter value is not supplied, then all records are returned.
Filter values are case-sensitive and must be provided in upper case.
The filter value is applied to the set of person parties resulting from the search, but is not applied to any child object criteria used in the search.
- Wildcards
- You can perform searches using partial search criteria that include the wildcard character, which is a percent sign (%).
- Look-alikes
- You can perform searches using partial search criteria that include the look-alike character, which is a question mark (?).
- Phonetic search
- You may wish to search for a party using a phonetic, or sounds like, search. You can use a phonetic search to look for an organization name, family name, given name, or city. For example, you may search for the person ‘Stephen Leighton' using search criteria of ‘Steven Layton'.
- Common Name Exclusions
- Common Name Exclusion search provides the ability to provide search
criteria exclusions, for example, common family names, when searching
for persons. With this feature, long-running queries and searches
that yield large, meaningless results sets can be prevented. Specifically,
searches based on the following exclusion rules can be prohibited:
- Common family names
- Common family names with given names
- Common family names in selected cities
- Party macro role search
- You can search for a party within the context of its party macro role. When searching for a party by macro role, the party macro role must match the macro role search criteria. For each search criterion provided, a corresponding party macro role association, for example, the name, address, contact method, identifier, party equivalency, for that party macro role must exist; if they do not exist the search will fail.
- Search results
- The maximum number of parties returned in the transaction response is configurable in the
Configuration and Management component. It is also possible to set the maximum number of parties
returned within the transaction itself. However, if this number is higher than that set in the
Configuration and Management component, the number of parties returned in the response is set to the
Configuration and Management component limit. For example, if there are 200 person parties in the
database with the family name 'Smith' and the maximum search results returned on the
Configuration and Management component is set to 100, then a family name search for Smith will
return only 100 parties.
The search results are scored based on matching search criteria, and the search results list is then sorted by descending score.
When searching by party equivalency, the search results may include both person and organization business objects.
The following search configuration items control the types of address, name, and party identification that are used in the search. For all matched records, the entire set of party data is returned.- /IBM/Party/Search/ReturnValue/personIdentificationType
- /IBM/Party/Search/ReturnValue/personNameUsageType
- /IBM/Party/Search/ReturnValue/personAddressUsageType
For the first name usage type listed for personNameUsageType, the transaction returns both active and inactive names for that type. The transaction returns only active values for the other name usage types, address, contact number, and party identification.
For example, if the search return value for addresses (/IBM/Party/Search/ReturnValue/personAddressUsageType) is set to 1, then the first active address found with a usage type of 1 is returned in the search results. If the address with a usage type of 1 is inactive, then the transaction returns all active addresses associated with the party instead. If there is no active address, then no address is returned.
Additionally, if the configured return usage type is not available for a particular party, then the first available value returned by the database will be returned in the summary details. In this case, the returned values depend on the order of the values returned by the database.
Note: For more information about party search configuration items, see Configuring and customizing Party Search features. - Transaction behavior
- Based on the search criteria provided, the search is performed
using a specific search strategy and execution path. The search is
executed based on the priority of the set of valid search criteria
as defined in the following table:
Table 1. Search criteria priority Path Search criteria provided Search by strategy 1 IdentificationType and IdentificationNum Identification 2 AdminPartyID Party Equivalency 3 LastName + Full Address (AddrLineOne, CityName, ZipPostalCode, ProvStateType, CountryType) Person Name 4 Full Address (AddrLineOne, CityName, ZipPostalCode, ProvStateType, CountryType) Address 5 CityName + ZipPostalCode + ProvStateType Address 6 ContactMethodReferenceNumber and ContactMethodType Contact Method 7 LastName Person Name 8 DateOfBirth, with no wildcards or look-alikes Date of Birth The following table specifies the details associated with the Party and Contract Combined search strategy:- M/O = Mandatory/Optional
- S13n = Standardization
- Y/N = Yes/No
Table 2. Name search strategy Field M/O Wildcards Look-alikes S13n Phonetics LastName M Y (multiple) Y (multiple) Y Y GivenNameOne O Y (multiple) Y (multiple) Y Y GivenNameTwo O N N Y Y GivenNameThree O N N Y Y GivenNameFour O N N Y Y DateOfBirth O Y (multiple) Y (multiple) N N AddrLineOne O Y (multiple) Y (multiple) Y N AddrLineTwo O Y (multiple) Y (multiple) Y N AddrLineThree O Y (multiple) Y (multiple) Y N CityName O Y (multiple) Y (multiple) Y Y ZipPostalCode O Y (multiple) Y (multiple) Y N ProvStateType O N N Y N CountryType O N N Y N - Request message
- <TCRMTxType> SearchPerson
<TCRMTxObject> TCRMPersonSearchBObj
<TCRMObject> TCRMPersonSearchBObj
- Response objects
- TCRMPersonSearchResultBObj object
- Special note
- Not applicable