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).
Headers	`Content-Type`	Yes	Should be `"Content-Type: application/json"`.
Query	`returnObjects`	No	Specifies if response should contain created objects. Note: Default value is `true`.
Query	`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
   }
}

Accelerate the Value of Data

Crosswalks

Supported Operations

Add Crosswalk

Edit/Add/Delete Date in Crosswalk

Delete Crosswalk

Delete Date From Crosswalk

Get Object Crosswalks

Update Crosswalk Value

Search by Crosswalk Count

Facet Search

Multiple Facet

Footer