BREX Data Module: What, Why, Who, When, Where & How

What?

The Business Rules Exchange Data Module (BREX DM) is used to programmatically enforce business rules that govern what can and cannot appear in an S1000D data module’s content. The BREX DM uses XPath statements that verify that authored content conforms to the project's business rules. For example: to ensure consistency in the units of measurement used in a program a BREX rule could specify and enforce the use of only metric values.

Note: There are business rules that are defined by a project that cannot be enforced programmatically. Business rules that cover general policy (such as publishing to an IETM environment) are dictated in a Business Rule document, but are not part of the BREX.

Why?

BREX validation is an additional layer of validation beyond the basic validation provided by the S1000D XML Schemas. The S1000D XML Schemas have hundreds of elements and attributes that are optional. The BREX DM specifies which of these are optional or required for your project. While you could author S1000D content without using BREX validation, you would certainly wind up with lots of information incorrectly marked up in your documents.

Who?

Analysts define the BREX DM.

Technical writers use the BREX DM.

When?

BREX generation occurs during the Business Rules stage of the S1000D Process and BREX validation happens during Authoring.

BREX Generation

BREX DMs are defined during the Business Rules phase of an S1000D project.  There are 2 ways to generate BREX DMs: 1) Manually or 2) Automated

Manual

BREX DMs can be created by reading business rules from a spreadsheet and then hand-coding XML. This is a tedious and error prone process that is very difficult to maintain over time.

Automated

BREX DMs can be created, managed, and maintained over time using an automated tool.

BREX Validation

BREX validating may occur during the authoring process or post-edit. Rules that forbid elements or provide an enumerated list of attributes can be enforced in real-time.  Rules that define required elements can only be enforced post-edit. BREX validation that occurs during editing requires integration with your XML editor. Post-edit validation occurs outside an XML editor.

Where?

BREX DMs are used by XML authoring tools and S1000D Common Store Databases (CSDB). If your tool supports BREX validation then business rules are enforced by the CSDB.

How?

1. Create BREX DM
2. Load BREX DM (into authoring tool or CSDB)
3. Load S1000D Content
4. Validate S1000D Content against BREX DM
5. If violations exist, report them to the content author.

Helpful links

• The Stages of an S1000D Project: http://www.crowsol.com/blog/bid/42486/The-Stages-of-an-S1000D-Project
• Beyond Spreadsheets: Achieving Traceability Between S1000D Business Rules and BREX: http://www.crowsol.com/company/white-papers
• S1000D Business Rules: http://www.crowsol.com/s1000d/s1000d-business-rules
• DecisionPoint™: http://www.crowsol.com/products/decision-point

 

- Dan

 

Free S1000D Consultation Opportunity!

Concurrent with the Joint Services S1000D Workshop being held at the Gulf Coast Community College in Panama City, Florida, Crowell Solutions will be present in Panama City Beach. Rick Schochler and Don Smith, Ph D., will be staying at the Holiday Inn Resort. Rick and Don are interested in meeting with other S1000D practitioners and discussing the issues and challenges of real-world S1000D implementations, such as:

• S1000D Business Rules
• S1000D Systems
• S1000D Training
• S1000D Best Practices

In addition, Rick and Don can discuss the industry leading application for developing and managing S1000D business rules, DecisionPoint™.

If you want to chat with two people who have been in the "S1000D trenches" shoot us an email at rschochler@crowsol.com or dsmith@crowsol.com, or call either Rick at 817-999-2258 or Don at 214-264-7136. You can also catch our twitter updates by following us @crowsol.

We look forward to seeing you in Florida!

The Stages of an S1000D Project

At a company that I once worked for (I won’t name names, but they once enjoyed a good reputation in the SGML/XML world), we developed and marketed a process for how data moved through a system, from creation to distribution. It served as a very effective tool for explaining to our customers exactly what we did and why our services were valuable.

I think a similar approach is needed for detailing the activities in instantiating an S1000D-based system. I’ll come up with a fancy term such as “S1000D Process” – see Mom, all my years of schooling are finally paying off!

The S1000D Process:

