guides

ByteChef Embedded, Part 12: The Automation Hub

ByteChef Embedded, Part 12: The Automation Hub
19 min read
Ivica Čardić

TL;DR: The Automation Hub is a complete automations page in one component. Render <AutomationHub jwtToken={token} /> from @bytechef/embedded 0.4.0 and your connected users get the catalog of templates you released to their environment, a Connect, Configure, Activate dialog that turns a template into a running automation on their own accounts, clear "needs attention" reasons, a Connections tab, and the embedded workflow builder. On the admin side, a template reaches users only when you publish the project and release a version through an enabled configuration per environment, which can also lock connections and inputs for everyone. This is part twelve of the series, and it runs on the JWT from part one.

In part eleven you handed users ByteChef's whole editor. Together with templates, chat, prompts and your own builder, that's five ways to create a workflow. None of them is a page your users come back to.

That page is where the long tail lives: which account does this use, is it on, why did it stop? Building it yourself means a catalog, an activation flow with rollback, an enable toggle that explains its failures, an inputs editor, a connections manager and a home for the builder.

The Automation Hub is all of that, in an iframe on your ByteChef host, themed to match, and scoped to one connected user by their JWT. This part covers what you set up, what the component takes, what your users get, and what it calls on the server.

The Pieces

Five terms carry the rest of this post:

TermWhat it isWho manages it
Automation projectA bundle of workflow templates you author, for example "Lead routing"You, in Embedded → Automations
VersionA frozen, read-only snapshot of a project, cut by PublishYou
ConfigurationReleases one version of a project to one environment, with an on/off switch, per-workflow switches, hub visibility, an assignment rule and provided valuesYou, per environment
ReferenceA user's automation that points at your template and holds only their connections and input valuesCreated when the user activates in the hub
CopyA user's own editable workflow, cloned from your templateCreated when the user picks Edit workflow

The key rule: publishing releases nothing. Users see a project only through an enabled configuration in their environment.

Step 1: Build and Publish an Automation Project

Projects and templates are edited only in the Development environment. Switch to it with the environment selector at the bottom of the left sidebar, then open Embedded → Automations.

  1. Click New Project: a Name, Description, optional Category and Tags, and an optional Permission Expression such as metadata['plan'] == 'pro' deciding which connected users see the project at all.
  2. Expand the project row and, on its Workflows tab, use Create Workflow (or Import Workflow for a .json, .yaml or .yml file). Each workflow has a Label, Description and its own Permission Expression.
  3. Build the template. Each component that needs an app account gets a connection slot. Values each user should supply, such as a Slack channel, go in the workflow inputs; the hub asks for them during activation.
  4. Publish from the project's ⋮ menu or the editor header, with an optional Description of what changed. The badge flips from V1 DRAFT to V1 PUBLISHED.

Step 2: Release a Version with a Configuration

A configuration is how a published version reaches an environment. Create one from the project's ⋮ menu (New Configuration), the Configure button in the Configurations tab, or Configure in the editor header. All three stay disabled with Publish the project before configuring it. until a version exists.

The Configuration Dialog

New Configuration is a two-step wizard, Basic then Workflows.

On Basic:

FieldWhat it does
ProjectFixed when you open the dialog from a project; a picker on the Automation Configurations page
EnvironmentA badge showing the environment the configuration belongs to: the one you're working in
NamePrefilled with the project name. Must be unique per project and environment, ignoring case
VersionThe project's published versions, defaulting to the latest. Picking an older one is how you roll back
Assignment ruleOptional expression deciding which new users land on this configuration, for example metadata['beta'] == 'true'. Empty means everyone
Show in Automation HubOn by default. Off removes the project from GET /automation/projects, so from the hub, while its workflows stay activatable by UUID

On Workflows, every workflow of the chosen version has its own switch. Switch one off and its template disappears from the hub in this environment.

Then Save. One detail trips people up: a new configuration is saved disabled. The row appears with its Enable Configuration switch off, and nothing reaches users until you flip it.

