Reltio SnapLogic Connector

The Reltio-SnapLogic Snap Pack enables you to transfer data to and from your tenant using SnapLogic. The transfer is done via Reltio REST APIs.

The Reltio-SnapLogic Snap Pack enables you to transfer data to and from your tenant using SnapLogic. The transfer is done via Reltio REST APIs.. SnapLogic has a graphical front-end that you use to specify the logical flow of information. In SnapLogic's terminology, each REST API is called a Snap Connector or just connector.

Note: The Reltio Snap Pack is an Early Access feature for 2017.33. If you are interested in testing the Reltio Snap Pack, please contact Reltio at support@reltio.com to enable this feature.

Here are the connectors in the Reltio Snap Pack:

  • Reltio Snap Write-Posts data into Reltio Cloud. It can be used for either a create or an update operation.

  • Reltio Snap Get by Object-Exports data from entities, relations, and interactions.

  • Reltio Snap Get by Crosswalk-Exports data from entities, relations, and interactions identified by a crosswalk.

  • Reltio Snap Merge-Merges two entities into a "winner" entity.

  • Reltio Snap Unmerge-Unmerges two entities that were previously merged.

  • Reltio Snap Delete by Object-Deletes an entitty.

  • Reltio Snap Delete by URI-Deletes an entity identified by its URI.

  • Relations Hierarchy Snap-Imports a CSV file and creates a hierarchical relationship.

  • Reltio Generic Execute-Executes any Reltio API.

Definitions

Here are some important terms that you will encounter.

  • Document: A structure representing data in JSON format so it can be used to exchange information between snaps and pipelines.

  • View: The interface for a Snap. This is the data stream that flows in or out of the Snap.

  • Document View: The data stream in JSON format.

  • Binary View: The data stream in binary format.

The SnapLogic GUI

The SnapLogic GUI is at https://elastic.snaplogic.com/sl/login.html. It consists of the SnapLogic core tools plus a large number of plugins that provide specific integration solutions. The Reltio Snap is one of many SnapLogic plugins, known as Snap Packs.

When you use a Reltio Snap, you integrate it into a workflow, known in SnapLogic terminology as a pipeline. A Snap is the basic building block of a pipeline. Each Snap performs a single complete function, such as read, write, merge, or delete.

Please refer to the main SnapLogic Documentation. This chapter assumes that the reader has a general working knowledge of SnapLogic but only needs to learn about the Reltio SnapLogic integration. To create Reltio pipelines, you will need to use some other SnapLogic tools.

Logging into the SnapLogic User Interface

Prior to using any of the Reltio Snaps, you need to set up a project.

  1. Navigate to the SnapLogic GUI. Enter your username and password and click Log in.

The SnapLogic Designer appears.

The Designer Tab

You will spend most of your time in the Designer.

Before using the SnapLogic Designer to transfer information, you need to create a SnapLogic project and a SnapLogic account. The account will hold your Reltio Authentication URL. SnapLogic uses it to obtain an initial access token and, when it expires, a refresh token.

Understanding SnapLogic Projects

A project is a logical group of pipelines, files, accounts, Snaps, and possibly other components. As such, you need to create a project to use Reltio Snaps to transfer data.

Creating a Project

It is best to create a project in the Manager tab of the SnapLogic UI. After you create a project and an account, you can switch to the Designer tab and build pipelines that transfer data to or from your Reltio tenant.

Create a Project

Use the following steps to create a project:

  1. Click the Manager Tab.

  2. Hover over a Project Spaces item in the sidebar until its contextual menu icon appears.
  3. Press the arrow to reveal the drop-down menu.
  4. Choose Create New Project.

  5. Enter a name for the project.

    Note: A project name cannot contain the characters #, ?, and /.
  6. Click Create.
  7. In the sidebar, expand the item that contains your new project and highlight it. In the next series of steps you will create an account for that project.

Creating an Account for the Project

A SnapLogic account contains the information that SnapLogic needs to obtain and refresh an access token. Each REST request must have a valid access token in its header. With an account, SnapLogic will take care of this for you.

To create an account for a project:

1. With your new project highlighted (as shown above), click All.

3. Above the table header, click on the Plus Sign.

