This discussion is archived
5 Replies Latest reply: Aug 28, 2012 4:43 PM by Davin Fifield RSS

Design Documentation

957275 Newbie
Currently Being Moderated
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?

Thanks!
Jim
  • 1. Re: Design Documentation
    Peter Still Newbie
    Currently Being Moderated
    Jim,

    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.

    Best,
    Peter Still
  • 2. Re: Design Documentation
    Davin Fifield Journeyer
    Currently Being Moderated
    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.

    Davin.
  • 3. Re: Design Documentation
    Jasmine Lee Expert
    Currently Being Moderated
    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

    Cheers,
    Jasmine
  • 4. Re: Design Documentation
    957275 Newbie
    Currently Being Moderated
    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 Journeyer
    Currently Being Moderated
    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.

    Davin.

Legend

  • Correct Answers - 10 points
  • Helpful Answers - 5 points