S1000D Business Rules Webinar SeriesWebinar 3 – S1000D BREX – Business Rules Exchange

Michael CookLead S1000D Business Analyst

Jennifer GoodmanVP Product Management and SDL S1000D Product Owner

2

Our Presenters

Lou “Wish you were here!” IuppaVP Strategic Business DevelopmentSDL S1000D Business Owner

Michael CookLead S1000D Business Analyst

Jennifer GoodmanVP Product ManagementSDL S1000D Product Owner

3

Agenda Today

Announcing the SDL Ask An S1000D Expert Tour

What you will learn today…• Basics of Business Rule EXchange data modules

• How elements or attributes are made mandatory

• How elements or attributes are excluded

• How enumerators are defined

Q&A

Industry Conferences, Local Events, and Recorded EducationalS1000D Webinars

4

Ask An S1000D Expert Tour

Mike CookS1000D Business AnalystSDL Structured Content Technologies

BREX – Business Rules EXchange

6

Abstract

The intent of this webinar is to:Present the inner workings of a BREX data module for Issue 4.0.1 of the S1000D specification

Focus audience:This session is for anyone new to S1000D who wants to know more about Business Rule EXchange data modules.Experts or people who are new to the S1000D methodology will find helpful information regarding how validation of data modules is accomplished using the BREX data module.

Primary knowledge transfer points:Basics of Business Rule EXchange data modulesHow elements or attributes are made mandatoryHow elements or attributes are excludedHow enumerators are definedFree tools to help in the identification of business decisions and creation of the BREX data module

7

A BREX data module is intended to:Validate project authored data modulesHold the meanings of enumerated values

Layering is a fairly new concept for business rulesThe intent of layering is to add further restrictions to the rules found in BREX data modules referencing BREX data modules higher within the layered structure.

A BREX data module can also be part of a “layered” BREX data module set or be part of a layered hierarchy of rules

What is a BREX data module

8

Validation

To validate data modules, so the content respects the intent of the Business Rule Design Documents, each data module must point to a BREX data module. Within the <identificationAndStatus> element block is an entry for a <brexDmRef> element. This reference should point to a BREX data module.

Example:<brexDmRef> <dmRef xlink:type="simple"

xlink:href="DMC-PROD1-A-00-00-00-00A-022A-D" xlink:title="My Special Project - BREX"> <dmRefIdent> <dmCode modelIdentCode="PROD1" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/> </dmRefIdent> </dmRef> </brexDmRef>

9

Validation – cont’d

BREX data module

references

If a BREX validation program is run on the data module it should provide a report of any deficiencies found in the data module – based on the rules set in the BREX data module.

Project data module

generates

DMC-PROD1-A-21-11-05-00A-520A-D_005-00.XML DMC-PROD1-A-00-00-00-00A-022A-D_001-00.XML

10

Validation - Layered

BREX data module 3

references

Project data module BREX data module 2

references

BREX data module 1

references

BREX 3 restricts BREX 2 BREX 2 restricts BREX 1

The project data module validates to BREX 3, but also any rules set in BREX 2 and BREX 1.

DMC-PROD1-A-21-11-05-00A-520A-D DMC-PROD1-A-00-00-00-00A-022A-D DMC-SB2000-A-00-00-00-00A-022A-D DMC-USGOV-A-00-00-00-00A-022A-D

11

Within the specification is a definition of how a layered BREX structure is implemented and how each layer further restricts rules.Practically speaking, this is supposed to be accomplished such that none of the rules in a layer above a given level are superseded by those in subsequent layers. The reality can be a little different.Not all projects can live with the rules as defined in a preceding layer. For example, at the project level (layer 4), a rule might supersede a rule in a higher layer to support either a business, project, or defense level rule. The specification suggeststhose lower in the layering structure petition to the organizations above it for waivers to the BREX rule set. There are also potential issues of theorganizations above a given layerhaving no idea of the road-blocks they areimposing on the levels below them.

Validation – Layered – Defense projects

12

Validation – Layered – Civil projects

