Retrieves the workflow for the given issue type in the given iTwin or project. The iTwin 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 an iTwin 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 project 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 parameters
The issue type to get workflow for.
The ID of the iTwin or project to get a workflow for. (Note: projectId is also accepted as an alias for this parameter.)
Request headers
OAuth access token with itwin-platform scope
Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.
Response 200 OK
OK
{ "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.
{ "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 issue 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 issue type.
{ "error": { "code": "WorkflowNotFound", "message": "Requested workflow is not available.", "target": "type" } }
Response 422 Unprocessable Entity
A URL parameter was malformed. Most likely reason: The required 'projectId' query parameter is missing or not a valid GUID.
{ "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 client sent more requests than allowed by this API for the current tier of the client.
{ "error": { "code": "RateLimitExceeded", "message": "The client sent more requests than allowed by this API for the current tier of the client." } }
Response headers
Number of seconds to wait until client is allowed to make more requests.
Workflow Response (get)
Workflow (get)
Unique identifier for this workflow.
The names of all the states that can be chosen for a newly-created issue's status property.
The issue type this workflow applies to.
A list of possible workflow states, i.e. possible values of the status issue property.
A list of valid workflow transitions. The status property of an issue 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 issue, and whose end property matches the new status value.
Transitions that govern setting the status property of a brand-new issue. 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 issue.
Workflow state representing the status of a new issue, before it has been saved. This mainly just determines (through the editableProperties array) which properties can be set on the issue's initial save. Even though this state's name property may be null, the issue's status property will have to be set to a valid, non-null value that matches one of the start state names.
Workflow State stateCategory
Classifies this state as a 'Closed', 'Open', or 'Draft' state. While the issue is in this state, its state property will automatically be set to this string.
Workflow State
The name of this state. This is used both for display purposes and to uniquely identify this state within the workflow. If an issue has a workflow, its status property must match a state's name property.
A hexadecimal RGB color string, e.g. '#ff0000'. This provides a hint to clients on how to highlight issues based on their current status property. Not all clients use, or are required to use, this property, and it may be null.
The names of properties that can be edited while the workflow is in this state.
Classifies this state as a 'Closed', 'Open', or 'Draft' state. While the issue is in this state, its state property will automatically be set to this string.
Workflow 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'.
Workflow Transition
The name of this transition, i.e. the text that should appear on the UI element that triggers this transition.
The name of the workflow state where this transition begins.
The name of the workflow state where this transition ends.
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'.
Uninitialized State
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.
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'.
Starting Transition
The name of this transition, i.e. the text that should appear on the UI element that triggers this transition.
The name of the workflow state where this transition ends.
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'.
DetailedError
Contains error information and an array of more specific errors.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
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
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
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.
Was this page helpful?