IFS Installer Interface

This document describes the Components Interface to the Installer.

Element	Description
<component>	The Component name
<installable component>	The main component "solutions", e.g. client, server, webclient
<sub component>	Component belonging to some of the above
${ant.property}	ant property

The Installer will scan all folders in it's <build_home> for config*.xml files, parse them and execute the tags stated.

There are two main sections in the Installer interface

parameter entry
Install, Configure
actual execution per OS
Analyze, Install, FileExec, DeployDB, Delete, Configure, Build, Post and Finalize

Note: FileExec and DeployDB should only be defined and used in component server (config_fndbas.xml)

All files, tags and possible actions are described in detail in this chapter.

Control and Plug-in Files
Config.xml
Install.xml
Build.xml
Component installer.jar

Control and Plug-in Files

File types

An <installable component> owns the following files:

config.xml, mandatory
The main file and it holds the logic for the installation. Basic name and description for the component,
queries and pointers to ant scripts or plug-ins to be run at the Analyze, Install, FileExec, DeployDB, Delete, Configure, Build, Post and Finalize steps.
install.xml, mandatory
Ant script file with ant targets for the above steps stated in config.xml.
The 'install' target is the only mandatory.
build.xml, optional
Ant script file with targets for building the applications in a <ifs_home>.

A <sub component> owns the following files:

config_[component}.xml
build_[component}.xml, optional
component_installer.jar, optional. A Jar file plug-in with specific forms and actions.

File location

Archive structure
\<component>\<installable component> from where they will be copied to <build_home> by IFS Configuration Builder.
<build_home> structure
\<installable component> and the plug-in should be compiled with output in \<installable component>\install_plugins.
<ifs_home> structure
\repository\<installable component>

Config.xml

This is the main control file in xml format used by Installer for a <installable component>.

<?xml version="1.0" encoding="UTF-8"?>
<config name="<installable component>" desc="Component Description" version="1.0.0">

The desc and version are displayed by Installer when Selecting Components to install to your target IFS home.
<installable component> must match the folder name.

Parameters Tag

<parameters>
    <parameter parameter="ifs.server.user"  value="ifs" desc="Server User"/>
    <parameter parameter="ifs.server.group" value="ifs" desc="Server Group"/>
</parameters>

Parameters passed to all targets used in this config file.

Jarfiles Tag

<jarfiles>
    <file value="xxxxxx.jar"/>
</jarfiles>

The jar file that should exist in "<installable component>"\javaruntime folder. A Java Class can be loaded by Installer from this jar file and executed.

DefaultParameters Tag

<defaultparameters>
  <parameter parameter="ifs.db.port" value="1521" desc="Oracle Port"/>
<defaultparameters>

Parameters that can be used in plug-in as default parameters in forms.

Example:

FndbasConstants.java:
 public static final String PARAM_FNDBAS_DB_PORT = "ifs.db.port";

OracleConfigForm.java:
 Properties prop;
 prop = InstallTool.getDefaultParameters(params, this.name);
 this.txtPort.setText(prop.getProperty(FndbasConstants.PARAM_FNDBAS_DB_PORT));

PropParameters Tag

<propparameters>
  <parameter parameter="ifs.url" value="${ifs.apache.url}" desc="URL"/>
<propparameters>

Parameters that will try to fetch its value from the build.properties file in an instance. In this example the ifs.url parameter will get the value of ifs.apache.url.

Install and Configure Tags for parameter entry

Two main tags defines the user interface logic for parameter entry when running the Installer:

The install tag is processed only when installing from a <build_home> to the target <ifs_home>.
Forms and queries will appear in defined order. In this example the form MainDeploymentForm1 will be called, then a dynamic table window with two parameters to accept, and next the AppDeployListPanel1.

Example:

<install>
  <forms>
    <form parameter="form" value="MainDeploymentForm1"/>
  </forms>
  <queries>
    <query parameter="ifs.server.port" value="80" desc="Server Port" type="1"/>
    <query parameter="ifs.server.name" value="java:java.net.InetAddress.getLocalHost().getHostName()" desc="Host"/>
  </queries>
  <forms>
    <form parameter="form"   value="AppDeployListPanel1"/>
  </forms>
  <dependon>
    <component name ="fndbas"/>
  </dependon>		
</install>

The configure tag is always processed.

Example:

