Alchemex WEB SOLUTION Installation Best Practices

Purpose

This tutorial / best practices document is purposely intended to be simple and to the point.
The intention is to empower you with all the information required to complete a working
and solid Alchemex WEB installation. This forms part of the Installation Best Practices
series for Alchemex Web Solution as well as the Alchemex Software and Security
Module.

Two Scenarios.

There are two basic installation scenarios, namely installing the Web Solution into an
existing Alchemex Installation site and secondly installing the Web Solution as part of a
brand new Alchemex installation.

Essentially both WEB scenarios share the same installation procedure and options but of
course the new installation would require you to fist read my “Alchemex Ver6 Installation
Best Practices document” as it will cover the Alchemex Software portion of the install.
Frankly it would be a good idea to give it a look through regardless of scenario.

Be Prepared.

• Get a copy of the pre-installation document which will confirm that all the
necessary pre-installation requirement have been met by the client.
• Secure your copy of the Web Installation CD as well as the Alchemex
Serialisation Details.
• Always carry a spare Generic Alchemex & Web Install CD as well as a copy of
ALL the Standard Template sets. (Covering all available source data types as
well) – Having a copy of all the above on a Memory Stick wont hurt either.
• IMPORTANT – The Web Solution will ONLY partner with a Generic Alchemex
installation. If you have plenty of time to waste, then challenge this statement.
(Essentially it revolves around the suffixes appended to the Alchemex.exe on the
likes of Alchemex for Accpac, Syspro, SAP etc. – AlchemexACP.exe in the case
of Accpac – that cause the Web Solution to roll over and die.)

Fitting the pieces in the Puzzle.

There are many possible installation configuration scenarios when it comes to the Web
Install, but this document will give you the “best” way to do it. For this exercise we will
be installing both elements onto two separate servers.

So what is the Web Solution really?

• The Web Solution consists of two separate components – The Request Server and
the Web Application. They can either be installed together on the same server or
be split between two servers.
o The Web Application must run on a machine with IIS installed. It consists
of “Web Pages” with supporting ASP code that resides in the MS ISS
folder – either direct or as a virtual folder.
 o The Request Server resides on either the same server or on another Server
