Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Creating a file listener

Updated on April 6, 2022

Create a file listener to import and process files from another system, for example, you can import data from files that is used to create a work object.

  1. In the header of Dev Studio, click CreateIntegration-ResourcesFile Listener.
  2. In the Short description field, enter a meaningful description of the file listener.
  3. In the Listener Name field, enter a name for the file listener. The name must start with a letter and contain only letters, numbers, ampersands, and hyphens.
  4. Click Create and open.
  5. In the Listener nodes section, select how the listener nodes will start.
    For Pega Cloud applications, the Node based startup and Host based startup settings are not available.
    • Block startup – When this setting is selected, the file listener cannot be started. When this setting is cleared, the file listener starts at system startup or from Admin Studio.
      Note: This option is primarily used in a development environment to block the startup of file listeners that are not ready to receive files. Listeners that are not blocked start when Pega Platform starts and can be stopped and restarted from Admin Studio. Blocked listeners do not start when a Pega Platform node starts and they cannot be started from Admin Studio.
    • Run on all nodes – The file listener starts on all servers in the cluster.
    • Node based startup – The file listener starts only on specified nodes.
      • In the Node ID field, in a multinode cluster, enter the node ID of the server host node or nodes where the file listener is to run. When a server starts, it activates the file listener on the current node if the current node matches any node in the list. If a node is specified, the current node must match a name in the list to activate the file listener. If a node is not specified, the file listener is not activated on any node.

        When multiple file listeners monitor the same directory, the order in which messages are processed might not be the same as the order in which they were put into the directory. If your application requires processing files in the order in which they are sent to the email inbox, use a single file listener on one node.

    • Host based startup – The file listener starts on a specified number of nodes on specific servers within the cluster.
      • In the Host name field, enter the network location name of the host server on which the file listener is to start.
      • In the Node count field, enter the number of nodes on which the file listener is to start.
    • NodeClassification based startup – The file listener starts on the specified node types.
      1. Click Add a row.
      2. In the Node type field, select the node type on which to start file listener.
      3. Repeat these steps to add additional node types.
    Note: You can control when the file listener starts by using the initServices/initFile dynamic system setting. When this setting is set to true, you can start and stop specific listeners on specific nodes from Admin Studio.
    • Owning rulesetPega-Engine
    • PurposeinitServices/initFile
    • Valuetrue (default)

    You can also change the initServices/initFile setting in the prconfig.xml file.

  6. Optional: Select Reset startup to delete all instances from the Log-Connect-AssignedNodes class so that file listeners can be restarted.
  7. In the Source properties section, configure the source properties:
    1. In the Source location field, enter the file specification for the file listener to look for input files.
      For example: file:\\folderlocation:\subfolder
      The file listener requests require read and write access to this directory. Only use Pega-provided repositories for the source location. You cannot use custom repositories.

      This field supports the Global Resource Settings syntax (= PageName.PropertyName ). The default property name for this field is pySourceLocation. For more information, see Using the Global Resource Settings feature.

      Note: Only use a Global Resource Setting when you need a dynamic source location, for example, if the location of the file is determined by the routing logic in a case. You configure this domain on a data page. For more information, see Using repository APIs in your application.
    2. In the Source name mask field, enter the filter for selecting files to process from the source location directory.
      You can use an asterisk as a wildcard. You can include only one asterisk in the root of the mask (before the period) and one asterisk in the file type. If you do not specify a mask or use a mask of *.*, the file listener selects every file in the source location.
    3. Optional: To specify whether the file listener processes a file regardless of whether uppercase and lowercase letters appear in the file name, select Disable case sensitivity.
  8. In the Listener properties section, configure the listener properties:
    1. In the Concurrent threads field, enter the number of threads on each server node that the listener requestor creates when it starts.
      Enter 1 or a small integer. Each thread operates on a single file. Multithreading has no benefit unless multiple files are available at the same time for processing. If the node on which the file listener runs has available JVM memory and CPU cycles, and multiple files are available for processing, using 2 to 5 threads can increase throughput.
    2. In the Service package field, select the file service that the file listener links to.
    3. In the Service class field, select the service class.
    4. In the Service method field, select the service method.
  9. If the file service requires requestors to be authenticated, in the Requestor login section, configure the requestor login information:
    1. In the Requestor user ID field, select the operator ID that the file listener uses to log in.
      The operator ID determines the access group, and therefore the ruleset list, of the file listener.
    2. In the Password field, enter the password for the operator ID.
  10. Click Save.
  11. Optional: You can test connectivity for all startup modes except Blocked startup. Click Test connectivity to confirm that your system can find the directory.
    The system attempts to create the listener thread on the current node and tries to access the device and directory. The test results are displayed including the parameters used in the test, the steps attempted, and the outcome of each step.

    For information about using remote logging to troubleshoot your file listener, see Debugging listeners by using remote logging.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us