Learn how to create your code repository and create a ConnectorStaged.
After completing this page, you should be able to:
- Describe the process of creating a ConnectorStaged.
Let’s jump into the first two steps of the Connector development workflow.
Step 1: Develop your applications locally
You can make use of the starter template provided to create your first Connect application.
Install the Create Connect app that you can use to set up a template application, either with Javascript or Typescript. (For Java, contact the Composable Commerce support team).
npm install \--global @commercetools-connect/create-connect-app
create-connect-app first-connect-application --template javascript
This will generate a directory structure, as required by Connect, with one folder for each type of Connect application. You can rename the folders to match the purpose of your applications. You must remove the folders not needed. Add, remove, rename the folders as needed while maintaining the basic directory structure. Implement the code in your applications.
Register your applications
Once you have implemented the application logic, you must then register your Connect applications in the connect.yaml
file. This is a very important step because the connect.yaml
file is where you define the settings and configurations information required for deployments. See here for an example.
deployAs:
- name: free-sample-product-service
applicationType: service
endpoint: /free-sample-product-service
scripts:
postDeploy: npm install && npm run build && npm run connector:post-deploy
preUndeploy: npm install && npm run build && npm run connector:pre-undeploy
configuration:
standardConfiguration:
- key: SAMPLE_PRODUCT_SKU
description: SKU of the free product
required: true
- key: CTP_REGION
description: commercetools Composable Commerce API region
required: false
default: 'europe-west1.gcp'
- key: CHANNEL_KEY
description: Channel key to be used for Inventory control
required: false
default: 'free-sample-channel'
securedConfiguration:
- key: CTP_PROJECT_KEY
description: commercetools Composable Commerce project key
required: true
- key: CTP_CLIENT_ID
description: commercetools Composable Commerce client ID
required: true
- key: CTP_CLIENT_SECRET
description: commercetools Composable Commerce client secret
required: true
- name: new-product-event-app
applicationType: event
endpoint: /new-product-event-app
scripts:
postDeploy: npm install && npm run build && npm run connector:post-deploy
preUndeploy: npm install && npm run build && npm run connector:pre-undeploy
configuration:
standardConfiguration:
- key: NEW_CATEGORY_KEY
description: The key of the Category used for new arrivals
required: true
- key: CTP_REGION
description: commercetools Composable Commerce API region
required: false
default: europe-west1.gcp
securedConfiguration:
- key: CTP_PROJECT_KEY
description: commercetools Composable Commerce project key
required: true
- key: CTP_CLIENT_ID
description: commercetools Composable Commerce client ID
required: true
- key: CTP_CLIENT_SECRET
description: commercetools Composable Commerce client secret
required: true
- name: new-category-cleanup-job-app
applicationType: job
endpoint: /new-category-cleanup-job-app
properties:
schedule: '0 1 * * *'
configuration:
standardConfiguration:
- key: NEW_CATEGORY_KEY
description: The key of the Category used for new arrivals
required: true
- key: CTP_REGION
description: commercetools Composable Commerce API region
required: false
default: europe-west1.gcp
securedConfiguration:
- key: CTP_PROJECT_KEY
description: commercetools Composable Commerce Project key
required: true
- key: CTP_CLIENT_ID
description: commercetools Composable Commerce API Client ID
required: true
- key: CTP_CLIENT_SECRET
description: commercetools Composable Commerce API Client secret
required: true
As you see in this connect.yaml
file, three Connect applications are declared as part of a Connector with the following properties:
**Application 1 **
-
Type:
service
-
Name:
free-sample-product-service
-
Endpoint:
free-sample-product-service
-
API Credentials to Composable Commerce project
-
Other configurations
**Application 2 **
-
Type:
event
-
Name:
new-product-event-app
-
Endpoint:
new-product-event-app
-
API Credentials to Composable Commerce project
-
Other configurations
**Application 3 **
-
Type:
job
-
Name:
new-category-cleanup-job-app
-
Endpoint:
new-category-cleanup-job-app
-
Properties:
'Schedule: 0 1 * * *'
-
API Credentials to Composable Commerce project
-
Other configurations
You can create two more application types that are not in the previous example, merchant-center-custom-app and assets.
Test your applications locally
Service and Event type applications can be tested locally in a controlled environment before you actually create a Connector. Testing an application locally allows you to make live changes with full visibility and control over your process, data, and results.
Test a Service application
Service Connect applications can be tested in 2 different ways:
-
With sample data simulating the call from API Extensions or
-
Create an API Extension and trigger it from your project
For step by step instruction, follow our documentation on Testing a service application locally.
Test an Event application
Event Connect applications can be tested by posting sample data in the body payload and reviewing the results.
For step by step instruction, follow our documentation on Testing an event application locally.
Now that you have developed your applications and also tested them locally, it’s time to push your code to a Github repository and create a release with a Git tag. This is needed in the next step to create a Connector Draft (also known as ConnectorStaged). If your Github repository is private, you must grant read access to the connect-mu machine user.
Step 2: Create a ConnectorStaged
ConnectorStaged represents the draft version of a Connector. Even though it is a draft, it can still be deployed and used in your Project for testing and preview, provided the application has been granted the Previewable
status. By creating a ConnectorStaged, you are registering the Connector with Connect.
To register you must send a request to:
curl https://connect.{region}.commercetools.com/connectors/drafts -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
with the following body included. In the first part of this tutorial, we will not make the Connector publicly available. This means we will have to include the Projects we want to access the Connector in privateProjects
. Private Connectors are also called Organization Connectors and can only be accessed in the projects listed in the privateProjects
array.
{
"key": "free-sample-training-connector",
"name": "Self Learning Training Connector",
"description": "A connector learn Connect",
"creator": {
"name": "Training Team",
"email": "training@commercetools.com",
"company": "commercetools",
"title": "commercetools",
"noOfContributors": 5
},
"repository": {
"url": "git@github.com:commercetools/self-learning-training-connector.git",
"tag": "v1.0.0"
},
"privateProjects": ["europe-west1.gcp:training-team-poc"],
"supportedRegions": ["us-central1.gcp", "europe-west1.gcp"]
}
The above code will result in a new Connector draft (ConnectorStaged).
Create a ConnectorStaged in Merchant Center
This process could also be completed from the Merchant Center. If you would like to create a Connector in the Merchant Center, go to Manage Organizations & Teams, select an Organization, and from the Connect tab select Organization connectors.

