Walkthrough: Implementing a Tenant Service Endpoint

Abstract

How to create a Tenant Service Endpoint in Sitecore Data Exchange Framework to handle read requests.

This topic shows you how to create a Tenant Service Endpoint (TSE) that handles requests to read data where the content is a JSON value.

Note

You can download source code and a Sitecore package that contains the finished solution for this example from GitHub.

Before you follow these instructions, you must set up a Tenant Service (web service) and add the Tenant Service to the Data Exchange Framework. You must also define the requirements for your provider, such as by constructing a user story describing the synchronization process. For example, the following user stories describe how someone responsible for building and mapping synchronization processes can handle the JSON content from the request:

  • I can specify a request path in order to configure a Matching Condition.

  • I can map the value from JSON content to a field on a Sitecore item, so I can create a Sitecore item using data from the request content.

This walkthrough describes how to:

  • Create a data exchange tenant

  • Add a Tenant Service Endpoint

  • Create a matching condition

  • Set the pipeline

  • Build the pipeline context builder

When process modeling is completed, you can use the Tenant Service to handle incoming web requests and run synchronization processes according to the model.

To create a data exchange tenant:

  1. In Sitecore Content Editor, navigate to /sitecore/System/Data Exchange.

  2. To create a new tenant, on the Folder tab, click Empty Data Exchange Tenant.

  3. In the Tenant Name field, enter a relevant tenant name.

  4. Upgrade the created tenant with the Tenant Service feature.

To add a TSE:

  1. Under the created tenant, navigate to Tenant Service Endpoints.

  2. To create a new endpoint, on the Folder tab, click Pipeline Tenant Service Endpoint.

  3. Enter a name for the TSE.

    Tip

    It is best practice to give the TSE an item name that describes its function. For example, you might name the TSE CRM Contact to Sitecore or Form submitted data to Sitecore.

To create a matching condition:

  1. Under the tenant, navigate to Tenant Service Settings/Matching Condition.

  2. To create a new item, on the Folder tab, click Absolute Path Matching Condition and enter a name for the item.

  3. In the created condition, in the Path field, set the request path.

  4. In the Condition Operator field, click Contains.

  5. Go to the Tenant Service Endpoint and assign the condition you just created.

For example, to run a pipeline from a TSE for the incoming request http://<tenantservice>/api/tenantservice/dosomething/?<query>, set the match condition with the following settings:

Setting

Value

Path

/dosomething/

Condition operator

Contains

The pipeline has the same meaning as in the Data Exchange Framework (DEF).

To run a pipeline from the handled request:

  • For the TSE item you just created, set a pipeline in the Pipeline field.

Note

You can only set a single pipeline.

The pipeline context has the same meaning as in the DEF.

To pass any request data to a pipeline, you must build the pipeline context with data passed through plugins.

To build the pipeline context:

  1. Under the tenant, navigate to Tenant Service Settings/Pipeline Context Builders.

  2. On the Folder tab, click the relevant pipeline context builder:

    Empty Pipeline Context builder

    Requests can be run with no data passing through the Pipeline Context. It means that your pipeline with pipeline steps does not have to handle any data from requests.

    Pipeline Context Plugin Builder

    Create plugins and add them to the Pipeline Context. The Pipeline Context is used in the selected pipeline. It can transform values from the request and passes the transformed values to the assigned plugin readers. All assigned plugins are added to the Pipeline Context.

  3. If you use a Pipeline Context Plugin Builder, you must specify the two value readers in DEF:

    Value Transformer

    Reads any data from the request before its read data is passed to the assigned Plugin Readers.

    Plugin Readers

    Allows you to assign multiple plugin readers where the read value must be of type IPlugin. All plugins are added to a new created Pipeline Context.