Post Transfer Actions

A Post Transfer Action is a program that is invoked on the Transfer Site file server after a file has been successfully uploaded to the server. You can configure Post Transfer Actions in Gateway Administrator or in a Reflection for Secure IT server that has been configured to act as the Transfer Site server.

Post Transfer Actions configured in Gateway Administrator

Actions configured in Gateway Administrator are associated with Transfer Sites. By default, new sites are added with no associated Actions. The Transfer Site administrator can add any defined Action to the Transfer Site. An Action that has been added to a Transfer Site runs after each successful upload of a file to that site. This approach is appropriate when you want to configure different Actions for different Transfer Sites, or when you want Actions to follow uploads to some sites, but not others.

Note

To use Post Transfer Actions in Gateway Administrator, you must configure the Transfer site file server to be an added SFTP server. Using the Reflection Gateway Proxy (the default) is not supported.
Post Transfer Actions in a Reflection for Secure IT Server for Windows.

This approach is available if you have configured a Reflection for Secure IT Server for Windows as your Transfer Site server. Actions configured on this server are not specific to individual Transfer Sites. By default, these Post Transfer actions act on all files uploaded to the server. A filter option is available that enables you to limit the action to all files that match the filter specification. For example, you might configure an Action to act only on files with a *.exe extension. This approach is appropriate when you want to ensure that Actions take place after all uploads. A typical use for this kind of Post Transfer Action is running a virus scanner.

Note

You can also use Jobs to initiate actions after files are uploaded to a Transfer Site. To compare features of these approaches, see Comparing Jobs and Transfer Sites.

Configure Post Transfer Actions in Gateway Administrator

A Post Transfer Action is a program that is invoked on the Transfer Site server after a file has been successfully uploaded to the server. For example, you might configure an Action in Gateway Administrator that renames or moves successfully uploaded files. Because these Actions are assigned to individual Transfer Sites, you can configure site-specific Actions.

Characteristics of Post Transfer Actions configured on Gateway Administrator:

Post Transfer Actions run on the Transfer Site file server.
Post Transfer Actions are assigned to Transfer Sites using the Add Actions option. An Action will run only if it has been added to the Transfer Site.
Although you can assign multiple Actions to a Transfer Site, the order of actions in the Transfer Site definition does not control the order of execution for these actions. To ensure that a series of actions takes place in a predictable sequence, it is possible to include the actions in a single script, then create an Action that runs that script. However, using Jobs is the preferred approach where multiple actions are required to occur in a specific sequence.
Outputs from one Action cannot be used as inputs to another Action.
Failed execution of an Action does not prevent other Actions from executing. Use Jobs when you want to ensure that one action is successful before the next action in a sequence is initiated.
Actions are executed only after successful transfers. They do not run after unsuccessful or canceled transfers.
Post Transfer Actions run immediately after file is transferred. Job actions do not run until after the configured scan interval.
Actions are not supported for downloads or other file transfer events, such as renaming or deleting a file on the server.
By default, up to 10 Actions can execute simultaneously. Additional actions are added to a queue and executed as other actions are completed. You can modify this default in the Gateway Administrator properties file using the configservice.event.threads setting.
If the Reflection Gateway Administrator service or computer shuts down for any reason, unprocessed actions are processed when the service resumes.

Note

To use Post Transfer Actions in Gateway Administrator, you must configure the Transfer site file server to be an added SFTP server. Using the Reflection Gateway Proxy (the default) is not supported.

To configure Post Transfer Actions in Gateway Administrator

Use the Actions tab to define a post transfer action.
Use the Transfer Sites tab to add the action to a Transfer Site.

Logging for Gateway Administrator Post Transfer Actions

The log file for Gateway Administrator Actions is the Gateway Administrator server log files. Output from the configured program or command is directed to this log. The log also includes Gateway Administrator error messages to help troubleshoot Actions. The default location is:

C:\Program Files\Micro Focus\ReflectionGateway\GatewayAdministrator\logs\

More Information

Define a Post Transfer Action in Gateway Administrator

You can configure a Post Transfer Action to perform actions on files successfully uploaded to the Transfer Site server.

To add or edit Post Transfer Actions, you must be a member of a group with the Manage actions role enabled.
After an Action is created, it will run only on Transfer Sites that have added it as an action. To add an action to a Transfer Site, you must have the Manage transfer sites role enabled; you do not need the Manage actions role to add an existing action.

Before you begin

In Gateway Administrator's File Servers tab, set Transfer site file server to be an added SFTP server (not the default setting), and confirm that Transfer Sites can upload successfully to that server.

