Get Comparison Job - Changed Elements

Changed Elements

Download API definition:

This API is a Technical Preview and is available for testing purposes only. Do not use in production.

GET https://api.bentley.com/changedelements/comparisonjob/{jobId}/itwin/{iTwinId}/imodel/{iModelId}

Gets comparison based on the job Id, iTwin Id, and iModel Id. The comparison will contain the job status, start and end changeset ids, and comparison progress. If the comparison is complete, the response will also include an href to the comparison information.

Job Id: is normally comprised of start changeset id and end changeset id, in the following format: {startChangesetId}-{endChangesetId}

Understanding Change

The comparison job blob, which can be downloaded using the provided link, includes a ChangedElements object. This object comprises several arrays of identical size. Each element across these arrays is identified by a unique index. map

Here are some key arrays that provide insights into the modifications made to an element:

opcodes: This array stores operation codes that indicate whether an element was inserted, updated, or deleted during the change. For more details, refer to DbOpcode. The relevant values are outlined below:

Element was deleted

Element was modified

Element was inserted

type: Contains the type of change that occurred to the element. This number is a bit-flag and can be used to know whether the element had property changes, geometric changes, placement changes, indirect changes, and hidden property changes. See TypeOfChange for more information. Below is a table with the values and their meaning:

Property

A property in the element changed

Geometry

The geometry of the element changed

Placement

The placement of the element changed. This means that the element changed its volume, origin or rotation.

Indirect

Indirect change occurred to this element by a related instance that provides properties for it

Hidden

Hidden properties of the element changed

Parent

The top-most parent of the element has changed

Prefer Header

You may set the Prefer header as return=minimal if you want to skip all data related to element properties.

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request

Request parameters

jobId

Yes

Comprised of start changeset Id and end changeset Id in the following format {startChangesetId}-{endChangesetId}.

iTwinId

Yes

Id of the iTwin where the iModel resides.

iModelId

Yes

Id of the iModel to query for status of changesets.

Request headers

Prefer

Determines whether to provide the comparison job with all data (return=representation) or the comparison job data without property values (return=minimal). If not provided, behavior defaults to return=representation

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v2+json is recommended.

Response

Response 200 OK

json

{
    "comparisonJob": {
        "comparison": {
            "href": "https://api.bentley.com/path1/path2/id"
        },
        "status": "Completed",
        "jobId": "16063aa71dfbcee75d32a7c5a31ca40e9bb2b094-8968f5c4449d26c0dababf37aed17dcc49d7059f",
        "iTwinId": "1036c64d-7fbe-47fd-b03c-4ed7ad7fc829",
        "iModelId": "0db82dc1-e871-4209-b40a-6753c6a68c19",
        "startChangesetId": "16063aa71dfbcee75d32a7c5a31ca40e9bb2b094",
        "endChangesetId": "8968f5c4449d26c0dababf37aed17dcc49d7059f",
        "currentProgress": 10,
        "maxProgress": 10
    }
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 404 Not Found

This response indicates that the provided iTwin, iModel, or jobId could not be found.

json

{
    "error": {
        "code": "ComparisonNotFound",
        "message": "Requested comparison is not available."
    }
}

Response 422 Unprocessable Entity

This response indicates that an URL parameter was malformed or there are missing required URL parameters.

json

{
    "error": {
        "code": "InvalidChangedElementsRequest",
        "message": "Could retrieve comparison.",
        "details": [{
                "code": "MissingRequiredParameter",
                "message": "Query parameter must be provided.",
                "target": "iModelId"
            },
            {
                "code": "MissingRequiredParameter",
                "message": "Query parameter must be provided.",
                "target": "iTwinId"
            },
            {
                "code": "MissingRequiredParameter",
                "message": "Query parameter must be provided.",
                "target": "jobId"
            }
        ]
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

Get Comparison Response

A response containing information regarding the comparison.

comparisonJob

Comparison

Details for the comparison.

json

{
    "type": "object",
    "title": "Get Comparison Response",
    "description": "A response containing information regarding the comparison.",
    "properties": {
        "comparisonJob": {
            "$ref": "#/components/schemas/Comparison",
            "description": "Details for the comparison."
        }
    },
    "additionalProperties": false
}

Href

A link to a resource.

href

String

Http reference.

json

{
    "type": "object",
    "description": "A link to a resource.",
    "properties": {
        "href": {
            "type": "string",
            "description": "Http reference.",
            "example": "https://api.bentley.com/path1/path2/id"
        }
    },
    "additionalProperties": false
}

Comparison

Information related to the comparison.

comparison

Href, null

A link to a comparison.

status

String

A string reflecting the status of the comparison. The statuses are: Queued, Started, Completed, or Failed.

jobId

String

Comprised of start changeset Id and end changeset Id in the following format {startChangesetId}-{endChangesetId}.

iTwinId

String

Id of the iTwin where the iModel resides.

iModelId

String

Id of the iModel to query for status of changesets.

startChangesetId

String

Id of the changeset to start from. This changeset must occur before end changeset.

endChangesetId

String

Id of the changeset to end at. This changeset must occur after start changeset.

currentProgress

Number

Comparison processing progress. Approaches the value of 'maxProgress'.

maxProgress

Number

The maximum value that 'currentProgress' will reach.

json

{
    "type": "object",
    "description": "Information related to the comparison.",
    "properties": {
        "comparison": {
            "$ref": "#/components/schemas/Href",
            "description": "A link to a comparison.",
            "nullable": true
        },
        "status": {
            "type": "string",
            "description": "A string reflecting the status of the comparison. The statuses are: Queued, Started, Completed, or Failed."
        },
        "jobId": {
            "type": "string",
            "description": "Comprised of start changeset Id and end changeset Id in the following format {startChangesetId}-{endChangesetId}."
        },
        "iTwinId": {
            "type": "string",
            "description": "Id of the iTwin where the iModel resides."
        },
        "iModelId": {
            "type": "string",
            "description": "Id of the iModel to query for status of changesets."
        },
        "startChangesetId": {
            "type": "string",
            "description": "Id of the changeset to start from. This changeset must occur before end changeset."
        },
        "endChangesetId": {
            "type": "string",
            "description": "Id of the changeset to end at. This changeset must occur after start changeset."
        },
        "currentProgress": {
            "type": "number",
            "description": "Comparison processing progress. Approaches the value of 'maxProgress'."
        },
        "maxProgress": {
            "type": "number",
            "description": "The maximum value that 'currentProgress' will reach."
        }
    },
    "additionalProperties": false
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?