HomeEngagementContentDiscoveryOther resources
Guides

ConnectorStaged

Integration

Suggest Edits

This following article is a guide on how to create and manage a ConnectorStaged.

The Commercetools ConnectorStaged represents the draft version of a Connector. It references a Repository, which links the connector to the codebase representing the integration.

Once you have finished developing and updating a ConnectorStaged, use the Publish update action to create a Connector ready for production. Once published, the read-only version of the Connector will be created and updated.

Create a ConnectorStaged

ConnectorStaged is how non-certified versions of Connectors are stored. Even after being certified and listed, a ConnectorStaged can be modified (to fix bugs and add new features) and re-certified to update the production Connector.

ConnectorStaged are created by posting a ConnectorStagedDraft to the /connectors/drafts endpoint:

curl --location 'https://connect.us-central1.gcp.commercetools.com/connectors/drafts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ token }}' \
--data-raw '{
    "key": "orium-ct-connect-bloomreach-engagement",
    "name": "Bloomreach Engagement connector",
    "description": "Bloomreach Engagement connector",
    "creator": {
        "title": "Mr",
        "name": "IT",
        "email": "[email protected]",
        "company": "Orium",
        "noOfDevelopers": 10
    },
    "repository": {
        "url": "[email protected]:composable-com/ct-connect-bloomreach-engagement.git",
        "tag": "v1.0.0"
    },
    "privateProjects": [],
    "supportedRegions": [
        "us-central1.gcp"
    ]
}'

Preview connectors

After creating your ConnectorStaged you can request a previewable status. This status will allow you to deploy your ConnectorStaged for testing and preview purposes without requiring certification.

Use the Preview Connector update action to request previewable status for your ConnectorStaged:

curl --location 'https://connect.us-central1.gcp.commercetools.com/connectors/drafts/key=orium-ct-connect-bloomreach-engagement' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ token }}' \
--data-raw '{
  "version" : 1,
  "actions" : [ {
    "action" : "updatePreviewable"
  } ]
}'

Query ConnectorStaged

curl --get https://connect.us-central1.gcp.commercetools.com/connectors/drafts/key=orium-ct-connect-bloomreach-engagement \
--header 'Authorization: Bearer {{ token }}' | json_pp

You should get something similar to this:

{
  "alreadyListed": false,
  "configurations": [
    {
      "applicationName": "service",
      "applicationType": "service",
      "securedConfiguration": [
        {
          "description": "commercetools Composable Commerce project key",
          "key": "CTP_PROJECT_KEY"
        },
        {
          "description": "commercetools Composable Commerce client ID",
          "key": "CTP_CLIENT_ID"
        },
        {
          "description": "commercetools Composable Commerce client secret",
          "key": "CTP_CLIENT_SECRET"
        },
        {
          "description": "commercetools Composable Commerce client scope",
          "key": "CTP_SCOPE"
        },
        {
          "description": "Bloomreach API key",
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY"
        },
        {
          "description": "Bloomreach API secret",
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET"
        },
        {
          "description": "Bloomreach project token",
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN"
        },
        {
          "description": "Bloomreach catalog locale",
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE"
        },
        {
          "description": "HTTP basic auth password",
          "key": "BASIC_AUTH_SECRET"
        }
      ],
      "standardConfiguration": [
        {
          "description": "commercetools Composable Commerce API region",
          "key": "CTP_REGION"
        }
      ]
    },
    {
      "applicationName": "event",
      "applicationType": "event",
      "securedConfiguration": [
        {
          "description": "commercetools Composable Commerce project key",
          "key": "CTP_PROJECT_KEY"
        },
        {
          "description": "commercetools Composable Commerce client ID",
          "key": "CTP_CLIENT_ID"
        },
        {
          "description": "commercetools Composable Commerce client secret",
          "key": "CTP_CLIENT_SECRET"
        },
        {
          "description": "commercetools Composable Commerce client scope",
          "key": "CTP_SCOPE"
        },
        {
          "description": "Bloomreach API key",
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY"
        },
        {
          "description": "Bloomreach API secret",
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET"
        },
        {
          "description": "Bloomreach project token",
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN"
        },
        {
          "description": "Bloomreach catalog locale",
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE"
        },
        {
          "description": "HTTP basic auth password",
          "key": "BASIC_AUTH_SECRET"
        }
      ],
      "standardConfiguration": [
        {
          "description": "commercetools Composable Commerce API region",
          "key": "CTP_REGION"
        }
      ]
    }
  ],
  "creator": {
    "company": "Orium",
    "email": "[email protected]",
    "name": "IT",
    "title": "Mr"
  },
  "description": "Bloomreach Engagement connector",
  "hasChanges": true,
  "id": "df328165-3684-4d22-8dc9-fc8bd466115b",
  "isPreviewable": "true",
  "key": "orium-ct-connect-bloomreach-engagement",
  "name": "Bloomreach Engagement connector",
  "previewableReport": {
    "entries": [
      {
        "createdAt": "2023-09-11T16:31:44.963Z",
        "title": "Image security analysis check succeeded",
        "type": "Information"
      },
      {
        "createdAt": "2023-09-11T16:31:44.967Z",
        "title": "SAST and SCA analysis check succeeded",
        "type": "Information"
      },
      {
        "createdAt": "2023-09-11T16:31:44.967Z",
        "title": "Connector specification file validation check succeeded",
        "type": "Information"
      }
    ]
  },
  "private": true,
  "repository": {
    "tag": "v1.0.0",
    "url": "[email protected]:composable-com/ct-connect-bloomreach-engagement.git"
  },
  "status": "Draft",
  "supportedRegions": ["us-central1.gcp"],
  "version": 7
}