To define a Post Transfer Action

Connect to Gateway Administrator.
On the Actions tab, click New.
- For Action name, specify a descriptive name to identify this action.
- For Command, specify an executable command or the full path and name of an executable file on the Transfer Site file server followed by command arguments. After the command include any arguments to be passed to the specified program. Arguments can include supported tokens (enclosed in dollar signs). Tokens are replaced by actual values when the Action runs. Use spaces to separate multiple arguments.Use double quotation marks around any argument that might include spaces in the returned value.
  
  For examples, see the Sample Post Transfer Action Commands that follow.
Click Save.
Add this Action to one or more Transfer Sites.

Note

If no path information is included, command output is created in the SSH login directory of the user whose UserID is configured for authentication in the server settings of the Transfer Site file server.
If full path information is included, the destination directory must exist, and the user account specified in the file server settings must be able to write to this directory.

Sample Post Transfer Action Commands

Use these examples as models for testing and configuring Post Transfer Actions. Samples include appropriate syntax for both Windows and UNIX SFTP servers.

Example 1: Save token values to a file in the upload directory

This example uses the operating system echo command to append the name of the uploaded file and the date of transfer to the contents of a file called tokenvalue.txt. (The file is created if it does not exist.) The token $FILE_PATH$ is used to create this file in the upload directory. Because this destination directory might include spaces, the token is enclosed in double quotation marks.

Windows SFTP server

cmd /c echo $FILENAME$: $DATE$ >> "$FILE_PATH$\tokenvalue.txt"

Note

On Windows servers, precede DOS commands with cmd /c. The /c switch is required; it specifies that cmd should exit after the specified command is carried out.

UNIX SFTP server

echo $FILENAME$: $DATE$ >> "$FILE_PATH$/tokenvalue.txt"

Example 2: Rename an uploaded file

This example renames the uploaded file by adding the name of the user who uploaded it to the filename. The $FULL_PATH$ token identifies the full path and name of the uploaded file.

Windows SFTP server

cmd /c rename "$FULL_PATH$" "$FILENAME$".$INITIATOR_USERID$

UNIX SFTP server

mv "$FULL_PATH$" "$FULL_PATH$".$INITIATOR_USERID$

Add an Action to a Transfer Site

To run a Post Transfer Action, you need to add the Action to a Transfer Site. After an Action has been added to a Transfer Site, if the Action is enabled (the default), it will act on all files that are successfully uploaded to that site. Post Transfer Actions do not run after uploads to Transfer Sites that have no added actions.

To add or edit the Actions associated with a Transfer Site, you must be a member of a group with the Manage transfer sites role enabled.

Before you begin

One or more Actions must already be defined.

To add an Action to a Transfer Site

Connect to Gateway Administrator.
On the Transfer Sites tab, click Add or select an existing site and click Edit.
Use the Add actions drop-down list to select the Action you want to add. Added actions appear below the drop-down list. Click the X in any added action to remove that action.

Note

You can assign more than one post transfer action to a Transfer Site, but the order of actions in the Transfer Site page does not control the order of execution for these actions. To ensure that a series of actions takes place in a predictable sequence, include the actions in a single script or batch file; or use Job Actions.
Click Save.

Configure Post Transfer Actions in Reflection for Secure IT

If you have configured Reflection for Secure IT Server for Windows (version 8.2 or later) as your Transfer Site file server, you can set up Post Transfer Actions directly on this server. Unlike Post Transfer Actions created in Gateway Administrator, Post Transfer Actions created this way are not associated with individual Transfer Sites; by default they act on all uploaded files. A typical use for this kind of Action is running a virus scanner.

Post Transfer Actions configured on the Reflection for Secure IT server run under the same account as the Reflection for Secure IT service (the Local System account). This account has administrative privileges on the local system.
By default, Post Transfer Actions act on all files uploaded to this server. A filter option is available that enables you to limit the action to all files that match the filter specification.
You can configure multiple Post Transfer Actions, but the order of actions in the Post Transfer Actions pane does not control the order of execution for these actions. To ensure that a series of actions takes place in a predictable sequence, include the actions in one batch file.
Outputs from one Post Transfer Action cannot be used as inputs to another Action.
Failed execution of a Post Transfer Action does not prevent other Post Transfer Actions from executing.
Post Transfer Actions are executed only after successful transfers. They do not run after unsuccessful (or canceled) transfers.
Post Transfer Actions are not supported for downloads or other file transfer events (such as renaming or deleting a file on the server).
By default, up to 50 actions can execute simultaneously. You can modify this default on the Post Transfer Actions pane.

