Accelerate the Value of Data

Crosswalks

The value of the entity attribute is associated with the data source via crosswalks.

Data comes to Reltio from different sources. To represent these various data sources in Reltio, you declare each source via the Reltio Configuration API. Once declared, an application can associate data being loaded through the API with a data source. Each attribute value in an entity or relationship is associated with a data source, which is done via a crosswalk. A crosswalk can be declared on the fly to be a data provider or a non-data provider. If the former, then it is associated with the attributes written during the call. If the latter, then it is merely associated with the overall entity (or relationship). In this case it is used to merely associate the object in Reltio with an object in another system.

It is important to preserve the uniqueness of a crosswalk. For example, if two records in Reltio contain the same crosswalk, it should be an indication that they both are linked to a single record in another system and, therefore, are logically the same entity, thus they should be merged. In fact, one way to merge records in Reltio automatically is to intentionally allow the records to obtain identical crosswalks. This is a strategy that is often used during a load to circumvent the alternative approach of using match/merge rules after the load has been completed. Since uniqueness is important, Reltio forms the complete description of a crosswalk from several elements: source-type (type), crosswalkValue (value), and sourceTable (optional).

Consider an example. Assume there is a data source (called PP for short) which provides records including those of Doctor House and Nurse Evans. In the PP source system, they reside in separate tables, t_nurses and t_doctors, and each table maintains its own ID number sequence. Thus, there is no guaranteed uniqueness across these two tables. Let us further assume for argument's sake that both these records happen to have been assigned identical ID numbers, row_id= 459. In Reltio, the target entity for both records might be the HCP entity (i.e. Health Care Provider). Without a way to add uniqueness to the two IDs of 459, these records would auto-merge in Reltio during the load because their crosswalks would be equal. To resolve this issue, we use the element of a Reltio sourceTable, as shown in the sample JSON below.

[
         {
              "url":"http://www.princetonhcs.org/staff/2e7143066",
              "type":"configuration/sources/PP",
              "value":"459",

"sourceTable":"t_nurses"
   },
         {
              "url":"http://www.princetonhcs.org/staff/266",
              "type":"configuration/sources/PP",
              "value":"459",

"sourceTable":"t_doctors"
   }
]
Table 1. Object Structure
Property Name Description Type

URI

Path that is used to reach a crosswalk. Format: {object URI}/crosswalks/{crosswalks_id}

String, URI

type

Source type of a crosswalk. This is a reference to source configuration by its URI. A crosswalk can have just one source.

String, Sources URI

value

ID of this object in source system defined in the type property. This property is required ONLY for entities.

Example: an entity comes from Facebook and its identifier in Facebook is 'id3562'. For this entity, we will have a crosswalk with type 'configuration/sources/Facebook', value 'id3562' and url 'https://www.facebook.com/id3562'.

String

url

URL of this object in the source system defined in the type property.

 

attributeURIs

Array of URIs to attributes that have data for this crosswalk.

String, Attributes URI

reltioLoadDate

Date when this crosswalk was updated using Reltio API.

UTC Timestamp or date in format supported by Reltio.  

Example: "12/10/2012" or 12938293293 or "2012-12-10T00:00:00.000+04:00"

createDate

Optional property, indicates the date when the crosswalk was created.

See reltioLoadDate.

updateDate

Optional property, indicates the date when the crosswalk was updated the last time in the original source; not in Reltio.

See reltioLoadDate.

deleteDate

Optional property, indicates the date when the crosswalk was removed.

See reltioLoadDate.

sourcePublishDate

Optional property, indicates the date when the crosswalk was published by a partner.

  • sourcePublishDate can be set for a source or defined on a crosswalk level.
  • sourcePublishDate returned for a crosswalk through APIs is the maximum of the sourcePublishDate values of the source and the crosswalk.
See reltioLoadDate.

sourceTable

Optional property. Reference to some external table in external data source where the data came from.

String

externalInfo

Optional property. This object describes information from external systems.

 

Note: When the object is created in the Reltio system-even if no crosswalks were specified - it will get its crosswalk 'Reltio' (value = object URI).
Table 2. Existing External System
Object Name Property Description

