iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

The "Update form data" operation in the iTwin Forms node allows users to update an existing form data instance by specifying its ID and modifying various attributes such as subject, description, due date, status, assignees, origin information, and custom properties. This operation is useful for workflows that need to programmatically manage and maintain form records within the iTwin platform, such as updating task statuses, adding workflow notes, reassigning responsibility, or adjusting metadata related to a form.

Practical examples include:

  • Automatically updating the status of a form after a review process.
  • Adding comments or workflow notes when changing the form's state.
  • Changing the assignee(s) based on project role changes.
  • Updating location or model-related metadata to reflect new context or corrections.

Properties

Name Meaning
ID The unique identifier of the form data instance to update. This is required to specify which form record will be modified.
Subject A brief title or description of the form.
Description A detailed description providing more context about the form.
Due Date The deadline by which action should be taken on this form. Applications use this to determine if the form is near due or overdue.
Status The new workflow status of the form, if applicable.
Workflow Note A comment associated with the status change. Must only be set if the 'status' property is also set and the workflow allows adding notes for the transition.
Assignee An object describing the primary user or role assigned to the form.
Assignees An array listing multiple users and/or roles assigned to the form, used when there are multiple assignees rather than just one primary assignee.
Source Entity An object representing a file in Storage related to the form.
Bounding Box Origin information describing a rectangular-prism-shaped region in a 3D model that the form pertains to.
Model Pin Origin information associating the form with a single point in a model that may not correspond to a model element.
Model View Origin information describing the view visible when the form was created.
Model Event Date Time The date and time represented in the model where the form pertains (useful for 4D models).
Location Origin information specifying the geographical location relevant to the form.
Properties A customizable object whose properties can vary depending on user customization within the project.
Options → Custom Payload Allows overriding the entire request body with a custom JSON payload instead of using the standard properties. Useful for advanced use cases requiring full control over the API request body.

Output

The node outputs the updated form data as a JSON object. The structure corresponds to the response from the iTwin Forms API after successfully updating the form. It typically includes all the updated fields of the form data instance.

If the update returns multiple items (unlikely in this context), each item is output as a separate JSON object in the output array.

No binary data output is indicated for this operation.

Dependencies

  • Requires an API authentication token 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 platform's API endpoints is necessary.

Troubleshooting

  • Common issues:

    • Missing or invalid form ID will cause the update to fail.
    • Providing a workflow note without setting a status or when the workflow does not allow notes for the status transition will likely result in an error.
    • Malformed JSON in properties like assignee, assignees, sourceEntity, etc., can cause parsing errors.
    • Using the custom payload option incorrectly (e.g., invalid JSON) can lead to request failures.

  • Error messages:

    • "Unknown operation": Indicates the specified operation name is not recognized; ensure "update-form-data" is selected.
    • API errors returned from the iTwin service will be passed through; check the message for details such as authorization issues, validation errors, or resource not found.

  • Resolutions:

    • Verify the form ID exists and is correct.
    • Ensure JSON inputs are valid and properly formatted.
    • Use the custom payload option only if you understand the API schema and want to override the default request body.
    • Confirm that the API credentials are correctly configured and have sufficient permissions.

Links and References

  • iTwin Developer Documentation
  • Refer to the iTwin Forms API documentation for detailed schema and workflow rules related to forms and their statuses.

Discussion