Home / PolicyModels Tutorial

Hello? World?

So far, we’ve put values into slots without asking the user for any information. That is, of course, not the common case. When we need to ask a user, PolicyModels offers the ask node:

[ask:
  {text: How friendly do you feel today?}
  {answers:
    {Not at all: [set: Greeting=ignore] }
    {Somewhat: [set: Greeting=hi] }
    {Quite so: [set: Greeting=hello] }
    {Borderline overly : [set: Greeting=_hug_] }
  }
]
[set: Subject += world]

The parts between { and } in the above ask node are sub-nodes - they can only live within other nodes, and are used to create their structure. This ask node has a text sub-node, which has the text for the question, an answers sub-node, containing the possible answers. Each of answers’ sub-nodes contain the answer text, and a list of top-level nodes (a single set node, in this case).

The the questionnaire runtime traverses an ask node as follows:

1. Gets to the ask node.
2. Waits until an answer is selected
3. Traverses the node list of the selected answer
4. If the traversal was not terminated (i.e. no end or reject nodes were encountered), continues to the node after said ask node.

Visualization for the above decision graph (\visualize-dg)

Note

Separating the answer text from its implementation (i.e. its list of nodes) allows for a separation between what answers the users see, and how the questionnaire handles their answers. You can ask the users in terms they understand, and process the answers in term that are convenient for you.

Run the questionnaire (here are the files for the tag space and the decision graph). The CLiRunner compiles the questionnaire, prompts the user with the question, and then sets the greeting according to her current friendliness.

# Run Started
How friendly do you feel today?
Possible Answers:
- Not at all
- Somewhat
- Quite so
- Borderline overly
answer (? for help): Somewhat
# Updating tags
# DataTags/Greeting = hi
# Updating tags
# DataTags/Subject = world

~~~~~~~~~~
Final Tags
~~~~~~~~~~
DataTags/Greeting = hi
DataTags/Subject = world

Terms

Real-world questions are likely to contain unfamiliar terms, especially when the questions are about legal matters, and the intended audience have had little or no legal training. To clarify terms that appear in a question’s {text:}, PolicyModels offers the {terms} sub-node.

[ask:
  {text: How friendly do you feel today?}
  {terms:
    {you: The person taking this interview. }
    {today: The day this interview is taking place.
            If you started this interview yesterday,
            please provide answers that reflect your mood
            at the time the interview started. }
  }
  {answers:
    {Not at all: [set: Greeting=ignore] }
    {Somewhat: [set: Greeting=hi] }
    {Quite so: [set: Greeting=hello] }
    {Borderline overly : [set: Greeting=_hug_] }
  }
]

The terms are displayed to the user along with the question’s text.

The terms, as displayed by CLiRunner

DataTaggingServer showing a question mentioning Business Associate and Covered Entity, as defined under HIPAA.

Yes/No Special Case

While working on PolicyModels, we found a repeating interview pattern: The user is asked a yes/no question. On one option (typically a “yes”), the interview goes through a serious of questions before proceeding to the node pointed by the other option (typically, a “no”). To naturally support this, if an ask node contains only a single “yes” or “no” answer, the other answer is implied, and leads to the next node following that ask node.

In the below decision graph, the user may decide to greet other subjects.

[ask:
  {text: How friendly do you feel today?}
  {answers:
    {Not at all: [set: Greeting=ignore] }
    {Somewhat: [set: Greeting=hi] }
    {Quite so: [set: Greeting=hello] }
    {Borderline overly : [set: Greeting=_hug_] }
  }
]
[set: Subject += world]
[ask:
  {text: You are greeting the world. Would you like to greet other objects? }
  {answers:
    {yes:
      [ask:
        {text: How about the moon?}
        {answers:
          {yes: [set: Subject += moon]}}]
      [ask:
        {text: Greet a planet?}
        {answers:
          {yes: [set: Subject += planet]}}]
      [ask:
        {text: Do you need to recognize what you greet?}
        {answers:
          {no: [set: Subject += unrecognizedOrbitingObject]}}]
    }
  }
]

The above code, visualized. Implied edges are pointed by arrows.

Empty Answers

If there’s an answer that requiers no action, you can leave the decision graph part of the answer empty, like so:

[ask
  {text: What do you want to do?}
  {answers:
    {nothing: }
    {something: [...]}
    {something else: [...]}
  }
]

Now that you’ve learned to ask questions and set slot values according to the user’s choices, you can start writing questionnaires! But you your training is not complete; there are more nodes to be discovered. First, however, we need to learn about node ids.