iTwin Forms icon

iTwin Forms

Comprehensive iTwin Forms API

Actions28

Overview

This node enables importing a form template into an iTwin platform instance. It allows users to create a copy of an existing form template by specifying the template name and the destination iTwin ID where the form should be imported. This is useful for scenarios such as migrating or replicating form templates across different iTwin projects or environments, customizing imported forms with new display names, statuses, or ID prefixes.

Practical examples:

  • Importing a standard inspection form template into a new iTwin project.
  • Duplicating a form template with a different status (e.g., from Draft to Approved) for testing purposes.
  • Setting a custom display name and ID prefix to distinguish imported forms in the target iTwin.

Properties

Name Meaning
Template Name The name of the template to import, identified by its name as retrieved from the Get templates endpoint.
Destination iTwin ID The unique identifier of the iTwin instance where the template copy will be imported.
Type The form type classification for the imported template. This cannot be changed after import.
Status The initial status of the imported form copy. Options: Draft, Approved, Maintenance, Archived. Default is 'Approved'.
Display Name Optional new display name for the imported form definition within the destination iTwin.
ID Prefix Optional new ID prefix to assign to the imported form definition in the destination iTwin.
Options → Custom Payload Allows overriding the entire request body with a custom JSON payload instead of using the predefined properties.

Output

The node outputs JSON data representing the result of the import operation. Typically, this includes details about the newly imported form template such as its identifiers, status, and metadata returned by the API.

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

No binary data output is indicated.

Dependencies

  • Requires an API authentication credential (OAuth2 token) configured for accessing the iTwin Forms API.
  • Depends on the iTwin Forms OpenAPI interpreter module internally to execute the import operation.
  • Network access to the iTwin Forms API endpoint is necessary.

Troubleshooting

  • Common issues:

    • Providing a template name that does not exist or is misspelled will cause the import to fail.
    • Incorrect or missing destination iTwin ID will prevent the form from being imported.
    • Using an invalid form type or status value may result in API errors.
    • If the user lacks sufficient permissions on the destination iTwin, the import will be rejected.

  • Error messages:

    • "Unknown operation": Indicates the specified operation name is not recognized; ensure "import-template" is selected.
    • API errors related to authorization or resource not found typically indicate credential or parameter issues.
    • JSON parsing errors if a custom payload is provided but malformed.

  • Resolutions:

    • Double-check template names via the Get templates endpoint before importing.
    • Verify destination iTwin ID correctness.
    • Use valid options for form type and status.
    • Ensure the API credential has proper scopes and permissions.
    • Validate any custom JSON payloads for correct syntax.

Links and References

  • iTwin Developer Documentation
  • Refer to the Get templates endpoint documentation to retrieve available template names.
  • Review iTwin Forms API guides for form types and statuses definitions.

Discussion