Starting Workflows

Besides starting a workflow from the Sample Dashboard, you can also start a workflow via API.

Prerequisites

To start a workflow, you will require two things

A SampleHC API key (see Authentication)
The slug (unique identifier) of the workflow you want to start To find a workflow slug, from the workflow page, click the Edit button at the top right. On the edit page, next to the title of the workflow (e.g., Sample Workflow Template), you will see the slug (e.g., sample-workflow-template).

Making a request

Below are examples of how to start a workflow with different types of request bodies. Remember to replace YOUR_API_KEY with your actual API key and <my-workflow-slug> with the slug of your workflow.

Using `application/json`

If you want to send data as a JSON object, use the Content-Type: application/json header. The body should be a JSON object, optionally containing a startData field.

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"startData": {"name": "First Workflow Instance", "priority": "high"}}' \
  https://api.samplehc.com/api/v2/workflows/<my-workflow-slug>/start

Using `multipart/form-data`

If you need to include files or send data as form fields, use multipart/form-data. curl will set the Content-Type header automatically when you use the -F option. Any form fields you send will be collected into the startData. If you send files, they will be processed and their resulting identifiers or content will also be part of startData.

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'customerName=Acme Corp' \
  -F 'orderId=12345' \
  -F 'attachmentFile=@/path/to/your/invoice.pdf' \
  https://api.samplehc.com/api/v2/workflows/<my-workflow-slug>/start

Start Data Schema

The start_data_schema field in a workflow definition allows you to specify the expected structure and validation rules for data sent when starting a workflow. This schema follows the JSON Schema specification and helps ensure data quality and provides clear documentation of expected inputs.

Simple Schema Examples

Here are some basic examples of start_data_schema definitions:

Basic Form Fields

from workflows_py.workflow import Workflow

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "patient_name": {
                "type": "string",
                "description": "Full name of the patient",
            },
            "patient_age": {
                "type": "integer",
                "description": "Age in years",
                "minimum": 0,
                "maximum": 150,
            },
            "visit_date": {
                "type": "string",
                "description": "Date of visit in YYYY-MM-DD format",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            },
            "is_emergency": {
                "type": "boolean",
                "description": "Whether this is an emergency visit",
            },
        },
        "required": ["patient_name", "visit_date"],
    },
)

File Upload Schema

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "File metadata ID",
                    },
                    "fileName": {
                        "type": "string",
                        "description": "Original file name",
                    },
                },
                "description": "Patient enrollment document",
                "x-formFieldType": "file",
                "x-formFieldOrder": 1,
                "x-formFieldLabel": "Upload Document",
            },
        },
        "required": ["document"],
    },
)

Multiple File Upload Schema

For workflows that need to accept multiple files at once, use an array field with x-formFieldType: "multi-file":

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "documents": {
                "type": "array",
                "description": "Upload multiple documents",
                "x-formFieldType": "multi-file",
                "x-formFieldOrder": 1,
                "x-formFieldLabel": "Upload Documents",
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "string",
                            "description": "File metadata ID",
                        },
                        "fileName": {
                            "type": "string",
                            "description": "Original file name",
                        },
                    },
                },
            },
        },
        "required": ["documents"],
    },
)

Complex Schema Examples

Medical Workflow with Nested Objects

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "File metadata ID",
                    },
                    "fileName": {
                        "type": "string",
                        "description": "File name",
                    },
                },
                "description": "The enrollment form for the patient",
                "x-formFieldType": "file",
                "x-formFieldOrder": 1,
                "x-formFieldLabel": "Enrollment Form",
            },
            "patient_id": {
                "type": "string",
                "description": "Patient ID in format P followed by 6 digits",
                "pattern": "^P\\d{6}$",
                "x-formFieldOrder": 2,
                "x-formFieldLabel": "Patient ID",
            },
            "visit_date": {
                "type": "string",
                "description": "Date of visit in YYYY-MM-DD format",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            },
            "patient_age": {
                "type": "integer",
                "description": "Patient's age in years",
                "minimum": 0,
                "maximum": 150,
            },
            "visit_cost": {
                "type": "number",
                "description": "Cost of the visit in dollars",
                "minimum": 0,
            },
            "is_emergency": {
                "type": "boolean",
                "description": "Whether this is an emergency visit",
            },
            "visit_type": {
                "type": "string",
                "enum": ["routine", "follow-up", "emergency", "consultation"],
                "description": "Type of medical visit",
            },
            "symptoms": {
                "type": "array",
                "description": "List of symptoms reported by patient",
                "items": {"type": "string"},
                "minItems": 1,
            },
            "insurance_info": {
                "type": "object",
                "description": "Patient's insurance information",
                "properties": {
                    "provider": {
                        "type": "string",
                        "description": "Insurance provider name",
                    },
                    "policy_number": {
                        "type": "string",
                        "description": "Insurance policy number",
                    },
                    "copay": {
                        "type": "number",
                        "description": "Copay amount",
                        "minimum": 0,
                    },
                    "coverage_details": {
                        "type": "object",
                        "description": "Detailed coverage information",
                        "properties": {
                            "deductible": {
                                "type": "number",
                                "description": "Annual deductible amount",
                            },
                            "coverage_percentage": {
                                "type": "integer",
                                "description": "Percentage of coverage",
                                "minimum": 0,
                                "maximum": 100,
                            },
                        },
                        "required": ["deductible"],
                    },
                },
                "required": ["provider", "policy_number"],
            },
            "email": {
                "type": "string",
                "format": "email",
                "description": "Patient's email address",
            },
            "phone": {
                "type": "string",
                "pattern": "^\\+?[1-9]\\d{1,14}$",
                "description": "Patient's phone number in international format",
            },
        },
        "required": ["patient_id", "visit_date", "document"],
    },
)

