Migration Guide

Upgrading CDK to v4

The v4 of CDK introduces two major changes. With v4, you get:

1. a global config object that gets passed to every operation of the connector
2. Raw HTTP operation

To use v4:

If you are building your first connector, update your cdk-cli using npm update -g @trayio/cdk-cli and just follow the Quickstart guide which uses CDK v4.

If you have built a connector before using v3 or lower and want to migrate the connector to v4 you will have to make a few changes to the code.

Here are the recommended steps for upgrading existing connectors:

1. Update the CLI

Update your cdk-cli using npm update -g @trayio/cdk-cli. Verify you are on 4.0.0 or higher using tray-cdk -v.

2. Update the connector

1. Run npm run build on the connector folder. This will create a GlobalConfig.ts file in src folder.
2. You will also need update the versions for @trayio/cdk-dsl and @trayio/cdk-runtime in the package.json file as shown below:

{
  "@trayio/cdk-dsl": "4.0.0",
  "@trayio/cdk-runtime": "4.0.0"
}

3. Delete the node_modules folder and package-lock.json file. Now, re-run npm i on the connector directory to install dependencies freshly.

GlobalConfig.ts

This file allows you set configs that can be used across all operations. Some things that can be initialized at the global level are:

• AuthType
• Base URL (withBaseUrl)
• Headers (withHeader)

Here is a sample where base_url and bearerToken have been initialized globally.

import { OperationGlobalConfigHttp } from "@trayio/cdk-dsl/connector/operation/OperationGlobalConfig";
import { TmdbAuth } from "./TmdbAuth";

/*
 * IMPORTANT NOTE: DO NOT DELETE THIS FILE
 * This is a global configuration that is used by all operations in the connector.
 * Update OperationGlobalConfigHttp.create<never> to use the right Auth type of the connector e.g. OperationGlobalConfigHttp.create<AuthType>
 * Update the baseUrl to the base url of the API.
 * To configure the auth use the withBearerToken method or use addHeader method to add custom headers.
 *
 * IMPORTANT NOTE: Do not change the name of the variable `globalConfigHttp` as it is used by the internal Raw Http Operation.
 * You can ignore this configuration if you have disabled the Raw Http Operation in connector.json
 */
export const globalConfigHttp = OperationGlobalConfigHttp.create<TmdbAuth>()
  .withBaseUrl((_ctx) => `https://api.themoviedb.org`)
  .withBearerToken((ctx) => ctx.auth!.user.access_token);

Update operations

Now that you have initialized the GlobalConfig.ts file, the global config can be passed to every operation using withGlobalConfiguration(globalConfigHttp). Here is a sample:

import { globalConfigHttp } from "../GlobalConfig";

export const getMoviesByGenreHandler = OperationHandlerSetup.configureHandler<
  TmdbAuth,
  GetMoviesByGenreInput,
  GetMoviesByGenreOutput
>((handler) =>
  handler.withGlobalConfiguration(globalConfigHttp).usingHttp((http) =>
    http
      .get("/3/discover/movie")
      .handleRequest((_ctx, input, request) =>
        request
          .addQueryString("with_genres", input.genre.toString())
          .withoutBody()
      )
      .handleResponse((_ctx, _input, response) =>
        response.parseWithBodyAsJson()
      )
  )
);

Update AuthType

Note: If your connector requires auth, then you don't need to make any changes. Please skip this step.

Till version 3 the default authType for a connector with no auth was never.

If your connector doesn't use an auth, it's authType should be set to any.

export type PdfProcessorAuth = any; // No Authentication

3. Deploy the connector

Now your connector is ready to be deployed again. Please check deployment guide if unsure.

4. Update the connector version in the workflows

Connector version isn't updated automatically in the workflows if you publish new versions. Your workflows NEED to be updated manually to use new version of the connector.