IM InfoSphere Identity Insight, Version 8.0


getRelationshipBetweenEntities() SOAP API method

Given two entities individually identified by entity ID or by the external ID and data source code of a composite identity, this service requests and returns the details of the best relationship between the two entities, if they relate at all. If the two entities are the same then the return value indicates this with the number of degrees of the relationship being equal to zero. The UMF API equivalent of the getRelationshipBetweenEntities method are the SOA_RELATIONSHIP_BETWEEN_ENTITIES_REQUEST input document and the SOA_RELATIONSHIP_BETWEEN_ENTITIES_RESPONSE output document.

Syntax

getRelationshipBetweenEntities
(
 fromEntityIdentifier,
 toEntityIdentifier,
 depth
);

Description

Parameters
fromEntityIdentifier
Abstract Parameter Type: EntityIdentifier
Default Concrete Types: EntityID, ExternalID
Nullable: No
This parameter identifies the entity (directly or indirectly) from which the relationship path (if any) should originate. If the entity identifier does not identify a known entity, the service returns the UMF equivalent of nothing.
toEntityIdentifier
Abstract Parameter Type: EntityIdentifier
Default Concrete Types: EntityID, ExternalID
Nullable: No
This parameter identifies the entity (directly or indirectly) at which the relationship path (if any) should terminate. If the entity identifier does not identify a known entity, the service indicates this by throwing an exception.
depth
Abstract Parameter Type: DepthSpecifier
Default Concrete Types: DepthSetting
Nullable: Yes
This parameter indicates the level of detail for the response. If not specified, then DepthSetting.FULL is assumed.
Valid Values: DepthSetting.FULL
RelationshipPath
Nullable: Yes
If the return value is null, then both subject entities were identified, but no relationship was found the from specified entity and the to specified entity. If a relationship is found, a RelationshipPath object is returned that describes the best-path relationship between the two entities to various degrees of detail depending on the specified depth parameter.
Example Requests
EntityID entityID1 = new EntityID();
entityID1.setEntityID(123456789);

EntityID entityID2 = new EntityID();
entityID2.setEntityID(111222333);

RelationshipPath relPath 
    = provider.getRelationshipBetweenEntities(entityID1,
                                              entityID2,
                                              DepthSetting.STANDARD,
                                              null);

if (relPath == null) {
  throw new Exception(“No relationship exists.”);
}

float strength = relPath.getPathStrength();
int degrees = relPath.getDegreesOfSeparation();
 
System.out.println(“Related at “ + degrees + “ degrees with “ + strength
                   + “ strength.”);

Relationship[] relationships = relPath.getRelationships();
if (relationships != null) {
  for (int index = 0; index < relationship.length; index++) {
    Relationship rel = relationships[index];
    System.out.println(“FROM ” + rel.getFromEntityID() 
                       + ” – TO ” + rel.getToEntityID());
  }
}



ExternalID extID1 = new ExternalID();
extID1.setExternalID(”1223334444”);
extID1.setDataSourceCode(”EMPLOYEE_DB”);

ExternalID extID2 = new ExternalID();
extID2.setExternalID(”5667778888”);
extID2.setDataSourceCode(”EMPLOYEE_DB”);

RelationshipPath relPath 
    = provider.getRelationshipBetweenEntities(extID1,
                                              extID2,
                                              DepthSetting.STANDARD,
                                              null);

if (relPath == null) {
  throw new Exception(“No relationship exists.”);
}

float strength = relPath.getPathStrength();
int degrees = relPath.getDegreesOfSeparation();

System.out.println(“Entity 1: “ + relPath.getFromEntityID());

System.out.println(“Entity 2: “ + relPath.getToEntityID());
 
System.out.println(“Related at “ + degrees + “ degrees with “ + strength
                   + “ strength.”);

Relationship[] relationships = relPath.getRelationships();
if (relationships != null) {
  for (int index = 0; index < relationship.length; index++) {
    Relationship rel = relationships[index];
    System.out.println(“FROM ” + rel.getFromEntityID() 
                       + ” – TO ” + rel.getToEntityID());
  }
}

Description

