Develop a Connect application

Learn how to create and structure Connect applications.

Connect applications are the applications that are hosted and run by Connect once their associated Connector 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 commercetools Project and a GitHub account. You can develop Connect applications using JavaScript/TypeScript or Java. See Supported runtimes for more information.

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.

Use a template

You can develop Connect applications with ease using one of the starter or application templates. Starter 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.
  npm install --global @commercetools-connect/create-connect-app
2. Install a template for JavaScript or TypeScript.
  create-connect-app first-connect-application --template javascript
  create-connect-app first-connect-application --template typescript
Application templates: For more information our application templates, and their use cases, see the following:

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

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 Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Project
  - name: job
    applicationType: job
    endpoint: /job
    properties:
      schedule: '*/5 * * * *'
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools 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 commercetools Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools 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:

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. 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`.
`healthCheck`	Optional. Configures an HTTP health check for `service` and `event` applications, used by Connect to monitor the application's availability. See Health checks below.
`retryPolicy`	Optional. Configures how failed event deliveries are retried for `event` applications. See Retry policy below.
`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.
`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.

Health checks

healthCheck lets service and event applications expose an HTTP endpoint that Connect calls periodically to verify the application is running correctly.

healthCheck is only valid for service and event applications. Configuring it for job, assets, merchant-center-custom-application, or merchant-center-custom-view applications causes the Connector's specification file to fail validation.

Your application must implement an HTTP handler that responds to GET requests at healthCheck.path; Connect does not provide this handler for you. service and event applications run on either AWS or GCP depending on the deployment's host region, and each platform defines its own success criteria for the check:

On GCP, any 2xx or 3xx response marks the check successful; any other response, a timeout, or a connection failure marks it failed. For details, see Configure container health checks for services in the Google Cloud documentation.
On AWS, the check similarly sends an HTTP request to the path at the configured interval. For details, see Configuring health checks for your service in the AWS documentation.

The values of healthCheck are as follows:

Key	Description
`healthCheck.path`	Required. The path Connect calls to check the application's health (for example, `/health`). Follows the same character rules as `endpoint`: up to 256 characters, letters, numbers, underscores, hyphens, and forward slashes for nested segments (for example, `/health/readiness`), and must not contain `//`.
`healthCheck.intervalSeconds`	Optional. How often, in seconds, Connect calls the health-check path. Must be an integer between `1` and `20`. If omitted, the hosting platform's default applies: `5` on AWS, `10` on GCP.
`healthCheck.timeoutSeconds`	Optional. How long, in seconds, Connect waits for a response before considering the call failed. Must be an integer between `1` and `20`. If omitted, the hosting platform's default applies: `2` on AWS, `1` on GCP.
`healthCheck.unhealthyThreshold`	Optional. The number of consecutive failed health checks before Connect considers the application unhealthy. Must be an integer between `1` and `20`. If omitted, the hosting platform's default applies: `5` on AWS, `3` on GCP.

If healthCheck is not configured, Connect still applies its own default monitoring for the application's availability.

deployAs:
  - name: service
    applicationType: service
    endpoint: /service
    healthCheck:
      path: /health
      intervalSeconds: 10
      timeoutSeconds: 5
      unhealthyThreshold: 3

Retry policy

retryPolicy lets event applications configure how Connect retries a failed event delivery before considering the delivery failed.

The following strategies are available:

Immediate: Connect attempts redelivery as soon as possible, without configuring a backoff delay.
Exponential backoff: Connect increases the delay between delivery attempts, starting at minBackoffSeconds and increasing to maxBackoffSeconds. If maxAttempts is configured, Connect stops retrying after that number of attempts and considers the delivery failed.

The following table describes the available configuration fields:

Key	Description
`retryPolicy.strategy`	Required. The retry strategy: `immediate` or `exponential-backoff`.

For exponential-backoff, the following fields are relevant:

Key	Description
`retryPolicy.minBackoffSeconds`	Required. The minimum delay, in seconds, before the first retry. Must be an integer between `1` and `600`, inclusive, and must be less than or equal to `maxBackoffSeconds`.
`retryPolicy.maxBackoffSeconds`	Required. The maximum delay, in seconds, that the delay between retries grows to. Must be an integer between `1` and `600`, inclusive.
`retryPolicy.maxAttempts`	Optional. The maximum number of delivery attempts before the delivery is considered failed. Must be an integer between `5` and `100`, inclusive. Defaults to 100 for AWS regions and unlimited for GCP regions.

You can override the retry policy for a specific deployment using the retryPolicy field of DeploymentConfigurationApplication. The deployment-level configuration takes precedence over the value defined in connect.yaml, which in turn takes precedence over the Connect defaults.

If no retry policy is specified, Connect applies its default exponential backoff policy with:

minBackoffSeconds: 10
maxBackoffSeconds: 120
maxAttempts: 10

Retry behavior also depends on the region where the Connector is deployed:

AWS regions: Total retry time is limited to 3,600 seconds. If the configured retry policy would take longer, for example maxAttempts: 100 with maxBackoffSeconds: 600, Connect discards the event when the time limit expires.
GCP regions: If the maxAttempts field is not set, Connect keeps retrying with backoff for up to 7 days before discarding the event. With the immediate strategy, redelivery continues without backoff for up to 7 days.

Because retry behavior can differ between cloud providers, use exponential-backoff when you need more consistent behavior across regions. Connect does not keep discarded events, so make sure your application handles failures that outlast the retry window.

deployAs:
  - name: event
    applicationType: event
    endpoint: /event
    retryPolicy:
      strategy: exponential-backoff
      minBackoffSeconds: 10
      maxBackoffSeconds: 120
      maxAttempts: 10

Generate an API Client

To simplify creating an API Client for interaction with the commercetools API, Connect offers automatic API Client generation. 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.

yarn

Run tests

yarn test

# or
yarn test:watch

Build the application

yarn build

# or
yarn build:watch

Run the application locally

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 in event applications to ensure reliability and resilience when integrating with third-party services. You can also configure how Connect itself retries failed deliveries to an event application using a retry policy.

Connect application templates provide sample implementation of testing using Jest.

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, 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 machine user.

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 to create a Connector using your Connect application.

Develop a Connect application

Requirements.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use a template.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use the correct directory structure.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configure connect.yaml.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Health checks.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Retry policy.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Generate an API Client.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Manage the application with Yarn commands.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Install dependencies.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Run tests.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Build the application.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Run the application locally.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test your Connect application.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Upload and create a release on GitHub.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Next steps.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}