Issue Service

View, create, and edit details of issues that have been raised in a CONNECT project or context, as well as their comments, attached files, and change history.  Retrieval of form definitions (which define how to display an issue in an interactive UI) is also supported, though customization of them is not, and should be done by a project administrator through the CONNECT Issues web application, if needed. This form-editing app can be found at https://connect-formmanager.bentley.com/ManageForms.aspx?projectId=yourProjectId where `yourProjectId` is replaced by the ID of the project you're creating custom forms for.

## Limits

All API calls that return a list of results will return a maximum of 50 results. Some endpoints support a `$top` parameter to specify a number of results to retrieve (up to the maximum) and a `continuationToken` parameter to continue paging through results, allowing access to results beyond the first 50. These parameters will be included in the documentation for those endpoints.

Clients with a Basic, Premium, or Enterprise subscription will be limited to 5000 requests per minute. Clients with a Trial subscription will be limited to 500 requests per minute.

issues-v1

---

Adds a new attachment to the specified issue. This only creates the attachment metadata; the file will need to be uploaded through a subsequent PUT call to the URL returned in the Location header of this endpoint's response.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the issue's associated form definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-attachment-to-issue

The ID of the issue to add an attachment to.

OAuth access token with scope `issues:modify`

Authorization

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

Accept

default

Indicates that the attachment metadata was created successfully. The file should then be uploaded via PUT to the URL in the Location header.

The URL where the attachment file should be uploaded.

Location

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.

HeaderNotFound

application/json;InvalidAuthorizationScheme

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

This response indicates that the user attempted to add an attachment to an issue that does not exist or is inaccessible to the user.

This response indicates that there is a problem with the request. Most likely, the 'includeHeader' parameter is included but not set to true or false.

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

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

retry-after

---

Deletes the specified attachment (including both its metadata and file) from the specified issue.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the issue's associated form definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-attachment

The ID of the issue to delete an attachment from.

attachmentId

Indicates that the attachment was successfully deleted. There is no response body in this case.

This response indicates that the attachment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the actual file contents for the attachment with the given ID. This API will attempt to infer the MIME type to return from the file's extension, but will return the default value of `application/octet-stream` if it does not recognize the extension.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the issue's associated definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-attachment-by-id

OAuth access token with scope `issues:read`

This response indicates that the specified attachment does not exist (code = 'AttachmentNotFound') or that the attachment metadata instance exists but does not have an associated file (code = 'FileNotFound').

---

Retrieves the metadata for all files attached to the given issue. In order to get the contents of a file itself, use the `Get attachment file by ID` endpoint, passing the `id` from the metadata object returned by this request as the `attachmentId` parameter of that request.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the issue's associated definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-issue-attachments

The ID of the issue to get attachments for

This response indicates that the specified issue does not exist or is inaccessible to the user.

---

Uploads a file's contents, associating it with the attachment metadata instance with the given ID. The request body is simply the file's bytes. If a file was already uploaded for the attachment with the given ID, that file will be overwritten.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the issue's associated form definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

upload-attachment-file

The ID of the issue this attachment belongs to.

The ID of the attachment metadata instance this file will be associated with.

Indicates that the attachment file was successfully uploaded

This response indicates that the specified attachment metadata instance does not exist or is inaccessible to the user.

Indicates that the file the user attempted to upload is above the maximum size.

---

Retrieves a reverse-chronologically-ordered list of all changes that have been made to this issue, including authors, dates, and old vs. new property values.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the issue's associated definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-issue-audit-trail

The ID of the issue to get audit entries for

---

Adds a new comment to the specified issue. Only the comment text is needed; the author and creation time will be automatically set by the server.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the issue's associated form definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

add-comment-to-issue

Indicates that the comment was created successfully

This response indicates that the issue the user attempted to add a comment to does not exist or is inaccessible to the user.

This response indicates that there is a problem with the format of the request body. Most likely causes: The body is not valid JSON, or the 'text' property is missing or not a string.

---

Deletes the specified comment from the specified issue.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Comment** (`Forms_CommentAccess`) permission for the project, or for the issue's associated form definition if form definition security is specified. (Having **Create/Modify**, **Assign**, **Approve**, or **Full** permission automatically grants the **Comment** permission as well.)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-comment

The ID of the issue the comment is associated with.

commentId

Indicates that the comment was successfully deleted. There is no response body in this case.

This response indicates that the comment with the specified ID does not exist or is inaccessible to the user.

---

Retrieves the text and metadata for all comments that have been posted to the given issue. If the Prefer header was specified with the value "return=representation", the response will include the email address of each comment author, though this may incur additional processing time.  If there is an extraordinarily large number of comments, only 50 distinct user email addresses will be retrieved and shown. Regardless of the Prefer header value, the "_links" object associated with each comment will provide a link to additional information about the comment author.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the issue's associated definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-issue-comments

Sets the level of detail to return. For this endpoint, setting 'return=representation' will add the comment authors' email addresses to the response.

