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:
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: cartExtensionapplicationType: serviceendpoint: /servicescripts:postDeploy: npm install && npm run connector:post-deploypreUndeploy: npm install && npm run connector:pre-undeployconfiguration:standardConfiguration:- key: CTP_PROJECT_KEYdescription: Project key of the commercetools Composable Commerce Project- key: CTP_REGIONdescription: Region where the commercetools Composable Commerce Project is hostedsecuredConfiguration:- key: CTP_CLIENT_IDdescription: client_id of an API Client for the commercetools Composable Commerce Project- key: CTP_CLIENT_SECRETdescription: secret of an API Client for the commercetools Composable Commerce Project- key: CTP_SCOPEdescription: 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
.
POST https://connect.{region}.commercetools.com/connectors/draftsAuthorization: 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.
POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connectorAuthorization: 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.
POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connectorAuthorization: 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.
POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connectorAuthorization: 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:
Search for a Connector
You should query the Search Connector endpoint to find available Connectors that fit your requirements.
GET https://connect.{region}.commercetools.com/connectors/searchAuthorization: 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.
GET https://connect.{region}.commercetools.com/connectors/search?text=paymentsAuthorization: Bearer ${BEARER_TOKEN}
If you know the name of the company that created the Connector, include the creator.company
parameter.
GET https://connect.{region}.commercetools.com/connectors/search?creator.company=commercetoolsAuthorization: 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 withinsecuredConfiguration
become encrypted on submission.
POST https://connect.{region}.commercetools.com/{projectKey}/deploymentsAuthorization: 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.