Documentation

Overview

Learn about the concepts and terminology of commercetools Connect.

What is commercetools Connect

commercetools Connect lets you add functionality to your Composable Commerce Project without needing to buy and maintain dedicated hosting or runtime environments.

commercetools 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 Composable Commerce Projects using the Connect API or the Merchant Center.

Example use case for commercetools Connect

A Composable Commerce customer has hired a software development company to add the following functionality to their Composable Commerce Project:

  • Validating the contents of carts.
  • Sending order confirmation emails.
  • Running daily maintenance, updates, or syncs with external systems.
  • Extending the Merchant Center to manage the order confirmation emails.

To do this, the Composable Commerce customer and software development company would usually need to develop and maintain separate systems/hosting for this functionality.

Who is commercetools Connect for

commercetools Connect provides advantages to creators (application developers) and clients (Composable Commerce customers).

Creators can develop public or private applications using JavaScript/TypeScript or Java, and enjoy a simplified development and publishing process.

Clients can deploy applications without needing to manage hosting or runtime environments.

In the example use case, the software development company would be the creator and the Composable Commerce customer would be the client.

The commercetools Connect workflow

The following steps outline how creators and clients use commercetools Connect.

Using the Connect API

  1. Creators develop Connect applications and store them in a GitHub repository.
  2. Creators use the Connect API to create a ConnectorStaged that references this GitHub repository.
  3. Creators publish their ConnectorStaged. Once published, the ConnectorStaged creates/updates a Connector.
  4. Clients use the Connect API to create a Deployment that includes a reference to this Connector. The Connector is now deployed to the client's Composable Commerce Project.

Using the Merchant Center

  1. Creators develop Connect applications and store them in a GitHub repository.
  2. Clients create and publish a Connector that references this GitHub repository.
  3. Clients install the Connector. The Connector is now deployed to the client's Composable Commerce Project.

In the example use case, the software development company would develop four Connect applications (one for each function), save their code to a GitHub repository, and use the Connect API to create and publish a ConnectorStaged.

The Composable Commerce customer would then use the Connect API to deploy the resulting Connector to their Composable Commerce Project.

Connect applications

Connect applications are the applications that commercetools Connect hosts and runs. You can create Connect applications using JavaScript/TypeScript or Java. 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:

  • Service: perform specific actions using API Extensions or webhooks to other systems.
  • Event: receive events and perform actions asynchronously using Subscriptions.
  • Job: perform tasks on a regular basis. You can schedule job applications using cron expressions.
  • merchant-center-custom-application: create Custom Applications to extend the functionality of the Merchant Center.
  • Assets: host static assets with CDN capabilities.

In the example use case, these application types would be suited for the following functions:

  • A service application to validate the contents of carts.
  • An event application to send order confirmation emails.
  • A job application to run daily maintenance, updates, or syncs with external systems.
  • An merchant-center-custom-application application to provide a frontend for modifying the emails sent by the event application.
  • An assets application to host static assets used by the other applications.

For more information, see Developing Connect applications.

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, which details the configuration of the Connect applications. You can view the example structure of a GitHub repository in the Connect Application Starter in JavaScript.

Connectors

The Connect API uses Connectors to prepare your Connect applications for deployment. Connectors include a reference to the GitHub repository which contains the source code of Connect applications, and application configuration details needed to configure deployments, such as 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 deployable Connector.

In the Merchant Center, your Connectors are referred to as Organization Connectors.

Certification process

The certification process verifies the functionality, security, and stability of Connect applications. Connectors must be certified to be publicly available on the Connect marketplace. Certification is not required for private Connectors. For more information about the certification process, see Certification.

Deployments

Deployments represent how clients integrate Connect applications into their Composable Commerce 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.

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

Deployment information and limitations

When deployed, Connect applications have the following behavior based on their application type.

service

  • Uses HTTP-based exposed endpoints.
  • The server will timeout after 5 minutes.
  • Will autoscale based on the number of requests.

event

  • Uses a message broker service.
  • The event acknowledgment timeout is 10 seconds.
  • The server will timeout after 5 minutes.
  • The delivery promise is at-least-once delivery with no ordering guarantees.
  • The message queue discards a message from a Subscription as soon as the message is acknowledged.
    • Unacknowledged messages are retained for 7 days.
  • The message queue will retry the message if the application responds with any other response code than 102, 200, 201, 202, or 204.
    • Push backoff applies if the application responds with too many negative acknowledgments.
  • Will autoscale based on the number of events being processed.

job

  • Uses a cron-based scheduler service.
  • The server will timeout after 30 minutes.

merchant-center-custom-application

  • Is a hosted React application.
  • The server will timeout after 5 minutes.
  • Will autoscale based on the number of requests.

assets

  • Hosts static assets.
  • The server will timeout after 5 minutes.
  • CDN capabilities are supported.