Create a deployment

Deployments are created by posting a DeploymentDraft to the Deployments endpoint.

You must include a reference to the Connector that will be deployed (using the Connector's id or key and version), the Region where the deployment will be made, and also the environment variables necessary for the Connector to operate. It is recommended to include a key to identify your Deployment:

curl --location 'https://connect.us-central1.gcp.commercetools.com/composable-product-dev-sandbox/deployments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ token }}' \
--data-raw '{
  "key": "orium-ct-connect-bloomreach-engagement-deployment",
  "connector": {
    "key": "orium-ct-connect-bloomreach-engagement",
    "staged": true,
    "version": 7
  },
  "region": "us-central1.gcp",
  "configurations": [
    {
      "applicationName": "event",
      "standardConfiguration": [
        {
          "key": "CTP_REGION",
          "value": "us-central1.gcp"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_CLIENT_ID",
          "value": "{{ SECRET }}"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "{{ SECRET }}"
        },
        {
          "key": "CTP_PROJECT_KEY",
          "value": "composable-product-dev-sandbox"
        },
        {
          "key": "CTP_SCOPE",
          "value": "manage_project:composable-product-dev-sandbox manage_api_clients:composable-product-dev-sandbox view_audit_log:composable-product-dev-sandbox"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
          "value": "en-US"
        },
        {
          "key": "BASIC_AUTH_SECRET",
          "value": "{{ SECRET }}"
        }
      ]
    },
    {
      "applicationName": "service",
      "standardConfiguration": [
        {
          "key": "CTP_REGION",
          "value": "us-central1.gcp"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_CLIENT_ID",
          "value": "{{ SECRET }}"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "{{ SECRET }}"
        },
        {
          "key": "CTP_PROJECT_KEY",
          "value": "composable-product-dev-sandbox"
        },
        {
          "key": "CTP_SCOPE",
          "value": "composable-product-dev-sandbox manage_api_clients:composable-product-dev-sandbox view_audit_log:composable-product-dev-sandbox"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
          "value": "{{ SECRET }}"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
          "value": "en-US"
        },
        {
          "key": "BASIC_AUTH_SECRET",
          "value": "{{ SECRET }}"
        }
      ]
    }
  ]
}'

You should get something similar to this:

