Overview

Learn about the concepts and terminology of Connect.

What is Connect

Connect lets you add functionality to your Composable Commerce 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 Composable Commerce Projects using the Connect API or the Merchant Center.

Example use case for 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 Connect for

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.

Connect workflow

The following steps outline how creators and clients use Connect.

Use Connect API

Creators develop Connect applications and store them in a GitHub repository.
Creators use the Connect API to create a ConnectorStaged that references this GitHub repository.
Creators publish their ConnectorStaged. Once published, the ConnectorStaged creates/updates a Connector.
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.

Use Merchant Center

Creators develop Connect applications and store them in a GitHub repository.
Clients create and publish a Connector that references this GitHub repository.
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 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.
merchant-center-custom-view: create Custom Views 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.
A merchant-center-custom-application application to provide a frontend for modifying the emails sent by the event application.
A merchant-center-custom-view to add custom functionality in the context of a specific page within a built-in Merchant Center 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.

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.
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.
Application request times out timeout 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.

Deployment type

The deployment type lets you control which type of environment your ConnectorStaged or Connector is deployed to.

Preview

The preview deployment type lets you test your ConnectorStaged during the development of your application by allowing 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 because they are meant to last only a short time and scale down to zero.

Sandbox

The sandbox deployment type is the default deployment type for Connectors that lets you run your Connector in a non-production environment, such as a development or QA environment. You cannot deploy a ConnectorStaged to a sandbox environment.

Deployments are deployed in the sandbox environment by default if no other type is specified, and they 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.

Production

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

This deployment type 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 your production environment, flag it as ready for production by contacting your Customer Success Manager or the Connect support team.

Overview

What is Connect.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Example use case for Connect.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Who is Connect for.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Connect workflow.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Use Connect API.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Use Merchant Center.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Connect applications.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

GitHub repository.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Connectors.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Certification process.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Deployments.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Deployment information and limitations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

service.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

event.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

job.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

merchant-center-custom-application.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

merchant-center-custom-view.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

assets.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Deployment type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Preview.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Sandbox.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Production.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}