<configure>
  <forms>
    <form parameter="form" value="MainDeploymentForm2"/>;
  </forms>
  <queries>
    <query parameter="ifs.server.name"  value="localhost" desc="Server" type="1"/>
    <query parameter="ifs.server.port"  value="4444"      desc="Server Port"/>
  </queries>
  <forms>
    <form parameter="form" value="AppDeployListPanel2"/>
  </forms>
</configure>

Forms and Queries Tags

In both tags, install and configure, the following sub tags can be used:

<...>
  <forms>
    <form parameter="form" value="MainDeploymentForm2"/>
  </forms>
  <queries>
    <query parameter="ifs.server.port" value="80" desc="Server Port" type="1"/>
    <query parameter="ifs.server.name"
           value="java:java.net.InetAddress.getLocalHost().getHostName()" 
           desc="Host"/>
  </queries>
</...>

Forms tag refers to a class in a plug-in that will be called by installer.

Queries tag queries will be shown in a dynamic table, and values can be edited.

parameter
the identifier you want to use saved in a parameter collection for further use.
value
will be shown and can be edited saved in a parameter collection for further use.
Value can be set to as a static java method. In the example the java.net.InetAddress class will be loaded, static method getLocalHost called, on the result getHostName will be called and the string result will be presented as default value for the query. If an error occurs, the input will be presented as default value, no error will be raised.
desc
the description for the identifier.

type

Value	Action
0 or not specified	private parameter name and value
1	public parameter name and value
2	private parameter name and value, encrypted
3	public parameter name and value, encrypted

For type "1" and "3", the parameter name and value will be saved in the parameter collection in a general tag, not in a section for the component. If the parameter belongs to a install tag, then the parameter name and value will be saved in general tag for installation, otherwise in general tag for configuration.

If same parameter name is later used by another component, with type equals "1" or "3", the value will be shared between the components. If a component saves the data as type "1" and another used it as type "3", the latter component will try to decrypt the value and will end up with wrong value.

Dependon Tags

<install>
.
  <dependon>
    <component name ="fndbas""/>
  </dependon>
.
</install>

Dependon tag can only be defined inside a install tag and will control the order for the components to be processed by the Installer. This tag can be used when a component has an install order dependency to another component, e.g. a value should be used in the plug-in that another component will set. If the referred component is not included in installation process nor already installed, no error will be raised.

If dependon tag is defined in <sub component>, the logic will be used to sort the plug-ins, in the <installable component>, in defined dependency order. The dependency order will be analyzed when installation or reconfiguration is performed.

For a <installable component> it controls the order for <installable component>.
For a <sub component> it controls the order for <sub component> in <installable component>.

Installhidden Tags

<install>
.
  <installhidden>
    <component name ="model""/>
  </installhidden>
.
</install>

Installhidden tag can only be defined inside an install tag and can only be specified in config.xml, not in sub config.xml (config_[component].xml).
This tag can be used if the component should install another component included in the installation, defined as hidden component, e.g. model component.

Requiredcomponent Tags

<install>
.
  <requiredcomponent>
    <component name ="server""/>
  </requiredcomponent>
.
</install>

Requiredcomponent tag can only be defined inside an install tag and can only be specified in config.xml, not in sub config.xml (config_[component].xml).
This tag can be used when a component has a dependency to another component that must be included in the installation or already is installed.

Requireddeploycomponent Tags

<configure>
.
  <requireddeploycomponent>
    <component name ="server""/>
  </requireddeploycomponent>
.
</configure>

Requireddeploycomponent tag can only be defined inside a configure tag and can only be specified in config.xml, not in sub config.xml (config_[component].xml).
This tag can be used when a component has a deployment dependency to another component and requires that the component must be included in deployment to the application server.

Classes Tags

<configure>
.
  <classes>
    <class parameter="class1" value="ModuleLoader"/>
  </classes>
.
</configure>

Classes tag can only be defined inside a configure tag and refers to a class in the component's plug-in that will be called when configuration step will be run by the Installer.

Analyze, Install, FileExec, DeployDB, Delete, Configure, Build, Post and Finalize tags for actual execution

When declaring the ant script in different operating system/version, nine different tags (analyze, install, fileExec, deployDB, delete, configure, build, post, finalize) can be used.

Note: FileExec and DeployDB should only be defined and used in component server (config_fndbas.xml)

Example:

