File Transfers (JOBF)

File Transfer objects automate the transfer of files from one system to another. They require two Agents, one on the source and another one on the target computer. The transfer can be structured to enable the exchange of files with packed and binary fields in heterogeneous system environments. All network transfers are encoded by default. This topic explains how to define and configure a File Transfer object to ensure reliable, customizable file exchange.

Note: The status of a File Transfer execution reflects the execution process, not the result of the transferred files. Even if the files contain errors, the return code remains 0 if the execution completes successfully.

This page includes the following:

When transferring files between operating systems or applications that use different character encoding pages, configure the File Transfer object to perform character conversion. Automic Automation supports this process at several levels:

• Character Conversion at Agent Level

  When configuring an Agent, your Automic Automation administrator specifies the Agent's character encoding set in its INI file. The Agent then uses this encoding to convert characters as needed when its host machine uses a different character encoding set than the Automation Engine Server.

• Character Conversion at Object Level

  When defining a File Transfer object, you can assign a specific character encoding on its Attributes page. This setting overrides the encoding defined in the Agent's INI file.

• Character Conversion at Transfer Level

  If both Agents involved in a transfer use different encoding pages, you can specify the encoding sets directly in the Code fields (Source and Destination) on the File Transfer page. This configuration temporarily overrides the encoding specified on the Attributes page and applies only to this particular transfer. Subsequent transfers are not affected.

Automic Automation provides two mechanisms for character conversion:

• Code Table objects, see Code Tables (CODE)

• Standard character conversion sets, see Code Tables and Standard Character Conversion Sets

Character conversion applies only to File Transfers of type Text. Transfers of type Binary are not affected.

1. In the Process Assembly perspective click Add Object. On the Add Object dialog, select File Transfer. For information on how to add objects, see Adding Objects.

2. On the Add Object dialog, select File Transfer. For details adding objects, see Adding Objects.

   A File Transfer object includes several definition pages:

   • Standard pages, available for all object types:

     • Defining the General Page

     • Defining the Version Management Page

     • Defining the Documentation Page

   • Executable object pages

     • Defining the Process Pages in Jobs

     • Defining the Attributes Page

     • Defining the Variables Page

     • Defining the Prompt Sets Page

     • Defining the Rollback Page

     • Registering External Output Files

   • The File Transfer page described here.

   Note: You can also create File Transfer objects directly from combo boxes used to select objects. For details, see Using AWI Combo Boxes.

3. On the Object Name dialog enter the name of the new object. Choose a meaningful name to ensure clarity and consistency. For best practices, see Best Practices: Naming Conventions for Objects.

4. Click OK to open the object definition pages.

