To install an extension, please consult the following post: eFORMz Install an Extension

When you install an application in Windows, you run its Setup.exe, or run its .msi file (MSI = Microsoft Installer). After answering a few questions about installation options, the install utility creates any necessary directories, copies all necessary files, and makes any configuration changes necessary.

The “Install an extension” feature in eFORMz provides a similar capability of installing an eFORMz project, automatically creating directories, copying files, and making most of the necessary configuration changes. The feature is made up of two parts:

1. Create the ZIP file containing the install files and a file called “Install.xml”. This step should be performed by someone experienced with eFORMz.
2. Install the extension. This is done from within the eFORMz Composer running on Windows (or Mac), by selecting the Host Tools menu, then one of the following menu commands:
   1. “Install an extension…” – this installs the project on the Windows machine where eFORMz Composer is running.
   2. AS400 > “Install an extension…” – this installs the project on an AS400 or iSeries server that is accessible from the machine running eFORMz Composer.
   3. Unix > “Install an extension…” – this installs the project on a Unix or Linux computer that is accessible from the machine running eFORMz Composer.

Create an Install ZIP File

The only hard requirement for the structure of the ZIP file is that it contain a file in its root directory named “Install.xml”, which must be named precisely this, with an upper-case I and the remaining characters lower-case. Beyond this hard requirement, there are some best practices that will help to simplify the creation and maintenance of your install process, discussed below.

Create the Directory Structure for the Install ZIP File

First you should create the directory structure for your Install ZIP file, naming the base directory “ProjectDelivery” and using the directory conventions described in the following sections for its subdirectories. The Install ZIP file will be created in the ProjectDelivery directory.

Directory “config”

The “config” directory should be created immediately below the root directory where the Install.xml file is located, and should contain all configuration files that are not in the projects directory, such as eFORMzCfg_User.xml, Databases.xml, Printers.xml, etc. Files will be copied one by one from this directory to their destination, sometimes overwriting the existing files and sometimes not.

Directory “projects”

The “projects” directory should be created immediately below the root directory where the Install.xml file is located and should contain one or more subdirectories that contain the eFORMz project files (.efz). We recommend that this directory structure match exactly the desired destination directory structure, so that you can simply copy the entire “projects” directory from the ZIP file to the destination.

Directory “translate”

The “translate” directory is only needed if you have translation table files to install. These are XML files created by the TranslateTableEditor.exe utility (in the eFORMz install directory).

Other Directories

You might have one or more .jar files to install, and these can be placed in a “jars” directory. Or you might have other files that need to be installed with the project.

Create the Install.xml File

The Install.xml file contains the instructions for installing your project and consists of specially named nodes with attributes that each perform a specific operation. The top two nodes always appear in every Install.xml file:

<Install Description=”Project description.”>

<Main Description=”The Main section is always installed.” Default=”true” Required=”true”>

CreateDirectory Command

You should create all the directories needed by your project, including the directory where the project files (*.efz) will be placed, the Input directory and any subdirectories, the output directory and any subdirectories, the translate directory if needed, and any other directories your project will use. You must create a directory before installing files to it, or doing an “install directory” command. You create a directory by including a CreateDirectory XML node, which has one attribute: “Name”.

If the directory already exists, the CreateDirectory command does nothing.

Note: Presently, every directory and subdirectory must be explicitly created. It would be nice if the InstallDirectory command would automatically create its subdirectories, but at present it does not.

<CreateDirectory Name=”projects”></CreateDirectory>

<CreateDirectory Name=”projects/CompanyName”></CreateDirectory>

InstallFile Command

The InstallFile command has several attributes that determine its behavior:

• Source – the source file’s relative path within the ZIP file
• Destination – the destination file’s path relative to the eFORMz install directory
• Type – ASCII or BINARY. Files of type ASCII include .efz, .xml, and .cfg. Files of type BINARY would include graphics files such as .jpg, .jpeg, or .png.
• Required – true or false to indicate whether the file is required or not. This should normally be “true”.
• Overwrite – true or false to indicate whether to overwrite the file if it already exists.

Here are a couple of example XML nodes for InstallFile:

<InstallFile Source=”config/eFORMzPrinters.cfg” Destination=”eFORMzPrinters.cfg” Type=”ASCII” Required=”true” Overwrite=”false”></InstallFile>

<InstallFile Source=”config/Databases.xml” Destination=”Databases.xml” Type=”ASCII” Required=”true” Overwrite=”false”></InstallFile>

InstallDirectory Command

The InstallDirectory command also has several attributes that determine its exact behavior, which are identical to the attributes for InstallFile, with one additional attribute that only applies to directories:

• Source – the source directory’s relative path within the ZIP file
• Destination – the destination directory’s path relative to the eFORMz install directory
• Type – ASCII or BINARY. Since directories can contain files that are both ASCII and BINARY, you should typically specify BINARY, which will handle both types.
• Required – true or false to indicate whether the directory is required or not. This should normally be “true”.
• Overwrite – true or false to indicate whether to overwrite the directory and its subdirectories and the contained files if they already exist.
• Recursive – true or false to indicate whether the copy should be recursive (a deep copy) or just the top-level directory.

Here are a couple of example XML nodes for InstallDirectory:

