Relations API
Relationships, as well as entities, are the building blocks of the relationship
graph. These are links between objects (entity-entity or relationship-entity). You can
define different types of relationships and their taxonomies in the Business Model (for
example, Spousal (family), Employment (professional), or Friend (affiliate) relationship
types). As for entities, we support the "catchAll
" bucket.
- Based on usability, relationship types are of the following types:
- Implicit- The relationships that enable you to build entity reference attributes.
- Explicit- The relationships which you want to track in a graph.
- Based on direction relationships can be directed, undirected, bidirectional, or, self-pointing (an entity to itself).
Relationships can have attributes and tags assigned to them. For example, there is an Employment relationship between an Individual and an Organization. This relationship can have a Title attribute.
Property | Description | Type |
---|---|---|
URI
|
Path that is used to reach a relation object. Format:
relations/{relation_id} Example:
relations/r1
|
String, URI |
type
|
Relationship type. Example:
configuration/relationTypes/Employment
|
String, Relation Types URI |
startObject
|
Entity declared as the start object of the relationship. Contains
properties:
{ "URI":"relations/r1/startObject",
"objectURI":"entities/e1",
"type":"configuration/entityTypes/Individual", "label":"John Smith",
"directionalLabel":"employee"}
|
JSON Object |
endObject
|
End object of a relationship. Contains properties:
{
"URI":"relations/r1/endObject", "objectURI":"entities/e2",
"type":"configuration/entityTypes/Organization", "label":"Super
Company", "directionalLabel":"employer"
}
|
JSON Object |
attributes
|
Attributes that relationship object has-this includes simple, nested
attributes. Each attribute has a reference to its configuration type.
Attributes are grouped by attribute configuration. Example: {
"URI": "relations/r1/attributes", "Title":[ { "URI":
"relations/r1/attributes/Title/1", "type":
"configuration/relationTypes/Employment/attributes/Title",
"value":"CEO" } ]}
|
Array of Attributes |
crosswalks
|
These are crosswalks to source systems and data in these source systems that are associated with an object. | |
createdBy
|
User who created the object. | UTC timestamp, ms |
createdTime
|
Timestamp when record was created, in milliseconds. | UTC timestamp, ms |
updatedTime
|
Timestamp when record was most recently updated, in milliseconds. | UTC timestamp, ms |
startDate |
This is an optional property that represents the date from which an
object starts being Active . From that day onwards, a
relation is considered as Active and can start
connecting two objects. |
UTC timestamp, ms (13 digit long value) |
endDate |
This is an optional property that represents the date on which an
object was marked Inactive . This property serves the
same purpose as the soft-delete functionality. This
means that from the endDate , a relation becomes
Inactive and stops connecting two objects. Also,
the reference attributes are no longer visible based on this relation. |
UTC timestamp, ms (13 digit long value) |
- If you are processing messages using message streaming, to identify the latest
event amongst several events for an object, use the
objectVersion
property. TheobjectVersion
property identifies the message with the latest object state. For more information, see CRUD events.You cannot use the timestamp in the
createdTime
andupdatedTime
properties since it is only used to indicate the start of the operation that creates or updates the object record. The timestamp does not indicate the time when the object record is committed to the database. When two or more operations are executed simultaneously, theupdatedTime
property may not reflect the latest object state if one operation started earlier than the other but is not committed to the database immediately. For more information, see Message streaming. - If the
startDate
option is later than theendDate
option, then theEND_DATE_EARLIER_THEN_START(600)
exception is displayed. For more information on overwriting ofendDate
,startDate
, andtags
, see Retrieve or modify the entity startDate and endDate.
Relationship Object Example
{
"URI":"relations/r1",
"type":"configuration/relationTypes/Employment",
"createdTime":1351899105569,
"createdBy":"admin",
"updatedTime":1353933493738,
"updatedBy":"fadler",
"startObject":{
"URI":"relations/r1/startObject",
"objectURI":"entities/e1",
"type":"configuration/entityTypes/Individual",
"label":"John Smith",
"directionalLabel":"employee"
},
"endObject":{
"URI":"relations/r1/endObject",
"objectURI":"entities/e2",
"type":"configuration/entityTypes/Organization",
"label":"Super Company",
"directionalLabel":"employer"
},
"attributes":{
"URI":"relations/r1/attributes",
"Title":[
{
"URI":"relations/r1/attributes/Title/1",
"type":"configuration/relationTypes/Employment/attributes/Title",
"value":"CEO"
}
]
},
"crosswalks":[
{
"URI":"relations/r1/crosswalks/1",
"type":"configuration/sources/MDM",
"value":"Employemnt.1000",
"attributes":[
"relations/r1/attributes/Title/1"
]
}
]
}
Self Pointing Relationships
Normally you use a crosswalk to define a relationship between one entity and another. Occasionally, you need to define a relationship between a given entity and itself. This example is an entity that needs to ship to itself. The API supports requests such as:
{
"type":"configuration/relationTypes/HasShipTo",
"crosswalks":[
{
"type":"configuration/sources/HCS",
"value":"HasShipTo_HCS_00370257_00370257"
}
],
"startObject":{
"crosswalks":[
{
"type":"configuration/sources/HCS",
"value":"00370257"
}
]
},
"endObject":{
"crosswalks":[
{
"type":"configuration/sources/HCS",
"value":"00370257"
}
]
}
}
This relationType
defines a crosswalk that has the same
startObject
as the endObject
. This example is
based on an entity that needs to ship a product to itself. In this way you can
define self-pointing objects.