5. In the Source/Destination Settings section, specify the file to be transferred and its origin:

   Agent

   You can select either an Agent or an Agent Group. Agent Groups can be either source or target but not both. For more information, see Agent Groups in File Transfers.

   • Source: Agent where the file that you want to transfer is located.

   • Destination: Agent that receives the file.

   Login

   Login object that provides authentication details for connecting to the target system.

   Code

   character conversion during file transfer,code tables in file transfers

   Code Table object or standard character encoding set for text conversion. This list is available only for Text File Transfers (see description of the Transfer Settings section later in this topic).

   The available entries in the Destination Settings > Code list depend on your selection in Source Settings > Code. The following table describes valid source and destination combinations and their behaviors:

   Source Agent	Destination Agent	Comment
   <UTF-8>	Disabled	There is no need to perform a conversion. Only the line breaks are converted, if required, to transfer files between different OS.
   CODE object	CODE object	A single byte character mapping is performed according to the CODE object definitions.
   Empty	Empty	If a conversion is required, the Agent default setting is applied.
   <UTF-8> or <ISO-8859-1> or <ISO-8859-15>or <UCS-2BE> or <UCS-2LE> or <WINDOWS-1252>	Disabled	The destination Agent stores the text data as it is sent by the source Agent. No code page conversion is performed.

   Although the combinations in the following table are possible, they result in either a failing File Transfer or they have no impact at all:

   Source Agent	Destination Agent	Comment
   CODE object	<ISO-8859-15> or <ISO-8859-1> or <WINDOWS-1252>	The File Transfer will fail.
   UC_CODE	<UTF-8> or <ISO-8859-15> or <ISO-8859-1> or <WINDOWS-1252>	This combination has no impact on the File Transfer.

   Note:  If a source or destination Agent does not support UTF-8 and you use either <ISO-8859-15> or <ISO-8859-1> or <WINDOWS-1252>, the File Transfer will fail or abort as failed. This is because non-UTF-8 Agents do not know the standard code pages.

   For more information about Automic Automation and UTF-8 support, see Universal Language Support (Unicode).

   File

   Replace the ghost text (SrcFile or DstFile) with the file name or full path. You can use * in file names but not in paths.

   Note: For a Partially Qualified File Transfer, define a filter using wildcards and fixed parts of the file name rather than specifying a complete file name.

   Source details:

   • VMS Agents do not resolve logical names. Specify here the directory and file name explicitly.

   • z/OS: File path formats depend on the file system (USS or Host).

     • USS absolute path: /dir1/dir2/datei
     • USS relative path: ./dir1/dir2/datei
     • Host file system: FLQN.DATASET.NAME

     File names on the USS system must comply with the EBCDIC International encoding. Otherwise, file names may appear incorrect on the target.

   • Unix Agents: For applicable parameters and conditions, see Call API Unix.

   • WINDOWS and UNIX: If you enter a relative path here, it resolves to your home directory.

   Destination details:

   You can use the variable &$SRC_AGENT# in target file names to automatically insert the source Agent’s name. For example:

   C:\temp\&$SRC_AGENT#_test*.txt

   For WINDOWS and UNIX Agents, if you enter a relative path here, it resolves to your home directory.

   File Attributes

   Apply additional attributes or formatting to source or destination files depending on the Agent type.

   For more information, see:

   • BS2000 Agent - File Transfer Support
   • z/OS and File Transfers
   • Agent - Interaction Between Automation Engine and NSK
   • OS/400 Agent - File Transfer Support
   • UNIX Agent - File Transfer Support
   • VMS Agent - File Transfer Support
   • Windows Agent - File Transfer Support

6. In the Transfer Settings section, specify the settings that govern the transfer:

   File Format

   • Text: Transfers only file content. Use for cross-platform transfers (for example, from Windows to UNIX). Line ending conversion occurs automatically.

   • Binary: Transfers the complete file structure.

   Keep Original File Attributes

   Keep Original File Attributes in file transfers

   Preserves the source file’s attributes. This option is only valid if both operating systems support identical attributes.

   Important!

   • In BS2000, OS/400, and z/OS, this option cannot override file attributes defined in the destination Agent.

   • In z/OS this option is unsupported for files on tape/VTL and requires disk-based datasets.

   Enabling this option is recommended, especially for text transfers between OS/400 systems, to prevent data corruption.

   Compression

   Specifies whether files are compressed during transfer.

   • Default value:

     Uses the Agent variable UC_HOSTCHAR_DEFAULT (FT_COMPRESS). Compression occurs if the source and destination agents have different settings. For example:

     WIN01 = No compression
     UNIX01 = Active compression

     The files are transferred in compressed form.

     The Agent uses the LZP+Huffman method for the compression.

     Tip: Use compression when transferring over networks with limited bandwidth (10 Mbit or less). On faster networks, compression may not improve performance due to processing time.

     Important! This setting overrides the Agent/system variable value.

   If file exists at destination

   • Cancel transfer: Cancels if the file already exists.

   • Overwrite file: Replaces (deletes and re-creates) the existing file.

   • Append file: Appends the transferred file to the existing one.

   Erase Source File

   Deletes the original file after a successful transfer.

   Important!

   • Deleting source files on UNIX requires specific permissions, see Rights for Deleting Source Files in File Transfers.
   • A File Transfer ends with ENDED_OK if all files have been successfully transferred, even if the source file cannot be deleted.

   Use Wildcards: Enables file transfer using wildcard characters:

   • Abort at First Error stops the file transfer immediately if an error occurs.

   • Include Sub-Directories transfers the contents of sub-directories as part of the file transfer.

   • Transfer Complete Folder Structure includes empty directories during partially qualified transfers.

     Note: This option is available only if you have activated Include sub-directories.