<!-- Script to run per OS, platform and version when Install is clicked -->
<!-- nine different tags (analyze, install, fileExec, deployDB, configure, build, post, finalize, delete) -->
<os name="windows" desc="Microsoft Windows">
  <platform name="x86" desc="Intel IA32-x86">
    <version name="other" desc="Windows">
 
      <analyze name="Analyze" desc="Analyze delivery">
        <antscript filename="install.xml" target="analyze">
 	  <parameter name="apache.archive.path" value="installer/os/windows/redist/apache"/>
	  <parameter name="apache.archive.file" value="apache2063_nt_50_ia32.zip"/>
	  <parameter name="openssl.archive.path" value="installer/os/windows/redist/openssl"/>
	  <parameter name="openssl.archive.file" value="openssl098h_nt_50_ia32.zip"/>
       </antscript>
      </analyze>

      <install name="fndwin" desc="Foundation1 Framework" type="mandatory">
        <antscript filename="install.xml" target="install.all-os-versions"/>
      </install>

      <fileExec name="database" desc="Database Administration" type="mandatory">
	<antscript filename="install_fndbas.xml" target="file-executor">
  	  <parameter name="script.path" value="tag:install+main+script.path"/>
	  <parameter name="script.path2" value="tag:install+main+script.path2"/>
	  <parameter name="temp.path" value="tag:install+main+script.log.path"/>
	  <parameter name="ifs.user" value="tag:configure+fndbas+ifs.user"/>
	  <parameter name="jdbc.url" value="tag:configure+fndbas+jdbc.url"/>
	  <parameter name="logfile.path" value="tag:install+main+script.log.path"/>
	</antscript>
      </fileExec>

      <deployDB name="database" desc="Database Installation" type="mandatory">
	<antscript filename="install_fndbas.xml" target="install-database">
	  <parameter name="install.tem.path" value="tag:install+main+install.tem.path"/>
	  <parameter name="temp.path" value="tag:install+main+install.tem.log.path"/>
	  <parameter name="ifs.application.owner" value="tag:configure+fndbas+ifs.application.owner"/>
	  <parameter name="jdbc.url" value="tag:configure+fndbas+jdbc.url"/>
	  <parameter name="logfile.path" value="tag:install+main+install.tem.log.path"/>
	  <parameter name="silent" value="tag:install+general+ifs.installer.silent"/>
	  <parameter name="run.install.tem" value="tag:configure+data-initialization+run.install.tem"/>
	  <parameter name="ifs.main.mode" value="tag:install+main+ifs.main.mode"/>
	</antscript>
      </deployDB>

      <configure name="fndbas" desc="IFS Base Server">
         <antscript filename="install.xml" target="generate-conf-files">
            <parameter name="appserver.auth.method" value="tag:configure+appserver-authentication+appserver.auth.method"/>
         </antscript> 
      </configure>
 
      <build name="fndwin1" desc="Foundation1 Framework1" type="mandatory">
        <antscript filename="build_fndwin.xml" target="build1"/>
      </build>
 
      <build name="fndwin2" desc="Foundation1 Framework2" type="mandatory">
        <antscript filename="build_fndwin.xml" target="build2"/>
      </build>
 
      <post name="installer" desc="Configuration">
         <antscript filename="install_fndbas.xml" target="import-profiles">
            <parameter name="jdbc.url" value="tag:configure+fndbas+jdbc.url"/>
            <parameter name="install.profiles" value="tag:configure+data-initialization+install.profiles"/>
         </antscript>
      </post>

      <finalize name="Finalize" desc="Finalize">
         <antscript filename="install_fndbas.xml" target="connect-finalize">
            <parameter name="connectserver.service" value="tag:configure+install-services+connectserver.service"/>
            <parameter name="connectserver.service.start" value="tag:configure+install-services+connectserver.service.start"/>
         </antscript>
      </finalize >
 
      <delete name="J2EE delete" desc="J2EE Delete">
        <antscript filename="install.xml" target="j2ee.delete">
          <parameter name="ifs.j2ee.instance"
                     value="tag:configure+mainaction+ifs.j2ee.instance"/>
          <parameter name="servertype"
                     value="tag:configure+appserver+servertype"/>
        </antscript>
      </delete>

Analyze and Install tag will be called when installing from <build_home> to <ifs_home>.

