formPartyGroupingProbabilistic
- Description
- This coarse-grained transaction leverages the Probabilistic Matching Engine to identify party
grouping members (specifically, household group members) and then forms or updates Party Groupings
and Grouping Associations and associated Party Grouping Values and Party Grouping Roles using the
formPartyGrouping transaction.
As a result of this transaction, Party Groupings and their Grouping Associations to preexisting Groups, and potentially other preexisting Groups, may be altered, ended, or deleted based on the configured behavior. Depending on the configuration, Party Grouping Values and Party Grouping Roles may also be reassigned to newly formed or updated Party Groupings from preexisting Groups and Grouping Associations.
- Web Services
- Operation name: formPartyGroupingProbalilistic
- Example
- Identify John Smith and Mary Smith as members of a new household group by leveraging a Probabilistic Matching Engine household algorithm and form a new household group accordingly.
- Usage information
- The formPartyGroupingProbabilistic transaction uses the searchPersonProbabilistic transaction to identify
members of households by leveraging a PME algorithm. When using the default PME algorithm for households, provide one or more of the following criteria:
- Address
- Address is mandatory. The transaction request supports only one Address object per request.
- TCRMPartyAddressBObj.AddressUsageType
- TCRMPartyAddressBObj.AddressUsageValue
- TCRMAddressBObj.AddressLineOne
- TCRMAddressBObj.AddressLineTwo
- TCRMAddressBObj.City
- TCRMAddressBObj.ResidenceNumber
- TCRMAddressBObj.ProvinceStateType
- TCRMAddressBObj.ProvinceStateValue
- TCRMAddressBObj.ZipPostalCode
- Contact Method
- Contact Method is optional. The transaction request supports zero or more Contact Methods.
- TCRMPartyContactMethodBObj.ContactMethodUsageType
- TCRMPartyContactMethodBObj.ContactMethodUsageValue
- TCRMContactMethodBObj.ReferenceNumber
An external validator, FormPartyGroupingProbabilisticRequestBObjValidator, enables you to validate formPartyGroupingProbabilistic requests, force a single, mandatory address, and generate PartyGroupingName if not provided.
An external rule, #221, enables you to split the household group that was constructed based on the result of the searchPersonProbabilistic into multiple household groups, if necessary, and also to process the group or split groups based on customizable survivorship logic in the rule.
A configuration item, /IBM/Party/FormPartyGroupingProbabilistic/maximumGroupingAssociations, enables you to specify the maximum number of members each household group can have.
- Preconditions
- A Party must exist.
- Mandatory input
-
- TCRMPartyGroupingBObj.PartyGroupingType
- ProbabilisticPersonSearch.TCRMPartyAddressBObj
- Inquiry levels
- Not applicable
- Filter values
- Not applicable
- Transaction behavior
- This transaction uses the input from the request, a mandatory address and zero or more optional
contact methods, as search criteria to get a list of candidate members of a household group. The
transaction then splits the group into multiple groups when applicable and analyzes the surviving
groups to form new groups or update existing groups as required.
This transaction returns a list of TCRMPartyGroupingListBObj objects. Each TCRMPartyGroupingListBObj contains a newly formed or updated Party Grouping with a system-marked source type and any impacted or expired or deleted Party Groupings, including any of their Party Grouping Associations or any associated Party Grouping Values and Party Grouping Roles.
In each returned TCRMPartyGroupingListBObj, the first Party Grouping is the newly formed or updated Party Grouping with one or more of its Grouping Associations. All other Party Groupings returned in the response are impacted Party Groupings and their Party Grouping Associations. Associated Party Grouping Values and Party Grouping Roles may also be returned based on the configuration items described in the documentation for the transaction formPartyGrouping.
When the Probabilistic Matching Engine does not identify any candidate members of a household group, this transaction calls the formPartyGrouping transaction without associated party IDs. As a result, the transaction returns all expired or deleted preexisting Party Groupings and all of their Party Grouping Associations that share the same PartyGroupingType and PartyGroupingName. This is done based on the configuration items described in the documentation for the transaction formPartyGrouping. When there is no preexisting Party Grouping with same PartyGroupingType and PartyGroupingName, the transaction fails with an error message stating that no Grouping exists.
When a PartyGroupingName is not supplied in request, the system generates a PartyGroupingName, such as Household #NNNN, in which NNNN is a hash code of the concatenated values of the TCRMAddressBObj's attributes with a business key designation.
When a PartyGroupingName is supplied with an existing PartyGroupingName in the database, the system reforms the existing grouping using the new input.
An external rule, #221, returns a map of groups. If grouping associations in any group are more than the maximum number of members (configurable), then the transaction fails with an error message stating that the maximum number of grouping associations has been exceeded. If the returned map does not contain any groups, the transaction fails with an error message stating that the impacted grouping associations are user managed, and no update is required.
The formPartyGroupingProbabilistic transaction ignores any StartDate and EndDate values included in requests. The service exists to form new groups or reform existing groups, not to update or end groups. However, there are some scenarios that cause an existing group to be ended in the process of reforming an existing group:- If all of a group's grouping associations are reassigned to a newly formed group.
- If an existing groups is reformed as an empty group because no matching grouping associations were found.
- Request message
- TCRMTxType> formPartyGroupingProbabilistic
<TCRMTxObject> TCRMFormPartyGroupingProbabilisticRequestBObj
<TCRMObject> TCRMFormPartyGroupingProbabilisticRequestBObj
with required business objects:
- Response objects
- FormPartyGroupingProbabilisticResponseBObj
with optional business objects:
- List of TCRMPartyGroupingListBObj
- List of TCRMPartyGroupingBObj
- List of TCRMPartyGroupingAssociationBObj
- List of TCRMPartyGroupingValueBObj
- List of TCRMPartyGroupingRoleBObj
- Special note
- Not applicable