Rules
JSON types and schemas for the five eXvisory logic rule types.

Shared types

Type
Description
String
JSON string.
Example:
"device_restart_fix"
Multiline
JSON array of Strings (used for readability of long strings).
Strings are concatenated when used, use markdown for line breaks.
Example: [ "line one\\n\\n", "line two"
]
Condition
Reference (by "_class" and "label") to test or eliminator.
For simple conditions "result" is a logic variable.
By convention the variable has the same name as the condition "label".
?var ⇒ evaluate condition (if not already evaluated)
$var ⇒ assign variable (if condition already evaluated)
Example: { "_class" : "device_restart", "label" : fix", "result" : "?fix" }
Variant condition
See Variants. As condition but "result" refers to a logic expression. The variable used in the logic expression must begin with ? and have the same name as the "label". The special empty string "result" expression "" means evaluate this variant if no other variant conditions match.
Examples:
  • { "_class" : "network", "label" : "type", "result" : "(eq ?type internet)" }
  • { "_class" : "network", "label" : "type", "result" : "" }
Expression
Legal characters: alphanumeric and ()_?$
Example: "(or (not ?http_public) (not ?https_public))"
Resources
A JSON object containing string templates used by logic rules.
Keys: alphanumeric + underscores.
Values: String or multiline, markdown and templates
Example: {
"key1" : "**resource 1** with {{ test_label }} macro", "key2" : [
"Multiline _resource 2_ ", "with {{ another_test_label }} macro ", "and [markdown link](https://exvisory.ai)" ]
}

Fault

Faults are specific diagnosable problems. Note: we also use the plural term 'faults' to refer collectively to both fault and fault group logic rules (but we'll always try to make that clear from the context).
Schema
Example
Key
Type
Description
"_class"
String
Fault class (unique across all faults and fault groups). Legal characters: alphanumeric (a-zA-Z0-9_)
Example: "device_restart_fix"
"comment"
Developer comment to describe the fault. Example: "Temporary problem fixed by restarting device"
"conditions"
Array of Conditions
JSON array of conditions.
Conditions are tests or eliminators evaluated to find or eliminate this fault (query tests ask the user questions). All conditions are evaluated and their results assigned to variables.
Example: [
{ "_class" : "device_restart", "label" : "fix", "result" : "?fix" }
]
"result"
Result of fault evaluation.
Boolean logic expression returning TRUE or FALSE.
Refers to variables assigned by evaluating "conditions".
Example: "(eq ?fix y)"
"resources"
String templates used by Fault. Valid resource keys:
  • "found" : text to be displayed if fault is FOUND (resultevaluates as TRUE). Displayed when inference is complete.
  • "eliminated" - text to be displayed if fault is ELIMINATED (result evaluates as FALSE).
At least one of "found" or "eliminated" should be present. Example: { "found" : "Unknown problem, fixed by restarting device."
}
device_restart_fix fault at https://dev.exvisory.ai/apps/sample-mobile
1
{
2
"_class" : "device_restart_fix",
3
"comment" : "Temporary problem fixed by restarting device",
4
"conditions" : [
5
{ "_class" : "device_restart", "label" : "fix", "result" : "?fix" }
6
],
7
"result" : "(eq ?fix y)",
8
"resources" : {
9
"found" : "Unknown problem, fixed by restarting device."
10
}
11
}
Copied!

Fault group

Fault groups are groups of related faults organised into a containment hierarchy. Note: we also use the plural term 'faults' to refer collectively to both fault and fault group logic rules (but we'll always try to make that clear from the context).
Schema
Example
Key
Type
Description
"_class"
String
Fault class (unique across all faults and fault groups).
Legal characters: alphanumeric (a-zA-Z0-9_)
Example: "power"
"comment"
String or Multiline
Developer comment to describe the fault group.
Example: "problem related to battery, power or charging"
"subclasses"
Array of String
Ordered array of "_class" names of sub-faults. Example: [ "battery", "charging", "power_up" ]
"resources"
String templates used by fault group.
Valid resource keys:
  • "found" - text to be displayed if a fault is FOUND within the fault group. Only used by top-level (root) fault group.
  • "eliminated" - text to be displayed if the fault group is ELIMINATED (by an eliminator logic rule).
  • "scoped" - text to be displayed if the fault group is SCOPED (by an eliminator logic rule). Displayed when inference is complete, for the last fault group to have been SCOPED, if a fault has not been FOUND.
  • "unknown" - text to be displayed if the fault group has been evaluated but is not ELIMINATED or SCOPED.
All these resource keys are optional. Example: {
"scoped" : [
"Unknown problem with device battery, power or charging"
]
}
power (fault group) at https://dev.exvisory.ai/apps/sample-mobile
1
{
2
"_class" : "power",
3
"comment" : "problem related to battery, power or charging",
4
"subclasses" : [ "battery", "charging", "power_up" ],
5
"resources" : {
6
"scoped" : [
7
"Unknown problem with device battery, power or charging"
8
]
9
}
10
}
Copied!

Eliminator

Eliminators are a special kind of test that ELIMINATE or SCOPE fault groups.
Schema
Example
Key
Type
Description
"_class"
String
Fault group class to which the eliminator applies.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"cellular_data"
"label"
String
Eliminator label (unique within fault), must be "eliminator".
Legal characters: alphanumeric (a-zA-Z0-9_)
"variant"
String
Eliminator variant (required, unique within eliminator). Legal characters: alphanumeric (a-zA-Z0-9_)
By convention "default" if only one variant.
Example:
"default"
"comment"
String or Multiline
Developer comment to describe the eliminator.
Example:
"ELIMINATED if not using mobile network"
"conditions"
Array of Conditions
JSON array of simple or variant conditions.
Eliminator conditions are tests or eliminators evaluated to ELIMINATE or SCOPE this fault "_class" (query tests ask the user questions). If the first condition is a variant condition its "result" field is a logic expression that decides which eliminator variant is to be fully evaluated. When an eliminator is fully evaluated all its conditions are evaluated and their results assigned to variables.
Example: [ { "_class" : "wireless", "label" : "eliminator", "result" : "?we" }, { "_class" : "internet", "label" : "network", "result" : "?network" } ]
"result"
Object
Eliminators evaluate to ELIMINATED, SCOPED or UNKNOWN by logically combining the variables from their conditions. This is captured by a JSON object with keys "ELIMINATED", "SCOPED" or "UNKNOWN" referring to logic expressions that refer to the condition variables. There are a limited number of key combinations:
  • <el> or <sc> = logic expressions, for example (not ?symptom)
  • "result" : undefined or {} ⇒ UNKNOWN
  • "result" : { "ELIMINATED" : "" } ⇒ ELIMINATED
  • "result" : { "SCOPED" : "" } ⇒ SCOPED
  • "result" : { "ELIMINATED": "<el>", "SCOPED": "" } ⇒ if <el> then ELIMINATED else SCOPED
  • "result" : { "ELIMINATED": "<el>", "UNKNOWN": "" } ⇒ if <el> then ELIMINATED else UNKNOWN
  • "result" : { "SCOPED": "<sl>", "UNKNOWN": "" } ⇒ if <sl> then SCOPED else UNKNOWN
  • "result" : { "ELIMINATED": "<el>", "SCOPED" : "<sl>", "UNKNOWN": "" } ⇒ if <el> then ELIMINATED else if <sl> then SCOPED else UNKNOWN
Example:
{
"ELIMINATED" : "(neq ?network mobile)", "SCOPED" : "(eq ?we SCOPED)", "UNKNOWN" : ""
}
which means"if not using mobile data network ELIMINATE this fault, otherwise if fault is scoped to parent narrow SCOPE to this fault, otherwise evaluate as UNKNOWN and continue inference".
"resources"
Resources
String templates used by eliminator.
Valid resource keys:
  • "pre_help" - text to be displayed before conditions are evaluated (but after variant condition).
  • "eliminated" - text to be displayed if result is ELIMINATED.
  • "scoped" - text to be displayed if result is SCOPED.
  • "unknown" - text to be displayed if result is UNKNOWN.
cellular_data eliminator at https://dev.exvisory.ai/apps/sample-mobile
1
{
2
"_class" : "cellular_data",
3
"label" : "eliminator",
4
"variant" : "default",
5
"comment" : "ELIMINATED if not using mobile network",
6
"conditions" : [
7
{ "_class" : "wireless", "label" : "eliminator", "result" : "?we" },
8
{ "_class" : "internet", "label" : "network", "result" : "?network" }
9
],
10
"result" : {
11
"ELIMINATED" : "(neq ?network mobile)",
12
"SCOPED" : "(eq ?we SCOPED)",
13
"UNKNOWN" : ""
14
},
15
"resources" : {
16
"eliminated" : "Fault is not with mobile network - using {{internet_network_usr}} network."
17
}
18
}
Copied!

Query test

Query tests ask end users questions in order to troubleshoot a problem.
Schema
Example
Key
Type
Description
"_class"
String
Fault (or fault group) class to which this test belongs. Assign tests to logically related faults (for legibility).
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"internet"
"label"
String
Test label ("<_class> <label> <variant>" must be unique). Tests are generally referred to as <_class> <label> so choose descriptive labels for legibility.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"network"
"variant"
String
Test variant (unique within test)
Optional: only include if your test has multiple variants.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
See Variants.
"comment"
String or Multiline
Developer comment to describe the test.
Example:
"ELIMINATED if not using mobile network"
"conditions"
Array of Conditions
JSON array of simple or variant conditions.
Test conditions are tests to evaluate before evaluating this query test. If the first condition is a variant condition its "result" field is a logic expression that decides which test variant is to be fully evaluated. When a test is fully evaluated all its "conditions" are evaluated and their results assigned to variables.
Note: query tests do not have a "results" key that refers to condition variables, but conditions can still be used for enforcing dependencies between tests, i.e. making sure that other tests have been evaluated before this test. This might be required if test "resources" use template macros to refer to other test results.
Example:
See Synthetic test example.
"_values"
Array of String
Defines query type and returned values:
  • undefined ⇒ free-text input (cannot be referred to in logic expressions)
  • [ "default value" ] ⇒ free-text input with default value
  • [ "y", "n" ] ⇒ boolean input (can be used in boolean logic expressions)
  • [ “cat”, “dog”, “budgie” ] ⇒ multiple choice input (can be used in non-boolean logic expressions)
Example:
[ "wifi", "mobile", "bluetooth", "usb" ]
"retry"
Logic expression that refers to query test input.
If expression evaluates to TRUE this query test is added to a list of tests to possibly retry after inference completes. The query test input is available in the variable ?result and the retry list is stored in a special exvisory_retries fact. This feature only works in our web chatbots.
Example:
"halt"
Logic expression that can refer to query test input and "conditions" variables. If expressions evaluates to TRUE inference then inference halts.
Example:
"resources"
Resources
String templates used by query test.
Valid resource keys:
  • "pre_help" - text to be displayed before "conditions" are evaluated (but after variant condition).
  • "help" - text to be displayed after "conditions" are evaluated but before query prompt (typically to help the user answer the query).
  • "prompt" - question prompt.
  • "y" or "n" - override default "Yes" or "No" user-visible choices for boolean query test.
  • "cat", "dog", "budgie" - user-visible choices for multiple choice query test (see "_values"). If omitted or set to empty string the choice is not displayed.
  • "result" - text to display after test evaluates.
  • "usr" - text to override class_label_usr fact.
See Query test example tab.
internet network (query test) at https://dev.exvisory.ai/apps/sample-mobile
1
{
2
"_class" : "internet",
3
"label" : "network",
4
"comment" : [
5
"identify network in use { wifi | mobile | bluetooth | usb }"
6
],
7
"_values" : [ "wifi", "mobile", "bluetooth", "usb" ],
8
"resources" : {
9
"bluetooth" : "-Bluetooth (tethering to another device)",
10
"help" : [
11
"It's not always obvious which network you are using to connect ",
12
"to the Internet. I'm talking about whether you are using WiFi or ",
13
"mobile/cellular data (if you are using Bluetooth or USB tethering I'm sure ",
14
"you know that). If not sure see:\\n\\n",
15
"{% if device_os == 'ios' %}",
16
"- [Status icons and symbols on your iPhone](https://support.apple.com/HT207354)\\n",
17
"- [About Wi-Fi Assist](https://support.apple.com/HT205296)\\n",
18
"{% elseif device_os == 'android' %}",
19
"- [Android Signal Icon Meanings](https://www.technipages.com/android-signal-icon-meanings) on your device status bar\\n",
20
"- [How do I know if I'm on WiFi or using data plan?](https://community.verizonwireless.com/thread/915359)\\n",
21
"{% elseif device_os == 'windows' %}",
22
"- [How can I tell whether I'm getting data via Wi-Fi or phone network?](https://windowsphone.stackexchange.com/questions/425/how-can-i-tell-whether-im-getting-data-via-wi-fi-or-phone-network)\\n",
23
"{% endif %}"
24
],
25
"mobile" : "Mobile (cellular) data",
26
"prompt" : "Which network are you using to connect to the Internet?",
27
"usb" : "-USB (tethering to another device)",
28
"wifi" : "WiFi"
29
}
30
}
31
Copied!

Synthetic test

Synthetic tests are tests that logically combine the results of other tests (to group tests or deduce intermediate conclusions useful to the fault diagnostic process).
Schema
Example
Key
Type
Description
"_class"
String
Fault (or fault group) class to which this test belongs. Assign tests to logically related faults (for legibility).
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"browser"
"label"
String
Test label ("<_class> <label> <variant>" must be unique). Tests are generally referred to as <_class> <label> so choose descriptive labels for legibility.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"activity"
"variant"
String
Test variant (unique within test)
Optional: only include if your test has multiple variants.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
See Variants.
"comment"
String or Multiline
Developer comment to describe the test.
Example:
"TRUE if browser can open HTTP or HTTPS web sites"
"conditions"
Array of Conditions
JSON array of simple or variant conditions.
Test conditions are tests to evaluate before evaluating this query test. If the first condition is a variant condition its "result" field is a logic expression that decides which test variant is to be fully evaluated. When a test is fully evaluated all its "conditions" are evaluated and their results assigned to variables.
Note: conditions are fundamentally used for enforcing dependencies between tests, i.e. making sure that other tests have been evaluated before this test. This might be required if test "resources" use template macros to refer to other test results.
Example:
[
{ "_class" : "browser", "label" : "https_public", "result" : "?https_public" },
{ "_class" : "browser", "label" : "http_public", "result" : "?http_public" }
]
"halt"
Logic expression that can refers to test "result" and "conditions" variables. If expressions evaluates to TRUE inference then inference halts.
Example:
"result"
Logic expression determining the result of this test.
Possible results (see Expressions):
  • Text or multiple choice literal, e.g. "phone"
  • Boolean literal, e.g. "TRUE" or "FALSE"
  • Logic expression referring to "conditions" variables, e.g. "(or ?http_public ?https_public)"
  • Resource expression referring to "resources", e.g. "x_test_device_which_make_model"
"resources"
Resources
String templates used by synthetic test.
Valid resource keys:
  • "pre_help" - text to be displayed before "conditions" are evaluated (but after variant condition).
  • "help" - text to be displayed after "conditions" are evaluated.
  • "result" - text to display after test evaluates.
  • "usr" - text to override class_label_usr fact.
See Synthetic test example tab.
browser activity (synthetic test) at https://dev.exvisory.ai/apps/sample-mobile
1
{
2
"_class" : "browser",
3
"label" : "activity",
4
"comment" : "TRUE if browser can open HTTP or HTTPS web sites",
5
"conditions" : [
6
{ "_class" : "browser", "label" : "https_public", "result" : "?https_public" },
7
{ "_class" : "browser", "label" : "http_public", "result" : "?http_public" }
8
],
9
"result" : "(or ?http_public ?https_public)",
10
"resources" : {
11
"pre_help" : [
12
"There are two kinds of web sites: most are SECURE, some are OPEN. ",
13
"You can [tell the difference](https://support.google.com/chrome/answer/95617) ",
14
"by looking at the browser address bar. ",
15
"SECURE web sites show a padlock icon beside the web address and the ",
16
"web address begins with a `https://` prefix (you might need to select ",
17
"the web address to reveal the prefix). OPEN web sites don't ",
18
"have the padlock icon and begin with `http://`. ",
19
"Let's see if your mobile device can browse to both kinds of web site."
20
],
21
"result" : [
22
"{% if browser_http_public and not browser_https_public %}",
23
"Being able to browse an OPEN (http) web site but not a SECURED (https) ",
24
"web site sounds like a browser problem.",
25
"{% elseif browser_https_public and not browser_http_public %}",
26
"Being able to browse a SECURED (https) web site but not an OPEN (http) ",
27
"web site sounds like a browser problem.",
28
"{% endif %}"
29
]
30
}
31
}
32
Copied!
Last modified 2yr ago