Get clash detection report - Clash Detection

Clash Detection

Download API definition:

Get clash detection report

GET https://dev-api.bentley.com/clash-detection/itwins/{itwinId}/reports/{id}[?cuid]

Retrieves the details of the clash detection report for the specified report id.

Discover clash report ids by calling GET /clash-detection/itwins/{itwinId}/reports

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 parameters

itwinId

Yes

The iTwin Id

Yes

Report id

cuid

Clash unique id for which the clash should be retrieved.

Request headers

Include-User-Metadata

Optional - Include user metadata when true.

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Response 200 OK

json

{
    "metadata": {
        "id": "ce75597b-3de6-454c-8592-fa17928f8aa1",
        "iTwinId": "384ebc14-d362-4a5a-8dce-0a5b3ebbe8ba",
        "repositoryId": "721e1260-6549-4216-a689-be80cc6648cf",
        "changesetId": "a8a3a9ad-862e-4ee9-8d88-c2bd220a8f57",
        "configurationId": "772c3f9d-4445-4c2d-9b4e-127827b4f8b2",
        "executed": "2023-06-17T14:45:47.66Z",
        "duration": 0,
        "numValidations": 102,
        "numElements": 31,
        "numRules": 7,
        "numIssues": 2,
        "status": 1,
        "userId": "76c4a684-fbdf-44e3-ae9b-dbdf9de1dbf2",
        "testSettings": {
            "resultsLimit": 10
        },
        "jobId": "e0e5ca59-4b5f-433d-a5ee-5a825e734782",
        "configurationName": "string",
        "changesetName": "version 1",
        "repositoryName": "Test iModel",
        "modifiedBy": "string",
        "modifiedAt": "2023-06-17T14:45:47.66Z",
        "userMetadata": {
            "createdBy": {
                "email": "Test.User@bentley.com",
                "name": "Test User"
            },
            "modifiedBy": {
                "email": "Test.User@bentley.com",
                "name": "Test User"
            }
        }
    },
    "report": {
        "calculateOverlap": true,
        "elementsWLoaderrors": 0,
        "numProcessed": 5,
        "numResults": 5,
        "processingTime": 200,
        "clashes": [{
            "cuid": "11099285-2960-46cb-999a-14f857def177",
            "elementAId": "0x20000000701",
            "elementALabel": "Pipe 6 1-SWS-0104",
            "elementBId": "0x200000011a7",
            "elementBLabel": "Pipe 6 1-SWS-0107",
            "clashType": "Collision",
            "clearance": -1,
            "elementAModelId": "0x20000000030",
            "elementBModelId": "0x20000000030",
            "elementACategoryId": "0x20000000047",
            "elementBCategoryId": "0x20000000047",
            "suppressingRules": [
                "9158efd6-2f18-455d-a032-91cfc636563b"
            ],
            "isMSupp": false,
            "status": 0,
            "boundingSphere": {
                "radius": 0,
                "center": {
                    "x": 0,
                    "y": 0,
                    "z": 0
                }
            },
            "id": 0
        }],
        "categoryList": [{
            "id": "0x20000000047",
            "label": "SWS-1-SWS-0104",
            "count": 1
        }],
        "modelList": [{
            "id": "0x20000000030",
            "label": "3D-PLANT",
            "count": 1
        }],
        "suppressionRules": [{
            "id": "9158efd6-2f18-455d-a032-91cfc636563b",
            "definition": "Test suppression rule.",
            "user": "76c4a684-fbdf-44e3-ae9b-dbdf9de1dbf2",
            "reason": "Test rule reason.",
            "parameters": {},
            "name": "Test rule"
        }]
    }
}

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 specified report/iTwin was not found.

json

{
    "error": {
        "code": "ResourceNotFound",
        "message": "Requested Resource is not available.",
        "details": [{
                "code": "iTwinNotFound",
                "message": "Requested iTwin is not available."
            },
            {
                "code": "ClashReportIdNotFound",
                "message": "Requested Clash Report Id is not available."
            }
        ]
    }
}

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax)

json

{
    "error": {
        "code": "InvalidClashDetectionReportRequest",
        "message": "Invalid clash detection report request."
    }
}

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

Clash Detection Result

metadata

Clash-result-metadata

Metadata of the the clash report.

report

clash-result

Clash detection report details.

json

{
    "title": "Clash Detection Result",
    "type": "object",
    "properties": {
        "metadata": {
            "description": "Metadata of the the clash report.",
            "$ref": "#/components/schemas/Clash-result-metadata"
        },
        "report": {
            "description": "Clash detection report details.",
            "$ref": "#/components/schemas/clash-result"
        }
    },
    "additionalProperties": false
}