The Configuration Row

Each row shows a Hidden from hub badge when the hub switch is off, Newer version available when you've published past its version, the V<n> it releases, the enable switch and the last execution. Its ⋮ menu has Edit, Change Project Version, Move Users… and Delete. Expand it to see each workflow with its own Enable switch and ⋮ Edit; click one for its executions across all connected users and a read-only view of the template.

Provided Values

Some values shouldn't be the user's choice, for example when every customer posts through your Slack bot. A configuration can provide connections and inputs for all its users. Open a workflow's ⋮ Edit in an expanded row; the Provided Values dialog lists:

  • one <App> Connection select per component: Let each user connect, or one of your own embedded connections in that environment;
  • one field per workflow input: Let each user fill it, or a value. Boolean inputs get a select. An input that references a component's property, like a Slack channel, gets a dropdown of real options, loaded through one of your connections (Load <input> options with).

Provided values can only be set once the configuration exists. In the hub, a provided component or input shows Provided by your administrator instead of a picker, and the server rejects any attempt to override it.

Several Configurations, One Environment

An environment can hold several configurations of one project, for example Everyone on V3 and Beta on V4 with metadata['beta'] == 'true'. Each connected user is assigned to one of them, on first use: when they first activate or copy a workflow, ByteChef picks the enabled configuration whose rule lets them in, preferring the highest version, then the newest. The rule is checked once; a later metadata change doesn't move anyone. A user no configuration admits doesn't see the project.

To move people deliberately:

  • Move Users… on a configuration row, to another configuration in the same environment.
  • Embedded → Connected Users: select users, click Upgrade automation, pick a Project and target Configuration (the newest is marked Latest version), then Upgrade.
  • One user: open them in Connected Users and use Change configuration…. The same sheet has Provision Workflow, which activates workflows for the user with connections and inputs you choose.

Users the target can't hold (it lacks a workflow they use) are skipped and listed; the rest still move.

Rolling Out a New Version

Publishing V2 changes nothing for users. To roll it out, pick Change Project Version on the configuration. The dialog warns you about the consequences before you save:

  • Version 2 adds required input channel to New lead alert: 14 connected users will pause until they fill it.
  • Version 2 adds a required Slack connection to New lead alert: connected users without a Slack integration will pause.
  • Moving to an older version warns that Versions that lack workflows connected users still use cannot be saved.

On save, references follow, keeping each user's connections and inputs; one that now lacks something pauses with a reason. Copies don't move.

Three more admin actions affect running automations:

  • Switching off a configuration or workflow pauses its references as "turned off by your administrator"; switching it back on restores what each user had.
  • Deleting a configuration deletes its references: This deletes 12 workflows of 9 users. Copies keep working. This cannot be undone.
  • Removing a workflow from the released version, or deleting the project, leaves its references dangling: disabled for good, until the user removes them.

Staging and Production

Outside Development, the sidebar shows Automation Configurations instead of Automations, with New Configuration in the header and the same row actions, but no editor. So a launch goes: build and publish in Development, test through a Development configuration, then configure Staging and Production with the version you tested.

Integrations Behind Each App

Each component that needs a connection must be backed by an embedded integration with an enabled integration configuration in the environment, as in part one. Without one, the user can't finish activating.

Step 3: Allow Your App's Origin

The hub only talks to the parent windows you allow. Set this on the ByteChef server:

BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS=https://app.example.com,https://admin.example.com

(the property is bytechef.embedded.allowed-parent-origins). It's a comma-separated list of exact origins, no paths, no wildcards. ByteChef sends it as Content-Security-Policy: frame-ancestors on the hub page, so browsers refuse to render the hub inside any other site, and the hub posts its EMBED_READY message only to those origins and accepts EMBED_INIT only from them.

Leave it empty and any site can embed the hub (the console warns about it), and the hub announces itself to the origin in document.referrer. If your app sends no referrer, it sits on its loading dots.

Step 4: Drop In the Component

'use client';

import {AutomationHub} from '@bytechef/embedded';