Note: The analyze tag will also be executed when you install a delivery after you have pointed out the path to the delivery in the wizard form.
Logic for specific actions can be added to inform the user, by using ant input command. Valid accepted arguments are YES/NO or OK. When analyze tag is executed in the install/configure process, the ant input command will be ignored by automatically send YES or OK to the target.

If the content of the delivery will require a system restart, then the analyze target should set the property ifs.systemrestart by calling the SystemRestart class.

<target name="SystemRestart">
  <taskdef name="SystemRestart" classname="ifs.application.installer.tools.SystemRestart">
    <classpath>
      <pathelement location="${ifs.dist.home}/installer/installer.jar"/>
      <pathelement location="${ifs.home}/repository/installer/installer.jar"/>
    </classpath>
  </taskdef>
</target>

<target name="create-restart" if="create.restart" depends="SystemRestart">
  <SystemRestart ifsHome="${ifs.home}" propValue="${ant.file}, analyze: ${ifs.dist.home}/${ifs.bin.os.dir}" />
</target>

A component can be defined as hidden component. This means that the component will not be shown as installable component, and can therefore not be selected.
To get this component installed, another component has to be selected that will install this hidden component. See section Installhidden Tags.

      <install name="model" desc="IFS Applications Model" type="hidden">
        <antscript filename="install.xml" target="install.all-os-versions"/>
      </install>

A component can be defined as showme component. This means that the component will be shown as optional installable component, and can therefore be selected.

      <install name="ifsdoc" desc="Documentation" type="showme">
        <antscript filename="install.xml" target="install"/>
      </install>

FileExec and DeployDB tag is used when deploying code to the database. The server plugin has the forms for this steps, and therefore only server plugin should have these tags defined in it's config_fndbas.xml.
- FileExec will be called when running Prepare Database / File Executor. Only valid when running from <build_home>.
- DeployDb will be called when running Deploy Database Objects when running from <build_home>, or when installing a delivery including database code, when running from <ifs_home>.

Delete, Configure, Build, Post and Finalize tag will be executed for your Instance on the <ifs_home>.

The description in the build tag will appear in Select Components to Deploy.
The value for name in the build tag will be the key for what to deploy and must be unique.

When ant scripts are called, a number of parameters will always be passed to the scripts, and there are also possibilities to specify additional parameters for specific ant scripts. Depending on in which tag the ant scripts are declared, different parameters and values will be passed.

Ant scripts can also load the property file for the current Instance that is created by Installer as
${ifs.home}\instance\${instance_name}\build.properties.
This property file will include properties with the ifs. prefix.

Properties passed to ant scripts

Always passed in installation and configuration:

Property	Value/Description
${ifs.dist.home}	<build_home>
${ifs.home}	<ifs_home>
${ifs.os.name}	os name from install script
${ifs.os.arch}	platform name from OS
${ifs.os.version}	version name from OS
${j2ee.deploy}	${ifs.home} + "stage/ear", if not specially defined in config.xml for installer.
${distribution}	${ifs.home} + "stage/jar"
${ifs.j2ee.instance}	current Instance name
${ifs.config.name}	value of name from current config.xml
${ifs.config.desc}	value of desc from current config.xml
${ifs.config.version}	value of version from current config.xml

Parameter

If a parameter parameter already exists in the general tag in parameter collection, the value of that parameter will be used, else the stated value.

When running install, the existence is checked in installtool+install+general section and when running configure, it is checked in installtool+configure+general section.

QueryParameters
Parameters defined as queries in install or configure tag, depending on witch step are run, will be passed to ant scripts.

FormParameters
If any form saves parameters in tag installtool+install+components+[componentname]+forms for install step or installtool+configure+components+[componentname]+forms for configure step, these parameters will be passed to ant scripts.

Ant script specific parameters

<antscript filename="xxxxx.xml" target="xxxx.yyyy">
  <parameter name="
  <parameter name="ifs.templates.version" value="1.0.0"/>
  <parameter name="oracleurl" value="tag:config+fndbas+oracleurl"/>
</antscript>

<parameter name=";ifs.templates.os" value="..." type="1"/>, value of parameter ifs.templates.os will be checked in installtool+install+general section if running install step, else in installtool+configure+general section. If not found, default value will be passed.

<parameter name="ifs.templates.version" value="1.0.0"/>, value of parameter ifs.templates.version will be passed as value.

