ReportBuilder

ReportBuilder methods are used to read builder metadata, validate report drafts, create queued builder report requests, and retrieve prepared builder results.

Filter metadata uses the shared FilterField properties: field, datatype, filter_type, multiple, operators, and required. Report-specific labels, option_source, applies_to_sources, and order extend that contract. Use the selected domain's GetSchema response as the catalog of allowed fields and operators.

Drafts and report requests use the shared Filter array with Field, Operator, and string Value. For In, pass comma-separated values; dates use Unix seconds, and datatype int supports 64-bit integers. Omit an optional filter to select all available values. Empty values, duplicate fields, unsupported operators, and field-reference placeholders are rejected. Validate also determines filters required by the chosen report structure.

Company and warehouse checks apply to domains whose schemas declare firm_id and stock_id. Crm and WorkTime do not require firm_id.

Building the filter and option panel

  1. Load GetSchema once per selected domain. Use filter metadata to choose inputs and option value_type, allowed_values, default_value, min_value and max_value to build option controls.
  2. Send the current structure, filters and options to Validate after edits. An incomplete draft is supported: missing required filters produce valid=false together with panel metadata.
  3. Join availability.filters by schema.filters.field and availability.options by schema.options.code. Show controls with enabled=true, mark required=true, and use reason_code to explain disabled controls. A filter can affect a metric even when its corresponding entity is not displayed as a column.
  4. Use applies_to_sources and applies_to_metrics from the resolved control state to explain partial applicability in mixed-source reports. The backend applies each filter only to its advertised sources.
  5. Use effective_parameters to inspect normalized active inputs. Compilation and execution use the same resolution. Inactive values are discarded with inactive_filter_ignored or inactive_option_ignored warnings. Invalid filter syntax is still reported; omit empty or inactive filters from requests.
  6. Submit AddRequest only when valid=true. Company and warehouse permissions remain enforced before queuing. Ignore stale Validate responses when newer edits have already been sent.

Option scope=execution means the backend applies the value. For scope=presentation, read the effective options from the decompressed prepared report: show_group_totals controls aggregate values on group rows, while expand_first_level controls initial expansion. Keep group labels and child rows accessible when hiding group totals. Options with execution_status=unsupported are hidden.

For example, stock_balance.current_quantity requires firm_id and date, while currency_id, price_type_id and cost_type are hidden. Adding stock_balance.stock_cost_amount enables cost_type and makes currency_id required. Adding stock_balance.retail_price requires price_type_id. ABC/XYZ thresholds and recommendation settings appear only in applicable drafts.

Known support limits are explicit in metadata: period_interval, tabular calculation options, and the Sales domain currency_id filter are unsupported. Period grouping comes from structure fields. Finance currency_id labels amount columns without converting amounts; Partner currency_id selects balance currency and labels trading amounts without conversion.