Workflow Steps

Workflow steps are the main interactive sections of your client-facing script. They guide users through multi-step processes, collect information, and perform operations between steps.

Step Structure

interface EnhancedStep {
  id: string
  name: string
  description: string
  uiNodes: UINode[]
  fields: Field[]
  preNextStepOperations?: PreNextStepOperation[]
  postNextStepOperations?: PreNextStepOperation[]
  successMessage?: string
  failureMessage?: string
  conditional?: ConditionalLogic
}

Basic Step Configuration

{
  "id": "select_items",
  "name": "Select Items to Return",
  "description": "Choose which items from your order you'd like to return",
  "uiNodes": [
    {
      "id": "item_selector",
      "type": "multi_select",
      "dataOperation": {
        "type": "update",
        "target": "selected_line_items"
      },
      "uiConfig": {
        "component": "product_multi_select",
        "props": {
          "label": "Select Items",
          "dataSource": "line_items",
          "displayFields": ["title", "variant_title", "price"],
          "required": true,
          "minSelections": 1
        }
      }
    }
  ],
  "fields": [
    {
      "id": "selected_line_items",
      "name": "Selected Items",
      "type": "array",
      "required": true
    }
  ]
}

Step Types and Patterns

1. Data Collection Steps

Steps focused on gathering user input:

{
  "id": "customer_information",
  "name": "Customer Information", 
  "description": "Please provide your contact details",
  "uiNodes": [
    {
      "id": "first_name_input",
      "type": "input",
      "dataOperation": {
        "type": "update",
        "target": "first_name"
      },
      "uiConfig": {
        "component": "text_input",
        "props": {
          "label": "First Name",
          "placeholder": "Enter your first name",
          "required": true,
          "maxLength": 50
        }
      },
      "validation": [
        {
          "type": "required",
          "message": "First name is required"
        },
        {
          "type": "min_length", 
          "value": "2",
          "message": "First name must be at least 2 characters"
        }
      ]
    },
    {
      "id": "phone_input",
      "type": "input",
      "dataOperation": {
        "type": "update",
        "target": "phone_number"
      },
      "uiConfig": {
        "component": "phone_input",
        "props": {
          "label": "Phone Number",
          "placeholder": "(555) 123-4567",
          "required": false,
          "helpText": "We'll only contact you if there are issues with your return"
        }
      }
    }
  ]
}

2. Selection Steps

Steps for choosing from options or products:

{
  "id": "return_reason_selection",
  "name": "Reason for Return",
  "description": "Help us understand why you're returning these items",
  "uiNodes": [
    {
      "id": "reason_selector",
      "type": "select",
      "dataOperation": {
        "type": "update",
        "target": "return_reason"
      },
      "uiConfig": {
        "component": "radio_group",
        "props": {
          "label": "Primary Reason",
          "options": "instanceData.merchant_return_reasons",
          "displayField": "name",
          "valueField": "id",
          "required": true,
          "layout": "vertical"
        }
      }
    },
    {
      "id": "custom_reason_input",
      "type": "input",
      "conditional": {
        "showIf": {
          "field": "return_reason",
          "operator": "equals",
          "value": "other"
        }
      },
      "dataOperation": {
        "type": "update", 
        "target": "custom_return_reason"
      },
      "uiConfig": {
        "component": "textarea",
        "props": {
          "label": "Please specify",
          "placeholder": "Tell us more about your reason for return",
          "required": true,
          "maxLength": 500
        }
      }
    }
  ]
}

3. Review and Confirmation Steps

Steps for displaying summaries and getting final confirmation:

{
  "id": "review_return",
  "name": "Review Your Return",
  "description": "Please review the details of your return request",
  "uiNodes": [
    {
      "id": "return_summary",
      "type": "display",
      "dataOperation": {
        "type": "display",
        "source": "instanceData"
      },
      "uiConfig": {
        "component": "return_summary_card",
        "props": {
          "title": "Return Summary",
          "sections": [
            {
              "title": "Items",
              "data": "selected_line_items",
              "template": "item_list"
            },
            {
              "title": "Refund Method",
              "data": "refund_method",
              "template": "text"
            },
            {
              "title": "Estimated Refund",
              "data": "final_amount",
              "template": "currency"
            }
          ]
        }
      }
    },
    {
      "id": "confirmation_checkbox",
      "type": "input",
      "dataOperation": {
        "type": "update",
        "target": "policy_agreement_checkbox"
      },
      "uiConfig": {
        "component": "checkbox",
        "props": {
          "label": "I agree to the return policy terms",
          "required": true,
          "linkText": "View return policy",
          "linkUrl": "/return-policy"
        }
      },
      "validation": [
        {
          "type": "required",
          "message": "You must agree to the return policy to proceed"
        }
      ]
    }
  ]
}

