Surface Workflows

Control Surface behavior through custom business logic, via configurable properties and optional HTTP behaviors. Surface workflows execute before child Component workflows.

Usage

const workflow: SurfaceWorkflow = async ({ identity, resource, features }: SurfaceWorkflowArgs) => {
    return {
        properties: {
            userMessage: `Hello, ${identity.identifier}`,
            hasWidgetAccess: features.widget.enabled,
            resourceId: resource.id,
        },
        http: {
            status: 200,
            headers: {
                "X-Custom-Greeting": `Welcome, ${identity.identifier}`,
            },
            body: JSON.stringify({
                message: `Hello from Surface Workflow, ${identity.identifier}!`,
            }),
        },
    } as SurfaceBehavior;
};

export default workflow;

Invocation

Surface workflows are executed as part of the Surface Decisions API request flow. When a surface decision is requested, the workflow runs synchronously to compute the surface behavior before the response is returned.

Arguments

See SurfaceWorkflowArgs.

Return Type

The workflow returns a SurfaceBehavior. As all properties are optional, returning an empty object {} is valid.

Surface Behaviors

• Properties: Use properties to attach computed values for surface control or to pass to child Component workflows.
• HTTP: Optional - Provide http to override or modify response headers/body/status for HTTP surfaces. If the http behavior is provided and replaces the body, no further processing of child Component workflows will occur.

Common Use Cases

• Customize surface responses based on user identity or attributes
• Control feature access at the surface level
• Fetch dynamic content or configuration from external APIs
• Implement A/B testing or feature flagging at the surface level
• Modify HTTP response headers or body for specific surfaces
• Log surface access or usage metrics

See Also

• SurfaceWorkflowArgs
• SurfaceBehavior
• HttpSurfaceBehavior