Creating Your First Issue
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.
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. Also, make sure you add the Project Delivery API association when registering the application on the developer site, or, if you’ve already registered the application, edit it to enable the issues:read and issues:modify scopes under Issues.
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.
You can create an issue by making a POST request to the Create issue endpoint.
The URL for creating an issue is always the same:
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.
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
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.
Sample method, URL, and headers
Sample body (Copy and use this! Fill in your form ID.)
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.
next.hrefwill not normally appear if there is just one issue to return, but was included in the sample response for illustrative purposes.)
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.
https://api.bentley.com/issues/<id of issue to change>
Sample method, URL, and headers
Sample body (Copy and use this!)