Pre and Post Step Operations

Pre-Next Step Operations

Operations that run before moving to the next step:

{
  "preNextStepOperations": [
    {
      "id": "validate_selection",
      "type": "validate",
      "name": "Validate Item Selection",
      "description": "Ensure selected items are eligible for return",
      "config": {
        "validationRules": [
          {
            "type": "custom",
            "message": "Some selected items are past the return deadline",
            "customValidator": "validateReturnEligibility"
          }
        ]
      }
    },
    {
      "id": "calculate_refund",
      "type": "transform",
      "name": "Calculate Refund Amount",
      "description": "Calculate the total refund amount",
      "config": {
        "calculations": [
          {
            "field": "subtotal",
            "expression": "selected_line_items.sum(item => item.price * item.quantity)"
          },
          {
            "field": "restocking_fee",
            "expression": "customerProfile.tier === 'premium' ? 0 : subtotal * 0.05"
          },
          {
            "field": "final_amount",
            "expression": "subtotal - restocking_fee"
          }
        ]
      }
    }
  ]
}

Post-Next Step Operations

Operations that run after advancing to the next step:

{
  "postNextStepOperations": [
    {
      "id": "log_progress",
      "type": "trackEvent",
      "name": "Log Step Completion",
      "description": "Track user progress through the workflow",
      "config": {
        "eventName": "workflow_step_completed",
        "properties": {
          "step_id": "select_items",
          "user_id": "instanceData.customer_id",
          "selected_count": "instanceData.selected_line_items.length"
        }
      }
    },
    {
      "id": "prefetch_shipping",
      "type": "retrieveData",
      "name": "Pre-fetch Shipping Options",
      "description": "Get available shipping methods for next step",
      "config": {
        "apiEndpoint": "/ShippingNode/get_return_rates",
        "apiMethod": "GET",
        "apiParams": {
          "items": "instanceData.selected_line_items",
          "destination": "instanceData.return_address"
        },
        "responseMapping": [
          {
            "sourceField": "rates",
            "targetFetchedRecord": "shippingRates"
          }
        ]
      }
    }
  ]
}

Conditional Steps

Show or hide entire steps based on conditions:

{
  "id": "manager_approval",
  "name": "Manager Review Required",
  "description": "Your return requires manager approval",
  "conditional": {
    "showIf": {
      "field": "requires_approval",
      "operator": "equals",
      "value": true
    }
  },
  "uiNodes": [
    {
      "id": "approval_notice",
      "type": "display",
      "uiConfig": {
        "component": "info_card",
        "props": {
          "type": "warning",
          "title": "Approval Required",
          "message": "Due to the value or nature of your return, it requires manager approval. You'll receive an email within 24 hours."
        }
      }
    },
    {
      "id": "manager_notes",
      "type": "input",
      "dataOperation": {
        "type": "update",
        "target": "manager_notes"
      },
      "uiConfig": {
        "component": "textarea",
        "props": {
          "label": "Additional Information",
          "placeholder": "Provide any additional details for the manager review",
          "maxLength": 1000
        }
      }
    }
  ]
}

Advanced Step Features

1. Multi-Column Layouts

{
  "uiNodes": [
    {
      "id": "left_column",
      "type": "container",
      "uiConfig": {
        "component": "column",
        "props": {
          "width": "60%"
        }
      },
      "children": [
        {
          "id": "item_details",
          "type": "display",
          "uiConfig": {
            "component": "product_details"
          }
        }
      ]
    },
    {
      "id": "right_column", 
      "type": "container",
      "uiConfig": {
        "component": "column",
        "props": {
          "width": "40%"
        }
      },
      "children": [
        {
          "id": "price_breakdown",
          "type": "display",
          "uiConfig": {
            "component": "price_summary"
          }
        }
      ]
    }
  ]
}

2. Dynamic Field Generation

