iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

This node enables 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 forms between projects, synchronizing form templates, or sharing standardized forms within an organization.

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 node allows you to import that form definition directly by specifying its ID and the destination iTwin ID.

Properties

Name Meaning
Source Form Definition ID The unique identifier of the form definition to import, obtained from 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 operation 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; otherwise, behaves like Copy.
- Share: Shares the form definition without copying, only valid if the form supports sharing. Default is Copy.
Type (Only valid for Copy or unset import action) Allows changing the form type of the imported copy. This property cannot be changed after import.
Status (Only valid for Copy or unset import action) Sets the initial status of the imported form definition. Options are Draft, Approved, Maintenance, Archived. Default is Draft.
Display Name (Only valid for Copy or unset import action) Sets a new display name for the imported form definition.
ID Prefix (Only valid for Copy or unset import action) Sets a new ID prefix for the imported form definition.
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 JSON data representing the result of the import operation. This typically includes details about the imported form definition such as its ID, status, and other metadata returned by the iTwin Forms API. The output structure depends on the API response but generally provides confirmation and information about the newly imported or updated form definition.

No binary data output is produced by this node.

Dependencies

  • Requires an API authentication token credential configured in n8n to access the iTwin Forms API.
  • Depends on the iTwin Forms REST API being accessible and the user having appropriate permissions to read from the source iTwin and write to the destination iTwin.
  • The node uses an internal OpenAPI interpreter module to execute the API calls.

Troubleshooting

  • Common issues:

    • Invalid or missing form definition ID or iTwin IDs can cause errors.
    • Using the "Share" import action on a form definition that does not support sharing will fail.
    • Insufficient permissions on either the source or destination iTwin may result in authorization errors.
    • Providing invalid JSON in the custom payload option can cause request failures.

  • Error messages:

    • "Unknown operation": Indicates the specified operation is not recognized by the node; ensure the operation name is correct.
    • API errors related to authorization or resource not found usually indicate incorrect IDs or insufficient permissions.
    • JSON parsing errors when using custom payloads suggest malformed JSON input.

To resolve these, verify all IDs, check permissions, and validate any custom JSON payloads before execution.

Links and References

Discussion