clash-result

Details of the the clash report.

calculateOverlap

Boolean

Flag to calculate and report clash overlaps (minimum orthogonal overlap distance).

elementsWLoaderrors

Number

Number of element load errors.

numProcessed

Number

Number of elements processed.

numResults

Number

Number of results generated.

processingTime

Number

Processing time of the run.

clashes

clashes[]

Array of clashes.

categoryList

category-lookup-entry[]

Category lookup table. Contains an array of category id, category display name and count pairs.

modelList

model-lookup-entry[]

Model lookup table. Contains an array of model id, category display name and count pairs.

suppressionRules

suppression-rule-lookup-entry[]

Suppression rule lookup table.

json

{
    "type": "object",
    "description": "Details of the the clash report.",
    "properties": {
        "calculateOverlap": {
            "type": "boolean",
            "description": "Flag to calculate and report clash overlaps (minimum orthogonal overlap distance)."
        },
        "elementsWLoaderrors": {
            "type": "number",
            "description": "Number of element load errors."
        },
        "numProcessed": {
            "type": "number",
            "description": "Number of elements processed."
        },
        "numResults": {
            "type": "number",
            "description": "Number of results generated."
        },
        "processingTime": {
            "type": "number",
            "description": "Processing time of the run."
        },
        "clashes": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/clashes"
            },
            "description": "Array of clashes."
        },
        "categoryList": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/category-lookup-entry"
            },
            "description": "Category lookup table. Contains an array of category id, category display name and count pairs."
        },
        "modelList": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/model-lookup-entry"
            },
            "description": "Model lookup table. Contains an array of model id, category display name and count pairs."
        },
        "suppressionRules": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/suppression-rule-lookup-entry"
            },
            "description": "Suppression rule lookup table."
        }
    },
    "additionalProperties": false
}

Details of clashes

Details of clashes.

cuid

String

Unique id of the clash report.

elementAId

String

The unique id of element A.

elementBId

String

The unique id of element B.

elementALabel

String

The display label of element A.

elementBLabel

String

The display label of element B.

clashType

String

The type of clash detected - possible values: Collision, Clearance, Touching, Not Initialized.

clearance

Number

When the clash type is Clearance, the value is returned in meters. Otherwise -1 is returned.

elementAModelId

String

Id of Element A Model.

elementBModelId

String

Id of Element B Model.

elementACategoryId

String

Id of Element A Category.

elementBCategoryId

String

Id of Element B Category.

suppressingRules

String[]

Array of suppressing rules for the clash.

isMSupp

Boolean

Flag to check if clash is manually suppressed.

status

Number

The status of clash. Possible values - 0: New, 1: Open, 3: Resolved.

boundingSphere

clash-detection-bounding-sphere

Bounding sphere of the source element.

Number

Clash id.

json

{
    "title": "Details of clashes",
    "type": "object",
    "description": "Details of clashes.",
    "properties": {
        "cuid": {
            "type": "string",
            "description": "Unique id of the clash report."
        },
        "elementAId": {
            "type": "string",
            "description": "The unique id of element A."
        },
        "elementBId": {
            "type": "string",
            "description": "The unique id of element B."
        },
        "elementALabel": {
            "type": "string",
            "description": "The display label of element A."
        },
        "elementBLabel": {
            "type": "string",
            "description": "The display label of element B."
        },
        "clashType": {
            "type": "string",
            "description": "The type of clash detected - possible values: Collision, Clearance, Touching, Not Initialized."
        },
        "clearance": {
            "type": "number",
            "description": "When the clash type is Clearance, the value is returned in meters. Otherwise -1 is returned."
        },
        "elementAModelId": {
            "type": "string",
            "description": "Id of Element A Model."
        },
        "elementBModelId": {
            "type": "string",
            "description": "Id of Element B Model."
        },
        "elementACategoryId": {
            "type": "string",
            "description": "Id of Element A Category."
        },
        "elementBCategoryId": {
            "type": "string",
            "description": "Id of Element B Category."
        },
        "suppressingRules": {
            "type": "array",
            "description": "Array of suppressing rules for the clash.",
            "items": {
                "type": "string",
                "description": "Suppressing rule Id."
            }
        },
        "isMSupp": {
            "type": "boolean",
            "description": "Flag to check if clash is manually suppressed."
        },
        "status": {
            "type": "number",
            "description": "The status of clash. Possible values - 0: New, 1: Open, 3: Resolved."
        },
        "boundingSphere": {
            "$ref": "#/components/schemas/clash-detection-bounding-sphere",
            "description": "Bounding sphere of the source element."
        },
        "id": {
            "type": "number",
            "description": "Clash id."
        }
    },
    "additionalProperties": false
}