7. Save your changes.

File Transfers with Target Agent Groups and the Erase Source File Option

If you specify an Agent Group (HOSTG) as destination (Destination Settings > Agent) AND if you also select Erase Source File in the Transfer Settings section, the source file is deleted immediately after the first Agent in the group has executed the File Transfer.

Because the file is removed immediately, any remaining transfers in the HOSTG container fail since the source file is no longer available.

Workload Balancing during a File Transfer

By default, Jobs and File Transfers run without Agent-level workload limits. However, different tasks place varying demands on the system; some require more CPU time or have longer runtimes. To manage this effectively, the Automation Engine includes a resource concept that accounts for Agent workload during task execution.

Each Agent has a defined resource pool. This allows you to specify how many resources a Job or File Transfer consumes when it runs. As a developer and object designer, you can assign resource values to objects in the Consume <x> resources field on the Attributes page. For details, see Defining the Attributes Page.

The resource values are abstract; they are not tied to specific metrics like CPU or memory. This abstraction provides flexibility in configuring workload distribution based on your system environment and priorities.

For more information, see Resources when Executing Objects: Agent Workload Balancing.

Modifying File Transfer Settings at Runtime

You can view and adjust File Transfer settings while the transfer is running by using script elements that access the object’s attributes. To allow runtime modifications, select the Display Attribute Dialog checkbox on the Attributes page.

For technical details on how File Transfer objects are processed, see File Transfer Procedure.

File Transfers Between TLS/SSL and Non-TLS/SSL Agents

File Transfers between TLS/SSL-enabled and non-TLS/SSL Agents require no additional configuration. The connection is automatically established through the TLS Gateway, which enables secure communication between mixed environments.

When a TLS Gateway is involved in a File Transfer, an entry in the File Transfer log identifies the gateway used for the connection. This log entry confirms that the transfer was routed through a TLS Gateway instance. For more information, see TLS Gateway.

The list below outlines how to work with File Transfers after defining them:

1. Execute the File Transfer

   File Transfer objects can be included in Schedules (JSCH) and thus be executed automatically at predefined dates or intervals. Likewise, they can be part of workflows (see Workflows (JOBP)). For more information, see Superordinate Tasks (Parents).

   You can also execute, restart or stop File Transfers manually. The following topics describe the execution process in Automic Automation in general and the File Transfer-specific characteristics:

   • Executing Objects

   • Execution Options

   • Executing File Transfers

   • Restarting File Transfers

2. Monitor the File Transfer

   Immediately after executing the object, you can start monitoring it. Right-click it to select Monitoring to access all the monitoring functions:

   • Show in Process Monitoring

   • Execution Data

   • Understanding the Reports

   • Analyzing the Last Execution of Executable Objects

   From the list of tasks in the Process Monitoring perspective, you can access all the functions that are available to File Transfer tasks, see Working with Tasks.

   Related Information:

   • Task Status

   • Troubleshooting, Root-Cause Analysis and Remediation

• File Transfer: Watch the Video
• File Transfer Procedure
• Executing File Transfers
• Restarting File Transfers
• File Transfer Attributes
• Secure File Transfer Protocol
• Partially Qualified File Transfer
• Reports for File Transfer Objects
• Using AWI Combo Boxes