Getting started

Learn how to create or deploy Connect applications.

Which guide to follow?

If you have created Connect applications and want to publish them, follow Create a Connector.

If you want to integrate Connect applications with your commercetools Composable Commerce Project, follow Deploy a Connector.

Create a Connector

This step-by-step guide leads creators through configuring and publishing their Connector.

Requirements

A Connect application saved in a GitHub repository.

Objectives of this guide

By the end of this guide you will have:

Created a ConnectorStaged
Published the ConnectorStaged
Learned how to maintain your Connector

Our example Connect application

In this guide we assume there is a GitHub repository containing a Connect application that is ready for publishing. The name of the GitHub repository used in this guide is abc/first-connect-application and the contents of the connect.yaml are as follows.

deployAs:
  - name: cartExtension
    applicationType: service
    endpoint: /service
    scripts:
      postDeploy: npm install && npm run connector:post-deploy
      preUndeploy: npm install && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Composable Commerce Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Composable Commerce Project

Any environment variables needed by the Connect application can be added in the configuration attribute as either a standardConfiguration (stored as plain text) or a securedConfiguration (which are encrypted and cannot be retrieved after being added). You should also include descriptions for environment variables to assist clients when they deploy your Connector.

For more information on developing a Connect application, see our Development guide.

Create a ConnectorStaged

ConnectorStaged are used to create, update, and preview Connectors before submitting them for publishing. Once published, they create/update the read-only production Connector.

ConnectorStaged are created by posting a ConnectorStagedDraft to the /connectors/drafts endpoint.

Create and post a ConnectorStagedDraft

The ConnectorStagedDraft should match the details within the connect.yaml file in your GitHub repository. It is also recommended to include a key to identify your ConnectorStaged.

In this example, https://github.com/abc/first-connect-application only has a single application called cartExtension.

Create a ConnectorStagedDraft

POST https://connect.{region}.commercetools.com/connectors/drafts
Authorization: Bearer ${BEARER_TOKEN}
Content-Type: application/json

{
  "key": "abc-first-connector",
  "name": "Abc First Connector",
  "description": "An example connector",
  "creator": {
    "title": "Mr",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "company": "abc",
    "noOfDevelopers": 10
  },
  "repository": {
    "url": "https://github.com/abc/first-connect-application.git",
    "tag": "0.0.0"
  },
  "supportedRegions" : ["europe-west1.gcp"]
}

For faster request processing, we recommend you add only the required Regions in supportedRegions.

Preview your connector

After creating your ConnectorStaged you can request previewable status. This status will allow you to deploy your ConnectorStaged for testing/preview purposes.

Request previewable status for ConnectorStaged

Use the Preview Connector update action to request previewable status for your ConnectorStaged.

Request a ConnectorStaged for previewable

POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector
Authorization: Bearer ${BEARER_TOKEN}
Content-Type: application/json

{
  "version" : 1,
  "actions" : [ {
    "action" : "updatePreviewable"
  } ]
}

Monitor Preview status

After requesting previewable status, the isPreviewable field of your ConnectorStaged will change to pending as it undergoes validation.

Then, the isPreviewable field will update to true if the previewable status is granted, or false if it is rejected. Rejections typically occur due to critical security issues in the code repository. For more details, contact the Connect support team.

For detailed insights into any issues encountered during the preview request process, refer to the ConnectorReport in the previewableReport field of your ConnectorStaged upon process completion.

Deploy previewable ConnectorStaged

Deployments are created by posting a DeploymentDraft to the Deployments endpoint. To deploy a previewable ConnectorStaged, the connector.staged value should be true. You can only deploy previewable ConnectorStaged to Projects listed in privateProjects of the ConnectorStaged.

Publish your Connector

If you plan to use your Connector solely on your own Projects, you should publish for private use. Certification is not required for private Connectors.

If you plan to make your Connector publicly available, you should list it on the Connect marketplace. Keep in mind that your Connector must pass the certification process before being listed.

Publish for private use

Use the Publish update action with certification set to false. Once published, the Connector can only be deployed to Projects defined in the privateProjects field of your ConnectorStaged.

To view additional information about the publishing process, including possible errors and warnings, use Get ConnectorStaged, then inspect the publishingReport field in the response.

After completion, consult the ConnectorReport about the process in the publishingReport field of your ConnectorStaged.

Publishing a Connector for private use

POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector
Authorization: Bearer ${BEARER_TOKEN}
Content-Type: application/json

{
  "version": 1,
  "actions": [
    {
      "action": "publish",
      "certification": false
    }
  ]
}

