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
Service name: Party
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.
In these scenarios, the empty group's EndDate is set to the current timestamp and the group is ended.
Request message
TCRMTxType> formPartyGroupingProbabilistic

<TCRMTxObject> TCRMFormPartyGroupingProbabilisticRequestBObj

<TCRMObject> TCRMFormPartyGroupingProbabilisticRequestBObj

with required business objects:

Response objects
FormPartyGroupingProbabilisticResponseBObj

with optional business objects:

Special note
Not applicable