with Alchemex and MS Excel installed.
o Despite the fact that both these elements are required to have a fully
working Web Solution, neither element knows that the other exist as they
“communicate” with each other via a 3rd party. That 3rd party is the
common Alchemex.svd
• Keep in mind that the Standard Alchemex install sees individual Alchemex
installations on ALL end user workstations. The only common thing they share is
that they all point to a common shared folder on the Server. This shared folder
contains the Alchemex.svd files as well as a “Templates” folder containing the
Excel.xlt template files. (Yes there are other folders and files but the above
mentioned ones are the only ones that really matter.
• If you read my “Installation Best Practices for Alchemex 6.0” you will recall that
we DO NOT install Alchemex on the Server. Well this rule is broken when
installing the Web Solution. The reason being that the Web Solution is dependent
on having 24/7 access to an Alchemex Installation (Alchemex.exe) and of course,
using our existing, pre configured, Server folder is the logical choice.

System Requirements.

Recommended System Requirements for Request Server

Operating System : Windows 2000 , Windows XP

Microsoft Excel 2003 or higher
Hardware: Pentium III
Memory: 128MB RAM
Hard Drive Space: 2GB
Alchemex 4.0 or higher, with at least Client Components installed.

Recommended System Requirements for Web Application

Any standard web server setup with IIS and a root folder.

INSTALLING THE REQUEST SERVER

Pre-requisites:

Set up the Domain User Account

Ensure that you have created an account for the service to run under. The Alchemex
Request Server is run as a Windows Service. This appears in the list of installed services
in the Services dialog box available from Control Panel; Administrative Tools; Services.
For Alchemex Request Server to run as a Windows Service it must be assigned a
Windows Service Account, either the Local System or Domain User account.
A Domain User account uses Windows Authentication, that is, the same user name and
password used to connect to the operating system is also used to run the service. A
Domain User account is typically used because it gives access to the network.
The Domain User account must have the following permissions:

• Rights to logon as a service.

• Read/write access to the Alchemex Server Folder e.g. \\MyServer1\Data\
Alchemex60\Standard MetaData Read access to the Output Folder where the
resulting temporary Excel reports generated by Alchemex will be saved. By
default, during installation, the Alchemex Web Report Output folder is created in
the Alchemex Server Folder i.e. \\MyServer1\Data\Alchemex60\Standard
MetaData\Alchemex Web Report Output\. However, you can create a folder
anywhere on the network and change the OutputPath key in the Alchemex
Request Server INI file (\Alchemex60\Request\ALCHSERV.INI) to reflect this
change.
• DCOM Local Launch and Activation permission for the Alchemex COM Server
Application. See Cannot Create ActiveX Component in Installation
Troubleshooting for details on how to modify the security permissions.
• DCOM Local Launch and Activation permissions for the Microsoft Excel
Application. See Permission Denied in Installation Troubleshooting for details on
how to modify the security permissions

Note on Using the Local System Account

The Local System account does not require a password, does not have network access rights in Windows
NT 4.0 and Windows 2000, and as such the Alchemex Request Server will be unable to access the Alchemex
Server Folder and Output Folder if they reside on the network. By default Alchemex Request Server is
installed to run under the Local System account, but in general this should be changed to run under a
Domain User account after installation.

Logon to the workstation with the user account that the service will run under so that you
can configure Alchemex for that account.
Ensure that the user account you logon with has local administrative permissions, or
assign the appropriate permissions to the domain user account.

Ensure that Alchemex on the workstation has been serialized with at least 1 Request
Server license. If you are using Alchemex on the workstation for the first time, then run
the Alchemex Report Manager and choose “Request Server (WEB)” when prompted for
the type of License to use on the machine. If you have already run Alchemex on the
workstation with a standard license then run the License Manager, select your
workstation and set the Workstation License type to “Request Server (Web)”.

If this is the first time the user account has been used to logon to the workstation, launch
Excel to configure it for the user account.

Make sure that you can Run a report manually from within the Report Manager to ensure
that the permissions to folders and templates are sufficient and that Excel is configured
for the user account.

Lastly, ensure that the Request Manager can be launched from Start -> All Programs ->
Alchemex60 -> Request Manager.

The COM interfaces of Alchemex.exe should have been registered when installing the Alchemex
Application. If the interface has become unregistered use the Tools Menu in the PLMAINT.EXE utility
found in your Alchemex Server folder to re-register the ActiveX interfaces. The Request Server uses these
interfaces to communicate with the core Alchemex engine.

To test that the Alchemex Engine is registered correctly and is accessible use the
“RequestRunTestTool.exe” tool located in the \Alchemex60\Request folder.
Although no requests exist at this point pressing the Run button will verify if the component is configured
and registered. If you receive a message “The request of ID 1 does not exist” then communication with the
Server has been successful. If you receive a message “ActiveX component can’t create object” then
communication with the Alchemex Engine has been unsuccessful.

If the interface is not registered correctly or has become unregistered use the "Register Alchemex.exe
COM Server" option Tools Menu in the PLMAINT.EXE utility found in your Alchemex Server folder to re-
register the ActiveX interfaces. The Request Server uses these interfaces to communicate with the core
Alchemex engine. Run the "RequestRunTestTool.exe" again. If you continue to receive an error message
then please see Getting Support for further help.

As a last check to ensure that Alchemex.exe COM interfaces are registered, search the registry for
“Alchemex.Application” and ensure that the LocalServer32 setting is pointing at the correct Alchemex.exe
file.

Installation (Request Server)

To begin the Web Server component installation, insert the Alchemex Web Components
Installation CD into your CD drive. Launch the Alchemex Request Server setup exe from
your CD (<CD Drive>:\Alchemex Request Server\SETUP.EXE).

For Alchemex Request Server to install you must have .NET Framework on the target
machine. If .NET Framework 1.1 is not installed then you will be prompted at the
beginning of installation with the following message, “Alchemex Request Server
optionally uses Microsoft .NET 1.1 Framework. Would you like to install it now”. You
must choose “Yes” if you do not have .NET Framework on the target machine. If you
choose “No” then the installation will fail.

Follow instructions on screen. When you have read the License agreement and if you
accept the terms of the agreement then select “I accept the terms in the license
agreement” option and press the Next button and continue with the installation.

When prompted for the Destination Folder then browse to or enter the name of the Folder
on your local machine hard drive. By default this is usually the C:\Program
Files\Alchemex60 folder. It is recommended that you use this path for the Request
Server.

When prompted for the Server Folder then browse to or enter the name of the Alchemex
Server Folder on your network or on the local machine where you want the Request
Server to point to. You should use the UNC (universal naming convention) for the folder
on your server as opposed to using drive mappings. The UNC naming convention is of
the form \\SERVERNAME\SHARENAME\Alchemex60\Standard MetaData e.g.
\\MyServer1\Data\Alchemex60 \Standard MetaData. Once you have made all your
selections press the Finish button to begin the installation. The installation program will
now proceed to install all the necessary files and settings.

By default, an [Alchemex Web Report Output] folder is created in the Alchemex Server
Folder that you have selected e.g. \\MyServer1\Data\Alchemex60\ Standard
MetaData\Alchemex Web Report Output\. This is the area where the resulting temporary
Excel reports will be saved. Ensure that the user account that will run the service has
rights to access this area. If you wish to change the place to which the Excel reports are
saved then you can move the folder and change the OutputPath setting in the Request
Server INI file (ALCHSERV.INI) at the end of the installation process.

On completion of installation you will need to configure and start the service. Before
doing so, browse to the Request Server INI file (ALCHSERV.INI) in the
Alchemex60\Request folder on the workstation, and check the default settings for the
service and make changes as necessary. (See the installed Alchemex Web Solution help
file for more details on these settings).

Lastly, from the Start; Control Panel; Administrative Tools; Services; right click on the
service called Alchemex Request Server and choose Properties. On the Log On tab
change the “log on as” details to use the account you configured at the beginning of the
installation. Once configured, start the service to complete the installation.

Installation Troubleshooting

Some of the more common Installation issues are listed below along with recommended
action.

1. Insufficient User Permissions

By far the most common problems during an installation are those related to Workstation
and Network Security. Please make sure that you are running under an account with
administrative rights during an installation. The error messages that you will receive if
you do not have sufficient privileges will not necessarily point to security issues and they
may be misleading. It is therefore essential that you make sure that you have
administrative privileges before commencing with an installation.

2. Error: Outdated Windows Installer

When attempting to install the following message is displayed: -

"The installation package cannot be installed by the windows installer service. You must
install the windows service pack that contains a newer version of the windows installer
service." To resolve the problem,

1. Reboot the machine. If this does not solve the problem attempt step 2 or 3
2. Navigate to the Alchemex Installation CD and run INSTMSIA.EXE for Win 9x
and Window ME OR INSTMSIW.EXE for Win NT and Win 2000 This will run
Microsoft Installer version necessary to run the Alchemex Installation, try
rerunning the Alchemex SETUP again now.
3. Install the latest service pack for the operating system prior to installing Alchemex

3. Error: NT 4.0 Service Pack 5 Required

Alchemex will not install on Windows NT 4 unless Service pack 5 or later has been
applied. The X86 NT Workstation SP 5 is included on the Alchemex CD for your
convenience. For NT 4.0 Server editions please obtain the latest service packs from
Microsoft.
4. Run Time Error '3706': Provider cannot be found. It may not be properly installed

This error can occur after installation when trying to run Alchemex if there are ADO or
MS Jet problems on the workstation. Please refer to the knowledge base article
http://www.alchemex.net/issues.asp?id=15 to resolve the problem.

Uninstalling Alchemex Request Server

Uninstalling Alchemex Request Server uses a “safe” removal method. Any files which
have been altered since Alchemex Request Server has been installed are not removed by
the uninstall. For this reason to completely remove all of the Alchemex Request Server
files you will need to uninstall Alchemex Request Server and then delete the Alchemex
Request Server folder from the hard drive.

INSTALLING THE WEB COMPONENT

Pre-requisites:

Ensure that your web server is setup with Internet Information Services and a root folder.
IIS can be installed from Control Panel; Add or Remove Programs; Add/Remove
Window Components and selecting the Internet Information Services component to be
installed. Your Windows Installation disk will be required for installation of IIS.

Ensure that you have created a user account for the Alchemex website to run under. In
general this is likely to be the same account as the one you configured the Alchemex
Request Server service to run under. If the Alchemex Server Folder, or the Output Folder
created during installation of Alchemex Request Server will reside on the network then
this must be a Domain User Account with read/write access to the Alchemex Server
Folder and read access to the Output Folder.

Log on to the operating system under a user account that has local administrative
permissions, or assign the appropriate permissions to the Domain User Account.

Installation (Web Component)

Launch the Alchemex Web Application setup exe from your CD (<CD Drive>:\Alchemex
Web Application\SETUP.EXE).

If .NET Framework 1.1 is not installed on the target machine then you will be prompted
at the beginning of the installation with the following message, “Alchemex Request
Server optionally uses Microsoft .NET 1.1 Framework. Would you like to install it now”.
You must choose “Yes” if you do not have .NET Framework on the target machine. If
you choose “No” then the installation will fail.

Follow instructions on screen. When you have read the License agreement and if you
accept the terms of the agreement then select “I accept the terms in the license
agreement” option and press the Next button and continue with the installation.

When prompted for the Destination Folder then browse to or enter C:\Program
Files\Alchemex60 folder. It is recommended that you use this path for the Web
Application components. (The installation sets up a virtual drive mapping to the IIS
folder)

When prompted for the Server Folder then browse to or enter the name of the Alchemex
Server Folder on your network or on the local machine where you want the Request
Server to point to. You should use the UNC (universal naming convention) for the folder
on your server as opposed to using drive mappings. The UNC naming convention is of
the form \\SERVERNAME\SHARENAME\Alchemex60\Standard MetaData e.g.
\\MyServer1\Data\Alchemex60 \Standard MetaData.
The user account you created must have permissions to access the Server Folder if it is on
your network.

Once you have made all your selections press the Finish button to begin the installation.
The installation program will now proceed to install all the necessary files and settings.

On completion of installation you will need to change the IIS security settings for the
Web Application.

Open Internet Information Services from Administrative Tools -> Internet Information
Services
Drill down in the local computers Web Sites folder to the Alchemex web site and right
click to open the properties.
On the Directory tab click the “Create” button next to “Application Name”.
Click on the "Configuration" button. On the Options tab ensure that "Enable Session
State" is selected and set the timeout period, by default this is 20 minutes. Close the
Configuration screen to return to the main Properties screen.
On the Directory Security tab click the "Anonymous access and authentication control"
edit button.
Ensure that “Anonymous Access” is selected while all other “Authenticated Access”
options are deselected.
With Anonymous Access selected, enter the User Name of the account you created above.
Deselect the “Allow IIS to control password” option
Enter the password and then click “OK”.
Apply the changes and confirm the password when prompted before exiting.

Lastly, browse to the Web Application INI file on the workstation in the \Binn directory
of the Alchemex web folder (C;\Inetput\wwwroot\Alchemex\Binn\PLALCWEB.INI) and
check the default settings for the Web Application and make changes as necessary. See
Configure Web Application INI in the install CD help file for further details.

To verify that Alchemex Web Application is working correctly, browse to the Alchemex
Web Application home page, http://SERVERNAME/Alchemex/AlchemexMain.htm.
Ensure that the page loads without any errors. Drill down to a report and click the Run
Report button. A pop up screen, RequestStatus.asp, should display details of the Report
request you have logged. If the Request Server has been installed and switched on, the
web page will refresh with the latest request status.

Troubleshooting
Alchemex Web Solution uses the event log to log errors that occur. To view the Event
Log go to Control Panel -> Administrative Tools -> Event Viewer. Errors occurring in
the Request Server are logged to the Application Log and have a source name of
Alchemex Request Server Log. Errors occurring in the Web Application are logged to
the Alchemex Web Application Log.

There are some limitations to the Web Solution that users should be aware of

When downloading an Excel file that contains a pivot table, if the Open option is selected
from the Download File Dialog box rather then the Save option then you will not be able
to refresh the pivot table. For the pivot table to function correctly, you should choose
Save and save the file to a valid folder. This is due to a problem with Temporary Internet
Files which which are saved to a temporary location when the Open option is chosen.

The ASP (Active Server Pages) pages provided on the installation CD make use of
frames, these may not be supported with your browser version. If this is the case then you
can alter the ASP pages to work with your browser.

Union Reports that use parameters will not run on Version 2.0 and earlier.

Reports that use Picklist connections will not work.