Skip to main content

Advanced Conditional Icon Rules for Map Visualizations

A complete guide to writing conditional rules that change map icon colors and styles based on field data, including combined conditions, numeric comparisons, and common pitfalls.

During the configuration import process, the Visualizations step lets you control how nodes and connections appear on the map. You can set up conditional rules so that icons change color automatically based on field data. For example, completed poles can turn blue, power-only poles can turn grey, and exported poles can turn green.

This guide covers everything from basic rules to advanced conditions. If you're new to conditional icons, start with Setting Up Conditional Map Styles and Icons for the fundamentals, then come back here for the advanced techniques.

Note: Conditional styles only affect how things look on the map. They do not change what data is collected, how data is exported, or how anything appears in Katapult.

In This Guide

  1. How Conditional Icons Work

  2. Field Names and Values

  3. Basic Rules

  4. Combined Conditions (AND / OR / NOT)

  5. Numeric Comparisons

  6. Matching Multiple Values

  7. Real-World Examples

  8. Icon Evaluation Order

  9. Common Pitfalls

  10. Tips and Reminders

How Conditional Icons Work

Each node type (pole, guy anchor, reference, etc.) in your configuration can have multiple icon styles. Each icon style has a fill color, stroke color, and an optional conditional rule written in a format called JSON Logic.

When the map renders a node, it checks each icon style from top to bottom. The first rule that matches determines the icon. If no rule matches, the system falls back to the last icon in the list (which should have no conditional rule).

Icon Position

Conditional

Behavior

Icon 1 (top)

Specific rule

Checked first. If it matches, this icon is used.

Icon 2

Specific rule

Checked second if Icon 1 did not match.

Icon 3 (bottom)

Empty {}

Default fallback. Used when no other rule matches.

Field Names and Values

Conditional rules reference the stored field name, not the display name you see in the template editor. Stored field names are always lowercase with underscores.

Display Name (what you see)

Stored Name (what you use in rules)

Field Completed

field_completed

Power Only

power_only or poweronly

Pole Owner Questionable

poleownerquestionable

measurement_data

measurement_data

To find the exact stored name, open your configuration, go to the data template for the node type, and look at the field names listed there.

How Values Are Stored

All field values are stored and compared as text strings. This includes values that look like other types:

Value Type

Stored As

Example

Yes/No (from Katapult)

"Yes" or "No"

Power Only, Pole Owner Questionable

True/False (Cloneable fields)

"true" or "false"

Field Completed

Numbers

"5", "10.5"

Pole height, counts

Empty fields

null

Fields the fielder hasn't filled in yet

Important: Fields imported from Katapult typically store "Yes"/"No", while fields created by Cloneable (like Field Completed) store "true"/"false". If your rule isn't matching, check which format your field uses.

Basic Rules

Equals

Check if a field matches a specific value:

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

Not Equals

Check if a field does NOT match a value:

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

Has Any Value (Not Empty)

Check if a field has been filled in:

{"!=": [{"var": "measurement_data"}, null]}

Is Empty (No Value)

Check if a field has NOT been filled in:

{"==": [{"var": "measurement_data"}, null]}

Combined Conditions (AND / OR / NOT)

You can combine multiple checks into a single rule. This is useful when an icon should only appear under very specific circumstances.

AND: Both Conditions Must Be True

Use and when a node must meet all of the conditions. For example, show a green icon only when the pole is completed AND is not a power-only pole:

{"and": [{"==": [{"var": "field_completed"}, "true"]}, {"==": [{"var": "poweronly"}, "No"]}]}

OR: At Least One Condition Must Be True

Use or when a node can meet any of the conditions. For example, show a yellow icon for high priority or critical priority poles:

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

This is also useful for handling the Yes/No vs. true/false difference. If you are not sure which format a field uses, you can check for both:

{"or": [{"==": [{"var": "poweronly"}, "true"]}, {"==": [{"var": "poweronly"}, "Yes"]}]}

NOT: Reverse a Condition

Use ! to flip a condition. For example, show an icon when a pole is NOT completed:

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

Important: Do not use {"!": {"var": "field_name"}} by itself to check for false or No. Because values are stored as text, the string "false" and the string "No" are both treated as non-empty (which counts as "truthy"), so this shorthand will not work as expected. Always use an explicit equals check instead: {"==": [{"var": "field_name"}, "false"]}

Nesting AND and OR Together

You can nest these to build more complex rules. For example, show a blue icon when the pole is completed AND is either joint-use or has been exported:

{"and": [{"==": [{"var": "field_completed"}, "true"]}, {"or": [{"==": [{"var": "poweronly"}, "No"]}, {"!=": [{"var": "last_export"}, null]}]}]}

Numeric Comparisons

You can compare field values against numbers using >, <, >=, and <=. Since field values are stored as text, the number on the comparison side must not be in quotes. This tells the system to treat the comparison as numeric instead of alphabetical.

Rule

Meaning

{">": [{"var": "count"}, 5]}

Count is greater than 5

{"<": [{"var": "count"}, 10]}

Count is less than 10

{">=": [{"var": "score"}, 80]}

Score is 80 or higher

{"<=": [{"var": "score"}, 100]}

Score is 100 or lower

Important: Always leave the number unquoted. Writing {">": [{"var": "count"}, "5"]} with quotes around the 5 will compare alphabetically instead of numerically, which gives incorrect results (for example, "10" would be considered less than "5" alphabetically).

Matching Multiple Values

