Scope

• Starting from release 1.11 YADE requires XML configuration files.
• SOS provides migration tools that convert existing .ini configuration files to YADE - Configuration files - and vice versa.
• The migration tools are shipped with the XML Editor and recommended to be used with previous YADE releases:
  • The XML Editor can be used to convert .ini files to .xml configuration files.
  • The XML Editor can be configured to create XML configuration files and compatible .ini settings files in parallel for use with YADE releases 1.8 up to 1.10.

Migration Tools

Conversion of .ini settings files to XML configuration files

JS-1528 - Getting issue details... STATUS

• Area of Operation
  
  • Migrate existing .ini settings file to XML configuration files.
• Prerequisites
  • The conversion is provided by a Java plugin that is available with the XML Editor and that is located in the plugins installation folder. 
  • A Java Runtime Environment starting with version 1.8 is required.

Scope of Conversion

• We did our very best to provide a decent conversion utility with approx. 90% coverage of YADE .ini settings files.
• However, some limitations exist that are specified in detail as follows.

Limitations

• The converter tries to identify existing profiles and fragments from your YADE .ini settings file:
  • A fragment is a section in the settings file that is included by other sections, mainly by profiles.
  • The remaining sections of a settings file are identfied as profiles if they
    • do not represent global sections (section header: [globals]) and
    • include an operation setting (having resolved any include statements from the profile section).
• The converter provides limited accuracy when identifying profiles:
  • If a profile from a settings file is included by any other profile then it will be considered a fragment and not a profile.
  • Settings file sections that are not used, that are incomplete or invalid are subject to conversion and might result in conversion errors. We recommend to clean-up existing settings files before conversion.
  • For some profiles no operation setting might have been specified as this can be added by direct parameterization of the YADE Client (command line or job parameter). Such profiles will not be identified as candidates for conversion and will be skipped.
• The XML result file of a conversion might not be valid if
  • empty settings have been used, i.e. settings without assignment, e.g. a missing recipient for a mail_to= setting. Such empty settings are valid for the settings file format, however, they are not valid for the XML configuration file format that implements more strict checking.
  • settings are missing, e.g. have been completed by use of command line parameters or job parameters.
  • The converter will report evident errors and missing parameters, additional errors might become visible when opening the converted configuration file with the XML Editor that validates the file against the YADE XSD Schema.

Implications

• Profiles from settings files that use send/receive operation settings are converted to the respective XML operations Copy or Move (should the setting remove_files=true have been used).
  • Send/receive operations are deprecated, see  YADE-280 - Getting issue details... STATUS
• The YADE XML configuration clearly distinguishes between fragments and profiles. Therefore, the source and target settings from settings files are moved to separate branches of the YADE XML configuration.
  • The names of fragment elements are created from 
    • the fragment type
      • for file transfer sources and targets this includes the file transfer protocol in use (FTP, SFTP etc.)
      • for mail and other elements the element name is used
    • a consecutive number.
    • Examples include: SFTPFragment#1234, FTPFragment#3421, MailFragment#2143 etc.
  • You can modify fragment names easily with the XML Editor that will automatically update references to the fragment.

Usage

• The Plug-in YADE Ini2Xml Converter is activated by hitting the respective button in the menu bar.
  • This operation opens the above dialog that suggests the location of your JRE and of the .ini settings input file that should be converted.
  • Hitting the button Transform will start the conversion. 
• The XML Editor offers to specify an XML output file for the converted content and shows the conversion summary like this:

• When using the Open output result button after conversion then the XML output file is available in an XML Editor tab for further editing.
• The XML Editor can be configured to write compatible .ini settings file when editing XML configuration files.

Conversion of XML configuration files to .ini settings files

• Area of Operation
  • This type of conversion is used for YADE releases 1.8 up to 1.10. You can make use of the XML Editor capabilities and continue to use .ini settings files.
  • The XML Editor provides the Plug-in YADE Xml2Ini Converter that is used to automate the conversion of XML configuration files to compatible .ini settings files.
  • This allows you to switch to using XML configuration with the XML Editor before the arrival of YADE 1.11. Users are not forced to perform a timely migration of the configuration format for release 1.11 but can switch to XML at an earlier point in time and benefit from use of the XML Editor.
  • SOS confirms that valid YADE XML configuration files created for releases prior to YADE 1.11 will be compatible or automatically transformed to YADE 1.11 without loss of functionality.
• Prerequisites
  • The conversion is provided by a number of Java classes that are available with the XML Editor and that are located in the plugins installation folder. 
  • Therefore a Java Runtime Environment starting with version 1.8 is required.

Scope of Conversion

• The converter has been tested to provide a near to 99% conversion of XML configurations to .ini settings files. 
• Restrictions mainly apply due to feature availability with specific YADE releases and are specified in detail as follows.

Limitations

• A few limitations exists that are mainly about features that are available for specific releases.
• For details see YADE - Configuration - XML Editor Compatibility Limitations

Implications

• Users should not modify converted .ini files. All changes to the configuration should be done by use of the XML format. The .ini settings file should always be re-created when changes to the XML configuration are applied. The XML Editor supports automated conversion when saving XML files, see below.
• The XML Editor creates partially redundant settings for the .ini format when applying reusable XML elements. This is of no concern when running YADE with the .ini settings file.

Usage

• The Plug-in YADE Xml2Ini Converter is activated by hitting the respective button in the menu bar.
  • This operation opens the above dialog that suggests the location of your JRE.
  • The Plug-in requires the YADE XSD Schema to be accessible for validation purposes. You can either accept to use the XSD Schema from the proposed location or you can download the XSD Schema and provide the path to the downloaded file.
• The Plug-in can be configured to automatically create an .ini settings file in parallel to saving a YADE XML configuration file.
  • The Autosave output file setting will cause the conversion to be performed automatically when saving files.
  • The .ini settings file will reside in the same folder and will have the same basename as the XML configuration file.