Schema with Hidden Fields

Hidden fields are useful for system-generated values that should be included in the workflow data but not shown to users in the form:

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "workflow_id": {
                "type": "string",
                "description": "System-generated workflow identifier",
                "x-formFieldHidden": true,
            },
            "created_by": {
                "type": "string",
                "description": "User who initiated the workflow",
                "x-formFieldHidden": true,
            },
            "patient_name": {
                "type": "string",
                "description": "Patient's full name",
                "x-formFieldLabel": "Patient Name",
                "x-formFieldOrder": 1,
            },
            "visit_type": {
                "type": "string",
                "enum": ["routine", "follow-up", "emergency"],
                "description": "Type of visit",
                "x-formFieldOrder": 2,
            },
            "internal_notes": {
                "type": "string",
                "description": "Internal processing notes",
                "x-formFieldHidden": true,
            },
        },
        "required": ["patient_name", "visit_type"],
    },
)

In this example, workflow_id, created_by, and internal_notes are hidden from the form but can be populated programmatically when the workflow starts.

Business Process Schema with Arrays and Enums

workflow = Workflow(
    start_data_schema={
        "type": "object",
        "properties": {
            "company_info": {
                "type": "object",
                "description": "Company registration details",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Legal company name",
                        "minLength": 2,
                        "maxLength": 100,
                    },
                    "industry": {
                        "type": "string",
                        "enum": [
                            "healthcare",
                            "finance",
                            "technology",
                            "manufacturing",
                            "retail",
                            "other"
                        ],
                        "description": "Primary industry sector",
                    },
                    "employees": {
                        "type": "array",
                        "description": "List of key employees",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "description": "Employee full name",
                                },
                                "position": {
                                    "type": "string",
                                    "description": "Job title",
                                },
                                "email": {
                                    "type": "string",
                                    "format": "email",
                                    "description": "Work email address",
                                },
                                "is_key_personnel": {
                                    "type": "boolean",
                                    "description": "Whether this is key personnel",
                                },
                            },
                            "required": ["name", "position", "email"],
                        },
                        "minItems": 1,
                        "maxItems": 50,
                    },
                },
                "required": ["name", "industry"],
            },
            "documents": {
                "type": "array",
                "description": "Required business documents",
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "string",
                            "description": "Document metadata ID",
                        },
                        "fileName": {
                            "type": "string",
                            "description": "Original filename",
                        },
                        "document_type": {
                            "type": "string",
                            "enum": [
                                "articles_of_incorporation",
                                "tax_id_verification",
                                "operating_agreement",
                                "other"
                            ],
                            "description": "Type of business document",
                        },
                    },
                    "required": ["id", "fileName", "document_type"],
                },
                "minItems": 1,
            },
            "annual_revenue": {
                "type": "number",
                "description": "Estimated annual revenue in USD",
                "minimum": 0,
                "maximum": 1000000000,
            },
            "setup_date": {
                "type": "string",
                "format": "date",
                "description": "When the company was established",
            },
        },
        "required": ["company_info", "documents"],
    },
)

Custom Form Field Extensions

Sample supports custom extensions to enhance form generation:

x-formFieldType: Specifies the UI component type (e.g., “file”, “date”, “select”)
x-formFieldLabel: Custom label for the form field
x-formFieldOrder: Controls the order of fields in generated forms
x-formFieldPlaceholder: Placeholder text for input fields
x-formFieldHidden: Hides the field from the generated form (useful for system-generated values)

Schema Validation Benefits

Using start_data_schema provides several advantages:

Data Validation: Ensures incoming data meets your requirements before workflow execution
Documentation: Serves as clear documentation of expected workflow inputs
Automatic form creation: Start data automatically creates a form so there’s no additional workflow updates needed

Cron Scheduling

Cron schedule functionality requires samplehc >= 0.3.0 and workflows-py >= 0.1.19 and requires an updated lambda_handler.py file.

Besides starting workflows manually via API or dashboard, workflows can also be automatically started on a recurring schedule using cron expressions. This is configured at the workflow level using the cron_schedule parameter in the Workflow constructor.

