ByteChef LogoByteChef
EmbeddedAutomations

Activate templates from your app

Open the activation dialog from your own page so a connected user can connect accounts, fill in inputs, and turn on a published automation template.

The activation dialog is the same flow the Automation Hub uses to activate a template, available on its own. Use it when you render your own list of automations and want ByteChef to handle the activation. It renders in your page, not in an iframe.

Before you start

  • A Signing Key and a backend that mints end-user JWTs - see Installing the SDK.
  • An automation project with the template and an enabled configuration in the environment, pointing at a published version that contains the template. See Automations.
  • The template does not have to be listed. Show in Automation Hub only controls whether the API lists the project, so a hidden project's workflows can still be activated by UUID. Turning off the configuration or the workflow is what stops activation and running.
  • For each component in the template that needs a connection, an integration that is set up, has an enabled configuration in the environment, and is visible to the connected user (its permission expression). See Adding an Integration. A component without one shows <App> isn't set up yet — ask your administrator, and activation cannot continue.

Open the dialog

'use client';
import {useActivationDialog} from '@bytechef/embedded';

export function ActivateButton({jwtToken, templateId}: {jwtToken: string; templateId: string}) {
    const {openDialog} = useActivationDialog({
        baseUrl: 'https://your-bytechef-host.example.com',
        environment: 'PRODUCTION',
        jwtToken,
        onActivated: (workflowUuid) => refreshAutomations(),
        onEditWorkflow: (workflowUuid) => openBuilder(workflowUuid),
        workflowTemplateId: templateId,
    });

    return <button onClick={openDialog}>Activate</button>;
}

useActivationDialog returns openDialog and closeDialog. <ActivationDialog /> is the same dialog as a component, for when you render it yourself; it is always open while mounted.

Props

PropTypeDefaultDescription
workflowTemplateIdstring-Required. The id of the template to activate.
jwtTokenstring-Required. The connected user's signed token.
baseUrlstringhttps://app.bytechef.ioYour ByteChef host.
environmentstring'PRODUCTION'The environment whose templates and connections the dialog uses.
connectionCreationAllowedbooleantrueWhether users can create a connection from the dialog. When false, the + button is hidden and they can only pick existing connections.
mode'dark' | 'light''light'The dialog's color mode. See Theming and Localization.
onActivated(workflowUuid: string) => void-Runs after the template is activated.
onDeactivated(workflowTemplateId: string) => void-Runs after Deactivate removes an automation the user already activated.
onEditWorkflow(workflowUuid: string) => void-Runs after Edit workflow copies the template, with the uuid of the copy. Omit it to hide Edit workflow.
onSaved(workflowUuid: string) => void-Runs after Save stores changes to an automation the user already activated. See Edit an activated automation.
onClose() => void-Runs when the dialog closes. Required on <ActivationDialog />; optional on the hook.

The flow

The dialog has up to three steps. A step with nothing to show is skipped.

  1. Connect - one row per component that needs a connection, with a list of the user's connections and a + button (named "Connect" for screen readers). + reuses the user's existing connection for that integration without showing a form when its credentials are valid. Otherwise it opens the Connect dialog for the integration behind that component; if an existing connection's credentials are invalid, the form reconnects it. The connection it creates belongs to an integration instance. Skipped when the template needs no connections.
  2. Configure - one field per workflow input. Required inputs must be filled. Skipped when the template has no inputs.
  3. Activate - the dialog provisions the template and turns it on.

What Activate does

Activate provisions a reference to the template with the chosen connections and inputs, then enables it. If this fails, the dialog removes the reference it created so the user can try again. A reference that already existed before the attempt is left in place.

Edit an activated automation

Open the dialog with the template id of an automation the user already activated, and it edits that automation instead of activating it again. The dialog finds it in GET /api/embedded/v1/automation/workflows, the row whose kind is REFERENCE and whose automationUuid is the template id, and opens with the user's choices filled in: the connection each component uses (the row's connections) and the input values (inputValues). The last step offers Save instead of Activate.

const {openDialog} = useActivationDialog({
    baseUrl: 'https://your-bytechef-host.example.com',
    environment: 'PRODUCTION',
    jwtToken,
    onSaved: () => refreshAutomations(),
    workflowTemplateId: automation.automationUuid,
});

Save sends the changes with the provision endpoint, POST /api/embedded/v1/automation/workflow-templates/{workflowTemplateId}/provision. It sends only the connections the user changed, and the inputs only when one of them changed. If nothing changed, the dialog closes without a request.

Saving only changes what the user chooses: their connections and input values. The workflow itself, its name, description, steps and the inputs it asks for, comes from the template and changes only when you publish a new version. Saving also does not switch the automation on or off; leave that to your own control, such as a switch that calls POST or DELETE /api/embedded/v1/automation/workflows/{workflowUuid}/enable. If the automation still needs a connection, the dialog returns to Connect and highlights that component.

If the dialog cannot load the user's automations, it opens to activate. Activate checks the list again before it provisions, so an automation that already exists is never removed.

When an MCP server offers the automation, the dialog also shows an Available to AI agents switch at the top. It takes effect at once, not on Save: it calls POST or DELETE /api/embedded/v1/automation/workflows/{workflowUuid}/mcp/enable. See MCP Servers.

Deactivate, in the footer while editing, removes the user's activation with its connections and input values. The first click asks for confirmation; the second calls DELETE /api/embedded/v1/automation/workflow-templates/{workflowTemplateId}/provision, runs onDeactivated, and closes the dialog. The template then shows as not activated again.

What Edit workflow does

Edit workflow copies the template into the user's own workflow and calls onEditWorkflow with the uuid of the copy, then closes the dialog. Opening the copy is up to your app, for example in the workflow builder. It is not offered for templates from code-workflow projects, which can only be activated as references.

Finding template ids

List the projects and their templates for the current user:

const response = await fetch(`${baseUrl}/api/embedded/v1/automation/projects`, {
    headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'X-Environment': 'PRODUCTION',
    },
});

const projects = await response.json();

Each project has a workflowTemplates array. The id of a template is the workflowTemplateId. The listing leaves out projects whose Show in Automation Hub switch is off; copy the UUID of such a workflow from the administrator's Automations page. The dialog itself reads the template with GET /api/embedded/v1/automation/workflow-templates/{workflowTemplateId}, which also returns templates of hidden projects.

One Connect dialog per page

Only one Connect dialog renders per page. Do not keep a useConnectDialog instance mounted on the same page while Connect in the activation dialog is in use.

How is this guide?

Last updated on

On this page