Skip to main content

Client-Facing Script Anatomy

Client-facing scripts in HandledScript are interactive workflows that customers use directly. These scripts create dynamic, multi-step forms and processes with validation, data fetching, and custom UI components.

Overview​

A client-facing workflow is a complete interactive application defined by a single JSON configuration. It handles everything from initial customer verification to final API calls and custom UI rendering.

Core Structure​

Every client-facing script follows the EnhancedWorkflow interface:

interface EnhancedWorkflow {
  id: number | string
  account_id?: number
  name: string
  description: string
  finalApiEndpoint: string
  finalApiMethod: "GET" | "POST" | "PUT" | "DELETE"
  instanceData: Record<string, any>
  fetchedRecords: Record<string, FetchedRecord | any>
  instanceDataSchema: InstanceDataSchemaDefinition
  gate: WorkflowGate
  workflowVariables: string[]
  steps: EnhancedStep[]
  onLoad?: PreNextStepOperation[]
  custom_ui_components_config?: Record<string, ComponentConfig>
  client_workflow_customization?: Record<string, any>
}

Essential Components​

1. Basic Information​

{
  "id": 1001,
  "name": "Customer Returns Portal",
  "description": "Full-featured returns system with customer verification",
  "finalApiEndpoint": "/HandledWorkflow/{instanceData.workflow_id}",
  "finalApiMethod": "POST"
}

Purpose: Identifies the workflow and defines the final API call made when the workflow completes.

Key Fields:

  • id: Unique identifier for the workflow
  • name: Human-readable workflow name
  • description: Brief explanation of what the workflow does
  • finalApiEndpoint: The API endpoint called upon completion (supports variable interpolation)
  • finalApiMethod: HTTP method for the final API call

2. Instance Data​

Instance data represents the current state of the workflow - all the information collected from the user as they progress through the steps.

{
  "instanceData": {
    "customer_email": "",
    "order_number": "",
    "selected_items": [],
    "return_reason": "",
    "refund_method": "",
    "notes": ""
  }
}

Purpose:

  • Stores user input as they progress
  • Provides default values for form fields
  • Acts as the data model for the entire workflow

Best Practices:

  • Initialize all fields that will be used
  • Use descriptive names
  • Set appropriate default values
  • Group related fields logically

3. Instance Data Schema​

Defines validation rules and data types for instance data fields:

{
  "instanceDataSchema": {
    "customer_email": {
      "type": "string",
      "required": true
    },
    "selected_items": {
      "type": "array", 
      "required": true
    },
    "refund_amount": {
      "type": "number",
      "required": false
    },
    "customer_profile": {
      "type": "object",
      "required": false,
      "itemSchema": {
        "tier": {"type": "string", "required": true},
        "total_orders": {"type": "number", "required": false}
      }
    }
  }
}

Supported Types:

  • string: Text values
  • number: Numeric values
  • boolean: True/false values
  • array: Lists of items
  • object: Complex nested objects (use itemSchema for validation)

4. Fetched Records​

Stores data retrieved from external APIs during workflow execution:

{
  "fetchedRecords": {
    "customerProfile": {
      "value": null,
      "instanceDataSetters": [
        {
          "instanceDataProperty": "customer_email",
          "setterFunction": "email"
        }
      ]
    },
    "orderDetails": {
      "value": null,
      "instanceDataSetters": [
        {
          "instanceDataProperty": "order_items",
          "setterFunction": "line_items"
        }
      ]
    }
  }
}

Purpose:

  • Cache API responses
  • Automatically populate instance data fields
  • Provide data for UI components and validation

Instance Data Setters:

  • instanceDataProperty: Field in instanceData to populate
  • setterFunction: Path/expression to extract data from the fetched record

Next Steps​