4. Press to reveal the hierarchical menu and choose Account > Reltio Snap Connector > Reltio Account.

The Create Account dialog appears.

Create Account Dialog box.

Here are descriptions of the fields in the Create Account dialog.

Name Description
Label The name of the account. Use it to refer to the account. Do not use spaces.
Username The username of the account.
Password The password for the account.
OAuth2 URL

The URL of the Reltio Authentication server. Replace the placeholder text with the URL of the Reltio Auth server. At present, it is: https://auth.reltio.com/oauth/token.

The Reltio-Snaplogic integration uses this URL to obtain an access token for the given tenant URL and user information. Before requesting information on behalf of that user, Snaplogic will check whether the current access token is current. If it has expired, it will request a new access token using the information stored in this account.

API Key The token for the OAuth2 server. This value is filled in for you.
  1. Enter a label for the account, your username and password, and enter the URL of your Auth server.
  2. Click Create.

The account that you have created contains your Authentication server's URL. SnapLogic uses this information to request an access token from the specified Auth server. When you use SnapLogic to create a request, SnapLogic will use this information to provide the current access token or, if it has expired, generates a refresh token.

Each successful response from the Reltio Auth server also includes information on when it expires and a refresh token. SnapLogic has the ability to request a new access token when the current access token expires. It does this by checking whether the current access token is valid before submitting the new request.

You are now ready to start using Reltio Snap integration tools. Click the Designer tab to switch to the SnapLogic Designer.

Follow the instructions in the next section to build the Reltio-SnapLogic pipelines that you need.

Using the Reltio Snap Connectors

You use Reltio Snap connectors in a pipeline that visually specifies the flow of data from start to finish. After you have created a project and at least one account, an empty pipeline is created when you switch to the Designer tab. You only need to build it using connectors.

When you want to build a second pipeline, click the Plus sign in the Designer tab toolbar.

The Configure New Pipeline dialog box appears, with a default name and the current path to your project folder.

The parameter table allows you to save key/value pairs with the pipeline.

Parameter Type Description
Capture Boolean If true, capture and save the value in the runtime environment.
Key String The value of the key field.
Value String The value associated with this key.

Adding a Snap to a Project

Here is an overview of the process of adding and configuring a Reltio Snap.

  1. Expand the Reltio Snap Connector group in the sidebar.

3. Drag a Snap to the editing pane. Your next task is to configure the Snap by setting its properties.

4. Click the Snap.

The Snap's Properties dialog appears. The properties dialog has four tabs:

  • Settings: Set the properties of the Snap,
  • Account: Set or change the account for the Snap,
  • Views: Modify the input, output, and error views for the Snap,
  • Info: Enter notes about the Snap in the current pipeline.

When you click a Snap icon in the Designer, it opens to the Settings tab:

Use it to set its properties. If an equals sign precedes an entry box, it turns on expressions for the entry. SnapLogic will try to interpret your entry as an expression rather than a constant. Notice that the Object and Object Types fields in this dialog have equals signs.

This feature is available only available for string properties.

As an example, the Reltio Snap Write connector has the following properties.

  • Label: The name of the Snap. It appears as the header of the dialog. Give it a name that suggests its function in the pipeline.

  • Tenant URL: The URL of your tenant.

  • Object: The type of object that you will be reading or writing. The options are: entities, interactions, and relations.

  • Object Types: The object types in the selected Object. This drop-down list is automatically populated from the information in the configuration when you enter the Tenant URL and Object in the two fields above it.

  • Query Parameters: If you need to specify Query parameters, specify them as one or more key/value pairs. The query parameters for an API are described in the API reference for that API. To add a query parameter, click the Plus sign. To delete a key/value pair, click the minus sign adjacent to the pair.

  • Batch Size: Reltio Snap connectors support batch mode operations when appropriate. If a connector supports batch mode, Batch Size appears as a parameter. It defines the batch size of the request. The incoming documents will be accumulated up to the defined batch size before it is submitted to the endpoint.

  • Maximum Threads: Specifies the maximum number of parallel instances that can run at a time. If the count of parallel instances is reached, then the Snap will wait until any instance completes.

  • Maximum Request Attempts: The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

  • Retry Request Interval: Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception.

