This step-by-step guide explains how to convert an existing integration into a Connector. It outlines the modifications needed to ensure that the project aligns with the new Connector requirements. The guide covers various aspects such as the Connector specification file (`connect.yaml`), determining the appropriate application type, implementing the proper folder structure, and constructing the necessary automation scripts for managing extensions and subscriptions. # Configure connect.yaml To convert an existing repository to a valid Connector you must create and configure a `connect.yaml` file. `connect.yaml` is required and is the starting point of each Connector repository. `connect.yaml` contains the descriptions and configurations of each application to be deployed, and is used to publish and deploy the Connector. ## Example connect.yaml file You can use the following example `connect.yaml` file as a reference to create your own. ```yaml title="Example connect.yaml file" deployAs: - name: service_app_name applicationType: service endpoint: /service scripts: postDeploy: npm run connector:post-deploy preUndeploy: npm run connector:pre-undeploy configuration: standardConfiguration: - key: CTP_PROJECT_KEY description: Project key of the commercetools Composable Commerce Project required: true default: 'default-key' securedConfiguration: - key: CTP_CLIENT_ID description: client_id of an API Client for the commercetools Composable Commerce Project required: true - name: job_app_name applicationType: job endpoint: /job properties: schedule: '*/5 * * * *' configuration: standardConfiguration: - key: CTP_PROJECT_KEY description: Project key of the commercetools Composable Commerce Project required: true securedConfiguration: - key: CTP_CLIENT_ID description: client_id of an API Client for the commercetools Composable Commerce Project required: true inheritAs: configuration: securedConfiguration: - key: GLOBAL_SECURED_CONFIGURATION description: Secured configuration that is applied to all applications required: true standardConfiguration: - key: GLOBAL_STANDARD_CONFIGURATION description: Standard configuration that is applied to all applications required: true ``` See the following table for explanations of each attribute. (a CSV formatted table follows. The first line are the column names.) Key,Required,Description `deployAs`,Yes,A root key of the file containing an array of the applications that we want to deploy in our Connector. In this file example, two applications named `service_app_name ` and `job_app_name` are deployed. The name must match the folder for the application in your repository. `name`,Yes,Identifier of the application deployment. This is important as the deployment's output URL, topic, and schedule are fetched based on this reference. `name` has a maximum length of 256 characters and can only contain the letters A to Z in lowercase or uppercase, numbers, underscores (`_`), and the hyphen-minus (`-`). `applicationType`,Yes,The type of application to deploy. Connectors currently support the following application types: `service`, `event`, `job`, `merchant-center-custom-application`, `merchant-center-custom-view`, and `assets`. `endpoint`,Yes (service, job, event applications),The `endpoint` naming used by the Deployment URL. The URL is constructed using the format `{connect-provided-url}/{endpoint}` (for example: `https://service-11111111-1111-1111-1111-111111111111.europe-west1.gcp.commercetools.app/service`) `endpoint` can optionally start with `/` and has a maximum length of 256 characters containing the letters A to Z in lowercase or uppercase, numbers, underscores (`_`), and the hyphen-minus (`-`). `endpoint` is not required if the `applicationType` is `merchant-center-custom-application`, `merchant-center-custom-view` or `assets`. `properties.schedule`,Yes (job type applications),Specifies the default cron expression for `job` applications. This expression defines the default schedule for executing the job. This default can be overridden per deployment using the `schedule` field of [DeploymentConfigurationApplication](https://docs.commercetools.com/connect/deployments.md#deploymentconfigurationapplication). `scripts`,No,Displays the configuration for the Connector's scripts. You will need this field if you need to create and use commercetools API Extensions and Subscriptions. `configuration`,No,An object of configurations to be used in the Connector as schema validation. This is an array containing `standardConfiguration` and `securedConfiguration`. `inheritAs`,No,A root key of the file that is optional and contains configurations that are shared with all applications. After gaining an understanding of the required application types for the Connector and creating `connect.yaml`, it is essential to adhere to a project structure that aligns with it. # Structure your project In the context of Connect, each application is treated independently and it is necessary to isolate each application in a separate folder, as each one will be provisioned in a slightly different manner based on its application type. Each folder must contain the value specified in the `name` attribute. Using the previous `connect.yaml` example, we should have the following directory structure: ```yaml myconnector/ ├── service_app_name/ │ └──src │ └── index.js │ ├── package-lock.json │ └── package.json ├── job_app_name/ │ └──src │ └── index.js │ ├── package-lock.json │ └── package.json └── connect.yaml ``` # Choose an application type Connect supports the following types of applications: - `service`: perform specific actions using [API Extensions](https://docs.commercetools.com/api/projects/api-extensions.md) or webhooks to other systems. A possible use case is to validate newly created resources, calculate custom shipping costs for a cart, and add mandatory items. - `event`: receive events and perform actions asynchronously using [Subscriptions](https://docs.commercetools.com/api/projects/subscriptions.md). You can use event applications to notify your customers after a successful payment or if a product is back in stock. - `job`: schedule tasks using cron expressions to run job applications on a periodic basis, such as updating a resource every minute, generating a nightly report, or sending an automated weekly email newsletter. - `merchant-center-custom-application`: create [Custom Applications](https://docs.commercetools.com/merchant-center-customizations/overview.md) to extend the functionality of the Merchant Center. - `merchant-center-custom-view`: create [Custom Views](https://docs.commercetools.com/merchant-center-customizations/overview.md) to extend the functionality of the Merchant Center. - `assets`: host static assets with CDN capabilities. # Implement Connect applications Every application receives the necessary configuration as defined in `connect.yaml`, which is provided through environment variables. Additionally, each Connect application must ensure that it exposes an HTTP server at 8080, encompassing all the required integration endpoints, as in the following examples: ## Service ```typescript import express, { Request, Response } from 'express'; import bodyParser from 'body-parser'; const app = express(); app.use(bodyParser.json()); app.use(bodyParser.urlencoded({ extended: true })); app.post('/service', async (req: Request, res: Response) => { const action = req.body; console.info('New action received', action); // handle business logic const additionalActions = []; // build additional resource update action res.status(200).json({ actions: additionalActions }); }); ``` ## Event ```typescript import express, { Request, Response } from 'express'; import bodyParser from 'body-parser'; const app = express(); app.use(bodyParser.json()); app.use(bodyParser.urlencoded({ extended: true })); app.post('/event', async (req: Request, res: Response) => { const event = req.body; console.info('New event received', event); // handle business logic // ex: notify user product back in stock res.status(200).send(); }); ``` ## Job ```typescript import express, { Request, Response } from 'express'; import bodyParser from 'body-parser'; const app = express(); app.post('/job', async (req: Request, res: Response) => { const event = req.body; console.info('New event received', event); // handle business logic // ex: build report, send email res.status(200).send(); }); ``` ## package.json You must include the following scripts in package.json. (a CSV formatted table follows. The first line are the column names.) Name,Description `gcp-build`,Automates the build process of the project to generate production-ready code. `start`,The entry point of the application, responsible for initializing the server listening on port 8080. ```json "scripts": { "gcp-build": "tsc", "start": "node build/index.js" } ``` ## Add automation scripts For automating configurations, for example, for Subscriptions or for creating Custom Types, see [Adding automation scripts](https://docs.commercetools.com/connect/automation-scripts.md). # Test your Connect application It is mandatory to include tests for your Connect application. This is to ensure that your application codebase has a good level of quality to guarantee proper functionality and maintainability. We recommend using a tool like [Jest](https://github.com/jestjs/jest), which allows you to use multiple useful assertions and mocks, and gather code coverage. ```js // isInteger.js const isInteger = (value) => !isNaN(parseInt(value, 10)); export { isInteger }; ``` ```js // __tests__/isInteger.spec.js import { isInteger } from './isInteger'; describe('isInteger function', () => { test('it should check if value is an integer number', () => { expect(isInteger(-1)).toEqual(true); expect(isInteger(0)).toEqual(true); expect(isInteger(1).toEqual(true)); expect(isInteger(1.5).toEqual(false)); }); }); ``` ```shell npm test PASS __tests__/isInteger.spec.js isInteger function ✓ it should check if value is an integer number (2ms) Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total Time: 0.764s, estimated 1s ```