Batch Reports

What this page describes is the mechanism. The specific kinds — document types, fields, statuses — are defined for your organization; yours may differ. See the entity system.

A report in CityScreen Deals is a bulk document merge — the system generates one combined output file from a template and a set of document records.

For metrics and charts, see dashboards.

Report types

A report type defines what kind of documents can be merged and which template is used to produce the output. The administrator creates report types and binds each one to a document type and a template file.

Only document types can serve as the source for a report type.

Generating a report

From the document list, optionally filtered by type and custom fields, choose Create report. Select a report type, give the report a name, and confirm.

The system queues the generation job. It runs in the background — you do not need to keep the page open. For large data sets, generation can take a significant amount of time.

When the job completes, the report appears in the reports list with status Created and a download link.

Filter values in the template

When a report is generated from a filtered document list, the search criteria the user applied are captured and injected into the template context under the key filter.

This lets the generated workbook display which filters produced the data set — useful for cover sheets, headers, and audit trails.

Accessing filter values

On any sheet of the template, use {{filter.<key>}} where <key> matches the search-criteria key:

Report filters:
  Document type: {{filter.documentType.id}}
  Region:        {{filter.variableValues.region}}

The filter object mirrors the search criteria hierarchy. Dot-separated criteria like variableValues.region become nested paths:

Search criteria key Template placeholder

name

{{filter.name}}

documentType.id

{{filter.documentType.id}}

variableValues.region

{{filter.variableValues.region}}

Inside a repeating section, use the root-context prefix to reach filter values from within a loop:

{{#items}}
  Region filter: {{$.filter.variableValues.region}}
  Document name: {{name}}
{{/items}}

Downloading a report

A report can be downloaded only when its status is Created. Reports that are still being generated (status Creating) do not yet have a file to download.

When a report fails

If generation encounters an error, the report’s status is set to Failed.

If a report fails:

  • Check whether the underlying template is valid — the same blank-output issues that affect single-document generation (misspelled placeholders, legacy syntax, corrupt template) can cause a batch job to fail. See template troubleshooting for the full list of common causes.

  • If the template is correct, contact your administrator.

Deleting reports

Reports can be deleted individually. Deletion requires the appropriate permission for the report’s type.

Related pages