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](https://docs.commercetools.com/connect/overview#connect-applications). Connect applications can be developed by anyone, and they are deployed to your Project using the Connect API, [Merchant Center](https://docs.commercetools.com/connect/merchant-center/connect), or [CLI](https://docs.commercetools.com/connect/cli).

# Who is Connect for

Connect provides advantages to creators (application developers) and clients (commercetools 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.

# Connect workflow

The following diagram and steps provide a complete overview of creating and deploying a Connector.

```mermaid
flowchart TD
	A[Create Connect applications] --> B[Save source code of Connect applications in a GitHub repository]
	B --> C[Create a release with a new Git tag]
	C --> D{Creating or updating a Connector?}
	D -->|Creating| E[Create a ConnectorStagedDraft that references the GitHub repository]
	E --> F[Post the ConnectorStagedDraft to the Create ConnectorStaged endpoint]
	D -->|Updating| G[Update the ConnectorStaged using the Set Repository update action]
	G --> H[Use the Preview Connector update action]
	F --> H[Use the Preview Connector update action]
	I -->|No| L[Fix issues in Connect applications]-->B

	subgraph Create preview build
		H --> I{Preview successful?}
		I -->|Yes| J[Create a DeploymentDraft that includes a reference to the ConnectorStaged]
		J --> K[Post the DeploymentDraft to the Create Deployment endpoint]
	end

	subgraph Create production build
		K --> M{Is the Connector intended for private or public use?}
		M -->|Private| N[Update the ConnectorStaged using the publish update action with certification set to false]
		M -->|Public| O[Update the ConnectorStaged using the publish update action with certification set to true]
		N --> P[Create a DeploymentDraft that includes a reference to the Connector]
		O --> P[Post the DeploymentDraft to the Create Deployment endpoint]
	end
```

1. Create [Connect applications](https://docs.commercetools.com/connect/overview#connect-applications) using JavaScript/TypeScript or Java.
2. Save the source code of these Connect applications in a [GitHub repository](https://docs.commercetools.com/connect/overview#github-repository).
3. When ready to test or deploy your Connect applications, [create a release in the GitHub repository](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) with a Git tag.
   - If your repository is private, you must 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).
4. [Create or update your Connector](https://docs.commercetools.com/connect/overview#create-and-update-connectors).
5. [Create and deploy a preview build](https://docs.commercetools.com/connect/overview#create-and-deploy-a-preview-build).
6. [Publish a production build](https://docs.commercetools.com/connect/overview#publish-a-production-build).

# 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](https://docs.commercetools.com/connect/supported-runtimes). For more information, see [Developing Connect applications](https://docs.commercetools.com/connect/development).

The source code of Connect applications is saved in a [GitHub repository](https://docs.commercetools.com/connect/overview#github-repository), and this repository is referenced by a [Connector](https://docs.commercetools.com/connect/overview#connectors).

Connect applications can be of the following types:

(a CSV formatted table follows. The first line are the column names.)
Type,Description,Example use case
Service,Perform actions using [API Extensions](https://docs.commercetools.com/connect/api/projects/api-extensions) or webhooks.,Validate the contents of carts.
Event,Receive events and perform actions asynchronously using [Subscriptions](https://docs.commercetools.com/connect/api/projects/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](https://docs.commercetools.com/connect/merchant-center-customizations/overview).,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](https://docs.commercetools.com/connect/merchant-center-customizations/overview).,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 types and their limitations, see [deployment information and limitations](https://docs.commercetools.com/connect/overview#deployment-information-and-limitations).

## GitHub repository

The source code of Connect applications must be saved in a GitHub repository and have a [Git tag](https://docs.github.com/en/rest/git/tags) 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](https://github.com/connect-mu) [machine user](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#machine-users).

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](https://docs.commercetools.com/connect/overview#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](https://github.com/commercetools/connect-application-kit/tree/main/application-templates/javascript).

## Connectors

Connectors prepare your [Connect applications](https://docs.commercetools.com/connect/overview#connect-applications) for deployment.

Connectors reference the [GitHub repository](https://docs.commercetools.com/connect/overview#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](https://docs.commercetools.com/connect/connectors-staged#connectorstaged): used to create, update, and preview Connectors before submitting them for publishing.
- [Connector](https://docs.commercetools.com/connect/connectors#connector): a read-only model that represents a published and deployable Connector.

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

### Create and update Connectors

Depending on if you are using the Connect API or Merchant Center, the process of creating and updating Connectors is different.

If you are creating a new Connector:

1. Create a [ConnectorStagedDraft](https://docs.commercetools.com/connect/connectors-staged#connectorstageddraft) that references your GitHub repository and Git tag.
2. Post the ConnectorStagedDraft to the [Create ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged#create-connectorstaged) endpoint. This creates a [ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged#connectorstaged) that you can preview and publish.

If you are updating an existing Connector:

1. Push your code changes to the GitHub repository and [create a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) with a Git tag.
2. Update the ConnectorStaged using the [Set Repository](https://docs.commercetools.com/connect/connectors-staged#set-repository) update action to reference the new Git tag.

If you are creating a new Connector, follow our Merchant Center guide to [Create an Organization Connector](https://docs.commercetools.com/merchant-center/connect#create-an-organization-connector).

If you are updating an existing Connector:

1. Push your code changes to the GitHub repository and [create a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) with a Git tag.
2. Open the Organization Connector in the Merchant Center, update the Repository tag, and click Save.

### Create and deploy a preview build

Preview builds allow you to test the functionality of your Connect applications before publishing the Connector.

Depending on whether you are using the Connect API or Merchant Center, the process of requesting and deploying a preview build is different.

1. Request the previewable status of the ConnectorStaged using the [Preview Connector](https://docs.commercetools.com/connect/connectors-staged#preview-connector) update action.
   - The system reviews your ConnectorStaged before it becomes previewable. To check the previewable status of your ConnectorStaged, query the [Get ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged#get-connectorstaged) endpoint and check the `isPreviewable` field.
   - If the `isPreviewable` field of your ConnectorStaged is `true`, the preview is successful and you can continue to step 2. If `false`, fix any issues in your Connect applications, update the ConnectorStaged if needed (for example by using the Set Repository update action), and repeat this step until `isPreviewable` is `true`.
2. Create a [DeploymentDraft](https://docs.commercetools.com/connect/deployments#deploymentdraft) that includes a reference to the ConnectorStaged. `connector.staged` must be set to `true` to deploy a previewable ConnectorStaged.
3. Post the DeploymentDraft to the [Create Deployment](https://docs.commercetools.com/connect/deployments#create-deployment) endpoint. This creates a [Deployment](https://docs.commercetools.com/connect/deployments#deployment) that includes a reference to the ConnectorStaged.

If you are creating a new Connector, follow our Merchant Center guide to [Create an Organization Connector](https://docs.commercetools.com/merchant-center/connect#create-an-organization-connector).

If you are updating an existing Connector:

1. Push your code changes to the GitHub repository and [create a release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) with a Git tag.
2. Open the Organization Connector in the Merchant Center, update the Repository tag, and click Save.
3. Reopen the Organization Connector in the Merchant Center and click Request preview.
4. Once the preview is successful, open the Organization Connector and click Deploy on Preview.

Preview builds must pass [validation](https://docs.commercetools.com/connect/overview#validation-process) before they can be deployed.

### Publish a production build

Connectors must be published before they can be deployed.

Depending on if you are using the Connect API or Merchant Center, the process of publishing Connectors is different.

1. If the Connector is intended for private use only, update the ConnectorStaged using the [publish](https://docs.commercetools.com/connect/connectors-staged#publish) update action with `certification` set to `false`.
   - If the Connector is intended for public use, update the ConnectorStaged using the [publish](https://docs.commercetools.com/connect/connectors-staged#publish) update action with `certification` set to `true`.
   - When published, a [Connector](https://docs.commercetools.com/connect/connectors#connector) is created or updated based on the ConnectorStaged.
2. Create a [DeploymentDraft](https://docs.commercetools.com/connect/deployments#deploymentdraft) that includes a reference to the Connector.
3. Post the DeploymentDraft to the [Create Deployment](https://docs.commercetools.com/connect/deployments#create-deployment) endpoint.
   - This creates a [Deployment](https://docs.commercetools.com/connect/deployments#deployment) that includes a reference to the Connector.

1) Open the Organization Connector in the Merchant Center.
2) If the Connector is intended for private use only, click Publish for private use.
   - If the Connector is intended for public use, click List on Marketplace.
3) Once the Connector is published, open the Organization Connector and click Deploy on Production.

Production builds must pass [validation](https://docs.commercetools.com/connect/overview#validation-process) before they can be deployed.

## Validation process

When requesting a preview build or publishing a Connector, the system checks the code quality and security of your [Connect applications](https://docs.commercetools.com/connect/overview#connect-applications). These checks include image security analysis, static application security testing (SAST), and software composition analysis (SCA). The content of the `connect.yaml` file is also validated. These checks help ensure that Connect applications meet the required standards for running in a production environment.

You can perform the validation process locally using the `commercetools connect validate` [CLI command](https://docs.commercetools.com/connect/cli#commercetools-connect-validate).

You can check the validation status of a preview build or published Connector using the Connect API or Merchant Center.

1. Query the [Get ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged#get-connectorstaged) endpoint of the ConnectorStaged.
2. Check the `previewableReport` or `publishingReport` fields of the ConnectorStaged.
   - The `isPreviewable` field indicates if the ConnectorStaged has passed validation for the preview build.
   - If the `status` field is `Published`, the ConnectorStaged has passed validation for publishing.

1) Open the Connector in the Merchant Center.
2) The labels Preview Accepted and Published indicate that the Connector has passed validation.
3) Go to Preview Report or Publish Report to view detailed information about the validation results.

## 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](https://docs.commercetools.com/connect/merchant-center/connect). The certification process verifies the functionality, security, and stability of [Connect applications](https://docs.commercetools.com/connect/overview#connect-applications). For more information about the certification process, see [Certification](https://docs.commercetools.com/connect/certification).

## Deployments

[Deployments](https://docs.commercetools.com/connect/deployments) represent how clients integrate [Connect applications](https://docs.commercetools.com/connect/overview#connect-applications) into their Project.

Deployments include a reference to a published [Connector](https://docs.commercetools.com/connect/overview#connectors), 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](https://docs.commercetools.com/connect/deployments#update-actions) the Deployment with new values.

You can deploy Connectors using the [Connect API](https://docs.commercetools.com/connect/deployments), [Merchant Center](https://docs.commercetools.com/connect/merchant-center/connect), or [CLI](https://docs.commercetools.com/connect/cli#deployment-management-commands).

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](https://docs.commercetools.com/connect/overview#connect-applications) have the following behavior based on their application type.

### Service

- Uses HTTP-based exposed endpoints.
- Application request times out after 5 minutes.
- Will autoscale based on the number of requests.

### Event

- Uses a message broker service.
- The event acknowledgment timeout for an application is 10 seconds.
- Application request times out 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 default schedule is defined by the `properties.schedule` cron expression in `connect.yaml`. You can override it per deployment using the `schedule` field of [DeploymentConfigurationApplication](https://docs.commercetools.com/connect/deployments#deploymentconfigurationapplication).
- Application request times out after 30 minutes.

### Merchant-center-custom-application

- Is a hosted React application.
- Application request times out after 5 minutes.
- Will autoscale based on the number of requests.

### Merchant-center-custom-view

- Is a hosted React application.
- The server times out after 5 minutes.
- Will autoscale based on the number of requests.

### Assets

- Hosts static assets.
- Application request times out after 5 minutes.
- CDN capabilities are supported.

## Environments

The [DeploymentType](https://docs.commercetools.com/connect/ctp:connect:type:DeploymentType) lets you control which type of environment your ConnectorStaged or Connector is [deployed](https://docs.commercetools.com/connect/overview#deployments) to.

Deployments are made to the `sandbox` environment by default if no other type is specified. These deployments automatically scale down to zero when they are unused for a while. This can cause timeouts because they require approximately 15 seconds to boot up again.

### Sandbox

The `sandbox` deployment type is the default deployment type for Connectors. It allows you to run your Connector in a non-production environment, such as a development or QA environment.

You cannot deploy a ConnectorStaged to a sandbox environment.

### Preview

The `preview` deployment type lets you test your ConnectorStaged during application development. It allows you to validate your logic and make sure the functionality works as expected.

You must set the ConnectorStaged `isPreviewable` status to `true` for preview deployments.

Preview deployments should be deleted as soon as testing is complete. They are only intended to last a short time and scale down to zero.

### Production

To deploy in production, your [Project](https://docs.commercetools.com/connect/api/project-configuration-overview) must not be a trial.

The `production` deployment type lets you deploy a Connector, which is already in production or is ready to be in your production environment. Only published Connectors can use the `production` deployment type.

`production` provides the highest scalability for optimal performance and stability of the Connector, with already warmed-up instances ready to manage the load at all times.

If you have not previously published your Connector to `production`, contact your Customer Success Manager or the [commercetools support team](https://support.commercetools.com/) for assistance.