5 Replies Latest reply: Aug 28, 2012 6:43 PM by Davin Fifield-Oracle RSS

    Design Documentation

      Has anyone defined best practices around design documentation for OPA Rules? Specifically, what is the best approach for reviewing rules in detailed design JADs if the audience is a mix of business and technical folks?

      We are currently considering two options but both have strong drawbacks:
      1) Write pseudo OPA rules - Drawbacks: complex rules are difficult for JAD participants to understand. also, this approach doesn't poke holes in policy as well as #2
      2) Using UML activity diagrams or decision trees that visually describe the decision - Drawbacks: during development it is difficult to write OPA rules based on decision trees.

      Would appreciate it if anyone could share their experience. Bottom line - what document do you look at while you write your rules?

        • 1. Re: Design Documentation
          Peter Still-Oracle

          The answer depends a lot on the source material you are using for your project.

          Are the rules based on existing legislation, regulations, a policy manual etc.? If so, the best practice is to use this material as the starting point for the documentation. Adding too many intermediate transformative steps can increase effort and reduce the mapping from source material to the natural language/tabular OPA rules.

          The answer may be different if the rules have not previously been documented.

          Peter Still
          • 2. Re: Design Documentation
            Davin Fifield-Oracle
            One approach some customers use is to use the same logical structure that OPA uses to define the rules in a visual tree form. This is not a decision tree (where the decsions are at the leaves), rather it is the same top-down "this decision is reached if..." structure, where for each node the children are connected with either "and"s or "or"s. These forms then translate easily into the actual rule documents, and it has the advantage of "poking holes" just as effectively as it would if you were actually modeling the rules in OPA.

            Another approach that works well is to co-develop the rules in a more agile fashion with the policy expert and rule author working side-by-side. Then there is no intermediate step.
            In this case, it's also easier to capture test cases with expected results as you go.

            • 3. Re: Design Documentation
              Jasmine Lee-Oracle
              Hi Jim,

              If you're thinking about design, here are two documents you may want to peruse:

              Guide to Designing a Policy Model: http://www.oracle.com/technetwork/apps-tech/policy-automation/learnmore/opaguidetodesigningapolicymodel-1531936.pdf

              Best Practice Guide for Rule Developers: http://www.oracle.com/technetwork/apps-tech/policy-automation/learnmore/opaguidetodesigningapolicymodel-1531936.pdf

              • 4. Re: Design Documentation
                Thanks very much for all the responses!

                Davin, your suggestion is of particular interest to us. Do you have an example of this? We are specifically wondering how ANDs and ORs are represented (do you just label the lines)?

                Thanks again!
                • 5. Re: Design Documentation
                  Davin Fifield-Oracle
                  One that I'm thinking of uses "if" on the line directly below the decision node, then puts either "and" or "or" simply as separate text floating half-way between each pair of sibling nodes.

                  To mirror OPA, for each set of siblings make sure to use either ANDs or ORs, not a combination of both.