{"id":2915,"date":"2020-05-01T19:56:00","date_gmt":"2020-05-02T02:56:00","guid":{"rendered":"https:\/\/alt2.minisoft.com\/support\/?p=2915"},"modified":"2021-11-12T15:25:15","modified_gmt":"2021-11-12T23:25:15","slug":"director-alerts","status":"publish","type":"post","link":"https:\/\/c002.minisoft.com\/support\/director-alerts\/","title":{"rendered":"Director Alerts"},"content":{"rendered":"<p><strong>eFORMz Version 10.5 or later<\/strong><br \/>\n<a href=\"\/support\/wp-content\/uploads\/2020\/05\/AlertsSample.zip\">Download Available Files &#8211; Alerts<\/a><\/p>\n<p>Starting in eFORMz Version 11.02, you can configure alert limits. For more information, see <a href=\"\/support\/index.php\/customizing-director-alert-limits\/\">Customizing Director Alert Limits.<\/a><\/p>\n<h1>Alert System for the Director<\/h1>\n<p>eFORMz can monitor for exceptions encountered during processing, and move the associated input file to a quarantine directory, as well as performing other actions, such as:<\/p>\n<ul>\n<li>Send an email notifying of the exception.<\/li>\n<li>Print a report listing the exception, the file being processed, and other information.<\/li>\n<\/ul>\n<p>Alert processing is enabled at the Director Toolkit configuration file level. If alert processing is not defined for a configuration file, any input queue defined therein could get stuck retrying an input file again and again, using up processor time and resources unnecessarily. Therefore, we strongly recommend that each configuration file have alert processing enabled. Note that if you have multiple configuration files, you must define Alert processing for each one.<\/p>\n<h1>How to Configure Alerts<\/h1>\n<p>A sample \u201c<a href=\"\/support\/index.php\/eformz-install-an-extension\/\">Install an extension<\/a>\u201d ZIP file can be downloaded using the link at the top of this page. [<a href=\"\/support\/wp-content\/uploads\/2020\/05\/AlertsSample.zip\">AlertsSample.zip<\/a>]<\/p>\n<p>Download this ZIP file to a location from which you will install it, but do not unzip it. To install the sample, run eFORMz Composer, select \u201cHost Tools &gt; Install an extension\u2026\u201d, navigate to the place you saved the ZIP file, select it and click Open, then follow the prompts until you see the \u201cInstallation Complete\u201d message, then click Done. Close the Composer.<\/p>\n<h2>Configuring the Sample Alert Configuration<\/h2>\n<p>The sample provides the Director Toolkit configuration file, a sample project to trigger an alert, and a sample project to handle that alert. To run the sample, you will need to configure eFORMz to use the Director Toolkit configuration file (AlertsTest.cfg) provided with the sample, following these steps:<\/p>\n<ol>\n<li>Click the Windows Start menu.<\/li>\n<li>Find the eFORMz 11 folder and click to open it.<\/li>\n<li>Click the \u201cDirector Configure\u201d item. If prompted \u201cDo you want to allow this app from an unknown publisher to make changes to your device?\u201d answer Yes.<\/li>\n<li>Click \u201cConfigure Startup Parameters\u201d.<\/li>\n<li>Type the following into the Startup Parameters field:<br \/>\nprojects\/AlertsTest\/AlertsTest.cfg<\/li>\n<li>Click OK<\/li>\n<li>Click Exit<\/li>\n<li>Answer Yes when prompted to save changes.<\/li>\n<\/ol>\n<h2>Tour of Alert Configuration<\/h2>\n<p>To assist in understanding how alert processing works, this section walks through the sample project and configuration installed in the previous section:<\/p>\n<ul>\n<li>Create an eFORMz project to accept the eFORMz XML Alert Format (EXAF), defined below. This project can send an email or perform other actions in response to an alert and will need to define global variables that are returned to the Director to move the input file or spool file. The sample project \u201cprojects\/Alerts\/Alerts.efz\u201d is such a project.\n<ul>\n<li>This project needs to define some eDirect output.<\/li>\n<\/ul>\n<\/li>\n<li>In the Director Toolkit, open the \u201cprojects\/AlertsTest\/AlertsTest.cfg\u201d configuration file. Note the AlertsQueue queue that accepts input files XML files (in EXAF format) and calls the project defined in step\u00a01.<\/li>\n<\/ul>\n<p><a href=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1.png\"><img decoding=\"async\" loading=\"lazy\" class=\"alignnone size-full wp-image-7916\" src=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1.png\" alt=\"\" width=\"536\" height=\"114\" srcset=\"https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1.png 536w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1-300x64.png 300w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1-150x32.png 150w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ1-250x53.png 250w\" sizes=\"(max-width: 536px) 100vw, 536px\" \/><\/a><\/p>\n<ul>\n<li style=\"list-style-type: none;\">\n<ul>\n<li>The File Selection should be set to \u201c*.xml\u201d, even though there is not really a file. The Director creates the XML in memory and calls the project with it, as if it was an input file. The Disposition is set to \u201cDelete selected file\u201d, but we keep a copy of the XML file in another directory with the \u201cOutput to output\/Alerts\/Alerts.xml\u201d directive.<\/li>\n<li>Right-click on the project line, then select \u201cAdd Output Process &gt; Process w\/eDIRECT PLUS\u2026\u201d Enter \u201coutput\u201d for the Base Directory, then check the \u201cDisable standard subdirectories\u201d checkbox.<\/li>\n<li>Right-click on the \u201cProcess w\/eDIRECT\u201d node, and add OS-specific commands to move the input file or input spool file so that it is not processed again.<br \/>\n<strong>Note<\/strong>: If you process different types of input that cannot be operated on (moved or put in hold status, etc.) by the same commands, you will need to separate the Director queues processing these different types of input into separate Director Toolkit configuration files. Then you can define an alert queue in each of these configuration files that will process the errant input file in the correct way.<br \/>\n<strong>Note 2:<\/strong> The example above shows a Windows configuration file with Windows-specific file operations to move (by copying and then deleting) the input file.<\/li>\n<\/ul>\n<\/li>\n<li>In the Director Toolkit, right-click on the root node, and select \u201cAlerts\u2026\u201d to display the Alerts Configuration dialog box:<br \/>\n<a href=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2.png\"><img decoding=\"async\" loading=\"lazy\" class=\"alignnone size-full wp-image-7917\" src=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2.png\" alt=\"\" width=\"496\" height=\"305\" srcset=\"https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2.png 496w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2-300x184.png 300w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2-150x92.png 150w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2-250x154.png 250w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2-293x180.png 293w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ2-488x300.png 488w\" sizes=\"(max-width: 496px) 100vw, 496px\" \/><\/a><br \/>\nIn the \u201cAlerts Queue\u201d dropdown, select the desired queue, \u201cAlertsQueue\u201d in this case. Set the Alert Fence to one of the values in the dropdown, which are numbers from 0 to 16. If an alert (processing exception) with a priority higher than the fence occurs, the alert will be triggered.<\/li>\n<li>Configure the other values: Alert Limit, Alert Nap, Alert (Spin) Fence, and Alert Age. These values allow you to fine-tune when a processing queue will be stopped because too many alerts happened in a certain time period. They are documented on this page: <a href=\"\/support\/index.php\/customizing-director-alert-limits\/\">Customizing Director Alert Limits<\/a><\/li>\n<li>The other queue defined in this configuration, named \u201cSample\u201d, simply triggers an alert:<\/li>\n<\/ul>\n<p><a href=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3.png\"><img decoding=\"async\" loading=\"lazy\" class=\"alignnone size-full wp-image-7918\" src=\"https:\/\/minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3.png\" alt=\"\" width=\"403\" height=\"66\" srcset=\"https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3.png 403w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3-300x49.png 300w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3-150x25.png 150w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3-250x41.png 250w, https:\/\/c002.minisoft.com\/support\/wp-content\/uploads\/2015\/04\/AQ3-400x66.png 400w\" sizes=\"(max-width: 403px) 100vw, 403px\" \/><\/a><\/p>\n<ul>\n<li style=\"list-style-type: none;\">\n<ul>\n<li>The details of how the sample alert is triggered aren\u2019t that important \u2013 the main thing is that it demonstrates a project triggering an alert, and shows how the alert is handled. However, for the A students, here are the details:\n<ul>\n<li>The alert is triggered because the \u201cOutput to projects\/AlertsTest\/Output\/test.pdf\u201d output option under the project call to \u201cprojects\/AlertsTest\/MakeBadFileName.efz\u201d specifies a directory that does not exist.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h1>Alert Processing Review<\/h1>\n<p>Let us review what happens in the processing of an alert in the sample project:<\/p>\n<ol>\n<li>When you copy the sample input file invdata-throwerror.dat into the \u201cprojects\/AlertsTest\/Input\u201d directory, it is picked up by the Sample queue and passed to the \u201cprojects\/AlertsTest\/MakeBadFileName.efz\u201d project.<\/li>\n<li>The project processes the file, produces some output, and returns to the Director.<\/li>\n<li>The Director attempts to write the output from the project to the file \u201cprojects\/AlertsTest\/Output\/test.pdf\u201d.<\/li>\n<li>Since the Output directory does not exist, this causes an alert to be triggered.<\/li>\n<li>The Director gathers up all the information about the queue, the project that processed the input file, and the input file, puts it in an XML packet in the EXAF format, and calls the defined Alerts Queue, Sample, which calls the \u201cprojects\/Alerts\/Alerts.efz\u201d project. This project sends out an email, and defines three global variables that are passed back to the Director:\n<ul>\n<li>gBadFileName<\/li>\n<li>gDestinationDirectory<\/li>\n<li>gSourceDirectory<\/li>\n<\/ul>\n<\/li>\n<li>The Director uses these three Queue Monitor variables to copy the errant input file to the directory specified by gDestinationDirectory, and then delete the file from the directory specified by gSourceDirectory.<\/li>\n<li>A copy of the Alert XML file is saved to the \u201coutput\/Alerts\u201d directory with the name \u201cAlerts.xml\u201d, and because the \u201cCreate unique filename\u201d checkbox is checked, a timestamp is added to the filename before the \u201c.xml\u201d extension.<\/li>\n<li>We\u2019re done.<\/li>\n<\/ol>\n<h1>eFORMz XML Alert Format (EXAF)<\/h1>\n<p>When the Director encounters an exception in a queue, it gathers information about the current processing state of that queue and formats it into an XML package that is passed to the configured Alert queue project. This format differs slightly depending on the environment in which eFORMz is running: Windows, AS400\/iSeries, Linux, etc. Below is a sample XML package for Windows:<\/p>\n<pre>&lt;?xml version=\"1.0\" encoding=\"utf-8\"?&gt;\n&lt;Alert Priority=\"15\" Timestamp=\"1588032397527\"&gt;\n\u00a0 &lt;Source&gt;&lt;![CDATA[Queue Monitor Sample for projects\/Alerts\/Input]]&gt;&lt;\/Source&gt;\n\u00a0 &lt;PrimaryMessages&gt;\n\u00a0\u00a0\u00a0 &lt;PrimaryMessage&gt;&lt;![CDATA[File output error]]&gt;&lt;\/PrimaryMessage&gt;\n\u00a0\u00a0\u00a0 &lt;PrimaryMessage&gt;&lt;![CDATA[\u00a0 C:\\\\Minisoft\\\\eFORMz_6\\\\projects\\\\Alerts\\\\Output\\\\test.pdf.hld (The system cannot find the path specified)]]&gt;&lt;\/PrimaryMessage&gt;\n\u00a0 &lt;\/PrimaryMessages&gt;\n\u00a0 &lt;SecondaryMessages&gt;\n\u00a0\u00a0\u00a0 &lt;SecondaryMessage&gt;&lt;![CDATA[java.base\/java.io.FileOutputStream.open0(Native Method)]]&gt;&lt;\/SecondaryMessage&gt;\n\u00a0\u00a0\u00a0 &lt;SecondaryMessage&gt;&lt;![CDATA[java.base\/java.io.FileOutputStream.open(FileOutputStream.java:292)]]&gt;\n\u00a0\u00a0\u00a0 &lt;\/SecondaryMessage&gt;\n\u00a0\u00a0\u00a0 &lt;SecondaryMessage&gt;&lt;![CDATA[java.base\/java.io.FileOutputStream.&lt;init&gt;(FileOutputStream.java:235)]]&gt;\n\u00a0\u00a0\u00a0 &lt;\/SecondaryMessage&gt;\n\u00a0\u00a0\u00a0 [...other SecondaryMessage nodes showing the call stack...]\n\u00a0 &lt;\/SecondaryMessages&gt;\n\u00a0 &lt;DataValues&gt;\n\u00a0\u00a0\u00a0 &lt;DataValue&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Name&gt;&lt;![CDATA[datafilename]]&gt;&lt;\/Name&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Value&gt;&lt;![CDATA[invdata-throwerror]]&gt;&lt;\/Value&gt;\n\u00a0\u00a0\u00a0 &lt;\/DataValue&gt;\n\u00a0\u00a0\u00a0 &lt;DataValue&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Name&gt;&lt;![CDATA[datafiletype]]&gt;&lt;\/Name&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Value&gt;&lt;![CDATA[PCL]]&gt;&lt;\/Value&gt;\n\u00a0\u00a0\u00a0 &lt;\/DataValue&gt;\n\u00a0\u00a0\u00a0 &lt;DataValue&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Name&gt;&lt;![CDATA[project]]&gt;&lt;\/Name&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Value&gt;&lt;![CDATA[MakeBadFileName]]&gt;&lt;\/Value&gt;\n\u00a0\u00a0\u00a0 &lt;\/DataValue&gt;\n\u00a0\u00a0\u00a0 &lt;DataValue&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Name&gt;&lt;![CDATA[datafileext]]&gt;&lt;\/Name&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Value&gt;&lt;![CDATA[dat]]&gt;&lt;\/Value&gt;\n\u00a0\u00a0\u00a0 &lt;\/DataValue&gt;\n\u00a0\u00a0\u00a0 &lt;DataValue&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Name&gt;&lt;![CDATA[directory]]&gt;&lt;\/Name&gt;\n\u00a0\u00a0\u00a0\u00a0\u00a0 &lt;Value&gt;&lt;![CDATA[projects\/Alerts\/Input]]&gt;&lt;\/Value&gt;\n\u00a0\u00a0\u00a0 &lt;\/DataValue&gt;\n\u00a0 &lt;\/DataValues&gt;\n&lt;\/Alert&gt;<\/pre>\n<p>The XML contains the following information about the exception:<\/p>\n<ul>\n<li>Priority \u2013 a number from 0 \u2013 15 with a higher number being more severe.<\/li>\n<li>Timestamp \u2013 a Java timestamp from the time the exception occurred. This is the number of milliseconds since January 1, 1970 00:00:00 GMT. This can be converted to a human-readable date and time using the Date Format action in eFORMz.<\/li>\n<li>Source \u2013 a phrase containing the name of the Queue Monitor and the input source being monitored. \u201cQueue Monitor &lt;queuename&gt; for &lt;inputsource&gt;\u201d, where &lt;queuename&gt; is the name of the Director Queue, and &lt;inputsource&gt; is the input directory or OUTQ or other input source.<\/li>\n<li>PrimaryMessages \u2013 a list of the one or two primary messages indicating the cause of the error.<\/li>\n<li>SecondaryMessages \u2013 the call stack from the exception, giving additional information that may be helpful to Minisoft in pinpointing the cause of the exception.<\/li>\n<li>DataValues \u2013 a list of the predefined Queue Monitor variables in effect at the time of the exception. Each variable is contained in a DataValue node.\n<ul>\n<li>Each DataValue node contains two subnodes.\n<ul>\n<li>Name \u2013 the name of the variable<\/li>\n<li>Value \u2013 the value of the variable at the time of the exception<\/li>\n<\/ul>\n<\/li>\n<li>The following variable names are always defined:\n<ul>\n<li><strong>datafilename<\/strong> \u2013 the base part of the data file name<\/li>\n<li><strong>datafileext<\/strong> \u2013 the extension of the data file name<\/li>\n<li><strong>datafiletype<\/strong> \u2013 the format of the data file, one of the eFORMz recognized formats, such as PCL, ZPL, PDF, PNG, XML, etc.<\/li>\n<li><strong>directory<\/strong> \u2013 the directory being monitored by the Queue Monitor<\/li>\n<li><strong>project<\/strong> \u2013 the project in whose context the exception occurred<\/li>\n<\/ul>\n<\/li>\n<li>The following additional variable names are defined in an iSeries (AS400) environment, and allow access to various attributes of the spool file:\n<ul>\n<li><strong>queue<\/strong> \u2013 the name of the Output Queue (OUTQ) being monitored<\/li>\n<li><strong>iSeries_AUX_POOL <\/strong>\u2013 the value of the Auxiliary Storage attribute<\/li>\n<li><strong>iSeries_COPIES <\/strong>\u2013 the value of the Copies attribute<\/li>\n<li><strong>iSeries_FILENUMBER <\/strong>\u2013 the value of the Spooled File Number attribute<\/li>\n<li><strong>iSeries_FORMTYPE <\/strong>\u2013 the value of the Form Type attribute<\/li>\n<li><strong>iSeries_JOBNAME<\/strong> \u2013 the value of the Job Name attribute<\/li>\n<li><strong>iSeries_JOBNUMBER <\/strong>\u2013 the value of the Job Number attribute<\/li>\n<li><strong>iSeries_JOBUSER <\/strong>\u2013 the value of the Job User attribute<\/li>\n<li><strong>iSeries_SAVE <\/strong>\u2013 the value of the Save Spooled File attribute<\/li>\n<li><strong>iSeries_SPFNAME <\/strong>\u2013 the value of the Spooled File Name attribute (same as <strong>datafilename<\/strong>)<\/li>\n<li><strong>iSeries_SPLFSTATUS <\/strong>\u2013 the value of the Spooled File Status attribute<\/li>\n<li><strong>iSeries_USERDATA <\/strong>\u2013 the value of the User Data attribute<\/li>\n<li><strong>iSeries_USERDEFDATA <\/strong>\u2013 the value of the User Defined Data attribute<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>The variables in the DataValue nodes can be used to construct Global Variables with the \u201cPass last value to Queue Monitor\u201d to pass back to the Director.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>eFORMz Version 10.5 or later Download Available Files &#8211; Alerts Starting in eFORMz Version 11.02, you can configure alert limits. For more information, see Customizing Director Alert Limits. Alert System for the Director eFORMz can monitor for exceptions encountered during processing, and move the associated input file to a quarantine directory, as well as performing [&hellip;]<\/p>\n","protected":false},"author":75,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[85,1],"tags":[27,648],"_links":{"self":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/2915"}],"collection":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/users\/75"}],"replies":[{"embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/comments?post=2915"}],"version-history":[{"count":43,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/2915\/revisions"}],"predecessor-version":[{"id":9823,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/2915\/revisions\/9823"}],"wp:attachment":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/media?parent=2915"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/categories?post=2915"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/tags?post=2915"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}