iTwin Issues icon

iTwin Issues

iTwin Issues API for issue management, form definitions, attachments, and comments

Actions27

Overview

The "Create issue" operation in the iTwin Issues node allows users to create a new issue within an iTwin project. This operation is useful for managing and tracking issues related to construction, design, or other project workflows by associating them with specific form definitions and metadata. It supports detailed descriptions, due dates, status updates, assignees, and origin information such as 3D model regions or geographical locations.

Typical use cases include:

  • Logging defects or problems found during project reviews.
  • Assigning issues to team members or roles for resolution.
  • Tracking issue status and deadlines.
  • Associating issues with specific parts of a 3D model or geographic location for precise context.

For example, a project manager can create an issue describing a structural defect, assign it to an engineer, set a due date, and link it to a particular area in the 3D model for easy identification and follow-up.

Properties

Name Meaning
Form ID The ID of the form definition to associate this issue with. Determines how the issue is displayed in Bentley applications. Must correspond to an existing form definition in the project.
Subject A brief title or description summarizing the issue.
Description A detailed explanation of the issue.
Due Date The deadline by which action should be taken on the issue. Used to identify near-due or overdue issues.
Status The current workflow status of the issue (e.g., Open, In Progress, Closed).
Assignee An object describing the primary user or role assigned to the issue.
Assignees A list of multiple users or roles assigned to the issue, used when more than one assignee is involved.
Source Entity Information about a file in storage related to the issue.
Bounding Box Describes a rectangular-prism-shaped region in a 3D model that the issue pertains to, providing spatial context.
Model Pin Associates the issue with a single point in a 3D model, which may not correspond to a specific model element.
Model View Describes the view visible when the issue was created, capturing the visual context.
Model Event Date Time The date and time represented in the model where the issue occurred, relevant for 4D models (time-based models).
Location Geographical location data related to the issue.
Properties Customizable object containing additional properties defined by the user or project customization.
Options > Custom Payload Allows overriding the request body with a custom JSON payload instead of using the standard fields. Useful for advanced use cases requiring full control over the API request body.

Output

The output of the "Create issue" operation is a JSON object representing the newly created issue as returned by the iTwin Issues API. This typically includes all the details of the issue such as its unique identifier, form association, subject, description, status, assignees, origin information, timestamps, and any other metadata provided or generated by the system.

No binary data output is indicated for this operation.

Dependencies

  • Requires an API authentication token configured via OAuth2 credentials to access the Bentley iTwin platform API.
  • The node depends on the iTwin Issues API endpoint at https://api.bentley.com.
  • Proper form definitions must exist in the project to associate issues correctly; these are managed externally via Bentley's Form Designer.
  • The node uses internal utilities for making authenticated HTTP requests to the iTwin API.

Troubleshooting

  • Missing or invalid Form ID: If the form ID does not correspond to an existing form definition in the project, the API will likely reject the request. Ensure the form ID is correct and that the form exists.
  • Authentication errors: Failure to provide valid OAuth2 credentials or expired tokens will cause authorization failures. Verify credential configuration and refresh tokens if needed.
  • Invalid JSON in complex fields: Fields like assignee, assignees, sourceEntity, boundingBox, etc., expect valid JSON objects. Malformed JSON input will cause errors. Use proper JSON formatting.
  • Unsupported operation error: If the node is misconfigured with an unsupported operation name, it will throw an error indicating the operation is unsupported.
  • API rate limits or network issues: Network connectivity problems or API throttling may cause request failures. Retry logic or error handling should be implemented as needed.

Links and References

Discussion