Deploy and use your Connector

Step 4a: Deploy and use your private Connector

You have come a long way. It’s time to sit back and relax! Your Connector can now be deployed and you will be able to see it in action. Let’s continue with our example and assume that you have followed all the steps and you have a Connector with one or more Connect applications that is ready to be deployed.

Make a GET request for your Connector and note down the id or key. You will need this data to create a deployment. Also, have a look at our documentation on deploying a Connector.

Deploying a Connector creates a running instance of it. You request a deployment by posting a deployment draft with the following parameters:

• A Connector reference using the id or key, and staged set to true if you plan to deploy a Staged version of the Connector.
• The service region (it is strongly recommended to deploy the Connector within the same region as your Project. Only Google Cloud Platform is presently supported for the Connect API).
• Configuration values for each Connect application as specified in the connect.yaml, and are needed by the Connector for hosting. This usually includes an API client with sufficient Scopes to perform the tasks in the Connect applications.

Let’s try making a request to:

curl https://connect.{region}.commercetools.com/{projectKey}/deployments -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \

With the payload like below updated to match your applications:

{
  "key" : "free-sample-training-connector-deployment",
  "connector" : {
    "key" : "free-sample-training-connector",
    "version" : 10
  },
  "region" : "europe-west1.gcp",
  "configurations" : [ {
   "applicationName" : "free-sample-product-service",
   "standardConfiguration": [
       {
           "key": "SAMPLE_PRODUCT_SKU",
           "value": "SMPL_SKU"
       }
   ],
   "securedConfiguration" : [...]
   },
   {
     ...other applications
   }
  ]
}

As with all steps above, this can also be done from the Merchant Center. Here creating a Deployment is called Installing a Connector.

You can monitor your deployment progress. It might take up to 15 minutes to have your Connector deployed.

After a successful deployment, Connect will run the post-deploy scripts mentioned in the connect.yaml file. Post-deploy scripts are used to create resources or to set up the environment as required by the Connect applications. For example, post-deploy scripts can:

• Create a Subscription in your Project for event type Connect applications.
• Create an API Extension in your Project for Connect applications of type service defined in your Connector.
• Create custom fields or other resources in your Project if your Connect application depends on it.

Your Connector should be working now. Read on for how to deploy and use a public Connector that comes along with its own source code.

Step 4b: Deploy and use a public Connector

To assist you in this process, commercetools Connect provides a separate /search endpoint. Here you can narrow down your search to keywords, names. Or you can restrict your search to certain creators.

For this part of the task, let’s search for a freely available, public, training example for which we can also provide the source code.

curl --get https://connect.{region}.commercetools.com/connectors/search?text=training&creator.company=commercetools -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

You should find the following Connector included in the response:

"id": ..,
"key": "free-sample-training-connector",
"version": ..
"name": "Self Learning Training Connector",

Exploring it further, you will see one Connect application included inside this Connector:

"applicationName": "free-sample-product-service",
"applicationType": "service",
"securedConfiguration": [ ],
"standardConfiguration": [ ]

You can explore the source code of this particular Connector. Now, let’s create a deployment.

• Make note of the id or key of the Connector as well as all the needed configurations.
• Create a deployment by posting a deployment draft.

curl https://connect.{region}.commercetools.com/deployments -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \

By posting a draft like:

{
  "key" : "free-sample-training-connector-deployment",
  "connector" : {
    "key" : "free-sample-training-connector",
    "version" : 12
  },
   "region" : "europe-west1.gcp",
   "configurations" : [ {
   "applicationName" : "free-sample-product-service",
   "standardConfiguration": [{
       ...
   }],
   "securedConfiguration": [{
       ...
   }]
  }]
}

Check the status of your deployment. (You can refer to the previous section, if needed, for more information on this process.)

If you see that the deployment failed because of a missing configuration key/value, you can update the deployment using the redeploy update action and providing the missing or incorrect configuration value as below.

curl https://connect.{region}.commercetools.com/deployments/key=free-sample-training-connector-deployment -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \

With the update request such as:

{
  "version": 1,
  "actions": [
    {
      "action": "redeploy",
      "configurationValues": [
        {
          "applicationName": "free-sample-product-service",
          "standardConfiguration": [
            {
              "key": "SAMPLE_PRODUCT_SKU",
              "value": "product-sku"
            }
          ],
          "securedConfiguration": [
            {
              "key": "CTP_PROJECT_KEY",
              "value": "project-key-value"
            }
          ]
        }
      ]
    }
  ]
}

When the status changes to deployed, you will notice that the deployed Connector has created the following resources in your project:

• A Service application that adds a configured sample product to carts when their total value is more than a certain amount. Installing this application also creates the following in your project:
  • A Channel called Free Sample Channel that will be used to control the inventory for our special sample item.
  • An inventory entry for the Channel and the SKU provided as configuration values during deployment.
  • An API Extension that is triggered every time a Cart update takes place in your Project.
• A Subscription that triggers an Event application every time a new product is published. The product is added to the configured new arrivals category if it was created less than 30 days ago.
• A Job application that runs daily and removes products older than 30 days from the new-arrivals category.

As always, you can deploy/install these Connectors from the Merchant Center following the steps outlined in the Deploy a marketplace Connector module.

We can test the Connector now by creating a Cart in the Merchant Center, under Orders > Add Order.

Amazing! Congratulations on deploying your Connector!

Review

Hey, great work! You have covered a lot of ground. Let's review the steps which we just covered in this module:

• We used a template to create a github repository.

This provided us with example code and a folder structure that fully complies with the requirements of a Connector. In this module we provided the source code for all our Connect applications.

• We declared Connect applications and their configurations in connect.yaml.

  All Connect applications that are part of our Connector must be defined in connect.yaml. One of those Connect applications was of type service.

• We created a ConnectorStaged.

  We used the Connect API and created a ConnectorStagedDraft with a reference to our Github repository and a git tag. This made our repository known to commercetools Connect.

• We updated the ConnectorStaged with the publish action.

  We triggered a publication process to start a thorough checking of our ConnectorStaged. After successful publication, the ConnectorStaged is now a Connector.

• We certified our Connector.

  We updated our Connector one more time with certification set to true. Now a much more thorough process started, which ended up by listing our Connector on the commercetools Marketplace.

• We deployed our (private or public) Connector.

  This provided us with a running instance of our Connector and proper runtime environments for all declared Connect applications. We also provided our Composable Commerce Project and API Client for our Connect application. commercetools Connect automatically created the required resources as defined in the post-deploy scripts. In the sample Connector, a Channel, an Inventory entry and an API Extension were created in the Composable Commerce Project.

The Connector started to work and every Cart update now triggers our Connect application to run and add a gift line item to the Cart.

Fantastic! Now it is time to review our knowledge related to deploying a Connector.

Test your knowledge