Triggers

Overview

Each Jetstream service will react to certain events and execute user-supplied scripts. The server accepts a --trigger-dir command line parameter, which should point to a directory containing the trigger scripts.

The name of the trigger script file must correspond exactly to the name of the event. For example, if the Jetstream service was started with --trigger-dir set to /var/lib/jetstream/triggers, Jetstream would look for and execute script /var/lib/jetstream/triggers/recv.transferComplete once a transfer has been completely received. On Windows, each trigger script must have a .bat extension.

Tip

A trigger script must be an executable file.

On Linux and macOS, make sure to set the executable bit on each trigger script (e.g. with chmod).

On Windows, make sure each trigger has a .bat extension.

Each trigger script will be passed predefined parameters, depending on which event occurred.

Event Triggers

launch

Required file name: launch

Triggered when the server successfully launches and begins listening on the control port.

Parameters:
  1. port: The control port used by the Jetstream server.
#!/bin/sh
echo "Jetstream server Launched on port "$1 >> log.txt

Tip

You can using this trigger to handle startup configuration, like adding destinations. See Startup Configuration for an example.

send.destinationCreated

Required file name: send.destinationCreated

Triggered on a successful createDestination() API call.

Parameters:
  1. destination: The address and port of the new destination, in the format <ip>:<port>.
  2. sender: The address and port of the sender that created the destination, in the format <ip>:<port>.
#!/bin/sh
echo "Sender "$2" created destination "$1 >> log.txt

send.destinationDeleted

Required file name: send.destinationDeleted

Triggered on successful deleteDestination() API call.

Parameters:
  1. destination: The address and port of the deleted destination, in the format <ip>:<port>.
  2. sender: The address and port of the sender that deleted the destination, in the format <ip>:<port>.
#!/bin/sh
echo "Sender "$2" deleted destination "$1 >> log.txt

recv.transferComplete

Required file name: recv.transferComplete

Triggered when a transfer is done and file has been written to disk.

Parameters:
  1. transfer_id: A transfer ID. Transfer IDs are returned from createTransfer(), and used in other methods to refer to a specific transfer.
  2. username: User that was used to authorize the transfer.

Changed in version 1.5.0: Removed sandbox_path parameter.

    Changed in version 1.7.0:

  • Removed destination_directory, transfer_index, transfer_count, truncated_file_count parameters.

  • Added username parameter.

#!/bin/sh
echo "Transfer ID ${1} initiated by ${2} is complete." >> log.txt

Transfer File List

In addition to its input parameters, the recv.transferComplete trigger also has access to the list of files in the completed transfer, and the path of the files on disk. These are provided in stdin. The file list is presented as absolute paths to where the files were written (see Where Do Transfers Go?). This can be used for further operations on the files.

#!/bin/sh
while IFS="   " read -r manifest_file file_path || [ -n "${manifest_file}" ]; do
  echo manifest file: ${manifest_file}, file path: ${file_path} >> log.txt
done

Tip

Naturally, trigger scripts that need to act on the received files should have access to the file system used by the receiver server.

API Command Triggers

Additionally, a trigger is called after each API command is processed. The names of these triggers are on.command, where command is the API command. For example, you may provide a trigger named on.send.createTransfer which will be called after the server processes the send.createTransfer API command.

Four parameters are provided to an API command trigger:

  1. command: (dict) The command structure submitted to the server. This is a dictionary in JSON format.
  2. status: (string) A string describing status of the command. If the command succeeded, this will be “success”.
  3. message: (string) A message returned from the server. Generally this is simply a confirmation that it has done as asked.
  4. result: (dict) The full result structure from the command. This is a dictionary in JSON format.

Since the command and result parameters are offered as dictionaries in JSON format, it may be beneficial to process an API command trigger using a Python script, rather than bash.

#!/usr/bin/env python
import json
import os.path
import sys

log = os.path.join(os.path.dirname(__file__), 'log.txt')

command, status, message, result = sys.argv[1:]
command = json.loads(command)
result = json.loads(result)
with open(log, 'a') as stream:
    stream.write('Message: {!r}\n'.format(message))
    stream.write('Status: {!r}\n'.format(status))
    stream.write('Command: {!r}\n'.format(command))
    stream.write('Result: {!r}\n'.format(result))

Message: 'Manifest requested.'
Status: 'success'
Command: {u'request': u'send.createManifest', u'parameters': {u'fileMappings': {u'/src/foo.txt': u'/dst/bar.txt'}}}
Result: {u'status': u'pending', u'processing': True, u'manifestId': u'ebec4994ea77a55c0100000000000022',
u'totalFiles': None, u'totalSize': None, u'errorMessage': None}

Trigger Considerations

There are some important details of the trigger execution model of which trigger authors should be aware:

  • Execution is serial. A long-running trigger script will block further trigger scripts from running until it is complete, at which point the other trigger scripts will be run one by one. If a trigger never exits, it will block all further triggers.
  • Execution is asynchronous. Each trigger will be called some time after the triggering event occurred. Not only does Jetstream not wait for the trigger to complete, it doesn’t even wait for the trigger to start before moving on to the next task.
  • Execution is silent. No errors are reported from triggers, and output is suppressed. Jetstream does not log trigger script failures or crashes. You may find it useful to do your own custom logging from within the trigger script.