Property Validation Basics
Introduction
Use Property Validation to check whether property values in an iModel conform to certain rules. The validation is run on user-defined rules for specified property values.
In this tutorial, you will learn how to:
- Get property value rule templates
- Create/Update/Delete a property validation rule, test, and run
- Run the property validation test against a specific iModel version
- Retrieve the property validation test run results
Prerequisites
This tutorial assumes that you already have:
- Access to an iModel and the associated project ID and iModel ID for that iModel, along with the named version ID for the version you want to run the test against.
- Property and schema information for the rules you want to implement.
- For instructions on retrieving schemas for a specific iModel, see Retrieve Validation Model Data.
1. Request an authorization token using one of the methods below
Use the OAuth2 Authorization article to implement an Authorization code workflow in your application. Include the scopes “validation:read” and 'validation:modify’.
- 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 checks 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. The HTTP GET https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId[&continuationToken][&$top]
request returns all property validation rule templates for the given project ID. Choose the template that is best suited for your goals based on the description.
In this tutorial, we demonstrate using the PropertyValuePattern template.
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":"0000000000000000000000000000000000000000000", "displayName":"PropertyValuePattern", "description":"Checks if the property confirms to the provided pattern", "prompt":"Looks for given pattern in iModel", "templateExpression":{ "propertyName": "LastMod", "pattern": "west" } }, "_links":{ "next":{ "href":"https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId=00000000-0000-0000-0000-000000000000" } } }
3. Creating a property validation rule
Configuring the validation rules is the biggest part of creating a property validation test.
To create a property validation rule, you need the template ID of a property validation template, a name for the rule, a description, the severity of the rule, and the dataType
. You will also need a project ID as well as an EC schema and class. Optionally, you can include a conditional whereClause
. Depending on the template used, you may also need to provide functionParameters
.
- severity: One of four values: “veryHigh’, 'high’, 'medium’, 'low”
- dataType: One of three values: “property’, 'aspect’, 'typeDefinition”
- functionParameters: These are the parameters listed in the templateExpression object of a retrieved template.
- whereClause: Syntax for the where clause is as follows: [propertyName][comparison operator] [value], ie USER_LABEL = 'Door’, for multiple properties connectors such as AND/OR can be used as well.
In the example on the right, a rule is created to match all PUMP elements with a COMPONENT_NAME
property containg the pattern “pmp” with the case-insensitive flag specified. The template ID is set to use the PropertyValuePattern template.
If your rule is created successfully, it will return the rule metadata and a rule ID. This will be used in the following steps to associate the rule with a test.
To update a rule, the request body format is the same, but requires calling the HTTP PUT https://api.bentley.com/validation/propertyValue/rules/{id}
request with the rule ID. Currently, functionParameters
cannot be updated. If a change is needed, you must delete the rule and create a new one.
Deleting a property validation rule requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/rules/{id}
request with the rule ID.
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":"ProcessPhysical", "ecClass":"PUMP", "whereClause":"", "dataType":"property", "functionParameters":{ "propertyName":"COMPONENT_NAME", "pattern":"pmp", "flags":"i" } }
Response Headers
Content-Type: application/json
Response Body
{ "rule":{ "id": "0000000000000000000000000000000000000000000", "displayName": "PropertyValuePatternRule", "description": "property value pattern rule", "templateId": "0000000000000000000000000000000000000000000", "severity": "high", "ecSchema": "ProcessPhysical", "ecClass": "PUMP", "whereClause": null, "functionParameters": { "propertyName": "COMPONENT_NAME", "pattern": "pmp", "flags": "i" }, "dataType": "property", "_links": { "self": { "href": "https://api.bentley.com/validation/propertyValue/rules/0000000000000000000000000000000000000000000" } } } }
4. Creating a Property Validation Test
The process of creating a property validation test is very basic as the majority of the configuration happens during rule creation.
To create a property validation test, you need the ID of the project, a name and description for the test, as well as an array of rule IDs to associate with the test.
To get a list of rules and rule IDs created and available for a specific project requires calling the HTTP GET https://api.bentley.com/validation/propertyValue/rules?projectId[&continuationToken][&$top]
request. The Prefer
parameter to the header can be used to get a condensed or more detailed list of rules. For more details, see Get validation PropertyValue rules.
For this tutorial, simply set the rules array in the given example request body to the ID of the newly created rule from the previous step. Optionally, call the GET request and add some of the rule IDs that are returned.
To update a test, the request body format remains the same but requires calling the HTTP PUT https://api.bentley.com/validation/propertyValue/tests/{id}
request with the test ID.
Deleting a property validation requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/tests/{id}
request with the test ID.
Request Syntax
POST https://api.bentley.com/validation/propertyValue/tests HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Prefer: return=representation Authorization: Bearer JWT_TOKEN
Request Body
{ "projectId":"00000000-0000-0000-0000-000000000000", "displayName":"PV test1", "description":"PV test1", "rules":[ "0000000000000000000000000000000000000000000" ], "stopExecutionOnFailure":true }
Response Headers
Content-Type: application/json
Response Body
{ "test":{ "id":"0000000000000000000000000000000000000000000", "_links":{ "self":{ "href":"https://api.bentley.com/validation/propertyValue/tests/0000000000000000000000000000000000000000000" } } } }
5. Run a Property Validation Test
Triggering a property validation test run requires the test ID from the created test, as well as the iModel ID and Named Version ID of the iModel on which the test is being run.
If a test is successfully triggered, the POST request will return the ID of the run triggered with the associated test. The given run ID can be used in the HTTP GET https://api.bentley.com/validation/propertyValue/runs/{id}
request to check the status of the run as well as retrieve the test results, which are detailed in the next step.
Request Syntax
POST https://api.bentley.com/propertyValue/runs HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN
Request Body
{ "testId":"0000000000000000000000000000000000000000000", "iModelId":"00000000-0000-0000-0000-000000000000", "namedVersionId":"0000000000000000000000000000000000000000" }
Response Headers
Content-Type: application/json
Response Body
{ "run":{ "id":"0000000000000000000000000000000000000000000", "_links":{ "run":{ "href":"https://api.bentley.com/validation/propertyValue/runs/0000000000000000000000000000000000000000000" } } } }
6. Getting Property Validation Test Results
A results link is provided in the response body of the HTTP GET https://api.bentley.com/validation/propertyValue/runs/{id}
request. Retrieving the results can be done by making a GET request using said link which points to the HTTP GET https://api.bentley.com/validation/propertyValue/results/{id}
request.
The property validation results are formatted with a result
array that holds all the invalid property values as well as a ruleList
array that holds all of the rules associated with the test run.
Within each object in the result
array:
- elementId: the element id of the invalid property
- elementLabel: the element label of the invalid property
- ruleIndex: the index of the rule within
ruleList
that this property failed to pass - badValue: the invalid property value
Within each object in the ruleList
array:
- id: the rule ID
- displayName: the rule name
The given example response body to the right shows what might be returned.
Deleting a property validation test run requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/runs/{id}
request with the run ID.
Request Syntax
GET https://api.bentley.com/validation/propertyValue/runs/C3LRQU_ILkmFYQVClhDuxow-EXGyYdJHrgH5zpcUQ8U 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
{ "run":{ "id":"0000000000000000000000000000000000000000000", "displayName":"PropertyValueTest1-10/21/2020 4:07:28 PM", "executedDateTime":"12/1/2020 5:12:50 PM", "count":"27", "userName":"John Johnson", "status":"queued", "_links":{ "result":{ "href":"https://api.bentley.com/validation/propertyValue/results/0000000000000000000000000000000000000000000000000000000000000000" }, "test":{ "href":"https://api.bentley.com/validation/propertyValue/tests/0000000000000000000000000000000000000000000" } } } }
Request Syntax
GET https://api.bentley.com/validation/propertyValue/results/0000000000000000000000000000000000000000000000000000000000000000 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":"0x3000000000d", "elementLabel":" [3-D] ", "ruleIndex":0, "badValue":"Undefined" }, { "elementId":"0x3000000000f", "elementLabel":" [3-F] ", "ruleIndex":0, "badValue":"Undefined" }, { "elementId":"0x30000000010", "elementLabel":" [3-G] ", "ruleIndex":0, "badValue":"Undefined" } ], "ruleList":[ { "id":"0000000000000000000000000000000000000000000", "displayName":"TestRule1" } ] }
Conclusion
In this tutorial, you learned how to create, update and delete property validation rules and tests. You also learned how to run a property validation test and fetch the results.