Diving Into the BREX (Final of 3 Part Business Rules Series)

In this blog post, the third and final of my business rules posts, I will give an overview of the types of rules that go in a BREX along with some sample code to aid in understanding. For purposes of this blog post series, I am using S1000D version 4.1.

Remember from my first blog that a BREX “…is the document that contains the computer language representation of the business rules.” This means that the business rules have to be converted into a language, called XPath that the computer understands before being put into the BREX as a BREX rule. There is not a one-to-one correlation between a business rule and a BREX rule, so one business rule may turn into multiple BREX rules.

The three types of BREX rules

There are three types of BREX rules in the spec; SNS Rules (snsRules), Context Related Rules (contextRules), and Context Independent Rules (nonContextRules). SNS Rules and Context Independent Rules are written in plain English and Context Related Rules are written in XPath (along with plain English descriptions to aid in understanding the rule).

SNS Rules

SNS Rules in the snsRules element have a formal structure, but are written in plain English. Because they are not written in XPath, and because SNS Rules were introduced in 4.0 of the spec, it is unlikely SNS Rules would be used to validate a data module.

If a formal SNS Rule structure is required, it should be documented in a Context Related Rule. Consider carefully before documenting SNS structure in the snsRules element. If your BREX has XPath SNS rules in the contextRules element, creating SNS rules in the snsRules element would be a duplicate that would need to be updated every time you change your SNS rules. Because of the potential for duplication, I don’t recommend using SNS Rules in your BREX.

Below is a sample SNS Rule that documents the definition of SNS System 25 with the title Equipment/Furnishings along with its subsystem of 1 with the title Subsystem 1.

<snsTitle>Equipment/Furnishings</snsTitle>

<snsTitle>Subsystem 1</snsTitle>

</snsSubSystem>

</snsSystem>

Context Related Rules

Context Related Rules are the heart of the BREX. This is where all the XPath BREX rules are stored. These rules are machine readable and can be used to validate a data module. Context rules can capture and define things like your SNS structure, what elements and attributes must or must not be used, which values are allowed/used for specified elements and/or attributes, plain English descriptions of the business rules, etc. Context is very important and things can get complicated, so I recommend you review some sample BREX data modules and learn a little XPath before you dive in too deep. Here is some sample code to illustrate my point.

BREX rules that would to apply to the procedural schema would be put into this element:

BREX rules that would apply to the entire project would be put into this element:

Below is a sample BREX Rule that documents the answers to Business Rule Decision Point 47. That BRDP actually requires two separate decisions in the BREX, what Language ISO code to be used and what Country ISO code to be used. The objectPath provides the context of where the rule will be applied, the objectUse provides the plain English description, and the objectValue provides the value that is allowed.

<objectPath allowedObjectFlag=”2″>//@languageIsoCode</objectPath>

<objectUse>BRDP-S1-00047. All data modules must use the languageIsoCode ‘en’. countryIsoCode must be ‘US'</objectUse>

<objectValue valueForm=”single” valueAllowed=”en”>English to be used.</objectValue>

</structureObjectRule>

<objectPath allowedObjectFlag=”2″>//@countryIsoCode</objectPath>

<objectUse> BRDP-S1-00047. All data modules must use the languageIsoCode ‘en’. countryIsoCode must be ‘US'</objectUse>

</structureObjectRule>

Context Independent Rules

Context Independent Rules are written in plain English and are captured in the element simplePara. Like SNS rules, Context Independent Rules are not written in XPath, so if you decide to document business rules inside Context Independent Rules, you may be creating a duplicate that would need to be updated every time you change your business rule. Because of the potential for duplication, I don’t recommend using Context Independent Rules in your BREX.

Below is a sample Context Independent Rule that documents the text of the first BRDP along with the business rule decision for the project.

<simplePara>BRDP-S1-00001. Decide whether and when to use the alpha characters “I” and “O”. </simplePara>

<simplePara>The project will not use alpha characters “I” and “O”.</simplePara>

</nonContextRule>

Thank You

Thank you for taking the time to read my blogs. If you have any questions about Business Rules, BREX or S1000D, please feel free to send me an e-mail at info@onestrand.com