Table of contents
Issues

Workflow

Download API definition:

GET https://api.bentley.com/issues/workflows/{type}?projectId

Retrieves the workflow for the given issue type in the given project. The project must be specified using the 'projectId' query string parameter.

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 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/manageforms.aspx?projectId=yourprojectid (replace yourprojectid with your actual project ID).

Authentication

Requires Authorization header with valid Bearer token for scope issues:read.

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

Request parameters

Name
In
Required?
Description
type
template
Yes

The issue type to get workflow for.

projectId
query
Yes

The ID of the project or context to get a workflow for.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with scope issues:read

Accept
No

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)

TableSchema
Name
Type
Description
workflow

Workflow (get)

TableSchema
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

TableSchema
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[]

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

stateCategory
String

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

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

notes
String

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

TableSchema
Name
Type
Description
editableProperties
String[]

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

Starting Transition

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

notes
String

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

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.

TableSchema
Name
Type
Description
error.code
String

Short string indicating the general category of error that occurred, such as '{Resource}NotFound'.

error.message
String

Longer string explaining to developers why the error occurred.

error.target
String,null

If relevant, this is the name of the property, URL template parameter, or query parameter that caused the error.

detailed-error-response

Indicates that a request failed and provides a list of details, explaining which properties or parameters in the request were incorrect. 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.

TableSchema
Name
Type
Description
error.code
String

Short string indicating the general category of error that occurred, such as 'Invalid{resource}Request'.

error.message
String

Longer string explaining to developers why the error occurred.

error.details
Object[]

If relevant, this is the name of the property, URL template parameter, or query parameter that caused the error.

Error

Contains error information and an optional array of more specific errors.

TableSchema
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

The target of the error.

details

Optional array of more specific errors.

Error Details

Contains error information.

TableSchema
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

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.

TableSchema
Name
Type
Description
error

Error information.