Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
icon() expression (first-party plugin)
Use icons as presentation values
The icon function resolves a stable ID from the bundled icon catalog into a platform-icon value. A compatible Studio renderer displays the glyph; the function does not download an image, follow a remote URL, create an attachment or perform the business action depicted by the glyph. A green approval icon cannot approve a task.
First choose the meaning and a text label, then select an actual catalog ID. Keep the business state authoritative and derive presentation from that state. Include a text alternative or adjacent status label so color and shape are not the only signals. The approved/pending/declined examples below refer to synthetic leave records that the viewer is already permitted to read.
| Contract | Practical use |
|---|---|
Signature icon(id) |
Exactly one non-empty text ID. |
| Catalog identity | Stable IDs, case-insensitive lookup; labels/categories are not IDs. |
| Result | A renderable object with catalog metadata; optional SVG and renderer mapping remain separate details. |
| Deterministic/argument-only | Resolution depends on the admitted catalog and supplied ID, not hidden document/user lookups. |
| Unknown/wrong-type ID | Governed invocation failure, not a remote-icon fallback. |
| Distribution | Bundled first-party pack, with customer-plugin administration a separate trust flow. |
Use first-party functions for pack discovery and screen language for the property that consumes the result. The catalog below remains the reference for available IDs.
Worked examples
Example DATA-ICON-01 — Render an approved status with a real catalog ID
Scenario and inputs. Sara sees a permitted leave request whose authoritative status is APPROVED. Nadia wants an approval glyph alongside the visible word Approved. The application has the admitted bundled icon function and a compatible icon-valued display property. The expression below is an expression fragment, not a complete screen document or an executable task action.
Procedure. 1. Find approval-approved in the current catalog rather than choosing a label such as Approved as the ID. 2. Bind icon("approval-approved") to the supported display property. 3. Keep the adjacent text label or accessible name derived from the same business state. 4. Preview the layout under the ordinary viewer’s permissions and relevant direction/viewport. 5. Inspect the renderer’s handling of the returned icon value instead of treating that object as a file URL.
Expected result. The function returns the catalog-owned platform icon metadata for approval-approved, including its stable ID and meaning. The renderer can display it consistently with the platform; no approval transaction or document mutation occurs.
Failure and recovery. If the editor reports an unknown function, diagnose pack discovery/admission before changing the expression. If the function exists but the property cannot render an object, use a compatible shared icon property rather than coercing it into a remote URL or injecting raw markup.
Sources. IconFunctions.java, IconCatalog.java.
Example DATA-ICON-02 — Select a status glyph from an explicit business condition
Scenario and inputs. The teaching dataset has PENDING and APPROVED requests. Nadia wants a dynamic glyph but also wants an unknown future state to remain recognizable instead of looking approved. The source status is already readable to Sara; this example does not fetch a record merely to compute its icon.
Procedure. 1. Choose actual catalog IDs for the two supported states and an honest neutral fallback. 2. Author an InflowEL if … then … else … expression using the current row/input name accepted by that screen property. 3. Start with a simple two-state expression such as if inputs:status = "APPROVED" then icon("approval-approved") else icon("status-pending") in a reusable expression rule with a declared status input. 4. In the application mapping, handle any separate declined/unknown state explicitly and supply an independent visible label. 5. Test each state rather than only the green branch.
Expected result. The selected icon follows the actual input state. The Boolean/branch expression returns an icon value, while the status text can continue to show the exact business value; the fallback does not silently mark an unknown state as successful.
Failure and recovery. A missing state input is a contract problem, not a reason to display an approval glyph. Correct the source mapping and requiredness. If an unknown catalog ID is used in one branch, repair that exact ID from the admitted catalog instead of hiding every function error with a misleading success icon.
Sources. IconFunctions.java, ExprInterpreter.java.
Example DATA-ICON-03 — Add a read-only grid indicator without adding an approval action
Scenario and inputs. Nadia extends the manager’s leave grid with an icon-based status column. The grid already has an explicit permitted projection and stable row identity. She wants a faster visual scan, while the real manager decision stays on its guarded task action and form.
Procedure. 1. Verify the selected control and expression-column contract can consume the intended value; not every generic grid column accepts an arbitrary object. 2. Add the supported expression/display recipe using the row’s admitted status field and actual icon IDs. 3. Keep the stable row key unchanged and give the column an accessible label. 4. Publish the changed screen and inspect pending and approved records as Sara. 5. Open the actual task separately for an authorized decision rather than registering the icon as a mutation shortcut.
Expected result. The viewer receives a status indicator for rows and fields already available under the published grid contract. Sorting or opening a record does not manufacture a new permission, and the icon carries no task completion payload.
Failure and recovery. If the source omits a field under current access, do not issue a second unauthorized record fetch for decoration. Remove or hide that presentation according to the control contract, or choose a permitted source field. Unsupported object rendering should lead to a compatible display design, not raw HTML or a guessed image route.
Sources. IconFunctions.java, DataGridQueryController.java.
Example DATA-ICON-04 — Diagnose unknown, empty and nontext IDs precisely
Scenario and inputs. A designer changes a known icon expression to icon("not-a-real-icon"); another draft calls icon(17), and a third accidentally supplies two arguments. The same pack is present in all three cases, so treating every failure as a missing installation would send the operator to the wrong recovery.
Procedure. 1. Inspect the function descriptor and compare the exact supplied arguments with icon(id). 2. For an unknown text ID, search the actual catalog and choose a documented stable ID. 3. For numeric/blank input, correct the authored expression or field mapping to supply meaningful non-empty text. 4. For the arity error, remove the extra parameter rather than guessing an optional size/color argument. 5. Re-test each changed branch and preserve text meaning/accessibility in the final rendering.
Expected result. Each failure remains a governed function invocation error tied to a concrete authoring mistake. The repaired call returns the same catalog-owned value contract as any other valid icon expression, without network fetches or mutable global styling.
Failure and recovery. Do not disable plugin verification, add a remote URL, or suppress the entire column to disguise an unresolved argument error. If catalog discovery itself is missing, handle that separate admitted-package problem through the normal operator path; a successful unit example is not proof that a particular running instance has loaded the pack.
Sources. IconFunctions.java, IconFunctionsBehaviorTest.java.
Detailed reference
Plugin: inflow-functions-icons
Function: icon(id)
Catalog: packaged inside the plugin JAR at icons/catalog.json
Purpose
icon(id) resolves a stable platform icon id from the catalog shipped
inside the first-party plugin JAR. It returns a structured value that Studio
renders as a glyph — it does not download remote images, accept URLs, or
write image files.
icon("approval-approved")
→ { kind: "platform-icon", id, name, category, color, meaning, … }
Self-contained pack
Everything the function needs lives in the JAR:
| Path in JAR | Role |
|---|---|
icons/catalog.json |
Full icon catalog (ids, labels, colors, meanings) |
plugin.json |
Plugin identity |
com/inflowai/plugins/icons/* |
icon() implementation |
To add or change bundled icons, a platform developer edits icons/catalog.json
in the inflow-functions-icons module and ships the rebuilt pack with an Inflow
release. Administrators do not replace or approve the bundled pack through the
customer-plugin UI. Additional custom packs use the separate
plugin review and runner flow.
Optional per-icon svg (inline <svg>…</svg>) lets a custom pack draw
glyphs that are not in Studio’s Lucide map.
Catalog entry shape
{
"id": "approval-approved",
"name": "Approved",
"category": "Approvals",
"color": "#16a34a",
"keywords": "approve accepted success",
"meaning": "A request was approved.",
"glyph": "CheckCircle2",
"svg": null
}
id— stable machine key used in expressions (case-insensitive).svg— when set, Studio renders this markup; when null, Studio uses the platform business-icon Lucide map for known ids.
Usage
Static icon
${ icon("status-active") }
Conditional icon
${ if item.status = "ACTIVE" then icon("status-active") else icon("status-inactive") }
Data grid expression column
- Configure data grid → Add expression column → Edit expression.
- Enter e.g.
icon("approval-approved")or a conditional as above. - Apply / save; Interactive Preview evaluates page-local and draws the glyph.
If a cell in an expression column cannot show its value, the cell reads Not available (Arabic: غير متاح) in the data grid, table, tree grid and editable grid. Hover the marker, or move to it with a screen reader, for a plain-words reason: the information the column needs is not available here (reload the page), the formula returned a kind of value the column cannot show, the formula uses a field that is not available for this row, the icon cannot be displayed here, or the value could not be calculated for this row. The cell never shows a technical code. Agents and tests read the code from the marker's data-column-refusal attribute and its family from data-column-refusal-reason. (SCRUM-3857) When the value in that slot is free evaluator or server text rather than a code (for example Division by zero.), both data-column-refusal and data-expression-error read SCREEN_COLUMN_CALCULATION_FAILED; the family is still in data-column-refusal-reason. (SCRUM-3859)
A failed cell is not announced on its own, so a column that fails on every row does not make a screen reader say Not available once per row. Each grid (data grid, table, tree grid, editable grid, and the data grid's mobile cards) has one quiet summary that a screen reader announces politely: Some calculated values are not available. (Arabic: بعض القيم المحسوبة غير متاحة.). It is announced when failed cells first appear, and again only when the set of failed cells changes, for example on another page or after a load whose failed cells are different. A reload with the same rows and the same failures is not announced again. The summary has the agent id <grid>.announcement.saved-columns; its data-agent-state is error while any cell on the page failed and ready otherwise, and data-column-refusal-count is the number of distinct failed cells (a cell that the data grid also shows in a mobile card is counted once). (SCRUM-3860)
Return value (Object):
| Field | Meaning |
|---|---|
kind |
Always platform-icon |
id |
Catalog id |
name |
Display name |
category |
Catalog group |
color |
Default hex color |
meaning |
Business description |
glyph |
Optional Lucide component name (authoring hint) |
svg |
Optional inline SVG from the pack |
Build and ship
mvn -f first-party-plugins/inflow-functions-icons -DskipTests package
# or all first-party packs:
.\scripts\build-first-party-function-plugins.ps1
Artifact: first-party-plugins/inflow-functions-icons/target/inflow-functions-icons.jar
Bundled into the application as bundled-expression-functions/inflow-functions-icons.jar.
Full catalog
Total icons: 188
Actions
| Id | Name | Color | Meaning |
|---|---|---|---|
action-add |
Add | #16a34a |
Add / create. |
action-cancel |
Cancel | #6b7280 |
Cancel. |
action-configure |
Configure | #111827 |
Configure. |
action-copy |
Copy | #111827 |
Copy. |
action-delete |
Delete | #dc2626 |
Delete. |
action-download |
Download | #111827 |
Download. |
action-edit |
Edit | #2563eb |
Edit. |
action-filter |
Filter | #111827 |
Filter. |
action-refresh |
Refresh | #111827 |
Refresh / retry. |
action-reset |
Reset | #6b7280 |
Reset. |
action-save |
Save | #16a34a |
Save. |
action-search |
Search | #111827 |
Search. |
action-submit |
Submit | #2563eb |
Submit. |
action-upload |
Upload | #111827 |
Upload. |
action-view |
View | #111827 |
View. |
Approvals
| Id | Name | Color | Meaning |
|---|---|---|---|
approval-approved |
Approved | #16a34a |
A request, step, or approval was approved. |
approval-auto-approved |
Auto Approved | #16a34a |
Approved automatically by a rule. |
approval-cancelled |
Approval Cancelled | #6b7280 |
The approval was cancelled. |
approval-delegated |
Delegated | #2563eb |
Approval delegated to another approver. |
approval-escalated |
Escalated | #9333ea |
Escalated to a higher authority. |
approval-pending |
Pending Approval | #f59e0b |
Awaiting an approval decision. |
approval-rejected |
Rejected | #dc2626 |
A request or approval was rejected. |
approval-returned |
Returned | #ea580c |
Sent back to the requester for changes. |
approval-review |
In Review | #2563eb |
Under review by an approver. |
approval-signature |
Signature | #111827 |
Requires or captured a signature. |
Communication
| Id | Name | Color | Meaning |
|---|---|---|---|
communication-announcement |
Announcement | #ea580c |
An announcement. |
communication-bell |
Alert Bell | #f59e0b |
An alert bell. |
communication-chat |
Chat | #111827 |
A chat conversation. |
communication-comment |
Comment | #111827 |
A comment. |
communication-email |
#111827 |
An email. | |
communication-mention |
Mention | #2563eb |
A mention. |
communication-message |
Message | #111827 |
A message. |
communication-notification |
Notification | #111827 |
A notification. |
communication-phone |
Phone | #111827 |
A phone call. |
communication-reply |
Reply | #111827 |
A reply. |
Data
| Id | Name | Color | Meaning |
|---|---|---|---|
data-export |
Export | #111827 |
Data export. |
data-field |
Field | #111827 |
A data field. |
data-filter |
Filter | #111827 |
A filter. |
data-import |
Import | #111827 |
Data import. |
data-list |
List | #111827 |
A list. |
data-mapping |
Mapping | #111827 |
A data mapping. |
data-model |
Data Model | #111827 |
A data model. |
data-object |
Object | #111827 |
A data object. |
data-search |
Search | #111827 |
A search. |
data-table |
Table | #111827 |
A data table. |
Documents
| Id | Name | Color | Meaning |
|---|---|---|---|
document-attachment |
Attachment | #111827 |
An attached file. |
document-audit-trail |
Audit Trail | #111827 |
The audit trail. |
document-comment |
Comment | #111827 |
A comment on a document. |
document-default |
Document | #111827 |
A generic document. |
document-field-update |
Field Updated | #ea580c |
A field value was updated. |
document-form |
Form | #2563eb |
A form or request document. |
document-history |
History | #111827 |
Document history. |
document-note |
Note | #f59e0b |
A note. |
document-signature |
Signature | #111827 |
A document signature. |
document-version |
Version | #111827 |
A document version. |
Finance
| Id | Name | Color | Meaning |
|---|---|---|---|
finance-approval-limit |
Approval Limit | #f59e0b |
An approval spending limit. |
finance-budget |
Budget | #16a34a |
A budget. |
finance-cost-center |
Cost Center | #111827 |
A cost center. |
finance-currency |
Currency | #111827 |
A currency / coins. |
finance-expense |
Expense | #ea580c |
An expense. |
finance-invoice |
Invoice | #111827 |
An invoice. |
finance-money |
Money | #16a34a |
Money / an amount. |
finance-payment |
Payment | #16a34a |
A payment. |
finance-purchase-order |
Purchase Order | #111827 |
A purchase order. |
finance-receipt |
Receipt | #111827 |
A receipt. |
HR
| Id | Name | Color | Meaning |
|---|---|---|---|
hr-attendance |
Attendance | #16a34a |
Attendance. |
hr-contract |
Contract | #111827 |
An employment contract. |
hr-employee |
Employee | #111827 |
An employee. |
hr-leave |
Leave | #f59e0b |
Leave / time off. |
hr-offboarding |
Offboarding | #ea580c |
Employee offboarding. |
hr-onboarding |
Onboarding | #16a34a |
Employee onboarding. |
hr-payroll |
Payroll | #16a34a |
Payroll. |
hr-performance |
Performance | #2563eb |
Performance review. |
hr-position |
Position | #111827 |
A job position. |
hr-recruitment |
Recruitment | #2563eb |
Recruitment. |
Navigation
| Id | Name | Color | Meaning |
|---|---|---|---|
navigation-back |
Back | #111827 |
Go back. |
navigation-breadcrumb |
Breadcrumb | #111827 |
Breadcrumb navigation. |
navigation-collapse |
Collapse | #111827 |
Collapse. |
navigation-expand |
Expand | #111827 |
Expand. |
navigation-external |
External Link | #2563eb |
An external link. |
navigation-home |
Home | #111827 |
Home. |
navigation-menu |
Menu | #111827 |
A menu. |
navigation-more |
More | #111827 |
More options. |
navigation-next |
Next | #111827 |
Go next. |
navigation-open |
Open | #111827 |
Open. |
Procurement
| Id | Name | Color | Meaning |
|---|---|---|---|
procurement-approval |
Procurement Approval | #16a34a |
Procurement approval. |
procurement-cart |
Cart | #111827 |
A shopping cart. |
procurement-contract |
Contract | #111827 |
A procurement contract. |
procurement-delivery |
Delivery | #2563eb |
A delivery. |
procurement-item |
Item | #111827 |
A procurement item. |
procurement-purchase |
Purchase | #111827 |
A purchase. |
procurement-quote |
Quote | #111827 |
A quote. |
procurement-request |
Purchase Request | #2563eb |
A purchase request. |
procurement-tender |
Tender | #111827 |
A tender. |
procurement-vendor |
Vendor | #111827 |
A vendor. |
Risk & Compliance
| Id | Name | Color | Meaning |
|---|---|---|---|
risk-audit |
Audit | #111827 |
An audit. |
risk-compliance |
Compliance | #16a34a |
Compliance. |
risk-control |
Control | #111827 |
A risk control. |
risk-error |
Error | #dc2626 |
An error / critical risk. |
risk-exception |
Exception | #9333ea |
An exception. |
risk-issue |
Issue | #ea580c |
An issue/finding. |
risk-lock |
Locked | #111827 |
A locked/controlled item. |
risk-policy |
Policy | #111827 |
A policy. |
risk-review |
Risk Review | #2563eb |
A risk review. |
risk-warning |
Warning | #f59e0b |
A warning. |
Security
| Id | Name | Color | Meaning |
|---|---|---|---|
security-group-access |
Group Access | #111827 |
Group access. |
security-key |
Key | #f59e0b |
A key/credential. |
security-lock |
Locked | #111827 |
Locked. |
security-permission |
Permission | #f59e0b |
A permission. |
security-private |
Private | #64748b |
Private/restricted. |
security-public |
Public | #16a34a |
Public/shared. |
security-role |
Role | #111827 |
A security role. |
security-shield |
Shield | #16a34a |
Protection. |
security-unlock |
Unlocked | #111827 |
Unlocked. |
security-user-access |
User Access | #111827 |
User access. |
Status
| Id | Name | Color | Meaning |
|---|---|---|---|
status-active |
Active | #2563eb |
Active status. |
status-approved |
Approved | #16a34a |
Approved status. |
status-cancelled |
Cancelled | #6b7280 |
Cancelled status. |
status-completed |
Completed | #16a34a |
Completed status. |
status-draft |
Draft | #6b7280 |
Draft status. |
status-escalated |
Escalated | #9333ea |
Escalated status. |
status-failed |
Failed | #dc2626 |
Failed status. |
status-in-progress |
In Progress | #2563eb |
In-progress status. |
status-inactive |
Inactive | #9ca3af |
Inactive status. |
status-on-hold |
On Hold | #64748b |
On-hold status. |
status-overdue |
Overdue | #dc2626 |
Overdue status. |
status-paused |
Paused | #64748b |
Paused status. |
status-pending |
Pending | #f59e0b |
Pending status. |
status-rejected |
Rejected | #dc2626 |
Rejected status. |
status-waiting |
Waiting | #f59e0b |
Waiting status. |
System
| Id | Name | Color | Meaning |
|---|---|---|---|
system-api |
API | #111827 |
An API. |
system-automation |
Automation | #f59e0b |
An automation. |
system-database |
Database | #111827 |
A database. |
system-error |
System Error | #dc2626 |
A system error. |
system-expression |
Expression | #9333ea |
An expression. |
system-integration |
Integration | #111827 |
An integration. |
system-refresh |
Refresh | #111827 |
Refresh. |
system-rule |
Rule | #111827 |
A business rule. |
system-settings |
Settings | #111827 |
Settings. |
system-sync |
Sync | #111827 |
Synchronization. |
Tasks
| Id | Name | Color | Meaning |
|---|---|---|---|
task-assigned |
Assigned | #2563eb |
A task assigned to someone. |
task-cancelled |
Cancelled | #6b7280 |
A cancelled task. |
task-claimed |
Claimed | #16a34a |
A task claimed by a user. |
task-completed |
Completed | #16a34a |
A completed task. |
task-default |
Task | #111827 |
A generic task. |
task-escalated |
Escalated | #9333ea |
An escalated task. |
task-inbox |
Inbox | #111827 |
A task inbox. |
task-open |
Open | #6b7280 |
An open/unassigned task. |
task-overdue |
Overdue | #dc2626 |
A task that is overdue. |
task-pending |
Pending | #f59e0b |
A pending task. |
task-queue |
Queue | #111827 |
A task queue. |
task-reassigned |
Reassigned | #ea580c |
A task reassigned to someone else. |
Time & SLA
| Id | Name | Color | Meaning |
|---|---|---|---|
sla-breached |
Breached | #991b1b |
SLA is breached. |
sla-calendar |
Calendar | #111827 |
A calendar / schedule. |
sla-clock |
Clock | #111827 |
A clock / time. |
sla-completed |
Completed | #16a34a |
SLA completed. |
sla-deadline |
Deadline | #ea580c |
A deadline. |
sla-due-soon |
Due Soon | #f59e0b |
SLA is due soon. |
sla-on-track |
On Track | #16a34a |
SLA is on track. |
sla-overdue |
Overdue | #dc2626 |
SLA is overdue. |
sla-paused |
Paused | #64748b |
SLA is paused. |
sla-timer |
Timer | #111827 |
A timer. |
Users & Groups
| Id | Name | Color | Meaning |
|---|---|---|---|
group-default |
Group | #111827 |
A generic group. |
group-department |
Department | #111827 |
A department. |
group-organization |
Organization | #111827 |
An organization. |
group-role |
Role | #111827 |
A role. |
group-team |
Team | #2563eb |
A team. |
user-approver |
Approver | #16a34a |
An approver. |
user-assignee |
Assignee | #2563eb |
The user a task is assigned to. |
user-claimant |
Claimant | #16a34a |
The user who claimed the task. |
user-default |
User | #111827 |
A generic user. |
user-manager |
Manager | #111827 |
A manager. |
user-requester |
Requester | #2563eb |
The person who raised the request. |
Workflow
| Id | Name | Color | Meaning |
|---|---|---|---|
workflow-active-step |
Active Step | #2563eb |
The currently active step. |
workflow-branch |
Branch | #111827 |
A branching gateway. |
workflow-completed-step |
Completed Step | #16a34a |
A completed workflow step. |
workflow-condition |
Condition | #111827 |
A conditional decision. |
workflow-end |
End | #6b7280 |
The end of a workflow. |
workflow-failed-step |
Failed Step | #dc2626 |
A step that failed. |
workflow-instance |
Process Instance | #2563eb |
A running process instance. |
workflow-loop |
Loop | #111827 |
A loop/repeat construct. |
workflow-merge |
Merge | #111827 |
A merge/join gateway. |
workflow-process |
Process | #2563eb |
A business process. |
workflow-returned-step |
Returned Step | #ea580c |
A step returned for rework. |
workflow-skipped-step |
Skipped Step | #64748b |
A step that was skipped. |
workflow-start |
Start | #16a34a |
The start of a workflow. |
workflow-step |
Step | #6b7280 |
A generic (pending) workflow step. |
workflow-transition |
Transition | #111827 |
A transition between steps. |