Click the Create Connector button which will open a web form linked to ConnectorStagedDraft.

Complete the form and click Next. You will then be asked Select what you want to do with the connector. Here you can:
- Request Preview
- Publish for private use
- List on Marketplace
- Skip this step

We will select Skip this step. This option will not publish or deploy the Connector, and instead will create a ConnectorStaged.
Great! You have just created your first ConnectorStaged! You can verify that by running the following GET request:
curl --get https://connect.{region}.commercetools.com/connectors/drafts/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
The response should look like this:
{
"id": "1c167d01-7a14-4f75-9240-04628ddcc350",
"key": "free-sample-training-connector",
"version": 1,
"name": "Self Learning Training Connector",
"description": "A connector learn Connect.",
"creator": {
"name": "Training Team",
"email": "training@commercetools.com",
"company": "commercetools",
"title": "commercetools",
"noOfContributors": 5
},
"repository": {
"tag": "v1.0.0",
"url": "git@github.com:commercetools/self-learning-training-connector.git"
},
"configurations": [
{
"applicationName": "free-sample-product-service",
"applicationType": "service",
"securedConfiguration": [
{
"key": "CTP_CLIENT_ID",
"description": "commercetools Composable Commerce client ID",
"required": true
},
{
"key": "CTP_CLIENT_SECRET",
"description": "commercetools Composable Commerce client secret",
"required": true
},
{
"key": "CTP_PROJECT_KEY",
"description": "commercetools Composable Commerce project key",
"required": true
}
],
"standardConfiguration": [
{
"key": "CHANNEL_KEY",
"description": "Channel key to be used for Inventory control",
"required": false,
"default": "free-sample-channel"
},
{
"key": "SAMPLE_PRODUCT_SKU",
"description": "SKU of the free product",
"required": true
}
]
},
{
"applicationName": "new-category-cleanup-job-app",
"applicationType": "job",
"securedConfiguration": [
....
],
"standardConfiguration": [
....
]
},
{
"applicationName": "new-product-event-app",
"applicationType": "event",
"securedConfiguration": [
....
],
"standardConfiguration": [
....
]
}
],
"private": true,
"privateProjects": [
"europe-west1.gcp:training-team-poc"
],
"supportedRegions": [
"us-central1.gcp",
"europe-west1.gcp"
],
"hasChanges": false,
"alreadyListed": false,
"status": "draft",
}
Nice one! Let's do a quick knowledge check.