iTwin Issues icon

iTwin Issues

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

Actions27

Overview

This node operation allows importing a form definition from one iTwin (a digital twin platform instance) into another. It is useful when you want to reuse or share form definitions across different iTwins without recreating them manually. Common scenarios include migrating form templates between projects, synchronizing form definitions for consistency, or sharing standardized forms across multiple iTwins.

For example, if you have a form definition in a source iTwin that captures inspection data and want to use the same form in a new project iTwin, this operation imports that form definition directly, optionally copying it, updating an existing copy, or sharing it depending on your needs.

Properties

Name Meaning
Source Form Definition ID The unique identifier of the form definition to import, obtained by querying the source iTwin's form definitions.
Destination iTwin ID The identifier of the target iTwin where the form definition will be imported.
Import Action The type of import to perform:
- Copy: Creates a local copy of the form definition in the destination iTwin.
- Upsert: If the form definition already exists in the destination iTwin, updates it to match the source; otherwise behaves like Copy.
- Share: Allows the destination iTwin to use the form definition without copying, only valid if the form definition supports sharing.
Type (Only valid if Import Action is 'Copy' or unset) Changes the issue type category the imported form definition belongs to in the destination iTwin. This cannot be changed after import.
Status (Only valid if Import Action is 'Copy' or unset) Sets the initial status of the imported form definition. Options are Draft, Approved, Maintenance, Archived. Default is Draft.
Display Name (Only valid if Import Action is 'Copy' or unset) Allows setting a new display name for the imported form definition copy.
ID Prefix (Only valid if Import Action is 'Copy' or unset) Sets a new ID prefix for the imported form definition copy.
Options → Custom Payload Allows overriding the request body with a custom JSON payload instead of using the standard parameters. Useful for advanced use cases requiring direct control over the API request body.

Output

The node outputs the JSON response returned by the API after attempting the import operation. This typically includes details about the imported form definition such as its ID, status, and metadata confirming the success of the import.

If the import fails, the output may contain error information describing what went wrong.

No binary data output is produced by this node.

Dependencies

  • Requires an API authentication token credential configured in n8n to authorize requests against the iTwin Issues API.
  • The node interacts with Bentley's iTwin platform REST API endpoints.
  • Proper permissions on both source and destination iTwins are necessary to read form definitions and create or update them.

Troubleshooting

  • Common issues:

    • Invalid or missing Source Form Definition ID or Destination iTwin ID will cause the API call to fail.
    • Using the "Share" import action on a form definition that does not support sharing (shareType is null) will result in an error.
    • Attempting to change properties like type or status when using import actions other than "Copy" may be ignored or cause errors.
    • Network or authentication failures can prevent successful API calls.

  • Error messages:

    • "Unsupported operation" — indicates the node was called with an unsupported resource or operation.
    • API errors related to authorization or permissions should be resolved by verifying credentials and access rights.
    • Validation errors from the API will specify which input property is invalid or missing.

  • Resolution tips:

    • Double-check all required IDs and parameters before running the node.
    • Use the "Copy" import action if unsure about the state of the form definition in the destination iTwin.
    • Ensure the API credential has sufficient scopes/permissions.
    • Enable detailed logging in n8n to capture request and response details for debugging.

Links and References

Discussion