Retrieve Validation Model Data

Introduction

Model validation functions are used to check a model you’ve created to make sure everything is as expected. In the case of property validation, this means making sure element properties fit specific criteria. In the case of clash detection, this means certain elements are not touching or are within a certain range of each other.

Info

Skill level:

Basic

Duration:

20 minutes

1. (Optional) Create a sample iModel for testing

Follow the steps listed here

You will be redirected to the “My sample iModels” page. Wait a few minutes while the create process completes. Once it is, you can click “Show” in the IDs column to easily access the Context ID (also referred to as the project ID) and the iModel ID, both which will be frequently used throughout validation API calls. To get the changeset ID, you can either follow Step 4 in this tutorial, or, when viewing the model in the CONNECT iTwinViewer, copying the string after “ChangeSetId=” in the URL.

Note that in the following sections and related tutorials, the sample code will include actual results and data from this model outside of project/iModel/named version IDs, which will be specific to your project upon creation, and any ID values generated via API functions. While in most cases the results will be truncated for brevity, they should give you an idea of what you’re looking for so you can easily determine if something has gone awry.

2. Get a token

To make request to the API a user token is needed. There are several ways to get it.

Follow this article to implement Authorization code workflow in your application. You will need to include the scopes clashdetection:read and clashdetection:modify.

  1. Go here
  2. Click “Try it” button.
  3. On Authorization section select “AuthorizationCode”.
  4. After popup closes Authorization header with your user token value should be visible.
  5. Save user token value for this tutorial.
Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

2. Retrieving Models and Categories

For creating any Clash Detection test, you will need a list of the models or categories you wish to check for clashing elements.

To do this, we need to send an HTTP request to GET https://api.bentley.com/clashdetection/modelsAndCategories/imodels/{modelId}?projectId={projectId} using your projectId in place of {projectId}. This is an asynchronous request; if model information has never been previously requested for iModel, the data extraction will need time to process and the job will return a status of 202. You can repeat this request periodically until it returns a status of 200, at which point it will include the full response.

The response will include a complete list of models and categories, with their respective ids and display names. You will only need the ids for any validation functions, but to determine which models you are looking for, you will probably want to reference the display name, which should describe the model/categories and would be the same name you would see when looking at a model list or element when the iModel is open in any viewer.

Request Syntax


HTTP
POST https://api.bentley.com/clashdetection/modelsAndCategories/imodels/00000000-0000-0000-0000-000000000000?projectId=00000000-0000-0000-0000-000000000000 HTTP/1.1

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v1+json
Prefer: return=representation
Authorization: Bearer JWT_TOKEN

Response Body


JSON
{
  "models":[
    {
      "id":"0x21",
      "displayName":"ProcessPhysicalModel"
    }
  ],
  "categories":[
    {
      "id":"0x20000000002",
      "displayName":"Uncategorized"
    },
    {
      "id":"0x30000000048",
      "displayName":"PID LineStyle Default"
    },
    {
      "id":"0x3000000004a",
      "displayName":"Border"
    },
    {
      "id":"0x4000000000d",
      "displayName":"Tag-Category"
    },
    {
      "id":"0x40000000e71",
      "displayName":"Structure"
    }
  ]
}

3. Get Schema Info

For creating Property Validation tests you will need access to the property information for elements with which validate against. To do this you will need to retrieve the schema info via an HTTP request to GET https://api.bentley.com/clashdetection/schemas/imodels/{modelId}?projectId={projectId} using your projectId in place of {projectId}.

Similarly to the Get Models and Categories step, this is an asynchronous request and if schema extraction has never been done for this iModel before, it will need time to process and return a 202 status until extraction is complete. The user can repeat this request periodically until it returns a status of 200, which will include the full response.

The response will include a complete list of classes, labels of the classes if they’re available, and all of the associated properties with that class and their respective names and labels. For creating tests and rules, you will be using the name properties, usually in the format of {className}.{propertyName} although the labels may help you figure out which classes and properties you’re looking for.

Request Syntax


HTTP
POST https://api.bentley.com/clashdetection/modelsAndCategories/imodels/00000000-0000-0000-0000-000000000000?projectId=00000000-0000-0000-0000-000000000000 HTTP/1.1

Request Headers


HTTP
Accept: application/vnd.bentley.itwin-platform.v1+json
Prefer: return=representation
Authorization: Bearer JWT_TOKEN

Response Body


