Creating and executing a Workflow

Overview

This recipe walks you through the entire workflow lifecycle:

1. Create a project
2. Create a workflow
3. Add workflow steps
4. Execute the workflow
5. Access the workflow session in the browser

Step 1: Create a Project

First, create a project to contain your workflow.

POST /v1/projects

{
    "name": "My Workflow Project",
    "description": "Project for testing workflow functionality"
}

Response: Save the id from the response - this is your projectId.

Step 2: Create a Workflow

Create a workflow within your project.

POST /v1/workflows

{
    "name": "My Sample Workflow",
    "description": "A sample workflow for testing",
    "projectId": "YOUR_PROJECT_ID_HERE"
}

Response: Save the id from the response - this is your workflowId.

Step 3: Add Workflow Steps

Add one or more steps to your workflow. You can add different types of steps like forms, document generation, data activation, sign, etc.

Example: Add a Form Step

POST /v1/workflows/{workflowId}/steps

{
    "name": "Customer Information Form",
    "stepType": "form",
    "order": 1,
    "configuration": {
        "formId": "YOUR_FORM_ID",
        "title": "Please fill out your information"
    }
}

Example: Add a Document Generation Step

POST /v1/workflows/{workflowId}/steps

{
    "name": "Generate Contract",
    "stepType": "document_generation",
    "order": 2,
    "configuration": {
        "templateId": "YOUR_TEMPLATE_ID",
        "outputFormat": "pdf"
    }
}

Example: Add a Signature Step

POST /v1/workflows/{workflowId}/steps

{
    "name": "Sign Document",
    "stepType": "sign",
    "order": 3,
    "configuration": {
        "documentId": "YOUR_DOCUMENT_ID",
        "signerEmail": "[email protected]"
    }
}

Response: Each step creation returns a stepId that you can use for further configuration.

Step 4: Configure Step Mappings (Optional)

If you need to pass data between steps, configure field mappings:

POST /v1/steps/{stepId}/mapping

{
    "sourceId": "PREVIOUS_STEP_ID",
    "sourceForeignFieldId": "customer_name",
    "targetForeignFieldId": "contract_recipient_name",
    "order": 1
}

Step 5: Execute the Workflow

Execute your workflow to start a session.

POST /v1/workflows/{workflowId}/execute

{
    "context": {
        "userEmail": "[email protected]",
        "initiatedBy": "api"
    }
}

Response: Save the sessionId from the response - this is crucial for accessing the workflow.

{
    "sessionId": "abc123-def456-ghi789",
    "status": "active",
    "startedAt": "2024-01-20T10:00:00.000Z"
}

Step 6: Access the Workflow Session

Navigate to the workflow session in your browser using the session ID:

https://us.streamline.formstack.app/sessions/{{sessionId}}

Replace {{sessionId}} with the actual session ID from Step 5.

For example:

https://us.streamline.formstack.app/sessions/abc123-def456-ghi789

What Happens Next

Once you access the session URL:

1. Forms: Users can fill out any form steps in the workflow
2. Document Generation: Documents are automatically generated based on form data and templates
3. Data Activation: Data is processed and sent to configured destinations
4. Signatures: Users can digitally sign documents
5. Other Steps: Any other configured steps execute in order

Monitoring Your Workflow

You can monitor the workflow session progress:

GET /v1/sessions/{sessionId}

This returns the current status and completed steps of your workflow session.

Common Workflow Patterns

Simple Form → Document → Sign

1. Form step to collect user data
2. Document generation step using form data
3. Signature step for the generated document

Data Collection → Processing → Activation

1. Form step to collect data
2. Data transformation/validation step
3. Data activation step to send data to external systems

Multi-Step Approval Process

1. Initial form submission
2. Review/approval step
3. Final document generation and signature

Tips

• Test your workflow steps individually before chaining them together
• Use field mappings to pass data between steps
• Monitor session status to track workflow progress
• Handle errors gracefully by checking step completion status