Overview

This page builds the container every integration needs before any business event, webhook, or view attaches.

When You Would Build One

Every build path starts here; Integration Categories describes what each adds.

You want	This page gives you
A partner integration	Campaign, root, model component
A tile on the Integrations page	Eight display settings and a resolving `logo`
A configuration tab	The `config-view-v10.0` child

How to Build

Create the Integration Campaign

Create an INTEGRATION campaign with the integration program type. Its tag names the integration component this campaign carries, as library bundles do; the component tags added next are what list it on the Integrations page.

curl --request POST "$EXTOLE_API_HOST/v2/campaigns" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Example Integration",
    "description": "Receives partner lifecycle events and maps them to Extole business events.",
    "campaign_type": "INTEGRATION",
    "program_type": "integration",
    "tags": ["internal:integration-component-name:example"]
  }'

Record the identifier and version. Creation adds a default PROGRAM label equal to the campaign identifier; replace it when the contract defines one:

curl --request POST "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/labels" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example-integration",
    "type": "PROGRAM"
  }'

One active PROGRAM label per campaign; creating one replaces the previous.

Create the Component Model

Create a root component following the Custom Integration Template conventions. Leave internal:type:integration off it; the Integrations page excludes roots.

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/version/$CAMPAIGN_VERSION/components" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "root",
    "description": "Declares campaign-level variables and cross-campaign inheritance.",
    "tags": ["internal:self-managed"]
  }'

