Scripts

Overview

Scripts are the command that can be specified when creating/editing Distribution, Consolidation or Script jobs, on step "Triggers" (see below). Scripts can run either before job starts or after it's finished and files are delivered to destination agents. These commands and scripts shall be supported by target OS.

Scripts allow using of variables: 

- agent tags variables. Admin can define them on tab AGENTS -> Edit Tags. These tags can be used in local scripts or right on the job creation page. See here for more details about using tags. All variables shall go with prefix TAG_ (resulting in %TAG_VARIABLE% on Windows, or $TAG_VARIABLE on posix) in the command.
- job variables. The following are supported: JOB_NAME, JOB_PATH, JOB_ROLE, JOB_START_TIME. (for example, %JOB_NAME% on Windows, or $JOB_PATH for a Linux)
Possible values for JOB_ROLE are RW and RO (respectively source and destination in Distribution/Consolidation jobs) and Script (in a script job).

Resilio Connect v2.5.2 and newer gives the choice of shells for executing scripts - either in transfer jobs or in a Script job - Powershell and CMD for Windows, Shell for unix. For each platform custom shell is also available.

How to use it

1. Select default shell and pass another shell there with all necessary params and path to script itself
   
2. Select custom shell, name it and pass the script body.

Powershell Example

For example, a powershell pre-indexing trigger to delete empty directories on source agent in a Distribution job.

Or if you'd like to remove files from the source of the distribution older than X days

For Powershell version 7 in order to execute a script from a file, the file must have .ps1 extension. Otherwise corresponding error appears

Exit code handling

Connect handles exit code for 'throw" for PS 5.0+ only. With PS version is 2.0-4.0 use trap { exit 1 } at the beginning of script with "throw".

Using custom shell

When using a Custom shell, you need to specify it first: 

Notes

• Script code and parameters are to be passed in trigger body. When using it on Windows, make sure that you've set PATH variable to the shell executable in system settings.
• For example, a script to list the downloaded files in job folder:
  

Default shell (CMD for Windows and Shell for unix) can be used to start any script or command

Examples

Example 1:

When files are delivered to a Windows workstation, they need to be moved to another location. We can specify commands:

mkdir "C:\some location"
move filename "C:\some location" 

• Also, one can execute a delivered exe file either directly in the destination directory, or after being moved to a proper location as illustrated above: "C:\some location\filename".

Example 2:

When files are delivered to a Unix workstation (OS X or Linux), one needs to execute the binary delivered, but first, it's necessary to ensure its executability.

Admin can prepare a Python, Perl or Shell script with all necessary commands (like: check posix permissions, add executable attribute, if necessary add firewall rules, launch the binary itself with parameters) and then, when setting up the job, just execute the script:

./launch.py

• Note: by default, these commands are executed from the destination folder. So the script can just be transferred by the Job together with other files. But if the scripts are already located elsewhere on the target workstations, specify the full path to it: /home/admin/launch.py

Scripts' log

Script execution, either successful or not, is recorded in a log. This log is available in Job run details -> Logs. Detailed information is available by clicking the 'Show Logs' link.

Known issue is broken encoding if the script itself has some special symbols (for example, a progress bar) 

Triggers types

Triggers indicate the moment when the script will be executed. This step can be skipped.

• Before file-indexing begins:
  Right after job is created, the source Agent will start indexing files in the specified directory. A script triggered at this moment can "cook the files before serving", for example, re-arrange them, add/remove new and do things alike, so that the folder is indexed and distributed in a proper manner the way you need. The directory in which the script in going to be executed must already exist on the Agent.
• Before finalizing download:
  Available from v4.1.0 and only for Agents v4.1.0 and newer. Executed by each destination Agent right after it downloads all the files (not counting the pre-seeded files). If this trigger is enabled, the Agent downloads file to a temp directory, and after executing the script moves them to their locations. Read more about it here.
• After an agent completes downloading:
  The script will run on each destination agent after it finishes download. Other agents may be still downloading the files, thus it's recommended not to remove or update the distributed files with this trigger. Otherwise the file will be re-downloaded from source again. It's possible to schedule the script for the Agent's local time. This script will run even if the Agents are paused and there's nothing to transfer in the job or there are only zero-sized files. 
• After all agents complete downloading:
  As opposed to the trigger above, in this case script will run only after all destination agents finish downloading all the files. This script will also be executed on the source agent.