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

See Expressions.

Legal characters: alphanumeric and ()_?$

Example: "(or (not ?http_public) (not ?https_public))"

Resources

See 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
Schema

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"

String or Multiline

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"

Expression

Result of fault evaluation.

Boolean logic expression returning TRUE or FALSE.

Refers to variables assigned by evaluating "conditions".

Example: "(eq ?fix y)"

"resources"

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."

}

Example
device_restart_fix fault at https://dev.exvisory.ai/apps/sample-mobile
{
"_class" : "device_restart_fix",
"comment" : "Temporary problem fixed by restarting device",
"conditions" : [
{ "_class" : "device_restart", "label" : "fix", "result" : "?fix" }
],
"result" : "(eq ?fix y)",
"resources" : {
"found" : "Unknown problem, fixed by restarting device."
}
}

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
Schema

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"

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"

]

}

Example
power (fault group) at https://dev.exvisory.ai/apps/sample-mobile
{
"_class" : "power",
"comment" : "problem related to battery, power or charging",
"subclasses" : [ "battery", "charging", "power_up" ],
"resources" : {
"scoped" : [
"Unknown problem with device battery, power or charging"
]
}
}

Eliminator

Eliminators are a special kind of test that ELIMINATE or SCOPE fault groups.

Schema
Example
Schema

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.

Example
cellular_data eliminator at https://dev.exvisory.ai/apps/sample-mobile
{
"_class" : "cellular_data",
"label" : "eliminator",
"variant" : "default",
"comment" : "ELIMINATED if not using mobile network",
"conditions" : [
{ "_class" : "wireless", "label" : "eliminator", "result" : "?we" },
{ "_class" : "internet", "label" : "network", "result" : "?network" }
],
"result" : {
"ELIMINATED" : "(neq ?network mobile)",
"SCOPED" : "(eq ?we SCOPED)",
"UNKNOWN" : ""
},
"resources" : {
"eliminated" : "Fault is not with mobile network - using {{internet_network_usr}} network."
}
}

Query test

Query tests ask end users questions in order to troubleshoot a problem.

Schema
Example
Schema

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"

Expression

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"

Expression

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.

Example
internet network (query test) at https://dev.exvisory.ai/apps/sample-mobile
{
"_class" : "internet",
"label" : "network",
"comment" : [
"identify network in use { wifi | mobile | bluetooth | usb }"
],
"_values" : [ "wifi", "mobile", "bluetooth", "usb" ],
"resources" : {
"bluetooth" : "-Bluetooth (tethering to another device)",
"help" : [
"It's not always obvious which network you are using to connect ",
"to the Internet. I'm talking about whether you are using WiFi or ",
"mobile/cellular data (if you are using Bluetooth or USB tethering I'm sure ",
"you know that). If not sure see:\\n\\n",
"{% if device_os == 'ios' %}",
"- [Status icons and symbols on your iPhone](https://support.apple.com/HT207354)\\n",
"- [About Wi-Fi Assist](https://support.apple.com/HT205296)\\n",
"{% elseif device_os == 'android' %}",
"- [Android Signal Icon Meanings](https://www.technipages.com/android-signal-icon-meanings) on your device status bar\\n",
"- [How do I know if I'm on WiFi or using data plan?](https://community.verizonwireless.com/thread/915359)\\n",
"{% elseif device_os == 'windows' %}",
"- [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",
"{% endif %}"
],
"mobile" : "Mobile (cellular) data",
"prompt" : "Which network are you using to connect to the Internet?",
"usb" : "-USB (tethering to another device)",
"wifi" : "WiFi"
}
}

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
Schema

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"

Expression

Logic expression that can refers to test "result" and "conditions" variables. If expressions evaluates to TRUE inference then inference halts.

Example:

"result"

Expression

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.

Example
browser activity (synthetic test) at https://dev.exvisory.ai/apps/sample-mobile
{
"_class" : "browser",
"label" : "activity",
"comment" : "TRUE if browser can open HTTP or HTTPS web sites",
"conditions" : [
{ "_class" : "browser", "label" : "https_public", "result" : "?https_public" },
{ "_class" : "browser", "label" : "http_public", "result" : "?http_public" }
],
"result" : "(or ?http_public ?https_public)",
"resources" : {
"pre_help" : [
"There are two kinds of web sites: most are SECURE, some are OPEN. ",
"You can [tell the difference](https://support.google.com/chrome/answer/95617) ",
"by looking at the browser address bar. ",
"SECURE web sites show a padlock icon beside the web address and the ",
"web address begins with a `https://` prefix (you might need to select ",
"the web address to reveal the prefix). OPEN web sites don't ",
"have the padlock icon and begin with `http://`. ",
"Let's see if your mobile device can browse to both kinds of web site."
],
"result" : [
"{% if browser_http_public and not browser_https_public %}",
"Being able to browse an OPEN (http) web site but not a SECURED (https) ",
"web site sounds like a browser problem.",
"{% elseif browser_https_public and not browser_http_public %}",
"Being able to browse a SECURED (https) web site but not an OPEN (http) ",
"web site sounds like a browser problem.",
"{% endif %}"
]
}
}