Skip to main content

Workflow Gates

The workflow gate is the entry point for your client-facing script. It handles initial customer verification, data collection, and pre-workflow operations before allowing users to proceed to the main workflow steps.

Gate Structure​

interface WorkflowGate {
  id: string
  name: string
  description: string
  uiNodes: UINode[]
  fields: Field[]
  preNextStepOperations?: PreNextStepOperation[]
  successMessage?: string
  failureMessage?: string
  icons?: GateIcons
}

Basic Gate Configuration​

{
  "gate": {
    "id": "customer_verification",
    "name": "Returns & Exchanges",
    "description": "Verify customer identity and order information",
    "uiNodes": [
      {
        "id": "order_number",
        "type": "input",
        "dataOperation": {
          "type": "update",
          "target": "order_number"
        },
        "uiConfig": {
          "component": "text_input",
          "props": {
            "label": "Order Number",
            "placeholder": "Enter your order number",
            "required": true,
            "helpText": "Found in your order confirmation email"
          }
        },
        "validation": [
          {
            "type": "required",
            "message": "Order number is required"
          }
        ]
      }
    ]
  }
}

Key Components​

1. UI Nodes​

UI nodes define the form fields and display elements in your gate:

Input Node​

{
  "id": "customer_email",
  "type": "input",
  "dataOperation": {
    "type": "update",
    "target": "customer_email"
  },
  "uiConfig": {
    "component": "email_input",
    "props": {
      "label": "Email Address",
      "placeholder": "Enter your email",
      "required": true
    }
  },
  "validation": [
    {
      "type": "required",
      "message": "Email is required"
    },
    {
      "type": "email",
      "message": "Please enter a valid email address"
    }
  ]
}

Select Node​

{
  "id": "reason_category",
  "type": "select",
  "dataOperation": {
    "type": "update",
    "target": "reason_category"
  },
  "uiConfig": {
    "component": "dropdown_select",
    "props": {
      "label": "Reason Category",
      "options": [
        {"value": "defect", "label": "Product Defect"},
        {"value": "sizing", "label": "Wrong Size"},
        {"value": "other", "label": "Other"}
      ],
      "required": true
    }
  }
}

Display Node​

{
  "id": "welcome_message",
  "type": "display",
  "dataOperation": {
    "type": "display",
    "source": "instanceData"
  },
  "uiConfig": {
    "component": "info_card",
    "props": {
      "title": "Welcome Back!",
      "message": "We're here to help with your return"
    }
  }
}

2. Validation Rules​

Gates support comprehensive validation:

{
  "validation": [
    {
      "type": "required",
      "message": "This field is required"
    },
    {
      "type": "min_length",
      "value": "3",
      "message": "Must be at least 3 characters"
    },
    {
      "type": "pattern",
      "value": "^[A-Z]{2}\\d{6}$",
      "message": "Must be 2 letters followed by 6 numbers"
    },
    {
      "type": "custom",
      "message": "Invalid order format",
      "customValidator": "validateOrderNumber"
    }
  ]
}

Validation Types:

  • required: Field must have a value
  • email: Must be valid email format
  • pattern: Must match regex pattern
  • min_length/max_length: String length constraints
  • min_value/max_value: Numeric range constraints
  • custom: Custom validation function

3. Pre-Next Step Operations​

Operations that run when the gate is submitted, before proceeding to the first workflow step:

{
  "preNextStepOperations": [
    {
      "id": "lookup_customer",
      "type": "retrieveData",
      "name": "Look Up Customer Profile",
      "description": "Retrieve customer information and order history",
      "config": {
        "apiEndpoint": "/ShopifyNode/get_customer",
        "apiMethod": "GET",
        "apiParams": {
          "email": "instanceData.customer_email"
        },
        "responseMapping": [
          {
            "sourceField": "customer",
            "targetFetchedRecord": "customerProfile"
          }
        ]
      }
    },
    {
      "id": "verify_order",
      "type": "validate",
      "name": "Verify Order Ownership",
      "description": "Ensure the customer owns the specified order",
      "config": {
        "validationRules": [
          {
            "type": "custom",
            "message": "Order not found or doesn't belong to this customer",
            "customValidator": "verifyOrderOwnership"
          }
        ]
      }
    }
  ]
}

4. Success and Failure Messages​

Customize messages shown based on gate validation results:

{
  "successMessage": "Customer verified successfully! Proceeding to returns form.",
  "failureMessage": "We couldn't verify your information. Please check your details and try again."
}

5. Icons Configuration​

Add visual elements to enhance the gate experience:

{
  "icons": {
    "first": {
      "icon_name": "shield-check",
      "title": "Secure Verification"
    },
    "second": {
      "icon_name": "clock",
      "title": "Quick Process"
    },
    "third": {
      "icon_name": "headphones",
      "title": "24/7 Support"
    }
  }
}

Advanced Gate Features​

Conditional Fields​

Show/hide fields based on other field values:

{
  "id": "order_type",
  "type": "select",
  "conditional": {
    "showIf": {
      "field": "customer_type",
      "operator": "equals",
      "value": "premium"
    }
  }
}

Multi-Step Gates​

For complex verification processes:

{
  "fields": [
    {
      "id": "verification_step",
      "name": "Current Step",
      "type": "string",
      "required": true
    }
  ],
  "uiNodes": [
    {
      "id": "step_1_fields",
      "conditional": {
        "showIf": {
          "field": "verification_step",
          "operator": "equals", 
          "value": "basic_info"
        }
      }
    }
  ]
}

Best Practices​

1. Keep Gates Simple​

  • Collect only essential information needed for verification
  • Defer complex data collection to workflow steps
  • Use clear, concise field labels

2. Provide Clear Feedback​

  • Include helpful placeholder text
  • Add validation messages that guide users to correct input
  • Use success/failure messages to communicate next steps

3. Design for Mobile​

  • Use appropriate input types (email, tel, number)
  • Keep form fields large enough for touch interaction
  • Test on various screen sizes

4. Handle Errors Gracefully​

  • Implement comprehensive validation
  • Provide fallback options for edge cases
  • Log validation failures for debugging

Common Gate Patterns​

Customer Verification Gate​

{
  "id": "customer_verification",
  "name": "Verify Your Identity", 
  "uiNodes": [
    {
      "id": "email_input",
      "type": "input",
      "uiConfig": {
        "component": "email_input",
        "props": {
          "label": "Email Address",
          "required": true
        }
      }
    },
    {
      "id": "order_lookup",
      "type": "input", 
      "uiConfig": {
        "component": "text_input",
        "props": {
          "label": "Order Number",
          "required": true
        }
      }
    }
  ],
  "preNextStepOperations": [
    {
      "id": "verify_customer",
      "type": "retrieveData",
      "config": {
        "apiEndpoint": "/verify_customer",
        "apiParams": {
          "email": "instanceData.email",
          "order_number": "instanceData.order_number"
        }
      }
    }
  ]
}

Product Configuration Gate​

{
  "id": "product_config",
  "name": "Configure Your Product",
  "uiNodes": [
    {
      "id": "product_selector",
      "type": "select",
      "uiConfig": {
        "component": "product_dropdown",
        "props": {
          "label": "Select Product",
          "dataSource": "available_products"
        }
      }
    },
    {
      "id": "customization_options",
      "type": "input",
      "conditional": {
        "showIf": {
          "field": "selected_product",
          "operator": "exists",
          "value": true
        }
      }
    }
  ]
}

Next Steps​