Screendragon API Integration Use Cases - Workflows

Modified on Tue, 30 Sep at 11:07 AM

Initiate a Workflow
Edit a Workflow
Execute a Workflow Action
Retrieve list of Workflow Assignments
Search for a Workflow

Initiate a Workflow

Endpoint

POST /api/workflows

Description

This endpoint validates and initiates the creation of a workflow for a specified item at a given location. It checks for item existence, user permissions, workflow validity, and other preconditions before proceeding.

Query Parameters

Name	Type	Required	Description
`id`	Int32	✅	ID of the item to attach the workflow to.
`location`	Int32	✅	ID of the location(folder) where the workflow is to be created.
`workflow`	String	✅	Workflow name or GUID to be used.
`comment`	String	❌	Optional comment to include with the workflow.
`creator`	String	❌	Username of the workflow creator. Defaults to the API user.
`clone`	Boolean	❌	If true, clones the workflow instead of creating a new one. Defaults to false.

Error Handling

Status Code	Message
400	"No such workflow for id:{id}"
400	"No such user with username '{editor}'"
400	"No such workflow with id: {id}"
400	"No such action with label: {action}"
400	"Invalid client configuration {site}"
400	"Some unexpected error message"

Notes

The id can be either the workflow ID or the item ID; the system resolves it internally.
If editor is provided, permission checks are performed.
If queued = true and the action supports queuing, the request is queued instead of executed.

Sample Request

POST /api/workflows?id=12345
&location=101
&workflow=onboardingFlow
&creator=jdoe
&comment=Initial+submission
&clone=false

Authorization: Bearer <token>

Sample Response (Success)

{
  "i_node": 98765
}

Sample Response (Error)

{
  "error": "No such location exists."
}

Edit a Workflow

Endpoint

PUT /api/workflows/{id}

Description

This endpoint edits the workflow by updating metadata fields and optionally executing a workflow action. Supports permission checks, action queuing and metadata updates.

Path Parameters

Name	Type	Required	Description
`id`	Int32	✅	ID of the workflow or the item association with the workflow.

Query Parameters

Name	Type	Required	Description
`action`	String	❌	Label of the workflow action to execute.
`comment`	String	❌	Optional comment to include with the action.
`editor`	String	❌	Username of the person editing the workflow. Defaults to API user.
`queued`	Boolean	❌	If true, queues the action instead of executing immediately.

Body Parameters

Name	Type	Required	Description
`fields`	Array	✅	A list of metadata fields to update for the workflow item.

Error Handling

Status Code	Message
400	"No item(id) was specified."
400	"No workflow specified."
400	"No such item exists."
400	"The item has ben deleted."
400	"No such location exists."
400	"The location has been deleted."
400	"No such user exists."
400	"The specified submitter account has been deleted."
400	"The specified submitter does not have write permissions to the item."
400	"The specified submitter does not have write permissions to the location."
400	"The specified workflow does not exist."
400	"The specified workflow has no steps."
400	"Some unexpected error message"

Notes

If creator is not provided, the API user is used by default.
The workflow can be specified by name or GUID.
All errors are logged internally with SQL context for debugging.

Sample Request

PUT /api/workflows?id=12345
&action=Approve
&editor=jdoe
&comment=Looks+good
&queued=false
Content-Type: application/json
Authorization: Bearer <token>

[
  {
    "FieldName": "Status",
    "Value": "Approved"
  },
  {
    "FieldName": "ReviewedBy",
    "Value": "jdoe"
  }
]

Sample Response (Success)

{}

Sample Response (Error)

{
  "error": "No such action with label: Approve"
}

Execute a Workflow Action

Endpoint

PUT /api/workflows/{id}

Description

This endpoint executes a specified action on an existing Workflow. It can optionally update metadata fields before performing the action. This endpoint supports permission validation, action queuing and audit logging. It is typically used to progress a workflow to its next step based on user input or system events.

Path Parameters

Name	Type	Required	Description
`id`	Int32	✅	ID of the workflow or the item association with the workflow.

Query Parameters

Name	Type	Required	Description
`action`	String	✅	Label of the workflow action to execute.
`comment`	String	❌	Optional comment to include with the action.
`editor`	String	❌	Username of the person editing the workflow. Defaults to API user.
`queued`	Boolean	❌	If true, queues the action instead of executing immediately.

Error Handling

Status Code	Message
400	"No item(id) was specified."
400	"No workflow specified."
400	"No such item exists."
400	"The item has ben deleted."
400	"No such location exists."
400	"The location has been deleted."
400	"No such user exists."
400	"The specified submitter account has been deleted."
400	"The specified submitter does not have write permissions to the item."
400	"The specified submitter does not have write permissions to the location."
400	"The specified workflow does not exist."
400	"The specified workflow has no steps."
400	"Some unexpected error message"

Notes

If creator is not provided, the API user is by default.
The workflow can be specified by name or GUID.
All errors are logged internally with SQL context for debugging.

Sample Request

PUT /api/workflows?id=12345
&action=Approve
&editor=jdoe
&comment=Approved+by+manager
&queued=false
Authorization: Bearer <token>
Content-Type: application/json

[
  {
    "FieldName": "Status",
    "Value": "Approved"
  },
  {
    "FieldName": "ReviewedBy",
    "Value": "jdoe"
  }
]

Sample Response (Success)

{
  "status": "Action executed successfully",
  "workflowId": 12345,
  "action": "Approve",
  "editor": "jdoe",
  "timestamp": "2025-07-10T14:30:00Z"
}

Sample Response (Queued)

{
  "status": "Action queued",
  "workflowId": 12345,
  "action": "Approve",
  "editor": "jdoe",
  "queued": true,
  "timestamp": "2025-07-10T14:30:00Z"
}

Sample Response (Error)

{
  "error": "The specified workflow does not exist."
}

Retrieve a List of Workflow Assignments

Endpoint

GET /api/workflows/Assignments

Description

This endpoint retrieves a list of workflow assignments for a specified user or group, filtered by location, form types, and custom metadata fields. This is typically used to display workflows assigned to a user or group, with support for advanced filtering and metadata enrichment.

Query Parameters

Name	Type	Required	Description
`assignedUserFilterType`	String	✅	Type of user filter (e.g. "userid", "username", "email").
`assignedUserFilterValue`	String	✅	Value to match against the filter type (e.g. userrname or user ID).
`f_node`	Int32	❌	Location IS to filter workflows by folder or hierarchy.
`formTypes`	String	❌	Comma-separated list of form type GUIDs to include.
`customFields`	String	❌	JSON formatted list of metadata fields to include in the result.
`orderBy`	String	❌	Field to sort by (e.g. "item", "status").
`orderByDirection`	String	❌	Sort direction: "ASC" or "DESC".

Error Handling

Status Code	Message
403	"Admin access is required to perform this operation"
400	"Invalid Form Type"
400	"No data"

Notes

Only admin users are allowed to access this endpoint.
The endpoint supports filtering by user ID or other identifiers.
Metadata fields must be provided in a valid JSON format.
Internal SQL logic ensures permission checks and data enrichment.

Sample Request

GET /api/workflows/Assignments?assignedUserFilterType=username
&assignedUserFilterValue=jdoe
&f_node=101
&formTypes=abc123,def456
&orderBy=item
&orderByDirection=ASC
Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "i_node": 12345,
    "workflowId": 98765,
    "f_node": 101,
    "parentId": 1001,
    "item": "Employee Onboarding",
    "status": "In Progress",
    "parent": "HR Department",
    "Project Start Date": "2025-07-01",
    "Project End Date": "2025-07-15",
    "ReviewedBy": "jdoe"
  },
  ...
]

Sample Response (Error)

{
  "error": "Admin Access is required to 
              perform this operation."
}

Search for a Workflow

Endpoint

GET /api/workflows/search/{formType}/{formField}/value/{value}

Description

This endpoint searches for workflow identifiers (inodes) based on a specific form type, form field, and field value. This endpoint is typically used to locate workflows that match a given form field value within a specified form type.

Path Parameters

Name	Type	Required	Description
`formType`	String	✅	The type of form to search within.
`formField`	String	✅	The specific field name in the form.
`value`	String	✅	The value to match in the specified field.

Error Handling

Status Code	Message
400	"No form type specified."
400	"No form field specified."
400	"No data"

Notes

All query parameters are mandatory.
The method returns an empty list if no workflows match the criteria.

Sample Request

GET api/workflows/search/123/Name/value/John
Authorization: Bearer <token>

Sample Response (Success)

Sample Response (Error)

{
  "error": "No form type specified."
}