User Guide

Welcome to ZReport. This guide will help you master report design, from simple lists to complex analytical dashboards.

Interface Overview

The designer is divided into four main areas:

Tutorial: Your First Report

Let's build a simple Employee List report.

Bands Explained

Bands are the containers for your elements. Understanding bands is key to mastering reporting.

Grouping Data

Grouping allows you to organize data into logical sections, such as Sales by Region or Employees by Department.

Elements Guide

Data Sources

The Data Dictionary panel is where you define and manage data sources for a project. These sources are shared across all reports in the same project.

Data Binding ($F, $P, $V, $R)

ZReport uses a JasperReports-style syntax to reference data. Every data-bound expression must be wrapped in curly braces {...} with a prefix.

Parameters & Variables Detail

Formatting & Patterns

Apply display patterns to your data using the colon : syntax within the expression.

Functions Reference

ZReport includes a powerful functional library with 50+ functions for calculations and data manipulation.

Conditional Logic

You can hide elements or entire bands based on data conditions using the printWhen property.

Inline Logic (IF)

Use the IF function for dynamic content within a single text box.

Preview & Exporting

Saving & Loading

Keyboard Shortcuts

Limits & Troubleshooting

Expression Engine

The expression parser evaluates JasperReports-style expressions at runtime.

Syntax

Format Specifiers

Append :format to apply formatting:

• $F{price:currency} – Format as currency
• $F{date:date:yyyy-MM-dd} – Format as date
• $F{name:uppercase} – Convert to uppercase
• $F{code:pad:6:0} – Left-pad with zeros

System Variables

• PageNumber – Current page number
• TotalPages – Total page count (available after render)
• PrintDate – Current date/time
• ReportName – Name of the report
• RecordNumber – Current record index
• GroupRecordNumber – Record index within current group

Rich Content & Rich Text Elements

Rich content is a JSON array of blocks called RichContent (headings, styled paragraphs, lists, tables, images). There are two ways to fill a block at export time — Method 1: a $R{paramName} expression on a Text element, and Method 2: a bindParam on a dedicated Rich Text element. Both read the array from parameters, so the request body is identical. An advanced id-map override is also available when you POST an inline template.

Method 1 — $R{paramName} on a Text element

The simplest method, and the only one fully supported in the visual designer. Add a Text element, set its content to $R{paramName}, enable Can Grow, then pass the RichContent JSON array as that parameter. Works with a saved report (reportId / reportName) or an inline template.

1. Drag a Text element onto the band.
2. Set its content to $R{bodyContent} (any parameter name works).
3. Enable Can Grow in the element's properties.
4. POST the matching parameter as a RichContent array:

{
  "reportId": "rpt_abc123",
  "parameters": {
    "bodyContent": [
      {
        "type": "paragraph",
        "align": "center",
        "content": [
          { "text": "Normal text " },
          { "text": "bold text", "bold": true },
          { "text": " colored", "color": "#ff0000", "fontSize": 14 }
        ]
      },
      { "type": "heading", "level": 2, "content": [{ "text": "Section Title" }] },
      { "type": "hr" }
    ]
  }
}

The parameter name inside $R{…} must exactly match the key in parameters, and the value must be a real JSON array — not a JSON-encoded string.

Method 2 — bindParam on a Rich Text element

Use a dedicated richtext element and set its bindParam to a parameter name. At export time the engine resolves parameters[bindParam] to that element's content, so you send the same RichContent array under parameters as in Method 1.

Note: a richtext element does not evaluate $R{paramName} — that is Method 1's Text-element behavior. There is also no field for bindParam in the visual designer yet, so set it directly in the template JSON: either POST an inline template (below) or edit the saved report definition.

{
  "template": {
    "pages": [
      {
        "bands": [
          {
            "type": "detail",
            "elements": [
              {
                "id": "student-comment",
                "type": "richtext",
                "x": 10,
                "y": 10,
                "width": 180,
                "height": 40,
                "bindParam": "commentBody",
                "canGrow": true
              }
            ]
          }
        ]
      }
    ]
  },
  "format": "pdf",
  "parameters": {
    "commentBody": [
      {
        "type": "paragraph",
        "content": [
          { "text": "Overall performance: ", "bold": true },
          { "text": "Very good" }
        ]
      }
    ]
  }
}

