Styling an RI Visual

Use Rainmaker Insights (RI) Chat to describe how you want a Visual to appear. You can also review or manually adjust its configuration in the ECharts Spec JSON field in the Style section.

Configure a Visual with RI Chat

RI Chat provides an easy way to configure your report using plain language. Describe the layout, formatting, or changes you want, and RI Chat generates the configuration.

1. Navigate to Reports → RI Visuals.

2. Create a new Visual or open an existing Visual for editing.

3. Select the RI Chat tab in the Build section.

4. Enter a prompt describing the changes you want. For example:

   • “Display the results as a pie chart showing account counts by status.”

   • “Group the table by agent and include subtotals and a grand total for the collected amount.”

   • “Rename the Amount column to Collected and display values with two decimal places.”

5. Select Run Preview and review the results.

6. Enter additional prompts to refine the Visual, then select Save.

For detailed instructions, see Creating an RI Visual.

The following sections explain the supported Style JSON settings for users who want to review or manually adjust the configuration.

Access the Style Section

1. Navigate to Reports → RI Visuals.

2. Open or create a visual.

3. Expand Style.

4. Enter the JSON configuration in the ECharts Spec JSON field.

5. Select Run Preview to review the results.

6. Select Apply or Save to save the visual.

Note

The ECharts Spec JSON field uses RI-specific configuration options. It is not a general ECharts configuration object. Only options supported by RI are applied.

What You Can Style

The JSON configuration can control:

• Visual types and data mappings.

• Column labels and formatting.

• Tables, groups, subtotals, and totals.

• Charts, heatmaps, gauges, scorecards, and cross tabs.

• Legends and cell visuals.

• Delivery and export defaults.

This article covers JSON configuration for individual RI Visuals. Board-level styles, SQL, and Default Parameters are configured separately.

Understand the JSON Configuration

The JSON configuration tells RI how to display the data returned by the visual's SQL. Most configurations include three types of settings:

For example:

• "type": "pie" tells RI to display the data as a pie chart.

• "labelColumn": "status" tells RI to use the SQL alias status for the pie slice labels.

• "valueColumn": "account_count" tells RI to use the SQL alias account_count to determine the value of each slice.

{
  "type": "pie",
  "labelColumn": "status",
  "valueColumn": "account_count"
}

JSON Syntax Guidelines

When entering JSON:

• Use double quotation marks for text values.

• Use true or false for Boolean values.

• Use brackets [ ] for lists.

• Enter numbers without quotation marks.

• Do not include comments or trailing commas.

• Omit optional settings when not needed.

• When referencing data, use the SQL output alias returned by the visual.

General Settings

Supported Visual Types

Configure Columns and Drilldowns

Columns control which data appears in the visual and how it is presented.

Column Configuration Example

{
  "type": "table",
  "columns": ["agent", "amount"],
  "hiddenColumns": ["agent_id"],
  "columnLabels": {
    "agent": "Agent",
    "amount": "Collected"
  },
  "columnFormats": {
    "amount": "decimal"
  }
}

Note

columns controls column order, not visibility. Additional columns returned by the SQL remain visible unless included in hiddenColumns.

Configure Tables

Table settings control how rows and columns are presented and how users interact with the table.

Row Formatting Example

{
  "rowColorColumn": "row_color",
  "hiddenColumns": ["row_color"]
}

Note

Setting pageable to false does not remove applicable data or memory limits. Grouping and totals can also affect how rows are loaded and displayed.

Format Column Values

Use columnFormats to control how values are displayed.

In this example, amount identifies the column to format and currency-decimal specifies how its values are displayed.

{
  "columnFormats": {
    "amount": "currency-decimal"
  }
}

Note

Formatting changes how a value is displayed. It does not change the value returned by the SQL.

Supported Formats

Use the lowercase values shown above. Unsupported values cannot be used to create custom formatting patterns.

Formatting Considerations

Formatting can vary by visual type and output format. For example, the same format may display differently in a table, gauge, scorecard, legend, or export.

• For amounts that require two decimal places, use decimal.

• For percentages, provide the value as a fraction. For example, 0.125 displays as 12.50%.

Note

When modifying an existing report, verify representative values in both the RI visual and the intended export format.

Configure Column Display Options

Use columnOptions to apply additional display options to individual columns.

