· APXDB version 2.0
· ODBC definitions on the web-server
· Installation of the required components for webAPX
· Installation of webAPX on the server
·
Special considerations to access the
APX-Spools
· Access to webAPX from a local or remote workstation
· Customization of the Forecast scrips
·
Installation’s guide for webAPX
·
Administrator’s guide for webAPX
·
Frequently asked questions for webAPX
The
current version of webAPX, option for APX,
can be installed on Window, Linux and Unix servers
running 32 bits or 64 bits. We recommend the utilisation of a 64bits server.
The
current version of webAPX is compatible with
the Apache2 and IIS web-servers.
The help of webAPX contains a
table explaining the compatibility of webAPX
with the different operating systems and database managers.
The
present document describes the installation of each component needed on a
server running webAPX.
Starting
with the version 2.0 of the APX
database two additional views must be installed to allow access to webAPX:
‘PCCDBA.HIERARCHY_LIST’ and ‘PCCDBA.OBJECT_LIST’.
If these views are not already installed in your Database please ask for them
to your webAPX representative with the procedure to
install and to set the rights to these database objects.
With the version 2.0 of the APX database the SQL Server ODBC Native Client
should not be used due to wrong display of the descriptions. Please use the
default SQL Server ODBC.
Introduction:
webAPX accesses the Production Database
with the ODBC driver delivered by the database supplier. The installation
documentation of the DB supplier describes the installation process.
The same kind of ODBC definitions as the one used by APX‑Control
or APX/PCC should be created for webAPX.
Even when webAPX runs on the same
server as APX‑Control we recommend to create a
specific Data Source for webAPX. That Data
Source must be a system Data Source.
SQL Server:
Note: The
ODBC drivers named ‘SQL Native Client’ version cannot be used with webAPX; with
this driver the profiles descriptions are not be displayed correctly and the
pages containing these descriptions are generally empty. Please use the driver
named: ‘SQL Server’.
The 32 bits or 64 bits version of the
ODBC-Sources Manager used to define the ODBC connection to webAPX must correspond to the
version of Apache2 installed; 32 or 64 bits.
The ODBC driver supplied by Microsoft must be installed
and customized the same way you did it for APX/PCC or APX-Control.
The Data Source definition must require a SQL authentication; trusted
connections are not possible. The Data source must be a System one.
Oracle database with Apache2 under Windows:
webAPX can access an Oracle Database with
the ODBC driver delivered by Oracle. We recommend installing ‘Instant Client
12.1’ on the webAPX server. The recommended
version of the driver can be downloaded from the Oracle website. The Instant
Client Base and ODBC packages must be installed as
described in the Oracle documentation.
The
installation of the ODBC driver under Windows is straight forward:
1.
Unzip
the two distribution files into a directory of your choice, further called
‘ODBC-Directory’.
2.
Run
the program ‘<ODBC-Directory>\odbc_install.exe’.
This is a very quick runner.
3.
Create
or customize the
following System variables based on your environment:
PATH=<ODBC-Directory>
NLS_LANG=FRENCH_FRANCE.WE8MSWIN1252
4.
Reboot
the server (this is mandatory).
5.
Create
your System ODBC Data Source with the standard Windows tools.
Please note the recommended format of the following parameter:
TNS Service Name = //<APX DB
server>:1521/<DB-Name>
Oracle with Apache2 under Linux / Unix:
The standard package unixODBC is a prerequisite on the Linux / Unix server to connect to an Oracle database. This package
must be installed before moving to the next steps. The minimum recommended
version is: ‘2.3.1’.
The ODBC-Extension of PHP must be installed too.
Installation
and customization steps for the ODBC driver with Oracle:
1.
If
not already done, as ‘root’ create the ODBC parameter members with the
following command:
cd
$ORACLE_HOME/odbc/utl/odbc_update_ini.sh
Customize the ODBC
source definition member:
vi
/root/.odbc.ini
Change the Data Source Name twice and the ‘ServerName=’ parameter. i.e:
ServerName
= //<machineName>:1521/<dbName>.
Move the this member to ‘/etc’ in order to be accessed by Apache2/PHP:
mv
/root/.odbc.ini /etc/odbc.ini
Sample members are
supplied in the ‘tools/oracle‘ directory of the webAPX distribution.
2.
If
webAPX is not running on the same server as
the Oracle Database, copy the member ‘tnsnames.ora‘ from the
Oracle server to connect to :
cp $ORACLE_HOME/network/admin/tnsnames.ora <were needed>.
A sample member is supplied in the ‘tools/oracle‘ directory of the webAPX
distribution.
3.
Set
the site specific Oracle environment variables for Apache2/PHP in the member /etc/apache2/envvars
by defining the
following variables based on your environment:
export
ORACLE_HOME=/u01/app/oracle/product/11.2.0/xe
export
NLS_LANG=FRENCH_FRANCE.WE8MSWIN1252
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH
A sample member is supplied in the tools/oracle directory of the webAPX
distribution.
4.
Check
the connection as the oracle user with the command:
isql
–v webAPX PCCDBA <password>
Informix under Windows:
For Windows systems Informix supplies an ODBC
driver to access the Production Database. The standard installation of the ODBC
is sufficient for webAPX.
Informix under Linux / Unix:
For Linux and Unix
systems Informix supplies an ODBC driver to access the Production Database. The
standard installation of the ODBC is sufficient for webAPX.
Sample ODBC members are supplied in the ‘tools/informix‘ directory of the webAPX
distribution. . The
ODBC-Extension of PHP generally installs the unixODBC
too.
The package unixODBC is a prerequisite on the Linux / Unix server to define an ODBC connection to an Informix
database. This package must be installed before to process with the next steps.
Installation
and customization steps for the ODBC with Informix:
1.
Install
the ODBC driver supplied by Informix.
2.
Create
or customize the following members based on your environment:
vi
<Informix-Directory>/etc/odbcinst.ini
vi
<Informix-Directory>/etc/odbc.ini
Move the following
members to be accessible by Apache2/PHP:
mv <Informix-Directory>/etc/odbc.ini
/etc/odbc.ini
mv
<Informix-Directory>/etc/odbcinst.ini /etc/odbcinst.ini
3.
Copy
the member ‘sqlhosts‘ from the Informix server running the
Production Database to and save it as:
<Informix-Directory>/etc/sqlhosts
4.
Define
the site specific Informix environment variables for Apache2/PHP:
vi /etc/apache2/envvars
The following variables
based on your environment must be specified:
export
LD_LIBRARY_PATH=<Informix-Dir.>/lib/esql:$LD_LIBRARY_PATH
export ODBCINI=/etc/odbc.ini
export
INFORMIXDIR=<Informix-Directory>
IIS Internet Information Services:
webAPX can be run on an IIS server. The
installation of the IIS server must be done by one of your system specialists. Please note that we offer no support
for the installation and customization of IIS.
The
following operations must be executed under the ‘Internet Information Services
Manager’ in order to setup webAPX for IIS:
-
Define
a new website.
-
Force
the extensions ‘.html’ and ‘.php’ to be processed by PHP. This is set via an
option in the configuration of the Home Directory of the new website.
-
Define
a Virtual Directory to access the Production Spool managed by APX. The Virtual
Directory is a link to the real Spool Directory on the same server or on
another one.
Installation of Apache2 and PHP with the webToolsAPX
setup program on a Windows server:
The Windows setup program for webAPX
offers the opportunity to installation the 32 bits version of Apache2 and PHP.
The Apache2 server will be installed in the same directory as webAPX and parameterized with default values.
Your security administrator is responsible to control if the delivered
configuration agrees with the security standards of his/her company.
Note: The Apache2
server installed with the setup program listen on port 5180. Your links
must be parameterized accordingly:
‘http://<servername>:5180/webAPX’.
Note: The
secured connections (SSL/TLS) installed with the setup program listen on port 5181.
Your links must be parameterized accordingly:
‘https://<servername>:5181/webAPX’.
Manual installation of Apache2:
The software and the related documentation can be retrieved in the
desired language for the required operating system from the Apache2 website:
At least the version 2 of Apache must be installed.
The standard installation of the software is
sufficient for webAPX.
Note: The
account defined in the properties to start the Apache service must have read
access to the production spool share. Generally the default account ‘SYSTEM’
will not have enough rights to do so. Please start Apache with its own account.
Note: The
Apache2 server can be set with SSL (Secure Socket Layer) support in order to
encrypt the data transfer between webAPX and
the user’s browser. If SSL is used, no special customization is needed for webAPX.
On Linux and Unix servers we recommend to
install the Apache version delivered with your distribution.
Customization for webAPX:
1.
Copy
the installation directory of webAPX in the
Apache2 ‘html’ directory
i.e.
‘/var/www/html/webAPX’
2.
If
needed define the installation directory of webAPX in the Apache2
configuration file:
‘/etc/apache2/apache2.conf’
or define a virtual web server.
3.
Force
processing of PHP statements into html-files:
vi
etc/apache2/mods-available/php7.0.conf:
<FilesMatch
".+\.html">
SetHandler
application/x-httpd-php
</FilesMatch>
4.
Restart
the Apache service.
Manual installation of PHP:
PHP on an IIS server:
If you are using an IIS server the PHP software
must be installed manually. On the Internet many documents are available to
describe the installation process, for example, at the following link:
http://www.peterguy.com/php/install_IIS6.html
PHP installation:
The software and the related documentation can
be retrieved in the desired language for the required operating system from the
PHP website:
On Linux and Unix servers we recommend to
install the Apache version delivered with your distribution. We recommend
installing the at least version 7.0 of PHP.
The standard installation of the software is sufficient for webAPX.
webAPX requires the option ‘safe_mode=off’ to setup and run. Therefore you must customize the PHP configuration
file: ‘PHP.INI’.
Without these changes you will receive an error message in place of the
expected post installation page.
webAPX requires the XSL-Extension to setup
and run. Therefore you must customize the PHP configuration file: ‘PHP.INI’: add a line for Windows with: ‘extension=php_xsl.dll’, for Linux install the package ‘php7.0-xls’.
The default behaviour of webAPX to
encrypt the cookies and passwords requires the customization of the PHP
configuration file: ‘PHP.INI’: uncomment or add the line for Windows ‘extension=php_openssl.dll’, for Linux install the package ‘php-openssl’.
If you attempt to produce graphs with webAPX,
you must customize the PHP configuration file: ‘PHP.INI’: uncomment or add the line for
Windows ‘extension=php_gd2.dll’, for Linux install the package ‘php7.0-gd’.
The graphs are presented with the Arial font; under Linux it must be installed
on the webAPX server in the directory ‘/usr/share/fonts/truetype’. The font can be downloaded from the
Internet.
Known issues:
Currently there is no known issue with the supported versions of Apache
and PHP.
Download webAPX:
The software and the related documentation can
be retrieved in the desired language from the following website:
http://www.unisoftware.ch/webapx
Windows: Download the setup program ‘webToolsAPX_setup.exe’ into the directory of your choice.
Linux or Unix: Download the distribution
file ‘webAPX_xxx.zip’ into the directory of your choice.
Authorization:
You must be logged with administrator or ‘root’
rights to fully process the installation or the upgrade of webAPX
on the web-server.
Software installation directory:
The entire software needed by webAPX is installed in its ‘Installation Directory’
only. No changes apply in any of the system directories.
Steps involved to the initial installation of webAPX:
Process to the next paragraph if you are upgrading
webAPX from a previous version!
The steps
involved in the initial installation of webAPX
on the server are:
1.
Make
sure a system ODBC Data Source exists on the web server to connect to the APX
Production Database.
2.
Linux or Unix: Unzip the distribution file into the
installation directory.
Please note that you must keep intact the directories structure contained in
the zip file.
3.
Windows:
Execute the downloaded program (webToolsAPX_setup.exe) and follow the instructions.
Linux or Unix: From a shell prompt execute the commands:
...cd <Installation directory>
...sh setup.sh
All instructions for the installation and customization are displayed at the
terminal.
Additional information can be found in the Administrator's
Guide which describes each configuration file.
The setup script updates the installation directory and restarts Apache.
4.
Windows:
At the end of the installation you will be automatically connected to webAPX with your browser and the post installation
process will be started. If the automatic connection fails, then point your
browser to i.e.
...‘http://localhost:5180/webAPX’
and the post installation process will be automatically started.
Linux or Unix: Connect to webAPX
with your browser i.e.
... ‘http://localhost/webAPX’
and the post installation process will be automatically started.
All instructions for the post installation and customization are displayed in
the presented browser page.
1.
Windows, Linux or Unix: In order to set the webAPX
authorizations for the current database version it is mandatory to connect at
least once with the user PCCDBA.
...‘http://localhost:5180/webAPX’
Steps involved to upgrade webAPX:
Introduction:
1.
Before
upgrading to a new version, be sure that the current installation directory of webAPX is saved.
2.
Linux or Unix: You must execute the upgrade procedure of the
new version in the SAME directory as the original installation
otherwise the setup procedure will ignore your already customized configuration
files.
Upgrade:
The steps
involved to upgrade webAPX on the server under
Windows are:
1.
Execute
the downloaded program (webToolsAPX_setup.exe) and follow the instructions.
2.
At
the end of the installation you will be automatically connected to webAPX with your browser and the post installation
process will be started. All instructions for the post installation and
customization are displayed in the browser page.
The
steps involved to upgrade webAPX on the server
under UNIX are:
1.
Unzip
the distribution file into the current installation directory of webAPX.
2.
From
a shell prompt execute the commands:
...cd <Installation directory>
...sh setup.sh
3.
Connect
to webAPX with your browser i.e. ‘http://localhost/webAPX’ and the post installation process
will be automatically started. All instructions for the post installation and
customization are displayed in the presented browser page.
Error during the installation of the Apache service under Windows
The installation of the Apache service can fail
if the ‘.NET Framework 2’ is not installed on the server.
The command used during the setup to install the service is:
...<install
dir>\_Apache2\bin\httpd.exe -n apache_webToolsAPX
-k install
If you give this command in a DOS-box you can
analyse the error message.
Please correct the error, uninstall webAPX, reboot the server and then reinstall webAPX.
Silent installation of webAPX on a Windows
server
webAPX can be silently installed in the
Windows environment with the following instruction:
webToolsAPX_setup.exe
/S ^
/DEBUGMODE=<true ¦ false> ^ //
Debug function?
/APACHE=<YES ¦ NO> ^ //
Install APACHE2, PHP and Subversion too?
/ODBCNAME=<SQL Instance Name> ^ // Default for the
System Configuration file
/USERNAME=${PCC_USER_NAME} ^ //
Default for the System Configuration file
/APXINSTANCE=<APX Instance Name> ^ // Default for the
Subversion environment
"/STARTGROUP=<StartMenuGroup
Name>" ^ //
Start menu where to put the webAPX link
"/APXJOBLOG=<Spool
Directory>"^ // Access to the production spools
/D=<webAPX
installation Directory>
Notes: Only the
‘/D=’ parameter
is mandatory.
The parameter names and values are case sensitive.
The quotes around parameters names and values are mandatory only if the value
given contains spaces.
The ‘/D=’ parameter
must be the last one on the command line.
The ‘/D=’ parameter
cannot have quotes around, even though if the directory name contains spaces.
Some production spools are too large to be displayed in a browser page.
In that case you can specify the maximum size of a spool displayed by webAPX in the browser page. The larger spools will
be downloaded as a file and the user can open or save it.
1.
The
parameter ‘bigSpoolSize’ must be set in the System Configuration file
of webAPX in order to define the maximum spool
size in bytes which will be displayed in a browser page.
2.
The
parameter ‘spoolNameRename’ must be set in the System Configuration file
of webAPX in order to define the server and
path to use when webAPX will access a large
spool file.
Sample values for this parameter:
http://user:password@localhost/joblogsAPX
file://
file://spools
ftp://aixprod/apxspools
ftp://user:password@aixprod/apxspools.
3.
If
the parameter ‘spoolNameRename’ refers to an HTTP-link, the
Apache2 configuration file must contain an Alias to access the spools i.e.:
Alias /joblogsAPX
"C:\Program Files\APX-PCC15\Joblog"
<Directory "C:\Program
Files\APX-PCC15\Joblog">
AllowOverride
None
Options None
Order allow,deny
Allow from all
</Directory>
Accessing APX-Spools via another web-server:
If the spools are stores under another web-server they will be
downloaded as a file and the user can open or save it.
1.
The
parameter ‘bigSpoolSize’ must be set to 1 in the System
Configuration file of webAPX.
2.
The
parameter ‘spoolNameRename’ must be set in the System Configuration file
of webAPX in order to define the server and
path to use when webAPX will access a large
spool file
Sample values for this parameter:
http://user:password@localhost/joblogsAPX
ftp://aixprod/apxspools
ftp://user:password@aixprod/apxspools.
APX-Spools kept in a directory of another Windows-server:
If the webAPX-server runs on a Windows
machine and the production spools are kept in a directory of another Windows
machine the following customization must be done:
1.
The
Apache2 service must start with a user account authorized to have read access
to the share of the Windows-Server storing the spool.
APX-Spools kept under Linux / Unix:
If the production spools are kept in a directory under Linux or UNIX the
following customization must be done:
1.
The
parameter ‘spoolDirectory’ must be set in the System Configuration file
of webAPX in order to define the server and/or
the directory to connect to when accessing a spool file is required. Usually
the server is the webAPX server.
Sample values for this
parameter:
http://user:password@localhost/joblogsAPX
smb://WindowsShare/joblogsAPX
file://apxSpool
/usr/apx/Joblog.
2.
A
symbolic link has to be added in the Apache2 root directory to allow access of
the web server to the spools. i.e:
ln –s
/apxcontrol/Joblog /var/www/spools.
3.
Carefully
check the Unix authorizations grant to the web server
user (usually www-data) accessing the production spools.
APX-Spools accessed by an IIS server:
If you are running an IIS server the following customization must be
done:
1.
A
Virtual Directory must be defined in the Internet Information Services Manager
to access the production spools stored on the local machine or on another
server.
For example: apxSpool.
2.
The
parameter ‘spoolNameRename’ must be set in the System Configuration file
of webAPX in order to define the Virtual
Directory to connect to when webAPX will
download a spool, i.e:
<spoolNameRename>http://localhost/apxSpool</spoolNameRename>.
webAPX on the user workstation only
requires a browser and a HTTP or HTTPS connection to the server webAPX is running on. Please make sure that no
firewall will block the connection between both machines.
If you are using the Apache2 server supplied with the ‘webToolsAPX’ setup program the port to connect to on the
server is 5180:
‘http://<servername>:5180/webAPX’.
A sample link is created
in the installation directory and on the Desktop. You can copy it to the user
workstations.
The connection from the user workstation to the server webAPX is running on can be encrypted if SSL/TLS is installed
on the server and the HTTPS protocol is used. If you are using the Apache2
server installed with the ‘webToolsAPX’ setup program
the SSL-port to connect to on the server is 5181:
‘https://<servername>:5181/webAPX’.
The user workstation can run any operating system as Windows, Linux,
Unix, Mac,…
The installation was made with the webToolsAPX
setup program:
The function ‘Add/remove software’ of the
‘Configuration Panel’ must be used to uninstall webAPX
from the machine.
If the Apache2 server was also installed with this setup, the
corresponding service will be automatically removed too.
The installation was made manually:
To remove webAPX you just have to
remove the directory containing the software.
SSL (Secure Sockets Layers) / TLS customization:
The webToolsAPX setup program pre-installs the configuration
needed by Apache2 to manage SSL/TLS connections.
The steps
involved in the final customization of the SSL/TLS connections are:
1.
Connect
the installation directory of webAPX.
2.
From
a DOS-Box or the Windows Explorer execute the commands:
cd
<webAPX Installation Directory>
.\bin\createSSLcert.cmd
Reply to the displayed questions.
3.
Restart
the Apache2 service and you can connect to the server via SSL/TLS:
‘https://<servername>:5181/webAPX’.
PHP.INI configuration file:
For security reasons we recommend to customize
the following parameters in your PHP configuration file ‘PHP.INI’:
register_globals = off
display_errors =
off
allow_url_fopen =
off
Note: The
best practice would be to set this parameter to ‘on’
but unfortunately in that case webAPX cannot
check for new versions of the product. You decide the way you want to set it.
open_basedir = ‘C:/<apache path>/htdocs/<webAPX dir>’
Note: The
best practice would be to set this parameter to root directory of webAPX but unfortunately in that case webAPX cannot display the spools at least when they
are stored on the same machine as the web server via SMB. You decide the way
you want to set it.
The
Forecast generation will run the program YMTV to generate one month of
planning. The current version of the program and procedures must be stored in
the directory:
‘\<webAPX Installation Directory>\bin‘.
Customization can be required depending on our server environment.
For Windows:
The Forecast generation function starts the script ‘.\bin\YMTVforecast.cmd’. No special customization is currently
required.
For UNIX:
The Forecast generation function starts the
script ‘.\bin\YMTVforecast.sh’.
Please customize the
script ‘.\bin\YMTVenvironment.sh’ in
order to position the settings based on your environment. This script contains
the documentation required to customize this function. This script will never
be changed automatically by the future updates of webAPX.
Last update: 01
March 2020