Create your ConnectorStaged

Elevate, May 20-22-2025, Miami Beach, Florida

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:

    1. With sample data simulating the call from API Extensions or

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

    Select Organization connectors.)

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

    Using the Merchant Center to create a ConnectorStaged.)

    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
    Select what you want to do with the connector.)

    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.

    Test your knowledge