<parameter name="oracleurl" value="tag:configure+fndbas+oracleurl"/> , value of parameter oracleurl will be checked in tag installtool+configure+fndbas+oracleurl. Accepted value is the one beginning with "tag:"

Install.xml

This is the ant script file, specified in config.xml file for a <installable component>.

The contents is ant targets with different ant tasks to be performed for the <installable component>.

Example of a simple install.xml file:

<?xml version="1.0" encoding="UTF-8" ?> <project basedir="." default="install.all-os-versions" name="generic"> <target name="install.all-os-versions"> <copy todir="${ifs.home}/templates/${ifs.config.name}" overwrite="true"> <fileset dir="${basedir}"/> </copy> <echo>Installing ${ifs.config.desc} done!</echo> </target> </project>

Own java classes for ant

Example on how to specify a class in components jar file to be available in this install.xml:

<taskdef name="set_manager_mask" classname="WebClientANTTask" classpath=install_plugin/<component>_installer.jar/>

Build.xml

The build.xml is owned by the [installable components] and specify what to be deployed.

This can be the standard build.xml for the [installable components] and the target to call from config.xml is e.g. 'pack-module'.

Component_installer.jar

This file handles specific forms and actions not handled by ant scripts, named <component>_installer.jar
and it resides in ../<installable component>/install_plugins.

All classes configured to be run by the Installer has to be created in the package ifs.application.installer.installationclasses.

To be able to create the classes, the Installer's installer.jar has to be added to the classpath.

Constants

A good practice should be to have an own class, if needed, containing all constants that will be referred to from your own classes. This class can import the class ifs.application.installer.tools.InstallConstants to be able to refer to declared constants in the Installer. For example InstallConstants.PARAM_INSTALL + "+<component>", or InstallConstants.PARAM_CONFIG + "+<component>" refers to the correct tag in the ParameterCollection for saving class specific information and can then be reused if defined in the class. The constant class should be named <component>constants.

Form

Classes that should be imported are:

ifs.application.installer.Install
ifs.application.installer.tools.*
ifs.application.installer.parameters.Parameter
ifs.application.installer.parameters.ParameterCollection

To be able to run an own form in the install wizard the class must implement the interface WizardElement .

A constructor like <component>[FormClass](Install main, String name, ParameterCollection params) must exist in the class.

The logic in Installer is to add these defined forms to the installer in the order they appear in the config.xml file.

The implemented method showMe from the interface will be called for the class, and logic to show already defined values in ParameterCollection can be implemented.

When exiting the form method setParameters will be called, and methods for saving values in ParameterCollection can be added.

Help Pages for wizardForms

Help pages for forms in the installer should be placed in the path ifs/application/installer/help. The name of the html file should be [FormClass].html where FormClass is the name of the java class.

Class that performs the configuration task

Classes that should be imported are:

ifs.application.installer.tools.*
ifs.application.installer.parameters.Parameter
ifs.application.installer.parameters.ParameterCollection

To be able to run the class in the configure step the class must implement the interface InstallerPlugin.

A constructor like <component>[ConfigClass]() must exist in the class.

The logic in Installer is to add classes in the configure step in the order they appear in the config.xml file.

The implemented method execute from the interface will be called for the class, and InstallToolTasksExecutor, ParameterCollection and FileSystemUtil will be passed to the method.

Example of defining form and class in config.xml for the Config step:

<configure>
  <forms>
    <form parameter="form" value="WebClientSitesTable"/>
  </forms>
  <classes>
    <class parameter="class" value="WebClientInstaller"/>
  </classes>
</configure>

IFS Installer Interface

Contents

Control and Plug-in Files

File types

File location

Config.xml

Parameters Tag

Jarfiles Tag

DefaultParameters Tag

PropParameters Tag

Install and Configure Tags for parameter entry

Forms and Queries Tags

Dependon Tags

Installhidden Tags

Requiredcomponent Tags

Requireddeploycomponent Tags

Classes Tags

Analyze, Install, FileExec, DeployDB, Delete, Configure, Build, Post and Finalize tags for actual execution

Properties passed to ant scripts

Always passed in installation and configuration:

Parameter

Ant script specific parameters

Install.xml

Own java classes for ant

Build.xml

Component_installer.jar

Constants

Form

Help Pages for wizardForms

Class that performs the configuration task