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, specifically to update locks on iModels. It is useful in scenarios where multiple users or processes need to coordinate access to parts of an iModel by locking objects to prevent conflicting changes. For example, when a user wants to ensure exclusive editing rights on certain elements within an iModel before making modifications, this node can update the lock status accordingly.

Practical examples include:

  • Updating locks after a user checks out or modifies parts of an iModel.
  • Synchronizing lock states across different clients or services working on the same iModel.
  • Ensuring that changesets are consistent by verifying and updating locks based on the latest changeset ID.

Properties

Name Meaning
ID The unique identifier of the iModel (iModelId) for which locks are being updated.
Briefcase ID Numeric identifier of the briefcase associated with the locks update. This identifies the client or session holding the locks.
Changeset ID Identifier of the latest changeset in which the locked object was updated. Used to ensure that locks are only acquired if the changeset is current or newer than the server's record, preventing conflicts from outdated locks.
Locked Objects A JSON array representing the objects to be locked. Each entry corresponds to an object within the iModel that should have its lock state updated.
Options Additional options for the request:
- Custom Payload: Allows overriding the entire request body with a custom JSON payload instead of using the standard parameters.

Output

The node outputs JSON data representing the response from the iModels API after attempting to update the locks. The structure typically includes information about the success or failure of the lock update operation and may contain details about the locked objects or error messages.

If the node supports binary data output, it would represent related binary content such as files or attachments, but in this case, the output is purely JSON-based reflecting API responses.

Dependencies

  • Requires an API key credential for authenticating with the iTwin Platform iModels API.
  • Needs proper configuration of OAuth2 credentials or equivalent authentication method to access the iModels service.
  • The node depends on the bundled IModelsOpenApiInterpreter module to interpret and execute API operations.

Troubleshooting

  • Common Issues:

    • Providing an outdated Changeset ID will cause the lock acquisition to fail because the server expects the latest changeset reference.
    • Incorrect or missing Briefcase ID may result in errors or unexpected behavior since locks are scoped per briefcase.
    • Malformed JSON in the Locked Objects property can cause parsing errors.
    • Using the "Custom Payload" option incorrectly might lead to invalid API requests.

  • Error Messages:

    • "Unknown operation": Indicates the specified operation name does not match any supported operation; verify the operation parameter.
    • Lock acquisition failures due to stale changeset references usually return errors indicating the changeset is older than expected.
    • Authentication errors if the API key or OAuth token is invalid or expired.

To resolve these issues:

  • Ensure the Changeset ID is up-to-date.
  • Validate JSON input for locked objects.
  • Confirm that authentication credentials are correctly configured and valid.
  • Use the "Custom Payload" option only if you fully control the request format.

Links and References

Discussion