Returns
relationshipPath
Nullable: Yes
If the return value is null, then both subject entities were identified, but no relationship was found the from specified entity and the to specified entity. If a relationship is found, a RelationshipPath object is returned that describes the best-path relationship between the two entities to various degrees of detail depending on the specified depth parameter.
minOccurs="0"
type="xsd_5:RelationshipPath"
RelationshipPath
fromEntityID
type="xsd:long"
toEntityID
type="xsd:long"
pathStrength
minOccurs="0"
type="xsd:float
degreesOfSeparation
minOccurs="0"
type="xsd:int
relationships
maxOccurs="unbounded"
minOccurs="0"
type=" xsd_1:Relationship
Relationship
fromEntityID
type="xsd:long"
toEntityID
type="xsd:long"
resolutionDetail
type=" xsd_2:ResolutionDetail
ResolutionDetail
relationshipConfidence
minOccurs="0"
type="xsd:int
likenessConfidence
minOccurs="0"
type="xsd:int
resolutionID
minOccurs="0"
type="xsd:long"
resolutionRuleID
minOccurs="0"
type="xsd:long"
resolutionRuleDescription
minOccurs="0"
type="xsd:string"
contributors
maxOccurs="unbounded"
minOccurs="0"
type=" xsd_1:ResolutionContributor

Description

Exceptions
[Generic Fault]
Cause: If the specified entities are not recognized or if an internal failure occurred.

Description

GetRelationshipBetweenEntities Depth Settings
Table 1. Shallow
Field (SOAP & JSON) UMF tags Availability
fromEntityID
<REL_PATH> 	
   <FROM_ENTITY_ID>
Provided
toEntityID
<REL_PATH>
		<TO_ENTITY_ID>
Provided
pathStrength
<REL_PATH>
	<PATH_STRENGTH>
Provided
degreesOfSeparation
<REL_PATH>
		<SEP_DEGREES>
Provided
relationships
<REL_PATH>
	<RELATIONSHIP>
Not provided
Table 2. Standard (same as Shallow with the following differences)
Field (SOAP & JSON) UMF tags Availability
relationships
<REL_PATH>
		<RELATIONSHIP>
Provided

relationships[n]

   fromEntityID

<REL_PATH>
	<RELATIONSHIP>
		<FROM_ENTITY_ID>
Provided

relationshipPath.

relationships[n].

toEntityID

<REL_PATH>
	<RELATIONSHIP>
		<TO_ENTITY_ID>
Provided

relationships[n].

resolutionDetail

<REL_PATH>
		<SEP_DEGREES><REL_PATH>
	<RELATIONSHIP>
		<ER>
Not Provided
Table 3. Deep (same as Standard with the following differences)
Field (SOAP & JSON) UMF tags Availability

relationships[n].

resolutionDetaily

<REL_PATH>
	<RELATIONSHIP>
		<ER>
Provided

relationships[n].

resolutionDetail.

relationshipConfidence

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<REL_CONF>
Provided

relationships[n].

resolutionDetail.

likenessConfidence

<REL_PATH>
	<RELATIONSHIP>
		<ER>
				<LIKE_CONF>
Provided

relationships[n].

resolutionDetail.

resolutionID

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<ER_ID>
Provided

relationships[n].

resolutionDetail.

resolutionRuleID

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<ER_RULE_ID>
Provided

relationships[n].

resolutionDetail.

resolutionRuleDescription

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<ER_RULE_DESC>
Provided

relationships[n].

resolutionDetail.

contributors

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<DISCLOSED_REL/>
			<NAME/>
			<ADDRESS/>
			<NUMBER/>
			<ATTRIBUTE/>
			<EMAIL/>
Not provided
Table 4. FULL (same as DEEP with the following exceptions)
Field (SOAP & JSON) UMF tags Availability

relationships[n].

resolutionDetail.

contributors

<REL_PATH>
	<RELATIONSHIP>
		<ER>
			<DISCLOSED_REL/>
			<NAME/>
			<ADDRESS/>
			<NUMBER/>
			<ATTRIBUTE/>
			<EMAIL/>
Fully provided (including children)




Feedback



Last updated: 2011