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).
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.
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"
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"
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.
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 (
resultevaluates 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"
Fault class (unique across all faults and fault groups).
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"power"
"comment"
Developer comment to describe the fault group.
Example:
"problem related to battery, power or charging"
"subclasses"
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.
- "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
Schema
Example
Key
Type
Description
"_class"
Fault group class to which the eliminator applies.
Legal characters: alphanumeric (a-zA-Z0-9_)
Example:
"cellular_data"
"label"
Eliminator label (unique within fault), must be "eliminator".
Legal characters: alphanumeric (a-zA-Z0-9_)
"variant"
Eliminator variant (required, unique within eliminator).
Legal characters: alphanumeric (a-zA-Z0-9_)
By convention "default" if only one variant.
Example:
"default"
"comment"
Developer comment to describe the eliminator.
Example:
"ELIMINATED if not using mobile network"
"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"
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
Schema
Example
Key
Type
Description
"_class"
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"
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"
"comment"
Developer comment to describe the test.
Example:
"ELIMINATED if not using mobile network"
"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:
"_values"
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:
- (eq ?result skip)
"halt"
Logic expression that can refer to query test input and "conditions" variables. If expressions evaluates to TRUE inference then inference halts.
Example:
- "(and (eq ?result direct) (eq ?subsymptom conn_internet))" is used in the device access query test at https://dev.exvisory.ai/apps/sample-mobile to halt inference after a contradictory response.
"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.
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"
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"
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"
"comment"
Developer comment to describe the test.
Example:
"TRUE if browser can open HTTP or HTTPS web sites"
"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:
- "(and (eq ?result direct) (eq ?subsymptom conn_internet))" is used in the device access query test at https://dev.exvisory.ai/apps/sample-mobile to halt inference after a contradictory response.
"result"
Logic expression determining the result of this test.
- 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"
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.
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
Copy link