Component Workflows

Customize behavior for individual Surface Components through business logic that executes within the context of a parent surface. Component workflows execute after the parent Surface workflow and receive properties computed by the surface.

Usage

Component Workflow

const workflow: SurfaceWorkflow = async ({ identity, resource, surfaceProperties }: SurfaceWorkflowArgs) => {
    return {
        properties: {
            message: `Component for ${identity.identifier}`,
            resourceId: resource.id,
        },
        content: {
            after: [
                {
                    type: "html",
                    content: `<div>${surfaceProperties?.userMessage}!</div>`,
                },
            ],
        },
    } as SurfaceBehavior;
};

export default workflow;

Invocation

Component workflows are executed as part of the Surface Decisions API request flow. When a surface decision is requested, component workflows run in parallel after the parent surface workflow completes. If the surface workflow returns a terminal output, such as a fixed HTTP body, component workflows will not execute.

Arguments

Component workflows use SurfaceWorkflowArgs, with the addition of surfaceProperties containing values computed by the parent surface workflow.

Prop

Type

Surface Properties

The surfaceProperties argument provides access to the properties object returned by the parent surface workflow:

// Parent surface workflow
const surfaceWorkflow: SurfaceWorkflow = async ({ identity }) => {
    return {
        properties: {
            theme: "dark",
            userId: identity.identifier,
        },
    };
};

// Component workflow - receives surface properties
const componentWorkflow: SurfaceWorkflow = async ({ surfaceProperties }) => {
    const theme = surfaceProperties?.theme; // "dark"
    const userId = surfaceProperties?.userId; // user identifier
    // ...
};

Return Type

The workflow returns a SurfaceBehavior. The result is mapped to componentBehaviors in the surface decision response. As all properties are optional, returning an empty object {} is valid.

Prop

Type

Component Behaviors

Properties: Use properties to attach computed values specific to this component.
Web Content: Optionally inject content before/after or remove the component's DOM element.

Common Use Cases

Apply feature access rules to individual UI elements
Customize component content based on parent surface context
Compute component-specific data from surface properties
Implement per-component A/B testing or personalization
Control visibility or behavior of specific UI components based on user attributes
Fetch component-specific data from external APIs