dtssInfo

tenantId

Data Tenant

matchReasons

List of Match Rules which caused the merge.

operationId

Identifier of the operation.

updatedBy

User of the operation.

updatedTime

Date/time of the operation.

Supported Operations

Add Crosswalk

This operation adds one or more crosswalks to an object.

Request

POST /{object URI}/crosswalks
Table 3. Parameters
Parameters Name Required Details

Headers

Authorization

Yes

Information about authentication access token in format "Bearer <accessToken>" (see details in Authentication API).

Content-Type Yes

Should be "Content-Type: application/json".

Query

returnObjects

No

Specifies if response should contain created objects.

Note: Default value is true.
maxObjectsToUpdate No
Note: The maxObjectsToUpdate parameter will be deprecated. Therefore, we recommend you do not use this parameter and instead, use the Immutable Reference Attributes feature. For more information, see deprecateservice.dita.
Specifies the maximum number of events generated by the Add crosswalk request for any related objects.

Body

--

Yes

JSON array with crosswalks to be added.

Response

JSON Array representing the results of the Add operation. Each result (JSON Object) contains several fields:

  • index- index of object in the list of the object crosswalks that were added
  • object - JSON object of object crosswalk that was created
  • successful - result of operation; possible values are "true" or "false

Request

POST /entities/1/crosswalks
Headers:Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512,

Content-Type:application/json
Body[
   {
      "url":"www.xyz.com",
      "type":"configuration/sources/XYZ",
      "value":"XYZ.10"
   }
]
 

Response

POST /entities/1/crosswalks
Headers:
Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512,

Content-Type:application/json
Body[
   {
      "index":0,
      "object":{
         "URI":"entities/1/crosswalks/Fmb",
         "type":"configuration/sources/XYZ",
         "value":"XYZ.10",
         "url":"www.reltio.com",
         "attributes":[

         ]
      },
      "successful":true
   }
]

Edit/Add/Delete Date in Crosswalk

This operation adds a new crosswalk date or edits or deletes an existing crosswalk date depending on the attribute value in the request query.

Request

PUT {TenantURL}/entities/{{entityId}}/crosswalks/{{crosswalkId}}/{{attribute}}
Authorization: Bearer 18c13d18-e704-4290-a470-8108479cd464
Content-Type: application/json
 
{ "value" : "2013-05-16T06:12:51.000+04:00" }

Possible values of {attribute}: deleteDate, updateDate, createDate.

Response

202Accepted[
         {
              "index":0,
              "object":{
                     "URI":"entities/005ZBhp/crosswalks/49",
                     "type":"configuration/sources/Veeva",
                     "value":"123",
                     "createDate":"2013-05-16T06:12:51.000+04:00",
                     "deleteDate":"2013-05-16T06:12:51.000+04:00",
                     "attributes":[

         ]
      },
              "successful":true
   }
]

Delete Crosswalk

Deletes a crosswalk from an object.

Request

DELETE /{crosswalk URI}
Table 4. Parameters
Parameters Name Required Details

Headers

Authorization

Yes

Information about authentication access token in format "Bearer <accessToken>" (see details in Authentication API).

Response

JSON Object representing result of a delete operation. Result contains: status- result of operation; possible values are "success" or "failed".

Request

DELETE /entities/1/crosswalks/2
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response

DELETE /entities/1/crosswalks/2
Headers:Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
Body{
       "status":"success"
}

Delete Date From Crosswalk

This operation deletes an existing crosswalk date.

Request

DELETE {TenantURL}/entities/{entityId}/crosswalks/{crosswalkId}{attribute}

Headers:Authorization:Bearer
204938ca-2cf7-44b0-b11a-1b4c59984512,
 

Response

200OK[
         {
              "index":0,
              "object":{
                     "status":"success"
      },
              "successful":true
   }
]

Get Object Crosswalks

Returns all crosswalks for an object.

Request

GET /{object URI}/crosswalks
Table 5. Parameters
Parameters Name Required Details

Headers

Authorization

Yes

