How can we create most efficient/performant report layouts?

The report engine and designer used for Apportunix Document Creator offers a rich set of features and capabilities. It is quite fast at rendering reports, but it’s good to keep a few things in mind to ensure that you develop report layouts that perform well.

This article discusses some tips  and recommendations for you to consider to improve the rendering time for your report layouts.

Dataset Size

To start off, the size of your dataset may have a great impact on your report’s performance. For example, including a lot of (repeated) pictures can result in a large XML dataset file. This results in long loading times before the engine even starts rendering.

Therefore it is good practice to avoid duplicating pictures, e.g., only send the same company logo once instead of multiple times per document header or even per document line. Avoid including item pictures if they are not used in the layout.

We also recommend aggregating your data in the report object definition as much as possible, instead of doing that in the report layout. The report layout should primarily be used to define the presentation of the output, and should avoid processing data (such as aggregation or other logic) as much as possible. In general, avoid including too many records, for example, do not include the G/L entry records for an entire year in your dataset, but instead use filtering and make sensible decisions on which data to include.

Finally, it’s good to check for columns and data items in your report objects that are unused. To determine which columns and data items are actually used by report layouts in your Business Central environment, the Apportunix Document Creator extension has Layout Column Usage Analysis Tooling that helps you analyze this.

Analyzing the Dataset for Unused Columns

Let’s have look at this tooling now. From the Report Layouts and Document Creator User-Defined Report Layouts page you can access the View Columns action (under the Dataset action group) to open an overview of the columns are currently being used by any report layout.



The View Columns action opens a page where you can view all columns in the report object, together with the following fields that tell you if the column is used:

  • Used by Any Report Layout - Specifies whether the column is used by any Document Creator report layout that exists for the report object.
  • Used by Selected Report Layout - Specifies whether the column is used by the selected Document Creator report layout.
  • Used by Filter Set Filters - Specifies whether the column is used by any filter set filters for dataset extensions for the report object. It is possible to drill down on this field to view the filter sets that reference the column.




Additionally, the Column Name will be displayed in Red if it’s not used by any report layout or filters for custom columns  in the current Business Central environment. If it’s an unused Custom Column, it will displayed in Bold + Red. These are columns that are likely candidates to be removed from the report to improve performance.



To summarize, you can use this tooling to reduce the size of your report datasets by doing one or more of the following:

  • • For custom report objects, adjust the base report object definition to exclude all columns that are not used in any way by any of the layouts.
  • Remove unused dataset extensions, i.e., columns and/or data items that are not used in any way by report layouts in your environment.


This is also a good time to make a special mention of the (experimental) Compress Render Requests setting on the Document Creator Setup page. When enabled, this setting removes all columns from the dataset that are unused in the selected report layout before sending it out to be rendered. Note that this adds a small amount of processing time for removing the unused columns and should therefore not be used for reports that are already optimized.

Image Size Considerations

Embedding large picture objects in the layouts themselves (instead of via dataset columns) can increase the layout size and rendering time.

Consider if the image should be included in its original size and resolution or if it can be removed. Company logos and branding materials specifically are often supplied in offset printing quality, but do you really need a 4K resolution to print a small logo?

In addition, look at large, unused areas in images. For instance, if you applied a letterhead image to the report as watermark or background that includes a small logo at the top and address and contact information at the bottom, and is otherwise just empty space, then cut it up into separate parts that are just large enough to hold the actual images needed, and position each on the report independently.

In general, try to remove large embedded picture objects from the layout or reduce them in size.

RichText

Rendering RichText controls costs considerably more time than plain text. Consider replacing RichText elements with regular TextObject controls that can be rendered more efficiently if you do not need to use RichText.

Overlays or Watermarks

Overlays and watermarks can also be potential causes for problems, especially when they hold a lot of content or content that has a large size. Consider adjusting your overlay bands’ and/or watermark contents, and cutting images up into small pieces instead of having one big image with a lot of empty space.

Disable Double Pass

Double pass handles functionality like adding running/per page totals, showing the total page count of a report (e.g. “Page 1 of 10”), and similar summations and counting. You can safely disable Double pass if you don’t use those in the page headers to save some time when the report is being prepared for rendering.