Prefer

minimal

representation

---

Gets the specified issue exported to the specified file format. Currently, the default--and only supported format--is PDF. The issue with the specified ID will be laid out in the PDF according to its associated form definition.

The generated PDF will have a header at the top of each page with metadata about the issue (such as its name and creation date) unless the 'includeHeader' query parameter is set to false.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

download-issue-as-file

The ID of the issue to download as a file.

The type of file to download the form as. Currently the default, and only supported value, is 'PDF'.

fileType

If downloading as PDF, sets whether to include form metadata on the top of each page. Default is true.

includeHeader

Indicates that the file was successfully generated in the requested format. The response body consists of the generated file.

This response indicates that the specified issue does not exist or is inaccessible.

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'fileType' parameter is set to an unsupported file type, or the 'includeHeader' parameter is set to a non-boolean value.

---

Requests that anywhere from 1 to 5 issues be exported to a file and saved in cloud-based project storage (accessible through the Storage API). Currently 'pdf' is the only supported file type. The IDs of the issues must be specified in a query string parameter named "ids", separated by commas if there is more than one. A sample request URL that exports 3 issues to a PDF is as follows--

https://api.bentley.com/issues/exportPdfToStorage?ids=abab23524535,89458jjlij,32636wtewtwt&folderId=090909877987&includeHeader=true

Note that unlike most GET requests, this is not an idempotent operation; each time it is called, a new file will be generated. The response will not contain the file itself, but links to download it from Storage.

All issues specified in the request must come from the same project, or the request will fail. The client may also specify the ID of a destination folder where the file should be saved; otherwise, it will be saved in the project's root folder.  They can also specify whether to include a textual header with issue metadata at the top of each page (default) or exclude it.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

export-issues-to-storage

Instance IDs of issues to export. Must include at least 1, but no more than 5, IDs, separated by commas, and they all must come from the same project.

If exporting to PDF, indicates whether to include metadata on top of each page.  Default is true.

Indicates the type of file to create. Right now PDF is the only valid option, and is the default if not specified.

The ID, as retrieved from the Storage API, of the folder where the produced file should be saved. If not set, will default to the project's root folder.

folderId

Indicates that the file was generated successfully. The response includes the generated file's filename as well as links for using the Storage API to retrieve it.

Either one of the issues specified does not exist (code = 'IssueNotFound') or the destination folder does not exist (code = 'FolderNotFound').

This response indicates that there is a problem with the request parameters. Depending on the problem, the 'details' array may include specific errors.

---

Gets the full form definition with the specified 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-form-definition-by-id

The ID of the form definition to get. This should be an ID retrieved from the "Get project form definitions" endpoint or an issue's "formId" property.

This response indicates that the form definition with the specified ID does not exist or is inaccessible to the user.

---

Use this request to look up a list group, which is a nested object structure that defines the options available in a chain of cascading list form controls. (Cascading lists are a set of &lt;select&gt; elements where only the first one is initially enabled until an option in it is selected, and then, depending on which option was selected, the available options in the next list can vary.) Each property in the structure represents an option in a select list, and its children represent options that become available in the next list in the chain if that option is selected.

### Sample Explanation

The sample for the 200 response shows an example of a list group that could be assigned to 3 controls in a form to let the user pick an American football team by conference, division, and name. Since the result has two properties ("AFC" and "NFC") as direct children of the "optionsTree" property, the first list in the cascading list chain would have two options--"AFC" and "NFC".  Whichever option is chosen, its child properties become available for selection in the second list, and so forth.  For example, if "AFC" and "North" were chosen for the first two lists respectively, the third list would show the available options "Bengals", "Browns", "Ravens", and "Steelers".  These four properties just have empty objects as their values because this particular list group only has three layers; these options are the final options in the chain and have no descendants.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-list-group

The ID of the form definition this list group is used in.

listGroupId

This response indicates that the list group or its associated form definition was not found.

---

Retrieves a list of Approved form definitions for the project with the given ID.  This only returns the definition's name, type, and ID. The full definitions will be returned in the 'Get form definition by ID' endpoint.

Note that in order to create an issue, it must be associated with the ID of one of these form definitions (through the 'formId' property in the 'Create issue' request body). This API cannot be used to create or edit form definitions. They can only be created/edited/imported by project administrators through the Bentley Form Manager webapp, which is accessible at https://connect-formmanager.bentley.com/manageforms.aspx?projectId=yourprojectid (replace `yourprojectid` with your actual project ID).

Note that the 'projectId' query string parameter is required. It must be a valid project GUID to get form definitions from.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-form-definitions

The GUID of the project to get form definitions for.

projectId

The issue type to get form definitions for. Omit to get all form definitions, regardless of type.

type

This response indicates that the project with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing projects.)

This response indicates that there is a problem with the format of the URL. Most likely problem: The 'projectId' parameter is missing or not a valid GUID.

---

