Rollout v1 and Rollout v2 share most of the same fundamental concepts.

In both versions, Rollout partners create Connectors to their apps and define the Triggers and Actions they wish to expose. Rollout's UI components enable the users of a partner's app to create Automations which can perform an operation (Action) in the partner's app when an event (Trigger) occurs in another app or vice versa.

The primary difference between Rollout v1 and Rollout v2 is the way in which partners create and manage their Connectors.

In v1, partners define their Connector's Auth, Triggers, Actions, and Queries through the Rollout dashboard either by specifying HTTP requests via the UI, or by switching to "Code Mode" and writing Javascript.

In v2, partners define their Connector's Auth, Triggers, Actions and HTTP endpoints (which replace Queries) in a Typescript Rollout Project which offers many advantages over the v1 approach, including:

• Code can be shared between the Connector's various parts, rather than requiring duplication.
• Rollout Projects can be deployed to different Project Environments, enabling partners to easily test changes to their Connectors before rolling out to live users.
• Partners can extend the functionality of Rollout's pre-built Connectors to fit custom or advanced usee cases by, for example, adding additional Triggers and Actions.
• Partners can define their own Connectors to third-party apps that Rollout may not yet support, allowing them to leverage Rollout's platform for these integrations.

The rest of this page discusses how to migrate an existing Rollout v1 implementation to Rollout v2.

Requesting an account#

If you'd like to migrate from Rollout v1 to Rollout v2, please reach out to [email protected]. We will provide you with an account to the new Rollout dashboard.

Authenticating with Rollout#

Authentication for the Rollout UI components and API remain largely unchanged in v2. As in v1, you will generate a JWT whose sub claim is a unique identifier for the user, team, or organization who is creating Automations in Rollout.

The differences between v1 and v2 are as follows:

• The iss claim, which previously was your Rollout clientId, is now any arbitrary identifier of your choosing. You could consider using e.g. your domain. This is a required JWT claim, but Rollout does not enforce its value.
• You will sign the JWT with a new "Consumer Token Signing Secret", which is unique to a given Project Environment. You can find your new signing secret in the "API" tab of a given Project Environment.
• JWT claims custom to Rollout are nested under a rollout.com claim rather than a rollouthq.com claim.
• Since there is no longer a concept of "publishing" or "unpublishing" Triggers and Actions, there is no analogous claim to rollouthq.com.dev.

UI Components#

The UI components expose almost exactly the same API in v2 as they did in v1. For compatibility with v2, however, you will need to install the latest version of the Rollout components which are now published under the rollout npm organization rather than the rollouthq organization. See the docs on component installation for more details.

API Requests#

The same API endpoints exist in Rollout v2, but rather than making those requests against a central Rollout server, you will now make requests to a specific Project Environment. This means that the base url for API request endpoints will now be https://<project-env-key>.rolloutapp.com/api.

You can find documentation for your Project Environment's API at https://<project-env-key>.rolloutapp.com/api-docs.

Migrating Auth#

It may be helpful to have the Rollout Project Template cloned locally so that you can more easily see where to add the code described in this section and below.

The specification for how to authenticate with your app's API is now defined in the auth.ts file in the directory of your Rollout Project containing your app's Connector.

You can find the auth v1 auth type you're using by navigating to the Authentication page of the v1 dashboard.

• If you're using the "OAuth" auth type in v1, you will want to use the defineOauth2 function in auth.ts.
• If you're using the "API Key" auth type in v1, you'll want to us the defineApiTokenAuth function.
• If yo're using the "Custom" type, you'll want to use defineJWTAuth. You can find more information on auth in v2 here.

Migrating Triggers#

When defining a Trigger in v1, each of the following is defined in the dashboard:

• The Trigger's key and name.
• The inputParams for filtering trigger events
• The Trigger's payload schema, which specifies the values returned that users can that map to Action inputParams
• The "API Configuration" which describes how to e.g. subscribe and unsubscribe from webhooks or how to poll your app's API

In v2, each of these elements is defined in code:

• The key and name are defined in code
• inputParams are defined in a schema in the input.ts file. Additionally in v2, you specify how users provide values for inputs in the ui.tsx file by binding inputs to UI Components.
• The payload schema is defined in the payload.ts file.
• The "API Configuration" logic now lives in the trigger.ts file. The same Trigger types exist in v1 and v2, but you will now use function like defineWebhookTrigger and definePushTrigger in place of the dashboard.

One thing to note is that there is no longer a direct equivalent to defining HTTP requests in "UI Mode". If you are using "UI Mode" in v1, the simplest solution is to instead define requests with the native node fetch module or other HTTP request clients like axios.

Migrating Actions#

When defining a Action in v1, each of the following is defined in the dashboard:

• The key and name are defined in code.
• The Action's key and name.
• The inputParams for configuring the Action's behavior.
• The "API Configuration" which describes how the Action performs its operation, e.g. by making a request to your API

In v2, each of these elements is defined in code:

• inputParams are defined in a schema in the input.ts file. Additionally in v2, you specify how users provide values for inputs in the ui.tsx file by binding inputs to UI Components.
• The "API Configuration" logic now lives in the action.ts file.

One thing to note is that there is no longer a direct equivalent to defining HTTP requests in "UI Mode". If you are using "UI Mode" in v1, the simplest solution is to instead define requests with the native node fetch module or other popular HTTP request clients like axios.

Replacing Queries with HTTP Endpoints#

Your Rollout v2 Connector can handle HTTP requests. One use case for this functionality is to replace the "Queries" used to populate dropdowns in v1. You can implement routes corresponding to your queries and then make requests from the ui.tsx files of your Triggers and Actions.

Migrating Data#

To migrate v1 Credentials and Automations to v2, you'll need to schedule a time with us by reaching out to [email protected] or over Slack. We will coordinate on moving your data over with no downtime for your users.