# 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](https://tray.ai/documentation/developer/connector-development-kit/overview/quickstarts/token-raw-http) 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.

> **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:

```json
\{
  "@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.

```typescript
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:

```typescript
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()
      )
  )
);
```

> **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`.

```typescript
export type PdfProcessorAuth = any; // No Authentication
```

## 3. Deploy the connector

***

Now your connector is ready to be deployed again. Please check [deployment guide](https://tray.ai/documentation/developer/connector-development-kit/overview/quickstarts/token-raw-http#deploy-the-connector) 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.

> **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.**&#x20;