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

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’.

Grab a user token from API reference “Try it out” Section

---

1. Open Get property value validation rule templates
2. Click the Try it out button.
3. In the Authorization section, select AuthorizationCode.
4. 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.

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.

Updating a property validation rule

---

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

---

Deleting a property validation rule requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/rules/{id} request with the rule ID.

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.

Updating a property validation test

---

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 test

---

Deleting a property validation requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/tests/{id} request with the test ID.

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.

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.

Delete a property validation test run

---

Deleting a property validation test run requires calling the HTTP DELETE https://api.bentley.com/validation/propertyValue/runs/{id} request with the run ID.

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.

More resources that you may like