--- title: "Reports" description: "Comprehensive guide on executing and customizing report mutations, including parameters and result structures, for generating business documents in software applications." lang: en languages: en: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/reports/index.md lastmod: 2026-07-10 --- > Documentation index: https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/llms.txt # Reports Last modified July 10, 2026 > Comprehensive guide on executing and customizing report mutations, including parameters and result structures, for generating business documents in software applications. Reports are business logic operations that typically result in one or more documents. Reports have many similarities with [processings](https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/processings/index.md). They have the very same structure for parameters and results. They are also available as mutation requests. However, unlike processings, they return documents and attachments. > [!WARNING] > > Line, processings, they are potentially long running operations. The time to execute a report may exceed the timeout of the HTTP request. In this case, you would get back an error status even though the process continues to run in the background and may finish successfully. Reports are associated with a table and a table can have multiple reports. However, not all tables have reports. For each table that provides reports, a field called `_reports` is available. The type of this field is called `Reports`. For instance, for the `Order` table, the reports field is called `order_reports` and its type is called `OrderReports`. You can see this in the following image: ![Mutation schema](https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/reports1.png) Under each field of this form, there is one field for each report available for the table. For instance, for the `Order` table, there are multiple reports such as `pickList`, `packingSlips`, `orderConfirmations`, `orderPrints`, etc. These are available under the field `order_reports`. This is shown in the next image: ![Report schema](https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/reports2.png) The following query shows an example for executing the order confirmation report for an order. ```graphql { title = "Query" } mutation run_report($cid : Int!, $ono : Int!) { useCompany(no : $cid) { order_reports { orderConfirmations( filter : { orderNo :{_eq: $ono} } ) { succeeded documents { name content } } } } } ``` ```graphql { title = "Result" } { "data": { "useCompany": { "order_reports": { "orderConfirmations": { "succeeded": true, "documents": [ { "name": "200022.pdf", "content": "JVBERi0xLjQKJdDExrT...", } ] } } } } } ``` ## Arguments Reports may have multiple arguments, as shown in the following table. All these arguments are optional. | Field | Type | Description | | ----- | ---- | ----------- | | `filter` | `FilterExpression_` | Allows for selecting the table rows that will be processed. This is the same filter used for querying data from the table. You can read more about that here: [Filtering](https://docs.vismasoftware.no/businessnxtapi/apireference/features/filtering/index.md). | | `args` | `Reports__Parameters` | Provides various arguments for the reporting process. | | `returnDocuments` | `bool` | Indicates whether documents should be returned as part of the result. When present, their content is available as base64-encoded text. | | `splitAttachments` | `bool` | Indicates whether attachments, when available, should be split into separate PDFs. Attachment content is available as base64-encoded text. | | `approval` | `bool` | When this value is `true` (which is the default if not specified) tables in the database will be updated, if applicable for the report. E.g. for order documents (like invoices), the tables with order lines and reservations will accumulate quantities processed so far. The documents may be archived in the database, and vouchers may be produced. The `Approval` property can be set to `false` when you only preview results. | | `documentDate` | `date` | Can be used by the business logic, depending on the actual report (e.g. as the invoice date), as well as be displayed on the printed form. | | `valueDate` | `date` | Used when producing vouchers (as part of the approval processing), to determine the accounting period and VAT period, if applicable for the report. | | `formNo` | `int` | The form number for the document type/form type. The value 0 (the default) indicates the default form. | | `printDestination` | `PrintDestination` | Specify different options for the result documents. | | `landscape` | `bool` | Indicates whether the report should be printed in landscape orientation. | | `mergeDocuments` | `bool` | Indicates whether the generated documents should be merged into a single PDF file. | | `zipDocuments` | `bool` | Indicates whether generated documents to be returned as a single ZIP archive. | | `breakBy` | `[_BreakBy!]` | Indicates whether the report should be split into multiple documents based on the specified break by options. | | `subTableQuery` | `_TableQuery` | Query options (filter, ordering, aggregation) applied to the report's sub-table. Available only for reports that define a sub-table. | ### Printing The following options are available for printing destination: | Destination | Description | | ----------- | ----------- | | `PRINT_TO_PDF` | Produces PDF files. This is the default value. | | `PRINT_TO_DEFINED_DESTINATIONS` | Distributes the documents according to "Document delivery methods" on the order/associate, if applicable for the report. The destination can be a selection for whether to use one or more of mail, e-mail, fax, EDI, and AutoInvoice, depending on the actual order; suggested from the customer or supplier. | | `SEND_EMAIL` | Sends PDFs by e-mail. | | `ONLY_APPROVAL` | Approves the documents without printing them (i.e. writes only to the database). | The execution of the order confirmation report is shown again here, this time with all the possible arguments: ```graphql { title = "Mutation" } mutation run_report($cid : Int!, $ono : Int!) { useCompany(no : $cid) { order_reports { orderConfirmations( returnDocuments :true splitAttachments : true approval : true formNo : 0 printDestination : PRINT_TO_PDF documentDate : "2022-03-01" valueDate : "2022-03-01" filter : { orderNo :{_eq: $ono} } ) { succeeded documents { name content attachments { name content } } } } } } ``` ```graphql { title = "Result" } { "data": { "useCompany": { "order_reports": { "orderConfirmations": { "succeeded": true, "documents": [ { "name": "200022.pdf", "content": "JVBERi0xLjQKJdDExrT...", "attachments": [] } ] } } } } } ``` ### The breakBy argument The `breakBy` is an optional argument that controls how report rows are grouped into sections (page breaks). You specify an ordered list of columns. Each column defines a break level. When the value of a break column changes between rows, a new section/page break is inserted in the report. Example: ```graphql breakBy: [ { invoiceCustomerNo: true }, { paymentTerms: true }, { currencyNo: true } ] ``` Each element in the array is an object with a single column set to true. The order of elements defines the break hierarchy (first element = outermost break level). However, for the `Order` table only, you can specify break columns for the `OrderLine` sub-table. ```graphql breakBy: [ { invoiceCustomerNo: true }, { paymentTerms: true }, { currencyNo: true }, {_thenBy : {orderNo : true}} ] ``` `_thenBy` can only be used when at least one break column is also specified. The following snippet shows how to execute the `invoicesAndCreditNotes` report on the `Order` table. ```graphql mutation invoice_order($cid: Int!, $ono1: Int, $ono2 : Int) { useCompany(no: $cid) { order_reports { invoicesAndCreditNotes( filter: {orderNo: {_in: [$ono1, $ono2]}} approval: true printDestination: PRINT_TO_PDF returnDocuments : true args: { formNo: 61, userDefinedSorting: 1, accounting: 1, directUpdate: 1, batchInvoices: 1, groupingByOrder: 1 }, breakBy : [ {invoiceCustomerNo : true}, {paymentTerms : true}, {currencyNo : true}, {_thenBy : {orderNo : true}} ] ) { succeeded documents { name content } } } } } ``` Requirements for `breakBy` columns: | Report | Table | breakBy columns | themBy columns | | ------ | ----- | --------------- | -------------- | | `invoicesAndCreditNotes` | `Order` | `invoiceCustomerNo`, `paymentTerms`, `currencyNo` | `orderNo` | > [!TIP] > > If you don't know what reports are available for each table, or what each report is doing, you can get this information using the schema explorer, available in both GraphiQL and Insomnia. The images at the beginning of this page demonstrate this. ### The subTableQuery argument `subTableQuery` is an optional argument available for reports that define a sub-table. It allows you to specify query options (filter, ordering, aggregation) applied to the report's sub-table. The following snippet shows how to execute the `invoicesAndCreditNotes` report on the `Order` table, with a `subTableQuery` argument. ```graphql mutation invoice_order($cid: Int!, $ono1: Int, $ono2 : Int) { useCompany(no: $cid) { order_reports { invoicesAndCreditNotes( filter: {orderNo: {_in: [$ono1, $ono2]}} approval: true printDestination: PRINT_TO_PDF returnDocuments : true args: { batchInvoices: 1, groupingByOrder: 1 }, subTableQuery :{ filter : { free3 : {_gt : 0} }, orderBy : [{customerNo :DESC}], includeTotalLine : true }, breakBy : [ {invoiceCustomerNo : true}, {paymentTerms : true}, {currencyNo : true}, {_thenBy : {orderNo : true}} ] ) { succeeded documents { name content } } } } } ``` --- [View this page](https://docs.vismasoftware.no/businessnxtapi/apireference/schema/mutations/reports/)