5 Creating, Updating, and Searching for Entities Using the Entity API

This chapter explains how applications can use the Entity API to create, update, and search for entities. It contains these sections:

About the Entity APIs
Creating Entities and Mapping Attributes
Data Storage
Scenario

5.1 About the Entity APIs

OAAM provides two Entity APIs that allow applications to manage entities and entity relationships needed to facilitate fraud detection.

5.1.1 Entity Tasks

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.

5.1.2 Processing Status

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. `response.getObject()` returns Array object containing `VCryptObjectResponse` for individual entities. Each response object contains an `EntityHeader` object on `SUCCESS`. Query for `response.isSuccess()`. (`true` for `SUCCESS` and `false` for `ERROR`).
ERROR	`ERROR` if no entity is created. `response.getObject()` returns object containing `VCryptObjectResponse`. Each response object contains error message on `ERROR`.

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`

5.1.3 Create or Update Entities

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

5.1.4 Replace or Merge Attributes

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.

5.1.5 Search Entity By Key

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

5.2 Creating Entities and Mapping Attributes

This section contains information about mapping attributes for entity resolution in fraud detection.

5.2.1 Entity Data Map

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: Henry
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: 9876543210

5.2.2 Complex Entity

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

5.2.3 Creating a Simple Entity

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: Henry
Key: email	Value: x@y.com
Key: mobile	Value: 9876543210

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 Henry 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","Henry");
```
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

5.2.4 Updating Attributes of an Existing Entity

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 -> Henry

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 -> Henry

email -> a@b.com

5.2.5 Erasing the Value of Attributes of an Existing Entity

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

5.2.6 Creating an Entity that has Related Entities with Complete Data of Both Top-Level Entity and Related Entities

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: Henry
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

5.2.7 Creating an Entity that has Related Entities (with Multiple Instances of a Single Entity) with Complete Data of Both Top-Level Entity and Related Entities

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: <attributeValue2>
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: Henry
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

5.2.8 Creating an Entity that has Related Entities with Complete Data of Top-level Entity and Entity Ids of One or More Related Entities

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: Henry
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.

5.2.9 Updating Related Entities of an Entity with Entity Ids of Related Entities

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 Henry. The billing address already exists with entityId as 103

Key: first name	Value: Mark
Key: last name	Value: Henry
Key: billing.$id$	Value: 103
Key: billing.city	Value: Chicago

5.2.10 Unlinking Linked Entities.

You can unlink one or more related entities from the parent entity.

Customer: first name:: abc

: last name:: xyz

: mobile:: 9876543210

: 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

Code Example

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","Henry"+timeStamp);
         entityDataMap.put("email","x@y.com");
         entityDataMap.put("mobile","9876543210");    
    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","9876543210");  
    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","9876543210");  
    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);
  }

5.2.11 Searching for an Entity on the Basis of Entity ID or Key Data

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.

API Call

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 Henry 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","Henry");
```
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); 
```

5.3 Data Storage

While creating a transaction instance, the relationship information about the entities involved in the transaction are persisted in the database.

5.3.1 Data Model

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.

5.3.2 Metadata

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.

5.3.3 Expiry of Records

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.

5.3.4 Transaction-Entity Mapping

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.

5.3.5 Storing Entity Relationships in Transaction Create/Update

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:
1. 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)
2. 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.

5.4 Scenario

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.