We have identified six components of the S1000D process:

1. Setup
   1. Determine which version of S1000D you are going to use.
   2. Identify content to be managed.
   3. Determine data module granularity.
   4. Determine publishing strategy (electronic, print, both).
   5. Complete the Functionality Matrix available from the S1000D website.
2. Business Rule Definition
   1. Detail your S1000D business rules.
   2. Determine which rules can and should be enforced by the BREX.
   3. Generate or develop your BREX document.
3. CSDB Selection
   1. Determine which tool best fits your organization’s needs.
   2. Decision is based on S1000D version, existing infrastructure, desired functionality and, of course, $$$.
   3. Note this right off the bat: You WILL need customizations.
4. CSDB Implementation
   1. Integrate with existing systems.
   2. Develop customizations to fulfill the totality of your requirements.
5. Authoring
   1. Coordinate with engineering.
   2. Technical writers are creating content utilizing S1000D schemas and the appropriate BREX document.
   3. Create illustrations.
6. Publishing and Distribution
   1. Publish to electronic and/or print.
   2. Distribute worldwide!

--Rick

S1000D: The Simplest Explanation Ever

At this past year’s AIA conference in lovely Clearwater, Florida (that’s not sarcasm, Clearwater is awesome…especially the SandKey Marriott…hey, maybe they’ll throw some points my way for this endorsement!) a speaker asked for a simple explanation of S1000D.

OK, here goes:

S1000D is a specification for creating and managing technical data in a modular format called “data modules”. Data modules are best described as one complete thought or process. This might be a description of a tool, or a subtask in a larger task. By creating this content in modular form (as opposed to traditional cover to cover technical manuals), content can be reused as many times as necessary. S1000D uses XML Schemas to control what can and cannot be found in data modules. There are several different types of data modules catering to content ranging from descriptive to procedural, to illustrated parts data and scheduled maintenance. S1000D is ideally suited for large-scale manufacturing and repair environments.

There. A simple explanation of S1000D. It occurs to me that S1000D is somewhat akin to baseball (though not as fun). Just as baseball is a simple sport to explain but a hard one to master, S1000D can be simply described, but the details of how it all works may take a LONG time to master.

--Rick

S1000D: Why NOT to Use Pseudo Data Module Codes

Even the most ardent defender of S1000D has to agree that it has limits. It is a great specification for capturing complex technical data in a complex fashion. And, while long, the Data Module Code (DMC) is good at uniquely identifying S1000D data module content. I admit I still have to, on occasion, look up all of the components that comprise a DMC. For a more detailed explanation, visit our S1000D Glossary.  For your reference, here is a quick explanation:

However, just as S1000D is not an ideal fit for someone creating a poem, a DMC is not a good means of identifying non-S1000D content. For example, using pseudo-DMCs while creating supporting content for the specification, including creating unique IDs for business rules is a bad idea.  Pseudo-DMCs create additional complexity and do not provide additional value in return.  Using a simpler ID syntax provides all the capabilities you will need.  The methodology we use is simple: take the chapter from which the rule came and append a -1, -2, -3, etc. (e.g. 3.9.1-1 correponds to the first rule within chapter 3.9.1).

Based on our experiences, DMCs should be used solely in identifying S1000D data module content.

-Rick

Creating a Standardized Means of Capturing S1000D Business Rules

We at Crowell have been knee-deep in S1000D Business Rules for the past couple of months. And that has resulted in our thinking of ways to improve the process of creating and managing business rules. In my previous blog, I mentioned how storing business rules in a spreadsheet application is a bad idea. In this post, I’d like to propose an additional idea for creating business rules: Standardization!

This should be a no-brainer for all of the people in the S1000D world, as we are all about standardization. Alas, we have failed to standardize the means of creating business rules. Programs, groups, and individuals are free to create business rules in any form and by any means they deem appropriate. The problem is that programs are going to want to view, “borrow” and reuse other groups’ business rules. The fact that there isn’t a standard model for creating business rule decisions means that sharing this content is a slight pain in the you-know-what.