<InstallDirectory Source=”translate” Destination=”translate” Type=”ASCII” Required=”true” Overwrite=”false” Recursive=”true”></InstallDirectory>

<InstallDirectory Source=”projects” Destination=”projects” Type=”BINARY” Required=”true” Overwrite=”true” Recursive=”true” />

RemoveFile Command

The RemoveFile command is useful when you are installing updates to a previously installed project, and you might have changed the name of one of the files. You can delete the old file using the RemoveFile command. If the file does not exist, the command does nothing, so you can simply leave it in all subsequent version of the Install ZIP file.

Other Benefits

There are some additional benefits of using the “Install an extension” feature:

1. Provides a simple type of version control for your project. At any time, you can create an Install ZIP file that will preserve the state of your project at that moment in time. We suggest naming your ZIP files Project01.zip, Project02.zip, etc., and that you create a project readme.txt file that describes what is in each of these releases.

Manual Steps Needed After Install

After you install an extension, you still need to make some changes manually, such as the following:

1. Edit eFORMzCfg_User.xml or copy the one from the ZIP file. You do not want to blindly overwrite the existing one.
2. If your Director Toolkit configuration file is not named LocalPM.cfg, or you have more than one such file, you’ll need to configure the Director with the name(s) of its configuration file(s), by running the Director_Configure.exe.

Real-Life Example

First the directory structure of the ZIP file is as follows:

config
jars
projects
    CompanyName
       LabelProject
          Test
Translate

The Install.xml file is listed below, with annotations:

<?xml version="1.0" encoding="utf-8"?>

<Install Description="CompanyName shipping label project install">

<Main Description="The Main section is always installed." Default="true" Required="true">

<CreateDirectory Name="projects"></CreateDirectory>

<CreateDirectory Name="projects/CompanyName"></CreateDirectory>

<CreateDirectory Name="projects/CompanyName/LabelProject"></CreateDirectory>

<CreateDirectory Name="projects/CompanyName/LabelProject/Test" />

<CreateDirectory Name="projects/CompanyName/LabelProject/Cache"></CreateDirectory>[1]

<CreateDirectory Name="projects/CompanyName/LabelProject/Cache/Items"></CreateDirectory>

<CreateDirectory Name="output"></CreateDirectory>

<CreateDirectory Name="Input"></CreateDirectory>

<CreateDirectory Name="Input/Queue1"></CreateDirectory>

<CreateDirectory Name="Input/Queue2"></CreateDirectory>

<CreateDirectory Name="Input/Queue3"></CreateDirectory>

<CreateDirectory Name="output/CompanyName"></CreateDirectory>

<CreateDirectory Name="output/CompanyName/LabelWaitQueue"></CreateDirectory>

<CreateDirectory Name="output/CompanyName/LabelActiveQueue"></CreateDirectory>

<CreateDirectory Name="output/CompanyName/LabelArchive"></CreateDirectory>

<CreateDirectory Name="translate"></CreateDirectory>

<InstallFile Source="config/eFORMzCfg_ExternalFunctionsExtra.xml" Destination="eFORMzCfg_ExternalFunctionsExtra.xml" Type="BINARY" Required="true" Overwrite="true"></InstallFile>

<!--Do not overwrite eFORMzCfg_User.xml-->

<InstallFile Source="config/eFORMzCfg_User.xml" Destination="eFORMzCfg_User.xml" Type="BINARY" Required="true" Overwrite="false"></InstallFile>[2]

<InstallFile Source="config/LocalCompanyNameReno.cfg" Destination="LocalCompanyNameReno.cfg" Type="BINARY" Required="true" Overwrite="false"></InstallFile>

<InstallFile Source="config/LocalCompanyNameLouisville.cfg" Destination="LocalCompanyNameLouisville.cfg" Type="BINARY" Required="true" Overwrite="false"></InstallFile>

<InstallFile Source="config/QueueDirs.xml" Destination="projects/CompanyName/LabelProject/QueueDirs.xml" Type="BINARY" Required="true" Overwrite="false"></InstallFile>

<InstallFile Source="config/LocalCompanyNameClearItemCache.cfg" Destination="LocalCompanyNameClearItemCache.cfg" Type="BINARY" Required="true" Overwrite="false"></InstallFile>

<InstallFile Source="jars/NetSuite_2017_1.jar" Destination="jars/NetSuite_2017_1.jar" Type="BINARY" Required="true" Overwrite="true"></InstallFile>[3]

<InstallFile Source="jars/nsi20171.jar" Destination="jars/nsi20171.jar" Type="BINARY" Required="true" Overwrite="true"></InstallFile>

<InstallDirectory Source="translate" Destination="translate" Type="BINARY" Required="true" Overwrite="false" Recursive="true"></InstallDirectory>[4]

<InstallDirectory Source="projects" Destination="projects" Type="BINARY" Required="true" Overwrite="true" Recursive="true" />[5]

</Main>

</Install>

[1] Current best practice is to put Cache directories under the Input directory rather than under the project directory.

[2] Note that we do not overwrite the eFORMzCfg_User.xml file, as it may contain other information we do not want to lose.

[3] Note that jar files can be installed with the project!

[4] The translate directory is set to NOT overwrite the existing files, because translation tables are by their nature extensible and thus should not be overwritten.

[5] The projects directory should not contain any user-editable files, so you can set overwrite to true.