.. _out_spool: ================================================================== Automatic Output spooling to printers and archiving of spool files ================================================================== Application Reports that run on the Task Queue will generate output which are saved (in the run directory on the server where Maymyo Daemons are running) and may need to be printed (by our automatic spooling daemon). Reports can be sent to the Task Queue by the user by pressing the *Queue* button when running a report from the Dashboard. It can also be sent to the Task Queue by a :ref:`Scheduled Job `. Application Commands can generate outputs that are saved in the same run directory too. Anything that is printed to the standard output are saved in an output file. Unlike Report outputs, these output files may only be viewed or saved by the browser using the Dashboard's "View your Tasks" button. They will not be automatically printed. Your Commands can log debug information to be viewed later. When an Application Report is run interactively, then its output is sent (as an HttpResponse) back to the browser, which will ask to open or save (on the user's computer) the output. The user can then view or print them using printers connected to their own computer. So spooling does not involve these outputs as Maymyo does not save interactive Report's output. Layout of the output directory ------------------------------ .. image:: ../_static/out_spool/output_dir.png Layout of output directory The above shows the directories containing the outputs of Reports and Commands. All Queued Task will be assigned a handle to an output file in this directory. A Command need not be aware of this handle as the Task Queue will redirect all its standard output to this file (its errors will go to the Task Queue's log). A Report's Reporting Engine will be passed this handle to save its output. The directory *mayrun* is a sibling of *maymyo_home* and is specified in the *settings.py*. Under it will be the *outputs* directory where output of all queued Reports are saved. There are 2 levels of sub-directories. The first directory is named using the month the Report was run, in *YYYYMM* format. The second directory is named using the day of month the Report was run, ie 01 to 31. The output files are named using the Application Report's Resource Code (in lower-case) appended with the Queued Task id. Its suffix follows its Output Format type, eg for TEXT is .txt. (See the *REPORT-OUTPUT-FORMATS* Value Set's Attribute 1). Output Queues and automatic spooling ------------------------------------ The automatic spooling daemon will read all queued Report output as soon as they are generated and send them to their designated printer (as long as that printer is Online and have the correct Paper mounted). If the designated printer is not ready, then the output will be held until somebody change the Output Queue's Online status and Paper mounted. Each Report can have an Output Queue defined, overriding the default of its Reporting Engine. When both Output Queues are not defined (ie at Report and Engine level), then the Application Default will be used. Printers are pointed to by Output Queues. Each Output Queue will point to an Operating System printer device (on the server where the daemon is running). The Output Queue will have a Paper (ie type of paper or form) currently mounted and an Online status. A Report must define what sort of Paper it needs to use when being printed (using its Output Format attribute 4). You can define a null printer using the OS null device (/dev/null or NUL on Windows). All Report output sent to this printer will not be printed. This is useful if you want your output to be archived for viewing only. In fact, the *NULL-PRINT* Output Queue is already provided by Maymyo. Standard Output Queues installed as fixtures -------------------------------------------- These are the standard Output Queues provided by Maymyo :- #. *USER-QUEUE* - Output Queue assigned to the logged in User, as maintained in her User Profile. Some Reports should be printed to the printer of the User who generated them. .. note:: the printer device name must be defined to the server where our Spooling Daemon runs. If it is a printer connected to the User's computer, then you need to use *samba* (or Windows Network) to connect it to the server. #. *WORKSTATION-QUEUE* - similar to the User Queue but this will use the printer attached to the workstation the user is logged into. The Value Set *WORKSTATION-MAPPINGS* defines the Output Queue. Attribute 2 is the Output Queue's code. This printer device must be visible to the server where the Spooling Daemon runs. #. *SYSTEM-DEFAULT* - Default printer on the server where the spooler daemon runs. Any Report which do not specify any Output Queue (at Report or Engine level) will use this printer. #. *NULL-PRINT* - This is the null device printer which will never print anything. You would use *USER-QUEUE* or *WORKSTATION-QUEUE* to automatically print reports as they are completed without any human intervention. The printer to use will depend on the User or the Workstation she is logged in to, For example, a Cashier can print a Receipt automatically to the printer attached to her computer when she posts her transaction. Defining Output Queues ---------------------- .. image:: ../_static/out_spool/output_queue.png Maintain Output Queues An Output Queue is always linked to a printer device on the server where the Spooler Daemon is running. This is the *Device Name* field. This printer device must be spelled exactly as defined to the Operating System. You should link printers to Output Queues on a one to one basis. *Is Online* and *Paper Mounted* should be used by the operator of the printer, to inform the Spooler that it is ready to print spool items. The *Purging Days* will be added to the default Spool Purge Months (as maintained in the Application Registry) before printed spool items are purged. Defining Output Commands ^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: ../_static/out_spool/output_cmd.png Maintain Output Commands We will use the *Output Command* to create the actual command to send the output file to the printer device. The default command provided by Maymyo should be adequate. If you have unique commands, you can always add your own Commands. Your *Execute String* can include the following tokens, which will be replaced with the actual Queued Task or Spool Item values just before running. #. ** - Maymyo Instance name, eg Development, Production. as maintained in your AppRegistry *APP-INSTANCE-NAME*. Maymyo's reports will accept this as a parameter to print in the background. This will allow users to differentiate reports printed from their Production vs Test instances. However, you do not use this token in the Output Command (because it is too late, the report output has been generated. The right way is to define this as a parameter to the report). #. ** - the Queued Task id, use this if your command needs to read or write the Queued Task instance. #. ** - the connected session's id #. ** - the Task Owner's username #. ** - the AppResource id of the Report #. ** - the absolute directory where the output file is, normally will be *may_run*/outputs/YYYY/MM*. #. ** - the output file name, usually Report code + Queued Task id + Output Format suffix (eg .pdf) #. ** - the output directory plus file name, this is the token that you need to use to send the file to your printer device. #. ** - the Spool Item id #. ** - the absolute archive directory (will be blank for non- archived Reports) where archive file is. The YYYY/MM is based on the archival date, currently the first Business Day of the month. #. ** - the archive file name. This is the Output File name plus the compression tool's suffix, currently .zip. #. ** - the archive directory plus file name. #. ** - the printer device name, as read from the Output Queue's device name. You will need this in your command. #. ** - the Paper required by the Report. You may need this in your command. An example of how we define the *Execute String* is the Command *UNIX-PRINT*:: lpr -P "" The above will use the *lpr* command to send the full output file name (absolute path name) to the printer device name. You can do more for your printer device that accepts other command options, eg line printers that can accept page length or character per inch options. The other field that you should use is the *Environment Parameter Set* to export before running the *Execute String* above. If you leave this empty, it will use the Application default, as used by the Spooler daemon. Archiving of output files ------------------------- If your Report is important enough to be saved permanently, then check the *To Archive* checkbox in "Maintain Application Reports". The archival of output files will run once a month and save compressed output files to the *archives* directory. This is a sibling of the *outputs* directory. Output files are purged in 3 months (default setting which can be changed) and their corresponding Spool Item instances are purged in 6 months, so you can reprint archive spool items up to 6 months. After this, you will have to go to the *archives* directory directly to retrieve the archive files. Purging of output files ----------------------- Report output files will be purged after 3 months. This is the default setting in the Application Registry. This task is run in the *PURGE-INFRA-MODELS* job (together with purging of Maymyo *infra* model instances) that is run on the last business day of every month. This is the default as loaded by our fixtures and can be changed. You may disable this Scheduled Job and add its Task to your own closing Job.