- Introduction
- Understanding the Crosswalk Concept
- Methods for Adding a New Crosswalk to an Existing Entity
- Prerequisites
- Manually Choose Which Crosswalk Will Be ‘Glued’ to the Other
- Trigger an Auto-merge Rule
- Add a Crosswalk without Contributing Any Data
- References
Introduction
This blog page aims to explore the ways of adding a crosswalk to an already existing entity. But first, let’s start with a couple of terms that we will use within this document.
Understanding the Crosswalk Concept
As we know a Reltio entity is formed of data coming from different sources. Inside Reltio we associate data with sources via crosswalks which play the role of unique identifiers. A Reltio entity can have multiple crosswalks and that is why it is of great importance for each crosswalk to be unique.
There are a couple of properties that make a crosswalk unique:
| Property | Description | Mandatory |
|---|---|---|
| Source Type | The URI reference to the source that you have declared in your Reltio tenantIt is unique as you cannot have two of the sameIf the object is created in the Reltio system and no crosswalks are specified, then its source type will be “Reltio”On Reltio UI the property is labeled as “Source System Name” and in the API call it is labeled as “type” | Yes |
| Crosswalk Value | Plays the role of the ID of the Reltio object in the source systemRequired only for entitiesOn Reltio UI the property is labeled as “ID Value” and in the API call it is labeled as “value” | Yes |
| Source Table | Used for scenarios where you want to refer data which is in an external source’s table | No |
| URL | The URL of the value in the source system | No |
Another thing to bear in mind is that a crosswalk can be of two kinds – data provider and non-data provider. A crosswalk can be specified as a data or non-data provider by adding a “dataProvider“ attribute to the crosswalk object. If such an attribute is not specified, by default the crosswalk will be considered as a data provider.
- Data provider – when a crosswalk is marked as a data provider it means that this crosswalk is associated with the attribute values provided for the object (the attributes set in the current API call). To mark a crosswalk as a data provider, set the “dataProvider“ attribute to true.
- Non-data provider – when a crosswalk is marked as a non-data provider that means that the crosswalk is associated with the overall entity/relationship and the crosswalk will not be associated with the provided attributes. It is primarily used to link a Reltio object with another system’s object.
Let’s look at this simple example:
Entity body that we push
[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"FirstName": [
{
"value": "John"
}
],
"LastName": [
{
"value": "Smith"
}
]
},
"crosswalks": [
{
"type": "configuration/sources/FB",
"value": "DataProviderPayload",
"dataProvider": true
},
{
"type": "configuration/sources/Salesforce",
"value": "NonDataProviderPayload",
"dataProvider": false
}
]
}
]When we go to the Reltio UI, we will see the following:
As we can see the First and Last name attributes have green marks and they come from the “Facebook” crosswalk. The Salesforce crosswalk which has “dataProvider” property set to false does not associate with any attribute, but it is associated with the profile.
Methods for Adding a New Crosswalk to an Existing Entity
Prerequisites
Before going deeper into the different ways of adding a new crosswalk, let’s prepare an example entity:
Payload of the initial state of our example entity
[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"FirstName": [
{
"value": "Jane"
}
],
"LastName": [
{
"value": "Doe"
}
]
},
"crosswalks": [
{
"type": "configuration/sources/Salesforce",
"value": "payloadInitial1"
}
]
}
]In Reltio UI the Sources tab of our entity looks like this:
We have only one crosswalk that has type “Salesforce” and value “payloadInitial1”. This crosswalk pushes only First and Last Name attributes.
Manually Choose Which Crosswalk Will Be ‘Glued’ to the Other
In the Legend Tab on Reltio UI, we have three options – Crosswalk (showing the existing crosswalks), Source (showing the sources associated with the crosswalks), and Contributor. If we click on the Contributor we will see that we have 2 contributors – one with Entity ID 0gFHp5V that holds the Salesforce crosswalk and one with Entity ID 0gFJGav that holds the Twitter crosswalk:
Important: In order to associate a new crosswalk with another entity, you have to add at least one contributor crosswalk.
Also note that when the “contributorProvider” equals true, the “dataProvider” should be false, otherwise you will receive an error.
Let’s add to the contributor that holds the Twitter crosswalk a new crosswalk that provides a Middle Name attribute :
Payload with Middle Name and “contributorProvider” crosswalk
[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"MiddleName": [
{
"value": "Anne"
}
]
},
"crosswalks": [
{
"type": "configuration/sources/TWITTER",
"value": "payloadToBeMerged",
"dataProvider": false,
"contributorProvider": true
},
{
"type": "configuration/sources/FB",
"value": "payloadToBeGlued",
"dataProvider": true
}
]
}
]When we go back to the Contributor’s Tab on Reltio UI we will see that the Facebook crosswalk is added to the contributor with Entity ID 0gFJGav:
Note: You can push multiple contributorProvider crosswalks at the same time only when you create a completely new entity. If the entity exists already, only one contributorProvider crosswalk can be pushed at a time.
Trigger an Auto-merge Rule
One way of adding a new crosswalk to an already existing entity is to push a new payload whose attributes are such that they trigger an auto-merge rule that is pre-configured in the L3 configuration.
For example, we have an auto-merge rule that is triggered when two entities have exactly the same First and Last Name attributes:
Automerge rule on Exact First and Last Name attributes in L3 configuration
{
"uri": "configuration/entityTypes/Individual/matchGroups/Auto_FirstLastName",
"label": "Auto_FirstLastName",
"type": "automatic",
"scope": "INTERNAL",
"useOvOnly": "true",
"rule": {
"and": {
"exact": [
"configuration/entityTypes/Individual/attributes/FirstName",
"configuration/entityTypes/Individual/attributes/LastName"
]
}
},
"scoreStandalone": 0,
"scoreIncremental": 0
}We push a new payload that has the exact same First and Last Name attributes so that it can invoke our auto-merge rule. Here the crosswalk has “TWITTER” for the type and “payloadToBeMerged” for the value:
Payload of the entity that will be merged with our initial entity
[
{
"type": "configuration/entityTypes/Individual",
"attributes": {
"FirstName": [
{
"value": "Jane"
}
],
"LastName": [
{
"value": "Doe"
}
]
},
"crosswalks": [
{
"type": "configuration/sources/TWITTER",
"value": "payloadToBeMerged"
}
]
}
]When we go back to our Reltio UI crosswalk’s view, we can see that the new crosswalk and its corresponding attributes have been added to our initial entity:
If we go and check the History tab, we can see that the automatic rule “Auto_FirstLastName” has been triggered:
Note: When you have merge on the fly, the incoming entity is assigned to a new contributor entity. We will look into what exactly is a contributor entity in the next section.
Add a Crosswalk without Contributing Any Data
You can also add a crosswalk that does not provide any data through an API call:
POST https://{{Env}}.reltio.com/reltio/api/{{MDMTenantId}}/entities/{{EntityId}}/crosswalksIn the body specify the source type and crosswalk’s value, for example:
[
{
"type": "configuration/sources/Salesforce",
"value": "addCrosswalkWithNoData"
}
]In Reltio UI it looks like this:
The same thing you can achieve from the UI – in the Crosswalk’s tab, click on the “+” sign and define the source system name and crosswalk’s value.