Some Snaps have more or fewer parameters, depending on their function. See the section on the Snap you are using or use the contextual help, described in the following section.

Contextual Help

The SnapLogic GUI offers contextual help throughout the system. With the window in front, hover over an interface element until the pointer turns into a question mark. Press down to display the contextual help for that interface element.

In this screenshot, the pointer is over the "Query Parameters" heading and has changed into a question mark. Each column heading in the Query Parameters section also has its own help text.

The Account Tab

Use this tab to specify the account to be used by the Snap in case it does not inherit the account that you created in the Manager tab or you need to change it. The Account Reference field has a drop-down list of the current accounts in the project, with the active account selected.

The Views Tab

Use the Views tab to add or delete input, output, or error views to the connector. The Views tab enables you to connect data inputs, output, or handle errors. For example, if the Snap has no Input view by default but you need to connect the output of another Snap to it, you can use this tab to add one.

In this screenshot, input and output views have been added.

Inputs and outputs are depicted visually in the Designer. A circle indicates a document (JSON) input or output. A diamond indicates a binary input or output. Here is a connector that has a binary input and a document output. The shapes indicate how it can be connected to other connectors.

The diamond input icon indicates that this Snap accepts only binary input data and the circular output icon shows that it outputs a JSON text document. That is, the shape of the input or output connector tells you the appropriate document type. You build pipelines by connecting compatible connectors into a chain that depicts the flow of data.

You specify error handling by choosing the desired value from the Error pop-up menu. This is illustrated below.

In the Designer, this option is depicted in the following way:

If a Snap doesn't have input or output connectors, its left and right sides are flat. By default, the Generic Reltio Snap has no inputs or outputs.

Add a row to the Input or Output table so it can be connected to its pipeline.

The Info Tab

You can use the Info tab to enter notes about the current tab. Of course, it is optional.

Pipeline Properties

The properties of pipelines can be viewed and edited in the Designer tab. Click the Edit Pipeline icon in the toolbar.

The Edit Pipeline dialog box appears.

Settings Tab

Name Required Description
Label Yes The name of the pipeline. Each pipeline within a project must have a unique name.
Project Yes

The project into which to save the pipeline, displayed as <project_space>/<project_name>. All necessary resources (such as files and accounts) should be within the same project unless they are part of the Shared project.

Note: This is only configurable before you save your pipeline the first time. To change the project later, you will need to move it to a new project or make a copy.

Parameters No

Lets you define parameters to be used during pipeline execution.

There is an option to capture pipeline parameters. Selecting this checkbox will send the value of the parameter to the pipeline runtime history if the pipeline is run through a task.

The parameters table is the same as for the Configure New Pipeline dialog box, discussed earlier.

Parameter Type Description
Capture Boolean If true, capture and save the value in the runtime environment.
Key String The value of the key field.
Value String The value associated with this key.

Pipeline parameters can only contain alphanumeric characters.

To use the value of that parameter as part of an expression within a Snap, you need to use the underscore character (_) as a prefix to the parameter name, such as "_myParam1", such as '/out'+_myParam1+'.json''.

Info Tab

Name Required Description
Notes No Detailed notes about the pipeline.
Purpose No Purpose of the pipeline.
Author No The primary author of the pipeline, defined by the user creating the pipeline.
Doc Link No Link to user-created documentation of the pipeline.

Please refer to the SnapLogic documentation for information on how to connect Snaps into a pipeline.

The following sections provide detailed descriptions of each Reltio Snap connector.

Reltio Snap Write

Reltio Snap Write writes the given data into a Reltio tenant for the given business model. You specify the object (for example: entities) and the object type for that business model. The possible business models are: entities, relations, and interactions.

Table 1. Snap Write Settings
Name Required Description and Example
Label Yes The name of the Snap. You should modify this to be more specific, especially if you have more than one Snap Write instance in your pipeline.

Example: write clinics

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant: https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Object Yes The Reltio object to write. The object names are retrieved from the configuration of the tenant and used to populate the popup.You select the appropriate object name to write the data from a business model. The business models are: entities, relations, and interactions.

Example: entities

Object Types No The value to filter by an object type inside an object. For example: configuration/entityTypes/Location. This list is populated after the tenant and object are selected.

