iTwin Issues icon

iTwin Issues

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

Actions27

Overview

This node operation updates the metadata of an existing form definition within the iTwin Issues system. It allows users to modify key attributes such as the display name, status, sharing permissions, and ID prefix of a form definition identified by its unique ID. This is useful for managing form definitions' lifecycle and accessibility without altering their layout or content directly.

Practical scenarios include:

  • Changing a form's status from "Draft" to "Approved" to allow issue filling.
  • Updating the display name to reflect new naming conventions.
  • Setting sharing permissions to enable cross-iTwin usage with controlled edit rights.
  • Adjusting the ID prefix that appears in auto-generated issue numbers.

Properties

Name Meaning
ID The unique identifier of the form definition to update. Must be obtained from the "Get iTwin form definitions" endpoint or from a form data instance's formId property.
Display Name A new display name for the form definition.
Status Sets the usability status of the form definition. Options:
- Draft: Editable layout, cannot fill issues.
- Maintenance: Editable layout, cannot fill issues.
- Approved: Can fill issues, layout locked.
- Archived: Neither editable nor fillable.
Share Type Controls whether the form definition can be shared between iTwins and how it can be edited. Options:
- Null (no sharing)
- Read Only: Shared, layout editable only in original iTwin.
- Read Write: Shared, layout editable anywhere. Once set, cannot be changed.
ID Prefix A string prefix (up to 25 characters) prepended to the auto-incrementing issue number generated from this form definition. If null, the prefix is determined automatically by the issue type.
Options Collection for advanced options including:
- Custom Payload: Allows overriding the request body with a custom JSON payload instead of using standard parameters.

Output

The node outputs an array of JSON objects representing the updated form definition metadata as returned by the API. Each object contains the updated properties reflecting the changes made.

If the "Custom Payload" option is used, the output corresponds to the API response for the custom JSON sent.

No binary data output is involved in this operation.

Dependencies

  • Requires an API authentication token credential configured in n8n to authorize requests against the iTwin Issues API.
  • The node sends HTTP PATCH requests to the iTwin Issues REST API endpoint responsible for updating form definitions.
  • No additional external services are required beyond the iTwin platform API.

Troubleshooting

  • Common issues:

    • Providing an invalid or non-existent form definition ID will result in an error indicating the resource was not found.
    • Attempting to change the share type after it has been set once will fail because the API does not allow unsharing or changing share type post-sharing.
    • Sending malformed JSON in the custom payload option may cause request failures.
    • Omitting required fields like the form definition ID will cause validation errors.

  • Error messages and resolutions:

    • "Form definition not found": Verify the ID is correct and exists in the target iTwin.
    • "Share type cannot be changed": Ensure you do not attempt to modify the share type after initial setting.
    • "Invalid JSON payload": Check the syntax of the custom JSON payload if using the override option.
    • "Unauthorized" or "Authentication failed": Confirm that the API authentication token is valid and properly configured in n8n credentials.

Links and References

Discussion