iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

This node integrates with the iTwin Forms API to create new form data entries associated with a specific form definition within a project. It is designed for scenarios where users need to programmatically submit or generate forms that are linked to predefined form templates managed in Bentley's ecosystem. Typical use cases include automating form creation workflows, populating forms with metadata and origin information, and assigning responsibility for follow-up actions.

For example, a construction project manager could use this node to automatically create inspection forms tied to specific model elements or locations, assign them to team members, and set due dates for completion.

Properties

Name Meaning
Form ID The ID of the form definition to associate this form with. This links the created form data to a predefined template used in Bentley's Forms webapp and other applications.
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 an action should be taken on this form. Used by applications to track near-due or overdue forms.
Status The workflow status of the form, if applicable (e.g., open, closed).
Assignee An object describing the primary user or role assigned to the form.
Assignees A list of multiple users and/or roles assigned to the form, for cases where responsibility is shared.
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, not necessarily corresponding 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 relevant to the form, useful for 4D models.
Location Geographical location information that the form pertains to.
Properties A customizable object whose properties vary depending on user customization within the project.
Options > Custom Payload Allows overriding the entire request body with a custom JSON payload, enabling advanced users to send arbitrary data structures directly to the API.

Output

The node outputs the response from the iTwin Forms API after creating the form data. The output is structured as JSON objects representing the newly created form data record(s). If multiple records are returned, each is output as a separate item.

No binary data output is indicated.

Dependencies

  • Requires an OAuth2 API credential for authentication with the iTwin platform.
  • Depends on the iTwin Forms API endpoint.
  • The node uses an internal OpenAPI interpreter class to map operations and execute requests.
  • Proper configuration of the project environment and access rights to form definitions is necessary.

Troubleshooting

  • Common issues:

    • Providing an invalid or non-existent Form ID will cause the operation to fail because the form data must be linked to an existing form definition.
    • Malformed JSON input for properties like assignee, assignees, sourceEntity, etc., can cause parsing errors.
    • Missing required parameters such as formId will result in validation errors.
    • Insufficient permissions or expired OAuth tokens may lead to authentication failures.

  • Error messages:

    • "Unknown operation: <operation>": Indicates the specified operation is not supported; ensure "create-form-data" is selected.
    • API errors returned from the iTwin Forms service will be passed through; check the error message for details such as invalid IDs or permission issues.
    • JSON parsing errors for fields expecting JSON input; verify the JSON syntax is correct.

  • Resolutions:

    • Verify all required fields are provided and correctly formatted.
    • Ensure the OAuth2 credentials are valid and have appropriate scopes.
    • Use the "Custom Payload" option only if you understand the API schema to avoid malformed requests.

Links and References

  • iTwin Developer Documentation
  • Bentley Form Designer (for creating/importing form definitions)
  • iTwin Forms API Reference (accessible via the documentation URL above)

Discussion