{
  "id": "834bd4ed-b380-4b42-b9d8-bf8dd0a683aa",
  "key": "orium-ct-connect-bloomreach-engagement-deployment",
  "version": 1,
  "connector": {
    "id": "df328165-3684-4d22-8dc9-fc8bd466115b",
    "version": 7,
    "name": "Bloomreach Engagement connector",
    "description": "Bloomreach Engagement connector",
    "creator": {
      "name": "IT",
      "title": "Mr",
      "email": "[email protected]",
      "company": "Orium"
    },
    "repository": {
      "url": "[email protected]:composable-com/ct-connect-bloomreach-engagement.git",
      "tag": "v1.0.0"
    },
    "configurations": [
      {
        "applicationName": "service",
        "applicationType": "service",
        "standardConfiguration": [
          {
            "key": "CTP_REGION",
            "description": "commercetools Composable Commerce API region"
          }
        ],
        "securedConfiguration": [
          {
            "key": "CTP_PROJECT_KEY",
            "description": "commercetools Composable Commerce project key"
          },
          {
            "key": "CTP_CLIENT_ID",
            "description": "commercetools Composable Commerce client ID"
          },
          {
            "key": "CTP_CLIENT_SECRET",
            "description": "commercetools Composable Commerce client secret"
          },
          {
            "key": "CTP_SCOPE",
            "description": "commercetools Composable Commerce client scope"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
            "description": "Bloomreach API key"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
            "description": "Bloomreach API secret"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
            "description": "Bloomreach project token"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
            "description": "Bloomreach catalog locale"
          },
          {
            "key": "BASIC_AUTH_SECRET",
            "description": "HTTP basic auth password"
          }
        ]
      },
      {
        "applicationName": "event",
        "applicationType": "event",
        "standardConfiguration": [
          {
            "key": "CTP_REGION",
            "description": "commercetools Composable Commerce API region"
          }
        ],
        "securedConfiguration": [
          {
            "key": "CTP_PROJECT_KEY",
            "description": "commercetools Composable Commerce project key"
          },
          {
            "key": "CTP_CLIENT_ID",
            "description": "commercetools Composable Commerce client ID"
          },
          {
            "key": "CTP_CLIENT_SECRET",
            "description": "commercetools Composable Commerce client secret"
          },
          {
            "key": "CTP_SCOPE",
            "description": "commercetools Composable Commerce client scope"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
            "description": "Bloomreach API key"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
            "description": "Bloomreach API secret"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
            "description": "Bloomreach project token"
          },
          {
            "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
            "description": "Bloomreach catalog locale"
          },
          {
            "key": "BASIC_AUTH_SECRET",
            "description": "HTTP basic auth password"
          }
        ]
      }
    ],
    "supportedRegions": ["us-central1.gcp"],
    "certified": false
  },
  "deployedRegion": "us-central1.gcp",
  "applications": [
    {
      "id": "80ca7d5b-78ec-4f58-9aad-7c3fc2975dfa",
      "applicationName": "event",
      "standardConfiguration": [
        { "key": "CTP_REGION", "value": "us-central1.gcp" }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_CLIENT_ID",
          "value": "***"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "***"
        },
        {
          "key": "CTP_PROJECT_KEY",
          "value": "***"
        },
        {
          "key": "CTP_SCOPE",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
          "value": "*****"
        },
        {
          "key": "BASIC_AUTH_SECRET",
          "value": "***"
        }
      ]
    },
    {
      "id": "773c6714-6081-4976-ab16-f8aff7998f87",
      "applicationName": "service",
      "standardConfiguration": [
        { "key": "CTP_REGION", "value": "us-central1.gcp" }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_CLIENT_ID",
          "value": "***"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "***"
        },
        {
          "key": "CTP_PROJECT_KEY",
          "value": "***"
        },
        {
          "key": "CTP_SCOPE",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_KEY",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_API_SECRET",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_PROJECT_TOKEN",
          "value": "***"
        },
        {
          "key": "BLOOMREACH_ENGAGEMENT_CATALOG_LOCALE",
          "value": "*****"
        },
        {
          "key": "BASIC_AUTH_SECRET",
          "value": "***"
        }
      ]
    }
  ],
  "details": {},
  "preview": true,
  "status": "Deploying"
}

Get a deployment

curl --get https://connect.us-central1.gcp.commercetools.com/composable-product-dev-sandbox/deployments/key=orium-ct-connect-bloomreach-engagement-deployment \
--header 'Authorization: Bearer {{ token }}' | json_pp

Request certification

After creating and/or previewing your ConnectorStaged, use the Publish update action with certification set to true to submit the ConnectorStaged for final certification and to be listed for production-ready deployments.

Learn more here.

Request preview for ConnectorStaged

Use the Preview Connector update action to request previewable status for your ConnectorStaged:

curl --location 'https://connect.us-central1.gcp.commercetools.com/connectors/drafts/key=orium-ct-connect-bloomreach-engagement' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{ token }}' \
--data-raw '
{
  "version": 1,
  "actions": [
    {
      "action": "publish",
      "certification": true
    }
  ]
}'

Monitor certification status

After triggering the certification process, the Connect team will review your ConnectorStaged. The status can be monitored by getting the ConnectorStaged and viewing the status field.

The Connect team may ask questions about your ConnectorStaged. This will change the status to FEEDBACK_REQUIRED. Comments can be viewed in the certificationInfo field of your ConnectorStaged. You can submit comments using the Add Certification Comment update action.

Once your ConnectorStaged is certified, a production Connector is created that contains the content of the ConnectorStaged. This production Connector then becomes available for deployment, and the value of alreadyListed will change to true.

Update connectors

If you update your Connect application to fix bugs or add new features, follow these steps to update the Connector:

  1. Update your GitHub repository with the new Connect application.
  2. Generate a new Git tag/release.
  3. Make changes in the GitHub repository as needed, ensuring that connect.yaml represents the new ConnectorConfigurationApplication.
  4. Use the Set Repository update action and include the GitHub repository URL and the new Git tag.
  5. Use the Publish update action to submit your updated application for certification.

Updated about 1 month ago

What´s next?