Skip to main content

Dynamic reports

Insights is the fastest way to get answers about your organization: you describe what you want in the AI dashboard builder and it assembles the widgets and queries for you.

Sometimes you want more control. When you need a report with a specific input form, exact queries, and a shape you define yourself, you can build it by hand as a dynamic report. Once published, it surfaces in Insights alongside the AI-generated dashboards, so your readers get to it the same way.

A dynamic report combines three things you define yourself:

  • A JSON Schema that defines the report's input fields.
  • A UI Schema that controls how those fields render as a form.
  • A set of queries that pull data and can populate field options.

Because reports use the same schema engine as the rest of nullplatform, you can reuse everything you already know from JSON UI Schema to design the form.

tip

If you just want a quick dashboard, start with the AI dashboard builder. Reach for dynamic reports when you need to hand-craft the form and queries.

Create a report with the np-report skill​

The recommended way to create a dynamic report is the np-report skill, part of the nullplatform AI plugins. Describe the report you want from your AI coding assistant (Claude Code, Kiro, or any tool that runs the plugins) and the skill writes the JSON Schema, the UI Schema, and the SQL queries for you, validates the queries against your organization's data, and saves the result as a draft you can review in Insights before publishing.

Create a report of deployments over time with filters for environment and date range

The skill proposes a plan and asks for confirmation before it persists anything, so you always see what it's about to create. To install the plugins, follow Set up the nullplatform AI plugins.

The rest of this page describes the pieces of a report, so you can review and fine-tune what the skill produces, or write a report from scratch.

What a report contains​

Besides the schema, the UI Schema, and the queries, a report has a name (the only required field), an optional slug and description, and a visibility setting that controls who can see it. The Reports API documents the full shape.

Queries​

The queries field maps a query ID to a query definition. A query runs a SQL SELECT and can populate a form field's options with the results.

Each query supports:

  • source: the SQL SELECT statement. It can include {name:Type} placeholders.
  • params: binds each placeholder to a form field. Each param has a scope, a JSON Pointer to the field (for example #/properties/environment).
  • target: a JSON Pointer to the schema property the query populates.
  • mapping: how results map onto the target field. Use enum to turn query results into the field's selectable options.

This is what makes reports dynamic: a query can read a value the user picked in one field and use it to populate the options of another.

{
  "environments": {
    "source": "SELECT name FROM environments WHERE account = {account:String}",
    "params": {
      "account": { "scope": "#/properties/account" }
    },
    "target": "#/properties/environment",
    "mapping": "enum"
  }
}

Visibility and access​

A report's visibility controls who can work with it. user reports are private: only the owner can see and edit them, within their own organization. organization reports are shared: everyone in the organization can see and edit them.

Next steps​