Column Display Example

{
  "type": "table",
  "columnOptions": {
    "status_markup": {
      "renderHtml": true
    },
    "encrypted_reference": {
      "decrypt": true,
      "padDirection": "LEFT",
      "padLength": 8,
      "padCharacters": "0"
    }
  },
  "columnFormats": {
    "encrypted_reference": "text"
  }
}

Warning

Decrypted values can appear in reports and exported files. Only use decrypt for fields the report audience is authorized to access.

Supported HTML includes common inline formatting and links. Scripts and other unsupported content are not rendered. PDF output can display HTML-formatted values differently.

Configure Groups, Subtotals, and Totals

Use grouping to organize table rows by a shared value and display subtotals or a grand total.

Summary Operations

Use the following values with summaryColumns:

• sum or total

• average, avg, or mean

• min or minimum

• max or maximum

• none

groupBy Settings

Grouped Table Example

{
  "type": "table",
  "groupBy": [
    {
      "column": "team",
      "label": "Team"
    }
  ],
  "showGroupSubtotals": true,
  "showGrandTotal": true,
  "summaryColumns": {
    "amount": "sum"
  }
}

Note

When using nested groups, verify results when the same value appears in more than one parent group.

Configure Grouped Headers

Use grouped headers to place related columns under a shared heading.

Use headerGroups for a single row of grouped headings or headerGroupRows for multiple rows.

Grouped Header Example

{
  "type": "table",
  "columns": ["agent", "amount", "rate"],
  "columnFormats": {
    "amount": "decimal",
    "rate": "percent"
  },
  "headerGroups": [
    {"label": "Team", "colspan": 1},
    {"label": "Performance", "colspan": 2}
  ],
  "groupBy": [
    {"column": "agent", "label": "Agent"}
  ],
  "showGroupSubtotals": true,
  "showGrandTotal": true,
  "summaryColumns": {
    "amount": "sum",
    "rate": "average"
  }
}

Note

Keep the column order and colspan values aligned so each grouped heading appears above the intended columns.

Configure Bar, Line, Area, and Pie Charts

Use chart settings to define categories, values, series, and display options.

Line Chart Example

{
  "type": "line",
  "title": "Monthly Collected",
  "xAxisColumn": "period",
  "yAxisColumn": "amount",
  "smooth": true,
  "showTrendLine": true,
  "columnFormats": {
    "amount": "currency-decimal"
  }
}

Note

Trend lines may not appear in PDF output.

If duplicate category and series combinations are returned, RI does not automatically combine their values. Aggregate the values in the visual's SQL when needed.

Pie Chart Example

{
  "type": "pie",
  "title": "Accounts by Status",
  "labelColumn": "status",
  "valueColumn": "account_count",
  "columnLabels": {
    "account_count": "Accounts"
  }
}

Configure Heatmaps and Comparison Matrices

A heatmap uses values to show differences across two categories.

A comparison matrix displays those values in a table-style grid and can show changes between current and prior values.

For a standard heatmap, configure:

• xAxisColumn

• yAxisColumn

• valueColumn

To display a comparison matrix, also set "renderMode":"table".

Comparison Matrix Example

{
  "type": "heatmap-cartesian",
  "renderMode": "table",
  "title": "Monthly Activity",
  "xAxisColumn": "period",
  "yAxisColumn": "team",
  "valueColumn": "amount",
  "priorValueColumn": "prior",
  "changeColumn": "change_pct",
  "minValue": -25,
  "maxValue": 25
}

Return one row for each row/period combination. Duplicate cells can replace previously returned values instead of aggregating them.

Comparison matrices include built-in totals, sorting, status colors, and amount formatting. CSV and Excel exports retain the source long-form heatmap rows rather than reproducing the displayed matrix.

Configure Progress Gauges

A progress gauge shows how a current value compares with a goal or target.

Use "type":"progress-gauge" to create a progress gauge. The gauge uses the first returned row, so the SQL should return the intended aggregate in that row.

Progress Gauge Example

{
  "type": "progress-gauge",
  "title": "Collected vs Goal",
  "valueColumn": "collected",
  "goalColumn": "goal",
  "minValue": 0,
  "maxValue": 100000,
  "format": "currency-decimal"
}

How Progress Is Calculated