To disable Double pass, open the Report Options window and then disable the Double pass setting on the General tab.



Move Report Rendering to a Background Task

To improve the user experience, it’s also good to consider moving the report rendering to a background task, e.g., schedule report runs as job queue entries. This will greatly improve the user experience for users that need to wait for a report run to complete before they can continue with their other work/tasks in Business Central, as they don’t see their screen “freezing” for a short time while the report is processed asynchronously.

For example, for processing/mailing your sales documents in the background, you may want to consider using the Apportunix Document Mail Queue extension.

This recommendation strongly applies to situations where report renders are triggered from external devices like those used in warehouse scanning or point of sale solutions.

On-Premises Considerations

When running the Document Creator rendering on on-premises servers, please take the following into account:

  • • If the Business Central NST server is hosted on an Azure host, then please make sure to have a performant host (e.g., a host with acceptable IOPS that has been assigned sufficient resources to be compliant with recommended Business Central specifications).
  • • Of course, the same also applies if your servers are hosted by another party. Ensure these machines comply with recommended specifications, and run tests to check if throughput and latency are acceptable.
  • • Check for typical performance degradations caused by anti-malware agents scanning the process that renders report layouts. Consult with your IT specialists to ensure the security setup is not degrading your performance.

Setting up a Dedicated API

Apportunix Document Creator continuously monitors the performance of the general rendering API and adjusts configurations when necessary to ensure acceptable rendering times. The resources are scaled up based on the number of concurrent requests that the API receives. To make sure all users have acceptable performance, and prevent a few “bulk users” to from degrading overall performance for other users, we also monitor for “acceptable usage”, as described in our end-user license agreement (EULA) (section about Acceptable Usage Policy).

If you have a demand for unusually high-volume report rendering, or if you want to run your report rendering on a private API without sharing resources with other users, you can reach out to us for setting up a dedicated API instance. A dedicated API instance can be scaled to meet the needs and requirements of your company and ensure even more stability in performance.

The report engine and designer used for Apportunix Document Creator offers a rich set of features and capabilities. It is quite fast at rendering reports, but it’s good to keep a few things in mind to ensure that you develop report layouts that perform well.

This article discusses some tips  and recommendations for you to consider to improve the rendering time for your report layouts.

Dataset Size

To start off, the size of your dataset may have a great impact on your report’s performance. For example, including a lot of (repeated) pictures can result in a large XML dataset file. This results in long loading times before the engine even starts rendering.

Therefore it is good practice to avoid duplicating pictures, e.g., only send the same company logo once instead of multiple times per document header or even per document line. Avoid including item pictures if they are not used in the layout.

We also recommend aggregating your data in the report object definition as much as possible, instead of doing that in the report layout. The report layout should primarily be used to define the presentation of the output, and should avoid processing data (such as aggregation or other logic) as much as possible. In general, avoid including too many records, for example, do not include the G/L entry records for an entire year in your dataset, but instead use filtering and make sensible decisions on which data to include.

Finally, it’s good to check for columns and data items in your report objects that are unused. To determine which columns and data items are actually used by report layouts in your Business Central environment, the Apportunix Document Creator extension has Layout Column Usage Analysis Tooling that helps you analyze this.

Analyzing the Dataset for Unused Columns

Let’s have look at this tooling now. From the Report Layouts and Document Creator User-Defined Report Layouts page you can access the View Columns action (under the Dataset action group) to open an overview of the columns are currently being used by any report layout.

The View Columns action opens a page where you can view all columns in the report object, together with the following fields that tell you if the column is used:

  • Used by Any Report Layout – Specifies whether the column is used by any Document Creator report layout that exists for the report object.
  • Used by Selected Report Layout – Specifies whether the column is used by the selected Document Creator report layout.
  • Used by Filter Set Filters – Specifies whether the column is used by any filter set filters for dataset extensions for the report object. It is possible to drill down on this field to view the filter sets that reference the column.

