Entities are data structures that can be associated as an instance of a transaction. Any process a user performs after successfully logging in can be termed as a transaction. Oracle Adaptive Access Manager can evaluate the risk associated with a transaction in real-time to prevent fraud and misuse.
This chapter explains how applications can use the Entity API to create, update, and search for entities. It contains these sections:
OAAM provides two Entity APIs that allow applications to manage entities and entity relationships needed to facilitate fraud detection.
The Entity APIs allow applications to perform create and update, replace, and search operations on entities in the database. The Entity APIs can:
Create and update an entity in the OAAM database schema
Replace or merge entity attributes
Search for entities
Entity tasks performed on the client's transaction data in the database require the following information:
The Entity key is the key provided by the Administrator when creating the entity definition in OAAM Admin
Entity data is the data entered by the user of the client application
The linked entity relationship name is the name specified by the Administrator when creating an entity definition in OAAM Admin. A linked entity relationship name is required for complex entity instances only.
VCryptObjectResponse contains information about the status of the processing.
Entity Create and Update API Return type: VCryptObjectResponse:
| Result | Description |
|---|---|
| SUCCESS | SUCCESS on successful execution of API (there is no database or connection error) and at least one entity is created.
|
| ERROR | ERROR if no entity is created.
|
Entity Search API Return type: VCryptObjectResponse
| Return Object | Description |
|---|---|
| VCryptObjectResponse | Contains EntityHeader object which is the entity object on SUCCESS or error message on ERROR |
You can use the createOrUpdateEntities API to perform the following tasks:
Create and update entities
Replace and merge attribute values during an entity update
When you create an entity, a unique key is generated using the primary key values from the entity data map. OAAM uses that key to check if the entity already exists in the database. If the entity does not exists, an entity is created, otherwise the entity is updated. The entity is updated based on the data specified in the entity data map.
To erase values for some attributes of an existing entity using the entityId, populate entityDataMap as follows, and set the isReplaceEntity (In createOrUpdateEntity) parameter to true.
API Signature:
public VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> createOrUpdateEntities(EntityData[] entityRequestData,boolean isReplaceEntity, int commitBatchSize, String requestId);
Parameters:
| Parameter | Description |
|---|---|
| entityRequestData | Array of EntityData objects. An EntityData object contains the information required to create one entity. For details on EntityData.java, see the Oracle Fusion Middleware Java API Reference for Oracle Adaptive Access Manager, Release 11g. |
| isReplaceEntity | Flag to determine replacement or merging of attributes on update of entity. Default value: FALSE which denotes merge. |
| commitBatchSize | Determines the number of entities which must be committed together. Default and minimum value is 1 |
| requestId | Value to identify the session. The value is sent by the client. If the client does not set this value then generate a dummy number |
Replacing or Merging Attributes: During an entity update, you can choose to merge or replace attributes. The difference between the two modes is visible only in the case where the user passes empty values for attributes in entity data. In the merge case, the value of such attributes will not change and the old value persists. In the replace case, the empty value will replace the old value and such attributes will be replaced with empty values. Default option is merge.
You can use the searchEntityByKey API to find entities based on its key attributes.
API Signature:
public VCryptObjectResponse<EntityHeader> searchEntityByKey(EntityData entityData);
Parameters:
| Parameter | Description |
|---|---|
| entityData | EntityData object with entityName and entityDataMap containing key(s) and value(s) of primary key attributes of the entity to be searched based on the ID scheme |
This section contains information about mapping attributes for entity resolution in fraud detection.
OAAM uses the entity data map to create an entity. The entity map includes the key value pairs of attribute names and their values specified by the user. For instance, for creating an entity of type Customer the data map can be:
Entity data map:
| Key: first name | Value: Mark |
|---|---|
| Key: last name | Value: Smith |
| Key: email | Value: x@y.com |
| Key: shipping.addr_line1 | Value: #1, Lex Residence |
| Key: shipping.addr_line2 | Value: Redmond Street |
| Key: shipping.zip | Value: 418001 |
| Key: shipping.phone_number | Value: 6035550100 |
A complex entity has other entities linked to it by a relationship name. For instance a Customer can be defined by the attributes listed in the subsequent example. Other entities link to it by a relationship name.
To receive data for creating a complex entity a dot convention is used for the keys in the entity data map. The attribute names of the linked entities in the data map must be preceded by the relationship name and a dot(.).
Example:
An attribute of an entity can be an entity itself. Such an attribute is called a linked entity. For instance, Shipping address is a linked entity of the entity, Customer.
Customer: first name (Simple attribute)
last name (Simple attribute)
phone (Simple attribute)
email (Simple attribute)
shipping address: addr_line1
: addr_line2
: city
: state
: country
: mobile
: zip
billing address : addr_line1
: addr_line2
: city
: state
: country
: mobile
: zip
A simple entity is one which is not linked to any other entity. When you create an entity instance, the entity related data is stored in the database.
The EntityData object takes following parameters:
Entity name: The entity name determines the type of entity to be created. For example, Customer. The definition for this entity type already exists in the database for entity creation.
Entity data map: The entity data map includes the key value pairs of attribute names and their values specified by the user. To create a simple entity that does not have any related entities, populate entityDataMap as follows:
| Key | Value |
|---|---|
Key: attributeName1 |
Value: attributeValue1 |
Key: attributeName2 |
Value: attributeValue2 |
Key: attributeName3 |
Value: attributeValue3 |
For example: create a Customer entity that does not have any related entity
| Context Data | Values |
|---|---|
| Key: first name | Value: Mark |
| Key: last name | Value: Smith |
| Key: email | Value: x@y.com |
| Key: mobile | Value: 6035550100 |
To create a simple entity instance:
Create a map that contains the entity data.
The map key is the entity attribute name (as specified in OAAM Admin), and the map value is the user input value.
In the subsequent example, you can see data for the Customer entity data, and user input is Mark Smith as name. The Customer entity has first name and last name attributes.
Map<String,String> entityDataMap = new HashMap<String,String>();
entityDataMap.put("first name","Mark");
entityDataMap.put("last name","Smith");
Create an EntityData object that encapsulates the entity data map and the entity type. For example, Customer.
EntityData entityData= new EntityData("Customer",entityDataMap);
Since the API only accepts array of EntityData's, create an array and insert the entitydata created into it.
EntityData[] entityRequestData= new EntityData[1]; entityRequestData[0]= entityData;
Finally, call the API tracker. This is a VCryptTracker instance.
response = tracker.createOrUpdateEntities(entityRequestData, true, commitBatchSize,requestId);
Errors occur if you try to create an entity instance in the following ways:
With an entity that does not exist
With null as the entity name
Without providing the required information
With null values as the required information
Using mismatching entity data types
Using entirely different entity data as compared to entity definition
Use the createOrUpdateEntities API to update attributes of an existing entity.
entityId ($id$)
id is the value of the Entity ID as stored in the database. You must pass the values of all the key attributes of the entity. This would uniquely identify the entity instance in the database.
Obtain the entityId ($id$) from the response of createOrUpdateEntity API. For example:
VCryptObjectResponse<EntityHeader>[] responseArray = response.getObject(); VCryptObjectResponse<EntityHeader> entityResponse = responseArray[0]; EntityHeader entityHeader = entityResponse.getObject(); Long entityId= entityHeader.getEntityId();
To update some attributes of an existing entity using the entityId, populate entityDataMap as follows:
entityDataMap:
| Key: $id$ | Value: EntityId |
|---|---|
Key: attributeName1 |
Value: attributeValue1 |
Key: attributeName2 |
Value: attributeValue2 |
For example, update the email Id of a Customer entity with entityId as 101:
| Key: $id$ | Value: 101 |
|---|---|
| Key: email | Value: a@b.com |
There are two ways to update an entity instance:
For example:
Customer (101): firstname -> Mark
lastname -> Smith
mobile -> 0987654321
email -> x@y.com
Suppose the prior example is an entity of type Customer with entity ID 101. Suppose you want to change its email to a@b.com, there are two way to pass entity data.
The first way is shown as:
$id$ -> 101
email -> a@b.com
The second way is shown as:
firstname -> Mark
lastname -> Smith
email -> a@b.com
To erase values for some attributes of an existing entity using the entityId, populate entityDataMap as follows, and set the isReplaceEntity (In createOrUpdateEntity) parameter to true.
entityDataMap:
| Key: $id$ | Value: EntityId |
|---|---|
Key: attributeName1 |
Value: |
Key: attributeName2 |
Value: |
For example, erase the email Id of a Customer entity with entityId as 101:
| Key: $id$ | Value: 101 |
|---|---|
| Key: email |
To create an entity that has related entities with complete data of both top-level entity and related entities, use this format:
entityDataMap:
Key: attributeName1 |
Value: attributeValue1 |
|---|---|
Key: attributeName2 |
Value: attributeValue2 |
Key: attributeName3 |
Value: attributeValue3 |
Key: relationshipName1.attributeName1 |
Value: linkedEnt1AttributeValue1 |
Key: relationshipName1.attributeName2 |
Value: linkedEnt1AttributeValue2 |
Key: relationshipName2.attributeName1 |
Value: linkedEnt2AttributeValue1 |
Shipping is a relationship name which links Customer to another entity of type address. To receive data for creating a complex entity, a dot convention for the keys in the entity data map. The attribute names of the linked entities in the data map must be preceded by the relationship name and a dot(.).
Example: to create a Customer entity with linked address entities with relationshipNames as shipping and billing
| Key: first name | Value: Mark |
|---|---|
| Key: last name | Value: Smith |
| Key: email | Value: x@y.com |
| Key: shipping.addr_line1 | Value: #1, Lex Residence |
| Key: shipping.addr_line2 | Value: Redmond Street |
| Key: billing.addr_line1 | Value: #2, Lex Residence |
To create an entity that has related entities (with multiple instances of single relationships) with complete data of both top-level entity and related entities, use the createOrUpdateEntities() API.
entityDataMap:
Key: attributeName1 |
Value: attributeValue1 |
|---|---|
Key: attributeName2 |
Value: atributeValue2 |
Key: attributeName3 |
Value: attributeValue3 |
Key: relationshipName1[index1].attributeName1 |
Value: linkedEnt1AttributeValue1 |
Key: relationshipName1[index1].attributeName2 |
Value: linkedEnt1AttributeValue2 |
Key: relationshipName1[index2].attributeName1 |
Value: linkedEnt2AttributeValue1 |
Key: relationshipName1[index2].attributeName2 |
Value: linkedEnt2AttributeValue2 |
Key: relationshipName2.attributeName1 |
Value: linkedEnt3AttributeValue1 |
Example: to create a Customer entity with linked address entities with relationshipNames as shipping and billing with two instance of shipping.
| Key: first name | Value: Mark |
|---|---|
| Key: last name | Value: Smith |
| Key: email | Value: x@y.com |
| Key: shipping[0].addr_line1 | Value: #1, Lex Residence |
| Key: shipping[0].addr_line2 | Value: Redmond Street |
| Key: shipping[1].addr_line1 | Value: #3, Lex Residence |
| Key: shipping[1].addr_line2 | Value: Redwood Street |
| Key: billing.addr_line1 | Value: #2, Lex Residence |
To create an entity that has related entities with complete data of top-level entity and entity Ids of one or more related entities
entityDataMap:
Key: attributeName1 |
Value: attributeValue1 |
|---|---|
Key: attributeName2 |
Value: attributeValue2 |
Key: attributeName3 |
Value: attributeValue3 |
Key: relationshipName1[index1].attributeName1 |
Value: linkedEnt1AttributeValue1 |
Key: relationshipName1[index1].attributeName2 |
Value: linkedEnt1AttributeValue2 |
Key: relationshipName1[index2].$id$ |
Value: linkedEnt2EntityId |
Key: relationshipName2.attributeName1 |
Value: linkedEnt3AttributeValue1 |
Example: to create a Customer entity with linked address entities with relationshipNames as shipping and billing with two instance of shipping. One of the shipping address entity already exists with entityId as 102.
| Key: first name | Value: Mark |
|---|---|
| Key: last name | Value: Smith |
| Key: email | Value: x@y.com |
| Key: shipping[0].addr_line1 | Value: #1, Lex Residence |
| Key: shipping[0].addr_line2 | Value: Redmond Street |
| Key: shipping[1].$id$ | Value: 102 |
| Key: billing.addr_line1 | Value: #2, Lex Residence |
Errors occur if you try to create a linked entity instance in the following ways:
Using a non-existent linked entity name
Using an empty linked entity name
Without all the required linked entity data
With null values for the required linked entity data
Using mismatching linked entity data data type
Using entirely different linked entity data as compared to the entity definition
Where the linked entity is of the same type as the parent
If you create a complex entity instance where the linked entity (multilevel) is of the same type as the parent, the entity instance is created with an error status. The error is from the mismatch in the entity definition since such a definition is not allowed.
To update related entities of an entity with entity Ids of related entities
entityDataMap:
Key: attributeName1 |
Value: attributeValue1 |
|---|---|
Key: attributeName2 |
Value: attributeValue2 |
Key: relationshipName1.$id$ |
Value: linkedEnt1EntityId |
Key: relationshipName1.attributeName1 |
Value: linkedEnt1AttributeValue1 |
Note: One can also pass the parent entityId instead of attributes for the parent entity.
Example: to update the city to Chicago in billing address for Customer Mark Smith. The billing address already exists with entityId as 103
| Key: first name | Value: Mark |
|---|---|
| Key: last name | Value: Smith |
| Key: billing.$id$ | Value: 103 |
| Key: billing.city | Value: Chicago |
You can Unlink one or more related entities from the parent entity.
Customer: first name:: abc
: last name:: xyz
: mobile:: 6035550100
: email:: p@q.com
: shipping address:: (entity with id = 102)
: shipping address:: (entity with id = 105)
: billing address:: (entity with id = 103)
unLinkEntities: List of mapId's of relationships to be deleted. mapId's is of type Long. The mapIds can be fetched from list of VTEntityOneMap objects returned as linkedEntities in Entity object.
unlinkEntities:
| Value (In form of a List) |
|---|
| 102,105 |
| 103 |
If unlinkEntities is specified as null while updating entity instances, then no changes are made to the existing entity relationships. All the entity relationships previously associated with the parent entity involved in update operation persist. New relationships can be however added (using entity data map) during the update.
An error occurs if you try to unlink entities in the following ways:
By passing in required attributes that do not correspond to existing the entity instance.
By passing in entity Id values that are null/empty
By passing in a parent entity Id, thereby removing the required attributes
By passing in entity Id values that do not exist
By passing in duplicate entity Id
public void testDeleteRelationships() throws Exception{
boolean isReplaceEntity = false;
int commitBatchSize=1;
String timeStamp = Long.toString(System.currentTimeMillis());
EntityData[] entityRequestData= new EntityData[1];
Map<String,String> entityDataMap = new HashMap<String,String>();
entityDataMap.put("first name","Mark"+timeStamp);
entityDataMap.put("last name","Smith"+timeStamp);
entityDataMap.put("email","x@y.com");
entityDataMap.put("mobile","6035550100");
EntityData entityData= new EntityData("customer",entityDataMap);
entityRequestData[0]= entityData;
String requestId= null;
VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> response =
vCryptTracker.createOrUpdateEntities(entityRequestData, isReplaceEntity,
commitBatchSize,requestId);
assertTrue(response.isSuccess());
VCryptObjectResponse<EntityHeader>[] responseArray= response.getObject();
VCryptObjectResponse<EntityHeader> entityResponse= responseArray[0];
assertTrue(entityResponse.isSuccess());
EntityHeader entity = entityResponse.getObject();
Long customerEntityId= entity.getEntityId();
// creating an address
Map<String,String> entityDataMapAddress1 = new HashMap<String,String>();
entityDataMapAddress1.put("addr_line1","testHouse1b"+timeStamp);
entityDataMapAddress1.put("addr_line2","testStreet1b");
entityDataMapAddress1.put("addr_line3","testlane1b");
entityDataMapAddress1.put("city","city1");
entityDataMapAddress1.put("state","state1");
entityDataMapAddress1.put("country","country1");
entityDataMapAddress1.put("zip","333031");
entityDataMapAddress1.put("phone","6035550100");
EntityData entityDataAddress1= new
EntityData("address",entityDataMapAddress1);
entityRequestData[0]= entityDataAddress1;
VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> responseAddress1 =
vCryptTracker.createOrUpdateEntities(entityRequestData, isReplaceEntity,
commitBatchSize,requestId);
assertTrue(responseAddress1.isSuccess());
VCryptObjectResponse<EntityHeader>[] responseArrayAddress1=
responseAddress1.getObject();
VCryptObjectResponse<EntityHeader> entityResponseAddress1=
responseArrayAddress1[0];
assertTrue(entityResponseAddress1.isSuccess());
EntityHeader entityAddress1 = entityResponseAddress1.getObject();
Long address1EntityId= entityAddress1.getEntityId();
// creating another address
Map<String,String> entityDataMapAddress2 = new HashMap<String,String>();
entityDataMapAddress2.put("addr_line1","testHouse2"+timeStamp);
entityDataMapAddress2.put("addr_line2","testStreet2");
entityDataMapAddress2.put("addr_line3","testlane2");
entityDataMapAddress2.put("city","city2");
entityDataMapAddress2.put("state","state2");
entityDataMapAddress2.put("country","country2");
entityDataMapAddress2.put("zip","333031");
entityDataMapAddress2.put("phone","6035550100");
EntityData entityDataAddress2= new
EntityData("address",entityDataMapAddress2);
entityRequestData[0]= entityDataAddress2;
VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> responseAddress2 =
vCryptTracker.createOrUpdateEntities(entityRequestData, isReplaceEntity,
commitBatchSize,requestId);
assertTrue(responseAddress2.isSuccess());
VCryptObjectResponse<EntityHeader>[] responseArrayAddress2=
responseAddress2.getObject();
VCryptObjectResponse<EntityHeader> entityResponseAddress2=
responseArrayAddress2[0];
assertTrue(entityResponseAddress2.isSuccess());
EntityHeader entityAddress2 = entityResponseAddress2.getObject();
Long address2EntityId= entityAddress2.getEntityId();
// creating relationships between the customer and addresses
Map<String,String> entityDataMapRelation = new HashMap<String,String>();
entityDataMapRelation.put("$id$",customerEntityId.toString());
entityDataMapRelation.put("shipping.$id$",address1EntityId.toString());
entityDataMapRelation.put("billing[0].$id$",address1EntityId.toString());
entityDataMapRelation.put("billing[1].$id$",address2EntityId.toString());
EntityData entityDataRelation= new
EntityData("customer",entityDataMapRelation);
entityRequestData[0]= entityDataRelation;
VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> responseRelation =
vCryptTracker.createOrUpdateEntities(entityRequestData, isReplaceEntity,
commitBatchSize,requestId);
assertTrue(responseRelation.isSuccess());
VCryptObjectResponse<EntityHeader>[] responseArrayRelation=
responseRelation.getObject();
VCryptObjectResponse<EntityHeader> entityResponseRelation=
responseArrayRelation[0];
assertTrue(entityResponseRelation.isSuccess());
EntityHeader entityRelation = entityResponseRelation.getObject();
Long relationEntityId= entityRelation.getEntityId();
assertEquals(customerEntityId,relationEntityId);
Map<String,List<Long>> linkedEntities = entityRelation.getLinkedEntities();
VCryptDataAccessMgr dataAccessMgr = null;
VCryptTrackerDataAccess mTrackerDataAccess = null;
try {
dataAccessMgr = new VCryptDataAccessMgr();
mTrackerDataAccess = dataAccessMgr.getVCryptTrackerDataAccess();
}catch(Exception e) {
logger.error("Error while creating TrackerEntityFactory instance", e);
}
List<VTEntityOneMap> relationships =
mTrackerDataAccess.getVTEntityOneMapByEntityId(customerEntityId,new
Integer(UserDefEnum.getElement(IBharosaConstants.OBJECT_TYPE_ENUM,
"VTEntityDef").getValue()));
assertEquals(relationships.size(),3);
// deleting all the relationships for the customer Entity
Map<String,List<Long>> unlinkEntities = linkedEntities;
Map<String,String> entityDataMapUnlink = new HashMap<String,String>();
entityDataMapUnlink.put("$id$",customerEntityId.toString());
EntityData entityDataUnlink= new
EntityData("customer",entityDataMapUnlink,linkedEntities);
entityRequestData[0]= entityDataUnlink;
VCryptObjectResponse<VCryptObjectResponse<EntityHeader>[]> responseDelRel =
vCryptTracker.createOrUpdateEntities(entityRequestData, isReplaceEntity,
commitBatchSize,requestId);
assertTrue(responseDelRel.isSuccess());
List<VTEntityOneMap> relationships1=
mTrackerDataAccess.getVTEntityOneMapByEntityId(customerEntityId,new
Integer(UserDefEnum.getElement(IBharosaConstants.OBJECT_TYPE_ENUM,
"VTEntityDef").getValue()));
assertEquals(relationships1.size(),0);
}
Use the Search API to perform an entity search based on the Entity Id or values of key entity attributes. The parameters required are the entity name and the entity data map. The entity name corresponds to the entity type and the entity data map contains the entity Id or key value pairs for attributes names and values for the entity to be searched. In case of entity Id, the entity data map is specified as follows:
entityDataMap:
| Key | Value |
|---|---|
| $id$ | 107 |
In this example, 107 is the entity Id of the entity to be searched.
Create a map that contains the entity data of the entity to be searched.
The map key is the entity attribute name (as specified in OAAM Admin), and the map value is the user input value.
In the subsequent example, you can see data for the Customer entity data, and user input is Mark Smith as name. The Customer entity has first name and last name attributes.
Map<String,String> entityDataMap = new HashMap<String,String>();
entityDataMap.put("first name","Mark");
entityDataMap.put("last name","Smith");
Create an EntityData object that encapsulates the entity data map and the entity type. For example, Customer.
EntityData entityData= new EntityData("Customer",entityDataMap);
Finally, call the API tracker. This is a VCryptTracker instance.
response =tracker.searchEntityByKey(entityData);
While creating a transaction instance, the relationship information about the entities involved in the transaction are persisted in the database.
VT_USER_ENTITY1_MAP stores information about entity relationships. The subsequent table describes the usage of different attributes of VT_USER_ENTITY1_MAP.
| Attribute | Description |
|---|---|
| MAP_ID | Primary key for the table, uniquely identifying an entity relationship instance. |
| ENTITY_ID | Entity ID of the parent entity. |
| MAP_OBJ_ID | Entity ID of the linked entity. |
| DEF_MAP_ID | Unique identifier for entity relationship definition. |
VT_ENT_DEFS_MAP stores the entity relationship definitions. The subsequent table describes the usage of different attributes of VT_ENT_DEFS_MAP.
| Attribute | Description |
|---|---|
| MAP_ID. | Primary key for the table, uniquely identifying an entity relationship definition. |
| ENTITY_DEF_ID_1 | Entity definition ID for parent entity type. |
| ENTITY_DEF_ID_2 | Entity definition ID for linked entity type. |
OAAM does not delete expired records. It stores expired unused records in VT_ENTITY_ONE and VT_ENTITY_ONE_PROFILE tables.
An entity instance which is stored in the VT_ENTITY_ONE table has an attribute known as expiry time. The expiry time is set to a configurable value while creating an entity instance object. The expiry time changes when an update operation occurs on that entity instance. Whenever the current time exceeds the expiry time, the corresponding record expires.
The values of attributes for an entity instance are kept in the table, VT_ENTITY_ONE_PROFILE. The profile data also follows the same expiry logic as the entity object in VT_ENTITY_ONE table. However, during an update operation, there is a new record added in the table with new profile data and the previous record expires.
When an entity is added as an instance to the transaction OAAM stores that association in VT_TRX_ENT_DEFS_MAP. The entity can be extended for entities that are linked to other entities. For example if an entity Customer has an association/link to another entity Address with relation type as Home Address, when the Customer entity is added to a transaction definition then OAAM can store two records into VT_TRX_ENT_MAP, one for the entity Customer and the other for the Address that is referenced by Customer. The inner/nested/child entity Customer.HomeAddress has a reference with the transaction definition with relation_type as Customer$HomeAddress that is derived by concatenating the relation_type between Transaction and Customer entity, dollar($) symbol and the relation_type between Customer entity and Address entity.
While creating a transaction instance, the relationship information about the entities involved in the transaction will be persisted in the database.
When transaction data is created, the following updates occurs:
The top-level/directly linked entities are determined.
For each top-level/directly linked entities, the following steps are performed:
Determine the nested/chained entities that are associated to this entity by querying the tables VT_ENT_DEFS_MAP (definition associations) and VT_USER_ENTITY1_MAP (data associations)
For each nested/chained entity:
Look up the transaction association map in VT_TRX_ENT_MAP.
Get the mapping information using the Transaction Definition Id and Entity Definition Id from VT_TRX_ENT_MAP. Note: This process is similar to an entity instance that is directly associated to the transaction.
Use the mapping information to create/lookup entity data (VT_ENTITY_ONE, VT_ENTITY_ONE_PROFILE).
Create a record in VT_ENT_TRX_MAP with the entity Id (from VT_ENTITY_ONE) and transaction Id from the current transaction.
Common scenarios are as follows:
Entities: provider (physician, nurse, and so on), patient and address.
An administrator is investigating a fraud scenario and would like to find out if a provider and patient live or work at the same address. This requires building the following relationships: patient-address, provider-address; and corresponding rules.
The business rule generates when a patient and physician are working or residing at the same location. The rule returns true and generates an alert if patient.worklocation = Physician.worklocation or patient.residence = Physician.residence.
In a medical record access transaction there are only two entities directly involved. That is Provider ID and Patient ID. No other data is given when calling the API to create the transaction. Both Providers and Patients have various entities related to them. One example is home address, an instance of the address entity. Session details shows a medical record access transaction containing a Provider ID and a Patient ID.