Learn how to create and structure Connect applications. Connect applications are the applications that are hosted and run by Connect once their associated [Connector](https://docs.commercetools.com/connect/connectors) has been published. Connect applications can be developed using JavaScript/TypeScript or Java. Follow this guide to learn how to structure your Connect application for use in a Connector. Links to starter templates are also provided. # Requirements Developing Connect applications requires a Project and a GitHub account. The following requirements are based on whether you are developing Connect applications using JavaScript/TypeScript or Java. ## JavaScript/TypeScript - Node v16.x LTS (or later) - npm or Yarn ## Java - Java v11 LTS (or later - v17 LTS is preferred) - Maven - Knowledge of the [Spring Boot](https://spring.io/projects/spring-boot) framework It is currently recommended to create Connect applications using JavaScript or TypeScript. For more information about creating Connect applications with Java, contact the [commercetools support team](https://support.commercetools.com/). # Use a template You can develop Connect applications with ease using one of the starter or application templates. [Starter templates](https://github.com/commercetools/connect-application-kit/tree/main/application-templates) provide boilerplate code and folder structures for creating generic Connect applications. To create applications for dedicated use cases, you can use the application templates. - Starter templates: To use a starter template, do the following: 1. Install the Create Connect App. ```shell npm install --global @commercetools-connect/create-connect-app ``` 2. Install a template for JavaScript or TypeScript. ```sh create-connect-app first-connect-application --template javascript ``` ```sh create-connect-app first-connect-application --template typescript ``` - Application templates: For more information our application templates, and their use cases, see the following: - [Sending transactional emails](https://docs.commercetools.com/connect/templates/transactional-emails) - [Exporting Products](https://docs.commercetools.com/connect/templates/product-export) - [Integrating payment service providers](https://docs.commercetools.com/connect/templates/payment-integration) - [Integrating tax services](https://docs.commercetools.com/connect/templates/tax-integration) # Use the correct directory structure You should structure your Connect application as in the following example. The following directory structure is reflected in the starter templates. ``` ├── < docs > │ └── readme.md ├── < event > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json ├── < job > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json ├── < service > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json ├── < merchant-center-custom-application > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json ├── < merchant-center-custom-view > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json ├── < assets > │ ├── src │ ├── tests │ ├── package-lock.json │ └── package.json └── connect.yaml ``` The folders `event`, `job`, `service`, `merchant-center-custom-application`, `merchant-center-custom-view`, and `assets` represent the possible [Connect application types](https://docs.commercetools.com/connect/overview#connect-applications) that can be run in your Connector. You can remove folders of applications you do not want to develop, or you can rename them to reflect the Connect application's purpose. A Connector can have one or more Connect applications of the same type. You must specify the deployment information of your Connect applications in `connect.yaml`. This file contains information that is required to create, publish, and deploy Connect applications. # Configure connect.yaml `connect.yaml` is located in the root of the Connect application and contains the necessary configuration, scripts, and environment variables for it to operate. The following example `connect.yaml` file is found in the starter template. ```yaml deployAs: - name: service applicationType: service endpoint: /service scripts: postDeploy: npm install && npm run connector:post-deploy preUndeploy: npm install && 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' - key: CTP_REGION description: Region where the Composable Commerce Project is hosted required: true securedConfiguration: - key: CTP_CLIENT_ID description: client_id of an API Client for the Composable Commerce Project required: true - key: CTP_CLIENT_SECRET description: secret of an API Client for the Composable Commerce Project required: true - key: CTP_SCOPE description: scope of an API Client for the Composable Commerce Project - name: job applicationType: job endpoint: /job properties: schedule: '*/5 * * * *' configuration: standardConfiguration: - key: CTP_PROJECT_KEY description: Project key of the Composable Commerce Project required: true default: 'default-key' - key: CTP_REGION description: Region where the Composable Commerce Project is hosted required: true securedConfiguration: - key: CTP_CLIENT_ID description: client_id of an API Client for the Composable Commerce Project required: true - key: CTP_CLIENT_SECRET description: secret of an API Client for the Composable Commerce Project required: true - key: CTP_SCOPE description: scope of an API Client for the Composable Commerce Project - name: event applicationType: event endpoint: /event scripts: postDeploy: npm install && npm run connector:post-deploy preUndeploy: npm install && npm run connector:pre-undeploy configuration: standardConfiguration: - key: CTP_PROJECT_KEY description: Project key of the Composable Commerce Project required: true default: 'default-key' - key: CTP_REGION description: Region where the Composable Commerce Project is hosted required: true securedConfiguration: - key: CTP_CLIENT_ID description: client_id of an API Client for the Composable Commerce Project required: true - key: CTP_CLIENT_SECRET description: secret of an API Client for the Composable Commerce Project required: true - key: CTP_SCOPE description: scope of an API Client for the Composable Commerce Project - name: merchant-center-custom-application applicationType: merchant-center-custom-application configuration: standardConfiguration: - key: CUSTOM_APPLICATION_ID description: The Custom Application ID required: true - key: ENTRY_POINT_URI_PATH description: The Application entry point URI path required: true - name: merchant-center-custom-view applicationType: merchant-center-custom-view configuration: standardConfiguration: - key: CUSTOM_VIEW_ID description: The Custom View ID required: true - key: ENTRY_POINT_URI_PATH description: The Application entry point URI path required: true - name: assets applicationType: assets 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 ``` The values of `connect.yaml` are as follows: (a CSV formatted table follows. The first line are the column names.) Key,Description `name`,Identifier for the application deployment. This ID is used to fetch the output URL, topic, and schedule of the deployment. `name` should match the application folder in your repository and can be up to 256 characters long. Allowed characters include uppercase and lowercase letters (A-Z, a-z), numbers, underscores (`_`), and hyphen-minus (`-`). `applicationType`,Specifies the type of the application. Possible values are `event`, `job`, `service`, `merchant-center-custom-application`, `merchant-center-custom-view` or `assets`. `endpoint`,Deployment URL endpoint, assigned in the format: `{connect-provided-url}/{endpoint}` (for example, `https://service-XYZ.europe-west1.gcp.commercetools.app/service`). `endpoint` can optionally start with `/` and must be no longer than 256 characters. Allowed characters are uppercase and lowercase letters (A-Z, a-z), numbers, underscores (`_`), and hyphen-minus (`-`). The `endpoint` is not required if `applicationType` is `merchant-center-custom-application`, `merchant-center-custom-view` or `assets`. `configuration`,Defines both standard (`standardConfiguration`) and sensitive (`securedConfiguration`) environment variables for the Connect application. Sensitive data, such as API keys, should be defined under `securedConfiguration`. Each variable includes a `key`, `description`, and `required` field. The client defines values for these environment variables when [deploying the Connector](https://docs.commercetools.com/connect/deployments#deploymentconfigurationapplication). If the `required` field is set to `true`, the value must be provided during deployment. Default values for `standardConfiguration` fields can be specified and used if no value is provided during deployment. `configuration` is not required if `applicationType` is `assets`. `properties`,Placeholder for additional arguments for a Connector. It includes the `schedule` field for `job` applications (see below). `properties.schedule`,Specifies the default cron expression for `job` applications. This expression defines the schedule for executing the job using cron syntax (for example, `0 0 * * *` to repeat the job daily). This default can be overridden per deployment using the `schedule` field of [DeploymentConfigurationApplication](https://docs.commercetools.com/connect/deployments#deploymentconfigurationapplication). `inheritAs.configuration`,Optional. Specifies configuration settings that can be shared across all applications, such as environment variables, deployment settings, or common values used in different application types. `inheritAs.apiClient.scopes`,Optional. Specifies a list of scopes required to generate an API Client. Scopes define access permissions for an API Client and are necessary to generate client credentials that are authorized to interact with specific services or APIs. `event` applications use a message broker service provisioned during deployment. Messages received by the queue are delivered to `event` applications to process. `job` applications use a scheduler service provisioned during deployment. The scheduler triggers the `job` application based on the cron expression defined in `properties.schedule`. You can override this schedule for a specific deployment using the `schedule` field of [DeploymentConfigurationApplication](https://docs.commercetools.com/connect/deployments#deploymentconfigurationapplication). # Generate an API Client To simplify creating an API Client for interaction with the Composable Commerce API, Connect offers [automatic API Client generation](https://docs.commercetools.com/connect/modify-connector). The required scopes for the API Client credentials are defined in the `inheritAs.apiClient.scopes` field of the `connect.yaml` configuration file. These scopes are displayed to customers during installation and are used to generate API Client credentials. # Manage the application with Yarn commands Use the following Yarn commands to manage your Connect application. ## Install dependencies Dependencies are installed using Yarn Workspaces. ```bash yarn ``` ## Run tests ```bash yarn test # or yarn test:watch ``` ## Build the application ```bash yarn build # or yarn build:watch ``` ## Run the application locally ```bash yarn start # or yarn start:dev ``` # Test your Connect application It is recommended to implement unit and integration test cases as part of application development and follow a test-driven development approach. This ensures that each part of your code is tested in isolation, allowing you to verify correctness, functionality, and reliability. These test cases are reviewed and also executed during the publishing process. Scripts to run tests should be defined in a test script. You should implement robust error handling in your Connect application to manage failures and retry mechanisms for temporary issues. This is crucial for [delivery guarantees](https://docs.commercetools.com/connect/api/projects/subscriptions#delivery-guarantees) in event applications to ensure reliability and resilience when integrating with third-party services. [Connect application templates](https://github.com/commercetools/connect-application-kit/tree/main/application-templates) provide sample implementation of testing using [Jest](https://jestjs.io/). # Upload and create a release on GitHub After finishing the development of a Connect application, you should push it to a GitHub repository. The Connect application should be released on GitHub with a Git tag so that specific application releases can be referenced by the Connector. Your GitHub repository can be public or private. If you create a Connector in the [Merchant Center](https://docs.commercetools.com/connect/merchant-center/connect#create-an-organization-connector), you'll be asked to specify the GitHub repository containing your Connect applications. You can specify the GitHub repository by linking your GitHub account, or by providing the SSH URL or HTTPS URL of the repository. The HTTPS URL will work only if the repository is public. If the repository is private, you must use the SSH URL and grant read access to the [connect-mu](https://github.com/connect-mu) [machine user](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#machine-users). Always push lock files, such as `package-lock.json` or `yarn.lock`, along with Node.js applications to your GitHub repository. Otherwise, the system may install different package versions than those the application was built and tested with, causing inconsistent or failed builds. # Next steps Once your Connect application, GitHub repository, and Git tag are ready, follow our [getting started guide](https://docs.commercetools.com/connect/getting-started#create-a-connector) to create a Connector using your Connect application.