Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Filesystem Trigger on the plugin site for more information.

This plugin is up for adoption. Want to help improve this plugin? Click here to learn more!

FSTrigger provides polling mechanisms to monitor a file system and trigger a build if a file or a set of files have changed.

Features

The plug-in makes it possible to monitor changes of a file or a set of files in a folder.

Note: The plug-in uses only persistence in memory. There is no impact on the Jenkins infrastructure (no new files created).
This plugin provides a polling typology among the XTrigger Plugin.

1) Polling a set of files in a folder

For the first use case, we trigger a build if the list of files has changed between 2 pollings:
A build is triggered in the following situations:

  • there are more or fewer files
  • the last modified date of at least one file has changed
  • the content of at least one file has changed

2) Polling a file in a folder

For the second use case, we monitor a file from a path.
The file path can be provided either explicitly or with a GLOB.

A build is triggered in the following situations:

  • The file exists and it didn't exist in the previous polling
  • The file no longer exists whereas it existed in the previous polling
  • The last modification date of the file has changed compared to the previous polling
  • The content of the file has changed

For the latest choice, the content file detection can be:

  • the full content in a file (whatever the file type)
  • the modification of values from XPath expressions in an XML file
  • the modification of the structure or the content in a JAR or in ZIP file
  • the modification of the structure or the content in a TAR file.
  • the modification of a property (or all properties) in a properties file
  • the modification of an attribute (or all attributes) in the MANIFEST.NF of a JAR file
  • the modification of an attribute (or all attributes) in a source MANIFEST.NF
  • the presence of a pattern in a text file (such as a log file)

Some use cases

1. Scheduling a build if a specified file is found in a folder and was not present in the previous build

2. Scheduling a build if the last modification date of a file has changed compared to the last modification file date captured in the previous polling

3. Avoiding explicit jobs dependencies (with upstream/downstream mechanisms)

  • A first job 'jobA' polls a SCM tool and schedules a build if there is at least one change.
    The build instantiates a build process, produces artifacts (binaries, text output, ...) and deploys these artifacts in a target filesystem.
  • A second job 'jobB' checks the existance of the new artifacts in the target filesystem. If there is a change, 'jobB' is scheduled.
    'jobB' may provide packaging steps, testing steps or other steps of a pipeline.

Both jobs are independents and listen external events.

Other similar plugins

* If you want just to know if a set of files exists and display the number of files found, you can use Files Found Trigger plugin.

Known Limitations

The current code is written in Java and it is not very optimized. For example, we can't get similar performance as with Python. Therefore, we recommend to not use FSTrigger plugin when you want to poll a directory with a large set of files.

The current code does not work with Pipeline projects.  JENKINS-48239 - Getting issue details... STATUS

Changelog

Release 0.39

* Fix XPath computation
* Fix Check Path field with latest Jenkins version in configuration
* Upgrade to latest Jenkins LTS (1.554.1)

Release 0.38

* Fix JENKINS-17591 - FSTrigger fails to poll when build node labels change

Release 0.37

* Fix JENKINS-18658 - NPE in FSTrigger upon configuration save

Release 0.36

* Fix JENKINS-17641 - Unknown field 'logEnabled' in org.jenkinsci.lib.xtrigger.XTriggerCause

Release 0.35

* Fix JENKINS-16809 - Plugins FSTrigger/Envinject, NPE while loading jobs
** Update to xtrigger-lib 0.20
** Update to envinject-lib 1.17

Release 0.34

* Fix NullPointerException on polling action
* Upgrade to envinject-lib 1.11
* Upgrade to xtrigger-lib 0.18

Release 0.33

* Fix potential NullPointer exception at startup (envinject-lib 1.8/ xtrigger-lib 1.5)

Release 0.32

* Upgrade to xtrigger-lib 0.14 (more logs)

Release 0.31

* Fix JENKINS-12176 - Unable to delete a job that has a fstrigger
* Upgrade to xtrigger-lib 0.13

Release 0.30

* Fix reponed JENKINS-12924 - FSTrigger triggers builds on jenkins restart

Release 0.29

* Fix JENKINS-12924 - FSTrigger triggers builds on jenkins restart

Release 0.28

* Update to xtrigger-lib 0.8 (fix JENKINS-12888)

Release 0.27

* Fix JENKINS-12865 - ERROR - SEVERE - Polling error Current Project is null from FSTrigger

Release 0.26

* Update to xtrigger-lib 0.7

Release 0.25

* Add the choice of check content, last modification date or a change in the size of files for folder content type
* Update to xtrigger-lib 0.6

Release 0.24

* For 'Folder type', add check with new directories

Release 0.23

* Fix JENKINS-12208 - More information in log file

Release 0.22

* Fix JENKINS-12168 - Monitor files - Does not monitor a unix soft link

Release 0.21

* Add check 'A job is not triggered when Jenkins is quieting down and is not buildable'

