Create your ConnectorStaged

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

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

Please note: there are two more application types, merchant-center-custom-app and assets, that you can create but they are not in the example above.

Testing 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.

Testing 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.

Testing 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 commercetools 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 commercetools 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 and submit the form to create the ConnectorStaged.

Great! You have just created your first commercetools 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 commercetools 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.