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, or submit them for certification, 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
Submitted the ConnectorStaged for certification
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 certification. 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
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
        - 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 is how non-certified versions of Connectors are stored. Even after being certified and listed, a ConnectorStaged can be modified (to fix bugs and add new features) and re-certified to update the 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"
  }
}

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 without requiring certification.

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 and your ConnectorStaged will be reviewed by the Connect team.

After being reviewed, isPreviewable will change to true if previewable status has been granted or false if it has been rejected. Rejections are usually caused by the code repository having critical security issues, and the Connect team will contact you with further information.

For more details about issues of the preview request process, consult the resulting Report in the previewableReport field of your ConnectorStaged after 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.

Publish for private use

Use the Publish update action with certification set to false to create a production-ready Connector for private use. The published Connector will be only available for deployments on the projects defined in the privateProjects field of your ConnectorStaged.

After completion, you can consult the Report 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
    }
  ]
}

Request certification

After creating and/or previewing your ConnectorStaged, use the Publish update action with certification set to true to submit the ConnectorStaged for final certification and to be listed for production-ready deployments.

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

After triggering the certification process, your ConnectorStaged will be reviewed by the Connect team. The status of which can be monitored by getting the ConnectorStaged and viewing the status field.

The Connect team may ask questions about your ConnectorStaged. This will change the status to FEEDBACK_REQUIRED. Comments can be viewed in the certificationInfo field of your ConnectorStaged. You can submit your own comments using the Add Certification Comment update action.

Once your ConnectorStaged is certified, a production Connector is created that contains the content of the ConnectorStaged. This production Connector then becomes available for deployment and the value of alreadyListed will change to true.

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 to submit your updated application for certification.

Deploy a Connector

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

Requirements

A commercetools Composable Commerce Project that is hosted in a supported Region.

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 that will be deployed (using the Connector's id or key and version), the Region where the deployment will be made, and also the environment variables necessary for the Connector to operate. It is recommended to include a key to identify your Deployment.

It is recommended to use the same region as your Composable Commerce Project.
The value fields within securedConfiguration become encrypted on submission.

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, please contact support.