Information about authentication access token in format "Bearer <accessToken>" (see details in Authentication API.

Response

An array of crosswalks that are associated with the object.

Request

GET /entities/10/crosswalks
Headers:Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512[
   {
      "URI":"entities/10/crosswalks/1",
      "type":"configuration/sources/Reltio",
      "value":"entities/10",
      "url":"www.reltio.com",
      "attributes":[
         "entities/10/attributes/FirstName/1",
         "entities/10/attributes/FirstName/2",
         "entities/10/attributes/Education/3/University/4",
         "entities/10/attributes/Education/3/University/5"
      ]
   },
   {
      "URI":"entities/10/crosswalks/2",
      "type":"configuration/sources/Reltio",
      "value":"XYZ.10",
      "attributes":[

      ]
   }
]

Update Crosswalk Value

This operation updates an existing crosswalk value.

Request

PUT {TenantURL}/{objectsType}/{objectId}/crosswalks/{crosswalkId}

Headers:Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512,
Body:{
   "value":"{{value}}"
}

Response

As a response, you will get an updated business object.

Request

PUT
http://localhost:8080/api/xx/relations/00XH5Yf/crosswalks/2GP
Headers:Authorization:Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512,
Body:{
   "value":"rel8"
}

Response

200OK{
       "URI":"relations/00XH5Yf",
       "type":"configuration/relationTypes/HasAddress",
       "startObject":{
              "objectURI":"entities/00XINTV",
              "URI":"relations/00XH5Yf/startObject",
              "type":"configuration/entityTypes/HCP",
              "label":"Split Testing E7  Split Testing Last Name 7",
              "directionalLabel":"has address"
   },
       "endObject":{
              "objectURI":"entities/00XIRjl",
              "URI":"relations/00XH5Yf/endObject",
              "type":"configuration/entityTypes/Location",
              "label":"Split Test Address 7   99777",
              "directionalLabel":"locates"
   },
       "attributes":{
              "AddressRank":[
                             {
                            "type":"configuration/relationTypes/HasAddress/attributes/AddressRank",
                            "ov":true,
                            "value":"7",
                            "URI":"relations/00XH5Yf/attributes/AddressRank/2zp"
         }
      ]
   },
       "crosswalks":[
                   {
                     "URI":"relations/00XH5Yf/crosswalks/2GP",
                     "type":"configuration/sources/AHA",
                     "value":"rel8",
                     "createDate":"2014-05-22T21:59:38.691+04:00",
                     "updateDate":"2014-05-22T22:16:45.599+04:00",
                     "attributes":[
                            "relations/00XH5Yf/attributes/AddressRank/2zp"

         ],
                     "singleAttributeUpdateDates":{

         }
      }
   ]
}

If you send an update request with a crosswalk where the crosswalk type is Reltio and the crosswalk value is an external value, then the value is ignored. The attribute value is replaced with the existing crosswalk and a new crosswalk will not be added. However, when two entities that have existing Reltio crosswalks are merged, then the merged entity will contain both crosswalks.

Search by Crosswalk Count

This operation performs a search for entities by crosswalks count.

Search Example

Request: find entities with crosswalks count 2

GET {TenantURL}/entities?filter=(equals(crosswalks_count,2))&max=2&select=uri
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response


[
  {
    "uri": "entities/20"
  },
  {
    "uri": "entities/142"
  }
]

Facet Search

This operation searches for crosswalks in a specific facet.

Facet Search Example

Request: facet crosswalks count with filter

GET {TenantURL}/entities/_facets?facet=crosswalks_count&filter=(equals(type,'configuration/entityTypes/HCP'))
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response


  {
    "crosswalks_count": {
      "1": 2,
      "3": 11,
      "5": 24
    }
  }

Multiple Facet

This operation searches for crosswalks across all facets.

Multiple Facet Search Example

Request: facet crosswalks count with filter

POST {TenantURL}/entities/_facets?filter=(equals(type,'configuration/entityTypes/HCP'))
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
[
  {
    "fieldName" : "crosswalks_count"
  }
]

Response

{  
   "crosswalks_count":{  
      "1":17,
      "2":15,
      "3":5
   }
}