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.

info

Upgrading you existing CDK connectors to use v4 is not a breaking change. But it is recommended as we will be relying more and more on Global Config to introduce new features into CDK.

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:
Copy
Copied
{
  "@trayio/cdk-dsl": "4.0.0",
  "@trayio/cdk-runtime": "4.0.0"
}
  1. 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.

Copy
Copied
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:

Copy
Copied
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()
      )
  )
);
info

Using the global config in every Operation is not mandatory. It's up to you to decide which Operations would need the global config.

You can always override the Global Configs at an operation level. E.g. passing a different value for a custom header (using withHeader) at the operation level than what was passed at the global level.

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.

Copy
Copied
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.

info

Updating the version may break your workflows. Please fix the errors on the properties panel if you see any as a result of updating the version.