export function AutomationsPage({jwtToken}: {jwtToken: string}) {
    return (
        <AutomationHub
            baseUrl="https://bytechef.example.com"
            className="h-[800px] w-full"
            environment="PRODUCTION"
            jwtToken={jwtToken}
            tabs={{connections: true, newWorkflow: false}}
            theme={{borderRadius: '0.5rem', mode: 'light', primaryColor: '#2563eb'}}
        />
    );
}

The component renders a <div className={className}> with an iframe of ${baseUrl}/automation-hub.html#/embedded/hub inside, at 100% width and height. Give the wrapper a height.

Props

PropTypeDefaultWhat it does
jwtTokenstringrequiredThe connected user's token from part one
baseUrlstringhttps://app.bytechef.ioYour ByteChef host
environment'DEVELOPMENT' | 'STAGING' | 'PRODUCTION''PRODUCTION'Whose catalog, configurations and connections to show; sent as X-ENVIRONMENT
classNamestringnoneClass of the wrapping element
tabsAutomationHubTabsConfigall trueWhich parts are shown, see below
editWorkflowAllowedbooleantrueOffers Edit workflow in the activation dialog and Customize on copies
includeComponentsstring[]noneRestricts the components offered in the builder
defaultLayout'grid' | 'list''grid'Initial catalog layout
layoutSwitcherAllowedbooleantrueShows the grid/list toggle. When false, defaultLayout always applies
themeAutomationHubThemenoneColors, font and radius
connectionDialogAllowedbooleantruefalse stops users creating connections in the hub, see below

There are no callbacks; everything is saved through the embedded API under the user's JWT.

tabs takes three keys:

KeyControls
automationsThe Automations tab: catalog and the user's automations
connectionsThe Connections tab
newWorkflowThe New Automation button and the My Automations section

The tab bar appears only when both tabs are on; with both off, the hub says No sections are enabled for this hub.

Connection Creation: Prop and Claim

The connectionDialogAllowed prop only shapes the UI. To have the server enforce the same rule, put a connectionDialogAllowed claim in the token:

const payload = {
    sub: externalUserId,
    name: userName,
    connectionDialogAllowed: false,
};

A token without the claim allows creation. With false, the server answers 403 to a connection-create call and the hub hides its Connect buttons, whatever the prop says. The two combine as an AND: either one set to false turns creation off. The claim must be a boolean; any other type makes ByteChef reject the token.

The Handshake and Token Refresh

On load, the hub page posts EMBED_READY and the component answers with EMBED_INIT carrying its props. When a prop changes, including a fresh jwtToken, the component sends a new EMBED_INIT without reloading the iframe; on a new token or environment the hub refetches as the new identity. Token rotation is just a re-render. The hub also remembers the user's last tab and their grid or list choice.

Theming

KeyEffect
mode'dark' for dark mode, anything else is light
primaryColorButtons, focus rings and accents; the text on top is picked for contrast
fontFamilyMust be a font the iframe can load: system or web-safe. Your page's @font-face rules don't cross the iframe
borderRadiusIn px, rem, em or %
surfaceColor / cardColorThe page background / cards, dialogs and popovers
activeBorderColorThe border of enabled automation cards
enableColor / disableColor / onAccentColorThe Enable and Disable buttons, and their text
segmentColorThe selected segment in the filter and layout toggles
cssVariablesAny other custom property, as {'--name': 'value'}

Unsupported values are ignored. The theme also reaches the dialogs and the builder inside the hub.

The Sample App

The embedded sample app has an Automation Hub entry in its sidebar. The whole page is front-end/src/app/automation-hub/page.tsx:

export default async function AutomationHubPage() {
    const jwtToken = await getToken();

    return (
        <div className="absolute inset-0 flex flex-col bg-muted lg:pl-72">
            <header className="px-4 pt-4">
                <h1 className="text-xl font-semibold">Automation Hub</h1>
            </header>

            <AutomationHub
                baseUrl={BYTECHEF_APP_BASE_URL}
                className="min-h-0 flex-1"
                connectionDialogAllowed={true}
                environment={BYTECHEF_ENVIRONMENT}
                jwtToken={jwtToken}
            />
        </div>
    );
}