If you want to check whether a field matches any value in a list, use the in operator. This is a cleaner alternative to writing a long chain of OR conditions.

For example, show a green icon when the status is any of "complete", "approved", or "verified":

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

This is equivalent to writing:

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

Real-World Examples

Example 1: Pole Completion with Power-Only Status

A common setup for utility pole inspections with five icon styles, checked top to bottom:

Icon

Color

Conditional Rule

When It Shows

1

Grey

{"or": [{"==": [{"var": "poweronly"}, "true"]}, {"==": [{"var": "poweronly"}, "Yes"]}]}

Power-only pole (skip for now)

2

Blue

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

Fielder marked complete

3

Red

{"or": [{"==": [{"var": "poweronly"}, "false"]}, {"==": [{"var": "poweronly"}, "No"]}]}

Joint-use, not yet completed

4

White

{"!=": [{"var": "measurement_data"}, null]}

Has measurements but no status yet

5

Red (default)

{}

Default fallback for everything else

Notice how Icon 1 (power-only) is checked first. If a pole is power-only, it shows grey immediately, and none of the other rules are evaluated. This is why icon order matters.

Example 2: Export Tracking

Track which poles have been exported back to Katapult:

Icon

Color

Conditional Rule

When It Shows

1

Green

{"!=": [{"var": "last_export"}, null]}

Successfully exported

2

Red (default)

{}

Not yet exported

Example 3: Field Completed with No Access Flag

Color-code poles to distinguish completed, no-access, and remaining work:

Icon

Color

Conditional Rule

When It Shows

1

Yellow

{"==": [{"var": "no_access"}, "Yes"]}

Pole is inaccessible

2

Green

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

Fielder marked complete

3

Red (default)

{}

Still needs work

Icon Evaluation Order

The order of your icon styles is critical. The system checks them top to bottom and uses the first match. Follow this pattern:

  1. Most specific conditions first (e.g., power-only AND completed)

  2. General conditions next (e.g., completed)

  3. Default icon last with an empty conditional {}

If you put a general "has measurements" check before a specific "field completed" check, the general rule will match first and the specific icon will never appear.

Important: Always include a default icon with an empty conditional {} as the last item. Without it, nodes that don't match any rule may not display correctly on the map.

Common Pitfalls

1. "Yes"/"No" vs. "true"/"false"

Fields imported from Katapult typically store "Yes" and "No", while fields created by Cloneable (like Field Completed) store "true" and "false". If your rule isn't matching, you may be comparing against the wrong format.

If you are unsure which format a field uses, you can check for both with an OR rule:

{"or": [{"==": [{"var": "poweronly"}, "true"]}, {"==": [{"var": "poweronly"}, "Yes"]}]}

2. Field Names Are Case-Sensitive

{"var": "PowerOnly"} will NOT match a field stored as poweronly. Always use the exact lowercase stored name from the data template.

3. Quoted Numbers Give Wrong Results

When comparing numbers, do not put quotes around the number. {">": [{"var": "count"}, "5"]} compares alphabetically, where "10" comes before "5". Use {">": [{"var": "count"}, 5]} instead (no quotes around 5).

4. All Poles Show the Same Color

This usually means one rule is matching everything. Common causes:

  • A "has any value" check ({"!=": [{"var": "field"}, null]}) is placed too high in the list, catching poles before more specific rules can match

  • The field name is misspelled or doesn't match the stored format

  • The comparison value uses the wrong format (e.g., "true" instead of "Yes")

5. Icons Work on Web but Not on Mobile

Make sure you have selected an icon shape (Circle, Diamond, Square, etc.) for each icon style. Color-only styles without a selected shape may not render correctly on mobile devices.

6. JSON Syntax Errors When Saving

If you see an error when saving, check for:

  • Missing or extra commas

  • Missing closing brackets } or ]

  • Single quotes instead of double quotes (JSON requires double quotes)

Tips and Reminders

  • Conditional styles are purely visual. They do not affect data collection, exports, or anything in Katapult.

  • You can safely experiment with conditional rules. Changes are easy to undo, and nothing will break your data.

  • Field names are always lowercase with underscores. Check the data template for the exact stored name.

  • Always include a default icon with an empty conditional {} as the last item.

  • Put the most specific rules at the top and the most general rules toward the bottom.

  • Use null comparisons for checking whether a field is empty or has any value. This is especially useful for last_export and measurement_data.

  • Select an icon shape for every icon style to ensure it renders correctly on both web and mobile.

  • If you want help writing a specific conditional rule, you can paste this article into ChatGPT or Claude and describe what you want. For example: "I want poles to turn green when field_completed is true and poweronly is No."

Quick Reference: All Operators

Operator

Syntax

What It Does

Equals

{"==": [{"var": "field"}, "value"]}

Field matches value

Not equals

{"!=": [{"var": "field"}, "value"]}

Field does not match value

Is empty

{"==": [{"var": "field"}, null]}

Field has no value

Has value

{"!=": [{"var": "field"}, null]}

Field has any value

AND

{"and": [rule1, rule2]}

Both rules must match

OR

{"or": [rule1, rule2]}

At least one rule must match

NOT

{"!": rule}

Reverse a condition

In list

{"in": [{"var": "field"}, ["a","b"]]}

Field matches any value in list

Greater than

{">": [{"var": "field"}, 5]}

Numeric: field is greater than 5

Less than

{"<": [{"var": "field"}, 10]}

Numeric: field is less than 10

Default

{}

Fallback when no other rule matches

Did this answer your question?