Skip to Content

In the various applications, industries and projects I have implemented BRF+ business rules I always came accross the question of how to document these rules.

As one intention of rules engines is to reduce documentation by providing a user interface which business and IT experts can use to actually browse through business rules, project requirements, support and other stake holders still demand a proper documentation of these rules.

If your rules engine does not provide the funcionality to print the modelled rules or not according to your standards/formats/needs I recommend you to follow these steps:

What are the program/project/customer guidlines you have to follow ?0.1.

Who will work with the documentation?0.1.

What media and formats do you want to use (word, excel, …) ?0.1.

In what detail will you require the documentation and how can you ensure the reader is able to find the documenation in the rules engine ?0.1.

Develop a template and teach your people how to use it ?While the most documentation is done in a Microsoft Word like program I recommend the following structure to use for documentation. This has been proofed to be easily readable and enhanceable while providing a clear structure. It can always be adjusted to the project needs. This approach is BRF+ specific, but can be adjusted to other engines.

Start with a description of the business use case you plan to support and how the BRF+ is integrated from a process and technical perspective. For every BRF+ application provide information about function details like names and attributes (transport mode, functional/event mode etc) and list the rule sets or top expressions being used by the function to provide an overall understanding of the BRF+ application.

Further, explain what context information is being passed to the function, what the result object will be and link to a naming convention document or document it within.

Open one sub-chapter per function and rule set.

For each rule, use the structure below (or an adjusted structure, but make sure everybody in the BRF+ team uses the same structure) to describe it’s conditions, actions and subsequent rules to whatever level it makes sense to you. I do not describe every mapping in detail, but rather the logical steps and expressions/actions/rules and their outcome. For details I refer to look into the rules engine or requirement documents.

Example (first try to understand the sequence of the rules in the table, and then compare it with the screenshots below):

Rule Set Description:

Provide background information, context, pre-conditions, exit conditions and alike.

Rules:

(1) Rule: Calculate discount, update one order object and trigger approval process ; BRF+ ID 64315000D8301ED08EB953EEBD81C010

IF

%

Expression Formula: FML_CALC_SUM (sum of all purchased products) > 10.000 €

%

</p></td><td rowspan=”2″ width=”49″><p>THEN</p></td><td colspan=”6″ width=”493″ valign=”top”><p>Process expression Formula: FML_CALC_DISCOUNT to determine the % discount.</p></td></tr><tr><td colspan=”6″ width=”493″ valign=”top”><p>1.1.    Process Rule: R_CALC_PRODUCT_PRICE</p></td></tr><tr><td colspan=”2″ width=”79″ valign=”top”><p> </p></td><td width=”30″><p>IF</p></td><td colspan=”5″ width=”463″ valign=”top”><p> <additional conditions could apply here></p></td></tr><tr><td colspan=”3″ width=”109″ valign=”top”><p> </p></td><td width=”49″><p>THEN</p></td><td colspan=”4″ width=”415″ valign=”top”><p>Process Expression Loop: LO_PRODUCTS for every product in IT_PRODUCTS and do for each entry: </p><p>Process expression Formula: FML_CALC_PRODUCT_PRICE to determine the final price.</p><p>Process action CRM Update OneOrder: UP_ITEM with final price</p></td></tr><tr><td colspan=”4″ width=”157″ valign=”top”><p> </p></td><td colspan=”3″ width=”393″ valign=”top”><p>1.1.1. Process Rule: R_TRIGGER_APPROVAL_WORKFLOW</p></td><td width=”22″><p> </p></td></tr><tr><td colspan=”4″ width=”157″ valign=”top”><p> </p></td><td width=”30″><p>IF</p></td><td colspan=”3″ width=”385″ valign=”top”><p>Expression Formula: FML_CALC_END_SUM (sum of all discounted products to be purchased) > 5.000 €</p></td></tr><tr><td colspan=”4″ width=”157″ valign=”top”><p> </p></td><td colspan=”2″ width=”49″><p>THEN*

%

Process expression *Workflow: WF_APPROVAL to create a new workflow item with WF Task ID TSxxxx and reason code 01 for responsible approver. </p></td></tr><tr><td width=”30″ valign=”top”><p>    </p></td><td width=”49″><p>ELSE</p></td><td colspan=”6″ width=”493″ valign=”top”><p> </p></td></tr></tbody></table><p>Now the same logic in screenshots of a BRF+ application.<br />Rule-Set*

image *</p><p>1st Rule<br /><a></a>!https://weblogs.sdn.sap.com/weblogs/images/251744534/rule1.png|height=313|alt=image|width=700|src=https://weblogs.sdn.sap.com/weblogs/images/251744534/rule1.png|border=0! </p><p>2nd Rule*!https://weblogs.sdn.sap.com/weblogs/images/251744534/rule2.png|height=295|alt=image|width=700|src=https://weblogs.sdn.sap.com/weblogs/images/251744534/rule2.png|border=0!</body>

