Skip to main content

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

Using file listeners

Updated on April 6, 2022

Use a file listener with a file service to import and process files from another system or that have been created by application users. For example, you can import data that is used to create a work object.

The file listener monitors the file directory. When files that arrive in the directory match the pattern that the file listener is listening for, the listener moves the files into the work_<name of listener>/completed directory and calls the file service. The file service uses a parse rule to open and read the file, evaluate each input record, divide the record into fields, and then write the fields to the clipboard and a service activity processes the data.

After processing the files, the file listener moves the files to either the work_<name of listener>/completed or work_<name of listener> directory depending on whether the files were processed correctly, and how you configured the file listener:

  • If the initial processing is successful, the file moves to the work_<name of listener>/completed directory.
  • If the initial processing fails, and Recovery is enabled, the file listener repeats the processing the number of times specified in the Max recovery attempts 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.

The file listener also creates a work_<name of listener>/reports directory to hold report files that contain the processing results, if the file listener is configured to generate reports. For more information, see Configuring file listener processing.

File listener restart after Service File rule changes

Any change to the Service File rule requires that you restart the listener from Admin Studio for the changes to take effect. For more information, see Restarting a listener.

The following topics describe how to use a file listener to import and process files from another system.

  • Creating a file listener

    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.

  • Configuring file listener processing

    Configure the processing that the file listener performs when it is running, including how often to check for new files, whether to generate a report, what to do after processing a file, and whether to keep a file after it is processed.

  • File listener error handling and debugging

    Learn about the processing that occurs at run time when requestors that are based on the file listener encounter errors. For example, you can configure the number of recovery attempts, whether to rename or delete files with errors, and specify the file extension to append to renamed files.

  • Best practices for processing files using the file listener

    Improve the resiliency of your file listeners by using file processing best practices.

  • Troubleshooting file listeners

    Use the following guidelines to troubleshoot problems with file listeners.

  • Configuring a file service and file listener to process data in files

    Use file services to read and process the data in files that were exported from another system or copied to a specific folder in a file repository. The file listener monitors your file directory and calls the file service so that you can easily import the contents of character-based files into your Pega Platform system.

  • Service File rules

    Use Service File rules to define a package of rules for importing the contents of character-based files into your Pega Platform system. This facility can import a wide variety of record-oriented files to create or update objects in your system, including text files, Comma-Separated-Value files, and completed PDF forms.

  • Parse Delimited rules

    Use a Parse Delimited rule to upload data into your Pega Platform system from an external file or files. Within each input record, a comma, tab, quote, or other character might separate fields. The rule extracts the text between the delimiter characters and stores it in a Single Value property or as one element of a Value List property. This rule expects a single row of data.

  • Parse Structured rules

    Use a Parse Structured rule in conjunction with a Service File rule or the Apply-Parse-Structured method to import structured data to the clipboard. For example, you can import fixed-format flat files from various external sources and platforms.

  • Map Structured rules

    Use a map structured rule to define a two-way mapping between clipboard properties and a fixed-format record structure or text property value.

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. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us