Release 0.20

* Fix reoponed JENKINS-12073 - fstrigger plugin download didn't pull in dependency envinject

Release 0.19

* Fix JENKINS-12073 - fstrigger plugin download didn't pull in dependency envinject
* For 'monitor folder' type, the last modification date is checked before a content check

Release 0.18

* Environment variables are taken into account

Release 0.17

* Fix JENKINS-11569 - Enhanced help for includes

Release 0.16

* Fix JENKINS-11567 - unhandled FileNotFountException

Release 0.15

* Add check for configuration page
* Built for 1.409 (compatible LTS)

Release 0.14

* Fix bug on save when no content nature is selected for FileNameTrigger

Release 0.13

* Fix empty includes value for 'Folder trigger type'

Release 0.12

* Fix path resolution for Windows - Merge pull request from vinaynaik

Release 0.11

* Add the ability to monitor more than one file.

Release 0.10.1

* Add an help message for the update center.

Release 0.10

* Remove named regular expression (unusual)
* Refactoring

Release 0.9 (technical release)

* Internationalizing some messages

Release 0.8

* Fix a bug for XML Content type
* Added help messages for end users.

Release 0.7

* Add Tar monitoring capabilities
* Fix a regression on the last modification date check

Release 0.6

* Fix check on last modification date

Release 0.5

* Polling is done on slaves if configured

Release 0.4

* Remove the usage of regular expression for the file name to poll

Release 0.3

* Internal Refactoring
* Add 'Poll the content of an XML File' regarding XPath expressions.

Release 0.2

* Add a page for displaying polling log

Release 0.1

* Initial release

