Table of contents
Issues
Download API definition:
GET https://qa-api.bentley.com/issues/workflows/{type}?iTwinId

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

Name
Required?
Description
type
Yes

The issue type to get workflow for.

iTwinId
Yes

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

Name
Required?
Description
Authorization
Yes

OAuth access token with itwin-platform scope

Accept
Yes

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

Response 200 OK

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 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.

json
{
    "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.

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

Name
Description
retry-after

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

Workflow Response (get)

Name
Type
Description
workflow

Workflow (get)

Name
Type
Description
id
String

Unique identifier for this workflow.

startStates
String[]

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

type
String

The issue type this workflow applies to.

states

A list of possible workflow states, i.e. possible values of the status issue property.

transitions

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.

startingTransitions

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.

uninitializedState

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.

Name
Type
Description
Closed
String
Open
String
Draft
String

Workflow State

Name
Type
Description
name
String

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.

color
String, null

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.

editableProperties
String[], null

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

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 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'.

Name
Type
Description
None
String
Optional
String
Required
String

Workflow Transition

Name
Type
Description
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

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

Name
Type
Description
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.

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'.

Name
Type
Description
None
String
Optional
String
Required
String

Starting Transition

Name
Type
Description
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

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.

Name
Type
Description
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

Optional array of more specific errors.

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.

Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

Name
Type
Description
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.

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.

Name
Type
Description
error

Error information.