# JSONLogic Icon Conditionals Documentation

## For Cloneable Cloud Platform Data Object Builder

## Table of Contents

1. [Overview](#overview)
2. [How It Works](#how-it-works)
3. [Field Naming and References](#field-naming-and-references)
4. [JSONLogic Syntax](#jsonlogic-syntax)
5. [Common Operators](#common-operators)
6. [Practical Examples](#practical-examples)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#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:

```json
{"operator": [arguments]}
```

***

## Common Operators

### 1. Variable Access (`var`)

Retrieves a field value from the data object.

```json
{"var": "field_name"}
```

### 2. Equality (`==`)

Checks if values are equal.

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

### 3. Inequality (`!=`)

Checks if values are not equal.

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

### 4. Logical AND (`and`)

All conditions must be true.

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

### 5. Logical OR (`or`)

At least one condition must be true.

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

### 6. Logical NOT (`!`)

Negates a condition.

```json
{"!": {"==": [{"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.

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

### 9. If-Then-Else (`if`)

Conditional branching (rarely needed for icon conditionals).

```json
{"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**:

```json
{"==": [{"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**:

```json
{"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**:

```json
{"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)**:

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

**Icon 2 - High (Orange)**:

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

**Icon 3 - Normal (Green)**:

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

**Icon 4 - Default (Gray)**:

```json
{}
```

### Example 5: Null Check with Completion

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

**Conditional**:

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

### Example 6: Numeric Comparisons

**Scenario**: Show different icons based on inspection score

**High Score (>= 90)**:

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

**Medium Score (50-89)**:

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

**Low Score (< 50)**:

```json
{"<": [{"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

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

#### Span Measurement Alerts

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

#### Work Order Priority

```json
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloneable.ai/cloneable-documentation/platform-documentation/data-objects/jsonlogic-icon-conditionals-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.