# Get started with Connect Learn how to create or deploy Connect applications. ## Select task Connect involves two roles, and you might perform one or both of them. For a full description, see [Who is Connect for](https://docs.commercetools.com/connect/overview.md#who-is-connect-for). - As a creator, you develop, publish, and maintain Connectors. If you have created Connect applications and want to publish them, follow [Create a Connector](https://docs.commercetools.com/connect/getting-started.md#create-a-connector). - As a client, you deploy and configure Connectors in your Project. If you want to integrate Connect applications with your Project, follow [Deploy a Connector](https://docs.commercetools.com/connect/getting-started.md#deploy-a-connector). If you are building a Connector for your own Project, you perform both roles: complete [Create a Connector](https://docs.commercetools.com/connect/getting-started.md#create-a-connector) first, then [Deploy a Connector](https://docs.commercetools.com/connect/getting-started.md#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](https://docs.commercetools.com/connect/getting-started.md#create-a-connectorstaged) - [Published the ConnectorStaged](https://docs.commercetools.com/connect/getting-started.md#publish-your-connector) - [Learned how to maintain your Connector](https://docs.commercetools.com/connect/getting-started.md#update-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. ```yaml 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](https://docs.commercetools.com/connect/development.md). ### Create a ConnectorStaged [ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged.md#connectorstaged) are used to create, update, and preview Connectors before submitting them for publishing. Once published, they create/update the read-only production [Connector](https://docs.commercetools.com/connect/connectors.md#connector). ConnectorStaged are created by posting a [ConnectorStagedDraft](https://docs.commercetools.com/connect/connectors-staged.md#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`. ```http 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"] } ``` ```curl curl -X POST https://connect.{region}.commercetools.com/connectors/drafts -H "Authorization: Bearer ${BEARER_TOKEN}" --data '{ "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](https://docs.commercetools.com/connect/connectors-staged.md#preview-connector) update action to request previewable status for your ConnectorStaged. ```http 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" } ] } ``` ```curl curl -X POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector -H "Authorization: Bearer ${BEARER_TOKEN}" --data '{"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 [commercetools support team](https://support.commercetools.com/). For detailed insights into any issues encountered during the preview request process, refer to the [ConnectorReport](https://docs.commercetools.com/urn?urn=ctp%3Aconnect%3Atype%3AConnectorReport) in the `previewableReport` field of your ConnectorStaged upon process completion. #### Deploy previewable ConnectorStaged Deployments are created by posting a [DeploymentDraft](https://docs.commercetools.com/connect/getting-started.md#create-a-deployment) 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](https://docs.commercetools.com/connect/getting-started.md#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](https://docs.commercetools.com/connect/getting-started.md#list-on-the-connect-marketplace). Keep in mind that your Connector must pass the [certification process](https://docs.commercetools.com/connect/certification.md) before being listed. #### Publish for private use Use the [Publish](https://docs.commercetools.com/connect/connectors-staged.md#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](https://docs.commercetools.com/connect/connectors-staged.md#get-connectorstaged), then inspect the `publishingReport` field in the response. After completion, consult the [ConnectorReport](https://docs.commercetools.com/urn?urn=ctp%3Aconnect%3Atype%3AConnectorReport) about the process in the `publishingReport` field of your ConnectorStaged. ```http 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 } ] } ``` ```curl curl -X POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector -H "Authorization: Bearer ${BEARER_TOKEN}" --data '{ "version": 1, "actions": [ { "action": "publish", "certification": false } ]}' ``` #### List on the Connect marketplace Connectors must be [certified](https://docs.commercetools.com/connect/certification.md) before being listed on the Connect marketplace. Certification is a semi-automated process that starts when you use the [Publish](https://docs.commercetools.com/connect/connectors-staged.md#publish) update action with `certification` set to `true`. You should check that your Connector meets the [requirements for certification](https://docs.commercetools.com/connect/certification.md#requirements-for-certification) before submitting it for certification. ```http 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 } ] } ``` ```curl curl -X POST https://connect.{region}.commercetools.com/connectors/drafts/key=abc-first-connector -H "Authorization: Bearer ${BEARER_TOKEN}" --data '{ "version": 1, "actions": [ { "action": "publish", "certification": true } ]}' ``` ##### Monitor certification status To monitor the status of the publishing process, use [Get ConnectorStaged](https://docs.commercetools.com/connect/connectors-staged.md#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](https://docs.commercetools.com/connect/connectors-staged.md#get-connectorstaged), then inspect the `certificationInfo` field in the response. To submit comments, use the [Add Certification Comment](https://docs.commercetools.com/connect/connectors-staged.md#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. 1. Update your GitHub repository with the new Connect application. 2. Generate a new Git tag/release. 3. Make changes in the GitHub repository as needed, ensuring that `connect.yaml` represents the new [ConnectorConfigurationApplication](https://docs.commercetools.com/connect/connectors-staged.md#connectorconfigurationapplication). 4. Use the [Set Repository](https://docs.commercetools.com/connect/connectors-staged.md#set-repository) update action and include the GitHub repository URL and the new Git tag. 5. Use the [Publish](https://docs.commercetools.com/connect/connectors-staged.md#publish) update action. If you are updating a private Connector, `certification` should be set to `false`. 6. Use the [Redeploy](https://docs.commercetools.com/connect/deployments.md#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 Project. ### Requirements - A Project that is hosted in a [supported Region](https://docs.commercetools.com/connect/hosts-and-authorization.md#hosts). - While requirements for installing individual Connectors vary based on the services they interact with, most require an [API Client](https://docs.commercetools.com/merchant-center/developer-settings.md#api-clients). 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](https://docs.commercetools.com/connect/getting-started.md#search-for-a-connector) - [Deployed a Connector](https://docs.commercetools.com/connect/getting-started.md#create-a-deployment) ### Search for a Connector You should query the [Search Connector endpoint](https://docs.commercetools.com/connect/connectors.md#search-connectors) to find available Connectors that fit your requirements. ```http GET https://connect.{region}.commercetools.com/connectors/search Authorization: Bearer ${BEARER_TOKEN} ``` ```curl curl -X GET https://connect.{region}.commercetools.com/connectors/search -H "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. ```http GET https://connect.{region}.commercetools.com/connectors/search ?text=payments Authorization: Bearer ${BEARER_TOKEN} ``` ```curl curl -X GET https://connect.{region}.commercetools.com/connectors/search?text=payments -H "Authorization: Bearer ${BEARER_TOKEN}" ``` If you know the name of the company that created the Connector, include the `creator.company` parameter. ```http GET https://connect.{region}.commercetools.com/connectors/search ?creator.company=commercetools Authorization: Bearer ${BEARER_TOKEN} ``` ```curl curl -X GET https://connect.{region}.commercetools.com/connectors/search?creator.company=commercetools -H "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](https://docs.commercetools.com/connect/deployments.md#deploymentdraft) to the [Deployments endpoint](https://docs.commercetools.com/connect/deployments.md#create-deployment). You must include a reference to the Connector (using the Connector's `id` or `key` and `version`), the [Region](https://docs.commercetools.com/connect/common-types.md#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](https://docs.commercetools.com/connect/common-types.md#region) than the one that hosts your Project. However, for best performance, we recommend using the same [Region](https://docs.commercetools.com/connect/common-types.md#region). ```http 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}" } ] } ] } ``` ```curl curl -X POST https://connect.{region}.commercetools.com/{projectKey}/deployments -H "Authorization: Bearer ${BEARER_TOKEN}" --data '{ "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": "test-project" }, { "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:{test-project}" } ] } ]}' ``` #### Monitor the deployment progress Your new Deployment will enter the deployment process, and you can monitor its status by [getting the Deployment](https://docs.commercetools.com/connect/deployments.md#get-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 [commercetools support team](https://support.commercetools.com/). ## Related pages - [Section overview page](https://docs.commercetools.com/connect.md) - [Previous page: Supported runtimes](https://docs.commercetools.com/connect/supported-runtimes.md) - [Next page: Develop a Connect application](https://docs.commercetools.com/connect/development.md)