Skip to main content
Every integration in the harness has a console at /integrations/<slug>. It shows the integration the way a consumer sees it: as a contract with operations you can run, events you can emit, a connection you can set up, and a health check. The surfaces the harness always rendered (widgets, the marketplace tile, the activation form and triggers) are one tab of it, Preview. The console is the home of a single-integration project (/ redirects to /integrations, which forwards to your one integration), and in a repo there is one per integration package.

​
The tabs

​
Overview

Shows the integration slug, package and contract versions with the contract’s digest, the connection it needs (none, api_key, oauth2, with the levels it supports: team, user), and how many operations and events it declares. A quiet Supports: line says whether it can run on Fixtures, Live or both. A package of your repo reads “Local · this repo” with one line of provenance (“Running from this repo.”). Paths are repo-relative, with the absolute path in a tooltip.

​
Connect

The connection status, in one word and always the same word across the harness: Connected, Not connected, No connection needed or Managed by Ekanos. Below it, the form that stores credentials, and Disconnect. Connecting integrations covers what is stored where.
  • An integration whose credentials are API keys declared in code shows a keys form.
  • An integration whose credentials are the fields of its activation form shows that form here, so you never need the Preview tab to connect.
  • An integration that declares oauth shows the Local OAuth panel and a Connect button. The panel lists the redirect URL to register with the provider: http://localhost:<port>/api/integrations/<slug>/oauth/callback (port 3100 unless you passed --port).
  • An integration that needs no connection says No connection needed. Its settings, if it has any, are optional (“Settings below are optional.” with a Save settings button).

​
Operations

Lists the contract’s operations. Each is marked Read or Write and has a runner: a form generated from its input schema (or raw JSON), a Fixtures or Live choice where the integration supports it, and the result with a badge saying whether it satisfies the output schema. A write does not run at once: it is held in the approvals tray, and the pending-approval card reads, for example, “1 write waiting for approval: acme-social draft_post”, with the payload behind Show details.

​
Events

Pick one of the contract’s events, edit its payload (the contract’s example is the starting point), and emit it. In Fixtures mode the harness validates the payload and lists the workflow triggers that would match. In Live mode it runs the integration’s own handler.

​
Health

Run health check runs the integration’s health check. Until you do, the page says “Not run yet”. The result is healthy, degraded, unhealthy or unknown, with the integration’s message.

​
Run log

Every call made through the harness in this session, newest first: time, operation, where it ran from, mode, channel, and status. It shows the latest 50; Show more loads more. Filter by outcome and by integration: A refused or failed row has its reason (operation_not_declared, invalid_input, …) and, under it, a plain-language line saying what to do. “No runs match these filters.” means the filters excluded everything.

​
Preview

The surfaces that render your integration in Ekanos chrome: Widgets, Marketplace tile, Activation form and Triggers. A section appears only if the integration uses it. This is where fixtures, the toolbar and triggers live. The old addresses /<slug>, /<slug>/widgets, /<slug>/widgets/<widgetId>, /<slug>/tile, /<slug>/activation and /<slug>/triggers still work: they redirect to the matching Preview address and keep the query string, because an OAuth return carries its result there.
The Preview tab is generated by ekanos dev. After upgrading @ekanos/cli and @ekanos/harness to the versions that add it (shell contract 5), run ekanos dev again so the shell is regenerated.

​
Next steps