JSONLogic Icon Conditionals Documentation

For Cloneable Cloud Platform Data Object Builder

Table of Contents

1. Overview

2. How It Works

3. Field Naming and References

4. JSONLogic Syntax

5. Common Operators

6. Practical Examples

7. Best Practices

8. Troubleshooting

---

Overview

The Cloneable Cloud Platform uses JSONLogic to create conditional icons for data objects. This allows icons to dynamically change based on the values of fields within a data object. For example, a utility pole icon can change from red to green when marked as "complete".

Key Components:

• Icon Customizer: UI interface in the data object builder form

• JSONLogic Engine: Evaluates conditional expressions

• Icon Evaluator: Determines which icon to display based on conditions

---

How It Works

1. Multiple Icons: You can define multiple icons for a single data object template

2. Conditional Evaluation: Each icon can have a JSONLogic conditional expression

3. Priority Order: Icons are evaluated in order from top to bottom

4. Default Fallback: Icons with empty conditionals ({}) serve as defaults

Evaluation Flow:

Data Object Fields → JSONLogic Evaluation → Icon Selection → Display

---

Field Naming and References

CRITICAL: Field Name Mapping

When referencing fields in JSONLogic conditionals, you must use the exact field name as defined in your data object template.

Examples:

Field Display Name	Field Name (use this)	JSONLogic Reference
Is Complete	is_complete	{"var":"is_complete"}
Done	done	{"var":"done"}
Status	status	{"var":"status"}
Priority Level	priority_level	{"var":"priority_level"}
Inspection Date	inspection_date	{"var":"inspection_date"}

Important: The field name is typically the lowercase, underscore-separated version of the display name, but always verify the actual field name in your data object template.

Field Value Types

Fields in data objects are stored as strings by default:

• Boolean fields: stored as "true" or "false" (strings)

• Numbers: stored as "5", "10.5" (strings)

• Complex JSON: stored as stringified JSON and automatically parsed

---

JSONLogic Syntax

JSONLogic uses JSON objects to represent logical expressions. Every operator is a key in a JSON object.

Basic Structure:

{"operator": [arguments]}

---

Common Operators

1. Variable Access (var)

Retrieves a field value from the data object.

{"var": "field_name"}

2. Equality (==)

Checks if values are equal.

{"==": [{"var": "status"}, "complete"]}

3. Inequality (!=)

Checks if values are not equal.

{"!=": [{"var": "status"}, "pending"]}

4. Logical AND (and)

All conditions must be true.

{"and": [
  {"==": [{"var": "done"}, "true"]},
  {"!=": [{"var": "error"}, "true"]}
]}

5. Logical OR (or)

At least one condition must be true.

{"or": [
  {"==": [{"var": "priority"}, "high"]},
  {"==": [{"var": "priority"}, "critical"]}
]}

6. Logical NOT (!)

Negates a condition.

{"!": {"==": [{"var": "active"}, "true"]}}

7. Comparison Operators

• Greater than: {">": [{"var": "count"}, "5"]}

• Less than: {"<": [{"var": "count"}, "10"]}

• Greater or equal: {">=": [{"var": "score"}, "80"]}

• Less or equal: {"<=": [{"var": "score"}, "100"]}

8. In Array (in)

Checks if a value is in an array.

{"in": [{"var": "status"}, ["complete", "approved", "verified"]]}

9. If-Then-Else (if)

Conditional branching (rarely needed for icon conditionals).

{"if": [
  {"==": [{"var": "priority"}, "high"]},
  "red",
  "green"
]}

---

Practical Examples

Example 1: Simple Completion Status

Scenario: Show green icon when "Is Complete" field is true

Field Setup:

• Field Name: is_complete

• Field Type: Checkbox/Boolean

Conditional:

{"==": [{"var": "is_complete"}, "true"]}

Example 2: Multiple Status Values

Scenario: Show success icon for any completed state

Field Setup:

• Field Name: status

• Field Type: Select/Text

Conditional:

{"in": [{"var": "status"}, ["complete", "approved", "finished"]]}

Example 3: Combined Conditions

Scenario: Show warning icon when inspection is done but has errors

Field Setup:

• Field Name 1: inspection_done