Additionally, the Column Name will be displayed in Red if it’s not used by any report layout or filters for custom columns  in the current Business Central environment. If it’s an unused Custom Column, it will displayed in Bold + Red. These are columns that are likely candidates to be removed from the report to improve performance.

To summarize, you can use this tooling to reduce the size of your report datasets by doing one or more of the following:

  • For custom report objects, adjust the base report object definition to exclude all columns that are not used in any way by any of the layouts.
  • Remove unused dataset extensions, i.e., columns and/or data items that are not used in any way by report layouts in your environment.

This is also a good time to make a special mention of the (experimental) Compress Render Requests setting on the Document Creator Setup page. When enabled, this setting removes all columns from the dataset that are unused in the selected report layout before sending it out to be rendered. Note that this adds a small amount of processing time for removing the unused columns and should therefore not be used for reports that are already optimized.

Image Size Considerations

Embedding large picture objects in the layouts themselves (instead of via dataset columns) can increase the layout size and rendering time.

Consider if the image should be included in its original size and resolution or if it can be removed. Company logos and branding materials specifically are often supplied in offset printing quality, but do you really need a 4K resolution to print a small logo?

In addition, look at large, unused areas in images. For instance, if you applied a letterhead image to the report as watermark or background that includes a small logo at the top and address and contact information at the bottom, and is otherwise just empty space, then cut it up into separate parts that are just large enough to hold the actual images needed, and position each on the report independently.

In general, try to remove large embedded picture objects from the layout or reduce them in size.

RichText

Rendering RichText controls costs considerably more time than plain text. Consider replacing RichText elements with regular TextObject controls that can be rendered more efficiently if you do not need to use RichText.

Overlays or Watermarks

Overlays and watermarks can also be potential causes for problems, especially when they hold a lot of content or content that has a large size. Consider adjusting your overlay bands’ and/or watermark contents, and cutting images up into small pieces instead of having one big image with a lot of empty space.

Disable Double Pass

Double pass handles functionality like adding running/per page totals, showing the total page count of a report (e.g. “Page 1 of 10”), and similar summations and counting. You can safely disable Double pass if you don’t use those in the page headers to save some time when the report is being prepared for rendering.

To disable Double pass, open the Report Options window and then disable the Double pass setting on the General tab.

Move Report Rendering to a Background Task

To improve the user experience, it’s also good to consider moving the report rendering to a background task, e.g., schedule report runs as job queue entries. This will greatly improve the user experience for users that need to wait for a report run to complete before they can continue with their other work/tasks in Business Central, as they don’t see their screen “freezing” for a short time while the report is processed asynchronously.

For example, for processing/mailing your sales documents in the background, you may want to consider using the Apportunix Document Mail Queue extension.

This recommendation strongly applies to situations where report renders are triggered from external devices like those used in warehouse scanning or point of sale solutions.

On-Premises Considerations

When running the Document Creator rendering on on-premises servers, please take the following into account:

  • If the Business Central NST server is hosted on an Azure host, then please make sure to have a performant host (e.g., a host with acceptable IOPS that has been assigned sufficient resources to be compliant with recommended Business Central specifications).
  • Of course, the same also applies if your servers are hosted by another party. Ensure these machines comply with recommended specifications, and run tests to check if throughput and latency are acceptable.
  • Check for typical performance degradations caused by anti-malware agents scanning the process that renders report layouts. Consult with your IT specialists to ensure the security setup is not degrading your performance.

Setting up a Dedicated API

Apportunix Document Creator continuously monitors the performance of the general rendering API and adjusts configurations when necessary to ensure acceptable rendering times. The resources are scaled up based on the number of concurrent requests that the API receives. To make sure all users have acceptable performance, and prevent a few “bulk users” to from degrading overall performance for other users, we also monitor for “acceptable usage”, as described in our end-user license agreement (EULA) (section about Acceptable Usage Policy).

If you have a demand for unusually high-volume report rendering, or if you want to run your report rendering on a private API without sharing resources with other users, you can reach out to us for setting up a dedicated API instance. A dedicated API instance can be scaled to meet the needs and requirements of your company and ensure even more stability in performance.