Creating Your First Issue

Introduction

Issues generally represent items of work that come up during a project and often need a particular person/group's attention by a certain due date. The Issues API lets you create, view, and edit these issues in your project.

In this tutorial, you will use the Issues REST API to create, modify, and view an issue. No programming experience is necessary, though familiarity with JSON and HTTP will help. This lesson is meant to begin getting you familiar with the Issues API's capabilities before you begin writing application code.

Prerequisites

If you haven't already, please complete the Web Application Quick Start tutorial before continuing. This will give you an iModel and a project under which you can create issues.

1. Creating an Issue

1.1. Choosing a Form Definition

---

In order to create an issue, you must associate it with a form definition. A form definition simply adds metadata to the issue, including how it should displayed in certain Bentley applications. However, for third-party applications, often the only property that matters is the type, as this will determine which type of issue is created.

To see all available form definitions in your project, make a request to the Get Project Form Definitions endpoint as shown under Sample request, replacing <yourId> with the ID of the project you created in a previous step.

This will return a list of form definitions similar to the Sample response.

Choose any one of these form definitions returned from your request and note its id for the next step.

1.2. Posting the Issue Data

---

You can create an issue by making a POST request to the Create issue endpoint.

URL

---

The URL for creating an issue is always the same: https://api.bentley.com/issues

Body

---

A new issue typically includes a few simple textual properties and, optionally, some metadata properties linking it to an iModel and, potentially, a specific element in that iModel. We'll go over those metadata properties (anything denoted as "Origin info" on the documentation page) in another tutorial.

The only property absolutely required for a new issue request is:

• formId: The ID of one of the form definitions in your project, as retrieved from the Get Project Form Definitions endpoint.

Other properties that are typically included are:

• subject: A short descriptive title of the issue, usually less than a sentence.
• description: A longer, more detailed explanation of the issue. Can be multiple sentences and can span multiple lines.
• assignee or assignees: A person, or list of people, respectively, who should review the issue and take action. These must be members of the current project. If neither property is set, assignee will default to whoever created the issue, i.e. you.
• dueDate: Date by which the assignee(s) should take action on the issue, if applicable. Apps might warn users when an issue is near due or overdue, for instance.

Generally, an app that creates issues would collect these properties from the user, such as by providing a text box for subject, a text area for description, a dropdown list of project members for assignee, and so forth.

Copy the sample body from the pane on the right and visit the documentation page to create your first issue. After you click Try It, paste the body into the text area, overwriting any JSON already there. Be sure to replace <your form id> with the id you obtained in Step 1.1.

Response

---

If you've made the request correctly, you should receive a response similar to the sample. Note that several properties are automatically filled in by the server, even though you didn't specify them: type is equal to the type of the form definition you chose, and properties such as createdBy and createdDateTime were automatically set to show who created the issue and when. You will need to use the id property's value to make further requests regarding that issue.

2. Viewing Your Issues

2.1. Viewing All Issues in Project

---

Make a request to the Get Project Issues endpoint to get a summary of all the issues in the project. You must specify the projectId in a query parameter, and you can optionally filter by type as an additional query parameter.

2.2 Viewing a Single Issue's Details

---

To retrieve all properties of an issue, call the Get issue details endpoint.

The URL for this request is https://api.bentley.com/issues/&lt;id> where <id> equals the id property of the issue you want to look up (in this case, the one you created in Step 1.2).

3. Modifying an Issue

Once you've created an issue, you can call the Update issue endpoint to modify its properties. Updating an issue can be done simply by making a PATCH request to the same URL where you retrieved its details (ending in the issue's ID). Provide a JSON object body containing only the properties you want changed; anything not included will keep its saved values. (Note: Including a property with a value of null on the will set that property on the saved issue to null; it is not the same as omitting the property from the request entirely.)

For example, if you wanted to make the description slightly more detailed, you could make a request using the body shown to the right. Be sure to set the id URL parameter to the ID of your newly created issue.

URL format

---

https://api.bentley.com/issues/<ID-of-issue-to-change>

Continue learning