Logging for Reflection for Secure IT Post Transfer Actions

Error messages and Post Transfer Action output can be viewed in either the Windows Event Viewer or the server's debug (text) log file. Windows Event logging is enabled by default, but the default logging level does not include the Post Transfer Action output; you need to increase the logging level to "Information" to see this content. Debug logging is not enabled by default. When working with Post Transfer Actions, enabling debug logging to a text file is recommended.

To configure Post Transfer Action logging to a text file on a Reflection for Secure IT Server for Windows

From the Reflection for Secure IT Server Configuration tab, click Debug Logging.
Click Enable debug logging to log file. By default, this log is set to Information, which is is sufficient to include Post Transfer Action output and error messages.

You can click Custom to fine-tune the level of output that is sent to this log. Three settings control Post Transfer Action output: LOG_I_PTA_ERROR, LOG_I_PTA_RESULT, and LOG_T_PTA.
Save your settings (File > Save Settings).

To view the text log file

From the Reflection for Secure IT Server console View menu, select View Latest Debug Log File.

Define a Post Transfer Action in Reflection for Secure IT

If you have configured Reflection for Secure IT as your Transfer Site file server, you can add Post Transfer Actions to this server.

Before you begin

Install the Reflection for Secure IT Server for Windows.
From the Reflection for Secure IT Server console, enable debug logging to a text file.
Add your Reflection for Secure IT Server to Gateway Administrator and make it the Transfer Site server. Confirm that Transfer Sites can upload successfully to this server.

To configure Post Transfer Actions in the Reflection for Secure IT Server for Windows**

From Reflection for Secure IT Server console, go to Configuration > Post Transfer Actions.
Click Add to create a new Post Transfer Action.

For information about configuring File filter, Program, and Arguments, refer to the dialog box help and the bridgehead_title that follow.
Save your settings (File > Save Settings).

Examples

Use these examples as models for testing and configuring Post Transfer Actions in a Reflection for Secure IT Server for Windows.

Example 1: Send a directory listing to the log file

This example sends a directory listing to the log file. The default file filter triggers the action after every upload. The program for these Post Transfer Actions must be specified using the full path; in this example it is the path to the Windows cmd command. The $FILE_PATH$ token is used to get the listing of the upload directory. Because the destination directory might include spaces, this token is enclosed in double quotation marks.

File filter: .*

Program: C:\Windows\System32\cmd.exe

Arguments: /c dir "$FILE_PATH$"

Note

Use the /c argument when you use the Windows cmd command. This switch specifies that cmd should exit after the specified command is carried out.

Example 2: Copy uploaded PDF documents to specified directory

This example copies uploaded PDF files to an existing destination directory. The file filter uses a regular expression to specify all files with a .pdf file extension.

File filter: .*\.pdf

Program: C:\Windows\System32\cmd.exe

Arguments: /c copy "$FULL_PATH$" c:\out

Post Transfer Action Tokens

Post Transfer Actions tokens can be passed as command line arguments to the Post Transfer Action executable. These tokens are replaced by actual values based on the file transfer.

Tokens must be preceded and followed by a dollar sign ($), for example $TIME$.
You can enclose tokens in quotation marks. This might be required to pass arguments that include spaces or special characters.

The following tokens are available:

	Description	Sample Output
CLIENT_IP	The IP address of the client system.	fe80::21a5:4df7:fdce:6951
DATE	The date of the transfer. The format for the date is determined by the locale setting of the server.	05/28/2014
FILENAME	The name of the uploaded file.	myfile.txt
FILE_HASH	The SHA-1 hash of the uploaded file.	ebd90566a6a5d7c66a784839cab05b08949a9141
FILE_PATH	The path—without the filename—to the destination directory on the Transfer Site file server.	C:\Base directory\Gateway\transfersite
FILE_SIZE	The file size (in bytes).	7326
FULL_PATH	The full path—including the filename—of the destination file on the Transfer Site file server.	C:\Base directory\Gateway\transfersite\myfile.txt
INITIATOR_EMAIL *	The email of the client user that uploaded the file.	joe@acme.com
INITIATOR_USERID	The domain and user ID of the client user that uploaded the file, in the format: domain\user.	mydomain\joe
TIME	The time of the transfer on the Reflection Secure Shell Proxy.	14:26:59
TIMEZONE	The time zone of the Gateway Administrator server.	-0700
TRANSFER_SITE_NAME *	The Transfer site name from New/Edit Transfer Site.	Accounting department files

* Supported in Gateway Administrator Post Transfer Actions, but not in Reflection for Secure IT Post Transfer Actions.