Property Validation Rules Basics

Introduction

Property Validation is used to check whether property values in an iModel conform to certain rules. The validation is ran 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 test run
  • Run the property validation test against a specific iModel version
  • Grab the property validation test run results

Info

Skill level:

Basic

Duration:

20 minutes

Prerequisites

This tutorial assumes that you already have:

1. Get a token

To make a request to the API a user token is needed.

Follow this article to implement Authorization code workflow in your application.

  1. Go to the property value api page
  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.

For this tutorial we will be using the Bay Town Processing Plant sample iModel as a basis for the response and request bodies. You can follow along with a copy of the iModel, or a different iModel of your own.

2. Get Property Validation Rules Templates

A property validation rule is used as a basis for cross-referencing the value of a property. A rule can check if a value of a property is defined, within a range of values, matches a pattern, etc.

To make it simpler, we’ve provided a variety of property validation rule templates. An HTTP GET https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId[&continuationToken][&$top] request will return all of the valid property validation rule templates for the given project id. You can simply choose the template that sounds best suited for your goals based on the description.

For this tutorial we will be using the PropertyValueDefined template for a Bay Town Processing Plant sample iModel, which is listed on the right in the response body.

Request Syntax


HTTP
GET https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId=5e19bee0-3aea-4355-a9f0-c6df9989ee7d HTTP/1.1

Request Headers


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

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "ruleTemplates":{
    "id":"unw8wohnNkK7jgrqoTScQVNliaVI4hlGt8hby0h45Rw",
    "displayName":"PropertyValueDefined",
    "description":"Checks whether the given property value is defined or not",
    "prompt":"Checks for the property in given iModel Schema",
    "templateExpression":{
      "propertyName":"LastMod"
    }
  },
  "_links":{
    "next":{
      "href":"https://api.bentley.com/validation/propertyValue/ruleTemplates?projectId=38b7e366-bc20-4bb1-9572-0797cf5221fd&continuationToken=eyJ0b3AiOjQsInNraXBUb2tlbiI6Ik1nPT0ifQ"
    }
  }
}

3. Creating a Property Validation Rule

The bulk of the process for creating a property validation test comes in the configuration of rules.

To create a property validation rule, you will 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 also include a conditional whereClause and depending on the template used, you may need to provide functionParameters.

  • severity: Should be one of four values: “veryHigh’, 'high’, 'medium’, 'low”
  • dataType: Should be one of three values: “property’, 'aspect’, 'typeDefinition”
  • functionParameters: These are the parameters listed in the templateExpression object of a retrieved template.
  • whereClause: Syntax for whereClause should be as follows: [propertyName][comparison operator] [value], ie USER_LABEL = 'Door’, for multiple properties connectors such as AND/OR can be used as well.

If your rule creation is successful, 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.

Following the previous step, we will be using the template selected to create a valid property validation rule with the given example response body.

For updating, a rule, the request body format remains the same, but is sent through the HTTP PUT https://api.bentley.com/validation/propertyValue/rules/{id} request, with id being the rule id. As of current functionParameters cannot be updated. If a function parameter needs to be updated, please delete and re-create the rule.

Deleting a property validation rule requires only sending an HTTP DELETE https://api.bentley.com/validation/propertyValue/rules/{id} request, with id being the rule id.

Note: At this time, deleting a property validation rule does not automatically delete them from associated tests, so please make an effort to update the tests in conjunction with the rule deletion to keep things consistent.

Request Syntax


HTTP
POST https://api.bentley.com/validation/propertyValue/rules HTTP/1.1

Request Headers


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

Request Body


JSON
{
  "projectId":"38b7e366-bc20-4bb1-9572-0797cf5221fd",
  "displayName":"TestRule1",
  "description":"test rule",
  "templateId":"unw8wohnNkK7jgrqoTScQVNliaVI4hlGt8hby0h45Rw",
  "severity":"high",
  "ecSchema":"ProcessFunctional",
  "ecClass":"NOZZLE",
  "whereClause":"UNIT>=0",
  "dataType":"property",
  "functionParameters":{
    "propertyName":"MANUFACTURER"
  }
}

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "rule":{
    "id":"1cKcvg7Ky0e66uT-2u8vpZ5ifQZec1dEhNDUO8ZloRk",
    "_links":{
      "self":{
        "href":"https://api.bentley.com/validation/propertyValue/rules/1cKcvg7Ky0e66uT-2u8vpZ5ifQZec1dEhNDUO8ZloRk"
      }
    }
  }
}

4. Creating a Property Validation Test

The process for creating a property validation test is very basic as the majority of the configuration happens in the rule creation process.

To create a property validation test, you will need the id of the project you wish to associate this test with, a name and a description for the test, as well as an array of rule ids associated with the test.