Record ROOT_COMPONENT_ID, refresh the campaign version, and create the model component with all eight display settings in one request:

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/version/$CAMPAIGN_VERSION/components" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "example",
    "display_name": "Example",
    "description": "Receives Example lifecycle events.",
    "types": [
      "integration-v10.0"
    ],
    "component_ids": [
      "'"$ROOT_COMPONENT_ID"'"
    ],
    "tags": [
      "internal:type:integration",
      "internal:self-managed"
    ],
    "variables": [
      {
        "name": "short.description",
        "type": "STRING",
        "values": {
          "default": "Connect Example lifecycle events to Extole."
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "about",
        "type": "STRING",
        "values": {
          "default": "This integration receives Example events and maps them to Extole business events."
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "documentation.url",
        "type": "STRING",
        "values": {
          "default": "https://docs.extole.com/docs/example"
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "external.url",
        "type": "STRING",
        "values": {
          "default": "PARTNER_PRODUCT_SITE"
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "external.integration.url",
        "type": "STRING",
        "values": {
          "default": "PARTNER_MARKETPLACE_LISTING"
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "categories",
        "type": "STRING",
        "values": {
          "default": "eCommerce Platform"
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "logo",
        "type": "IMAGE",
        "values": {
          "default": "ASSET_HOST_LOGO_URL"
        },
        "tags": [
          "internal:ui-display"
        ]
      },
      {
        "name": "imageKey",
        "type": "STRING",
        "values": {
          "default": "example"
        },
        "tags": [
          "internal:ui-display"
        ]
      }
    ]
  }'

Use variables; CampaignComponentCreateRequest has no settings property. Replace PARTNER_PRODUCT_SITE, PARTNER_MARKETPLACE_LISTING, and ASSET_HOST_LOGO_URL with absolute URLs. integration-v10.0 is the long-standing revision, later ones such as integration-v10.1 exist, so keep an installed source’s own type.

Set Integration Display Metadata

The type checks only that all eight are present, not that their values are usable. Tag every one internal:ui-display, exactly that string — the tag marks tile metadata and hides the setting from the settings list.

short.description — one tile sentence.
about — what the integration receives and sends.
documentation.url — the partner-facing page for this integration, not this guide.
external.url — the partner’s product site.
external.integration.url — the partner’s marketplace or extension listing, or an empty string.
categories — one STRING category other integrations already use, such as eCommerce Platform; the admin groups by exact value, so copy it from a working integration.
logo — the IMAGE the Integrations page renders, covered below.
imageKey — the key the platform resolves to its own stored partner image, read by the older partner detail view rather than the tile; take it from the partner page.

Set a Logo That Resolves

The Integrations page renders the built value of logo:

curl --request GET \
  "$EXTOLE_API_HOST/v1/components/built?having_all_tags=internal:type:integration&limit=50" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN"

A resolved logo is an absolute URL on Extole’s asset host, such as an originAssetId path:

{
  "name": "logo",
  "type": "IMAGE",
  "values": { "default": "ASSET_HOST_LOGO_URL" }
}

A registered component for this partner exists — copy its built logo URL from /v1/components/built, never /v1/components, whose source listing returns an unresolved expression naming an asset your component does not own.
No registered component has it — take an absolute URL from the partner’s site: the og:image meta tag, the header logo <img>, or a brand-assets download link. Prefer PNG or SVG over a sprite or background image.
You have the file — upload it as an asset, then set logo to spel@buildtime:context.getAsset('example').getUrl().
The partner has neither — track logo as outstanding until the real file arrives.

Confirm an address answers with the image before storing it. To upload, send multipart form data with the metadata in an asset part and the bytes in a file part:

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/components/$INTEGRATION_COMPONENT_ID/assets" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --form 'asset={"name":"example","tags":[],"description":"Example Logo"};type=application/json' \
  --form "file=@example.png;type=image/png"

The expression builds into a hosted URL on the account’s asset domain. A reward integration repeats this with reward-supplier-logo, exposed as rewardSupplierLogo, on every supplier template. logo is IMAGE and required, so "default": "" is rejected:

{
  "code": "settings_build_failed",
  "parameters": { "errors": { "logo": {
    "code": "variable_value_invalid_type",
    "expected_types": ["IMAGE"],
    "details": "The value: is not valid for the type:IMAGE"
  } } }
}

Add the Partner Settings

Add partner configuration settings separately, each with a display name, description, type, default, importance:basic, and a priority, prefixed with the integration component name — exampleAccountUrl, exampleSetupInstructions.

Never tag a partner configuration setting internal:ui-display, and never place a credential value in a setting the configuration view displays.

Setup instructions carry the event endpoint, the current program label, the event names, the payload fields, the credential rule, and the documentation link, which Send Platform Events to Extole tells implementers to read from this view. Compute them at build time, substituting the campaign’s program label for PROGRAM_LABEL:

{
  "name": "exampleSetupInstructions",
  "type": "STRING",
  "display_name": "Example Extension Setup",
  "description": "Connection details for the server-side Example extension.",
  "tags": ["category:configuration", "importance:basic"],
  "priority": "20",
  "values": {
    "default": "javascript@buildtime:(function(){ return \"Extole event endpoint: POST /v6/events — see Send Platform Events to Extole\\nProgram label (send as data.labels): PROGRAM_LABEL\\nEvent names: example_order_created, example_order_shipped, example_order_canceled\\nUse a server-side access token from the Security Center. Do not use a token that can manage campaigns in the partner application.\"; })()"
  }
}

The value is interpolated at creation, so replacing the campaign’s PROGRAM label means updating this setting too.

Add Typed Sockets

Add a businessEvents multi-socket:

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/version/$CAMPAIGN_VERSION/components/$INTEGRATION_COMPONENT_ID/settings" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "businessEvents",
    "display_name": "Business Events",
    "description": "Reusable business events produced from partner input events.",
    "type": "MULTI_SOCKET",
    "filters": [
      {
        "type": "COMPONENT_TYPE",
        "component_type": "business-event-v10.0"
      }
    ]
  }'

Add a views multi-socket:

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/version/$CAMPAIGN_VERSION/components/$INTEGRATION_COMPONENT_ID/settings" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "views",
    "display_name": "Views",
    "description": "Views rendered in the integration UI.",
    "type": "MULTI_SOCKET",
    "filters": [
      {
        "type": "COMPONENT_TYPE",
        "component_type": "view-v10.0"
      }
    ]
  }'

Declare a type on every socket and attach only components that satisfy it. view-v10.0 is the parent of every view type, so one filter accepts the configuration view below plus the report-runner-view-v10.0 and event-stream-view-v10.0 children from Add the Activity and Event Views.

Add a Configuration View

Create a config-view-v10.0 child attached to the integration model component:

curl --request POST \
  "$EXTOLE_API_HOST/v2/campaigns/$CAMPAIGN_ID/version/$CAMPAIGN_VERSION/components" \
  --header "Authorization: Bearer $MANAGEMENT_API_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "configuration",
    "display_name": "Configuration",
    "description": "Configuration view for the Example integration.",
    "types": [
      "config-view-v10.0"
    ],
    "installed_into_socket": "views",
    "component_ids": [
      "'"$INTEGRATION_COMPONENT_ID"'"
    ],
    "variables": [
      {
        "name": "order",
        "type": "INTEGER",
        "values": {
          "default": 1
        }
      },
      {
        "name": "title",
        "type": "STRING",
        "values": {
          "default": "Configuration"
        }
      },
      {
        "name": "status",
        "type": "STRING",
        "values": {
          "default": "javascript@buildtime:context.getComponent().getParent().getVariableValue(\"exampleAccountUrl\") ? \"READY\" : \"IN_PROGRESS\""
        }
      },
      {
        "name": "settingsToDisplay",
        "type": "STRING_LIST",
        "values": {
          "default": [
            "exampleAccountUrl",
            "exampleSetupInstructions"
          ]
        }
      }
    ]
  }'

component_ids takes the parent model component, which owns the views socket, and settingsToDisplay names parent settings only, including exampleSetupInstructions. Set status from a buildtime expression so the tab reports READY only once the settings Extole can verify are complete.

How to Test

Read the built component with GET /v1/components/built?having_all_tags=internal:type:integration and confirm logo resolved to an absolute URL on Extole’s asset host, every settingsToDisplay name appears with its display name, and the component sits under the root with internal:self-managed and both sockets filled.

Troubleshooting

Symptom	Cause	Fix
`settings_build_failed`, `variable_value_invalid_type`, `expected_types: ["IMAGE"]`	`logo` sent empty	A resolvable URL or buildtime asset expression
Create rejected	Only some of the eight display settings sent; no later mutation adds them	Send all eight in one create
Grey Extole placeholder	Built `logo` is an expression, or its URL 404s, redirects, or returns HTML — as Extole documentation images and favicons do	Read `/v1/components/built` and replace it
Display settings show beside the partner’s	A tag other than `internal:ui-display`	Retag all eight
A `settingsToDisplay` name never appears	That setting carries `internal:ui-display`	Remove the tag
A `settingsToDisplay` name fails validation	No parent setting has it	Create it or drop the name
The integration groups nowhere, or alone	`categories` sent as `STRING_LIST`, or a new spelling	One existing category, typed `STRING`
The view installs into the root, which lacks `views`	`component_ids` omitted	Recreate with the parent component
Configuration tab stuck in progress	`status` hardcoded	Use a buildtime expression

Integration Overview

Extole AI Tools

Platform Integrations

Partners

Building Packaged Integrations

Solutions

Operational Tasks

Troubleshooting

Create the Integration Campaign and Component Model

Overview

When You Would Build One

How to Build

Create the Integration Campaign

Create the Component Model

Set Integration Display Metadata

Set a Logo That Resolves

Add the Partner Settings

Add Typed Sockets

Add a Configuration View

How to Test

Troubleshooting

​Overview

​When You Would Build One

​How to Build

​Create the Integration Campaign

​Create the Component Model

​Set Integration Display Metadata

​Set a Logo That Resolves

​Add the Partner Settings

​Add Typed Sockets

​Add a Configuration View

​How to Test

​Troubleshooting

Overview

When You Would Build One

How to Build

Create the Integration Campaign

Create the Component Model

Set Integration Display Metadata

Set a Logo That Resolves

Add the Partner Settings

Add Typed Sockets

Add a Configuration View

How to Test

Troubleshooting