getPartyByAdminSysKey

Description

This inquiry transaction uses a specified external administrative system party ID to retrieve the InfoSphere® MDM party information for a given party. Note: This transaction can also be used in a hybrid MDM implementation to retrieve the configured composite view of the party from virtual MDM if only cross-reference keys of the entity are persisted in physical MDM.

Web Services

Operation name: getPartyByAdminSysKey

Service name: PartyService

Example

Retrieve details for the Person party Kimberly Carrol using her unique customer ID from the CRM source system.

Retrieve the configured composite view of the entity from virtual MDM since only the cross-reference keys for the entity have been persisted in a hybrid MDM implementation.

Retrieve the persisted view of the entity from physical MDM since the entity has been fully persisted in a hybrid MDM implementation.

Usage information

The input for this transaction is:

The type of the administrative system in which the primary key is maintained, AdminSystemType
The external administrative system primary key, AdminPartyId
An inquiry level

The inquiry level controls the detail of information returned for the party being queried.

Preconditions

Not applicable

Mandatory input

AdminSystemType
AdminPartyId
InquiryLevel

Inquiry levels

PartyInquiryLevel:

Level 0 - returns Party data including names, identifications, party privacy preferences, line of business relationships, and either personal data, if a Person, or organizational data, if an Organization.
Level 1 - returns level 0 data plus all party addresses and contact methods.
Level 2 - returns level 1 data plus all party relationship data.
Level 3 - returns level 2 data plus all party bank account, party charge card, and income source data.
Level 4 - returns level 3 data plus all party value data.

The default inquiry levels are configured for use with physical MDM and are based on the data model for physical MDM. For hybrid MDM implementations, rather than using the default inquiry levels, consider creating custom inquiry levels that account for how the person or organization entities are defined within the shared virtual MDM and physical MDM data models.

For hybrid MDM implementations, you can create a new inquiry level to verify that the members for the virtual MDM entity and the members for the physical MDM entity are in synch. For details, see the Special note section at the end of this topic.

Filter values

Not applicable

Transaction behavior

If both active and inactive parties exist that match the specified administrative system type and key, this transaction returns the active party with the most recent last update date value. However, if only inactive parties are found that match the specified administrative system type and key, this transaction returns the inactive party with the most recent last update date.

Whether or not this transaction retrieves additional detail about when the data was last used or verified (that is, the AccessDateValue) depends on the value of the global flag attrib_access_date_value property. If the attrib_access_date_value flag is turned on, then this transaction returns the AccessDateValue at the attribute level.

Note: If you have implemented a hybrid MDM solution, the transaction uses both entity link status and entity status to determine whether to retrieve the party details from physical MDM or from virtual MDM. If the entity is fully persisted, then the persisted party in physical MDM is returned. If only the cross-reference keys of the entity are persisted (entity registration), or if the entity status indicates that the last update of a fully persisted entity has failed, then the configured composite view of the entity from virtual MDM is returned. Supplemental attributes added to the entity in physical MDM are also returned if the attributes are included in the inquiry level specified.

Table 1. Summary of where Party details are retrieved from in a Hybrid MDM solution
Entity Link Status:	Entity Status:	Party details are retrieved from:
1 (entity registration)	<null>	Virtual MDM
1 (entity registration)	1 (Persisted entity is up-to-date)	Virtual MDM
1 (entity registration)	2 (Last entity update from virtual MDM failed)	Virtual MDM
2 (full persistence)	<null>	Physical MDM
2 (full persistence)	1 (Persisted entity is up-to-date) or <null>	Physical MDM
2 (full persistence)	2 (Last entity update from virtual MDM failed)	Virtual MDM

Request message

<InquiryType> getPartyByAdminSysKey

Response objects

Party details, depending on the value of InquiryLevel:

0 includes:
- TCRMPersonBObj or TCRMOrganizationBObj
- TCRMPersonNameBObj list or TCRMOrganizationNameBObj list
- TCRMPartyIdentificationBObj list
- TCRMPartyPrivPrefBObj list
- TCRMPartyLobRelationshipBObj list
1 includes level 0 plus:
- TCRMPartyAddressBObj list, each with associated TCRMAddressBObj
- TCRMPartyContactMethodBObj list, each with associated TCRMContactMethodBObj
2 returns the same data as level 1
3 includes level 2 plus:
- TCRMPartyBankAccountBObj list
- TCRMPartyChargeCardBObj list
- TCRMIncomeSourceBObj list
4 includes level 3 plus TCRMPartyValueBObj

Special notes

For hybrid MDM implementations, an additional validation is available to determine whether the entity that has been retrieved by using a particular AdminSysKey still has the same AdminSysKey as the entity within the virtual MDM. In other words, the validation determines whether the members for the virtual MDM entity and the members for the physical MDM entity are out of synch.
The validation addresses the following situation: On the virtual MDM, an update occurs which moves members between entities. While the event notification mechanism is replicating the update to the virtual MDM, the user issues a getPartyByEntityId request for the same entity. The request can potentially return an entity that is no longer associated with the member used to request it. In other words, the membership information for the entity can be out of synch.

If the validation fails, the request returns an error message rather than the requested entity. Note that the validation is only active when ContEquiv (AdminSysKey) records are part of the inquiry level. It is not a feature of any of the standard inquiry levels. To take advantage of the validation, create and use a new inquiry level that incorporates the AdminSysKey object.
In a hybrid MDM implementation, if InquireAsOfDate is provided in the request for a historical inquiry, then any historical records returned by the transaction apply only to the party records persisted in physical MDM.

Last updated: 5 Jun 2018