Learn about the concepts and terminology of Connect.
What is Connect
Connect lets you add functionality to your Project without needing to buy and maintain dedicated hosting or runtime environments.
Connect provides a runtime environment for running small applications, referred to as Connect applications. Connect applications can be developed by anyone, and they are deployed to your Project using the Connect API, Merchant Center, or CLI.
To follow the end-to-end process of creating, previewing, and deploying a Connector, see Connect workflow.
Who is Connect for
Connect serves two personas: creators and clients.
- Creators are the developers who design, build, publish, and maintain Connect applications and public or private Connectors using JavaScript/TypeScript or Java. They typically work with the Connect CLI and the ConnectorStaged resource of the Connect API.
- Clients are the commercetools customers who find, deploy, and configure published Connectors in their own Project. They do not manage any hosting or runtime environments. Clients typically work with the Merchant Center or the Connector and Deployment resources of the Connect API.
These roles describe tasks rather than people, so the same person or team can perform both. For example, when you build a Connector only for your own Projects, you take on both roles. You are the creator while you develop and publish it, and the client when you deploy it. The Connect workflow shows which tasks belong to each role.
Key concepts of Connect
The following sections explain the key concepts and terminology of Connect.
Connect applications
Connect applications are the applications that Connect hosts and runs. You can create Connect applications using JavaScript/TypeScript or Java. For more information, see Developing Connect applications.
The source code of Connect applications is saved in a GitHub repository, and this repository is referenced by a Connector.
Connect applications can be of the following types:
| Type | Description | Example use case |
|---|---|---|
| Service | Perform actions using API Extensions or webhooks. | Validate the contents of carts. |
| Event | Receive events and perform actions asynchronously using Subscriptions. | Send order confirmation emails. |
| Job | Perform scheduled tasks using cron expressions. | Run daily maintenance, updates, or syncs with external systems. |
| merchant-center-custom-application | Extend the Merchant Center with Custom Applications. | Provide a frontend for modifying the emails sent by the event application. |
| merchant-center-custom-view | Add custom functionality to a specific Merchant Center page using Custom Views. | Add custom functionality in the context of a specific page within a built-in Merchant Center application. |
| Assets | Host static assets with CDN capabilities. | Host static assets used by the other applications. |
For more information on how each application type behaves when deployed, see Deployment behavior and environments.
GitHub repository
The source code of Connect applications must be saved in a GitHub repository and have a Git tag that refers to a specific release.
The GitHub repository can be public or private. If the GitHub repository is private, you must grant read access to the connect-mu machine user.
The GitHub repository must have a specific structure, including a
connect.yaml file in the root. connect.yaml contains the configuration details of the Connect applications, including defining environment variables used by the applications. You can view the example structure of a GitHub repository in the Connect Application Starter in JavaScript.Connectors
Connectors prepare your Connect applications for deployment.
Connectors reference the GitHub repository containing the source code of Connect applications, and include configuration details for defining environment variables.
In the Connect API, Connectors have two representations:
- ConnectorStaged: used to create, update, and preview Connectors before submitting them for publishing.
- Connector: a read-only model that represents a published and deployable Connector.
In the Merchant Center, your Connectors are referred to as Organization Connectors.
You prepare a Connector for deployment in three stages:
- Create or update the Connector to reference your GitHub repository and Git tag.
- Request a preview build to test the Connector.
- Publish the Connector for private or public use.
For a visual overview of these stages, see Connect workflow. To follow the Connect API process, see Get started with Connect. To follow the Merchant Center process, see the Merchant Center Connect guide.
Validation pipeline
When you request a preview build or publish a Connector, Connect checks the code quality and security of your Connect applications. Connect also validates the content of the
connect.yaml file. These checks help ensure that Connect applications meet the required standards for running in a production environment.For a description of each pipeline step and how to check validation results, see Validation pipeline.
Certification process
If you are creating a Connector for private use only, then certification is not required.
Certification is only required for Connectors that you want to make publicly available on the Connect marketplace. The certification process verifies the functionality, security, and stability of Connect applications. For more information about the certification process, see Certification.
Deployments
Deployments represent how clients integrate Connect applications into their Project.
Deployments include a reference to a published Connector, and the configuration needed for the Connect applications to work, such as values for environment variables.
Connect handles provisioning the infrastructure and runtime environment for Deployments. Clients only need to use the Connect API to create the Deployment. If any of the values for application configuration change, then the client can redeploy the Deployment with new values.
Connectors that use third-party services may require that you have a commercial contract with the service provider before deploying the Connector.
Environments
The DeploymentType lets you control which type of environment your ConnectorStaged or Connector is deployed to. Connect provides three environments:
sandbox for development and QA, preview for testing a ConnectorStaged during development, and production for deployment to non-trial Projects.For the behavior and requirements of each environment, see Deployment behavior and environments.