Reports

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. 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 <tablename>_reports is available. The type of this field is called <tablename>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

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

The following query shows an example for executing the order confirmation report for an order.

Query


mutation run_report($cid : Int!,
                    $ono : Int!)
{
  useCompany(no : $cid)
  {
    order_reports
    {
      orderConfirmations(
        filter :
        {
          orderNo :{_eq: $ono}
        }
      )
      {
        succeeded
        documents
        {
          name
          content
        }
      }
    }
  }
}

Result


{
  "data": {
    "useCompany": {
      "order_reports": {
        "orderConfirmations": {
          "succeeded": true,
          "documents": [
            {
              "name": "200022.pdf",
              "content": "JVBERi0xLjQKJdDExrT...",
            }
          ]
        }
      }
    }
  }
}

Reports may have multiple arguments, as shown in the following table. All these arguments are optional.

Field	Type	Description
`filter`	`FilterExpression_<tablename>`	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.
`args`	`<tablename>Reports_<reportname>_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.

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:

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
          }
        }
      }
    }
  }
}

Result


{
  "data": {
    "useCompany": {
      "order_reports": {
        "orderConfirmations": {
          "succeeded": true,
          "documents": [
            {
              "name": "200022.pdf",
              "content": "JVBERi0xLjQKJdDExrT...",
              "attachments": []
            }
          ]
        }
      }
    }
  }
}

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.

Last modified September 24, 2024