{
  "id": "item_questions",
  "type": "dynamic",
  "dataOperation": {
    "type": "generate",
    "source": "selected_line_items"
  },
  "uiConfig": {
    "component": "dynamic_form_generator",
    "props": {
      "template": {
        "type": "input",
        "uiConfig": {
          "component": "textarea",
          "props": {
            "label": "Why are you returning {item.title}?",
            "placeholder": "Please provide details...",
            "required": true
          }
        }
      }
    }
  }
}

3. Progress Tracking

{
  "id": "progress_indicator",
  "type": "display",
  "uiConfig": {
    "component": "progress_bar",
    "props": {
      "currentStep": 3,
      "totalSteps": 5,
      "stepLabels": [
        "Verify Order",
        "Select Items", 
        "Return Reason",
        "Shipping Method",
        "Review & Submit"
      ]
    }
  }
}

Step Validation Patterns

Field-Level Validation

{
  "validation": [
    {
      "type": "required",
      "message": "This field is required"
    },
    {
      "type": "custom",
      "message": "Invalid selection",
      "customValidator": "validateItemEligibility",
      "params": {
        "field": "selected_line_items",
        "checkReturnWindow": true
      }
    }
  ]
}

Step-Level Validation

{
  "stepValidation": [
    {
      "type": "minimum_selection",
      "field": "selected_line_items",
      "minimum": 1,
      "message": "Please select at least one item to return"
    },
    {
      "type": "total_value",
      "field": "selected_line_items",
      "maximum": 5000,
      "message": "Returns over $5000 require phone verification"
    }
  ]
}

Best Practices

1. User Experience

Keep steps focused on a single task or concept
Use clear, descriptive step names and descriptions
Provide progress indicators for multi-step workflows
Allow users to go back and edit previous steps

2. Data Management

Validate data at each step before proceeding
Use pre-next step operations for complex validations
Store intermediate calculations in instanceData
Handle edge cases gracefully with appropriate messaging

3. Performance

Use post-next step operations for non-blocking API calls
Prefetch data for upcoming steps when possible
Minimize the number of API calls during step transitions
Cache expensive calculations

4. Error Handling

Provide clear, actionable error messages
Use conditional logic to handle different scenarios
Implement fallback options for failed operations
Log errors for debugging and monitoring

Common Step Patterns

Item Selection with Validation

{
  "id": "select_exchange_items",
  "name": "Choose Exchange Items",
  "uiNodes": [
    {
      "id": "product_search",
      "type": "search",
      "uiConfig": {
        "component": "product_search",
        "props": {
          "placeholder": "Search for products...",
          "resultsSource": "products",
          "multiSelect": true
        }
      }
    }
  ],
  "preNextStepOperations": [
    {
      "id": "validate_exchange_value",
      "type": "validate",
      "config": {
        "validationRules": [
          {
            "type": "custom",
            "message": "Exchange value cannot exceed return value",
            "customValidator": "validateExchangeValue"
          }
        ]
      }
    }
  ]
}

Address Collection Step

{
  "id": "shipping_address",
  "name": "Return Shipping Address",
  "uiNodes": [
    {
      "id": "address_form",
      "type": "composite",
      "uiConfig": {
        "component": "address_form",
        "props": {
          "allowInternational": false,
          "validatePostalCode": true,
          "requirePhoneNumber": true
        }
      }
    }
  ],
  "preNextStepOperations": [
    {
      "id": "validate_address", 
      "type": "validate",
      "config": {
        "apiEndpoint": "/AddressValidation/validate",
        "validationField": "return_address"
      }
    }
  ]
}

Next Steps

UI Components - Custom interface elements
Data Operations - API calls and transformations

Step Structure​

Basic Step Configuration​

Step Types and Patterns​

1. Data Collection Steps​

2. Selection Steps​

3. Review and Confirmation Steps​

Pre and Post Step Operations​

Pre-Next Step Operations​

Post-Next Step Operations​

Conditional Steps​

Advanced Step Features​

1. Multi-Column Layouts​

2. Dynamic Field Generation​

3. Progress Tracking​

Step Validation Patterns​

Field-Level Validation​

Step-Level Validation​

Best Practices​

1. User Experience​

2. Data Management​

3. Performance​

4. Error Handling​

Common Step Patterns​

Item Selection with Validation​

Address Collection Step​

Next Steps​