Advanced — id-map override by element id

When you POST an inline template (not a saved reportId), you can override any richtext element by its id without setting bindParam. The key in richContent must match the element id, so one template can render different rich text per request. The reportId / reportName Export API routes do not read this richContent map — use Method 1 or Method 2 for saved reports.

{
  "template": {
    "version": "1.0",
    "metadata": {
      "id": "student-report",
      "name": "Student Report",
      "createdAt": "2026-06-01",
      "updatedAt": "2026-06-01"
    },
    "settings": {
      "paperSize": { "type": "A4" },
      "orientation": "portrait",
      "margins": { "top": 20, "right": 20, "bottom": 20, "left": 20 },
      "units": "mm"
    },
    "dataSources": [],
    "parameters": [],
    "variables": [],
    "styles": [],
    "pages": [
      {
        "id": "page-1",
        "name": "Page 1",
        "bands": [
          {
            "id": "detail",
            "type": "detail",
            "height": 80,
            "elements": [
              {
                "id": "student-comment",
                "type": "richtext",
                "x": 10,
                "y": 10,
                "width": 180,
                "height": 40,
                "canGrow": true,
                "defaultFont": { "family": "Helvetica", "size": 12 },
                "defaultColor": "#000000"
              }
            ]
          }
        ]
      }
    ]
  },
  "format": "pdf",
  "richContent": {
    "student-comment": [
      {
        "type": "heading",
        "level": 2,
        "content": [{ "text": "Conduct" }]
      },
      {
        "type": "paragraph",
        "content": [
          { "text": "Punctuality: ", "bold": true },
          { "text": "Excellent", "color": "#047857" }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "items": [
          { "content": [{ "text": "Participates actively in class" }] },
          { "content": [{ "text": "Completes assignments on time" }] }
        ]
      }
    ]
  }
}

Rich Text Resolution Order

When a richtext element is rendered, ZReport uses the first structured content source it finds:

1. richContent[element.id] in the request body.
2. parameters[element.bindParam], when bindParam is set.
3. element.richContent, the content saved by the designer.
4. element.content, legacy HTML fallback.

For PDFs, canGrow: true or an omitted canGrow allows rich text to flow across pages when it exceeds the element box. Set canGrow: false to clip content to the element box.

Block Types

Inline Text Properties

Each block that accepts content takes an array of inline text objects with these properties:

List Styles

Set the style property on a list block to control the marker type. If omitted, defaults to "bullet" (or "number" when ordered: true for backward compatibility).

For check and radio lists, each item accepts a checked boolean. It ticks the checkbox (☑/☐) for check, and fills the radio dot (●/○) for radio \u2014 set checked: true on the option you want pre-selected. radio is cosmetic (it renders the glyph; it does not enforce single-selection), so mark exactly one item if you want true radio semantics. In PDF the checkbox/radio markers are drawn as crisp vector shapes, so they never depend on font glyph coverage; DOCX uses the ☑/● glyphs. The canvas/HTML preview shows a plain list.

In the designer, the rich-text editor toolbar has a list-style dropdown (Bullet, Numbered, Letters, Roman, Checklist, Radio). For Checklist and Radio, select an item and use the ☑/● toggle button to mark it as checked / pre-selected.

Add "layout": "horizontal" to flow the items in a wrapping row instead of stacking them — ideal for a rating scale. Works with any style; markers and selection behave the same.

{
  "type": "list",
  "style": "radio",
  "layout": "horizontal",
  "items": [
    { "content": [{ "text": "Excellent" }], "checked": false },
    { "content": [{ "text": "Very Good" }], "checked": true },
    { "content": [{ "text": "Good" }], "checked": false },
    { "content": [{ "text": "Fair" }], "checked": false },
    { "content": [{ "text": "Poor" }], "checked": false }
  ]
}

{
  "type": "list",
  "style": "check",
  "items": [
    { "content": [{ "text": "Design mockups" }], "checked": true },
    { "content": [{ "text": "API integration" }], "checked": true },
    { "content": [{ "text": "Write tests" }], "checked": false }
  ]
}

A radio list with one pre-selected option (the item with checked: true renders as ●, the rest as ○):

{
  "type": "list",
  "style": "radio",
  "items": [
    { "content": [{ "text": "Pass" }], "checked": true },
    { "content": [{ "text": "Pass with corrections" }], "checked": false },
    { "content": [{ "text": "Fail" }], "checked": false }
  ]
}

Full Example

[
  {
    "type": "heading",
    "level": 1,
    "content": [{ "text": "Invoice Summary" }]
  },
  {
    "type": "paragraph",
    "content": [
      { "text": "Thank you for your order. " },
      { "text": "Order #12345", "bold": true },
      { "text": " has been confirmed." }
    ]
  },
  {
    "type": "table",
    "headers": [
      { "content": [{ "text": "Item" }] },
      { "content": [{ "text": "Qty" }] },
      { "content": [{ "text": "Price" }] }
    ],
    "rows": [
      [
        { "content": [{ "text": "Widget A" }] },
        { "content": [{ "text": "2" }] },
        { "content": [{ "text": "$49.99" }] }
      ]
    ]
  },
  {
    "type": "list",
    "style": "bullet",
    "items": [
      { "content": [{ "text": "Free shipping included" }] },
      { "content": [{ "text": "30-day return policy", "italic": true }] }
    ]
  },
  {
    "type": "list",
    "style": "check",
    "items": [
      { "content": [{ "text": "Payment received" }], "checked": true },
      { "content": [{ "text": "Order shipped" }], "checked": false }
    ]
  },
  { "type": "hr" },
  {
    "type": "paragraph",
    "align": "center",
    "content": [
      { "text": "Visit our website", "link": "https://example.com", "color": "#0563C1" }
    ]
  }
]

Supported in PDF and DOCX exports. The element's position and dimensions (x, y, width, height) from the report designer are used to place the rich content block.

Export Services

ZReport supports exporting rendered reports to multiple formats.

Export API

Generate reports in various formats programmatically using our REST API.

Authentication

All API requests require an API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys from your organization settings at Settings → API Keys.

Export Endpoints

POST https://api.zreport.cloud/api/export/pdf
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "reportId": "rpt_abc123",
  "data": {
    "orders": [
      { "id": 1, "product": "Widget", "amount": 99.99 }
    ]
  },
  "parameters": {
    "title": "Q4 Sales Report",
    "startDate": "2024-10-01"
  }
}