RI calculates progress by comparing the current value to the configured minimum and maximum values:

(value - minValue) / (maxValue - minValue)

For the example above, $62,500 of $100,000 displays as 62.5% progress.

The result is limited to a range of 0–100%. If maxValue is omitted, RI uses the goal as the maximum value.

Configure Scorecards

Scorecards display important metrics in individual cards, making them useful for showing summary values such as collected amounts, account counts, or rates.

Use "type":"scorecard" and metricCards to configure scorecard metrics.

Scorecard Example

{
  "type": "scorecard",
  "metricCards": [
    {
      "label": "Collected",
      "valueColumn": "amount",
      "format": "currency-decimal",
      "tone": "good"
    },
    {
      "label": "Recovery Rate",
      "valueColumn": "rate",
      "format": "percent",
      "tone": "watch"
    }
  ]
}

A scorecard uses the first returned row. It does not automatically sum multiple rows; perform the required aggregation in SQL.

Configure Cross Tabs

A cross tab summarizes data in a grid. One SQL result becomes the rows, another becomes the columns, and a value appears at their intersection.

For example, a cross tab could display teams as rows, months as columns, and collected amounts as values.

Use "type":"crosstab" to pivot long-form results into row and column categories.

Cross Tab Example

{
  "type": "crosstab",
  "rowColumn": "team",
  "columnColumn": "period",
  "valueColumn": "amount",
  "aggregation": "sum",
  "showRowTotals": true,
  "showColumnTotals": true
}

Note

Use "aggregation":"sum" when repeated row/column combinations should be added together. Otherwise, a later matching row can replace an earlier value.

Configure Legend and Summary Boxes

Legend and summary boxes display calculated or fixed values alongside a visual.

Use legendBox to configure one summary box or legendBoxes to configure multiple boxes.

Supported item operations include:

• first

• count

• sum

• average, avg, or mean

• min or minimum

• max or maximum

Example:

{
  "legendBox": {
    "title": "Summary",
    "items": [
      {
        "label": "Collected",
        "valueColumn": "amount",
        "operation": "sum",
        "format": "currency-decimal"
      },
      {
        "label": "Period",
        "value": "Current month"
      }
    ]
  }
}

Note

Legend calculations use the rows available to the visual. When the visual is paged, calculations may reflect only the loaded rows.

Configure Bullet Bars

Bullet bars add an inline visual indicator to a table cell.

Use tableCellVisuals to add supported inline visuals to ordinary table cells. cellVisuals is an alternate setting.

Currently supported cell visual type:

bullet-bar

Bullet Bar Example

{
  "type": "table",
  "columns": ["agent", "amount"],
  "tableCellVisuals": {
    "amount": {
      "type": "bullet-bar",
      "thresholdColumns": ["low_goal", "high_goal"]
    }
  }
}

Note

Some Style JSON options are supported only in the RI Visuals screen and may not produce the same result in exported or PDF output. Verify the delivery format used by the report.

Configure Delivery and Export Settings

Style JSON can define default delivery and CSV settings.

Supported defaultExportFormat values are:

• PDF

• CSV

• EXCEL

• HTML

• TSV

• DELIMITED

• FIXED_LENGTH

• XML

• JSON

Use EXCEL, not XLSX, for this setting.

Example:

{
  "type": "table",
  "defaultExportFormat": "CSV",
  "csvDelimiter": "|",
  "csvQuoteCharacter": "\"",
  "showHeader": true
}

The Default delivery format field in the Style section updates the applicable settings in the same configuration.

Note

Default Parameters, displayed below ECharts Spec JSON, are separate SQL-defined controls. Do not add Default Parameters to ECharts Spec JSON.

Troubleshoot Style JSON

Verify the Configuration

When creating or changing Style JSON:

1. Start with an explicit type and exact SQL aliases.

2. Change one group of settings at a time.

3. Select Run Preview and test representative values, including zero, negative, and missing values.

4. Select Save or Apply.

5. Verify the delivery or export format that the report will use.

Glossary

ECharts Spec JSON Option Index

Use this index to locate additional information about a JSON setting.

Nested settings are documented with their parent configuration: columnOptions, groupBy, headerGroups/headerGroupRows, metricCards, legendBox/legendBoxes, and tableCellVisuals/cellVisuals.