Bounding Sphere

Bounding sphere of the source element.

radius

Number

The clash radius.

center

clash-center

The clash center point.

json

{
    "title": "Bounding Sphere",
    "type": "object",
    "description": "Bounding sphere of the source element.",
    "properties": {
        "radius": {
            "type": "number",
            "description": "The clash radius."
        },
        "center": {
            "$ref": "#/components/schemas/clash-center",
            "description": "The clash center point."
        }
    },
    "additionalProperties": false
}

Clash Center

The clash center point. This contains x, y, and z properties for the exact spatial position of the center point.

Number

x-axis value for the center point.

Number

y-axis value for the center point.

Number

z-axis value for the center point.

json

{
    "title": "Clash Center",
    "type": "object",
    "description": "The clash center point. This contains x, y, and z properties for the exact spatial position of the center point.",
    "properties": {
        "x": {
            "type": "number",
            "description": "x-axis value for the center point."
        },
        "y": {
            "type": "number",
            "description": "y-axis value for the center point."
        },
        "z": {
            "type": "number",
            "description": "z-axis value for the center point."
        }
    },
    "additionalProperties": false
}

Clash-result-metadata

Metadata of the the clash report.

String

Unique id of the clash report.

iTwinId

String

The unique id of iTwin.

repositoryId

String

The unique id of iModel.

changesetId

String

The unique id of changeset.

configurationId

String

The unique id of configuration.

executed

Date-time

Execution date time of validation run.

duration

Number

Duration of the validation run.

numValidations

Number

Number of validations that occurred..

numElements

Number

Number of elements processed.

numRules

Number

Number of rules processed.

numIssues

Number

Number of issues generated.

status

Number

The status of the clash detection run. Started = 0, Completed = 1, Failed = 2.

userId

String

Unique id of user that started the run.

testSettings

clash-detection-test-settings

Settings to run the clash detection test.

jobId

String

Unique id for the job.

configurationName

String

The name of the configuration.

changesetName

String

The name of the changeset.

repositoryName

String

The name of the iModel.

modifiedBy

String

Unique id of user that modified the run.

modifiedAt

Date-time

Modification date time of validation run.

userMetadata

get-test-result-usermetadata

User Metadata - available if Include-User-Metadata flag is set to true.

json

{
    "type": "object",
    "description": "Metadata of the the clash report.",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique id of the clash report."
        },
        "iTwinId": {
            "type": "string",
            "description": "The unique id of iTwin."
        },
        "repositoryId": {
            "type": "string",
            "description": "The unique id of iModel."
        },
        "changesetId": {
            "type": "string",
            "description": "The unique id of changeset."
        },
        "configurationId": {
            "type": "string",
            "description": "The unique id of configuration."
        },
        "executed": {
            "type": "string",
            "format": "date-time",
            "description": "Execution date time of validation run."
        },
        "duration": {
            "type": "number",
            "description": "Duration of the validation run."
        },
        "numValidations": {
            "type": "number",
            "description": "Number of validations that occurred.."
        },
        "numElements": {
            "type": "number",
            "description": "Number of elements processed."
        },
        "numRules": {
            "type": "number",
            "description": "Number of rules processed."
        },
        "numIssues": {
            "type": "number",
            "description": "Number of issues generated."
        },
        "status": {
            "type": "number",
            "description": "The status of the clash detection run. Started = 0, Completed = 1, Failed = 2."
        },
        "userId": {
            "type": "string",
            "description": "Unique id of user that started the run."
        },
        "testSettings": {
            "$ref": "#/components/schemas/clash-detection-test-settings",
            "description": "Settings to run the clash detection test."
        },
        "jobId": {
            "type": "string",
            "description": "Unique id for the job."
        },
        "configurationName": {
            "type": "string",
            "description": "The name of the configuration."
        },
        "changesetName": {
            "type": "string",
            "description": "The name of the changeset."
        },
        "repositoryName": {
            "type": "string",
            "description": "The name of the iModel."
        },
        "modifiedBy": {
            "type": "string",
            "description": "Unique id of user that modified the run."
        },
        "modifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Modification date time of validation run."
        },
        "userMetadata": {
            "$ref": "#/components/schemas/get-test-result-usermetadata",
            "description": "User Metadata - available if Include-User-Metadata flag is set to true."
        }
    },
    "additionalProperties": false
}

User Details

User Details.