Code Examples

Playground

Test the Export API directly from this page.

Response

On success, the API returns the file as a binary stream with appropriate content-type headers. On error:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Report ID is required"
  }
}

Rate Limits

MCP Server

ZReport exposes a Model Context Protocol server that lets AI agents (Claude Desktop, Claude Code, ChatGPT, custom integrations) read, generate, and design reports in your organization — programmatically, in natural language.

1POST https://api.zreport.cloud/mcp
2Authorization: Bearer zr_…
3Accept: application/json, text/event-stream

Prerequisites

• A ZReport organization with at least one project.
• An API key generated from Settings → API Keys (or via POST /api/v1/organizations/:orgId/api-keys). Tokens carry the zr_ prefix and are shown only once at creation. Legacy mr_ tokens issued before the rebrand keep working.

Connecting Clients

Most AI clients speak stdio MCP, so we bridge to the HTTP transport via the mcp-remote helper.

Claude Desktop

Edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

1{
2  "mcpServers": {
3    "zreport": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote",
8        "https://api.zreport.cloud/mcp",
9        "--header",
10        "Authorization: Bearer zr_abc123..."
11      ]
12    }
13  }
14}

Restart Claude Desktop. The 24 ZReport tools appear in the tools panel.

Claude Code

Drop the same block into .mcp.json at your workspace root, or into ~/.claude/mcp.json for a global config.

ChatGPT (Custom GPTs)

