iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

This node interacts with the iTwin Forms API, specifically allowing users to update metadata of a form definition within the iTwin platform. It is useful for managing and modifying form definitions' properties such as display name, status, sharing permissions, and ID prefix without altering the form's layout or data instances.

Common scenarios include:

  • Changing the display name of an existing form definition to better reflect its purpose.
  • Updating the form's status to control whether it can be edited or filled out by users.
  • Configuring sharing options to allow the form to be used across multiple iTwins with different permission levels.
  • Setting or changing the ID prefix that appears on filled-out form instances for easier identification.

Practical example:

  • A project manager wants to mark a form definition as "Approved" so field workers can start filling it out but prevent further layout changes.
  • An administrator needs to share a form definition in read-only mode across several iTwin projects.

Properties

Name Meaning
ID The unique identifier of the form definition to update. This should be obtained from the "Get iTwin form definitions" endpoint or from a form data instance's formId property.
Display Name New display name for the form definition. Used to rename the form for clarity or updated context.
Status Sets the usability status of the form definition. Options:
- Draft: Editable layout, cannot fill instances.
- Maintenance: Editable layout, cannot fill instances.
- Approved: Fillable, layout locked.
- Archived: Neither editable nor fillable.
Share Type Controls sharing permissions between iTwins. 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 Optional prefix (up to 25 characters) prepended to auto-incrementing numbers for each filled-out form instance. If null, prefix is determined automatically based on form type.
Options Collection for advanced customization:
- Custom Payload: Allows overriding the request body with a user-defined JSON payload instead of using standard parameters.

Output

The node outputs JSON objects representing the response from the iTwin Forms API after updating the form definition metadata. The structure typically reflects the updated form definition resource, including fields like ID, display name, status, share type, and other metadata.

If the operation returns multiple items, each is output as a separate JSON object in the array.

No binary data output is involved.

Dependencies

  • Requires an API authentication credential configured in n8n to access the iTwin Forms API.
  • The node depends on the FormsOpenApiInterpreter class internally to map operations and execute API calls.
  • Network connectivity to the iTwin API endpoints is necessary.

Troubleshooting

  • Unknown operation error: If the specified operation is not recognized, ensure the operation name matches exactly "update-form-definition-metadata".
  • Invalid or missing ID: The form definition ID must be valid and previously retrieved; otherwise, the API will reject the update.
  • Permission errors: Insufficient API credentials or lack of permissions to modify the form definition may cause authorization failures.
  • Immutable shareType: Once a form definition is shared, attempting to change the shareType again will fail. Plan sharing settings carefully.
  • Malformed custom payload: If using the custom JSON payload option, ensure the JSON is valid and conforms to the API schema to avoid request errors.

Links and References

  • iTwin Developer Documentation
  • Refer to the "Get iTwin form definitions" endpoint documentation to retrieve valid form IDs before updating.
  • Review API guidelines on form statuses and sharing rules for correct usage.

Discussion