CDK (Connector Development Kit)

info

If you know your way around CDK already, you can jump to the CLI and DSL references directly:

Make sure you check out the sample connectors repo which covers a variety of examples / use cases.

Tray has a huge library with hundreds of connectors for 3rd party Services.

Two general scenarios which would necessitate the use of the Tray CDK are:

  • You are looking to integrate with a 3rd party service and Tray does not have an existing connector for the service.
  • You are looking for some API operations which aren't yet covered in an existing connector.

Tray's Connector Development Kit allows you to build a connector for any 3rd party service.

In this guide, we'll show you how to:

  1. Install and run the CDK CLI (Command Line Interface)
  2. Obtain your organisations namespace
  3. Create a new connector project
  4. Set up testing for your connector
  5. Run your first test

Once your set up is ready i.e. you have run your first test, you can jump to the quickstart to start development.

Prerequisites

Languages / environments

info

You are not required to be a Typescript expert to build a connector.

Knowledge of Javascript with a basic understanding of Types is sufficient. Here are some resources to get you started:

Install CDK CLI

Open a terminal window and:

npm install -g @trayio/cdk-cli

This will install the CDK CLI globally on your machine.

'Globally' means the CDK commands can be used from a terminal window on any folder.

Test the installation of CDK using:

tray-cdk version

This will show the CDK CLI version that's installed along with your system architecture and node version you are using.

So, depending on your version, something like the following:

Copy
Copied
@trayio/cdk-cli/3.0.0 darwin-arm64 node-v20.9.0

Create or retrieve your organisation namespace

Before deploying a connector to Tray platform, you will need to obtain your organisational 'namespace'.

To create a namespace for your organisation use the following:

tray-cdk namespace create ORGID NAMESPACE [--us] [--eu] [--ap]

To retrieve a namespace for your organisation the following:

tray-cdk namespace create ORGID NAMESPACE [--us] [--eu] [--ap]

Where [ORGID] is the UUID of your organisation, which can be found in the tray app URL eg. https://app.tray.io/workspaces/[UUID]

When creating a namespace we recommend:

  • Associating with your company’s legal entity or brand name
  • Choose a shorter name over a longer one
  • Hyphens are supported, numbers and other symbols are not supported
  • For example enter-company-name
info

Each Tray organisation is limited to one namespace. However, you can use the same namespace across multiple organisations owned by use (e.g. for eu or ap can share the same namespace).

Create a new Connector project

Now open a terminal window in the folder where you want to build your connector project.

For example, this could be ~/projects/tray-connectors

Initialize project

Then run the following command:

tray-cdk connector init [CONNECTOR_NAME]

Where [CONNECTOR_NAME] is the name of your connector eg. tray-cdk connector init acme

info

We recommend doing the next steps in a terminal window within an IDE such as VS Code so you can visualize the folder structure.

Install dependencies

cd to the newly created connector folder e.g. cd acme

Now run:

npm i

This will install the project dependencies.

info

Tip: When intializing a project, you can simultaneously install the dependencies using the -i or --install flag e.g. tray-cdk connector init acme -i

Test your installation

Each time a project is initialized a test connector with one operation is installed.

To test your setup, you can run:

npm test

You should see the following message in your terminal:

Copy
Copied
> acme@1.0.0 test
> jest --config ./jest.config.js

 PASS  src/get_product/handler.test.ts
  Operation get_product Test
    ✓ should get a product (353 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.316 s
Ran all test suites.

Now you can continue to the quickstart on the next page.

This will guide you on how to add new operations, add test auth, test operations and finally deploy your connector.