Example: configuration/entityTypes/HMO

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Execute During Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Query Parameters No The query parameters that are submitted as part of the request. The query parameters for an API are described in the associated REST API.
Example Query Parameters
Example 1

These query parameters check whether the Reltio Cloud contains attributes.ISO3166-3 inside an object. If it does, then it fetches 5 records.

Query Parameter Value
filter (exists(attributes.ISO3166-3))
max 5
Example 2

This is the same as above, but the value is passed upstream.

Query Parameter Value
filter $exists
max 5
Views
Name Description
Input This Snap has exactly one document input view. Each document contains data in the form of a JSON object.
Output This Snap has exactly one document output view. Each document contains the corresponding response from Reltio Cloud when the snap is able to write the data into Reltio Cloud.
Error This Snap has at most one document error view and produces zero or more documents in the view. Each document contains the corresponding error record if the Snap is not able to write the data into Reltio Cloud.

Snap Write Settings Example

In this example, the binary data in a file is converted to a JSON file and is sent to the Write Snap for writing into the given tenant. It will show the response in the output view.

Here is the pipeline:

The File Reader reads a CSV binary file and the CSV Snap converts it to JSON. The Mapper maps the fields in the file to the fields to be populated in the given tenant. Here are the Snap Write properties:

Reltio Snap Get by Object

The Get by Object Snap executes the HTTP GET method to a Reltio REST API service endpoint to retrieve data for the specified business model for a tenant. The business models are: entities, relations, and interactions. Additional Snaps need to be attached to the output of the Reltio Get Snap to convert the JSON output into CSV format and be saved into a file.

Table 2. Get by Object Properties
Name Required Description and Example
Label Yes The name of the snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline.
Tenant URL Yes

The service endpoint URL of this REST API. The default value is the current tenant: https://<yourreltiohost>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Object Yes

The Reltio object to read. The object names are retrieved from the configuration of the tenant. You must select the appropriate object name to get/read the data from a business model (entities, relations, and interactions).

Example: entities

Object Types No

The value to filter by an object type inside an object.

Example: configuration/entityTypes/Location

Explode No

If true, export several records for multi-valued fields. The data can be exported in two ways: (1) multi-row export, (2) multi-column export (default) i.e., You may select the explode option as true (for multi-row export) or false (for multi-column export). The Explode option is No.

For multi-valued attributes, the Snap can either export either as separate record (with explode) or shows it as a multi-column export. For instance, if an entity has 3 addresses but only 2 departments, then the Get snap with the Explode option as true will produce 3 records with 3rd department data as null.

Example: Yes

Maximum Request Attempts No

The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5

Example: 3

Retry Request Interval No

Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3

Example: 10

Execute During Preview No

Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Table 3. Views
Type Description
Input This Snap has at most one document input view.
Output This Snap has exactly one document output view. Each document contains data retrieved from the Reltio Cloud.
Error This Snap has at most one document error view and produces zero or more documents in the view.

Reltio Snap Get connector

Here are some examples of the Reltio Snap Get connector.

Get All Entities

The following request returns the entities in the given tenant. The number of entities returned is limited by API restrictions. It is 200 entities per request.

Get All Entities by Type

This request uses a Mapper to process the output of the Get by Object Snap. The number of entities returned is limited by API restrictions. It is 200 entities per request.

Use a Mapper Snap to process the output of the Reltio Get by Object.

Get Entity Count

This example gets the total of the entities of a Get by Object Snap.

Reltio Snap Get by Crosswalk

The Snap Get by Crosswalk executes an HTTP POST method to a Reltio REST API service endpoint to retrieve data for a given business model in the given tenant by filtering on a crosswalk value and crosswalk type. The business models are: entities, interactions, and relations.

Table 4. Snap Get by Crosswalk Properties
Name Required Description and Example
Label Yes The name of the Snap. You should modify this to be more specific, especially if you have more than one Snap Get by Crosswalk instance in your pipeline.

Example: colleges

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant. https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Object Yes The Reltio Object to write. The object names are retrieved from the configuration of the tenant. You must select the appropriate object name to get/read the data from a business model (entities, relations, and interactions).

Example:entities