List on the Connect marketplace

Connectors must be certified before being listed on the Connect marketplace. Certification is a semi-automated process that starts when you use the Publish update action with certification set to true.

You should check that your Connector meets the requirements for certification before submitting it for certification.

Submit a ConnectorStaged for certification

POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector
Authorization: Bearer ${BEARER_TOKEN}
Content-Type: application/json

{
  "version": 1,
  "actions": [
    {
      "action": "publish",
      "certification": true
    }
  ]
}

Monitor certification status

To monitor the status of the publishing process, use Get ConnectorStaged, then inspect the status field in the response.

The Connect team may ask questions about your ConnectorStaged.

To view comments, use Get ConnectorStaged, then inspect the certificationInfo field in the response.

To submit comments, use the Add Certification Comment update action.

Update your Connector

If you update your Connect application to fix bugs or add new features, you should follow these steps to update the Connector.

Update your GitHub repository with the new Connect application.
Generate a new Git tag/release.
Make changes in the GitHub repository as needed, ensuring that connect.yaml represents the new ConnectorConfigurationApplication.
Use the Set Repository update action and include the GitHub repository URL and the new Git tag.
Use the Publish update action. If you are updating a private Connector, certification should be set to false.
Use the Redeploy update action with updateConnector set to true.

Deploy a Connector

This step-by-step guide leads clients through finding and deploying Connectors for use in their Composable Commerce Project.

Requirements

A Composable Commerce Project that is hosted in a supported Region.
While requirements for installing individual Connectors vary based on the services they interact with, most require an API Client. For greater security and auditability, we recommend creating a specific API Client for each Connector.

Objectives of this guide

By the end of this guide you will have:

Learned how to find Connectors
Deployed a Connector

Search for a Connector

You should query the Search Connector endpoint to find available Connectors that fit your requirements.

Return all available Connectors

GET https://connect.{region}.commercetools.com/connectors/search
Authorization: Bearer ${BEARER_TOKEN}

The Search Connector endpoint supports various parameters to assist you in narrowing down your search results. For example, include the text parameter to only return Connectors with a specified string within its name and/or description.

Search for Connectors with payments in the name or description

GET https://connect.{region}.commercetools.com/connectors/search
?text=payments
Authorization: Bearer ${BEARER_TOKEN}

If you know the name of the company that created the Connector, include the creator.company parameter.

Search for Connectors made by commercetools

GET https://connect.{region}.commercetools.com/connectors/search
?creator.company=commercetools
Authorization: Bearer ${BEARER_TOKEN}

Upon finding a Connector you want to deploy, take note of the id or key of the Connector and its version as they are needed to create a Deployment.

The information within the configurations field is also required for you to reference Connect applications and to include the necessary environment variables.

Create a Deployment

Deployments are created by posting a DeploymentDraft to the Deployments endpoint.

You must include a reference to the Connector (using the Connector's id or key and version), the Region of the Deployment, and the environment variables necessary for the Connector to operate. We recommended including a key to identify your Deployment.

You can deploy to a different Region than the one that hosts your Composable Commerce Project. However, for best performance, we recommend using the same Region.

Create a Deployment

POST https://connect.{region}.commercetools.com/{projectKey}/deployments
Authorization: Bearer ${BEARER_TOKEN}
Content-Type: application/json

{
  "key": "my-first-deployment",
  "connector": {
    "id": "207f5046-95e7-4cfb-8c3b-93934f8c865e",
    "version": 8,
    "staged": false
  },
  "region": "europe-west1.gcp",
  "configurations": [
    {
      "applicationName": "cartExtension",
      "standardConfiguration": [
        {
          "key": "CT_PROJECT_KEY",
          "value": "{projectKey}"
        },
        {
          "key": "CT_REGION",
          "value": "europe-west1.gcp"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CT_CLIENT_ID",
          "value": "client-id-value"
        },
        {
          "key": "CT_CLIENT_SECRET",
          "value": "client-secret-value"
        },
        {
          "key": "CT_SCOPE",
          "value": "manage_project:{projectKey}"
        }
      ]
    }
  ]
}

Monitor the deployment progress

Your new Deployment will enter the deployment process, and you can monitor its status by getting the Deployment and viewing the status field or the report field in the build details.

The initial status for your new Deployment will be Queued, and it can take up to 15 minutes to finish the deployment process. Once finished, your Deployment will have the status Deployed and will be ready to use. You can check the details field within the Deployment to view its configuration.

If your Deployment status is Failed, contact the Connect support team.