Here's a practical example: we have a customer who is developing a set of business rules for a new program. In developing these rules they are referring to a governing set of rules developed for an entire branch of the military. However, we are using chapters as the foundation of business rule ids and they are using pseudo Data Module Codes. Secondly, these governing business rules have imperatives in the description column of the particular rule. That is, there are “shalls” and “shall nots” in both the description of the business rule and in the business rule decision. These two items, coupled with the fact that the guiding business rules are in a spreadsheet (my previous angst on this expressed above) and thus not easily reusable, makes the job of mapping the governing business rules to our customer’s business rules somewhat of a Sisyphean task.

I propose a simple solution: A standard means of capturing business rules.

I think this could be fairly easily accomplished, as most business rule documents have a similar structure, even if the content is in a spreadsheet. That structure is:

1. A business rule ID – Every business rule needs an id. I hate the concept of pseudo Data Module Codes, and will “rant” about that in my next blog post, but if I lose that small battle for the sake of the larger victory, I am fine with that. The bottom line is that every business rule needs an id.
2. Heading or Title – This is the informative title of the particular business rule, such as “Use of Graphics within Titles”.
3. Business Rule Description – This component of business rules lays out the problem at hand, such as “Projects must decide whether or not to allow graphics within the title element.” As noted previously, this descriptive content should not have any imperatives. There should be no directives here, only a description of the content.
4. Program Decision – This is the group’s decision with respect to a particular business rule. Continuing the example, a good business rule decision would be “Program X will not allow graphics to be located within titles”, or, “Authors shall not place graphic elements inside of title elements”.

These business rule components, and any others deemed necessary, can be captured in a very simple and easy to use XML syntax. It could look something like this:

I suppose someone could argue that we simply use the syntax located in the BREX for this, but the BREX isn’t designed for human exchange of business rules. Rather, it is designed to be machine processable. I suppose that’s what I am getting at: A standardized syntax for the human consumption of business rules.

--Rick

Using Spreadsheets to Maintain S1000D Business Rules

There’s a trend emerging with respect to creating S1000D Business Rules, and for a couple of solid reasons, I’d like to see it nipped in the bud. The trend I am referring to is storing business rules in an Excel Spreadsheet. Why is this a bad idea you ask? I’ll give you a couple of reasons:

First, storing business rules in an Excel file renders the business rule completely useless if you wish to reuse it for anything else at any point in the future. The OBVIOUS reuse opportunity is the generation of BREX rules. BREX rules are derived directly from your business rules. As such, is it not the most technically and analytically sound decision to have your BREX rules literally derived from your business rules?

If you store your business rules in an application that is capable of reusing them, you immediately gain the following advantages:

1. You don’t have to write a BREX document…that’s right, you don’t have to write a bunch of XPath statements or pay somebody a boatload of money to do it for you.
2. You can link business rules to BREX rules. Then, when your business rule changes, your BREX rule is changed and all you have to do is press the “go” button to generate a new BREX document.

My second reason for wanting to do away with maintaining S1000D Business Rules in a spreadsheet has to do with the concept of “layered” Business Rules. Right now, entities such as the Air Force, Army, and Naval Aviation Departments are creating business rules. Individual programs will want to use those rules as a baseline and also create their own rules that further define their policies and guidelines with respect to S1000D. And guess what? They’ll probably want to see and use other programs' and departments' rules as well. The more columns that are added to a spreadsheet, the more unreadable it becomes. And, adding a new column does nothing if a group wants to actually use a business rule from another source.

I wrote up a white paper that dives further into this topic. It can be downloaded from White Papers.

-Rick Schochler

 

Next Blog Entry: Creating a Standardized Means of capturing S1000D Business Rules

Welcome!

Welcome to our new and improved website and our new blog page. We are going to post blogs on a regular basis, and we will try to stick to topics that are essential to us and our customers – that is S1000D, content management, Tech Pubs, document management, etc. As per the norm, this will be informal, and it will include opinions, likes and dislikes. We encourage feedback, regardless of whether you agree or disagree, and we certainly hope you find it useful and informative.

Thanks,

Rick Schochler, COO Crowell Solutions