The civil aviation structure for layered BREX rules is more plausible, however the layer concept contradicts the intent of the BREX definition in Issue 3.0 and earlier.In previous issues of the specification, the BREX defined by a project had the final say in what was and was not checked/validated. The new paradigm imposes severe control and potentially immovable rules and definitions.As part of the businessrules definition for yourproject, you should decidewhether or not yourorganization will use thelayered BREX approach.Therefore, the layered approach is OPTIONAL.

13

Layered BREX

Logically speaking, the layered BREX methodology makes good sense.

Practically speaking, the layered BREX approach is problematic when customers have differing requirements within their organizations – such that more than one defined BREX exists to support a project. For example, a multi-project product used by more than one customer.

Technically, the project BREX must support multiple customer requirements – but all customers must agree to the same BREX at their layer within the BREX layered structure. This can creat contradictory BREX rules.

The USAF MIL-STD S1000D specification indicates there are contradictions between the USAF and Joint Services organizations. These differences – because these organizations could all be classified as Layer 2 or above – will cause considerable problems for a business attempting to author content for a product used by both agencies.

For defense related projects, it is highly likely you will not have the option to “opt out” of using the layered BREX. You will most likely be bound contractually to using the layered BREX model.

14

Question

15

Validation of Elements or Attributes

One of the primary capabilities of the BREX is to set specific elements or attributes to either “required” or “do not use”.The second capability is to define the enumerations of specific attributes and elements – and creating definitions of new/custom enumerations.All other validations require special handling using XPath expressions.

16

Make an Element or Attribute Mandatory

The first rule type you can use in a BREX is to make an element or attribute mandatory. Use the following XML code structure within the BREX to accomplish this capability.

The “allowedObjectFlag” sets an element or attribute to required if it has a value of “1”.The “//crewMember/@crewMemberType” is a relative XPath address indicating when a <crewMember> element is encountered it is required to have an attribute “crewMemberType” within it.

<structureObjectRule> <objectPath allowedObjectFlag="1">//crewMember/@crewMemberType</objectPath> <objectUse>Type of crew member required for drill or procedural step</objectUse> <objectValue valueAllowed="cm01" valueForm="single">All</objectValue> <objectValue valueAllowed="cm51" valueForm="single">Bike rider</objectValue> <objectValue valueAllowed="cm52" valueForm="single">Bike technician</objectValue> </structureObjectRule>

17

Exclude an Element or Attribute

The second rule type you can use within a BREX is to exclude an element or attribute from use. To do so use the following XML code structure within the BREX.

<structureObjectRule>

<objectPath allowedObjectFlag=“0">//warning/orderedList</objectPath>

<objectUse>Ordered lists are not allowed in Warnings</objectUse>

</structureObjectRule>

The “allowedObjectFlag” sets an element or attribute to excluded if it has a value of “0”.The “//warning/orderedList” is a relative XPath address indicating when a <warning> element is encountered it is required to never have an <orderedList> element within it.

18

Define Enumerators

The third rule type you can use within a BREX is to set the definition of enumerated values for a given attribute or element. For example:<structureObjectRule> <objectPath>//emphasis/@emphasisType</objectPath> <objectUse>Type of emphasis</objectUse> <objectValue valueAllowed="em01" valueForm="single">Bold </objectValue> <objectValue valueAllowed="em02" valueForm="single">Italic</objectValue> <objectValue valueAllowed="em03" valueForm="single">Underline</objectValue> <objectValue valueAllowed="em04" valueForm="single">Overline</objectValue> <objectValue valueAllowed="em05" valueForm="single">Strikethrough</objectValue> </structureObjectRule>

The enumerated values set with the “valueAllowed” attribute is a little misleading. The range defined in the schemas (for this attribute) is usually “em01” through “em05”. This means there are 94 unused values – which supposedly means those extra values are open for other uses – which you can take advantage of if your project needs them.The “valueForm” attribute determines whether the enumerated value is “single”, “range”, or a “pattern”.

19

“valueForm” Attribute

The valueForm attribute has three possible values.singleA single entry can be provided in the “valueAllowed” attribute. Example: “at02”

rangeA range of values can be provided in the “valueAllowed” attribute. Example: “em01~em99” (note the tilde not a hyphen or dash)

