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 Named Versions associated with a specific iModel. Named Versions represent snapshots or milestones within an iModel, useful for tracking changes over time.

Common scenarios include:

  • Fetching all named versions of an iModel to display version history.
  • Filtering named versions by name or description to find specific milestones.
  • Paginating through large sets of named versions using continuation tokens.
  • Sorting named versions by creation date or changeset index to analyze progression.

Practical example:

  • A user wants to list all milestone versions named "Release 1" in an iModel to review changes made up to that point.

Properties

Name Meaning
ID The unique identifier of the iModel whose named versions are being retrieved. This is required.
Continuation Token A token used to fetch the next page of results in paginated responses. It must be sent exactly as received from the service. Using this disables the default skip-based pagination. To start using continuation tokens, provide an empty string initially. This property is mutually exclusive with the skip parameter.
Order By Specifies sorting order of the returned named versions. Supports ascending (asc) or descending (desc) order on changesetIndex and createdDateTime. If no direction is specified, ascending order is assumed. Example: changesetIndex desc,createdDateTime desc sorts by changeset index descending, then creation date descending.
Search Filters named versions whose name or description contains the given search string (case insensitive). Cannot be used simultaneously with the Name property. The search string must be non-empty and up to 255 characters. Example: searching for "Milestone 1" returns named versions containing that phrase in their name or description.
Name Filters named versions by exact name match (case insensitive). Must be a non-empty string not exceeding 255 characters and cannot be used together with the Search property. Example: specifying "Milestone 1" returns named versions named exactly "Milestone 1".

Output

The node outputs an array of JSON objects representing the named versions retrieved from the iModel. Each object typically includes properties such as:

  • Named Version ID
  • Name
  • Description
  • Changeset Index
  • Creation DateTime
  • Other metadata related to the named version

If multiple named versions are returned, each will be an individual item in the output array.

The node does not output binary data.

Dependencies

  • Requires an API authentication credential for the iTwin Platform (an OAuth2 token).
  • Uses the iTwin Platform iModels API endpoint to fetch named versions.
  • No additional external dependencies beyond the configured API credentials.

Troubleshooting

  • Missing or invalid iModel ID: Ensure the ID property is correctly set to a valid iModel identifier.
  • Pagination issues: When using continuation tokens, ensure the token is passed exactly as received. Mixing continuation tokens and skip parameters can cause errors.
  • Conflicting filters: Do not use Search and Name properties simultaneously; this will likely result in an error or no results.
  • API authentication errors: Verify that the API key or OAuth2 token is valid and has sufficient permissions.
  • Sorting syntax errors: Make sure the Order By string follows the correct format, e.g., changesetIndex desc.

Common error messages may include:

  • "Unknown operation" if the operation parameter is incorrect.
  • API errors indicating invalid query parameters or unauthorized access.

Resolving these usually involves verifying input parameters and API credentials.

Links and References

Discussion