getToken() in front-end/src/lib/api.ts fetches a fresh token from the sample's back-end when the cached one is within 30 seconds of expiring. The back-end (back-end/src/index.ts) signs it with RS256 and your Signing Key's kid, and merges any customClaims from the request into the payload, which is where a connectionDialogAllowed: false claim would go. BYTECHEF_ENVIRONMENT defaults to DEVELOPMENT, so the sample's hub needs a Development configuration.

What Your Users See

The Catalog

The Automations tab opens on a toolbar: an All / Active / Enabled filter, a Search templates box (matching labels), the grid/list toggle and, with tabs.newWorkflow, a New Automation button. Below it, one card per template the user may see, from the version their configuration releases, minus workflows switched off there and templates their permission expressions hide.

A card shows the label, description and the icons of the components the template uses. A template the user hasn't activated shows Use. Once they have an automation for it, the card shows:

  • a V<n> badge with the automation's version,
  • Enable or Disable, with an accent border while enabled,
  • a ⋮ menu with Settings (only when there are inputs the user can set), Customize (only for a copy, see below) and Remove,
  • a Needs attention badge and a one-line reason when something blocks it.

Remove asks Remove automation? first. For a reference it de-provisions; for a copy it deletes the workflow.

The Activation Dialog

Use opens the activation dialog, which walks through up to three steps:

  1. Connect. One row per component that needs a connection and isn't provided, with a Select a <App> account picker and, when creation is allowed, Connect, which opens the Connect dialog and selects the new connection. If no enabled integration backs the app, the row says to ask the administrator and Next stays disabled. Skipped when nothing needs connecting.
  2. Configure. One field per workflow input the user sets, typed by input type (date, email, number, URL and so on), required ones starred.
  3. Activate (Everything is ready. Activate to switch this automation on.).

The footer has Back, Next or Activate, Edit workflow (with editWorkflowAllowed), and a small "Powered by ByteChef" mark, so the hub isn't fully unbranded. On success the dialog simply closes and the card updates.

What Activate Sends

Activate makes four calls at most, with the user's JWT and X-Environment:

GET    /api/embedded/v1/automation/workflows
POST   /api/embedded/v1/automation/workflow-templates/{templateUuid}/provision
POST   /api/embedded/v1/automation/workflows/{templateUuid}/enable
DELETE /api/embedded/v1/automation/workflow-templates/{templateUuid}/provision    (only on failure)

The first checks for an existing reference. The second creates the reference, with connections and inputs in one body:

{
    "connections": {"slack": 42, "hubspot": 17},
    "inputs": {"channel": "#sales"}
}

Connections are keyed by component name; omitted ones are auto-matched to the first connection the user may use for that app. Provided values are left out, since sending them is rejected. The third call turns the reference on; note that a reference is addressed by the template's UUID, which GET /automation/workflows returns as both its workflowUuid and automationUuid.

If a new reference fails to provision or enable, the dialog deletes it so the user can retry cleanly, and reacts to the cause:

FailureWhat the dialog does
409 with missingConnectionComponentNameJumps back to Connect and highlights that row: Connect <App> to continue
409 with providedComponentName or providedInputNameExplains that the administrator already provides some details and asks for a reload
401Your session has expired. Reload the page and try again.
403You don't have permission to do this.
404This automation could not be found.
Rollback itself failsActivation failed and could not be fully undone. Check your automations before trying again.
Anything elseSomething went wrong. Please try again.

Edit Workflow and the Builder

Edit workflow copies the template (POST /automation/workflow-templates/{uuid}/copy) and opens the copy in the part-eleven builder, inside the iframe, with the hub's includeComponents and theme. If the user already has a copy, the server answers 400 with its UUID and the dialog opens that one. A fresh copy is unpublished, so its Enable is disabled with Publish this automation in the builder before enabling it.

