Creating and executing a Workflow
A step-by-step guide to create, execute, and run a complete workflow from start to finish.
Overview
This recipe walks you through the entire workflow lifecycle:
- Create a project
- Create a workflow
- Add workflow steps
- Execute the workflow
- 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:
- Forms: Users can fill out any form steps in the workflow
- Document Generation: Documents are automatically generated based on form data and templates
- Data Activation: Data is processed and sent to configured destinations
- Signatures: Users can digitally sign documents
- 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
- Form step to collect user data
- Document generation step using form data
- Signature step for the generated document
Data Collection → Processing → Activation
- Form step to collect data
- Data transformation/validation step
- Data activation step to send data to external systems
Multi-Step Approval Process
- Initial form submission
- Review/approval step
- 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
Updated 21 days ago