JADE User Manual - Configuring Profiles and Fragments - 3 The Profile Branch

Overview

File transfer parameters in JADE are defined hierarchically and are sorted into two branches - Profiles and Fragments. A Profile specifies what is to be done (e.g. copy from A to B) and the Fragment defines how this is to be done (e.g. using Protocol X, authentication Y, etc.)

The considerations necessary for defining the Profile branch of the configuration are described in this article.

How to generate the Profile configuration

The diagram below shows the parameter hierarchy required to specify a file transfer from a remote source per FTP protocol to the local file system.

When the SOS XML Editor is used to generate the configuration you will be guided using the Add child button to insert valid elements starting with the Profiles element and proceed down the hierarchy.

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.

• Profiles
  • Profile (profile_id= 'p1')
    
    • Operation
      • Copy
        
        • CopySource
          
          • CopySourceFragmentRef
            
            • FTPFragmentRef (Has the ref Attribute which specifies the source ProtocolFragment)
          • SourceFileOptions
            • Selection
        • CopyTarget
          
          • CopyTargetFragmentRef
            • LocalTarget (A ProtocolFragment does not need to be defined here as the target is the local file system)
          • Directory
  • Profile (profile_id= 'p2')
  • etc....

Each individual file transfer is headed up by a Profile, which is added as a child of the Profiles element.

The individual parameters that have to be specified in the Profile are as follows:

• The Profile requires a 'profile_id' which is used to call the profile when the transfer is called from the command line.
• Each Profile element is required to have an Operation element.
• In the example, a Copy operation is specified, which, in turn, requires that CopySource and CopyTarget elements are set.
• The CopySource element requires a CopySourceFragmentRef element that in turn requires an FTPFragmentRef element. This element contains the reference specifying the ProtocolFragment element that in turn specifies the transfer connection parameters such as authentication, protocol, etc.
  • Note that the FragmentRef element (FTPFragmentRef), which is used to specify the ProtocolFragment element, is protocol-specific. This allows optional pre- and post-processing child elements - which are not shown in the diagram - to be added to the profile as child elements of the FTPFragmentRef element. Such elements are protocol-specific.
• The CopyTarget element does not have a corresponding FTPFragmentRef child element as the target is the local file system.

 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

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 JADE 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 protocol fragments have been defined.

Operationally, the starting point is a Profile, which then calls the protocol fragment(s).

Specification of Protocol Fragments

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 parameters such as the authentication method, the connection type and proxy.

The upper levels of the Fragments branch of the XML hierarchy are structured as follows:

• Fragments
  • ProtocolFragments
    • FTPFragment
    • FTPFSRagment
    • etc.
  • AlternativeFragments (optional)
  • NotificationFragments (optional)

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.

The next diagram shows the structure of an example protocol fragment element - the FTPFragment:

• FTPFragment
  • BasicAuthentication
    • Account
    • Password (optional)
  • BasicConnection
    • Hostname
    • Port (optional)

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.

The XML hierarchy used to define the fragments required for a copy operation from a remote source to a target on the local file system is as follows:

• Operation
  • Copy
    
    • CopySource
      
      • CopySourceFragmentRef
        
        • FTPFragmentRef (Has the ref Attribute which specifies the source ProtocolFragment)
      • SourceFileOptions
        • Selection
    • CopyTarget
      
      • CopyTargetFragmentRef
        • LocalTarget (A ProtocolFragment does not need to be defined here as the target is the local file system )
      • Directory

The use of protocol fragments is described in more detail in the Configuring Protocol Fragments article.

General Comments

The advantage of this approach - which may at first seen somewhat complex - is that fragments can flexibly reused within the otherwise strict XML hierarchy and that configurations can be validated against an XSD schema. Validation means that the possibility of configuration errors is greatly reduced.

A Fragment can be used as both a source or as a target within the one Configuration.

Note:

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.
  
  

Each individual file transfer has its own profile, which is added as a child of the Profiles element.

The Profile requires a 'profile_id' which is used to call the profile when the transfer is called from the command line.

JADE use of protoco