• Field Name 2: has_errors

Conditional:

{"and": [
  {"==": [{"var": "inspection_done"}, "true"]},
  {"==": [{"var": "has_errors"}, "true"]}
]}

Example 4: Priority-Based Icons

Scenario: Different icons based on priority levels

Icon 1 - Critical (Red):

{"==": [{"var": "priority"}, "critical"]}

Icon 2 - High (Orange):

{"==": [{"var": "priority"}, "high"]}

Icon 3 - Normal (Green):

{"==": [{"var": "priority"}, "normal"]}

Icon 4 - Default (Gray):

{}

Example 5: Null Check with Completion

Scenario: Show complete icon only when field exists and is true

Conditional:

{"and": [
  {"!=": [{"var": "done"}, null]},
  {"==": [{"var": "done"}, "true"]}
]}

Example 6: Numeric Comparisons

Scenario: Show different icons based on inspection score

High Score (>= 90):

{">=": [{"var": "inspection_score"}, "90"]}

Medium Score (50-89):

{"and": [
  {">=": [{"var": "inspection_score"}, "50"]},
  {"<": [{"var": "inspection_score"}, "90"]}
]}

Low Score (< 50):

{"<": [{"var": "inspection_score"}, "50"]}

---

Best Practices

1. Icon Order Matters

• Place specific conditions first

• Put default icons (empty conditional {}) last

• Icons are evaluated top to bottom

2. Field Name Verification

• Always verify the exact field name in your template

• Use underscores for multi-word fields (e.g., is_complete, not Is Complete)

• Field names are case-sensitive

3. String Values

• Remember that most field values are stored as strings

• Boolean: use "true" and "false" (not true/false)

• Numbers: use string format "5" for comparisons

4. Default Icons

• Always include at least one default icon with empty conditional {}

• This ensures an icon always displays

5. Testing

• Test your conditionals with different data values

• Use the preview feature in the Icon Customizer

• Check the browser console for any JSONLogic errors

---

Troubleshooting

Common Issues and Solutions

Issue 1: Icon Not Changing

Cause: Field name mismatch Solution: Verify exact field name in template (use underscores, lowercase)

Issue 2: Invalid JSON Error

Cause: Malformed JSON syntax Solution: Validate JSON using a JSON validator, check for missing quotes/brackets

Issue 3: Always Shows Default Icon

Cause: Conditional never evaluates to true Solution: Check field values are strings ("true" not true)

Issue 4: No Icon Displays

Cause: No default icon defined Solution: Add an icon with empty conditional {} as fallback

Debug Tips

1. Check Field Values:

   • Inspect actual stored values in the data object

   • Remember values are typically strings

2. Validate JSON:

   • Use online JSON validators

   • Ensure proper quote usage

3. Test Incrementally:

   • Start with simple conditions

   • Add complexity gradually

4. Console Logging:

   • Browser console will show JSONLogic evaluation errors

   • Look for "Failed to parse or evaluate icon conditional" messages

---

Advanced Examples

Utility Industry Specific

Pole Inspection Status

{
  "and": [
    {"==": [{"var": "inspection_type"}, "pole"]},
    {"==": [{"var": "inspection_complete"}, "true"]},
    {"!": {"var": "requires_maintenance"}}
  ]
}

Span Measurement Alerts

{
  "or": [
    {">": [{"var": "sag_measurement"}, "15"]},
    {"<": [{"var": "clearance_height"}, "18"]}
  ]
}

Work Order Priority

{
  "and": [
    {"in": [{"var": "work_type"}, ["emergency", "safety"]]},
    {"==": [{"var": "assigned"}, "true"]}
  ]
}

---

Reference Links

• JSONLogic Documentation: https://jsonlogic.com/

• JSONLogic Playground: https://jsonlogic.com/play.html

---

Summary

The JSONLogic icon conditional system provides powerful, flexible icon management for data objects. By understanding field naming conventions and JSONLogic syntax, you can create dynamic visual indicators that enhance data visualization and workflow management in the Cloneable Cloud Platform.

Remember:

1. Use exact field names (typically lowercase with underscores)

2. Field values are usually strings

3. Evaluate conditions in order

4. Always include a default icon

5. Test thoroughly with actual data