IM InfoSphere Identity Insight, Version 8.0


getDirectEntityRelationships() SOAP API method

Finds all direct (one-degree) relationships for an entity regardless of path strength. The entity is identified by its entity ID or by the external ID of one of its constituent identity records. The UMF API equivalent of the getDirectEntityRelationships method are the SOA_DIRECT_ENTITY_RELATIONSHIPS_REQUEST input document and the SOA_DIRECT_ENTITY_RELATIONSHIPS_RESPONSE output document.

Syntax

getDirectEntityRelationships
(
 entityIdentifier,
 depth
);

Description

Parameters
entityIdentifier
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 indicates this by throwing an exception.
toEntityIdentifier
Abstract Parameter Type: EntityIdentifier
Default Concrete Types: EntityID, ExternalID
Nullable: No
This parameter identifies the entity (directly or indirectly) from which the relationship paths should originate. 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 request 1
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.”);
}

Example request 2

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
Note: For Multi-degree relationships (Degree > 1) the degreesOfSeparation value that is returned denotes the degree of separation of that Entity expressed as an Absolute distance from the original 'entityIdentifier' in the relationship-path, not a Relative-distance from the preceding Entity in the relationship path.
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