Projects
Project management including creating workflows, retrieving workflow details and it's steps.
Quick Navigation
What is a Project?
In Intellistack Streamline, a workflow is always contained within a project. A workflow consists of a collection of steps connected to one another by edges that identify the step that precedes and follows it.
Every step has a type that defines the available configuration options for that specific step.
This structure is represented through a declarative JSON schema that can be used to create and update the entire workflow.
Projects and workflows are managed entirely through a declarative JSON schema, making them easy to version control and programmatically manage.
Core Concepts
Schema structure overview
The general structure of a project/workflow is represented through a fairly simple structure.
The project is the top-level object, along with its basic configuration.
A collection of steps can be added to the schema. Every step contains its own basic configuration, as well as step-specific configuration. The edges, which represent the connection between the previous and next steps of the workflow, are also defined on the step itself.
For more details on the available options for each types of step, please refer to individual step documentation.
{
"name": "Project Name",
"workflow": {
"accessType": "Access Type",
"name": "Workflow Name",
"steps": [
{
"description": "Step Name",
"type": "Step type",
"config": {
//Step type specific configuration
},
"edges": [
//Step edges
]
}
]
}
}Mapping
Fields that support mapping let you reference data from a previous step and pass it into the current one. Streamline also supports session metadata fields (session id, start date, user id, project id) that are always available regardless of step order. For the full syntax and all available sources, see Mapping.
Edges
Edges define the connection between two steps. In a declarative schema, you must use the edge property to define the relationship between the step and the step that immediately precedes it.
{
"edges": [{ "prev": "Previous Step" }]
}A few things to note:
- Edges must always be a collection.
- The first step in your workflow must define an empty collection
- Only one step can reference a specific step as its previous step.
How-To Guides
Let's explore common scenarios for managing Projects and Workflows.
Creating a new Project
Creating a project and its related workflow can be done by using the create project endpoint.
This endpoint accepts both properties for the project to be created, as well as the underlying schema definition for the workflow it contains.
Let's examine a simple example for creating a new employee onboarding project.
{
"name": "Employee Onboarding",
"workflow": {
"accessType": "public",
"name": "Employee Onboarding",
"steps": [
{
"description": "Form",
"type": "data_capture",
"config": {
"type": "data-capture",
"readonly": false,
"components": [
{
"type": "group",
"readonly": false,
"components": [
{
"type": "static_content",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "heading",
"label": "Header",
"level": 1,
"content": "Employee Onboarding",
"textAlign": "left"
}
}
},
{
"id": "employee_name",
"type": "group",
"label": "",
"subType": "name",
"parentId": "",
"readonly": false,
"components": [
{
"id": "1c42e8e6-2df4-4e5d-bfcc-c6286064322e",
"type": "name_part",
"label": "First Name",
"groupId": "first",
"parentId": "employee_name",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "First name one",
"helpText": "First name one"
}
}
},
{
"id": "76a965c8-ebb7-4c08-9940-ad441bf81479",
"type": "name_part",
"label": "Last Name",
"groupId": "last",
"parentId": "employee_name",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "Last name",
"helpText": "Last name"
}
}
}
],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "full_name",
"label": "Name"
}
}
},
{
"id": "email",
"type": "email",
"label": "",
"parentId": "group2",
"readonly": false,
"components": [],
"validation": {
"format": "email",
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "Email",
"placeholder": "[email protected]"
}
}
}
]
}
],
"presentation": {
"form": {
"label": "",
"submitLabel": "Onboard"
}
}
},
"edges": []
}
]
}
}This will result in creating a simple project with a workflow containing a single Form step.
Configuring a session name
A session name is a human-readable label that helps you identify one workflow run among many. You can combine fixed text with values collected during the workflow, such as a person's name from a form step.
Session names are not part of the project JSON sent to POST /v1/projects. Configure the name after the project and workflow version exist. The rule belongs to a specific workflow version, so changing it does not rename sessions that have already finished.
New sessions use the published workflow version unless you are testing against a draft. Configure the published version for production runs, or configure the draft and publish it when you are ready.
What you need first
Before configuring a session name, make sure you have:
- Created the project using the project endpoint.
- Noted the
workflowIdfrom the project response or the__metafield. - Chosen the workflow version to configure:
- While building, use the version you are editing. Retrieve its ID with GET /v1/workflows/{workflowId}.
- For production runs, configure the published version, or configure the draft and then publish it.
For more information about draft and published version IDs, see Retrieving workflow version IDs.
Discover which fields you can use
You can choose one or both of these optional helpers before creating the rule:
| Reader goal | Endpoint | Description |
|---|---|---|
| Browse or search fields by label | List fields available for session names | Lists form and step fields that can be included in the name. Use labelFilter to narrow the results. |
| Get recommended fields | Suggest fields for session names | Returns a short list of fields that work well as identifiers, such as names, IDs, and email addresses. |
Use the step names and field labels returned by these endpoints when you build the rule. They are the same names you see in the workflow.
Set the naming rule
Use PUT /v1/workflow-versions/{versionId}/session-name with your bearer PAT. The example below builds on the Employee Onboarding project above and combines fixed text with the first and last name collected by the Form step.
{
"sessionName": "Onboarding — {{`Form`.`First name one`}} {{`Form`.`Last name`}}"
}For the complete request and response details, see the session-name configuration reference.
Use the step's name (description) and the field's label in each placeholder, as described in Mapping. File-upload fields are not suitable for readable session names. The visible name updates as referenced fields receive values during the run, so a value may be empty until its step completes.
For programmatic clients, you can send parts instead of sessionName to define ordered fixed-text and mapped-field segments. If both are provided, sessionName takes precedence. Keep the number of mapped field references to 10 or fewer.
The following example creates the same kind of name using separate static and mapped parts.
{
"parts": [
{
"type": "STATIC",
"value": "Onboarding — "
},
{
"type": "MAPPED",
"stepName": "Form",
"fieldLabel": "First name one"
},
{
"type": "STATIC",
"value": " "
},
{
"type": "MAPPED",
"stepName": "Form",
"fieldLabel": "Last name"
}
]
}Check or update the rule
Use GET /v1/workflow-versions/{versionId}/session-name to retrieve the current rule. The response includes readableSessionName, which shows the configured name in plain language, and may include isStale and staleFieldCount.
If isStale is true, some fields in the rule no longer exist because the workflow changed. Fix the rule or publish the updated workflow to remove invalid references.
To change the rule, send another PUT request with the new sessionName or parts value.
Remove the rule
Use DELETE /v1/workflow-versions/{versionId}/session-name to remove the custom rule. The endpoint returns 204 No Content, and future sessions will no longer use that custom name.
See the name on a running session
After you start a session, use the Sessions API to read its sessionName. Session-name visibility and privacy masking are documented in Sessions — Session identifiers and masking.
If the mappable-fields response returns
isTruncated: true, narrow the search by providing alabelFilter.
Building a multi-step workflow
Since our schema is a declarative definition of our workflow, we can simply send the new desired state of the structure, and the workflow will automatically update to reflect its new state.
Building on our previous example, we can add a new notification step to warn us of a new form submission.
{
"name": "Employee Onboarding",
"workflow": {
"accessType": "public",
"name": "Employee Onboarding",
"steps": [
{
"description": "Form",
"type": "data_capture",
"config": {
"type": "data-capture",
"readonly": false,
"components": [
{
"type": "group",
"readonly": false,
"components": [
{
"type": "static_content",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "heading",
"label": "Header",
"level": 1,
"content": "Employee Onboarding",
"textAlign": "left"
}
}
},
{
"id": "employee_name",
"type": "group",
"label": "",
"subType": "name",
"parentId": "",
"readonly": false,
"components": [
{
"id": "employee-first-name",
"type": "name_part",
"label": "First Name",
"groupId": "first",
"parentId": "employee_name",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "First name one",
"helpText": "First name one"
}
}
},
{
"id": "employee-last-name",
"type": "name_part",
"label": "Last Name",
"groupId": "last",
"parentId": "employee_name",
"readonly": false,
"components": [],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "Last name",
"helpText": "Last name"
}
}
}
],
"validation": {
"required": false
},
"presentation": {
"form": {
"type": "full_name",
"label": "Name"
}
}
},
{
"id": "email",
"type": "email",
"label": "",
"parentId": "group2",
"readonly": false,
"components": [],
"validation": {
"format": "email",
"required": false
},
"presentation": {
"form": {
"type": "input",
"label": "Email",
"placeholder": "[email protected]"
}
}
}
]
}
],
"presentation": {
"form": {
"label": "",
"submitLabel": "Onboard"
}
}
},
"edges": []
},
{
"description": "Notification",
"type": "notification",
"config": {
"notifications": [
{
"label": "Notification 1",
"smsConfig": null,
"emailConfig": {
"from": "Employee Onboarding",
"message": "<p>{{`Form`.`employee-first-name`}} {{`Form`.`employee-last-name`}}filled out the employee onboarding form. <br><span style=\"font-size: 14px;\">Reach out to them at</span><span style=\"box-sizing: border-box; margin: 0px; padding: 0px;\"> </span>to complete the onboarding process.</p>",
"replyTo": "[email protected]",
"subject": "Employee Onboarding",
"recipients": ["[email protected]"],
"attachments": []
}
}
]
},
"edges": [
{
"prev": "Form"
}
]
}
]
}
}A few key elements to notice:
- Our second step, the notification, now has a value configured in the "edges" property that references the previous step. This property is required for any additional step in the workflow.
- The "message" property of that step uses our mapping syntax to use values from the previous step.
Understanding the __meta field in project responses
__meta field in project responsesWhen you create or retrieve a project using the Schema API the response includes a special __meta field that provides important metadata about the project and its workflow.
The __meta object contains the following properties:
workflowId- The UUID of the workflow associated with this project. This can benullif the workflow hasn't been created yet.sessionStartUrl- A POST endpoint URL that can be used to start a new workflow session/execution.webhookSessionStartUrl- A POST endpoint URL specifically designed for webhook-triggered workflow sessions.
Example __meta response
__meta response{
"__meta": {
"workflowId": "dbd635f4-226e-4410-8f3a-0fbe4f4d4e0c",
"sessionStartUrl": "https://us.streamline.intellistack.ai/v1/sessions",
"webhookSessionStartUrl": "https://us.streamline.intellistack.ai/v1/sessions/webhooks/a1e273b1-04d4-43d1-9444-ec42ef53bc42"
}
}These URLs are particularly useful for:
- Starting workflow executions - Use the
sessionStartUrlto programmatically initiate workflow sessions - Webhook integrations - Use the
webhookSessionStartUrlwhen configuring webhook triggers for your workflow - Dynamic workflow management - Reference the
workflowIdfor subsequent API calls to update or manage the workflow
Retrieving workflow version IDs
A workflow version is identified by a UUID (id on each version record, or liveVersionId / draftVersionId on the workflow). That UUID is different from the integer version field (1, 2, 3, …) on each item returned by GET /v1/workflows/{workflowId}/workflow-versions.
To retrieve the version IDs, first obtain the workflowId from the project response (or the __meta.workflowId field), then call:
GET /v1/workflows/{workflowId}
The response includes:
liveVersionId— the currently published version that customer sessions execute against (this is usually the value you want)draftVersionId— the active draft version (null when there are no unpublished edits)
To list every version of a workflow, including its integer version number, name, publishedAt, and publishedBy:
GET /v1/workflows/{workflowId}/workflow-versions
To retrieve a single version's details by its UUID:
GET /v1/workflow-versions/{versionId}
To publish the current draft so it becomes the live version:
Starting a workflow session
To start a new workflow session using the sessionStartUrl, make a POST request with the following body:
{
"workflowId": "dbd635f4-226e-4410-8f3a-0fbe4f4d4e0c"
}The workflowId should match the workflow ID provided in the __meta object. This will initiate a new execution of your workflow.
Updated 15 days ago