Anatomy of a CDK connector

This article breaks down the anatomy of a CDK connector, explaining each component in detail.

Project Structure

connector-directory

A CDK project is essentially a Node.js and TypeScript project preconfigured with necessary dependencies, linter rules, and compiler options. A connector folder contains the following key files / folders:

  • connector.json : Contains metadata about the connector, such as name, version, title, and more.
  • src directory : Houses the core logic of the connector, including authentication files, operation folders, and test context files.

Context and Authentication

  • Context (ctx) : Passed along with inputs in handlers, containing common values for all operations, primarily the auth property which typically includes tokens for third-party service authentication.
  • Authentication : Defined in auth.ts file within the src directory, specifying the type of authentication used (e.g., OAuth, API Key).

Operations

Each operation of a connector resides in its own folder under the src directory, containing:

  • operation.json : Operation metadata like name and title.
  • input.ts and output.ts : Define the input and output types for the operation.
  • handler.ts : Contains the logic of the operation.
  • handler.test.ts : Includes test cases for the operation.

Input & Output

  • Input (input.ts) : Specifies the data structure expected by an operation.
  • Output (output.ts) : Defines the data structure returned by an operation.

Handler

The handler is where the operation's functionality is implemented. It can be configured to perform HTTP requests to third-party services or composite operations that combine multiple steps.

HTTP Implementation

  • Configures HTTP requests, including method, headers, body, and response handling.
  • Utilizes the handleRequest and handleResponse methods to customize request preparation and response parsing.

Composite Implementation

  • Defines operations that combine multiple steps or invoke other operations.
  • Uses the invoke function to call other operations within the handler.

Testing

  • handler.test.ts : Contains test cases to verify the operation's behavior.
  • Utilizes the CDK's testing framework to simulate operation execution and validate outcomes.

Deployment

Once developed and tested, the connector can be deployed to the Tray platform, making it available for use in workflows.

Next Steps

If you have followed the introduction to install CDK CLI and initialize a connector project, you can follow the quickstart to build / deploy a connector.