> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/code/marketplace/connection.md).

# Enable and configure a connection

Enable a marketplace listing on a project, configure and test the connection, disable or delete it.

**Where:** Code → Functions → **Find in Marketplace** → a listing · `/projects/<project>/code/marketplace/<listingId>` (enable: `…/<listingId>/enable`, configure: `…/<integrationId>/edit`)

A *connection* is a marketplace listing enabled on your project, with its settings and secrets. Its id starts with `int_`; the listing id starts with `ml_`.

{% hint style="warning" %}
Cloud cannot enable a listing yet: **Save** on the enable form fails with *CM-ERRORS-PROPERTY-001: Property ViewId is required*, because the server expects the caller to choose the id of the new connection and Cloud sends none. Enable it from code (below, with an id you make). Once a connection exists, Cloud shows it, configures it, tests it, and disables or deletes it.
{% endhint %}

## Before you start

* The Code module is on — see [Enable the module](/codemash/cloud/code.md#enable-the-module).
* For a vendor listing, its keys — for example a Slack **Bot token** (`xoxb-…`, see Slack's [token types](https://api.slack.com/authentication/token-types)). The Norbix built-ins (**Norbix Database**, **Norbix Web**) need no keys.
* You need `marketplace:create` to enable a listing, `marketplace:update` to change, test or disable it, `marketplace:delete` to delete it.

## Steps

1. Click a card in the [Marketplace](/codemash/cloud/code/marketplace.md), here **Slack**. The page shows the listing — name, description, category · transport, tags — the **Enable** button, the note *Enable this connection to add functions*, and **Available functions** with **Review** (read only).

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-eb20f8beca86247a4fcc19f3d52487f4118c9bc3%2Fconnection-1.png?alt=media" alt="The Slack listing: Communication · Rest, the Enable button, the note Enable this connection to add functions, and the function Send channel message (chat.postMessage, POST /chat.postMessage) with Review"><figcaption><p>A listing that is not enabled yet.</p></figcaption></figure>
2. Press **Enable**. The form is built from the listing:

   | Field                | Required            | What it does                                                                                                   | Example                                   |
   | -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
   | Configuration fields | as the listing says | Plain settings of the listing, with a default.                                                                 | **API base URL** `https://slack.com/api`  |
   | Secret fields        | as the listing says | Keys of the vendor. Stored encrypted; on edit the field stays empty — leave it empty to keep the stored value. | **Bot token** `xoxb-placeholder-not-real` |
   | Integration Name     | yes                 | How the connection is listed in Norbix.                                                                        | `Shop alerts Slack`                       |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-1112df55eed97b33e59c118d3fd0f719f704429a%2Fconnection-2.png?alt=media" alt="New Slack Integration: API base URL, Bot token with a documentation link, Integration Name, Cancel and Save"><figcaption><p>The enable form of Slack.</p></figcaption></figure>
3. Press **Save**. Today Cloud answers with the red box *CM-ERRORS-PROPERTY-001: Property ViewId is required* and nothing is saved — here for **Norbix Web**, named `Shop web reader`. Enable it from code instead ([Do it from code](#do-it-from-code)).

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-e243ea9993c7c22ccbb8d86f1752addbfe43a1a1%2Fconnection-3.png?alt=media" alt="New Norbix Web Integration with the name Shop web reader and the error CM-ERRORS-PROPERTY-001: Property ViewId is required"><figcaption><p>Enable fails in Cloud.</p></figcaption></figure>
4. Once the connection exists, its listing page, here **Norbix Database** (`Bookshop database`), shows the badges **ENABLED** and **TESTED** (or **NOT TESTED**), **Configure …**, **Actions**, the **Added functions** of the connection and **Available functions** with **Add …**.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-43039cfadcc98ba4d4d4b9216c40327da39dc2ad%2Fconnection-4.png?alt=media" alt="Norbix Database enabled: badges ENABLED and TESTED, Configure, Added functions with Find books (db.find, func_154strpl8cl6Kk4eL7k5Rj) and Available functions with Add"><figcaption><p>An enabled connection.</p></figcaption></figure>
5. Press **Configure …** (also in **Actions**). The edit page shows the badges, the connection id `int_4dotEqXT1UolAf5w6FqcMT`, the same fields as the enable form, and the test panel. Press **Test integration**: Norbix checks that the listing exists and that the required settings and secrets are filled — it does not call the vendor.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-a02998000c5e5fe17cdd7a005d09624efa0ab3e9%2Fconnection-6.png?alt=media" alt="Editing Norbix Database integration: ENABLED, TESTED, int_4dotEqXT1UolAf5w6FqcMT, Integration Name, and Test passed with the steps Resolve catalog listing and Validate config fields"><figcaption><p>Configure and test.</p></figcaption></figure>

## Result

The connection appears with the **Enabled** badge on its card in the [Marketplace](/codemash/cloud/code/marketplace.md), and its listing page offers **Add …** for each function — see [Add and call a function](/codemash/cloud/code/marketplace/function.md). The first test result stays on the connection: **TESTED** or **TEST FAILED**; until then the yellow note *Connection was not tested* is shown.

## Change or remove it later

The **Actions** menu of the edit page offers **Disable** (or **Enable**), links to the documentation (they point at an old address that does not open) and **Delete**.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-bea9b0bf76f3be4254766ea00675b4b699304a20%2Fconnection-7.png?alt=media" alt="The Actions menu of the Norbix Database connection: Disable, See Norbix documentation, See SDK documentation, See API documentation, Delete"><figcaption><p>Actions on a connection.</p></figcaption></figure>

* **Disable** — the connection and its functions stay, but its functions do not run; the listing page shows *Connection is disabled* and functions cannot be added or changed.
* **Delete** — removes the connection; only possible here.
* **Change secrets** — type a new value in the secret field and **Save**; an empty secret field keeps the stored value.

## Do it from code

The server wants the caller to choose the id of a new connection — a random UUID written as `int_` + base62. This is the only way to enable a listing today:

```ts
const newIntegrationId = () => {
  const b = crypto.randomUUID().replace(/-/g, '').match(/../g).map((h) => parseInt(h, 16));
  const le = [b[3], b[2], b[1], b[0], b[5], b[4], b[7], b[6], ...b.slice(8)];
  let v = 0n;
  for (let i = 15; i >= 0; i--) v = (v << 8n) + BigInt(le[i]);
  const chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
  let s = '';
  while (v > 0n) { s = chars[Number(v % 62n)] + s; v /= 62n; }
  return `int_${s}`;
};

const integrationViewId = newIntegrationId(); // for example int_1LIzQWUiMQFbVTwFCbnkg0
await norbix.hub.code.saveMarketplaceIntegration({
  integration: {
    viewId: integrationViewId,
    integrationName: 'Archive database',
    isEnabled: true,
    listingViewId: 'ml_norbix_database_v1',
    transport: 'Internal',
    vendor: 'Norbix',
    category: 'Database',
    config: {},
  },
  secrets: {}, // for Slack: { botToken: 'xoxb-…' }
});
await norbix.hub.code.testMarketplaceIntegration({ integrationViewId });
await norbix.hub.code.disableMarketplaceIntegration({ integrationViewId });
await norbix.hub.code.deleteMarketplaceIntegration({ integrationViewId });
```

```sh
norbix hub code marketplace integration save --integration:json '{"viewId":"int_1GwJEFn6leCTq8OBJPr1M6","integrationName":"Reports database","isEnabled":true,"listingViewId":"ml_norbix_database_v1","transport":"Internal","vendor":"Norbix","category":"Database","config":{}}'
```

`listingViewId`, `transport`, `vendor` and `category` come from [Get Marketplace Listing](/codemash/api-reference/code/marketplace/get-marketplace-listing.md). API: [Save Marketplace Integration](/codemash/api-reference/code/marketplace/save-marketplace-integration.md) · [Test Marketplace Integration](/codemash/api-reference/code/marketplace/test-marketplace-integration.md) · [Disable](/codemash/api-reference/code/marketplace/disable-marketplace-integration.md) · [Enable](/codemash/api-reference/code/marketplace/enable-marketplace-integration.md) · [Delete Marketplace Integration](/codemash/api-reference/code/marketplace/delete-marketplace-integration.md) · [Replace Marketplace Integration Secrets](/codemash/api-reference/code/marketplace/replace-marketplace-integration-secrets.md)