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.

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.

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 creating 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 iTwin Team Member Details endpoint of the Access Control API, assuming you have access to it.

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

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

Continue learning