ReferencesWorkflow Kit

Creating workflow actions

The @inngest/workflow-kit package provides a workflow engine, enabling you to create workflow actions on the back end. These actions are later provided to the front end so end-users can build their own workflow instance using the <Editor />.

Workflow actions are defined as two objects using the EngineAction (for the back-end) and PublicEngineAction (for the front-end) types.

import { type PublicEngineAction } from "@inngest/workflow-kit";

export const actionsDefinition: PublicEngineAction[] = [
  {
    kind: "grammar_review",
    name: "Perform a grammar review",
    description: "Use OpenAI for grammar fixes",
  },
];

In the example above, the actionsDefinition array would be passed via props to the <Provider /> while the actions are passed to the Engine.

Why do I need two types of actions?

The actions need to be separated into 2 distinct objects to avoid leaking the action handler implementations and dependencies into the front end:

The Workflow Kit provides a Workflow Engine to compose workflow actions on the back end and a set of pre-defined React components for the front end.

Passing actions to the React components: PublicEngineAction[]

  • Name
    kind
    Type
    string
    Required
    required
    Description

    Kind is an enum representing the action's ID. This is not named as "id" so that we can keep consistency with the WorkflowAction type.

  • Name
    name
    Type
    string
    Required
    required
    Description

    Name is the human-readable name of the action.

  • Name
    description
    Type
    string
    Required
    optional
    Description

    Description is a short description of the action.

  • Name
    icon
    Type
    string
    Required
    optional
    Description

    Icon is the name of the icon to use for the action. This may be an URL, or an SVG directly.

Passing actions to the Workflow Engine: EngineAction[]

Note: Inherits PublicEngineAction properties.

  • Name
    handler
    Type
    function
    Required
    optional
    Description

    The handler is your code that runs whenever the action occurs. Every function handler receives a single object argument which can be deconstructed. The key arguments are event and step.

src/inngest/actions.ts

import { type EngineAction } from "@inngest/workflow-kit";

import { actionsDefinition } from "./actions-definition";

export const actions: EngineAction[] = [
{
    // Add a Table of Contents
    ...actionsDefinition[0],
    handler: async ({ event, step, workflow, workflowAction, state }) => {
        // ...
    }
},
];

The details of the handler() unique argument's properties can be found below:

handler() function argument properties

  • Name
    event
    Type
    TriggerEvent
    Required
    optional
    Description

    See the Inngest Function handler event argument property definition.

  • Name
    step
    Type
    Step
    Required
    optional
    Description

    See the Inngest Function handler step argument property definition.

  • Name
    workflow
    Type
    Workflow
    Required
    optional
    Description

    See the Workflow instance format.

  • Name
    workflowAction
    Type
    WorkflowAction
    Required
    optional
    Description

    WorkflowAction is the action being executed, with fully interpolated inputs.

    Key properties are:

    • id: string: The ID of the action within the workflow instance.
    • kind: string: The action kind, as provided in the PublicEngineAction.
    • name?: string: The name, as provided in the PublicEngineAction.
    • description?: string: The description, as provided in the PublicEngineAction.
    • inputs?: string: The record key is the key of the EngineAction input name, and the value is the variable's value.
  • Name
    state
    Type
    object
    Required
    optional
    Description

    State represents the current state of the workflow, with previous action's outputs recorded as key-value pairs.