Object Types No The value to filter by an object type inside an object. This list is populated after the tenant and object are selected.

Example: configuration/entityTypes/Location

Query Parameters No The query parameters that are submitted as part of the request. The query parameters for an API are described in the Reltio API Command Reference for that API. See examples below.
Explode No

If true, export several records for multi-valued fields. The data can be exported in two ways:

  • multi-row export
  • multi-column export (default)

You may select the Explode option as true (for multi-row export) or false (for multi-column export, this is the default value). The Explode option is not selected by default.

Example: Yes

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Execute During Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception.
Note: The retry mechanism is implemented with exponential back of logic. Please refer to appendix 2 for the algorithm. The default value is 3.

Example: 10

Table 5. Snap Get by Crosswalk Views
Name Description
Input This Snap has exactly one document input view. Each document contains records of the crosswalk value and the crosswalk type.
Output This Snap has exactly one document output view. Each document contains data retrieved from the Reltio Cloud.
Error This Snap has at most one document error view and produces zero or more documents in the view.

Snap Get By Crosswalk Example

This example reads tenant data by passing a set of crosswalk values and crosswalk types as JSON. Here is the pipeline:

The JSON Generator Snap provides JSON type/value pairs that the Get by Crosswalk Snap expects. Here are its properties.

Reltio Snap Merge

The Reltio Merge Snap executes an HTTP POST to a Reltio API service endpoint to merge the entities for the given Winner ID and Loser ID into one entity. The Winner ID is the ID of the survivor or winner entity. The Loser ID is the entity to be merged with the Winner ID entity.

The user needs to pass the values for Winner ID and Loser ID. The Merge Snap will show the response which contains only the winner entity in the output view.

Table 6. Reltio Snap Merge Properties
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Snap Merge instance in your pipeline.

Example: Offices

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant. https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Object Yes The appropriate object name to write the data in the specified tenant for a business model. The choices are: entities, interactions, and relations.

Example: entities

Object Types No The specific type of object to write. If this is not given, the property value is considered.configuration/entityTypes/Location
Batch Size No The batch size of the request. The incoming documents will be accumulated in a list up to the defined batch size before it is submitted to the endpoint. The default is 50.

Example: 40

Maximum Threads No The maximum number of parallel instances that can run at the same time. The default is 50.

Example: 30

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Execute During Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Table 7. Views
Name Description
Input This Snap has exactly one document input view. Each document contains the winner ID of the object and the loser id of the object to be merged.
Output This Snap has exactly one document output view. Each document contains the response from the Reltio Cloud when the merge is successful.
Error This Snap has at most one document Error view and produces zero or more documents in the view. Each document contains the response from the Reltio Cloud when the merge is not successful, i.e. the error record is pushed to the Error view.
Note: Use the Mapper Snap to map the Winner ID and Loser ID to the $winnerID and $loserID of a Reltio Snap Merge corrector. It will merge the two entities.

Here is the relevant portion of the pipeline:

The Mapper configuration simply maps the two entities to be merged to the $winnerId and $loserId variables.

Here are the Merge Snap's properties.

Reltio Snap Unmerge

Reltio Snap Unmerge unmerges the entities from a previously merged identity for a given source ID. This Snap executes a HTTP POST method to a Reltio REST API service endpoint to unmerge the entities for the given Origin ID and Spawn ID. The Origin Id is the Origin or composite entity ID. The Spawn Id is the ID of the entity to be unmerged. The user needs to provide the map for the entity ID for origin and spawn.

For the case of mapping the entity ID for Origin and Spawn ID, the unmerge snap will generate the input schema.

This Snap will unmerge the Spawn entity from the Origin entity (if the Spawn entity was previously merged to the Origin entity and the Origin entity contains the reference to the spawn ID in the crosswalks property). The Unmerge Snap will show the response which contains both the Origin entity and Spawn entity in the output view.

Table 8. Reltio Snap Unmerge Properties
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Snap Unmerge instance in your pipeline.

