Specifying Connection Parameters with Protocol Fragments
When a source or target is specified for a file transfer operation a reference is made to a ProtocolFragment element. ProtocolFragments are elements in the Fragments branch of the YADE XSD Schema and can be thought of as a series of predefined part configurations that can be called up as required for specific file transfer operations.
Protocol fragments usually form the starting point when configuring a file transfer. Profiles, which reference protocol fragments, can then be specified after the necessary protocol fragments have been defined.
Operationally, the starting point is a Profile, which then calls the protocol fragment(s).
How to generate Protocol Fragments
In the YADE XML hierarchy ProtocolFragments are children of the Fragments element and in turn can have any number of child elements. Example protocol fragment elements would be the FTPFragment and the SFTPFragment.
Protocol fragment elements have descendants that specify connection parameters such as the authentication method, the connection type and proxy.
The diagram below shows the fragment hierarchy required to specify a connection to carry out file transfer from a remote source per FTP using password authentication.
You are recommended to use the XML Editor to generate the configuration. The editor uses the YADE parameter configuration XSD schema to guide parameter specification.
Starting at the ProtocolFragments element, the Add child button is used to insert valid elements at each level in the hierarchy until the configuration is complete.
Note that the links behind each parameter name in the diagram lead to the Parameter Reference page for that element, which provides detailed information about the parameter.
Protocol fragment elements are protocol-specific - that is, there is a ProtocolFragments element defined in the XSD schema for each file transfer protocol. This approach enables the properties of each protocol to be reflected in the schema and allows dependencies and incompatibilities to be defined. A trivial example here would be that a PassiveMode element can be specified for an FTPFragment but not for an SFTPFragment.
Note that protocol fragments can be used for either a transfer source or target as required. This is described in more detail in the next section.
Calling Protocol Fragments
Any number of ProtocolFragments can be specified within a file transfer configuration and any number of fragments can be defined for a particular protocol. A particular fragment is referenced by a name attribute and this attribute is referenced by a corresponding fragment reference element in the configuration Profiles branch.
Operation-dependent source and target elements specify the ProtocolFragments element that is to be used. For example:
- A Copy operation requires that CopySource and CopyTarget elements are specified.
- The CopySource and CopyTarget elements in turn are used to specify CopySourceFragmentRef and CopyTargetFragmentRef elements, that respectively define the fragments to be used for each of the two parts of the operation.
See the Configuring Profiles and Fragments - 3 The Profile Branch article for more information about configuring the elements around a ProtocolFragment reference.
The following optional fragments can be specified in addition to ProtocolFragments:
- AlternativeFragments elements are used to specify a number of fragments. These fragments will be applied in order, should, for example, a server not be available. For example, it is conceivable that in some situations a less secure protocol would be tried if the original (more secure) one is not available.
AlternativeFragments are described in more detail here.
- NotificationFragments specify how e-mails informing about successful or unsuccessful file transfer operations are to be sent.
- CredentialStoreFragments are used to retrieve file transfer authentication credentials from a secure source.
Related Sections of this User Manual:
- YADE User Manual - Configuration Formats & Tools
- YADE User Manual - Configuring and Running File Transfers
The use of the Operations element - the only Profiles child element whose use is required - is described in the Operation section of this manual.