iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

This node integrates with the iTwin Forms API to add an attachment to a specific form data instance. It is useful when you want to programmatically upload files (such as images, documents, or other media) as attachments to existing form entries within the iTwin platform. Typical use cases include automating document management workflows, enriching form submissions with supplementary files, or linking visual evidence to form responses.

For example, after collecting form data from a user, you might use this node to attach a photo or PDF report directly to that form entry for further processing or archival.

Properties

Name Meaning
ID The unique identifier of the form data instance to which the attachment will be added.
File Name The filename of the attachment. This determines the MIME type of the file when accessed later.
Caption A descriptive string explaining the significance or context of the attachment.
Binding Associates the attachment with an Image Drop control if the attachment originates from such a control.
Options Additional options including:
  Custom Payload Allows overriding the request body with a custom JSON payload instead of the standard format.

Output

The node outputs JSON objects representing the response from the iTwin Forms API after adding the attachment. The structure typically contains details about the newly created attachment, such as its ID, URL, metadata, or status confirmation.

If multiple items are returned by the API, each is output as a separate JSON object in the array.

Binary data is not output by this node; it only handles metadata and references related to the attachment.

Dependencies

  • Requires an API authentication token credential configured in n8n to access the iTwin Forms API.
  • Depends on the FormsOpenApiInterpreter class internally to map and execute API operations.
  • The node expects the iTwin OAuth2 API credentials to be set up properly in n8n for authorization.

Troubleshooting

  • Common issues:

    • Invalid or missing form data ID can cause the operation to fail.
    • Incorrect file name or unsupported file types may lead to MIME type errors.
    • Missing or invalid API credentials will result in authentication failures.
    • If using the Custom Payload option, malformed JSON will cause parsing errors.

  • Error messages:

    • "Unknown operation": Indicates the specified operation is not recognized; ensure "add-attachment-to-form" is selected.
    • API errors related to permissions or resource not found usually indicate incorrect IDs or insufficient access rights.
    • JSON parsing errors when using custom payloads require validating the JSON syntax before submission.

Links and References

Discussion