File Listener data instances

The File Listener processes files in the source location. After processing, the file moves to either the Completed or Work subdirectory depending on whether the file processed correctly, and how you configured the File Listener:

  • If the initial processing completes successfully, the file moves to the Completed directory.
  • If the initial processing fails, and Recovery is enabled, the File Listener repeats the processing the number of times specified in the Retries field. The file moves to the Completed directory regardless of whether the retried processing is successful.
  • If the initial processing fails and Recovery is disabled, the file moves to the Work directory.

If Generate report is enabled, the File Listener creates a report in the Report directory.

The File Listener processes files in the source location when the processing begins. If additional files are added to the source location during processing, the new files are not processed until the next time the File Listener runs.

Where, when, and whether listeners start

If desired, you can edit the prconfig.xml file or Dynamic System Settings to prevent the file listener from starting when the system starts (on an eligible server node). Locate the initServices/initFile entry and set the associated value to false. Thereafter, you can use Admin Studio to start and stop specific listeners on specific nodes.

The listener is a data instance, so it has no associated ruleset or version. However, to process an input file, a requestor based on this listener needs access to the ruleset and version that contains the referenced Service File rule.

Three settings affect how the File Listener requestors run. They control whether the listeners can run, when the listeners start, and where the listeners can run:

  1. Whether — Controlled by the Blocked check box on the Properties tab of this form.
  2. When — Controlled by the initServices/initFile entry in the prconfig.xml file or Dynamic System Settings. (enabled by default)
  3. Where — Controlled by the Startup Option property on the Properties tab of this form.

Controlling whether listeners start

The Block startup check box on the Properties tab determines whether the listener requestors defined by this File Listener data instance start. If this box is cleared, these listeners start when Pega Platform starts (on eligible nodes). You can also stop and restart listeners from Admin Studio

If the Block startup check box is selected, they do not start when a Pega Platform node starts and you cannot start them from Admin Studio until you clear the check box and save the listener instance.

For more information, see Listener management and the Admin Studio help.

Controlling when listeners start

Entries in the prconfig.xml file or Dynamic System Settings control when file listeners start. To start unblocked file listeners when Pega Platform starts, edit this file to add or update the initFile element within the initServices section: 

<env name="initServices/initFile" value="true"/>

If this entry is not present in the file or the value is not "true," "y," or "yes," you can start unblocked file listeners only from Admin Studio. For more information, see Listener management and the Admin Studio help.

Controlling where listeners run

The options listed in the Startup Options property on the on the Properties tab determine where the listener starts. The following options are available.

  • Run on all nodes — The listener is run on all nodes — all servers in a cluster.
  • Node based startup — The listener is started only on specified nodes.
  • Server based startup — The listener is started on a specified number of nodes on specific servers within the cluster.

Listener restart after service rule changes

Any change to the Service Email rule on the Service, Request, or Response tab requires that you restart the listener from Admin Studio. If you do not restart the listener, the changes do not take effect. For more information, see Listener management and the Admin Studio help.

Using remote logging to debug listeners

The remote logging feature is often helpful when debugging file listeners. To set up remote logging:

  • On the Properties tab, identify a workstation to receive logging output and a TCP/IP port (port 8887 by convention).
  • Select the Remote Logging check box on the Service File form for each Service File rule you want to debug.
  • Start the listener using Admin Studio.

Java EE resource adapter access

In a web-tier deployment of Pega Platform, a file listener accesses the physical file system. In an e-tier deployment, a file listener can access the physical file system or a resource adapter, depending on the value of a prconfig.xml setting. To use a resource adapter in an e-tier deployment, include this element to the prconfig.xml file: 

<env name="storage/class/default:/type" value="resadaptor" />

To use the file system, specify:

<env name="storage/class/default:/type" value="filesystem" />

Debugging

To include the clipboard results of service file processing in the Pega log, temporarily add the Log-Message method at an appropriate place in the service activity. Set the LoggingLevel parameter to InfoForced and the Message parameter to: 

Contents of page:\n" + myStepPage.getXML());

Monitoring performance

Through changes to the prconfig.xml file or Dynamic System Settings, you can be alerted to unusually long service operations.

Example

For an example of a multithreaded file service, see the Pega Community article How to support high-throughput file services with multithreading.