Skip to main content

Compatibility Endpoint Migration Guide

This guide will help you migrate from Jitsu Classic to Jitsu 2.0 using compatibility endpoints. You don't need to change your client code, but you need to update the the configuration.

Alternatively, you can switch to a native Jitsu 2.0 client and protocol. See the Sending Data guide for more details.

Set up a new Jitsu 2.0 project​

Open https://use.jitsu.com and create a new project.

Migrate API Keys​

For each API Key in Jitsu Classic project, a corresponding Site entity must be created in Jitsu 2.0.

To add a new Site entity, open the Event Streaming -> Sites section of the main menu and click the Add new site button.

There you will obtain a new Write Key that should be used in the client configuration.

Also t.jitsu.com host must be changed to the legacy.d.jitsu.com in all your client configurations.

Custom domains​

In Jitsu 2.0 custom domains are managed on the Site entity level.

To direct you exising custom domain to Jitsu 2.0 you need to add it to the Jitsu 2.0 site and change CNAME to cname.jitsu.com

caution

Issuing a new certificate can take a few minutes. To avoid downtime, you can use the legacy.d.jitsu.com host in the meantime or choose a different subdomxain for Jitsu 2.0.

Migrate Destinations​

Destination Credentials​

In Jitsu 2.0, the Destination entity only sets credentials and destination-specific settings.

To migrate the destination credentials, you need to create a new Destination entity in Jitsu 2.0 and set up the same credentials as in Jitsu Classic.

To add a new Destination entity, open the Destinations section of the main menu and click the Add new destination button.

Migrate Connections​

In Jitsu Classic links between an API Key and Destinations can be found in the Connected Destinations property of an API Key.

For each connected destination, you need to create a new Connection entity in Jitsu 2.0.

To add a new Connection entity, open the Event Streaming -> Connections section of the main menu and click the Connect site and destination button.

In the Connection editor choose the corresponding Site(Source) and Destination entities.

Here you can also set parameters like Sync Mode, Data Layout, Functions, etc...

Migrate Transformation​

In Jitsu 2.0, the Transform Destination setting is replaced by the Function entity.

To replicate the same transformation logic, you need to create a new function and add it to the Connection settings.

To add a new Function entity, open the Event Streaming -> Functions section of the main menu and click the Add new function button.

There are two ways to adjust existing transformation logic to Jitsu 2.0:

  1. Rewrite the transformation logic to work with the new event format.
  2. Use the toJitsuClassic, fromJitsuClassic methods to convert the event to the Jitsu Classic format and back:
export default async function(event, ctx) {
    const $ = toJitsuClassic(event, ctx)
    // your existing transformation logic here
    return fromJitsuClassic($)
}

Don't forget to use fromJitsuClassic($) method unless you apply transformation for the Webhook destination.

Open the Connection entity editor and add the function in the Functions section.

Data Warehouses specific settings​

To make Jitsu 2.0 use the same table layout as Jitsu Classic, you need to set up a Connection entity with the Data Layout set to Legacy Jitsu.

Jitsu 2.0 doesn't have the Table Name setting. To customize the table name, you can use the Function

The User Recognition settings in Jitsu 2.0 was renamed to Identity Stitching and can be found in the Advanced section of the connection settings.

Webhook specific settings​

In Jitsu 2.0 webhook destination doesn't have the HTTP JSON Body setting. To customize the request body, you need use the Functions

In Classic project, the webhook request body is derived from classic event layout. To replicate that in Jitsu 2.0 project you need to set up a function that transforms the event back into classic format:

export default async function(event, ctx) {
  const $ = toJitsuClassic(event, ctx)
  // request body transformation logic if any
  return $
}

Add that function to the connection settings.

caution

In Jitsu 2.0, the webhook destination doesn't support the JSON array as the root object of the request body. If it is strictly required, please contact the Jitsu support team.

Change Client configuration​

After all API keys, destinations, and connections are migrated, you need to update the client configuration to send event to Jitsu 2.0.

HTML Snippet​

Change the hostname of src attribute to legacy.d.jitsu.com and replace the data-key attribute with the Write Key of your Site:

Snippet for Jitsu Classic:

<script src="https://t.jitsu.com/s/lib.js" data-key="[JITSU_API_KEY]" defer></script>
<script>window.jitsu = window.jitsu || (function(){(window.jitsuQ = window.jitsuQ || []).push(arguments);})</script>

Snippet for Jitsu 2.0:

<script src="https://legacy.d.jitsu.com/s/lib.js" data-key="[SITE_WRITE_KEY]" defer></script>
<script>window.jitsu = window.jitsu || (function(){(window.jitsuQ = window.jitsuQ || []).push(arguments);})</script>

Other clients​

For other clients, you need to:

  1. Replace the key parameter with the Write Key of your Site
  2. Replace or add tracking_host parameter with the https://legacy.d.jitsu.com value.

NPM package:

const { jitsuClient } = require('@jitsu/sdk-js');
const jitsu = jitsuClient({
    key: "[SITE_WRITE_KEY]",
    tracking_host: "https://legacy.d.jitsu.com" ,
    ...params
});

If you're writing data directly into Jitsu HTTP API, you need to update the endpoint to https://legacy.d.jitsu.com/api/v1/s2s/event and change the write key(token) to the new one.

Migrate Sources​

In Jitsu 2.0, the Sources entity is replaced by:

  • the Service Connections entity which keeps the credentials for the data sources
  • the Sync entity which works as a link between Service Connections and Destinations and defines the data import settings and stream selection.

Both entities can be found in the Connectors section of the Jitsu 2.0 main menu.

Make sure that events are flowing​

In Jitsu 2.0 you can check the event flow in the Data -> Live Events section of the main menu. There you can find 3 tabs:

  • Incoming Events - see the incoming events by Sites
  • API Destinations & Functions Logs - logs of API Based Destinations and Functions
  • Batches & Data Warehouse Events - logs of Data Warehouse and Batch Destinations

To check how migrated Sources are running you can use the Connectors -> Syncs or Connectors -> All Logs sections of the main menu.