iTwin iModels icon

iTwin iModels

Interact with iTwin Platform iModels API for managing iModels, changesets, named versions, and more

Actions54

Overview

This node interacts with the iTwin Platform's iModels API to retrieve information about iModels associated with a specified iTwin. It is designed to fetch lists of iModels, supporting filtering, sorting, and pagination options. This node is useful in scenarios where users need to programmatically access metadata about iModels for project management, reporting, or integration with other systems.

Practical examples include:

  • Retrieving all iModels under a specific iTwin to display in a dashboard.
  • Filtering iModels by name or state to find those that are initialized or match a search term.
  • Paginating through large sets of iModels using continuation tokens.
  • Sorting iModels by creation date or name to organize results.

Properties

Name Meaning
iTwin ID The unique identifier of the iTwin whose iModels you want to retrieve. This is a required string input.
Continuation Token A token used to retrieve the next page of results in a paginated response. This token is generated by the service and must be sent exactly as received. It is mutually exclusive with the skip parameter. To start using continuation tokens, provide an empty value on the first request.
Order By Specifies the sorting order of the returned iModels collection. You can sort ascending (default) or descending by one or more properties. Supported properties are name and createdDateTime. Example: name desc,createdDateTime asc.
Search Filters iModels whose name or description contains the given search string. Cannot be used simultaneously with the Name property. The search string must be non-empty and no longer than 255 characters. Example: searching for "Sun City" returns iModels with that phrase in their name or description.
Name Filters iModels by exact name matching. The name must be a non-empty string, not just whitespace, and up to 255 characters. Cannot be used simultaneously with the Search property. Example: Sun City Renewable-energy Plant will return iModels with exactly that name.
State Filters iModels by their initialization state. Valid values are initialized or notInitialized. For example, selecting initialized returns only iModels that have been initialized.

Output

The node outputs an array of JSON objects representing iModels retrieved from the iTwin Platform. Each object corresponds to an iModel and includes its properties such as name, creation date, state, and other metadata as provided by the API.

If the API supports binary data related to iModels (e.g., files or attachments), the node would output this in a binary field; however, based on the provided code and properties, the output focuses on JSON metadata.

Example output structure (simplified):

[
  {
    "json": {
      "id": "string",
      "name": "string",
      "description": "string",
      "createdDateTime": "string",
      "state": "initialized" | "notInitialized",
      ...
    }
  },
  ...
]

Dependencies

  • Requires an API authentication credential configured in n8n to access the iTwin Platform API.
  • Depends on the iTwin Platform's iModels API endpoint.
  • Uses an internal interpreter module (IModelsOpenApiInterpreter) to map operations and execute API calls.

Troubleshooting

  • Common issues:

    • Missing or invalid iTwin ID will cause the API call to fail.
    • Using both Search and Name filters simultaneously will likely result in an error or unexpected behavior since they are mutually exclusive.
    • Pagination errors may occur if the continuation token is malformed or expired.
    • Incorrect Order By syntax could lead to API rejection of the query.

  • Error messages:

    • "Unknown operation: <operation>": Indicates the specified operation is not supported by the node. Verify the operation name.
    • API errors related to authentication usually mean the API key or OAuth2 credentials are missing or invalid.
    • Validation errors on input parameters typically indicate incorrect formatting or mutually exclusive parameters being used together.

To resolve these:

  • Ensure all required fields are correctly filled.
  • Use either Search or Name, not both.
  • Validate continuation tokens before use.
  • Check API credentials and permissions.

Links and References

Discussion