Create Multi-Property Validation Rule
Introduction
Multi-property validation rules allow you to apply the same validation function to all elements with a property name containing a specified filter string. In this tutorial, you will learn how to:
- Get a list of all property validation rule templates.
- Get a list of all properties in an iModel that contain the specified filter string.
- Create a multi-property validation rule.
Info
Skill level:
Basic
Duration:
20 minutes
Prerequisites
This tutorial assumes that you have:
- Access to an iModel and the associated projectId and imodelId for that iModel, along with the named version ID for the version you are testing against
1. Request an authorization token using one of the methods below.
Implement the Authorization Code Flow in the application
Use the OAuth2 Authorization article to implement an Authorization code workflow in your application. Include the scopes “validation:read” and 'validation:modify’.
Retrieve a user token using the API Reference “Try it out” button.
- Open Get property value validation rule templates
- Click the Try it out button.
- In the Authorization section, select AuthorizationCode.
- Copy the Authorization token in the Header section for use in this tutorial. It will replace the JWT_TOKEN dynamic parameter in the following steps.
2. Get Property Validation Rule Templates
A property validation rule is used as a basis for verifying the value of a property. A rule can check if the value of a property is defined, within a range of values, matches a pattern, etc.
We have provided a variety of property validation rule templates to get you started. An HTTP GET https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId[&continuationToken][&$top] request returns all valid property validation rule templates for the given project ID. Choose the template that is best suited for your goals based on the description.
For this tutorial we are using the MultiPropertyValidation rule template shown on the right in the response body.
Request Syntax
GET https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId=00000000-0000-0000-0000-000000000000 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Response Headers
Content-Type: application/json
Response Body
{ "ruleTemplates": [{ "id": "1cKcvg7Ky0e66uT-2u8vpW9vzfUgkKBIp6XGd_WdXPM", "displayName": "MultiPropertyValidation", "description": "Runs a given template on multiple properties in iModel Schema", "prompt": "Runs a given template on multiple properties in iModel Schema", "templateExpression": { "templateId": "a5896553-e248-4619-b7c8-5bcb4878e51c", "functionParameters": { "propertyName": "LastMod" }, "schemas": [{ "name": "Architecture_rvt_ThreeD_3D", "label": null, "entities": [{ "name": "Cameras", "label": null, "properties": [{ "name": "Eye__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Eye Elevation" }, { "name": "Far__x0020__Clip__x0020__Offset_PG_VIEW_EXTENTS_Length", "label": "Far Clip Offset" }, { "name": "Target__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Target Elevation" }] }] }] } }], "_links": { "next": null } } }
3. Get Filtered Validation Properties
Before creating a multi-property validation rule, a filtered list of properties may be retrieved for the desired iModel. The hierarchical response contains a list of all schemas in the iModel. Within each schema is a list of all entities and within those are lists of properties.
Provide the iModel ID, project ID and filter string in the request.
Review the schemas array in the response and then pass it into the request body in Step 4.
Request Syntax
GET https://api.bentley.com/validation/propertyValue/properties/imodels/00000000-0000-0000-0000-000000000000?projectId=00000000-0000-0000-0000-000000000000&filter=LENGTH HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Response Headers
Content-Type: application/json
Response Body
{ "data": { "searchProperty": { "schemas": [ { "name": "Architecture_rvt_ThreeD_3D", "label": null, "entities": [ { "name": "Cameras", "label": null, "properties": [ { "name": "Eye__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Eye Elevation" }, { "name": "Far__x0020__Clip__x0020__Offset_PG_VIEW_EXTENTS_Length", "label": "Far Clip Offset" }, { "name": "Target__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Target Elevation" } ] } ] } ] } } }
4. Creating a Multi-Property Validation Rule
To create a multi-property validation rule, provide a rule name, description, template ID, severity, data type and, optionally, a whereClause.
In the functionParameters object, set the nested template ID, parameters and schemas as described below. They will be used during processing to apply the rule for each of the properties listed.
- templateId: The template ID of the MultiPropertyValidation rule template.
- ecSchema: Should be set to '*' since it will be set based on the schemas parameter below.
- ecClass: Should be set to '*' since it will be set based on the schemas parameter below.
- whereClause: (Optional) The syntax is: [propertyName][comparison operator] [value], ie USER_LABEL = 'Door’, for multiple properties connectors such as AND/OR can be used as well.
- severity: The rule severity can be one of four values: 'veryHigh’, 'high’, 'medium’, 'low’.
- dataType: Should be set to 'property’.
- functionParameters/templateId: This nested template ID determines which additional parameters are required below.
- functionParameters/functionParameters: These are the function parameters listed in the templateExpression object of the rule template (specified by the template ID).
- functionParameters/schemas: The list of schemas, entities, and properties retrieved in Step 3 are used to set this parameter.
If your rule creation is successful, it will return the rule metadata and a new rule ID. This ID will be used to associate the rule with a test.
On the right, you can see an example of creating a multi-property validation rule which calculates the percentage of elements that have their selected property value set.
Request Syntax
POST https://api.bentley.com/validation/propertyValue/rules HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Request Body
{ "displayName":"TestRule1", "description":"test rule", "templateId": "0000000000000000000000000000000000000000000", "severity": "high", "ecSchema": "*", "ecClass": "*", "whereClause": "", "dataType": "property", "functionParameters": { "templateId": "0000000000000000000000000000000000000000000", "functionParameters": { "propertyName": "Len" }, "schemas": [ { "name": "Architecture_rvt_ThreeD_3D", "label": null, "entities": [ { "name": "Cameras", "label": null, "properties": [ { "name": "Eye__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Eye Elevation" }, { "name": "Far__x0020__Clip__x0020__Offset_PG_VIEW_EXTENTS_Length", "label": "Far Clip Offset" }, { "name": "Target__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Target Elevation" } ] } ] } ] } }
Response Headers
Content-Type: application/json
Response Body
{ "rule": { "id": "ZuO3OCC8sUuVcgeXz1Ih_aW46T-rqU1DrOAlAo6t8xc", "displayName": "MultiPropPctAvailRule", "description": "Multi-property percent available test rule", "templateId": "0000000000000000000000000000000000000000000", "severity": "high", "ecSchema": "*", "ecClass": "*", "whereClause": null, "functionParameters": { "templateId": "0000000000000000000000000000000000000000000", "functionParameters": { "propertyName": "Len" }, "schemas": [ { "name": "Architecture_rvt_ThreeD_3D", "label": null, "entities": [ { "name": "Cameras", "label": null, "properties": [ { "name": "Eye__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Eye Elevation" }, { "name": "Far__x0020__Clip__x0020__Offset_PG_VIEW_EXTENTS_Length", "label": "Far Clip Offset" }, { "name": "Target__x0020__Elevation_PG_VIEW_CAMERA_Length", "label": "Target Elevation" } ] } ] } ] }, "dataType": "property", "_links": { "self": { "href": "https://dev-api.bentley.com/validation/propertyValue/rules/00000000000000000000000000-0000000000000000" } } } }
5. Getting Multi-Property Validation Test Results
After creating a test with the multi-property validation rule, it was run to produce the (shortened) list of results on the right.
The property validation results are formatted with a “result” array that reports the calculated percentage of elements with available property values. It also includes a “ruleList” array that lists all of the rules associated with the test run.
Within each object in the “result” array:
- elementId: the first element id of the set containing the reported property
- elementLabel: the schema:class:property being reported
- ruleIndex: the index of the rule within “ruleList” that this property validation was based on
- badValue: in this case, instead of containing the “bad” value of a property validation failure, this field simply contains the percentage of elements that have a value available for each matching property.
Within each object in the “ruleList” array:
- id: the rule ID
- displayName: the rule name
Request Syntax
GET https://api.bentley.com/validation/propertyValue/results/000000000000000-000000000000000000000000000000000-00000-00000000 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Response Headers
Content-Type: application/json
Response Body
{ "result":[ { "elementId": "0x16fc", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Roofs:Type__x0020__Comments_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "0" }, { "elementId": "0x16fc", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Roofs:FamilyType)", "ruleIndex": 0, "badValue": "100" }, { "elementId": "N/A", "elementLabel": "No property found", "ruleIndex": 0, "badValue": "TypeDefinition is not a valid property." }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Door__x0020__Opening_INVALID_Length_TYPE)", "ruleIndex": 0, "badValue": "20" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:OmniClass__x0020__Number_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "10" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Width_INVALID_Length_TYPE)", "ruleIndex": 0, "badValue": "20" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Depth_INVALID_Length_TYPE)", "ruleIndex": 0, "badValue": "20" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Manufacturer_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "40" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Type__x0020__Comments_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "40" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Type__x0020__Mark_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "0" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:OmniClass__x0020__Title_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "40" }, { "elementId": "0x1fd7", "elementLabel": "Percent Available (Architecture_rvt_ThreeD_3D:Specialty__x0020__Equipment:Assembly__x0020__Code_PG_IDENTITY_DATA_Text_TYPE)", "ruleIndex": 0, "badValue": "70" } ], "ruleList":[ { "id":"0000000000000000000000000000000000000000000", "displayName": "MultiPropPctAvailRule" } ] }
6. Conclusion
You are now able to successfully create a multi-property validation rule allowing you to easily validate all elements that have a property name containing a specified filtering string.