Advisor library

The Advisor library makes it easy to create data gathering solutions that involve human evaluation. It is based on the criterion concept from version 1 of Advisor.

During an assessment, a user is presented with a series of questions, each one of which can require a textual response and/or the selection of a single grade from a list. This is an effective way of gathering both subjective and objective opinions from users.

Libraries

The library.advisor library contains metadata to support assessment. It contains the following types:

  • Advisor Library - library used to contain a set of questions etc.
  • Advisor Library Prototype - can be inherited by an instance of Advisor Library to provide standard metadata.
  • Criterion - a question
  • Criterion Group - a group of questions or a questionnaire
  • Criterion With Derivation Scripts - a question with derivation logic. Used for Name (library.advisor.AssetName).
  • Finding - a recommendation or other inference.
  • Grade - one of a group of possible grades for a question
  • Rule - recipe for deriving a finding from grades and other findings

The general idea is to create an instance of Advisor Library which inherits from Advisor Library Prototype, and then use this to create the criteria, criterion groups, findings, grades and rules required for an assessment solution.

Criteria and Criterion Groups

To support assessments, Advisor provides the following types:

  • library.advisor.CriterionType - this defines a criterion, which is used to create a question. During derivation the criterion is elaborated with metadata to allow it to be used as a member type.
  • library.advisor.CriterionGroupType - this is a container for a group of criteria. During derivation the criterion group is elaborated with metadata to allow it to be used as a type, including the creation of tabs and calculation of member type scales to represent importance weightings for the criteria.

Criterion groups can contain any member types, not just criteria.

Within criterion groups, member type library.advisor.CriterionList works like system.MEMBER_TYPE list, but if it encounters any items with targets of type library.advisor.CriterionGroupType, then these are treated as "groups".

The members of the group are copied into the member type list in place of the group, with hierarchically arranged sequence numbers and hierarchically proportioned scales, calculated as a percentage. Any group which contains members is considered a tab.

For example, if type A contains:

  • Group A, scale 3
  • Group B, scale 2

Group A contains:

  • Member Type A1, scale 1
  • Member Type A2, scale 2

Group B contains:

  • Member Type B1, scale 0
  • Member Type B2, scale 1
  • Member Type B3, scale 1

Then the resultant tabs will be:

Value
1/Group A
2/Group B

And the resultant member types will be:

ValueScaleTarget
1/1 20 Member Type A1
1/2 30 Member Type A2
2/1 0 Member Type B1
2/2 20 Member Type B2
2/3 20 Member Type B3

There do not have to be a consistent set of groups. For example, if the type Type A contains:

  • Member Type 1, scale 5
  • Group X, scale 2
  • Member Type 2, scale 3

And Group X contains

  • Member Type Xa, scale 4
  • Member Type Xb, scale 6

Then the resultant tabs will be:

Value
/TypeA
2/Group X

And the resultant member types will be:

ValueScaleTarget
1 50 Member Type 1
2/2.1 8 Member Type Xa
2/2.1 12 Member Type Xb
3 30 Member Type 2

If the display properties Show and Show Edit are both set to false for a member, a sequence number will not be generated for the member.

Grades

When used as member types, criteria may present a set of grades to the user from which they pick one. The type library.advisor.GradeType can be used for this.

Each grade is represented by a node. The selection of the node is simply the selection of a target

Grades are independent of criteria.

Findings

The Findings List member type (library.advisor.FindingList) holds a list of grades, inferences and recommendations pertinent to a node. The target of each member points to a grade or a finding node, which describes what has been found. The value holds the associated response.

Findings are managed in a number of ways:

  • They are derived from criterion gradings.
  • They may be entered in other ways from other member types.
  • They are inferred using rules.
  • They may be removed using some form of filter.

The type library.advisor.FindingType can be used to set a finding. This provides a name and a description (just like a grade), but also sets a priority for the finding and a priority adjustment list. These are explained in the recommendation section below.

Rules

Rules allow relationships between grades and findings to be declared.

The basic idea of a rule is to combine a set of grades and findings into a logical condition, which, if true, sets another set of findings to true.

Specifically, each rule contains:

  • One or more rule findings, i.e. what will be set to true if the rule evaluates to true.
  • A condition. This is expressed in LISP-like syntax using symbols of the user's choosing, and (and ..), (or ..) and (not ..) constructs.

    Rules use a very compact syntax to describe under what conditions the rule must fire.

    The simplest rule is a single condition, such as:

    (foo)

    The reference foo must match a name in the rule bindings section. If the assessed node uses the bound node as a grade, or has already inferred it as a finding, then the condition is considered true.

    Combining multiple conditions

    If the rule should be fired only when two or more conditions are satisfied, simply code them one after another.

    (foo)
    (bar)

    Alternatively, enclose them in an (and ..) sequence:

    (and
      (foo)
      (bar)
    )

    The line breaks and indents are not significant, but can be added for clarity.

    If the rule should fire when any of two or more conditions are satisifed, enclose them in an (or ..) sequence.

    (or
      (foo)
      (bar)
    )

    If the rule should fire when another condition is not true, use not:

    (not
      (foo)
    )

    The conditions can be combined:

    (or
      (foo)
      (and
        (bar)
        (not
          (fee)
        )
      )
    )

    This means "foo or (bar and not fee)".

    Notes

    You do not need an (and ..) at the top-level. You can think of the top level as having an implicit (and ..) around it.

    Remember that every reference in the conditions must match a name in the binding list.

    If you require any grade except one, it is better to list all the permissible grades with an (or ..), rather than use a (not ..). This ensures that if the question is not answered the rule does not fire, and also provides better traceability for the reason processing in the recommendation (see below).

  • Rule bindings. These relate the symbols used in the condition with grades and other findings.
  • Salience. This is a priority under which the rule should fire, in which higher salience means fire first. Generally this can be left to default to 0, and the underlying rules engine will determine the priority. In some cases it can be useful to set it, for example setting a rule with a (not ..) condition that references another finding to lower than the rule that sets the finding.

Rules are defined independently of criterion groups and criteria, but are then be attached to criterion groups and criteria (using the Rule List member type), so that the rules pertinent to a criterion group can be collated.

Criterion groups derive two member types from the rules that they and their members contain:

  • library.advisor.RuleListText - generated text of the rules, in the format required by the RunRules service.
  • library.advisor.FindingPredicates - for each finding, a list of grades and findings that directly or indirectly trigger the rule. This is generated in JavaScript object notation (JSON) and is used by the Recommendations member type to calculate the reason for the recommendation.

For rules to run, the criterion group must contain the library.advisor.RunRules member type. This must appear before the library.advisor.Recommendations member type. Run Rules has display properties Show and Show Edit both set to false, and does not appear on the page.

Recommendations

The output of the rule processing is simply some additional findings on the findings list. The member type Recommendations converts a finding list to a series of actionable recommendations.

The recommendations is based on the finding list, but with the following changes:

  • All findings on the finding list with no priority set, or a priority of 0, are removed. This removes all grades.
  • A priority for each recommendations is calculated. This is based on the priority of the associated finding node. This is adjusted using the priority adjustment, which lists findings which can be used to adjust the priority up or down. For example, if it provides an adjustment of -1 for the finding somecompany.loans.badCredit, it means "make the recommendation 1 step more important (lower priority number) if the finding somecompany.loans.badCredit is set".
  • A reason for each recommendation is calculated. This is derived by finding the response text associated with all the grades that triggered the rule. This therefore provides, in the user's own words, a justification for the recommendation.

The recommendations member type has an extension script which formats the recommendations in a block.