CDK (Connector Development Kit)

info

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

Make sure you check out the sample connectors repo here 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. Create a new connector project
  3. Set up testing for your connector
  4. 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

Request a namespace

Before deploying a connector, you will need to request a 'namespace'.

By default, connectors created and deployed through the CDK can only be hosted in a single region.

In order to share connectors between different Tray organizations (i.e. across regions) you must submit a Tray support ticket from within the app to request a namespace:

submit-ticket

Submit a ticket with the following details:

  • Issue type: Technical support
  • Subject: Requesting namespace for CDK deployment
  • Description: I would like to request a namespace for CDK connector deployments across my Tray Organizations. Please call the namespace enter-name-here
  • Best practices for choosing the name of your namespace:
    • Associate with your company's legal entity or brand name
    • Choose a shorter name over a longer one
    • Separate multiple words by dashes, not spaces or underscores
  • Priority: normal
  • Workflow / solution URL: Copy / paste the URL of the Projects page in your instance of Tray
  • Workflow environment: Select an appropriate option from the list
  • Preferred support location: Select an appropriate option from the list
info

Each Tray organisation is limited to one namespace. However, It is possible to use the same namespace across multiple organisations owned by you (e.g. your EU or AP orgs can share the same namespace.)

This policy ensures a streamlined and organised framework for your CDK deployments.

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