createdBy

result-usermetadata-createdby

User details.

modifiedBy

result-usermetadata-modifiedby

User details.

json

{
    "title": "User Details",
    "type": "object",
    "description": "User Details.",
    "properties": {
        "createdBy": {
            "$ref": "#/components/schemas/result-usermetadata-createdby",
            "description": "User details."
        },
        "modifiedBy": {
            "$ref": "#/components/schemas/result-usermetadata-modifiedby",
            "description": "User details."
        }
    },
    "additionalProperties": false
}

Created By User Details

Created By User Details.

name

String

Name of user that created the run.

String

Email id of user that created the run.

json

{
    "title": "Created By User Details",
    "type": "object",
    "description": "Created By User Details.",
    "properties": {
        "name": {
            "type": "string",
            "description": "Name of user that created the run."
        },
        "email": {
            "type": "string",
            "description": "Email id of user that created the run."
        }
    },
    "additionalProperties": false
}

Modified By User Details

Modified By User Details.

name

String

Name of user that modified the run.

String

Email of user that modified the run.

json

{
    "title": "Modified By User Details",
    "type": "object",
    "description": "Modified By User Details.",
    "properties": {
        "name": {
            "type": "string",
            "description": "Name of user that modified the run."
        },
        "email": {
            "type": "string",
            "description": "Email of user that modified the run."
        }
    },
    "additionalProperties": false
}

Category Lookup Entry

String

Unique identifier of the category.

label

String

Name of the category.

count

Number

Count of the category.

json

{
    "title": "Category Lookup Entry",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier of the category."
        },
        "label": {
            "type": "string",
            "description": "Name of the category."
        },
        "count": {
            "type": "number",
            "description": "Count of the category."
        }
    },
    "additionalProperties": false
}

Model Lookup Entry

String

Unique identifier of the model.

label

String

Name of the model.

count

Number

Count of the model.

json

{
    "title": "Model Lookup Entry",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier of the model."
        },
        "label": {
            "type": "string",
            "description": "Name of the model."
        },
        "count": {
            "type": "number",
            "description": "Count of the model."
        }
    },
    "additionalProperties": false
}

Suppression Rule Lookup Entry

String

Unique identifier of the suppression rule.

definition

String

Description of the suppression rule.

user

String

Unique id of user that created the suppression rule.

reason

String

Reason for the suppression rule.

parameters

One of: object string, null

Parameters will vary based on the chosen template. Some templates, like 'suppress clashes if clashing elements are in the same category, do not require any parameters.

name

String

Name of the suppression rule.

json

{
    "title": "Suppression Rule Lookup Entry",
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "Unique identifier of the suppression rule."
        },
        "definition": {
            "type": "string",
            "description": "Description of the suppression rule."
        },
        "user": {
            "type": "string",
            "description": "Unique id of user that created the suppression rule."
        },
        "reason": {
            "type": "string",
            "description": "Reason for the suppression rule."
        },
        "parameters": {
            "oneOf": [
                {
                    "type": "object"
                },
                {
                    "type": "string"
                }
            ],
            "nullable": true,
            "description": "Parameters will vary based on the chosen template. Some templates, like 'suppress clashes if clashing elements are in the same category, do not require any parameters."
        },
        "name": {
            "type": "string",
            "description": "Name of the suppression rule."
        }
    },
    "additionalProperties": false
}

Clash Detection Test Settings

resultsLimit

One of: number string

The maximum clash/failure limit for the clash detection test. Default is 100000.

json

{
    "title": "Clash Detection Test Settings",
    "type": "object",
    "properties": {
        "resultsLimit": {
            "oneOf": [
                {
                    "type": "number"
                },
                {
                    "type": "string"
                }
            ],
            "description": "The maximum clash/failure limit for the clash detection test. Default is 100000."
        }
    },
    "additionalProperties": false
}

DetailedError

Contains error information and an array of more specific errors.

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.

details

Error[]

Optional array of more specific errors.

json

{
    "type": "object",
    "description": "Contains error information and an array of more specific errors.",
    "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
        },
        "details": {
            "type": "array",
            "description": "Optional array of more specific errors.",
            "items": {
                "$ref": "#/components/schemas/Error"
            }
        }
    },
    "required": [
        "code",
        "message",
        "details"
    ],
    "additionalProperties": true
}

Detailed 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

DetailedError

Error Detailed information.

json

{
    "type": "object",
    "title": "Detailed 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 Detailed information.",
            "$ref": "#/components/schemas/DetailedError"
        }
    },
    "required": [
        "error"
    ],
    "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

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?