Adding Attachments and Comments to Your Issue

Introduction

Attachments and comments provide a great way for your team to discuss and collaborate on solving an issue. Attachments let you provide files with more details about an issue, and comments let multiple people ask questions and talk about an issue without overwriting each others’ changes.

In this tutorial, you will learn how to use the Issues REST API to add comments to an already-existing issue and view all of the issue’s comments. You will also use the API to attach a file to the issue and then download it.

Prerequisites

You will need to create an issue in your project so that you can add comments and attachments to it. Please complete the tutorial Creating Your First Issue if you haven’t already.

Once you have created an issue, note its id property. You will need to use that anytime you see <your issue id> in this tutorial.

Info

Skill level:

Basic

Duration:

15 minutes

1. Comments

Comments are simple text posts that are associated with a single issue. Many different users in your project can comment on an issue, and anyone who can view the issue will be able to see who said what and when. They’re a useful tool for asking questions or providing clarification.

1.1. Creating a Comment


Creating a comment is simple! Make a POST request to the Add Comment to Issue endpoint. The body is a JSON object containing just one property—text—whose string value is the contents of the message you want to send. The server will automatically generate and save metadata, including when the comment was posted and who made the request.

URL


The path includes your issue id followed by /comments, i.e. https://api.bentley.com/issues/<your issue id>/comments

Body


Provide a JSON object with a text property containing your message, and no other properties.

Response


If the request succeeds, the response will just consist of the 201 Created status code (and some headers) without a body.


Method, sample URL, and headers


1 2 3 4 5 POST https://api.bentley.com/issues/<your issue id>/comments HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token> Content-Type: application/json

Sample body


1 2 3 { "text": "This has been noted and will be fixed in version 1.3." }

Sample response


1 HTTP/1.1 201 Created

1.2. Viewing an Issue’s Comments


You can read the comment you added by making a GET request to the Get Issue Comments endpoint.

URL


The URL for this request is exactly the same as it is for creaing a comment: https://api.bentley.com/issues/<your issue id>/comments

Response


The response consists of an array of comments. For each comment, the author’s display name and the comment’s creation time are provided, even though you didn’t manually set them in your request.

Each comment in the response also includes a link that can be followed to request additional information about the comment’s author from the Get Project Team Member Details endpoint of the Projects API, assuming you have access to it.


Sample request


1 2 3 4 GET https://api.bentley.com/issues/<your issue id>/comments HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token>

Sample response


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 HTTP/1.1 200 OK Content-Type: application/json { "comments": [ { "id": "xospFt7H20-9uSSLOwfBeO7IKKXOvh1Nkl344vJ_s_E", "text": "This has been noted and will be fixed in version 1.3.", "authorDisplayName": "Andrew Menzies", "_links": { "author": { "href": "https://api.bentley.com/projects/16ab8bc6-c7de-4fdb-bdb9-248b3b07c178/members/9e543213-2457-466d-9de3-8d8a186b4189" } }, "createdDateTime": "2021-06-14T20:34:33.9220455Z" } ] }

2. Attachments

The Issues API supports attaching files of many different types to issues—nearly any non-executable file type is supported. These can include documents, images (like a problem at the project’s physical site or a screenshot of an iModel), and even short videos (up to 30MB). Adding an attachment to an issue right after you create it can be an excellent way of providing more context than words alone.

2.1. Adding an Attachment


Adding an attachment is a two-step process. First, make a POST request to the Add Attachment to Issue endpoint to create metadata for the file you’re about to upload.

URL


The URL path includes the issue’s id property followed by /attachments, i.e. https://api.bentley.com/issues/<id>/attachments.

Body


The request body is a JSON object. It must contain a fileName property which can be any valid filename (without a directory path). The file extension should be accurate for the type of file you are about to upload to ensure that users who download the file will be able to open it.

You may also add a caption property. It just contains simple text that can provide additional context to users who look up the issue’s attachments.

Response


If successful, the response will include a Location header with a URL. Now, for the second step: Upload your raw file (plus the Authorization header, as usual) via PUT request to that URL to complete the process.

You can upload the file using the Upload Attachment File endpoint. The attachmentId URL parameter is equal to the final segment of the URL that was returned in the Location header. (That is, the segment after /attachments/. For example, in the response shown under Sample response, the attachment id would be xospFt7H20-9uSSLOwfBeM-a1K5hBDdNtT9MMU6U2dI, but it’ll be different for your attachment.)

Note: To upload a file using the Try It feature of our documentation site, choose the Binary radio button under Body.


Method, sample URL, and header


1 2 3 4 5 POST https://api.bentley.com/issues/<your issue id>/attachments HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token> Content-Type: application/json

Sample body


1 2 3 4 { "fileName": "ExampleDoc.txt", "caption": "Document related to the issue" }

Sample response


1 2 3 HTTP/1.1 201 Created Location: https://api.bentley.com/issues/xospFt7H20-9uSSLOwfBeBs-UbbpqxhKgAL4wWWajpw/attachments/xospFt7H20-9uSSLOwfBeM-a1K5hBDdNtT9MMU6U2dI


Sample request (you will also need to include the file's bytes)


1 2 3 4 PUT https://api.bentley.com/issues/xospFt7H20-9uSSLOwfBeBs-UbbpqxhKgAL4wWWajpw/attachments/xospFt7H20-9uSSLOwfBeM-a1K5hBDdNtT9MMU6U2dI HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token>

2.2. Getting the Issue’s Attachments


Make a GET request to the Get Issue Attachments endpoint, passing your issue’s id as the id parameter, to get a list of all files attached to the issue.

This will return a JSON array of attachment metadata, including fileName, id, and the auto-populated size (in bytes) and createdDateTime. Find your attachment and take note of its id.

Make a GET request to the Get Attachment File by ID endpoint, passing the same issue id as the id parameter and passing the attachment id as the attachmentId parameter. This will return the file you uploaded earlier. (If using the Try It feature, our developer site will attempt to display the file’s bytes as text, so it may not work well for images. It might be better to try attaching a plain .txt file for purposes of this tutorial.)


Sample request to get attachment list


1 2 3 4 5 GET https://api.bentley.com/issues/<your issue id>/attachments HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token> Content-Type: application/json

Sample attachment list response


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 HTTP/1.1 200 OK Content-Type: application/json { "attachments": [{ "id": "xospFt7H20-9uSSLOwfBeM-a1K5hBDdNtT9MMU6U2dI", "fileName": "ExampleDoc.txt", "createdDateTime": "2021-06-16T19:11:21.2722577Z", "size": 405, "caption": "Document related to the issue", "binding": null, "type": "txt" }] }


Sample request to get file


1 2 3 4 GET https://api.bentley.com/issues/<your issue id>/attachments/<your attachment id> HTTP/1.1 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer <token>