Connect Sitecore Personalize to an external destination

This walkthrough describes how to set up a connection from Sitecore Personalize to an external destination. In Sitecore Personalize, to begin creating a triggered experiment or experience, you must first select a connection for sending the personalized data. You can set up a connection to an external destination, such as an Email Service Provider (ESP) or a REST API endpoint. This connection provides a way to send the output of a triggered experiment or experience to the chosen destination. For example, you might use a connection to an ESP when configuring an abandoned cart email message. Similarly, you can create a connection to the Guest REST API for updating a guest's data extension after an order is created.

Team members with a User, Developer, or Admin role in Sitecore Cloud Portal can connect to an external destination.

This walkthrough describes how to:

Create a new connection
Authenticate the connection
Configure the request
Review and save the connection

Create a new connection

The first step to connect Sitecore Personalize to an external destination is to create a new connection to that destination.

To create a new connection:

On the navigation menu, click Developer center > Connections.
On the Connections page, click Add connection > Destination.
On the Name & Describe page, complete the following fields:
- Name - enter a unique, intuitive name for the destination.
- Description - enter a concise description of the destination.
- Icon - from the drop-down list, select the icon that the user will see when they create a triggered experiment or experience.
Click Next to proceed to the Authenticate page.

Authenticate the connection

After you name the connection, you must choose how you want to authenticate the connection to the external destination. We recommend that you use OAuth 2, when possible.

To authenticate the connection to the destination:

On the Authenticate page, click one of the following authentication methods and complete the required fields:
- OAuth 2:
  - Access Token URL - enter the URL to the access token of the destination. The access token is generated by the destination system. The access token must use an HTTPS URL. This ensures you are using a secure connection.
  - Authentication option - select the Header option to pass the authentication credentials in the header or select the Body option to pass the authentication credentials in the body of the request.
  - Client ID - enter the client ID of the destination.
  - Client Secret - enter the client secret of the destination.
  - Headers - optionally, click Show headers and enter the key in the first field and the value in the second field. To enter additional headers, click Add Headers. If you selected Header for the Authentication option, you must enter the authentication parameters and values here.
  - URL encoded form - optionally, click Show URL encoded form and enter the key in the first field and the value in the second field. To enter additional items, click Add form item. This option enables you to convert keys and values into a valid URL format that you can send to Sitecore Personalize.
  - Configure with Mutual TLS - click to enable Mutual Transport Layer Security (mTLS). This lets Sitecore Personalize and the destination that you're connecting to authenticate each other using the TLS protocol.
    
    To view the Sitecore Personalize mTLS JSON Web Key Set (JWKS) endpoint, click the icon. The JWKS is a set of keys containing the public keys used to verify any JSON Web Tokens (JWT).
- Basic:
  - Username - enter the username for authenticating credentials to the destination.
  - Password - enter the password for authenticating credentials to the destination.
- None - this is only used for public APIs and is not recommended for connecting to an external destination like an ESP.
Click Next to proceed to the Configure Request page.

Configure the request

When you configure the request, you can set the headers and parameters that represent the metadata associated with the REST API request and response. Headers and parameters contain information that can help you troubleshoot issues.

To configure the request:

On the Configure Request page, in the Request URL drop-down list, select one of the following HTTP methods to use in the request:
- POST - use this method to send data to create a child resource under the resource collection.
- PUT - use this method to send data for updating an existing resource. Alternatively, if the resource does not exist yet, it creates a new one.
- PATCH - use this method to make partial updates on an existing resource. It allows you to modify a single value or a set of values within a resource without the need to resend the entire resource.
- DELETE - use this method to remove an existing resource.
In the Request URL field, enter the URL to send the destination request.

You can include variables in the URL by using the FreeMarker variable notation ${}. For example, https://example.com/api/emails/${email}?limit=${num}.

Important

When setting the request URL, headers, or request body in your connection, you cannot use variables from the guest data object, such as ${guest.email}. Unlike in experiences or experiments, FreeMarker does not recognize these objects and their properties at runtime, which might result in an exception.
Click Show Default Headers to display the default headers and parameters for the destination:
- Accept - this field displays application/json to specify that JSON is the accepted format for the response.
- Accept-Encoding - this field displays gzip to specify that gzip is the accepted compression type.
- Content-Type - this field displays application/json to specify that JSON is the format of the content sent in the request.
To add additional headers, click Add Header. An additional row displays to enter the following:
- Key - enter the header name.
- Value - enter the parameter.
You can include variables in header names and parameters by using the FreeMarker variable notation ${}.
To configure the connection timeout, fill in the following fields:
- Connection Timeout (ms) - in the drop-down list, select the number of milliseconds of inactivity after which the connection will close. The default is 1000.
- Read Timeout (ms) - in the drop-down list, select the number of milliseconds between connectivity being established and not receiving a response from the server after which the connection will close. The default is 1000."
In the Request field, enter a sample JSON request to test your connection. Ensure that the JSON is valid. Don't send real guest contact details in the sample request.

You can include variables in the sample request by using the FreeMarker variable notation wrapped in double quotes "${}". For example, "name": "${name}" or "email": "${email}".
Click Test Request. If you included variables in the request URL, header, or body, such as ${email}, enter test values for them. Then click Run Test.

The results of the test display in the Response field with the relevant status code.
Click Next to proceed to the Review & Save page.

Review and save the connection

You must continue to this page otherwise the connection that you have set up in the previous pages will not be saved and you will have to start over creating a connection.

To save the connection:

On the Review & Save page, you can see a consolidated view of your connection. Check that the external destination has been set up correctly.
To return to a previous page to edit the setup details, click the relevant tab at the top of the page, or click Back.
When you are ready to finalize the connection setup, click Save.

Warning

After you save, you cannot edit the connection. Review it before saving.

You can now use this connection when you're creating a triggered experiment or experience.

Do you have some feedback for us?

If you have suggestions for improving this article,