New Automation creates a blank workflow (POST /automation/workflows) and opens it the same way; Customize on a copy's card reopens one. A reference never opens in the builder.

My Automations and Needs Attention

Automations without a template card, such as blank ones, dangling references and duplicates, go under My Automations, shown only while tabs.newWorkflow is on. A card's reason line comes from its attentionReason:

attentionReasonWhat the card says
MISSING_CONNECTION:<component>Connect <component> to keep this running
INPUT_REQUIRED:<input>Fill in <input> to keep this running
INVALID_WORKFLOW:<count>Fix the <count> errors in this workflow to turn it on (and Enable is disabled)
TURNED_OFF_BY_ADMINISTRATORTurned off by your administrator; it comes back when they turn it on again
UPDATE_PENDINGTurn it on again to apply the latest update

A copy only ever reports INVALID_WORKFLOW. A dangling reference shows the badge with Enable disabled; Remove is the way out.

When Enabling Fails

Enable on a card calls POST /automation/workflows/{uuid}/enable. A 409 carries one field that says what's wrong, and the hub turns it into a toast titled Could not enable "<label>":

  • missingConnectionComponentName: Connect a <App> account first, then enable it again.
  • missingInputName: The "<input>" setting needs a value first. The hub also opens Settings.
  • invalidWorkflowErrorCount: Fix the <count> errors in this workflow first, then enable it again.

Settings edits the user's input values and saves with PUT /automation/workflows/{uuid}/inputs; a reference that was waiting only on that input resumes on its own.

The Connections Tab

Connections lists the user's connections in a table: Name (with a Reconnect needed badge when the credentials are invalid), App, Created, and Shared for connections you share with every connected user. The row menu has Reconnect and Delete, and appears only on connections the user owns (editable); shared ones are read-only.

  • Reconnect replaces the credentials but keeps the connection's ID, so automations using it keep working.
  • Delete asks Remove connection?. If an automation still uses the connection, the server answers 409 with {"reason": "CONNECTION_IS_USED"} and the row shows This connection is still used by an enabled automation.

There's no "add" button here. New connections come from the activation dialog and the builder.

The Endpoints Behind the Hub

Everything goes to /api/embedded/v1 with Authorization: Bearer <JWT> and X-ENVIRONMENT. If you'd rather build your own hub, these are the calls to copy:

PurposeRequestNotes
CatalogGET /automation/projectsOnly projects with an enabled configuration for the user and Show in Automation Hub on
One templateGET /automation/workflow-templates/{uuid}Also returns templates of hidden projects; 404 if not available to the user
User's automationsGET /automation/workflowsCopies and references, with kind, automationUuid, copiedFromWorkflowUuid, dangling, inputs, inputValues, attentionReason
One automationGET /automation/workflows/{uuid}Used by the builder view
ActivatePOST /automation/workflow-templates/{uuid}/provision204; 400 for a connection the user can't use; 409 as above
Remove a referenceDELETE /automation/workflow-templates/{uuid}/provision204
CopyPOST /automation/workflow-templates/{uuid}/copyReturns the copy's UUID
Blank automationPOST /automation/workflowsBody {definition}, returns the UUID
Enable / disablePOST / DELETE /automation/workflows/{uuid}/enablePOST returns {enabled, attentionReason}
InputsPUT /automation/workflows/{uuid}/inputsBody {inputs}; an absent key clears that input
Publish a copyPOST /automation/workflows/{uuid}/publishBody {description}
Remove a copyDELETE /automation/workflows/{uuid}204
PickersGET /components/{componentName}/connectionsThe user's connections for one app, including shared ones
Connections tabGET /connections, DELETE /connections/{id}, POST /connections/{id}/reauthorize409 on delete when in use

Every /automation/... row, and the per-app connections picker, also exists in a server-to-server form, /{externalUserId}/automation/..., authenticated with your environment's API key. That's how you provision automations for a user from your backend, for example right after signup, without them ever opening the hub.

