persistEntity
This transaction creates, updates, or deletes the single representation of a virtual MDM person or organization entity in physical MDM in a hybrid MDM implementation.
- Description
- The transaction can persist the virtual entity in one of two ways: 1. Persist only the cross-reference keys of the virtual entity (that is, the virtual entity ID and source member IDs associated with the entity). This is also referred to as entity registration. 2. Persist the single, configured composite view of the virtual entity, as well as the cross-reference keys. This is also referred to as full persistence.
- Web Services
- Operation name: persistEntity
- Service name: PersistEntity
- Example
- Add only the cross reference keys to the virtual entity in physical MDM as part of the initial loading of the data.
- Fully persist the virtual entity with the intention of later augmenting the party data with supplemental attributes, such as party alerts.
- Update the fully persisted entity if there is a change to the primary address in the existing view of the entity in virtual MDM.
- Update the persisted entity, including the cross reference keys, if a new member has joined the entity in virtual MDM.
- Delete the persisted entity if the entity no longer exists in virtual MDM.
- Usage information
- Note: With the current release, persistEntity is supported only for Person and Organization parties. Additionally, only a single composite view can be defined and used for the persistence of an entity.
Both the entity type and entity ID of the virtual entity are required in the transaction request. When using the default Party model in virtual MDM, the values for EntityType are as follows:
- mdmper for a person entity
- mdmorg for an organization entity
PersistenceMode is an optional input which determines how much information about the virtual entity to persist in physical MDM. There are two modes for persisting an entity:
- Set PersistenceMode to 1 to persist the entity in entity registration mode. With entity registration mode, only cross-reference keys on the virtual MDM entity, such as Entity ID, source system, and source member IDs, are persisted. Entity attributes such as names, addresses, and so on are not persisted.
- Set PersistenceMode to 2 to persist the entity in full persistence mode. This setting persists the configured composite view of the virtual MDM entity, along with the cross-reference keys, in physical MDM.
An entity that has been persisted in entity registration mode can be fully persisted subsequently with PersistenceMode set to 2. However, after an entity is fully persisted, it must continue to be persisted in full persistence mode.
If PersistenceMode is not specified in the request and the entity is a new entity in physical MDM, the transaction persists the entity using the configured default persistence mode. If the entity already exists in physical MDM, the entity is persisted according to the entity link status, which indicates the persistence mode of the existing entity.
Note: When an entity is persisted in entity registration mode, hybrid-enabled inquiry transactions such as getParty, getPartyByAdminSysKey or getPartyByEntityId retrieve party information from virtual MDM and supplemental attributes from physical MDM. The combined results from virtual MDM and physical MDM are returned. Conversely, the same inquiry transactions retrieve both party information and supplemental attributes from physical MDM if the entity is persisted in full persistence mode. - Preconditions
- Hybrid MDM mode must be enabled.
- Default persistence mode must be configured for each entity type.
- Entity must exist in the virtual MDM.
- Mandatory input
- EntityId
- EntityType
- Inquiry levels
- Not applicable
- Filter values
- Not applicable
- Transaction behavior
- The transaction uses the EntityId and EntityType provided in the
request to retrieve the configured composite view of the entity from
virtual MDM. It persists either only cross-reference keys or all attributes
in the configured composite view depending on the setting for PersistenceMode.
If the entity does not exist in physical MDM, it is added. If the entity already exists, the entity is updated. If the entity no longer exists in virtual MDM, the entity is deleted from physical MDM.
The transaction also maintains the entity link status of the persisted entity to reflect the mode in which the entity is persisted.
- 1 indicates that the entity is persisted in entity registration mode.
- 2 indicates that the entity is persisted in full persistence mode.
The table summarizes the transaction behavior based on the PersistenceMode setting, whether or not the entity already exists, and if existing, the entity link status of the persisted entity.
PersistenceMode New or existing entity in physical MDM? Entity link status if existing Result 1 (entity registration) New Not applicable A new entity ID has been provided. Only the entity ID and the cross-reference keys (contact equivalency) associated with the entity are added to physical MDM. 1 (entity registration) Existing 1 (entity registration) If the cross-reference keys associated with the entity ID have changed, they are updated in physical MDM. No other changes occur. If the entity no longer exists in virtual MDM, it is deleted. 1 (entity registration) Existing 2 (full persistence) The entity link status is not compatible with the setting for PersistenceMode. Once the view for an entity is persisted, the entity in physical MDM cannot be reverted to entity registration mode. An error is returned. 2 (full persistence) New Not applicable The new entity is persisted in full persistence mode. Entity link status is set to 2. 2 (full persistence) Existing 1 (entity registration) Existing entity is updated and persisted in full persistence mode. Entity link status is updated from 1 to 2. If the entity no longer exists in virtual MDM, it is deleted. 2 (full persistence) Existing 2 (full persistence) Existing entity is updated in full persistence mode. New attributes are added, existing attributes are updated, and obsolete attributes are deleted. Member cross-reference keys associated with the entity are also updated if members associated with the entity have changed in virtual MDM. If the entity no longer exists in virtual MDM, it is deleted. Not specified New Not applicable The new entity is persisted using the configured default persistence mode. Not specified Existing 1 (entity registration) Entity is updated in entity registration mode. Entity link status remains 1. If the entity no longer exists in virtual MDM, it is deleted. Not specified Existing 2 (full persistence) Entity is updated in full persistence mode. Entity link status remains 2. If the entity no longer exists in virtual MDM, it is deleted. If this transaction is not successful, for example due to data quality errors, it will set Entity Status to 2 (Last entity update from virtual MDM failed) to indicate that the persisted entity does not have the latest view of the entity from virtual MDM. If the persistEntity transaction is subsequently processed successfully, it will set Entity Status to 1 to indicate that the persisted entity is now up-to-date.
The Entity Status is set using the transaction failover rule ID 218. The com.ibm.mdm.hybrid.externalrule.TransactionFailoverRule is the hybrid version of Rule 218.Note: When a fully persisted entity has an entity status of 2, the hybrid-enabled inquiry transactions will retrieve the configured composite view of the entity from virtual MDM and merge them with applicable supplemental attributes in physical MDM to ensure the most current view is returned. - Request message
<TCRMTxType> persistEntity
<TCRMTxObject> PersistEntityRequestBObj
<TCRMObject> PersistEntityRequestBObj
- Response objects
PersistEntityResponseBObj containing TCRMPersonBObj or TCRMOrganizationBObj
Note that if the entity is deleted, the TCRMPersonBObj or TCRMOrganizationBObj are nested inside TCRMDeletedPartyBObj.
Optional business objects:- Special note
- This transaction might invoke one of the following transactions:
- With a user interface that is included with IBM® Stewardship Center, you can view and fix data quality issues that occur when you run the persistEntity service. The interface presents a list of data quality issues with details about each issue, such as an incorrect birth date or a missing field. For issues that require changes to virtual MDM source systems, you can send e-mails to the administrators of the source system with embedded information about the particular issues.