Example: Offices

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant. https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Unmerge Identity Tree No If True, the spawn would be unmerged with all previous content obtained in previous merges if the spawn entity was a result of several merges.
Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Execute during Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Table 9. Reltio Snap Unmerge Views
Name Description
Input This Snap has exactly one document input view. Each document contains the Origin ID of the object and Spawn ID of the object to be unmerged.
Output This Snap has exactly one document output view. Each document contains the response from the Reltio Cloud when unmerge is successful.
Error This Snap has at most one document error view and produces zero or more documents in the view. Each document contains the response from the Reltio Cloud when the merge is not successful, i.e. the error record is pushed to the error view.

Example

Use the Mapper Snap to map the Origin ID and Spawn ID from a previous merge operation. Here is a simple pipeline:

The mapper simply maps the two entities to $originId and $spawnId.

Here are the Unmerge Snap's properties.

Reltio Snap Delete by Object

The Delete by Object Snap deletes the specified resource object from the given tenant. You select the object to be deleted using the objectIdentfier parameter in the Settings dialog.

Here are the properties of the Delete by Object Snap.

Table 10. Reltio Snap Delete by Object Properties
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Snap Delete instance in your pipeline.

Example: Offices

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant:. https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01

Object Yes The appropriate object name to write the data in the specifies tenant for a business model. The choices are: entities, interactions, and relations.

Example: entities

Object Identifier Yes The ID of the object to be deleted.

Example: EJ4UesS123

Explode No If true, export several records for multi-valued fields. The data can be exported in two ways: (1) multi-row export, (2) multi-column export (default) i.e., User may select the explode option as true (for multi-row export) or false (for multi-column export) This is the default value.

Example: Yes

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception.
Note: The retry mechanism is implemented with exponential back of logic. Please refer to appendix 2 for the algorithm.
The default value is 3.

Example; 10.

Execute During Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

This example loads two entities, gets the entity numbers from the URI, and maps the entity numbers to identifier in the Delete Snap. The Delete Snap will process the delete operation. Here is the pipeline:

The Filter selects the entity to be deleted and sets it to $identifier variable. Here are the Delete by Object's properties:

Reltio Snap Delete by URI

Snap Delete by URI deletes the resource objects from Reltio Cloud for a given Reference URI.

Settings

Here is the Reltio Snap Delete by URI properties dialog box.

Table 11. Reltio Snap Delete by URI Properties
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Snap Delete by URI instance in your pipeline.

Example: Delete Branches

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant. https://<your_reltio_host>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/reltio/api/SnApLoGiCJpdf01

Object Yes User must select the appropriate object name to delete the data from a business model. The choices are: entities, relations, and interactions.

Example: entities

Reference URI Yes The URI of the object to be deleted.

Example: entities/EH4Ueas

Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Table 12. Reltio Snap Delete by URI Views
Name Description
Input This Snap has at most one document input view.
Output This Snap has exactly one document output view. Each document contains data retrieved from the Reltio Cloud. Each document contains the response from the Reltio Cloud when the delete is successful.
Error This Snap has at most one document error view and produces zero or more documents in the view. Each document contains the response from the Reltio Cloud when the delete is not successful, i.e. the error record is pushed to error view.

This example reads an entity URI using Reltio Get Snap and gets that URI by passing that entity's URI to the Delete by URI Snap. Here is the pipeline:

The Filter Snap is used to select the URI to be deleted. Here are the properties of this Delete by URI Snap.

Relations Hierarchy Snap

The Relations Hierarchy Snap reads data from the given CSV input file and builds a relationship hierarchy from it. The input data must be in the form of a CSV file. If the input data is not in CSV format, then it must be reformatted into CSV type. The first record of the CSV file will be treated as header data. This relationship hierarchy needs to be passed to a Write snap by mapping the schema for creating the relationships in Reltio Cloud.

The Tenant URL should be given. You also need to select or suggest the relation type such as Employee. You also need to specify the crosswalk source type.

Here is the Relations Hierarchy Snap properties dialog box.

The Relations Hierarchy Snap Properties.

Table 13. Relations Hierarchy Snap Properties
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Relations Hierarchy Snap instance in your pipeline.

Example: Offices

Tenant URL Yes The service endpoint URL of this REST API. The default value is your tenant: https://<your_reltiohost>/reltio/api/<tenantid>

Example: https://sndbx.reltio.com/reltio/api/SnApLoGiCJpdf01

Object Types No Relation type.

Example: configuration/relationTypes/Academic

