Actr_AddFolderTrigger (function reference)

By April 1, 2020April 2nd, 2020Online Help, Troi Activator Plug-in
Activator Plug-in > Functions reference > Actr_AddFolderTrigger
Activator Plug-in for FileMaker Pro

Actr_AddFolderTrigger

Add a folder action, which will trigger a script when the monitored folder is changed.

SyntaxFunction badge

Actr_AddFolderTrigger ( switches; folderPath ; fileName ; scriptName )

Parameters

switchesmodify the behavior of this function
folderPaththe path of the folder which needs to be monitored for changes
fileNamethe name of the FileMaker file that contains the script
scriptNamethe name of the script to trigger when a change in the folder occurs

Switches

Switches can be empty or one or more of the following:

-AllItems(default) trigger when a file or a folder is added, removed or modified
-FilesOnlyonly trigger a script when a file is added, removed or modified
-FoldersOnlyonly trigger a script when a folder is added, removed or modified

You can also add this switch:

-AddedItemsOnlyonly trigger a script when an item is added (not when removed from the folder or modified)

Returned Result

Data type returned

Error code

Result

The returned result is an error code. An error always starts with 2 dollars, followed by the error code. You should always check for errors. Returned error codes can be:

0no error
$$-50 paramErrthere was an error with a parameter
$$-120dirNFErrthe monitor folder could not be found
$$-4295maxFolderTriggersErrthe maximum number of folder triggers is already running

Other errors may be returned.

Originated in

Activator Plug-in 6.0

Compatibility

FileMaker Pro 15 to 18

Considerations

The script parameter of the triggered script will contain all the information on what was changed in the folder. This is a return separated list, containing a multiple of 2 lines, where the first line will contain what action happened, for example ADDED or REMOVED. The next line contains the path to the file or folder that was changed. The path is a fully qualified path compatible with FileMaker Pro’s paths, on macOS a path will be formatted like this:

/volumeName/directoryName/fileName
/volumeName/directoryName/subFolder/

on Windows it is formatted like:

/driveletter:/directoryName/fileName
/driveletter:/directoryName/subDir/

NOTE the script might be triggered multiple times when multiple items are changed, with each ScriptParameter containing only a part of the change information.

Possible returned actions can be: ADDED, REMOVED, MODIFIED, RENAMED_OLD_NAME and RENAMED_NEW_NAME.
When a file or folder is renamed you will first receive the RENAMED_OLD_NAME action with the old path, followed with the RENAMED_NEW_NAME action and the new name.

NOTE You don’t need to delete any trigger data, all data comes in via the script parameter.

Example

Set Variable [ $ErrorCode ; Actr_AddFolderTrigger ( "-Unused" ; "/MacHD/incomingData/" ; 
                                                  "FolderMonitor.fmp12" ; "Folder_TriggerScript" ) ]

This will start to monitor the folder “/MacHD/incomingData/”. When there is a change in the monitored folder (like a file or folder is added to this folder), it will trigger the script “Folder_TriggerScript” in file “FolderMonitor.fmp12”. Note that this example is somewhat simplified, normally you should not use a hardcoded filename like in the above example.

When the script “Folder_TriggerScript” is run, use Get( ScriptParameter ) to get detailed information on what was changed in the monitored folder. The script parameter might contain for example this text with 4 lines (on macOS):

ADDED 
/MacHD/incomingData/new_report.pdf
REMOVED 
/MacHD/incomingData/stale_folder/

on Windows ScriptParameter might contain:

ADDED 
/D:/incomingData/new_report.pdf
REMOVED 
/D:/incomingData/stale_folder/

This indicates that the file new_report.pdf was added to the folder and the folder stale_folder was removed.

Example 2

Create a trigger script called Folder_TriggerScript. Add the following script steps to your script:

Enter Browse Mode
# Get the data from the script parameter
Set Variable [ $ScriptParameter ; Get ( ScriptParameter ) ]
# We are getting each pair of information out in a loop and store it 

Set Variable [ $index;  1 ]
Loop
	# Get the action first
	Set Variable [ $Action ; GetValue ( $ScriptParameter ; $index ) ]
	# Now get the path:
	Set Variable [ $Path ;  GetValue ( $ScriptParameter ; $index + 1 ) ]
	# If $Action and/or $Path is empty, there are no more lines of information, and we are done:
	Exit Loop If [ $Action = "" or $Path = "" ]

	# We have a new change, store it into the database: 
	New Record/Request
	Set Field [ folderEvents::ActionType ; $Action ]
	Set Field [ folderEvents::Path ; $Path ]

	# ** Add your own stuff here. ** 
	
	# Point the index to the next pair:
	Set Variable [ $index;  $index + 2 ]
End Loop
Go to Field[ ]
Exit Script [ Result: 0 ]

To start monitoring you can create a “Start Folder Monitor” script. Add the following script steps:

Set Variable [ $DesktopFolderPath ; Get ( DesktopPath ) ]
Set Variable [ $ErrorCode ; Actr_AddFolderTrigger ( "-Unused" ; $DesktopFolderPath ; 
                                                  Get ( Filename ) ; "Folder_TriggerScript" ) ]

This will start monitoring the wanted folder (in this example the Desktop folder). When running on Windows and you rename a file this will trigger the script and result in this ScriptParameter:

RENAMED_OLD_NAME
/C:/Users/brad/Desktop/name.txt
RENAMED_NEW_NAME 
/C:/Users/brad/Desktop/newname.txt

Related functionFunction badge

Actr_RemoveFolderTrigger

Related script stepScript step badge

Add Folder Trigger

Related topics

Activator Plug-in online help (overview)


Online Help Page for Activator Plug-in for 15 to 18 –> Actr_AddFolderTrigger (actrp4626) 2020-0401 21:11:15