Setting Up Cron Scheduling

To schedule a workflow to run automatically, pass a cron expression string to the cron_schedule parameter:

from workflows_py.workflow import Workflow, Step

workflow = Workflow(
    cron_schedule="0 9 * * 1-5",  # Run at 9 AM Monday through Friday
    start_data_schema={
        "reportType": {"type": "string", "default": "daily"},
        "timestamp": {"type": "string", "format": "date-time"}
    }
)

workflow.then(
    Step("generate-report", generate_daily_report_function)
)

Cron Expression Format

Cron expressions use five fields separated by spaces:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, Sunday to Saturday)
│ │ │ │ │
* * * * *

Common Cron Examples

# Every day at 8:00 AM
cron_schedule="0 8 * * *"

# Every weekday at 9:00 AM
cron_schedule="0 9 * * 1-5"

# Every hour on the hour
cron_schedule="0 * * * *"

# Every 15 minutes
cron_schedule="*/15 * * * *"

# First day of every month at midnight
cron_schedule="0 0 1 * *"

# Every Sunday at 3:00 PM
cron_schedule="0 15 * * 0"

Scheduled Workflow Behavior

When a workflow runs on a cron schedule:

The workflow starts automatically at the specified time
No manual trigger or start data is required unless specified in start_data_schema
The workflow runs with an empty start data context unless configured otherwise
Multiple scheduled instances can run simultaneously if the schedule frequency is higher than workflow execution time

Combining Cron Scheduling with Start Data Schema

Cron scheduling works alongside start data schemas to provide structured data to scheduled workflows:

workflow = Workflow(
    cron_schedule="0 6 * * *",  # Daily at 6 AM
    start_data_schema={
        "type": "object",
        "properties": {
            "reportType": {
                "type": "string",
                "enum": ["daily", "weekly", "monthly"],
                "default": "daily",
                "description": "Type of report to generate"
            },
            "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "When the report was scheduled"
            },
            "includeMetrics": {
                "type": "boolean",
                "default": true,
                "description": "Whether to include performance metrics"
            }
        }
    }
)

Best Practices for Scheduled Workflows

Use appropriate timing: Consider system load and business hours
Handle failures gracefully: Include error handling for automated runs
Set up monitoring: Track scheduled workflow execution and failures
Test thoroughly: Verify cron expressions work as expected before production
Consider time zones: Ensure cron times align with business requirements
Use start data defaults: Provide sensible defaults in your start data schema for scheduled runs

Monitoring Scheduled Workflows

Scheduled workflows appear in the workflow dashboard just like manually triggered workflows. You can:

View execution history and status
Monitor for failed scheduled runs
See the next scheduled execution time
Manually trigger workflows outside of their schedule if needed

Workflows

Screens

Other guides

Prerequisites

Making a request

Using `application/json`

Using `multipart/form-data`

Start Data Schema

Simple Schema Examples

Basic Form Fields

File Upload Schema

Multiple File Upload Schema

Complex Schema Examples

Medical Workflow with Nested Objects

Schema with Hidden Fields

Business Process Schema with Arrays and Enums

Custom Form Field Extensions

Schema Validation Benefits

Cron Scheduling

Setting Up Cron Scheduling

Cron Expression Format

Common Cron Examples

Scheduled Workflow Behavior

Combining Cron Scheduling with Start Data Schema

Best Practices for Scheduled Workflows

Monitoring Scheduled Workflows

Workflows

Screens

Other guides

​Prerequisites

​Making a request

​Using application/json

​Using multipart/form-data

​Start Data Schema

​Simple Schema Examples

​Basic Form Fields

​File Upload Schema

​Multiple File Upload Schema

​Complex Schema Examples

​Medical Workflow with Nested Objects

​Schema with Hidden Fields

​Business Process Schema with Arrays and Enums

​Custom Form Field Extensions

​Schema Validation Benefits

​Cron Scheduling

​Setting Up Cron Scheduling

​Cron Expression Format

​Common Cron Examples

​Scheduled Workflow Behavior

​Combining Cron Scheduling with Start Data Schema

​Best Practices for Scheduled Workflows

​Monitoring Scheduled Workflows

Prerequisites

Making a request

Using `application/json`

Using `multipart/form-data`

Start Data Schema

Simple Schema Examples

Basic Form Fields

File Upload Schema

Multiple File Upload Schema

Complex Schema Examples

Medical Workflow with Nested Objects

Schema with Hidden Fields

Business Process Schema with Arrays and Enums

Custom Form Field Extensions

Schema Validation Benefits

Cron Scheduling

Setting Up Cron Scheduling

Cron Expression Format

Common Cron Examples

Scheduled Workflow Behavior

Combining Cron Scheduling with Start Data Schema

Best Practices for Scheduled Workflows

Monitoring Scheduled Workflows