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

Retrieves all properties of the specified issue.

Known, common properties will be returned directly on the 'issue' object, whereas custom properties unique to the issue's type will be returned on the 'properties' sub-object.

Note that many properties in the schema are described as 'Origin info.' This means that they are metadata about where the issue came from and what business domain object(s) it is related to, such as a PDF file or a 3D model. Their meanings can differ from application to application. Many applications will use only a subset of these properties, and in general applications SHOULD NOT use or set these values unless they have a good reason to do so. Other properties, not marked 'Origin info', will commonly be set on most issues, but clients SHOULD NOT assume that all of them are set.

Permissions

To use this endpoint, the user is required to have the Forms View (Forms_ViewAccess) permission for the iTwin, or for the issue's associated form definition if form definition security is specified. (Having any other level of Forms permission automatically grants the View permission as well.)

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
id
Yes

The ID of the issue to get details for

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
{
    "issue": {
        "id": "e5Ue5Ue5U02hNz19awLcRsnTtOGubQZPhV123456789",
        "formId": "VcVcVcC8sUuVcgeXz1Ih_cnRU1gUD8dKqbBHUBHUBHU",
        "type": "Punchlist",
        "displayName": "PUN-00001",
        "state": "Open",
        "subject": "Unspecified material",
        "description": "The plans do not specify what material this support beam will be made out of.",
        "dueDate": "2021-07-27T00:00:00Z",
        "boundingBox": {
            "lowerLeftPoint3D": {
                "x": 0.0,
                "y": 1.0,
                "z": 2.0
            },
            "upperRightPoint3D": {
                "x": 3.0,
                "y": 4.0,
                "z": 5.0
            }
        },
        "createdBy": "Joe User",
        "createdDateTime": "2021-02-08T19:39:10.7421874Z",
        "lastModifiedBy": "Joe User",
        "lastModifiedDateTime": "2021-02-08T19:39:10.7421874Z",
        "number": "ISS-00001",
        "status": "Draft",
        "statusColor": "#ff0000",
        "assignee": {
            "displayName": "Sue Doe",
            "id": "ac777777-7770-4777-9777-77765ff26777"
        },
        "assignees": [{
                "displayName": "Sue Doe",
                "id": "ac777777-7770-4777-9777-77765ff26777"
            },
            {
                "displayName": "Jim Jay",
                "id": "bd888888-8880-4888-9888-88865ff26888"
            }
        ],
        "modelPin": {
            "location": {
                "x": 239397.84550275817,
                "y": 3969886.4094498586,
                "z": 37.408973499239124
            },
            "description": "Location of support beam"
        },
        "modelView": {
            "iModelJsView": "01ababab-1230-4567-9012-88865ff26888",
            "cameraView": {
                "viewPoint": {
                    "x": 200000,
                    "y": 300000,
                    "z": 37
                },
                "direction": {
                    "x": 2,
                    "y": 3,
                    "z": 30
                },
                "up": {
                    "x": 0,
                    "y": 0,
                    "z": 1
                },
                "viewToWorldScale": 10,
                "fieldOfView": 90
            }
        },
        "modelEventDateTime": "2021-02-27T11:13:33Z",
        "location": {
            "longitude": -40,
            "latitude": -30,
            "elevation": 200,
            "description": "Construction site"
        },
        "properties": {}
    }
}

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 specified project does not exist, or the user doesn't have permission to view it.

json
{
    "error": {
        "code": "IssueNotFound",
        "message": "Requested issue is not available.",
        "target": "id"
    }
}

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.

Issue Details (get)

Name
Type
Description

Issue (get)

Contains the full data of this issue. Any property that was never set on the issue will be omitted from the response.

Name
Type
Description
id
String

Unique identifier for this instance. Read-only.

displayName
String, null

Name that should be used to show this issue in a list of issues in the UI. This is read-only. Project managers can configure how this is generated; usually, it will be the value of another property.

formId
String

The ID of the form definition that this issue was created with. Note: This property will only be returned during the 'Get issue details' query, not in the result of a Create or Modify operation.

subject
String, null

Brief title/description of the issue.

description
String, null

Detailed description of the issue.

type
String

Read-only. Describes which domain of work the issue involves, which determines what applications will show it. Automatically set based on the form definition that was used to create the issue.

number
String, null

An human-readable identifier for the issue, consisting of an alphanumeric prefix (that can be configured by the project administrator) followed by an auto-incrementing number. Read-only.

dueDate
Date-time, null

The date by which an action should be taken on this issue. Applications will use this to determine whether an issue is near due or overdue.

status
String

The current workflow status the issue is in right now.

state
String

Indicates whether the issue's status is an Open, Closed, or Draft status. This property is read-only.

statusColor
String, null

