{"title":"OnAfterSetupPrinters Event","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-onaftersetupprinters-event/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-onaftersetupprinters-event, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-onaftersetupprinters-event","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Describe the OnAfterSetupPrinters Event in Business Central.","date":"2021-04-01","meta":{"topic":"article"},"outline":[{"level":2,"title":"Usage","slug":"usage","at":96,"chars":447},{"level":2,"title":"Publisher","slug":"publisher","at":543,"chars":43},{"level":2,"title":"Raised","slug":"raised","at":586,"chars":431},{"level":2,"title":"Syntax","slug":"syntax","at":1017,"chars":143},{"level":2,"title":"Parameters","slug":"parameters","at":1160,"chars":489},{"level":2,"title":"Printer payload","slug":"printer-payload","at":1649,"chars":6601},{"level":3,"title":"Attributes","slug":"attributes","at":2753,"chars":5497},{"level":2,"title":"Related information","slug":"related-information","at":8250,"chars":332}],"text":"This article describes the OnAfterSetupPrinters event and the structure of the printer payload.\n## Usage\nUse the OnAfterSetupPrinters event to set up different printers that users can use to print reports. Users can set which printer to use on the Printer Selections page. By subscribing to this event, you create payloads for different printers. A payload specifies settings such as paper sizes, paper trays, and more. For more information about subscribing to this event, see Developing Printer Extensions Overview<devenv-reports-printing>.\n## Publisher\nCodeunit 44 ReportManagement.\n## Raised\nThe OnAfterSetupPrinters event is raised when you:\n Open a page that uses the virtual table Printer as its source is opened in the client.\n Select the lookup on the Printer Name field in page 64 Printer Selections. This field is used for selecting a printer to use on a report.\n Select the Print or Preview action on the request page of a report that is set up to use a specific printer from the Printer Selections page.\n## Syntax\n```al\n[IntegrationEvent(false, false)]\nlocal procedure OnAfterSetupPrinters(var Printers: Dictionary of [Text[250], JsonObject])\n```\n## Parameters\nPrinters\nThe Printers parameter is a Dictionary of [Text, Text]<methods-auto/dictionary/dictionary-data-type> type. It includes a collection of key-value pairs that define different printer setups. The key specifies a name for the printer. The value is a JSON object that specifies various settings supported by the printer. The settings include information like the paper size, paper trays, default number of copies, and more. The JSON object is referred to as the payload.\n## Printer payload\nThe payload consists of several attributes that are arranged in the following structure.\n```json\n{\n    \"version\":,\n    \"description\":,\n    \"duplex\":,\n    \"color\":,\n    \"defaultcopies\":,\n    \"papertrays\":\n    [\n        {\n            \"papersourcekind\":,\n            \"paperkind\":,\n            \"units\":,\n            \"height\":,\n            \"width\":,\n            \"landscape\":\n        }\n    ]\n}\n```\n The version and papertrays attributes are mandatory.\n The papertrays attribute must contain at least one paper tray setup.\n Each individual paper tray setup is defined within brackets `{ }` and must include the attributes papersourcekind and paperkind.\nGiven this information, the minimum payload looks like this:\n```json\n{\n    \"version\":1,\n    \"papertrays\":\n    [\n        {\n            \"papersourcekind\":\"Upper\",\n            \"paperkind\":\"A4\"\n        }\n    ]\n}\n```\nIf the required attributes aren't provided, a general error similar to the following error occurs at runtime:\n\"The provided payload for printer 'My Printer' is not formatted correctly. Please update the payload and try again.\"\n### Attributes\nversion\nCurrently, the only supported version for the payload is `1`. If the value is less than or greater than 1, an invalid payload version error like the following error is shown:\n\"The payload version '2' is not valid for the printer 'My Printer'. The version must be a positive number not greater than 1. Please change the version and try again.\"\ndescription\nSpecifies an alternative or friendly name for the printer. The value can include 250 characters. If the value is greater than 250, an invalid payload version error like the following error is shown:\n\"The description of the printer 'My Printer' exceeds the limit of 250 characters (current length: 300 characters). Please change the description and try again.\"\nduplex\nSpecifies whether the printer supports duplex (double-sided) printing. true specifies that the printer supports duplex printing; false specifies that it doesn't.\n> NOTE\n> duplex is currently not used and ignored at runtime.\ncolor attribute\nSpecifies whether the printer supports color printing. true specifies that the printer supports color printing; false specifies that it doesn't.\n> NOTE\n> color is currently not used and ignored at runtime.\ndefaultcopies\nSpecifies the number of copies to print by default. The value must be a non-negative integer that isn't greater than 32767.\n> NOTE\n> defaultcopies is currently not used and ignored at runtime.\nIf the value exceeds 32767, an error like the following error is shown:\n\"The provided payload for printer 'My Printer' is not formatted correctly. Please update the payload and try again.\"\nIf the value is less than 0, an error like the following error is shown:\n\"The value for the default copies parameter for the printer 'My Printer' must be a positive number. Please update the parameter and try again.\"\npapertrays\nSpecifies a setup for one or more paper trays that the printer has. Each paper tray setup is defined within a set of brackets `{ }` and separated by a comma. A paper tray setup must contain a papersourcekind and paperkind attribute. Other attributes are optional.\nThere can be a maximum of 14 paper trays. The first defined paper tray in the list will be considered as the default paper tray.\nIf the papertray attribute is empty, an error like the following error occurs:\n\"The provided payload for printer 'My Printer' is not formatted correctly. Please update the payload and try again.\"\npapersourcekind\nSpecifies a standard paper source for the paper tray. You can set the value to any of the 14 paper sources that are supported by .NET Framework. You can see the supported paper sources at PaperSourceKind Enum<https://learn.microsoft.com/dotnet/api/system.drawing.printing.papersourcekind>. You can either use the text representation (such as AutomaticFeed or the corresponding number (such as `7`).\nThe papersourcekind must be unique within the paper trays, meaning it cannot be used more than once in the list. If values for papersourcekind are not unique, an error like the following error occurs:\n\"The printer 'My Printer' already has the paper source kind 'Upper'. Please change the paper source kind and try again.\"\npaperkind\nSpecifies the paper sizes supported by the printer. You set the value to any standard paper kind that .NET Framework supports. You can see the supported paper kinds at PaperKind Enum<https://learn.microsoft.com/dotnet/api/system.drawing.printing.paperkind>. You can either use the text representation (such as A4) or the corresponding number (such as `9`).\nIf you use any value other than Custom or `0`, the system will automatically take care of the height, width, and units attributes. For example, if you specified that paperkind is A4, then the paper dimensions are 210 mm by 297 mm. In this case, if you provide values for the height, width, and units attributes, the values will be ignored.\nIf paperkind is set to Custom or `0`, then paper size is defined by the user in the client. However, you must provide proper values for height and width attributes; otherwise an error will occur. The values are used as the default values for the custom size. So if you don't set an attribute, then 0 is used, which isn't valid. Additionally, if the paperkind is Custom or `0`, you can also specify unitsattribute.\nunits\nSpecifies the units of measurement for values in height and width attributes. Valid values include:\n HI for hundredths of an inch. This value is the default value.\n TI for thousandths of an inch.\n IN for inches.\n CM for centimeters.\n MM for millimeters.\n PC for picas.\n PT for points.\nIf you provide a unit that isn't valid, the following error is shown:\n\"The provided payload for printer 'My Printer' is not formatted correctly. Please update the payload and try again.\"\nheight and width\nSpecifies the dimensions of the paper. Set these attributes only when the paperkind is set to Custom.\nValid values include positive integers up to 2147483647. If the provided value exceeds the limit, an error like the following error occurs:\n\"The provided payload for printer 'My Printer' is not formatted correctly. Please update the payload and try again.\"\nIf the value is less than 1, an error like the following error occurs:\n\"The paper 'height' must be a positive number (paper kind = 'Custom', paper source kind = 'Custom', printer = 'My Printer'). Please update the 'height' parameter and try again.\"\nlandscape\nSpecifies whether landscape orientation is supported. true specifies landscape orientation is supported; otherwise false.\n## Related information\nWorking With and Troubleshooting Payloads<devenv-reports-troubleshoot-printing>\nDeveloping Printer Extensions Overview<devenv-reports-printing>\nCreating a Printer Extension<devenv-reports-create-printer-extension>\ndevenv-events-in-al\ndevenv-publishing-events\ndevenv-raising-events\ndevenv-subscribing-to-events"}