24 Comments

  1. Unknown User (peerke)

    I like to process large amount of media files with Jenkins. It would be really nice to trigger this build with this plugin, but I discovered that scanning part of this plugin takes a lot of cpu power and blocking requests to jenkins when scanning large files. Is there a way to let this plugin only scan for the last change date and not for the actual content? Or build in a option to do this? That would be really helpful. 

    1. Unknown User (gbois)

      You have to use '[FS Trigger] - Monitor files'.
      You give them a file path. And don't check the checkbox 'Inspect the contents'.
      With this configuration, the fstrigger plugin should not scan file content and schedule a build only if the last modification date of the file has changed.

      1. Unknown User (peerke)

        That could work, but that option would also be nice in the '[FSTrigger] - Monitor folder'. Maybe as feature for a future version. 

        Thanks for the response. I will check if this is working for me. 

        1. Unknown User (gbois)

          FSTrigger 0.19 should fixed this issue.

  2. Unknown User (jimsearle)

    Can the FS Trigger - Monitor Files be a unix soft link?  It does not seem to be working.  The trigger says nothing changed.  Is there a file somewhere that stores the info for this trigger so I can debug?

    I looked around and couldn't find any info.

    1. Unknown User (gbois)

      No It doesn't.
      Could you fill in a bug report?
      Thanks

  3. Unknown User (ketang1)

    Ok.  This may seem silly.  I'm new to Jenkins so please be nice.

    FS Trigger - Monitor Files

    D:\download\tmp*.txt    -   works                   (formatting keeps messing up, D:\download\tmp[slash]*.txt)

    D:\download***.txt   -   does not work            (formatting keeps messing up, D:\download[slash][star star][slash]*.txt)

    Am I missing something?

    1. Unknown User (gbois)

      I don't understand your issue.
      Please could you post your message on the Jenkins user mailing list?
      Thanks in advance.

  4. Unknown User (aershov)

    Hi!
    Is there any way to get the information about new files found since last run in the job context ?
    I need to know latest file name to run automatet tests against it.
    Hi!

    Is there any way to get the information about new files found since last run in the job context ?

    I need to know newest file name to run automatet tests against it. (We use network folder to store all versions of artifacts, so i need only the newest file name)

    1. Unknown User (gbois)

      From the version 0.25, you are able to exclude check on the following points

      • last modification date
      • content change
      • more or fewer files

      Therefore, it would meet your needs.

      Let me know if it suits you

  5. Unknown User (alex01ves)

    When the plugin encounters an error (for example, when it runs into "permission denied"), it posts a message into the polling log and exits silently. If an administrator doesn't check the log regularly, the build will never be run.

    I see no clean way of solving this, but I believe this to be a major issue. 

    1. Unknown User (gbois)

      Thanks for your remark. I don't know to handle this kind of error for now.

      1. Unknown User (gbois)

        Thanks for your remark. I don't know to handle this kind of error for now.

  6. Unknown User (alex01ves)

    And another thing. The plugin takes about 50 (!) minutes to poll my folder, even though I checked the "Exclude check content" checkbox.

    It is a network folder with about 100 large files (up to 10 GB), but the size shouldn't be a problem, since only metadata is checked. For example, the following Python script:

    for x,y,z in os.walk(PATH):

       for file in z:

          os.stat(x + "/" + file)

    Takes about 2 seconds to complete, and I believe it is roughly the same thing that the FS-trigger should do.

    1. Unknown User (gbois)

      The current code is written in Java and it is not optimized. We won't do it better than Python. Maybe a refactoring and a delegation of business to Python could be great but a bit difficult for now.

    2. Unknown User (jamesco)

      For users with a large directory to traverse use a ScriptTrigger instead.

  7. Unknown User (hugues)

    Hi Gregory,

    Your plugin is very usefull for me but I have a problem with string parameters or text parameters.

    I use string parameters in my jobs. It seems that I can't use paramaters with your plugin.

    Do you confirm ? Do you think update the plugin ?

    Thanks,

    Hugues

  8. Unknown User (abhidumca)

    Hi Gregory,

    I am trying to poll for a file.

    FS Trigger - Monitor Files

    /root/*.iso    -   works

    But i don't know the exact path, and when i am trying to do

    /root/**/*.iso      - does not work

    I have attached the FSTrigger Monitor Logs


    and Monitor Files configuration.

    Am I missing something?

    1. Unknown User (jamesco)

      ** is a java specific path globbing pattern and I think(YMMV!) it actually doesn't match empty string or current directory although one would think it should. 

      /home/**Matches /home/gus and /home/gus/data on UNIX platforms

      "The ** characters matches zero or more characters crossing directory boundaries."

      https://docs.oracle.com/javase/7/docs/api/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)


  9. Unknown User (sachi87)

    Hi Greg,

    I am having an xml file(executeRM.xml) with contents as mentioned below.<r1> <n1 name="component1" version="14.0" state="ToBeInstalled"/> <n2 name="Component2" version="13.0" state="Installed"/> <n3 name="Component3" version="12.0" state="TobeInstalled"></r1>I have used "FS trigger-Monitor files" and is an every one minute schedule, where I have given the full path of the above xml file. Now I want to write an xpath query, which will trigger the job only when state will be "ToBeInstalled" for any of the 3 components or all. I have written the below xpath query, but the job itself is not getting triggered.
    /r1/n1@name='Component1' and @state='ToBeInstalled' /r1/n2@name='Component2' and @state='ToBeInstalled' /r1/n3@name='Component3' and @state='ToBeInstalled'
    At any point of time if any one or all three(it may get increased to 6-7) conditions hold good then I should be able to trigger the build. 
    If I use /r1/n1/@state, multiple build get triggered. So either I have to use the proper Xpath query or should use some other trigger mechanism. 
    Please suggest me if I can play with xpath queries or better go for some other method. But the XML structure remains constant, 
    I may have to add few nodes, but the attributes remain the same. For any component, if the attribute value is "ToBeInstalled", build should get triggered.

  10. Unknown User (twar)

    Hello,

    Is there a way to obtain information what actually changed? ie. is there some environment containing information about changes?

    Let say new folder has been created in monitored folder or user added new file, how can I get this information?

    Regards.

    1. Unknown User (jamesco)

      A bit late to answer but for future users hopefully this example is useful . . . 

      A job with FSTrigger shows the FSTrigger Files Log on the left:

       FSTrigger Files Log

      This job shows when polling started and result of last poll e.g. 

      [FSTrigger] - Monitor files

      Polling started on Oct 31, 2018 4:50:00 PM
      Polling for the job kudos-upgrade
      Looking nodes where the poll can be run.
      Looking for a candidate node to run the poll.
      Looking for a node with no predefined label.
      Trying to poll with the last built on node.
      
      Polling on master.
      There is no matching files in the folder '/var/jenkins_home/jobs/upgrade/workspace' for the fileName 'upgrade.START'.
      Checking one file: '/var/jenkins_home/jobs/download/workspace/LATEST'.
      The computed file doesn't exist.
      
      Polling complete. Took 3 ms.
      No changes.


      A job that was triggered by FSTrigger will show:

      [FSTrigger] Triggered by a change to a file (log)

      Same FSTrigger info and example here showing the trigger fired due to date/time change of file: 
      The last modification date of the file '/var/jenkins_home/jobs/download/workspace/LATEST' has changed.
      
      The last date/time was   Oct 26 10:40:03
      The current date/time is Oct 30 22:40:01
      
  11. Unknown User (jamesco)

    FSTrigger is very useful.

    Note that I see that if a file changes during a jenkins restart (or just before a jenkins restart if the FSTriggered job is running) then the FSTrigger doesn't detect a change in the file. 

    I see issue "JENKINS-12924 - FSTrigger triggers builds on jenkins restart" I guess this behaviour is on purpose, normal case is that jenkins is continuously running and jobs will be triggered on any file changes that happen.

  12. Unknown User (xiaoyao9184)

    how can i use this in declarative pipeline?