1. Create a new Custom GPT.
2. Open Connectors → Add MCP Server.
3. URL: https://api.zreport.cloud/mcp
4. Authorization header: Bearer zr_abc123...

MCP Inspector (Testing)

For one-off debugging, run the official inspector:

1npx @modelcontextprotocol/inspector

Opens a UI at http://localhost:6274. Choose Streamable HTTP, paste the ZReport URL, add the Authorization header, and click Connect.

Tools & Resources

The server exposes 24 tools across three groups, plus rich resource feeds for schemas and existing reports.

Read

Generate

Design

Multi-page reports

Reports can carry multiple pages (ReportDefinition.pages: Page[]). Each page has its own bands and renders as a distinct section:

• PDF: each page begins a fresh paper-page sequence; $V{PageNumber} counts continuously across the whole document.
• DOCX: each page becomes its own section — new sections start on a new physical page.
• Excel: each page becomes its own worksheet, named from Page.name.

The band and element tools target a specific page where applicable:add_band and add_group accept an optional pageId(defaults to the first page); single-instance bands like pageHeader /detail / pageFooter are scoped per page — each page can have its own. update_band, add_element,update_element, and remove_element look their target up by id across every page, so they work regardless of which page it lives on.

Batched design with apply_operations

For anything more than a one-line tweak, batch your mutations into a singleapply_operations call. Each entry has the same shape as the matching single-op tool, minus the top-level reportId, plus an op discriminator (named op rather than type because several schemas already usetype for the value's own type and would otherwise collide):

1{
2  "reportId": 42,
3  "operations": [
4    { "op": "set_data_source", "dataSourceId": "..." },
5    { "op": "add_parameter",   "name": "asOf", "type": "date" },
6    { "op": "add_band",        "type": "pageHeader", "height": 30 },
7    { "op": "add_element",     "bandId": "band-...", "element": { /* full element */ } },
8    { "op": "update_band",     "bandId": "band-...", "height": 25 }
9  ]
10}

• Atomic. All ops run in one db transaction. If any fails, nothing is persisted.
• Pre-validation. Element shapes parse before the transaction opens; Zod errors come back with paths like operations[3].element.font.size.
• Error locator. Failures include data.opIndex and data.opType so the model can target the fix.
• Cap: 200 ops per call. Split into turns above that.

Resources

Beyond tools, the server publishes resource URIs that agents can fetch for richer context:

Expressions

Most element fields and variables accept the same expression syntax used in the designer:

• $F{fieldName} — current row's field value
• $P{paramName} — scalar parameter passed at generation time
• $V{variableName} — computed variable (often an aggregate)
• $R{paramName} — rich content (HTML / structured text) sourced from a parameter. Use inside a text element with isRichText: true to inject formatted text, tables, or images. Distinct from $P, which yields a plain scalar.
• Function calls — sum($F{amount}), format($F{date}, 'yyyy-MM-dd'), upper($F{name})

Typical Workflow

1. Discover — list_projects, list_data_sources, get_data_source_schema.
2. Create — create_report, set_data_source, add_parameter.
3. Design — add_band, add_group, add_element.
4. Populate — add_field, add_variable, update_element with expressions.
5. Generate — generate_report for a sample preview.
6. Iterate — refine via update_element and update_band.
7. Export — final generate_report in PDF / Excel / DOCX.

Limits, Errors & Security

Rate Limits (per API key)

Generated files larger than 25 MB return a download URL only (no inline base64). Download URLs are single-use and expire after 1 hour.

Error Kinds

MCP errors carry a structured data.kind field for programmatic handling:

Troubleshooting

Privacy & Security

• API tokens are bearer credentials. Treat them like passwords — they grant full access to the issuing organization.
• Tokens are SHA-256 hashed at rest. The full value is shown only once at creation; lost tokens must be regenerated.
• Tokens are redacted from access logs (URL-path tokens are rewritten before logging) and from audit arguments (sensitive keys like password, token, secret are replaced with ***).
• Cross-org access returns not_found, never forbidden — this prevents disclosing the existence of resources owned by other organizations.