Tray.io has a huge library with hundreds of connectors for 3rd party Services.
Two general scenarios which would necessitate the use of the Tray.io 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:
- Install and run the CDK CLI (Command Line Interface)
- Create a new connector project
- Set up testing for your connector
- Run your first test
Once your set up is ready i.e. you have run your first test, you can jump to the tutorial to start development.
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 a ticket with the following details:
- Issue type: Technical support
- Subject: Requesting namespace for CDK deployment
I would like to request a namespace for CDK connector deployments across my Tray Organizations. Please call the namespace
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
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:
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:
@trayio/cdk-cli/1.3.0 darwin-arm64 node-v16.15.1
Now open a terminal window in the folder where you want to build your connector project.
For example, this could be
Then run the following command:
tray-cdk init [CONNECTOR_NAME]
Where [CONNECTOR_NAME] is the name of your connector eg.
tray-cdk init acme
We recommend doing the next steps in a terminal window within an IDE such as VS Code so you can visualize the folder structure.
cd to the newly created connector folder e.g.
This will install the project dependencies.
Tip: When intializing a project, you can simultaneously install the dependencies using the
--install flag e.g.
tray-cdk init acme -i
Each time a project is initialized a test connector with one operation is installed.
To test your setup, you can run:
You should see the following message in your terminal:
> firstname.lastname@example.org 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 tutorial on the next page.
This will guide you on how to add new operations, add test auth, test operations and finally deploy your connector.