Source System Type No Crosswalks source type.

Example: configuration/sources/HMS

Table 14. Relations Hierarchy Snap Views
Name Description
Input This Snap has exactly one document input view.
Output This Snap has exactly one document output view.
Error This Snap has at most one document error view and produces zero or more documents in the view.
Note:
  • A CSV parser Snap (or its equivalent) should be the left side Snap.

  • A Relations Snap will produce a relation hierarchy which will become the input schema for the right side Snap.

  • The first record of the input CSV data will be treated as the header.

  • The input data contains the crosswalks ID of the entity. The output schema of the Relations Hierarchy Snap will contain the crosswalks type and value for both startObject and endObject.

This example builds a relations hierarchy from an Excel document and writes the relations to Reltio.

Here is the pipeline:

Here are the settings for the Mapper Snap:

Expression Target Path
$['HCQ.Name'] $['HCQ.Name']
$['Level2 Hierarchy'] $['Level2 Hierarchy']
$['Level1 Hierarchy'] $['Level1 Hierarchy']
$['GPO Parent'] $['GPO Parent']

Here are the Relations Hierarchy's properties:

Reltio Generic Execute

Performs any HTTP operation on Reltio Cloud for the given tenant. Unlike all the other Reltio Snaps, it has a field for the HTTP action, so it can use anyREST action. You can use it when a specific Reltio Snap is not available.

Here is the Reltio Generic Execute properties dialog.

Table 15. Reltio Generic Execute Snap
Name Required Description and Example
Label Yes The name of the snap. You should modify this to be more specific, especially if you have more than one Snap Generic Execute instance in your pipeline.

Example: Get Branches

HTTP Method Yes The type of HTTP request. The choices are: GET, PUT, POST, and DELETE. Choose the desired action from the drop-down list.

Example: GET

Service URL Yes The service endpoint URL of this REST API. The default value is your tenant: https://<yourreltiohost>/reltio/api/<tenant_id>

Example: https://sndbx.reltio.com/api/SnApLoGiCJpdf01/entities

HTTP Body No Used for importing data. The JSON path to the HTTP entity data in the input Map data. Leave this property empty if there is no entity data to send to the service URL. The default value is $ (the HTTP entity data is at the root of the input Map data).

Example: $.entity (if the HTTP entity data is the value of the "entity" key at the root of the input Map data)

Query Parameters No The query parameters that are submitted as part of the request. The query parameters for an API are described in the Reltio API Command Reference for that API. See the examples below.
Maximum Request Attempts No The maximum number of attempts to be made to receive a response. The request is terminated if the specified number of attempts does not result in a response. The default value is 5.

Example: 3

Retry Request Interval No Specifies the interval (in seconds) between two successive requests. A retry happens only when the previous attempt resulted in an exception. The default value is 3.

Example: 10

Execute During Preview No Executes the Snap during a pipeline Save operation so that the output view can produce the preview data. The default is No.

Example: Yes

Query Parameters

Example 1

These query parameters will check the whether the Reltio Cloud data contains attributes.ISO3166-3 inside an object. If it does, then it fetches 5 records.

Query Parameter Value
filter (exists(attributes.ISO3166-3))
max 5

Example 2

This is the same as above, but the value is passed upstream.

Query Parameter Value
filter $exists
max 5

Views

Use the Views tab in the Settings dialog to configure the views to handle your use case. The proper settings will depend on the HTTP action that you choose.

Name Description
Input This Snap has at most one document input view. Each document contains data in the form of JSON.
Output This Snap has exactly one document output view. Each document contains the corresponding response from Reltio Cloud when the snap is able to write the data into Reltio Cloud.
Error This Snap has at most one document error view and produces zero or more documents in the view. Each document contains the corresponding error record if snap is not able to write the data into Reltio.

This example writes JSON data into an entity. This functionality is also available with the Reltio Write Snap. The example uses a Mapper Snap to map the JSON data to the payload and the JSON Formatter snap to convert the data to binary. Here is the pipeline.

Note: Input, output, and error handling views were added to the Generic Snap.

Here is the Mapper configuration:

Expression Target Path
$attributes $payload[*].attributes
$type $payload[*].type

Here are the properties: