Get workflow - Forms | iTwin Platform

Forms

Download API definition:

GET https://api.bentley.com/forms/workflows/{type}?iTwinId

Retrieves the workflow for the given form type in the given iTwin or project. The iTwin or project ID must be specified using the 'iTwinId' query string parameter. Existing clients can continue to use the 'projectId' parameter as an alias for 'iTwinId'.

It is possible for users of a project to choose not to set a workflow for a given type. In that case, requests to get the workflow of that type will return a 404 Not Found response where the 'code' property of the body's 'error' object is set to "WorkflowNotFound". This does not indicate client or server error. Other HTTP status codes, or other values of the 'code' property, do indicate an unexpected error of some sort.

Note that workflows cannot be customized through this API; they can only be added, deleted, or changed manually by iTwin administrators through the Bentley Form Manager webapp, found at https://connect-formmanager.bentley.com/designer/#/your-itwin-id (replace your-itwin-id with your actual project or iTwin ID).

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request

Request parameters

type

Yes

The form type for which to get a workflow.

iTwinId

Yes

The GUID of the iTwin or project for which to get a workflow. (Note: projectId is also accepted as an alias for this parameter.)

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Response

Response 200 OK

json

{
    "workflow": {
        "id": "e5Ue5Ue5U02hNz19awLcRh3pqLoNXpZDuR123456789",
        "startStates": [
            "Open",
            "Closed"
        ],
        "type": "Other",
        "states": [{
                "name": "Open",
                "color": "#ff0000",
                "editableProperties": [
                    "assignee.id",
                    "assignee.displayName",
                    "assignees",
                    "description",
                    "dueDate",
                    "subject"
                ],
                "stateCategory": "Open"
            },
            {
                "name": "Closed",
                "color": "#274e13",
                "editableProperties": [],
                "stateCategory": "Closed"
            }
        ],
        "transitions": [{
                "displayName": "Close",
                "start": "Open",
                "end": "Closed",
                "notes": "None"
            },
            {
                "displayName": "Reopen",
                "start": "Closed",
                "end": "Open",
                "notes": "None"
            }
        ],
        "startingTransitions": [{
                "displayName": "Create as Open",
                "end": "Open",
                "notes": "None"
            },
            {
                "displayName": "Create as Closed",
                "end": "Closed",
                "notes": "None"
            }
        ],
        "uninitializedState": {
            "editableProperties": [
                "assignee.id",
                "assignee.displayName",
                "assignees",
                "description",
                "dueDate",
                "subject"
            ]
        }
    }
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 404 Not Found

This response indicates that the project does not exist (code = 'RepositoryNotFound') or that there is no workflow set for this form type (code = 'WorkflowNotFound'). This latter case does not indicate client error, as it is valid for a user to choose not to set a workflow for a given form type.

json

{
    "error": {
        "code": "WorkflowNotFound",
        "message": "Requested workflow is not available.",
        "target": "type"
    }
}

Response 422 Unprocessable Entity

A URL parameter was malformed. Most likely the required 'projectId' query parameter is missing or not a valid GUID.

json

{
    "error": {
        "code": "InvalidWorkflowRequest",
        "message": "Cannot retrieve workflow.",
        "details": [{
            "code": "MissingRequiredParameter",
            "message": "The 'projectId' query parameter must be provided.",
            "target": "projectId"
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

Workflow Response (get)

workflow

workflow-get

json

{
    "type": "object",
    "title": "Workflow Response (get)",
    "properties": {
        "workflow": {
            "$ref": "#/components/schemas/workflow-get"
        }
    },
    "additionalProperties": false
}

Workflow (get)

String

Unique identifier for this workflow.

startStates

String[]

The names of all the states that can be chosen for a newly-created form data instance's status property.

type

String

The form type this workflow applies to.

states

workflow-state[]

A list of possible workflow states, i.e. possible values of the form data's status property.

transitions

workflow-transition[]

A list of valid workflow transitions. The status property of a form data instance can only be changed if there is a transition, accessible to the current user, whose start property matches the current value of the status property of the form, and whose end property matches the new status value.

startingTransitions

starting-transition[], null

Transitions that govern setting the status property of a brand-new form data instance. These will each have a null value for start and a starting state name for end. Clients should not depend on this array existing or including a transition for every start state, but should still allow the user to select any start state when creating a new form data instance.

uninitializedState

uninitialized-state

Workflow state representing the status of a new form data instance, before it has been saved. This mainly just determines (through the editableProperties array) which properties can be set on the form's initial save. Even though this state's name property may be null, the form's status property will have to be set to a valid, non-null value that matches one of the start state names.

json

{
    "type": "object",
    "title": "Workflow (get)",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier for this workflow."
        },
        "startStates": {
            "type": "array",
            "description": "The names of all the states that can be chosen for a newly-created form data instance's `status` property.",
            "items": {
                "type": "string"
            }
        },
        "type": {
            "type": "string",
            "description": "The form type this workflow applies to."
        },
        "states": {
            "type": "array",
            "description": "A list of possible workflow states, i.e. possible values of the form data's `status` property.",
            "items": {
                "$ref": "#/components/schemas/workflow-state"
            }
        },
        "transitions": {
            "type": "array",
            "description": "A list of valid workflow transitions. The `status` property of a form data instance can only be changed if there is a transition, accessible to the current user, whose `start` property matches the current value of the `status` property of the form, and whose `end` property matches the new `status` value.",
            "items": {
                "$ref": "#/components/schemas/workflow-transition"
            }
        },
        "startingTransitions": {
            "type": "array",
            "nullable": true,
            "description": "Transitions that govern setting the `status` property of a brand-new form data instance. These will each have a null value for `start` and a starting state name for `end`. Clients should not depend on this array existing or including a transition for every start state, but should still allow the user to select any start state when creating a new form data instance.",
            "items": {
                "$ref": "#/components/schemas/starting-transition"
            }
        },
        "uninitializedState": {
            "description": "Workflow state representing the status of a new form data instance, before it has been saved. This mainly just determines (through the `editableProperties` array) which properties can be set on the form's initial save. Even though this state's `name` property may be null, the form's `status` property will have to be set to a valid, non-null value that matches one of the start state names.",
            "$ref": "#/components/schemas/uninitialized-state"
        }
    },
    "additionalProperties": false
}

Workflow State stateCategory

Classifies this state as a 'Closed', 'Open', or 'Draft' state. While a form data instance is in this state, its state property will automatically be set to this string.

Closed

String

Open

String

Draft

String

json

{
    "type": "string",
    "description": "Classifies this state as a 'Closed', 'Open', or 'Draft' state. While a form data instance is in this state, its `state` property will automatically be set to this string.",
    "enum": [
        "Closed",
        "Open",
        "Draft"
    ],
    "title": "Workflow State stateCategory"
}

Workflow State

name

String

The name of this state. This is used both for display purposes and to uniquely identify this state within the workflow. If a form has a workflow, its status property must match a state's name property.

color

String, null

A hexadecimal RGB color string, e.g. '#ff0000'. This provides a hint to clients on how to highlight forms based on their current status property. Not all clients use, or are required to use, this property, and it may be null.

editableProperties

String[], null

The names of properties that can be edited while the workflow is in this state.

Workflow State stateCategory

workflow-state-stateCategory

Classifies this state as a 'Closed', 'Open', or 'Draft' state. While a form data instance is in this state, its state property will automatically be set to this string.

json

{
    "type": "object",
    "title": "Workflow State",
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of this state. This is used both for display purposes and to uniquely identify this state within the workflow. If a form has a workflow, its `status` property must match a state's `name` property."
        },
        "color": {
            "type": "string",
            "nullable": true,
            "description": "A hexadecimal RGB color string, e.g. '#ff0000'. This provides a hint to clients on how to highlight forms based on their current `status` property. Not all clients use, or are required to use, this property, and it may be null."
        },
        "editableProperties": {
            "type": "array",
            "nullable": true,
            "items": {
                "type": "string"
            },
            "description": "The names of properties that can be edited while the workflow is in this state."
        },
        "stateCategory": {
            "type": "string",
            "description": "Classifies this state as a 'Closed', 'Open', or 'Draft' state. While a form data instance is in this state, its `state` property will automatically be set to this string.",
            "enum": [
                "Closed",
                "Open",
                "Draft"
            ],
            "title": "Workflow State stateCategory",
            "$ref": "#/components/schemas/workflow-state-stateCategory"
        }
    },
    "additionalProperties": false
}

Workflow Transition notes

Denotes whether the transition allows or requires a workflow note to be set when it is triggered (workflowNote property on Form Data Update object). Possible values: 'None', 'Optional', 'Required'.

None

String

Optional

String

Required

String

json

{
    "type": "string",
    "description": "Denotes whether the transition allows or requires a workflow note to be set when it is triggered (`workflowNote` property on `Form Data Update` object). Possible values: 'None', 'Optional', 'Required'.",
    "enum": [
        "None",
        "Optional",
        "Required"
    ],
    "title": "Workflow Transition notes"
}

Workflow Transition

displayName

String

The name of this transition, i.e. the text that should appear on the UI element that triggers this transition.

start

String

The name of the workflow state where this transition begins.

end

String

The name of the workflow state where this transition ends.

Workflow Transition notes

workflow-transition-notes

json

{
    "type": "object",
    "title": "Workflow Transition",
    "properties": {
        "displayName": {
            "type": "string",
            "description": "The name of this transition, i.e. the text that should appear on the UI element that triggers this transition."
        },
        "start": {
            "type": "string",
            "description": "The name of the workflow state where this transition begins."
        },
        "end": {
            "type": "string",
            "description": "The name of the workflow state where this transition ends."
        },
        "notes": {
            "type": "string",
            "description": "Denotes whether the transition allows or requires a workflow note to be set when it is triggered (`workflowNote` property on `Form Data Update` object). Possible values: 'None', 'Optional', 'Required'.",
            "enum": [
                "None",
                "Optional",
                "Required"
            ],
            "title": "Workflow Transition notes",
            "$ref": "#/components/schemas/workflow-transition-notes"
        }
    },
    "additionalProperties": false
}

Uninitialized State

editableProperties

String[], null

The names of properties that can be edited while the workflow is in this state (i.e., when it is newly created and it has not yet been saved). A null value means there are no restrictions.

json

{
    "type": "object",
    "nullable": true,
    "title": "Uninitialized State",
    "properties": {
        "editableProperties": {
            "type": "array",
            "nullable": true,
            "items": {
                "type": "string"
            },
            "description": "The names of properties that can be edited while the workflow is in this state (i.e., when it is newly created and it has not yet been saved). A null value means there are no restrictions."
        }
    },
    "additionalProperties": false
}

Starting Transition notes

Denotes whether the transition allows or requires a workflow note to be set when it is triggered (workflowNote property on Issue Update object). Possible values: 'None', 'Optional', 'Required'.

None

String

Optional

String

Required

String

json

{
    "type": "string",
    "description": "Denotes whether the transition allows or requires a workflow note to be set when it is triggered (`workflowNote` property on `Issue Update` object). Possible values: 'None', 'Optional', 'Required'.",
    "enum": [
        "None",
        "Optional",
        "Required"
    ],
    "title": "Starting Transition notes"
}

Starting Transition

displayName

String

The name of this transition, i.e. the text that should appear on the UI element that triggers this transition.

end

String

The name of the workflow state where this transition ends.

Starting Transition notes

starting-transition-notes

Denotes whether the transition allows or requires a workflow note to be set when it is triggered (workflowNote property on Issue Update object). Possible values: 'None', 'Optional', 'Required'.

json

{
    "type": "object",
    "title": "Starting Transition",
    "properties": {
        "displayName": {
            "type": "string",
            "description": "The name of this transition, i.e. the text that should appear on the UI element that triggers this transition."
        },
        "end": {
            "type": "string",
            "description": "The name of the workflow state where this transition ends."
        },
        "notes": {
            "type": "string",
            "description": "Denotes whether the transition allows or requires a workflow note to be set when it is triggered (`workflowNote` property on `Issue Update` object). Possible values: 'None', 'Optional', 'Required'.",
            "enum": [
                "None",
                "Optional",
                "Required"
            ],
            "title": "Starting Transition notes",
            "$ref": "#/components/schemas/starting-transition-notes"
        }
    },
    "additionalProperties": false
}

DetailedError

Contains error information and an array of more specific errors.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

details

Error[]

Optional array of more specific errors.

json

{
    "type": "object",
    "description": "Contains error information and an array of more specific errors.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/Error"
            }
        }
    },
    "required": [
        "code",
        "message",
        "details"
    ],
    "additionalProperties": true
}

Detailed Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

DetailedError

Error Detailed information.

json

{
    "type": "object",
    "title": "Detailed Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error Detailed information.",
            "$ref": "#/components/schemas/DetailedError"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

Error Response

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?