Copies and References

Reference (from Use)Copy (from Edit workflow)
What the user holdsTheir connections and input valuesA whole workflow of their own
Editable in the builderNoYes, Customize
Follows your new versionsYes, through their configurationNo, keeps the version copied
Provided valuesApplied, and lockedNot applied
When you switch the workflow offPaused, turned off by your administratorKeeps running
When the template leaves the versionDanglingKeeps running
Needs publishing before enablingNoYes

References are what let you fix a template once and roll it out. Set editWorkflowAllowed={false} to keep users on references only.

Gotchas

  • Publishing isn't releasing. Without an enabled configuration in the hub's environment, Development included, the catalog is empty. New configurations start disabled.
  • Moving users is explicit. A new configuration on V2 doesn't move anyone already assigned. Use Change Project Version, Move Users… or Upgrade automation.
  • newWorkflow: false hides more than a button. It also hides My Automations, which is where dangling and switched-off references show up.
  • The claim wins. connectionDialogAllowed={true} on the component can't override a token that says false, and the prop alone isn't enforced by the server.
  • Fonts don't cross the iframe. Pick a system or web-safe fontFamily.
  • No referrer, no origins, no hub. Configure the allowed origins rather than relying on document.referrer.

Before You Go to Production

  • Projects published, and an enabled configuration in Staging and Production pointing at the version you tested.
  • Show in Automation Hub, workflow switches and Provided Values set per configuration.
  • An enabled integration configuration for every app your templates use.
  • Assignment rules written against metadata you actually set on connected users.
  • BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS set to your app's exact origins.
  • connectionDialogAllowed decided per user as a JWT claim, not only as a prop.
  • Token refresh before expiry, passed as a new jwtToken prop.
  • environment passed explicitly; it defaults to PRODUCTION.
  • tabs, editWorkflowAllowed and includeComponents chosen on purpose, and a wrapper with a real height.
  • A theme that matches your product, in light and dark.
  • A rollout habit: Change Project Version, read the warnings, then save.

What You Own, What ByteChef Owns

  • You own the templates and their inputs, which versions are released where, provided values, assignment rules and permission expressions, which apps are enabled, the allowed origins, the JWT and its claims, the page around the iframe, and the theme.
  • ByteChef owns the catalog, the activation flow and its rollback, connection auto-matching, reference rollout across versions, the attention reasons, the inputs editor, the connections manager, the builder, credential storage, and the engine that runs every automation.

Your code is one component and a token. Behind it is a lifecycle: release, assign, activate, roll forward, pause and retire.

What's Next

The hub manages automations, and its Connections tab lists accounts. But where does a user browse your integrations and connect them in the first place, without hunting for a template? That's part thirteen: the Integration Marketplace, the ready-made version of the integrations grid you built by hand in part one.

Twelve Parts In

Here's the series so far:

  1. Connect your users' apps (the JWT and ConnectDialog everything rests on).
  2. Act on those connected apps directly with the ComponentKit.
  3. Chat with an AI assistant that uses the ComponentKit's tools.
  4. Trigger their workflows from your product's events.
  5. Call a workflow like a synchronous API.
  6. Agent over MCP: the same tools, discovered through an open protocol.
  7. Author workflows in a builder you designed yourself.
  8. Start from a template you curated.
  9. Talk a workflow into existence with ByteChef's agent.
  10. Describe it in one sentence and get a finished workflow back.
  11. Hand users the whole editor with the embedded workflow builder.
  12. Give them a home for it all with the Automation Hub (this part).

Parts seven through eleven create workflows. Part twelve is where they live afterwards: activated, explained and switchable, under the same JWT from part one.

Following along? Publish an automation project in Development, create a configuration under its Configurations tab and switch it on, then run the embedded sample app and open Automation Hub. Click Use on a template, connect an account, and watch the card turn into a running automation.

Subscribe to the ByteChef Newsletter

Get the latest guides on complex automation, AI agents, and visual workflow best practices delivered to your inbox.

Related posts