Gets a link to a static image to be displayed in a form. The 'fileId' parameter should match the 'fileId' property of a static image control in the form's definition.  It will be a positive integer.  This endpoint returns only a _links object containing the URL of the actual file, which is publicly available and can be set as the 'src' attribute of an HTML <img> tag to display the image.

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-static-image

The ID of the form definition to get a static image for.

The ID of the static image.  Will be a positive integer, not a GUID.

fileId

This response indicates that the static image or its associated form definition was not found.

---

Creates a new issue. The user must specify the ID of a form definition to associate the issue with; that will set its issue type as well as determine how clients such as the CONNECT Issues web app will display it. The form definition ID should be obtained by calling the 'Get project form definitions' endpoint.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Create/Modify** (`Forms_CreateAccess`) permission for the project, or for the chosen form definition if form definition security is specified for it.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

create-issue

The plans do not specify what material this support beam will be made out of.

Unspecified material

Indicates that the issue was successfully created. The response body contains the issue's data after creation, including its id.

This response indicates that the specified form definition does not exist (or is inaccessible due to insufficient permissions).

This response indicates that there is a problem with the format of the request body. Most likely causes: The 'formId' property is missing, an unrecognized standard or custom property was added, a standard property was set in the 'properties' object instead of the top-level object, the body is invalid JSON, or a property was set to a value of the wrong type.

---

Deletes the issue with the specified ID.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **Delete** (`Forms_DeleteForms`) permission for the project.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-issue

Indicates that the issue was successfully deleted. There is no response body in this case.

This response indicates that the issue with the specified ID does not exist or is inaccessible to the user.

---

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 ProjectWise Forms **View** (`Forms_ViewAccess`) permission for the project, or for the issue's associated definition if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-issue-details

This response indicates that the specified project does not exist, or the user doesn't have permission to view it.

---

Retrieves a list of issues for the project with the given ID. If the Prefer header is omitted, or set to "return=minimal", this only returns basic info about each issue--its ID, display name, type, subject, and whether it is in an Open, Closed, or Draft state. Setting the Prefer header to "return=representation" will return more data. Use the "Get Issue Details" endpoint to see full information about a particular issue.

Note that the 'projectId' query string parameter is required. It must be a valid project GUID to get issues from.

### Permissions

To use this endpoint, the user is required to have the ProjectWise Forms **View** permission (`Forms_ViewAccess`) for the project, or for some issues' associated form definitions if form definition security is specified. (Having any other ProjectWise Forms permission automatically grants the **View** permission as well. If a user does not have permission to view a particular issue, it will be silently excluded from the list.)

### 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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-project-issues

The type of issue data to get. Omit to get all types.

The number of issues to get in each page. Max 50, which is also the default if this parameter is not included.

$top

Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.

continuationToken

Required. The GUID of the project to get issues for.

If set, will only retrieve issues in the specified workflow state (Open, Closed, or Draft)

state

Gets whether to return only a summary of each item (return=minimal) or full properties of each item (return=representation).  Default is return=minimal

This response indicates that the issue with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing issues.)

---

Modifies the provided properties of the specified issue to match the values provided in the request.

Setting a property value to null in the request will set the corresponding property value to null on the issue. However, omitting a property from the request body entirely will leave that property's current value on the issue unchanged.  Also, setting an object (other than "properties") to null will have the same effect as setting each individual property in that object to null.

### Permissions

To use this endpoint, the user is required to have different ProjectWise Forms permissions (for the project, or for the issue's associated form definition if form definition security is specified) based on the changes being made:

- Change to the `status` property: **Approve** (`Forms_ApproveAccess`) permission
- Change to the `assignee` or `assignees` property: **Assign** (`Forms_AssignAccess`) or **Approve** permission
- Changes to other properties: **Create/Modify** (`Forms_CreateAccess`) permission

**Full Access** (`Forms_FullAccess`) will satisfy all of these requirements.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `issues:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

modify-issue

The plans do not specify what material this support beam is made of. Updated bounding box for v1.2 of the blueprint.

Unspecified material (v1.2)

Indicates that the changes were successfully made. The response body contains the issue's data after modification, including both changed and unchanged properties. Note: If a workflow transition occurred, some properties may have been automatically changed in addition to the properties the client specified to change in the request.

This response indicates that the issue the user attempted to update does not exist (or is inaccessible due to insufficient permissions).

This response indicates that there is a problem with the format of the request body. Most likely causes: An unrecognized standard or custom property was added, a standard property was set in the 'properties' object instead of the top-level object, the body is invalid JSON, or a property was set to a value of the wrong type.

---

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](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-workflow

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

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.

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

Changelog - Issues | iTwin Platform

Use the Issues REST API to add documents, images, and comments to an issue.

Adding Attachments and Comments to Your Issue

Learn the basics of the Issues REST API by creating, viewing, and modifying an issue.

Creating Your First Issue

Use a workflow to track the status of an issue created through the Issues REST API.