Clash Suppression Rules Basics

Introduction

Suppression rules are rules for clash detection tests that will allow you to filter out potentially unwanted results based on properties of either or both of the clashing elements. In this tutorial, you will learn how to:

• Create a suppression rule
• Associate a suppression rule with a test
• Interpret the results of a test using suppression rules
• Update your suppression rule
• Delete your suppression rule

Prerequisites

This tutorial assumes that you already have:

• Access to an iModel and the associated projectId and imodelId for that iModel, along with the named version ID for the version you want to run the test against
• Knowledge of how to run a clash detection test
  • Instructions on clash test basics, including creation and running are located here
• Property and schema information for the rules you want to implement

1. Get a token

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

Implement Authorization Code Flow in the application

---

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

Grab a user token from Api reference "Try it" Section

---

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.

2. Get Suppression Rules Templates

Suppression rules work by checking elements in a valid clash against specific criteria. A rule can suppress a clash based on matching query criteria on a single element in a clash, matching criteria on both elements in a clash, or even matching criteria based on the relationship between two elements in a clash.

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

3. Creating a Suppression Rule

To create a suppression rule, you need to include the template id of your chosen template, a name for the rule, a reason that describes why the rule exists and what it covers, and the test parameters and send an HTTP request to POST https://api.bentley.com/clashdetection/suppressionRules

The parameters will vary based on your chosen template. Some templates, like 'suppress clashes if clashing elements are in the same category', don't require any parameters- we don't need any more information from you, we can just check the element categories against each other. For templates that do require parameters, you should follow the guidelines set forth by the template expression.

For more advanced users, or those who wish to do something a little more complicated that isn't covered by the standard templates, there are UnaryECSql and BinaryECSql templates that are essentially freeform and allow you to write the desired query criteria yourself in an ECSql expression.

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.

4. Adding a Suppression Rule to a Clash Test

You can either use your suppression rule when creating a fresh clash test or when updating a previously created test. If you need a refresher, full instructions and parameter explanations for either option are located here

The only new step for either option is including a suppression rules array in the request block properties. This will be an array of IDs including the testId returned in the previous creation step, along with any other rules you would want to associate with the test.

Note that when updating a test, this is a replacement update, so if there were previously any rules associated with a test, you will need to include them in the array if you want them to continue to be associated with the test. This also means to disassociate a suppression rule with a clash test, all you would have to do is send an update request without the specified ID in the suppressionRules array.

5. Interpreting Clash Results with Suppression Rules

At this point, you should already understand the basics of how clash tests work and how to run them, so go ahead and run your updated test now, or if you need to, go here to review the process.

While the process of running a test hasn't changed, the results themselves will if there were clashes affected by your new suppression rule. Clashes that fit the suppression rule criteria are not removed from results directly; rather, they have an array property (suppressingRuleIndexArray) that includes the zero-based index of any suppression rule. You can then use this array index to look up the relevant suppressing rule in the suppressingRuleList array, which includes the id and name. This will allow you to see the effect of multiple suppression rules, and which clashes they impact, without having to rerun the test multiple times.

6. Updating a Suppression Rule

To update a suppression rule is relatively simple, all you need to do is send a HTTP PUT https://api.bentley.com/clashdetection/suppressionRules/{id} request. However, you can only update the name and reason- you will not be able to change the rule parameters and would have to create a new rule instead. Both parameters are optional, so if you only want to update one or the other, you can only send that property during the update. You will not need to update any of the associated tests- next time you run them, they will returns responses based on the updated rule.

7. Deleting a Suppression Rule

Deleting a suppression rule is also easy, just send a HTTP request to DELETE https://api.bentley.com/clashdetection/suppressionRules/{id} Upon a successful deletion, the response body will be empty; it will only include additional information if the deletion failed.

At this time, deleting a suppression 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.

8. Conclusion

You should now be able to successfully create and update suppression rules. This will allow you to filter the number of clashes based on your specified criteria so you only have to spend time investigating the issues you think might need attention.

More resources that you may like