Developing a Connect application
Learn how to create and structure Connect applications.
What are 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 Composable Commerce 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 framework
It is currently recommended to create Connect applications using JavaScript or TypeScript. For more information about creating Connect applications with Java, contact the Connect 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:
Install the Create Connect App.
npm install --global @commercetools-connect/create-connect-appInstall a template for JavaScript or TypeScript.
create-connect-app first-connect-application --template javascriptcreate-connect-app first-connect-application --template typescriptApplication 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├── < assets >│ ├── src│ ├── tests│ ├── package-lock.json│ └── package.json└── connect.yaml
The folders event
, job
, service
, merchant-center-custom-application
, 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: serviceapplicationType: serviceendpoint: /servicescripts:postDeploy: npm install && npm run connector:post-deploypreUndeploy: npm install && npm run connector:pre-undeployconfiguration:standardConfiguration:- key: CTP_PROJECT_KEYdescription: Project key of the commercetools Composable Commerce Projectrequired: truedefault: 'default-key'- key: CTP_REGIONdescription: Region where the Composable Commerce Project is hostedrequired: truesecuredConfiguration:- key: CTP_CLIENT_IDdescription: client_id of an API Client for the Composable Commerce Projectrequired: true- key: CTP_CLIENT_SECRETdescription: secret of an API Client for the Composable Commerce Projectrequired: true- key: CTP_SCOPEdescription: scope of an API Client for the Composable Commerce Project- name: jobapplicationType: jobendpoint: /jobproperties:schedule: '*/5 * * * *'configuration:standardConfiguration:- key: CTP_PROJECT_KEYdescription: Project key of the Composable Commerce Projectrequired: truedefault: 'default-key'- key: CTP_REGIONdescription: Region where the Composable Commerce Project is hostedrequired: truesecuredConfiguration:- key: CTP_CLIENT_IDdescription: client_id of an API Client for the Composable Commerce Projectrequired: true- key: CTP_CLIENT_SECRETdescription: secret of an API Client for the Composable Commerce Projectrequired: true- key: CTP_SCOPEdescription: scope of an API Client for the Composable Commerce Project- name: eventapplicationType: eventendpoint: /eventscripts:postDeploy: npm install && npm run connector:post-deploypreUndeploy: npm install && npm run connector:pre-undeployconfiguration:standardConfiguration:- key: CTP_PROJECT_KEYdescription: Project key of the Composable Commerce Projectrequired: truedefault: 'default-key'- key: CTP_REGIONdescription: Region where the Composable Commerce Project is hostedrequired: truesecuredConfiguration:- key: CTP_CLIENT_IDdescription: client_id of an API Client for the Composable Commerce Projectrequired: true- key: CTP_CLIENT_SECRETdescription: secret of an API Client for the Composable Commerce Projectrequired: true- key: CTP_SCOPEdescription: scope of an API Client for the Composable Commerce Project- name: merchant-center-custom-applicationapplicationType: merchant-center-custom-applicationconfiguration:standardConfiguration:- key: CUSTOM_APPLICATION_IDdescription: The Custom Application IDrequired: true- key: CLOUD_IDENTIFIERdescription: The cloud identifierdefault: 'gcp-eu'- key: ENTRY_POINT_URI_PATHdescription: The Application entry point URI pathrequired: true- name: assetsapplicationType: assets
The values of connect.yaml
are as follows.
Key | Description |
---|---|
name | Identifier of the application deployment. The Deployment's output URL, topic, and schedule are fetched based on this reference. name must match the folder for the application in your repository. 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 | Can be event , job , service , merchant-center-custom-application or assets . |
endpoint | 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 or assets . |
configuration | Defines the standard and secret environment variables needed by the Connect application. Sensitive information, such as API keys, should be defined under securedConfiguration . The client defines values for these environment variables when deploying the Connector. If required is true , a value for the environment variable must be include when deploying the Connector. You can define default values for standardConfiguration fields. These default values are used as fallback values if they are not provided when the Connector is deployed. configuration is not required for assets . |
properties | Placeholder for all additional arguments in hosting a Connector. Currently supports a schedule for job applications. |
properties.schedule | Cron expression for job applications. |
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. Scheduler services triggers the job
application based on the cron expression defined in properties.schedule
.
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# oryarn test:watch
Build the application
yarn build# oryarn build:watch
Run the application locally
yarn start# oryarn start:dev
Testing 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.
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 have a private repository, you must give access to the GitHub machine user connect-mu before you publish your Connector. After inviting connect-mu
to your repository, it might take up to an hour for the invitation to be accepted.
Push the lock files along with packages for node applications to your GitHub repository.
Next steps
Once your Connect application, GitHub repository, and Git tag are ready, you can follow our getting started guide to create a Connector using your Connect application.