Install and test your Connector

Zen Electron's Deployment says it succeeded, but no email arrives. By the end of this page, you can tell in one request whether the Connector is wired up, and you have seen an Order reach it.

Choose an install route

The Merchant Center has no sandbox install. If your Project is a trial, production isn't available either, so install a published Connector to sandbox with the CLI or the API.

Choose the Region and environment

Install with the Connect CLI

commercetools connect deployment create \
  --connector-key zen-order-confirmation \
  --key zen-order-confirmation-sandbox \
  --region europe-west1.gcp \
  --type sandbox \
  "${CONFIG[@]}"

commercetools connect deployment describe --key zen-order-confirmation-sandbox

Install with the Connect API

jq -n --argjson configurations "$CONFIGURATIONS" '{
  key: "zen-order-confirmation-sandbox",
  type: "sandbox",
  connector: { key: "zen-order-confirmation" },
  region: "europe-west1.gcp",
  configurations: $configurations
}' | curl -sS --fail-with-body -X POST "$CONNECT_URL/$CTP_PROJECT_KEY/deployments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @- | jq '{key, type, status}'

• connector: omit staged: true to reference the published Connector instead of the ConnectorStaged. The CLI has no flag for version, so the status check below shows which version was deployed.
• configurations: applicationName must match deployAs[].name in connect.yaml.

Poll the status:

curl -sS --fail-with-body "$CONNECT_URL/$CTP_PROJECT_KEY/deployments/key=zen-order-confirmation-sandbox" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, connector: .connector.version}'

Install from the Merchant Center

• Connector: select Zen Electron order confirmation on the Organization connectors tab, and use Deploy on Production for the published Connector.
• Projects: on production, choose the specific Project that you're testing in.
• Fields: one for each key in your connect.yaml: CTP_REGION and the eight secured keys. Use the values from the CONFIG array. The deployment step also displays the scopes that inheritAs requests for the generated API Client, so nobody enters commercetools credentials.

Verify the resource, not the status

curl -sS --fail-with-body -G \
  "https://api.$CTP_REGION.commercetools.com/$CTP_PROJECT_KEY/subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'where=key="ct-connect-email-delivery-subscription"' \
  | jq '.results[] | {key, status, destination: .destination.type, messages}'

A working installation returns one Subscription:

{
  "key": "ct-connect-email-delivery-subscription",
  "status": "Healthy",
  "destination": "GoogleCloudPubSub",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": ["OrderCreated", "OrderImported"]
    }
  ]
}

Read the result as follows:

• No result: postDeploy didn't create the Subscription, whatever the Deployment says. Check the destination validator change and the inheritAs scopes in connect.yaml, then redeploy.
• status other than Healthy: the Subscription exists, but delivery has a problem. Look up the value in SubscriptionHealthStatus to see whether delivery is still being retried. Operate a Deployment covers what to do.
• messages with Customer types: the Deployment runs a tag from before Implement and test the event app to the contract. Check connector.version on the Deployment.
• destination is SNS: the Project is in an AWS Region. The template doesn't decode the SNS envelope, as noted in Implement and test the event app to the contract.

Trigger an Order

ORDER_NUMBER="ZE-$(date +%s)"
SKU="ZE-MON-4K" # Replace with the SKU of a Product Variant in your Project.

curl -sS --fail-with-body -X POST \
  "https://api.$CTP_REGION.commercetools.com/$CTP_PROJECT_KEY/orders/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"orderNumber\": \"$ORDER_NUMBER\",
    \"customerEmail\": \"learner@example.com\",
    \"totalPrice\": { \"currencyCode\": \"AUD\", \"centAmount\": 4900 },
    \"lineItems\": [
      {
        \"name\": { \"en-US\": \"Zen Electron 4K monitor\" },
        \"variant\": { \"sku\": \"$SKU\" },
        \"quantity\": 1,
        \"price\": { \"value\": { \"currencyCode\": \"AUD\", \"centAmount\": 4900 } }
      }
    ]
  }" | jq '{id, orderNumber}'

• orderNumber is generated per run, because repeating a number fails the import.
• customerEmail is the recipient. Without it and without a customerId, the template skips the Order.
• name has an en-US key, because the template reads line item names from that locale only.

Find the work in the logs

commercetools connect deployment logs \
  --key zen-order-confirmation-sandbox \
  --application mail-sender

Email provider stub: email not sent {"sender":"orders@example.com","templateId":"order-confirmation","lineItemCount":1}
Order confirmation handed to email provider {"messageType":"OrderImported","resourceId":"<order-id>","sequenceNumber":1}

If no line appears within a few minutes:

• Wait a minute after a new Deployment. Deliveries in the first minute can be rejected with 401 while Connect sets up push authentication. Pub/Sub retries them, and they then succeed.
• Check for a cold start. On sandbox, the first Message after an idle period can arrive late.
• Check the Subscription again. If it's missing or unhealthy, the Message never reached the application.

Worked example: install Zen Electron's Connector

1. Install zen-order-confirmation to sandbox with deployment create and wait for Deployed.
2. Query the Subscription by key: one result, Healthy, GoogleCloudPubSub, and the two Order Message types.
3. Import an Order with a new order number.
4. Find one Order confirmation handed to email provider line with the imported Order's ID.

One Order produced one stubbed send. Zen Electron has proved the full path, from Order to Subscription to Connector, without trusting the Deployment status.

Keep this Deployment. The next page operates it.

Key takeaways

• Installing your own private Connector is the same Client task as installing a public one.
• The Merchant Center offers preview and production installs. Use the CLI or the API for sandbox, which is the route for trial Projects.
• Deploy in the Project's Region, which Connect recommends, and within the Connector's supportedRegions. Connect supports Google Cloud and AWS Regions.
• A Deployment can report success when postDeploy failed. Prove the installation by querying the resource it creates, such as the Subscription, by key.
• Trigger the Connector with a real platform event, such as an imported Order, and confirm the work in the Deployment logs.
• Expect delays right after deployment and after a sandbox cold start before you debug.

Test your knowledge