To get a list of rules and rule ids created and available for a specific project, use this 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. More details on this GET request can be found here.

For this tutorial, simply update the rules array in the given example request body with the id of the newly created rule from the previous step. Optionally, you can also run the GET request and grab multiple rule ids returned from that list as well.

For updating a test, the request body format remains the same but is sent through the following HTTP PUT https://api.bentley.com/validation/propertyValue/tests/{id} request, with id being the test id.

Note: This will replace everything, so if you are adding new rules, make sure to pass in the full list of rule ids rather than just the new rule.

Deleting a property validation test is similar to deleting a rule. You will need to send an HTTP DELETE https://api.bentley.com/validation/propertyValue/tests/{id} request, with id being the test id.

Note: Deleting a property validation test does not automatically delete associated test runs.

Request Syntax


HTTP
POST https://api.bentley.com/validation/propertyValue/tests HTTP/1.1

Request Headers


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

Request Body


JSON
{
  "projectId":"38b7e366-bc20-4bb1-9572-0797cf5221fd",
  "displayName":"PV test1",
  "description":"PV test1",
  "rules":[
    "ZuO3OCC8sUuVcgeXz1Ih_fQIIEKQjLNCh4y1BGTvDpg"
  ],
  "stopExecutionOnFailure":true
}

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "test":{
    "id":"1cKcvg7Ky0e66uT-2u8vpZ5ifQZec1dEhNDUO8ZloRk",
    "_links":{
      "self":{
        "href":"https://api.bentley.com/validation/propertyValue/tests/1cKcvg7Ky0e66uT-2u8vpZ5ifQZec1dEhNDUO8ZloRk"
      }
    }
  }
}

5. Run a Property Validation Test

Triggering a property validation test run requires only the test id from the created test as well as the iModel id and Named Version id of the iModel you wish to run the test on.

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 see on the status of the run as well as retrieve the test results, which are detailed in the next step.

Request Syntax


HTTP
POST https://api.bentley.com/propertyValue/runs HTTP/1.1

Request Headers


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

Request Body


JSON
{
  "testId":"1cKcvg7Ky0e66uT-2u8vpZ5ifQZec1dEhNDUO8ZloRk",
  "iModelId":"ea349f77-f670-4e53-912b-2de45ce824ec",
  "namedVersionId":"ee1f94bbf53ee6bc4a524e5580c4e9a4fb49c98e"
}

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "run":{
    "id":"1cKcvg7Ky0e66uT-2u8vpSTBs9cXiSlMrE8Zym2jD0Y",
    "_links":{
      "run":{
        "href":"https://api.bentley.com/validation/propertyValue/runs/1cKcvg7Ky0e66uT-2u8vpSTBs9cXiSlMrE8Zym2jD0Y"
      }
    }
  }
}

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.

Note: While the results link will always appear in the response body, you will not be able to actually retrieve the results until the status is shown as complete.

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 is a shortened snippet of what should be returned if the rule we created earlier was used on a Bay Town Processing Plant iModel.

Deleting a property validation test run is similar to the other two deletions. You will need to send an HTTP DELETE https://api.bentley.com/validation/propertyValue/runs/{id} request, with id being the run id.

Request Syntax


HTTP
GET https://api.bentley.com/validation/propertyValue/runs/C3LRQU_ILkmFYQVClhDuxow-EXGyYdJHrgH5zpcUQ8U HTTP/1.1

Request Headers


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

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "run":{
    "id":"1cKcvg7Ky0e66uT-2u8vpSTBs9cXiSlMrE8Zym2jD0Y",
    "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/1cKcvg7Ky0e66uT-2u8vpU1fL3jpQOxEs7jYnNkoTYgKU2BJP-MPTK5-8S9ARz4T"
      },
      "test":{
        "href":"https://api.bentley.com/validation/propertyValue/tests/1cKcvg7Ky0e66uT-2u8vpQlT8rXn5qlIq7JOBnNZtKY"
      }
    }
  }
}

Request Syntax


HTTP
GET https://api.bentley.com/validation/propertyValue/results/1cKcvg7Ky0e66uT-2u8vpU1fL3jpQOxEs7jYnNkoTYgKU2BJP-MPTK5-8S9ARz4T HTTP/1.1

Request Headers


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

Response Headers


HTTP
Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body


JSON
{
  "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":"unw8wohnNkK7jgrqoTScQe2MwrbLanBJiVF3Xl8QXZ8",
      "displayName":"TestRule1"
    }
  ]
}

Conclusion

In this tutorial, we walked through how to create, update and delete property validation rules and tests. We also walked through the process to trigger a property validation test as well as how to fetch the results of the test afterwards.