iTwin Issues icon

iTwin Issues

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

Actions27

Overview

This node operation allows importing a template into a specified iTwin environment by creating a copy of an existing template. It is useful when you want to replicate or migrate form definitions (templates) from one iTwin context to another, possibly with modifications such as changing the display name, ID prefix, issue type, or status.

Typical use cases include:

  • Automating the deployment of standardized templates across multiple iTwins.
  • Importing approved or draft templates for further customization or immediate use.
  • Managing lifecycle states of templates by setting their initial status upon import.

For example, you might import a "Safety Inspection" template into a new project iTwin, setting its status to "Draft" and assigning it a new display name and ID prefix to distinguish it from other templates.

Properties

Name Meaning
Template Name The name of the template to import, as retrieved from the Get templates endpoint. Since templates do not have IDs, this name uniquely identifies the template to import.
Destination iTwin ID The identifier of the target iTwin where the template copy will be imported.
Type Sets the issue type category that the imported template will belong to. This property is immutable after import.
Status Defines the initial status of the imported template copy. Options are: Draft, Approved, Maintenance, Archived. Default is 'Approved'.
Display Name Optionally sets a new display name for the imported form definition within the destination iTwin.
ID Prefix Optionally sets a new ID prefix for the imported form definition in the destination iTwin.
Options → Custom Payload Allows overriding the entire request body with a custom JSON payload. This is useful for advanced users who want to send a fully customized import request beyond the standard parameters.

Output

The node outputs an array of JSON objects representing the response from the API after attempting to import the template. The exact structure depends on the API's response but typically includes details about the newly created form definition, such as its ID, name, status, and other metadata.

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

No binary data is produced by this node.

Dependencies

  • Requires an API key credential for authentication with the iTwin platform.
  • The node uses the iTwin Issues API endpoint to perform the import operation.
  • Proper configuration of the OAuth2 credentials or API keys in n8n is necessary to authorize requests.
  • Network access to the Bentley iTwin API endpoints is required.

Troubleshooting

  • Common issues:

    • Incorrect or missing Template Name: Since templates are identified by name, providing an incorrect name will cause the import to fail.
    • Invalid Destination iTwin ID: If the target iTwin ID does not exist or the user lacks permissions, the import will not succeed.
    • Improperly formatted custom JSON payload: When using the custom payload option, invalid JSON or missing required fields can cause errors.
    • Insufficient permissions or expired API tokens can lead to authorization failures.

  • Error messages:

    • "Unsupported operation": Indicates that the selected operation is not implemented or recognized by the node.
    • API errors related to 4xx or 5xx HTTP status codes usually indicate client or server issues respectively; check the message for specifics.
    • JSON parsing errors when using custom payloads suggest malformed JSON input.

  • Resolutions:

    • Verify template names via the Get templates endpoint before importing.
    • Confirm the destination iTwin ID is correct and accessible.
    • Validate JSON syntax if using the custom payload option.
    • Refresh or reconfigure API credentials if authorization errors occur.

Links and References

Discussion