patternIf the value must match a pattern, consult the following specification for the syntax:http://www.w3.org/TR/xmlschema-2/Example: valueAllowed="[0-9][A-Z]{3}" (one numeric value followed by three uppercase alpha values). For example: “3ABC”

20

Optional BREX Capabilities

It is possible to define the SNS hierarchy of a project within the BREX.

It is possible to accomplish a similar goal using a Front Matter data module known as the Table of Contents (TOC) data module using a table.

This optional SNS definition capability is problematic for large projects (for example an aviation style SNS where a complete SNS could easily be more than 8,000 entries (but would translate to over 32,000 lines in the BREX)). This could cause memory limitation issues with BREX validation if a large BREX file also

included the SNS. If you have a complex BREX file with a significant number of validation points, it is

recommended to not include the SNS in the BREX. In this case, it is recommended to create a new BREX file and provide it with a different DM code, potentially using an information code variant of “022B” (or whatever you choose to define) or to use the prescribed disassembly code incremental approach “01”, “02”, etc.

21

Optional BREX Capabilities – cont’d

XML structure of the SNS node in the BREX:<snsRules> <snsDescr> <snsSystem> <snsCode>00</snsCode> <snsTitle>General</snsTitle> <snsSubSystem> <snsCode>4</snsCode> <snsTitle>Publication</snsTitle> <snsSubSubSystem> <snsCode>0</snsCode> <snsTitle></snsTitle> <snsAssy> <snsCode>0001</snsCode> <snsTitle>System Description Section</snsTitle> </snsAssy> </snsSubSubSystem> </snsSubSystem> </snsSystem> </snsDescr> </snsRules>

Optional to have 2 or 4 characters for a Unit or Assembly code.

22

Optional BREX Capabilities – cont’d

Notation rules. If you want to enforce or disallow the use of a specific notation, here’s how you do it.

<notationRuleList> <notationRule> <notationName allowedNotationFlag="0">NOTATION cgm SYSTEM "image/cgm"</notationName> <objectUse>Disallowed notation found.</objectUse> </notationRule> </notationRuleList>

This notation rule is in reference to a NOTATION in the DOCType block.

23

XPath Notation

Take note of the following example and how XPath is used to create a conditional statement:

<structureObjectRule> <objectPath allowedObjectFlag="0">//descendant-or-self::orderedList[not(ancestor-or-self::description)]</objectPath> <objectUse>Sequential (numbered) lists not allowed unless in descriptive data modules</objectUse> </structureObjectRule>

The string from the <objectPath> element is an XPath expression://descendant-or-self::orderedList[not(ancestor-or-self::description)]

This creates a statement which restricts the use of the <orderedList> element to a <description> element block of a data module created from the descrip.xsd schema (<description> is the container for descriptive content in a descrip.xsd schema). If you’ve created any transforms (xslt) files, this should be familiar. This is how you make a rule specific to a given schema

This webinar does not discuss the finer points of XPath. However, this is a very powerful capability you should explore in order to add even greater capabilities to your BREX data module.

24

Example BREX

DMC-PROD1-A-00-00-00-00A-022A-D.XML

DMC-PROD2-A-00-00-00-00A-022A-D.XML

BREX Builder

25

Thank You for Joining Us

S1000D in person…Ask An S1000D Expert Tour – register at www.sdl.com/s1000dtour May 25 – Seattle, WA June – San Diego, CA September – Fort Worth, TX October – Warner Robins, GA November – Washington DC

Industry Conferences May 12-13, 2011 - AIA-Joint Services Technical Publications workshop

• Clearwater Beach, Fla. June 6-8, 2011 - ATA e-Business Forum and S1000D User Forum

• Montreal, Quebec, Canada

To register for all SDL events visit: www.sdl.com/en/xml/events

26

S1000D: Recorded Events

SDL S1000D Webinar Series RecordingsIntroduction to S1000D ConceptsS1000D Content WorkflowS1000D ApplicabilityS1000D and IETPSS1000D and MultimediaS1000D Business Rules Webinar Series

http://www.sdl.com/en/xml/resources/resources-by-topic/topic-s1000d.asp

Questions?