JSON
{
  "schema":[
    {
      "name":"ECDbMeta",
      "label":null,
      "entityClass":[
        {
          "name":"ECClassDef",
          "label":"ECClass",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"Description",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"ECSchemaDef",
          "label":"ECSchema",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"Description",
              "label":null
            },
            {
              "name":"Alias",
              "label":null
            },
            {
              "name":"VersionMajor",
              "label":null
            },
            {
              "name":"VersionWrite",
              "label":null
            },
            {
              "name":"VersionMinor",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"ECPropertyDef",
          "label":"ECProperty",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"Description",
              "label":null
            },
            {
              "name":"IsReadonly",
              "label":null
            },
            {
              "name":"Priority",
              "label":null
            },
            {
              "name":"Ordinal",
              "label":null
            },
            {
              "name":"ExtendedTypeName",
              "label":null
            },
            {
              "name":"ArrayMinOccurs",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"ECEnumerationDef",
          "label":"ECEnumeration",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"Description",
              "label":null
            },
            {
              "name":"IsStrict",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"KindOfQuantityDef",
          "label":"KindOfQuantity",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"PersistenceUnit",
              "label":null
            },
            {
              "name":"RelativeError",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"PropertyCategoryDef",
          "label":"PropertyCategory",
          "properties":[
            {
              "name":"Name",
              "label":null
            },
            {
              "name":"DisplayLabel",
              "label":null
            },
            {
              "name":"Description",
              "label":null
            },
            {
              "name":"Priority",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        },
        {
          "name":"ECRelationshipConstraintDef",
          "label":null,
          "properties":[
            {
              "name":"MultiplicityLowerLimit",
              "label":null
            },
            {
              "name":"MultiplicityUpperLimit",
              "label":null
            },
            {
              "name":"IsPolymorphic",
              "label":null
            },
            {
              "name":"RoleLabel",
              "label":null
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        }
      ]
    },
    {
      "name":"ProcessPhysical",
      "label":null,
      "entityClass":[
        {
          "name":"PIPING_COMPONENT",
          "label":"Piping Component",
          "properties":[
            {
              "name":"COMPONENT_NAME",
              "label":"Component Name"
            },
            {
              "name":"STATE",
              "label":"Component State"
            },
            {
              "name":"LENGTH_EFFECTIVE",
              "label":"Length Effective"
            },
            {
              "name":"DESIGN_LENGTH_CENTER_TO_BRANCH_END_EFFECTIVE",
              "label":"Design Length Center To Branch End Effective"
            },
            {
              "name":"DESIGN_LENGTH_CENTER_TO_OUTLET_END_EFFECTIVE",
              "label":"Design Length Center To Outlet End Effective"
            },
            {
              "name":"DESIGN_LENGTH_CENTER_TO_RUN_END_EFFECTIVE",
              "label":"Design Length Center To Run End Effective"
            },
            {
              "name":"WALL_THICKNESS",
              "label":"Wall Thickness"
            },
            {
              "name":"UPDATE_GRAPHICS",
              "label":"Update Graphics"
            },
            {
              "name":"NOMINAL_DIAMETER_RUN_END",
              "label":"Nominal Diameter Run End"
            },
            {
              "name":"Geometry",
              "label":"Element Geometry"
            },
            {
              "name":"SPOOL_ID",
              "label":"Spool Id"
            },
            {
              "name":"SPOOL_NUMBER",
              "label":"Spool Number"
            },
            {
              "name":"OPTION_CODE",
              "label":"Option Code"
            },
            {
              "name":"NOTES",
              "label":"Notes"
            },
            {
              "name":"CATALOG_NAME",
              "label":"Catalog Name"
            },
            {
              "name":"EC_CLASS_NAME",
              "label":"EC Class Name"
            },
            {
              "name":"UNIT_OF_MEASURE",
              "label":"Unit Of Measure"
            },
            {
              "name":"PIECE_MARK",
              "label":"Piece Mark"
            },
            {
              "name":"FABRICATION_CATEGORY",
              "label":"Fabrication Category"
            },
            {
              "name":"LINENUMBER",
              "label":"Line Number"
            },
            {
              "name":"INSULATION_THICKNESS",
              "label":"Insulation Thickness"
            },
            {
              "name":"INSULATION",
              "label":"Insulation Material"
            },
            {
              "name":"LENGTH",
              "label":"Length"
            },
            {
              "name":"INSIDE_DIAMETER",
              "label":"Inside Diameter"
            },
            {
              "name":"NORMAL_OPERATING_PRESSURE",
              "label":"Normal Operating Pressure"
            },
            {
              "name":"OUTSIDE_DIAMETER",
              "label":"Outside Diameter"
            },
            {
              "name":"PIPE_FLANGE_TYPE",
              "label":"Pipe Flange Type"
            },
            {
              "name":"GRADE",
              "label":"Grade"
            },
            {
              "name":"SHOP_FIELD",
              "label":"Shop Field"
            },
            {
              "name":"HUB_DEPTH",
              "label":"Hub Depth"
            },
            {
              "name":"HUB_WIDTH",
              "label":"Hub Width"
            },
            {
              "name":"TRACING",
              "label":"Tracing"
            }
          ],
          "aspects":[],
          "typeDefinitions":[]
        }
      ]
    }
  ]
}

4. Conclusion

You should be able to successfully retrieve the related IDs and schema info for your model. While this information is of limited value on its own, it is useful and necessary for creating clash detection and property validation tests, so check out the continue learning section to put your new knowledge to use.

More resources that you may like

Clash Test Basics

A tutorial that covers the basics of the clash detection lifecycle and usage

Validation API documentation

An overview and detailed version of Validation API documentation, including both Clash Detection and Property Validation