A RBG hexadecimal color string, e.g. #ff0000. Read-only. If set, this gives a hint for how to highlight the issue in a list of issues based on its current workflow status.

assignee

The primary user or role assigned to this issue.

assignees

For cases when an issue is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.

createdBy
String

The display name of the user who originally created this issue. Read-only.

createdDateTime
Date-time

The date and time when this issue was originally created. Read-only.

lastModifiedBy
String

The display name of the user who most recently made a change to this issue. Read-only.

lastModifiedDateTime
Date-time

The date and time when this issue was most recently edited. Read-only.

sourceEntity

Origin info. An object linking the issue to an entity outside the Issues service, such as a file in Storage or an element in an iModel, that the issue was created to pertain to.

boundingBox

Origin info. Describes a rectangular-prism area of the model that the issue pertains to.

modelPin

Origin info. Describes a point in 3D space that the issue pertains to. May or may not be based on the position of a particular element.

modelView

Origin info. Describes a view of the model that shows the relevant elements that the issue pertains to.

modelEventDateTime
Date-time, null

The date and time represented in the model where the issue occurred (if in a 4D model).

location

Origin info. Describes the geographical coordinates the issue pertains to.

properties

Contains all issue-type-specific and user-defined properties that were set on this issue. Properties set here may be strings, numbers, booleans, arrays, or objects, depending on how the project's administrator defined them in the Form Designer.

_links

Links to related entities, if applicable.

Primary Assignee

An object describing the primary user or role assigned to an issue.

Name
Type
Description
id
String

The GUID identifying the user or role.

displayName
String

The role's name, or the user's given name and surname, as it should be displayed in an application.

Secondary Assignee

An object describing one of potentially several users or roles assigned to an issue.

Name
Type
Description
id
String

The GUID identifying the user or role.

displayName
String

The role's name, or the user's given name and surname, as it should be displayed in an application.

isRole
Boolean

If true, this is a role; otherwise, it is an individual user.

bounding-box

Origin info. Describes a rectangular-prism-shaped region in a 3D model that the issue pertains to.

Name
Type
Description
lowerLeftPoint3D

The lower-left corner of the region.

upperRightPoint3D

The upper-right corner of the region.

Model Pin

Origin info. Associates an issue with a single point in a model that does not necessarily correspond to a model element.

Name
Type
Description
location

The location of the pin.

description
String, null

String describing the relevance of the pin's location.

Model View

Origin info. Describes the view that was visible when the issue was created.

Name
Type
Description
cameraView

An object describing the view that can be parsed by non-IModelJS applications.

iModelJsView
String, null

The ID of a saved view showing the issue.

point3D

Name
Type
Description
x
Number
y
Number
z
Number

camera

Name
Type
Description
viewPoint

The location of the camera within the model.

direction

Endpoint of a vector from the origin that determines the camera's facing direction.

up

Endpoint of a vector from the origin that determines which direction appears as upwards in the view.

viewToWorldScale
Number, null

Determines the zoom level of the camera, i.e. how much to multiply 1 distance unit in the view by to get the actual distance in meters in the model. Either this or fieldOfView should be specified, but not both.

fieldOfView
Number, null

Determines the number of degrees in the circular arc around the camera's position that is visible in the view. Either this or viewToWorldScale should be specified, but not both.

location

Origin info. The geographical location the issue pertains to.

Name
Type
Description
latitude
Number, null

The degrees latitude of the issue's location. North: positive, south: negative.

longitude
Number, null

The degrees longitude of the issues location. East: positive, west: negative.

elevation
Number, null

The geographical elevation above/below sea level. Units for this property are not standardized, so an application should not make assumptions about this property's value set by other applications unless that other application's units are known.

description
String, null

A string describing the significance of this location.

source-entity-file

Represents a file in Storage about which an issue was created.

Name
Type
Description
storageFile.fileId
String

ID used to identify the file in the Storage API.

storageFile.folderId
String

ID of the folder containing the file in the Storage API.

storageFile.fileName
String, null

Name of the file, including extension.

source-entity-i-model-element

Represents an element in an iModel about which an issue was created.

Name
Type
Description
iModelElement.modelId
String

ID of the iModel containing the element, as it exists in the iModels API.

iModelElement.elementId
String

ID of the element. Can be a hexadecimal numeric string (space-separated to include multiple elements) or a presentation key.

iModelElement.changeSetId
String

ID of the changeset where the issue was created.

iModelElement.modelName
String

Name of the model.

source-entity-links-file

Links to retrieve the related file, and the folder that contains it, from the Storage API.

Name
Type
Description
folder
file

source-entity-links-i-model-element

Links to retrieve the related element's specific changeset, or iModel in general, from the iModels API.

Name
Type
Description
iModel
iModelChangeset

Dynamic Object

An object whose properties can vary depending on user customization within the project.

link

Name
Type
Description
href
String

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.