To report this post you need to login first.

6 Comments

You must be Logged on to comment or reply to a post.

  1. Former Member
    I’ve gone down this path before too on projects, but what I’ve learned is that this is specifically how to document business rules in a technical format for an IF/THEN business rules system like BRFplus.

    The formal documentation of business rules should always be first done in a semantic manner that business people can understand (see SBVR, RuleSpeak and upcoming DMN notation).  This is arguably the most critical part of the whole process of taking ownership of the rules back into the hands of the business.  The documentation itself should be considered a living key deliverable in a business rules project, since it will be updated (by the business) with every single rule change before the system is updated. Implementation is only half of the game and it is the more technical side of the game.

    However, once the formal documentation is complete, this is a good approach for functional/technical specifications.  Companies using the infamous ‘RICE’ concept simply need to adapt.  Business rules cannot be considered an ‘enhancement’ to the ‘standard’, and we cannot use the same old word templates we’ve had since 1995.

    I think in this relatively new field, most companies will skip the first semantic step and jump into the technical documentation right away.  Usually this is because the customer or isv thinks a business rules engine by itself can be used to improve a business.  What these companies don’t understand is that only changing implementation technologies isn’t going to benefit them much.  Changing the whole approach by having formal documentation which is then leveraged in a new technology will work much better in the case of business rules.

    Lee

    (0) 
    1. Former Member Post author
      Hi Lee,
      thank you for your comment.
      Documentation is always product, project and overall custom specific. I agree with you.

      If I understand you right you describe the requirement of a comprehensive process and rule documentation of the solution. I can also agree on this. My example above is of a more detailed level. The documentation you mention would need to be set up on project or even program level and involve more than business rules of certain use cases like mentioned in the example.

      Most projects I have implemented or evaluated BRF+ were custom projects to enhance or modify a standard SAP solution. It should perform a specific task within a solution rather than being the core component of a whole solution. As of now, BRF+ does not replace standard applications, but rather provide an additional layer (or a black box) on top of a solution. I think this applies to most built-in rules engines. Modeling tools for composing new applications and generating applications from models might follow different approaches.

      Eventually, I believe that manually created documentation might become obsolete but rather will be generated on demand by the solution itself.

      Best regards,
      Matthias

      (0) 
  2. Former Member
    In my experience working with business rules management system the most important, and under used, piece of analysis/documentation is an effective model of the decisions involved. Much more than the rules themselves, which are often adequately documented because the rules are easy enough to read and manage in the repository, information about the business decisions involved is critical.
    Analysts should identify the key business decisions to be automated, decompose them to determine the lower level decisions on which they are dependent and map these decisions to information about the business – especially to business metrics and objectives. This will help guide business rules development and keep it focused on automating the decisions that will make a difference to the business metrics.
    James
    (0) 
  3. Former Member
    Hi Matthias!

    I have been wondering – when I have the chance to think about BRF+.  I’m reading the comments and the blog.  I have a question, can you set BRF+ up similar to configuration where it can use a set of rules to control a programs behavior?

    Is it like a workflow?  Like BPM?  What would it do for me besides give me some great documentation, and a great way to think through problems.

    Thank you for the answers!  And I may be asking too many for a blog.  Then I’ll have to wait until Teched!

    Michelle

    (0) 
    1. Former Member
      Hi Michelle,
      While business rules conceptually control business decisions, technically speaking they are controlling the behavior of software which implements your business.

      Business rules, workflow, BPM are all very different things too.  These things all work together to implement a business, but they are all different tools.

      The main reason for using a business rules engine is to separate knowledge (rules) from processes.  This way you can maintain the rules of your business without having to constantly change everything else around the rules, such as the business processes.  I.E., every time rule A changes, the ABAP code doesn’t need to change too.

      I would read more blogs on BRF+, and read wikipedia on business rules to get a better idea.

      Cheers,
      Lee

      (0) 
    2. Former Member Post author
      Hi Michelle,
      I can recommend you browsing through Carsten Ziegler’s blogs (/people/carsten.ziegler/blog) and buying the BRF+ book. It will help you understand that technology quicker and better.
      TechEd is of course a great event, too. You can probably try to meet Carsten in person and have a little chat with him. Maybe I’ll be there, too.

      After the theoretical study I would recommend you to build some examples, which you can also find in the book and try to learn the thinking of how to design and set-up business rules.
      As Lee mentioned business rules have a specific purpose, you might want to fully understand first before getting your hands on.

      If you or your company wants then support to actually implement it and get best practices we have made by implementing many of these projects for various industries and customers, please feel free to contact me/us. Business rules will be on the critical path of your project implementation as they mostly play a central role.

      All the best,
      Matthias

      (0) 

Leave a Reply