Alchemy Administrator's Guide
Copyright © 2006 Infusient LLC. All rights reserved
Published by Infusient LLC., 578 Washington Blvd #233,Marina del Rey, CA 90292
Publishing HistoryFebruary 2006: First Edition
Alchemy, Alchemy Framework, Alchemy logo, and the Infusient logo are trademarks of Infusient LLC.
While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.
02/06 v0.7
© Infusient LLC
Table of ContentsPreface................................................................................................................................iii
Who Should Read This Book.......................................................................................iii
Assumptions This Book Makes....................................................................................iii
How This Book is Organized........................................................................................iv
Conventions Used in This Book....................................................................................iv
Services and Support......................................................................................................v
Installation............................................................................................................................1
System Requirements ....................................................................................................1
Pre Installation Steps......................................................................................................3
Installing Alchemy.........................................................................................................4
Post Installation..............................................................................................................5
Troubleshooting..............................................................................................................6
Anatomy of an Alchemy Installation..............................................................................7
Upgrading an Existing Alchemy Installation.................................................................9
Alchemy Servers................................................................................................................11
What is an Alchemy Server..........................................................................................11
Creating a new Alchemy Server ..................................................................................12
Starting and Stopping Alchemy Servers.......................................................................15
Server Monitoring and Status.......................................................................................15
Administration Portal...................................................................................................16
Configuring Alchemy.........................................................................................................19
Alchemy Modules.........................................................................................................19
Alchemy Application Suite..........................................................................................21
Creating a new Module................................................................................................22
User Administration...........................................................................................................27
User Authentication......................................................................................................27
User Authorization.......................................................................................................30
Directory Based Access Control..................................................................................30
Role Based Access Control..........................................................................................32
Alchemy Schema...............................................................................................................35
AWS_ACL....................................................................................................................36
AWS_ACL_CATEGORY.............................................................................................36
AWS_ATTACHMENT.................................................................................................37
AWS_DIRECTORY.....................................................................................................37
i
© Infusient LLC
AWS_FILTER..............................................................................................................38
AWS_HISTORY...........................................................................................................38
AWS_LOV_REF..........................................................................................................39
AWS_MENU................................................................................................................39
AWS_MENU_OPT......................................................................................................40
AWS_ROLE..................................................................................................................41
AWS_USER_ROLE.....................................................................................................41
DS_TEAM....................................................................................................................41
DS_TEAM_MEMBERS..............................................................................................42
Command Reference..........................................................................................................43
Resources...........................................................................................................................51
Internet Resources........................................................................................................51
Books............................................................................................................................52
ii Alchemy Administrator's Guide
© Infusient LLC
Preface
This book is the Administrator’s Guide to Alchemy, an application framework fordeveloping web applications. Alchemy framework includes a transactional applicationserver with robust support for a variety of databases.
Who Should Read This BookThis guide is about installing and administering Alchemy. It is essential for systemadministrators who are responsible for installing, configuring and maintaining Alchemyframework. It is also relevant to developers who desire to complement their knowledge ofAlchemy development platform with some under-the-hood architectural details. Finally,system engineers and project managers working on an Alchemy development ordeployment project shall gain insights into Alchemy platform’s extensive configurationand customization possibilities thru this guide.
Assumptions This Book MakesThis book assumes a working familiarity with the UNIX system and its command linetools. Some of the instructions and examples require using a text editor such as vi tochange configuration files. Alchemy requires an RDBMS and familiarity with yourchosen database and its tools and capabilities is useful.
We realize, if you are reading this guide, you already are an experienced computingprofessional with expertise in installing and administering systems comparable toAlchemy in functionality and scope, and probably want to get your hands around this newplatform as quickly as possible.
Our objective is to get you there with the minimum of fuss, so the writing style isdeliberately technical, aiming to cover all relevant details while omitting much of theknowledge common to Unix community. The resulting text is relatively high ininformation density and repetition is kept to a minimum. Screen shots are used sparingly,if ever. They tend to convey little information beyond the style and feel of the interfaceand are never a good substitute for clear textual description.
Preface iii
© Infusient LLC
You may find it useful to read this guide from cover to cover, as the sections do build oneach other a bit from beginning to end. Afterwards, keep it around as a reference, whenyou need help to perform a specific administration task.
How This Book is OrganizedAlchemy Administrator’s Guide is divided into four chapters and three appendixes:
Chapter 1, Installation
Describes the system requirements for an Alchemy installation, discusses pre-installation actions, covers a typical Alchemy installation and details post-installationsteps.
Chapter 2, Alchemy Servers
Introduces the concept of Alchemy servers, describes the setup, configuration andmaintenance of Alchemy servers.
Chapter 3, Configuring Alchemy
Presents Alchemy modules, describes setup and functionality of domains, menus andother entities under administrator’s control. In addition, Chapter 3 includes a reviewof Alchemy registry and its role in configuring and customizing Alchemy.
Chapter 4, User Administration
Discusses Alchemy security model, introduces the concept of roles and privilegesand how they provide resource level access control. The separation of security policyfrom the application code is emphasized and finally, administration activities such asadding and deleting users are explained.
Appendix I, Alchemy Schema
Documents the standard database tables that are installed by default in an Alchemyinstance.
Appendix II, Command Reference
Provides a list of Alchemy commands and their usage options in a format similar toUnix manual pages.
Appendix III, Resources
Further reading, related information sources and links.
Conventions Used in This BookPlain text
Indicates menu titles, menu options, menu buttons, and keyboard accelerators (suchas Alt and Ctrl).
Italic
Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames,directories, and Unix utilities.
iv Alchemy Administrator's Guide
© Infusient LLC
Constant width
Indicates commands, options, switches, variables, attributes, keys, functions, types,classes, namespaces, methods, modules, properties, parameters, values, objects,events, event handlers, XML tags, HTML tags, macros, the contents of files, or theoutput from commands.
Constant width bold
Shows commands or other text that should be typed literally by the user.
Constant width italic
Shows text that should be replaced with user-supplied values.
This paragraph signifies a tip, suggestion, or general note.
This paragraph indicates a warning or caution.
Services and Suppor tA wide range of information about Infusient products and services is available on theInternet, from: http://www.infusient.com/
You can e-mail questions or feedback regarding this document to:
Preface v
© Infusient LLC.
1Installation
While installing Alchemy is a straightforward process, taking some time to learnAlchemy system requirements and installation steps can save a lot of troubleshootingtime. This chapter covers the installation of Alchemy framework and the accompanyingsuite of applications into a supported hardware and operating system platform.
After reviewing system requirements for Alchemy, we’ll discuss pre-installationpreparation, document the installation process and present post-installation activities. Thechapter wraps up with a discussion of the physical layout of an installed Alchemy releaseto familiarize the reader with the terminology used in later chapters.
System Requirements This section describes the requirements for installing Alchemy. Before starting theinstallation, verify that your system meets the requirements listed here:
Operating System Requirements
Alchemy supports the following platforms:
• Linux
• Red Hat Enterprise Linux 4
• Novell SUSE Linux Professional 9.3
• Fedora Release 4
• Sun SunOS 4+ (includes Solaris)
• HP-UX 11
• Apple Macintosh OS X
The operating systems listed above are supported in all available processor architectures.For instance, Linux support includes both Intel and AMD64 as well as PPC.
Installation 1
© Infusient LLC.
Hardware Requirements
Alchemy needs the following hardware resources:
• Processor: Any processor supported by underlying OS
• Hard Disk: 50MB for typical installation
• Memory: 512MB minimum – 1GB recommended
• Network At least one open port to listen for requests
RDBMS Requirements
Alchemy is a transactional application server and depends on a RDBMS to store andmanage its data. The following RDBMS vendors and flavors are supported:
• Oracle Release 8.1.7 or later
• Postgres Version 8.0
• Sybase ASE 12.5
• SQL Server Supported via Sybase driver
• MySQL Version 4.1 or later
Please note that the database support list above is for AlchemyFramework only. Individual applications in the Alchemy suite may havea more limited list of supported database platforms. Infusientguarantees full Alchemy suite support for only Oracle and Postgres.
Java VM
If you plan on using Java integration features of Alchemy or incorporate PDF reportingwhich depends on FOP, a java application, then you need to install and configure anapproved Java VM. JDK versions 1.1, 1.2, 1.3 and 1.4 are known to work well withAlchemy. JDK 1.5 has not yet been tested with Alchemy and is not recommended forproduction use. Alchemy Java integration functionality is not available in Macintosh OSX platform.
Client Software Requirements
Alchemy provides a Service Oriented Architecture (SOA) and does not require anysoftware installation on a per client basis. Any user with network access to Alchemyserver and a standards compliant browser can use Alchemy. The following is a list ofbrowsers tested and verified on Alchemy. Other browsers that follow the standardsestablished by W3C should also work:
Browser Name Tested Version
Mozilla Firefox 1.0.6
Opera 8.0
Netscape 8.0
2 Alchemy Administrator's Guide
© Infusient LLC.
Browser Name Tested Version
Safari 1.2
Internet Explorer 6.0
Not all browsers provide consistent support for web standardsestablished by W3C which may result in slight variations in theAlchemy user experience when moving between different webbrowsers. This is an expected side effect of the web platform and doesnot impact the functionality or feature set available in Alchemy.
For production deployments, Infusient recommends Firefox fromMozilla foundation (http://www.mozilla.org). It has excellent supportfor web standards and is very secure, free of viruses and bugs that seemto plaque Internet Explorer constantly.
Pre Installation StepsPrior to installing Alchemy, the system administrator needs to setup the target machine bygoing through the following checklist:
Create a UNIX user for Alchemy
Although it is possible to install Alchemy as any existing user, we strongly recommendcreating a separate UNIX user for Alchemy. This simplifies system maintenance andensures software integrity and security at the file system level. You may choose anycommand shell you prefer for alchemy such as bash or csh. The examples in thisguide use csh.
Setup the umask for alchemy to 022 to ensure group and other have read andexecute permissions, but not write permission, on alchemy files.
The Alchemy software will be installed under the Alchemy user’s home directory bydefault. It is, again, possible to change the installation directory but it complicatesscheduled software upgrades and is not recommended for production environments.
The examples in this manual references to the Alchemy UNIX user asalchemy and to the installation directory as /home/alchemy. These arejust convenient defaults and administrators may change the user nameor home directory.
Ver ify Installation Directory
For an initial install, make sure that the installation directory is empty and alchemy hasfull read/write/execute privileges. Running ls –ld . in alchemy home should return aline similar to the following:
drwxr-xr-x 2 alchemy users 4096 Aug 8 23:59 .
Setup Database
Alchemy needs a database connection to setup the initial server instance and populate theAlchemy tables. Although the DBA may setup new schemas for additional Alchemy
Installation 3
© Infusient LLC.
servers after the installation, at least one database schema is needed to complete theinstallation process.
The database schema can be setup on any one of the supported RDBMS platforms and itneeds to be accessible to Alchemy for login. Alchemy installer needs resource privilegesin the target schema to create its tables, views, packages and other database objects. Werecommend creating a new empty database schema for Alchemy to simplify databaseadministration and to ensure data integrity.
Copy the Software
Alchemy software is delivered in a CD which needs to be copied to alchemy homedirectory prior to installation. The contents of the CD may vary from platform to platformor release to release but it primarily has the following files:
File Name Descr iption
README Brief installation instructions with latest changesand platform notes
LICENSE Software License Agreement
alchemy<rel>-<platform>.sh Installation script. Verify the release# andplatform
dist/ Software distribution directory
Copy the files in the CD to alchemy home directory as alchemy user.All files in the distribution need to be owned by alchemy
Installing AlchemyAfter going through the pre-installation checklist and verifying alchemy user setup, youare now ready to move to the installation phase. Perform the following installation stepsin sequence:
1. Login as alchemy user
The full Alchemy installation has to be performed while logged in as alchemy from thealchemy home directory. Take a moment to verify your user id and current directory.
2. Run the installation scr ipt
Locate the installation script in your current directory. The installation script can be runeither in command-line or graphical mode. If you prefer to run the GUI version make sureDISPLAY environment variable reflects the X server for your PC.
Run the installation script as follows (Replace <rel> and <platform> with release #and platform for your installation):
In Command Line mode:
./alchemy<rel>-<platform>.sh –cli
In Graphical Mode:
./alchemy<rel>-<platform>.sh –gui
4 Alchemy Administrator's Guide
© Infusient LLC.
3. Respond to Prompts and Questions
The precise sequence of installation steps, along with user prompts and log messages varyslightly between command-line and GUI versions. But the questions and the defaults areidentical in either case. The list of prompts, their defaults and recommended user actionsare detailed in the following table:
Prompt Default Action
Accept License Agreement Decline Read and accept the agreement toproceed
Product Serial # None Enter the serial# that came with yourcopy of Alchemy
Alchemy User Name <logged user> Keep the default
Installation Directory <user home> Accept the default
Applications to Install None Select applications from the list
Alchemy Instance Name alchemy Accept the default
Port # 80 Select an available port for the initialinstance
Host Host name Accept the default unless themachine is defined under a differentname in DNS
Database Driver None Select the driver for backenddatabase from list
DSN None Provide login details for database –user id, password, host name etc.
Alchemy Admin Password None Select a password for AlchemyAdministrator
Install Schema Yes Yes, create schema objects for initialinstall
Alchemy installer, after collecting and validating required information, proceeds with theinstallation during which, you will receive various status / progress messages. Thesemessages are also captured in the install.log file.
The installation itself is relatively fast and should complete within 5-10 minutes. Aftersuccessful completion, Alchemy installer exits returning you to the alchemy homedirectory.
Post InstallationYour Alchemy installation is now complete. The installer created one default Alchemyserver listening on the port and connected to the database specified during theinstallation. You can use this server to define and activate additional Alchemy serverinstances. A good starting point is to add a separate server for each purchased application.
Installation 5
© Infusient LLC.
Alchemy framework comes with an unlimited enterprise site license.This means there is no limit to the number of server instances or users.You may create more than one instance for each application. Forinstance, each department in your organization may have their owninstance.
Now you are ready to start using Alchemy. Start up your browser and point it to thefollowing URL:
http://<host>:<port>/adm/
Where <host> and <port> are the host name and the port number selected during theinstall. You will be prompted for a user name and password. Use admin (all lowercase)for user name, for password enter the password selected during install. Now you are in theAlchemy administration screen where you can complete the configuration of Alchemy.The next chapter discusses setup, configuration and maintenance of Alchemy servers.
TroubleshootingIf you are unable to login to Alchemy, try following troubleshooting steps to identify theproblem:
1. Make sure Alchemy server is running
Check running processes for alchemy to make sure the server started successfully. Theexecutable for Alchemy application server is aws. You should see a process commandline similar to:
aws –id alchemy
If the process is not running, restart Alchemy server using the following command line:
bin/awsctl start
2. Check for er rors in server star tup
Alchemy server controller awsctl, outputs diagnostic messages to etc/awsctl.logfile. Check the log file to make sure there are no fatal errors reported. One commonproblem is failed database logins. Try logging into the database with another client tool(such as sqlplus for Oracle or psql for Postgres). If you discover a problem with thedatabase login parameters (e.g. wrong password), edit local/etc/dsn.rc file tocapture the correct login arguments (for details on how to edit DSN entries, see the DSNSetup section in Chapter 2).
3. Ver ify your password
Alchemy user id and passwords are case sensitive. Make sure you use admin as youruser id and enter the password exactly as it is entered during the installation. If you forgetyour password you can manually reset it by editing local/etc/passwd file.
4. Contact Infusient Suppor t
If you are still unable to resolve the problem after trying previous steps, e-mail Infusientsupport at [email protected]. Include a description of the problem, the details ofyour hardware and software platform, and any other details you deem relevant fortroubleshooting the problem. Infusient usually responds to installation problems within24 hours.
6 Alchemy Administrator's Guide
© Infusient LLC.
Anatomy of an Alchemy InstallationThis section provides an overview of the physical layout of a typical Alchemy installation.Familiarity with the directory structure under Alchemy home comes handy especiallywhen performing administration tasks that require manually updating configuration files.The vast majority of Alchemy administrative tasks, and essentially all regularadministration chores, can be performed via the web interface but there still are a fewinstances where the administrators are asked to tweak system files manually.
The command line also provides a backup when it is not possible or practical to start upan Alchemy application server instance (e.g. scripted or batch administration).
The following table presents the directory structure of Alchemy along with a descriptionof each directory or file:
Table 1-1. Alchemy Directory Layout
File Name or Pattern Description
bin/ Directory for Alchemy executables
bin/ash Alchemy Shell. Provides interactive and batchaccess to Alchemy Framework API. For moreinformation on Alchemy Shell refer to AlchemyDeveloper's Reference.
bin/aws This is the executable for Alchemy ApplicationServer. Alchemy server controller launches acopy of aws for each permanent Alchemyinstance defined in etc/servers file.
bin/awsctl Alchemy Server Controller. Used to start up orshutdown Alchemy server instances.
bin/awsdispatch Alchemy Load Balancer. Distributes requestsamong multiple identical server instances.
bin/rotate Rotates Alchemy server logs, generates usagereports and statistics.
etc/ Alchemy System Configuration directory.Standard Alchemy configuration and setup iscaptured here. Do not modify files in thisdirectory, instead, save your configuration in thecorresponding directories under local/
etc/*.rc Startup configuration files for Alchemy modulesand other components of Alchemy platform (e.g.chart.rc, dsn.rc, report.rc)
etc/*.conf Registry keys for Alchemy modules andcomponents including skins.
etc/servers Attributes and status (running, inactive etc.) forall Alchemy server instances. This file isautomatically maintained by awsctl and aws.Do not manually change if any Alchemy serversare running.
etc/awsctl.log Alchemy Server Controller Log. Startupdiagnostic and error messages are captured here.
Installation 7
© Infusient LLC.
File Name or Pattern Description
Check this file for any startup error messages ifAlchemy server does not start up or haspersistent errors.
local/ Installation specific configuration and setup.Alchemy installer does not modify or overwritethe contents of this directory when upgrading toa new release. All customizations to your systemshould be captured here.
local/bin/ Directory for locally developed programs andbatch scripts. All Alchemy related scripts such asinterfaces to other systems should be stored here
local/etc/ Site configuration directory. Any customizationsthat are specific to this Alchemy installation oran individual server instance should be placedhere
local/etc/<id>.rc Server instance startup file. Each Alchemyserver instance has a corresponding .rc filehere describing server specific setup such as listof modules to load.
local/etc/<module>.rc Alchemy module startup file. Any system-widecustomizations to Alchemy modules applicableto all Alchemy instances are defined here.
local/etc/<module>.conf Alchemy Module Registry. Any system-widechanges to Alchemy module registries arecaptured here.
local/etc/<id>/ Server configuration directory. Any serverspecific customizations to Alchemy modulesshould be stored in the module startup files inthis directory.
local/etc/<id>/<module>.rc Alchemy module startup file. Any customizationsto Alchemy modules applicable to a singleAlchemy instance are stored in the correspondingmodule .rc files here.
local/etc/<id>/<module>.conf Alchemy module Registry. Any changes toAlchemy module registries applicable to a singleAlchemy instance are captured in thecorresponding module registry file here.
web/ Alchemy Application Server Root. This is thedefault root directory for all Alchemy serverinstances. All URL's submitted to the Alchemyserver are mapped to files and directories belowthis directory by default.
web/images/ Images and icons used in Alchemy skins. If youchange the server root directory for one or moreAlchemy instances, make sure this directory iscopied to the new root.
web/log/ Alchemy application server keeps its usage andstatus logs in this directory. The default log
8 Alchemy Administrator's Guide
© Infusient LLC.
File Name or Pattern Description
directory can be changed to a directory outsidethe Alchemy directory structure (for instance/var/log/alchemy).
web/log/aws_<id>.yy.mm.dd Daily usage logs for each Alchemy serverinstances. The log files are in Apache CLFFormat. Log rotate program periodically scansand compresses log files. It also useswebalizer tool to generate usage statistics.
web/log/aws_<id>.error Any run-time errors encountered while servicinguser requests are captured in this error file namedafter the Alchemy server instance.
web/tmp/ Alchemy application server creates itstemporary files in this directory. The defaultlocation can be moved out of Alchemy directorystructure.
web/style/ CSS Style sheets for various browsers supportedby Alchemy.
web/upload/ Files uploaded by users are stored in thisdirectory. File attachments for Alchemyapplications are also stored here by default.
We recommend you change this directory to aproperly sized disk outside Alchemy directorystructure and assign a separate directory to eachserver instance to simplify data management andarchiving.
web/<module>/ If you obtained a source license for yourAlchemy applications, Alchemy installer placesthe page template source files (extension .tml)in matching directories for each module underweb directory.
Some larger modules split their functionality intomultiple directories. For instance Alchemy ERPcomes with four directories (erp, mrp, pdm, ess).
Upgrading an Existing Alchemy InstallationThe process to upgrade an existing Alchemy installation is essentially the same as a brandnew installation. The only difference is the “Pre-Installation Steps” are not needed sincethe environment for Alchemy (Unix user, database instance) are already there.
The installation script automatically checks for an existing Alchemy installation andupgrades the base distribution and all server instances to the latest release. It also appliesany schema and meta data changes for all DSN's tied to Alchemy servers. Any installedAlchemy applications are automatically detected and presented to the user in theApplications to Install selection. Any licensed but not installed applications are alsoavailable in this selection, so you can use the same installation process to add a newapplication to an existing Alchemy installation.
Installation 9
© Infusient LLC.
Please keep in mind that any new application(s) will be installed into the default DSNspecified by the user. You can use this feature to create multiple instances of the sameapplication. Alternatively you can use the initdb program provided in the Alchemydistribution (See Appendix II – Command Reference for details).
The installation script is written with extreme care to ensure that anyexisting user customizations or meta data is preserved during theupgrade process. Nevertheless, problems such as an aborted installationor failures beyond the control of the installation process may cause datacorruption or loss. Infusient strongly recommends backing up the fullAlchemy directory structure and all relevant database schemas prior toany upgrades.
10 Alchemy Administrator's Guide
© Infusient LLC.
2Alchemy Servers
The previous chapter described the installation of Alchemy into a new machine andfinished with a new Alchemy instance up and running at its assigned port.
A quick look at this server shows that there is not much going on. The administrationscreen has some options on servers, modules and a couple of links related to useradministration, but overall the new server does not seem to be doing much. Mostimportantly no Alchemy applications seem to be running and isn’t this the main reasonfor installing Alchemy in the first place ?
The administrator needs to configure each Alchemy server for its targeted use.Specifically, the applications (modules in Alchemy parlance) required by the server, thedatabase environment, the security model are all defined as part of server’s deployment.
This chapter describes the concepts behind Alchemy servers, and covers creation,starting, stopping and configuration of Alchemy servers from an administrator’sperspective.
What is an Alchemy ServerEven though it is quite convenient to consider an Alchemy installation as the AlchemyServer , it is misleading since each Alchemy installation can host numerous Alchemyservers, as many as your hardware can bear actually. Each Alchemy server, when properlysetup, has its own configuration, its own database schema for application data, its ownURL, users and security model. With a little bit planning, you can have all your Alchemyapplication instances peacefully coexist side-by-side on the same hardware and code-base. This approach has a number of advantages over its alternatives:
• Shared code-base prevents source code fragmentation and version control problems
• Central administration reduces support complexity and overhead
• One code-base encourages process discipline and backward compatibility
• A common application platform promotes skill set development and reduces trainingcosts for users and developers
Alchemy Servers 11
© Infusient LLC.
Creating a new Alchemy Server Once the initial Alchemy server configured during installation is up and running, theadministrator can define and activate new Alchemy server(s) just by using theadministration functionality available in Alchemy.
The option to create a new Alchemy server is:
Admin Portal→Sidebar→New Server→Start New Alchemy Server
The Start New Alchemy Server screen prompts the administrator for the attributes of thenew server instance. The list of attributes, their defaults and descriptions are detailed inthe following table:
Server Attr ibute Descr iption
Id This is the unique identifier for the server. Select alower case descriptive name for the server. Serverid has to start with a letter and can only includealphanumeric characters
Host Name This is part of Alchemy server URL, make sure itis defined in DNS
Port Number Choose an available port for the server to listen forrequests
Server Root Usually default works unless the server rootdirectory is moved after installation.
Database Connect String DSN for the database schema
Password File Name User password file for the server
Group File Name User Groups file for directory level access control
Log File Directory This directory is for Alchemy web logs and usagestatistics
Temp File Directory Alchemy creates temporary files it needs in thisdirectory
Web Master’s E-Mail Address More accurately, this is the e-mail address for theadministrator. User feedback and problem reportsare sent to this address
Number of Listeners (Server Pool) If this number is greater than 1 then Alchemy pre-starts the specified number of servers for round-robin load balancing. This option may improveperformance in heavily used reporting and dataanalysis servers
Separate Server Configuration Always set this option. It allows administrator toindependently configure and customize the server
Launch Server at Startup Check this option too. It tells awsctl to start thisserver as part of its normal startup process
There are a few points to watch out when defining an Alchemy server:
• Make sure all directory and file names are expressed as absolute paths. Path namesrelative to Alchemy home directory do not work.
12 Alchemy Administrator's Guide
© Infusient LLC.
• If you choose to maintain separate password and group files for each server thencopy the password and group files from your initial Alchemy server to the newlocation otherwise you will not be able to login to the new server.
• If you are using a separate database schema for the new server, as recommended,then arrange for the DBA to create and populate the new schema before you createthe new server. If the new server is unable to connect to the database at startup thenyou can not use the server to finish the configuration.
• Database Connect String parameter is actually a Data Source Name (DSN). DSN is aconceptual name for an actual database connection. This approach eliminates theneed to specify database user name and passwords in command line arguments andgives administrators the flexibility to change back-end database setup withoutimpacting the application server.
DSN Setup
Part of a new Alchemy server setup is getting the database schema initialized andpopulated by the DBA. Usually DBA uses the tools provided by the RDBMS vendor toclone the original Alchemy schema. Another option is to use the initdb script providedin the local/bin directory which sets up an skeletal Alchemy schema populated onlywith Alchemy meta data for the selected applications.
Once the new schema is ready, the Alchemy administrator needs to define a DSN whichassociates a mnemonic name with the actual connection parameters for the databaseschema. Thereafter, the DSN name is used any place where a database login string isrequired reducing the visibility of database user id and passwords.
DSN entries are defined manually in the file local/etc/dsn.rc. The followinglisting shows a typical setup in dsn.rc:
Example 2-1. Sample local/etc/dsn.rc file
dbi::dsn add alchemy -title "Alchemy Default Schema" -driver oracle -desc { Default Alchemy Login} -user alchemy -password alchemy -sid dev -host server01
dbi::dsn add stacs -title "Local STACS DB" -driver postgres \ -dbname stacs -user alchemy
dbi::dsn add local -title "Local SQLite Database" -driver sqlite \ -file /var/alchemy/atm.db
As seen in the sample above, DSN entries are defined in the following format:
dbi::dsn add id [option value]…
Here id is the unique name for the DSN followed by a number of option / value pairs.Some of the options are common to all DSN types, the rest are unique for each type ofdatabase driver. The common DSN attributes are:
DSN Attr ibute Descr iption
-driver This required attribute defines the database driverused to connect to the target database. The validdrivers are:
• oracle
• postgres
Alchemy Servers 13
© Infusient LLC.
DSN Attr ibute Descr iption
• sybase
• mysql
• sqlite
-title Short Description of DSN.
-desc Detailed information about DSN, such as purpose,DBA etc.
-on-connect Script to execute on successful connection
The DSN attributes specific to the database drivers are:
Oracle:
-user Schema Name
-password Database password
-db Database SID or global/TNSNAMES Id.
or use the following instead of –db:
-host host name for database server
-port Oracle listener port, default: 1521
-protocol SQL*NET Communication protocol, default: TCP
Postgres:
-user Database user name
-password Database password
-dbname Postgres database name.
-host host name for database server
-port Postgres listener port
Sybase:
-user Database user name
-password Database password
-server Sybase database server.
MySQL:
-user Database user name
-password Database password
-db Schema name.
-host host name for database server
-port MySQL listener port
MySQL also supports a long list of connection parameters that Alchemy passes onverbatim. Check MySQL documentation for details.
SQLite:
-file Database file name
Once the DSN is captured in in local/etc/dsn.rc, test the connection usingAlchemy Shell. The command line is:
bin/ash –dblogin DSN
14 Alchemy Administrator's Guide
© Infusient LLC.
If ash prompt comes up without any error messages then you are ready to define and startup the Alchemy server as described in the previous section.
Star ting and Stopping Alchemy ServersAlchemy server instances can be started or stopped using awsctl, Alchemy servercontroller:
awsctl [start | stop | sync ] [serverId]
The subcommands to awsctl are:
start
Starts up the specified server. If the server id is not provided then awsctl starts alldefined Alchemy servers. If a server is already running then it is recycled (i.e. it isshut down and restarted).
stop
Shuts down the specified server. If the server id is not provided then awsctl stopsall defined Alchemy servers.
sync
Starts up the specified server if it is not already running. If the server id is notprovided then awsctl checks the status of all defined Alchemy servers and starts upany inactive server(s).
awsctl can be used in system initialization or cron scripts to perform scheduled start upand shut downs. Make sure the awsctl command is run as alchemy UNIX user to ensuresystem integrity. One common mistake is to run awsctl directly from systeminitialization script which launches Alchemy servers under root privileges. The followingversion should do the trick:
su – alchemy –c “/home/alchemy/bin/awsctl start”
There is also a shell script named Alchemy in /home/alchemy/etc directory that isa wrapper around awsctl which can be used in init.d scripts.
Another alternative way to start/stop Alchemy servers is the Alchemy administrationportal. The administrator can control other Alchemy server instances if there is onealready running. The option for server start up / shut down is:
Admin Portal→Sidebar→Server Controller
The screen elements match the parameters to awsctl.
Server Monitor ing and StatusUsing Alchemy admin portal you can monitor the status of Alchemy servers. The figurebelow shows a screen shot of Alchemy Servers page accessed via:
Admin Portal→Sidebar→Active Servers
Alchemy Servers 15
© Infusient LLC.
Figure 2-1. Active Servers Screen
The servers are color-coded to indicate their current status. The colors are:
• Gray: Permanent Alchemy server, Running
• Yellow: Alchemy Load Balancer
• Blue: Pre-launched server for load balancer
• Green: Permanent Alchemy Server, Inactive
The links on server names allow administrator to configure server parameters. There arealso links for:
• Status: Shows status details such as number of hits, user statistics, error log etc. Thestatus information is in real-time and reflects the activity since last restart of theserver.
• Statistics: This link presents usage statistics in monthly and daily charts. Theinformation in the charts are generated automatically from usage logs usingrotate.
• Admin: Switches to the Admin Portal for the specified server. This option allowsadministrators to manage more than one server from a central page.
• Activate: Inactive servers can be started using this option. This is similar to theServer Controller described in the previous section.
Administration Por talAdministration portal is where you, the system administrator, go to perform mostcommon, and some not so common, Alchemy administration tasks. We have earlierreferred to it without explaining exactly what it is and how it is used.
Here are some facts about Alchemy Administration Portal:
• Each Alchemy server instance has its own administration portal which is accessedvia URL: http://<host>:<port>/adm.
• Only users with admin group privilege can access the portal. Initially only useradmin has this privilege but additional users can be added to the admin group.
• The administration portal functionality is provided by application Alchemy which isloaded automatically into each server instance at startup. This application also loadsthe meta data and configuration used by all other applications.
• Although the administration portal is quite handy; it needs a properly configured andrunning Alchemy server to work. When a crash or some other issue prevents bringing
16 Alchemy Administrator's Guide
© Infusient LLC.
up an Alchemy server instance, then use Alchemy command line tools to administeror repair the system. A reference for Alchemy command line tools are provided inAppendix II.
The functionality and options provided by Administration Portal are documented in thecorresponding sections in this manual. For your reference, a brief summary of options inthe portal sidebar is listed in the following table:
Option Descr iption
Servers This pull down lists all active Alchemy serverinstances running on the current Alchemyinstallation. Pick one to change its attributes.
Active Servers Lists all permanent Alchemy server instances andtheir status (Running, inactive etc.). Use thisoption as a launchpad to administer multipleserver instances.
New Server Creates a new Alchemy server instance with theattributes provided.
Server Controller Starts or stops Alchemy server instances.
Reconnect Database Renews the database connection. Useful forreestablishing the database connection if it isdropped. This option is not usually needed sinceAlchemy server constantly monitors the databaseconnection and reconnects automatically if it goesdown.
User Profile This pull down lists all defined users for thecurrent server instance. Pick a user to view thecorresponding user profile.
Directory Search Searches user directory by various criteria.
Add New User Creates a new Alchemy user. If Alchemy is linkedto the enterprise employee directory, then you onlyneed to enter the user name and Alchemy pulls inother user attributes (e.g. name, phone, org code)from the employee directory.
Delete User Deletes the selected user and all privilegesassigned.
Groups Provides a list of users belonging to a given group.Initially only two groups are defined: admin –Administrators and alchemy – All users.
Teams Creates and maintains user teams. The teamconcept is used by some Alchemy applications todesignate groups of users that collaborate on aproject (usually outside the enterprise orgstructure).
White Pages Searches employee directory (only available whenlinked to the enterprise employee directory).
Modules This pull down lists all loaded Alchemyapplications (i.e. modules). Select a module toview module specific setup and configuration.
Alchemy Servers 17
© Infusient LLC.
Option Descr iption
Domain Search Searches module domains. Domains are lists ofvalid values that are attached to user input fields toprovide lookup and validation.
Domain Maintenance Creates and maintains module domains.
Menus View and maintain application menus used in eachavailable module.
Registry Alchemy Registry is organized under contexts.This pull down lists all defined contexts, select oneto view and maintain the registry keys definedwithin that context.
Reload Alchemy Registry is saved in multipleconfiguration files (*.conf). This option reloads allthe registry files in the configuration path, erasingany unsaved changes.
Save to File Saves registry changes to the selected registry filein the configuration path.
New Creates a new registry context.
18 Alchemy Administrator's Guide
© Infusient LLC.
3Configuring Alchemy
In this chapter, we continue our review of the configuration and customization optionsoffered by the Alchemy Application Server which provides a web deployment platformfor Alchemy Framework and can host a number of web applications in each of itsinstances.
We shall see how Alchemy eases the task of building and deployment of web applicationsby combining all application and business logic with the required configuration andresources into a bundle called Module that can be independently defined, configured,loaded or unloaded from an Alchemy server.
We will look at how you can create a new module and load it into an Alchemy server. Youwill also learn about configuring various module components so that you can customizethe module without touching the application code.
Finally, we look at Alchemy Registry and how Alchemy applications use it todynamically configure their behavior and user interface.
Alchemy ModulesAs a web front end for Alchemy Framework, Alchemy Application Server can host anyweb application developed using Alchemy Framework. Each web application is a logicalcollection of Alchemy template pages (.tml), configuration files, registry entries, menusand static web resources such as HTML pages, images, multimedia documents, etc.
A web application and all its related resources are represented by an object called Modulein Alchemy which provides a useful abstraction for managing applications.
What is a Module ?
A module is an Alchemy component that encapsulates the code and all related resourcesfor a web application and provides an API for management and customization of theapplication. Alchemy administrators use this API – either directly in setup or ash scriptsor indirectly via Admin Portal – to define, customize, load and unload Alchemyapplications.
Configuring Alchemy 19
© Infusient LLC.
In this book, we sometimes use the terms module and web application interchangeablyand most of the time the intent can be deduced from context. However, for the sake ofaccuracy, it pays to repeat that an Alchemy application refers to the application logic andcode that makes up the application functionality whereas a module is all the additionalsetup and resources the application needs and the conventions it follows so that Alchemyserver can load, unload and otherwise manage the application.
The main components of a module are:
An application directory
This directory contains all the Alchemy template pages that make up the user visiblefunctionality of the application. This directory also contains other static resourcessuch as HTML pages used by the application. Application directory is usually a toplevel directory under Alchemy Server Document Root and named after the module(For instance, the application directory for a module named Erp would be/home/alchemy/web/erp/.).
A Module URL
This is the module home page, it is what users see first when they login to thesystem. It usually provides a portal view with user interface elements and moduleoptions laid out in a web page. The module URL usually points to the applicationdirectory. For example the module URL for the Erp module would behttp://<host>:port/erp/.
A startup configuration file
Each module has a startup configuration file where the module is defined and itsattributes and default configuration is specified. Alchemy server searches for andexecutes the startup file when it is asked to load a module. This file is stored inAlchemy System Configuration Directory (/home/alchemy/etc/) and named after themodule, e.g. the startup file for Erp module is erp.rc.
A module registry
Alchemy applications use Alchemy Registry to capture aspects of the application thatcan be customized by the system administrator. Alchemy registry stores key/valuepairs similar to MS/Windows registry. However, unlike MS/Windows which is onemonolithic binary file subject to corruption and performance problems, Alchemyregistry is saved in multiple files (one for each module) which are in human readabletext format. This approach simplifies registry backup, recovery and version control.The Registry files have an extension of “ .conf” .The module registry file is stored inAlchemy System Configuration Directory (/home/alchemy/etc/) and named after themodule, e.g. the registry file for Erp module is erp.conf.
Domain definitions
Domains are lists of key/value pairs that are used in data entry and validation e.g. adomain may populate a pull-down data entry field or validate the user-entered dataduring form updates. As an Alchemy system administrator, you will use the AdminPortal to setup and maintain domains as your instance of Alchemy module evolves.We will look into domain use and maintenance in the next section.
Parameter and column definitions
Parameters and columns capture the attributes that correspond data entry and displayaspects of domains respectively. They are customarily defined in the module startupfile and include attributes that effect presentation and validation of domains.
20 Alchemy Administrator's Guide
© Infusient LLC.
Application menus
Any options or menus available in application template pages are stored in thedatabase, not in the application code. This provides a clear separation betweenbusiness logic (authorization) and presentation (look-and-feel). Alchemyadministrators can enable/disable individual menu options based on user privilegesor other criteria without touching application code base. The customization of menuswill be reviewed in the next section.
Security model
Alchemy Framework provides a role based security model where applications tieaccess to restricted resources to named privileges which are then combined into rolesby system administrator using ACL categories. The users can then be assigned one ormore roles which are merged into a user privilege/ACL matrix by Alchemy. Thisprovides an effective separation of mechanism from policy and allows the Alchemyadministrator (re)implement the application security model to reflect businessprocess changes without modifications to the application code base.
Alchemy Application SuiteInfusient develops and sells a number of web applications using its Alchemy Frameworkplatform, some of which may have been included in your Alchemy distribution(depending on your Alchemy license and installation options). These applications arecollectively known as Alchemy Application Suite. We will present a brief overview ofAlchemy Application Suite and their module setup here before moving on how to create anew module.
Alchemy Application Suite includes the following applications:
Alchemy ERP
Alchemy ERP is a web based data analysis and reporting front-end for most commonERP systems. It supports ERP systems from SAP, Oracle, PeopleSoft and Avexus. Itsinnovative use of a compatibility layer designed around common ERP concepts allows itto be adapted to new and customized systems with relative simplicity.
Alchemy ERP uses module name Erp and its application functionality is divided betweenerp/, mrp/ and ess/ top level directories. The module startup and registry files are namederp.rc and erp.conf respectively and are placed in Alchemy system configurationdirectory (/home/alchemy/etc/).
Alchemy Task Manager
Alchemy Task Manager (ATM) is a task life-cycle management tool that enablescoordination of product teams and provides a central repository for engineeringdeliverables with groupware, work ow execution and document managementflfunctionality.
The module for ATM is called Tm with a top level directory of tm/. ATM also includesWorkflow Modeler application (module name: Wfm) in application directory wfm/ whichis a support application for the definition and maintenance of process models used inATM.
Configuring Alchemy 21
© Infusient LLC.
Alchemy STACS
Alchemy STACS is a project and initiative tracking tool that delivers full-cycle projectmanagement and tracking including cost of quality reporting, document management anda central repository for cost improvement ideas. STACS comes in multipleconfigurations customized for different application areas and methodologies such asSupply Chain, Six Sigma or Lean.
The module for STACS is called Cip with a top level directory of stacs/. Like all otherapplications in Alchemy suite, STACS uses Alchemy system configuration directory forits startup configuration and registry.
Alchemy Scheduler
Alchemy Scheduler is an enterprise job scheduling and management system. Designedwith distributed systems in mind, it provides dependency and event-based scheduling,notifications, centralized management and role-based administration. Alchemy Schedulercan also be used as a web-based job management portal for third-party job controlsystems such as CA Unicenter Autosys.
The module name for Alchemy Scheduler is Ats with a matching top level directory ofats/.
Alchemy Base
Additionally, each Alchemy server automatically loads the module Aws which delivers thedefault environment and functionality all other modules depend on as well as the AdminPortal (adm/). Alchemy base module is distributed and installed with all releases ofAlchemy Framework.
What's in a Name?Naming your Module
You probably noticed that module names in the Alchemy application suite areinitcapped, that is the first letter of the module name is capitalized while therest of the module name is in lowercase, even when the module name is anabbreviation (e.g. ERP). This is a convention adopted to visually differentiatemodule handles from other objects within the Alchemy Framework. Werecommend you follow the same naming convention for your own webapplications. Specifically, observe the following guidelines:
� Module name starts with a capital letter followed by alphabetic lowercasecharacters (a-z)
� Application directory matches module name and is in lowercase
� Any module startup and registry file names are derived from modulename by converting it to lowercase.
Creating a new ModuleOnce you finish writing your very own Alchemy web application, you need to follow asequence of steps to define it as a module and integrate into Alchemy Framework. In this
22 Alchemy Administrator's Guide
© Infusient LLC.
domain portfolio_id -sql { select portfolio_id, portfolio_desc from portfolio_master where portfolio_id = :key } -errormsg { '%v' is not a valid Risk Portfolio!} init -role -menu -filter -attachment}
Let us review main sections of this file to see how the module setup is specified:
catch {delete object Ra}
This line destroys the module object and all its configuration if it already exists. Thiswould be the case if we reinitialize the module after it is loaded. In that caseAlchemy simply reloads the module startup file and it is our responsibility to makesure the existing module object is destroyed. The statement is wrapped in a catchcommand to avoid throwing an error when loading the module for the first time.
Module Ra -desc "Risk Analysis" -url /ra -init {....}
This is the main command where the module object and its configuration is defined.Module attributes (URL, description, initialization script) are specified in key/valuepairs after the module name – Ra. The initialization script is where the defaultmodule configuration – domains, parameters, columns etc. - is defined and loadedfrom the database. We will not go into details of how those module components aredefined here. This task falls to the Alchemy developer and is unique for each module.However, we will review module components that can be configured by the Alchemyadministrator in the next section.
4. Load the Module into Alchemy Server
Once the module startup file is created, the Activate link on Alchemy Modules page turnson. Clicking on the link loads the module into the server and sets up the relatedconfiguration. The module is now ready to be used.
Naturally this recipe for creating an Alchemy module skips over the steps essential to areal application such as the code and all the functionality that goes into making aworking application. Usually Alchemy administrators work with the developers to preparea new application for production rollout per the guidelines laid out in this book.
Loading Modules at Star tup
Alchemy servers customarily load the module(s) they need as part of their startupprocessing so that they are immediately available to be used. It is common foradministrators to create a separate server instance for each application. It is also possibleto maintain multiple configurations of the same application by creating additionalAlchemy servers with different setups.
The modules to be loaded into each Alchemy server is specified on the server instancestartup file which is named after the instance id and saved in site configuration directoryi.e. /home/alchemy/local/etc.
For example; if we would like to load our module, Ra, into an Alchemy server namedtest, we need to add the following line to the file /home/alchemy/local/etc/test.rc :
Module::require Ra
Module::require command tells Alchemy server to load and configure the specifiedmodule. If more than one module is required, issue a separate Module::require command
24 Alchemy Administrator's Guide
© Infusient LLC.
for each module in the sequence they should be loaded. For example the following codefragment loads Erp, Tm and Wfm modules in sequence:
Module::require ErpModule::require TmModule::require Wfm
Configuring Alchemy 25
© Infusient LLC.
4User Administration
In this chapter, we shall cover one of the most basic administrative tasks: useradministration. It is also by far the most common and repetitive of administrative chores.We shall see how Alchemy streamlines the task of creating and managing user accountsby minimizing or bundling repetitive actions.
We will start with a review of Alchemy user authentication and authorizationfunctionality, review the pro's and con's of various authorization approaches and generalsecurity and access control issues.
We shall look into common user administration challenges. Finally, we shall review theoptions available for adding, disabling and deleting users.
User AuthenticationAlchemy uses a password file, like UNIX and most other systems, to authenticate users.The password file format is very similar to Unix /etc/passwd file. It uses colon as thefield separator. The fields are: user id, password, user name and password expiration datein Unix seconds format. The following figure provides a sample from Alchemy passwordfile.
Example 4-1. Sample etc/passwd file
admin:secret:Alchemy Administrator:doe:MyPassword:John Doe:107030000tester:Tester1:Jane Tester:107039310
You can see that the user names are lowercase and passwords can be mixed case. Thepasswords are in plain-text. Because of that the Alchemy passwd file permissions areset to be readable by the Alchemy UNIX user only. Also notice that the admin user doesnot have a password expiration date. We will look into selectively enabling or disablingpassword expiration later in this chapter. The location of the passwd file is not hard-codedinto Alchemy, instead use -userfile server option to point to the passwd file foreach instance. By convention, the passwd and other files specific to the configuration ofa server instance are kept in server configuration directory (local/etc<id>/).
User Administration 27
© Infusient LLC.
Although it may be tempting to share the same password file amongmultiple servers; The increase in administrative complexity and cross-dependencies makes it not worth the savings. We recommend youmaintain a separate password file for each Alchemy server instance.
The user id and passwords captured in the passwd file provides the basic setup toauthenticate users in Alchemy; we will later explore other user authenticationmechanisms, but for now, let us see how the authentication is triggered:
When a user tries to access Alchemy, either by typing in the URL in browser or selectinga link from a web page, the directory for the requested page and all parent directoriesleading to the requested page are checked for directory access control files, commonlynamed .htaccess, are adapted from Apache web server “ distributed configurationfile” format1. The following listing shows a typical Alchemy .htaccess file:
Example 4-2. Sample .htaccess file
AuthUserFile $::Parm(-userfile)AuthGroupFile $::Parm(-groupfile)AuthType BasicAuthName Alchemy <Limit GET POST>require group alchemy</Limit>
Let us review each line in the file to see how access control is configured:
AuthUserFile $::Parm(-userfile)
Use the server password file for authentication
AuthGroupFile $::Parm(-groupfile)
Use the server group file to check for group membership. We will review groupfunctionality in the next section.
AuthType Basic
Authorization type. HTTP Basic authorization is the default. You can also use Digestauthorization.
AuthName Alchemy
This is the message displayed to the user on login prompt.
<Limit GET POST>
This is boilerplate directive; telling Alchemy we should authorize all web access(GET and POST).
require group alchemy
In addition to a valid user name and password, we also require the users to belong thegiven group. Alchemy initially has only two groups:
admin: System administrators. Admin Portal access requires admin groupmembership.
alchemy: Everybody else. Essentially every user needs to be in group alchemy toaccess the system. We will later see that taking away alchemy group membership isan effective way to lock him out without deleting all the user setup and history.
1See URL: httpd.apache.org/docs/1.3/howto/htaccess.html for more info on .htaccess format
28 Alchemy Administrator's Guide
© Infusient LLC.
Defining an .htaccess file on any directory under Alchemy server Document Rootwill trigger directory access control for the corresponding directory and all itssubdirectories. You can override the access control setup at a lower level directory simplyby defining a new .htaccess file.
Other Authentication Mechanisms
passwd file is a simple and straightforward mechanism for user authentication. It issimple to understand and implement. However, it is also harder to extend or integrate withenterprise authentication methods such as LDAP.
Alchemy provides a plug-in mechanism to facilitate extensions to its user authorizationprocess. Essentially it provides an interface for authentication libraries which take theauthentication realm user name, password and other attributes from .htaccess andshould return success (user authenticated) or failure (access denied). The extensions touser authorization process can be developed in C, Tcl or a combination of two.
Using the plug-in approach Alchemy natively supports the following additionalauthentication mechanisms:
LDAP
Authenticate user against the LDAP server specified in the AuthUserFileparameter. AuthType is LDAP.
Digest
Use Alchemy password file for authentication but employ HTTP Digestauthentication instead of Basic. AuthType is Digest.
Database
Authenticate user against the current database if the underlying database driversupports user logins and roles. The user needs to be defined as a database user withthe given password and connect privilege. Any group requirements in the.htaccess file are checked against database roles granted to the user if theunderlying database driver supports user roles.
Whatever the authentication mechanism, the login process stays the same. The user isprompted for a user name and password, the corresponding authentication function iscalled which returns either success or failure, the user is granted access or prompted tologin again.
Support for Multiple Authentication Mechanisms
One major shortcoming of using .htaccess files to control and configure userauthentication should be obvious; the files are stored under Alchemy Document root,hence multiple Alchemy server instances should either use the same authentication setupor split their document root from the main installation. Either option is not very desirable,so Alchemy provides a feature where the name of the .htaccess file, hence theauthorization mechanism, can be specified for each Alchemy server instance.
Alchemy server option -auth is used to implement this feature. Here are the possiblevalues for this option and their explanations:
basic
This option is the default and uses the .htaccess files for user authentication asdescribed above.
User Administration 29
© Infusient LLC.
crypt
This option is essentially the same as basic except passwords in Alchemy passwdfile are encrypted for some added security.
none
This option disables user authentication. This option is equivalent to removing all.htaccess files under Alchemy document root. It is not generally recommendedbut sometimes it can be useful, for instance, when driving an Internet web site withdynamically generated content.
any other value
If anything else is provided as the value -auth option; Alchemy uses it to generatea new name for the .htaccess file. Let us use an example to explain this: Supposewe name our access mechanism new (i.e. -auth new), then Alchemy checks foraccess files named .newaccess instead of the usual .htaccess. By matchingthe value of -auth to the name of the access file and then creating those fileswhere needed with the right setup, we can implement any number of userauthentication mechanisms simultaneously in the same Alchemy implementation.
User Author izationAuthenticating users is only half of the challenge, the other half is making sure the usersonly access and manipulate the resources they are authorized to.
Alchemy provides two distinct mechanisms to define and manage user authorizationmodels:
1. Directory Based Access Control
2. Role Based Access Control
Directory Based Access ControlDirectory based access control is a simple and straightforward authorization modelsupported by most applications that separate their functionality into screens, units thatperform a single transaction or display a single report or form.
Alchemy functionality is delivered in Alchemy template pages so it lends itself to thismodel naturally. Application functionality can be split into one or more directories whereeach directory can be associated with a different access level which is matched with theprivileges users posses to determine access to any template page in a given directory.
Alchemy implements directory based access control using Groups. We have already seenan example of group usage in User Authentication section where access to Admin Portal(adm/ directory under Alchemy Document Root) is limited to users belonging to admingroup.
Implementing a new directory based access control policy is quite straightforward inAlchemy. You need to:
1. Create one or more new Groups
A new group is defined by adding an entry to the GROUP domain in Alchemy module.Pull up the list of values for GROUP domain via: Admin Portal→Sidebar→Modules <Alchemy>→Module Properties→Parameters<Group>
30 Alchemy Administrator's Guide
© Infusient LLC.
Add your group to LOV Key, group names should be short lowercase tokens. enter a briefdescription to LOV Desc, commit your changes. Repeat for each new group you need.
2. Partition Template Pages into Sub Director ies
This step is required only if you have different access levels for your module. For instancescreens that are used to change application setup or otherwise restricted can be moved toa restricted directory under module directory.
3. Tie Groups to Director ies
For each access controlled directory create an .htaccess file with the right “requiregroup” clause. See the .htaccess files included with Alchemy or Example 4.2 for correctsyntax.
4. Assign Users to Groups
For each user who needs access, pull up the corresponding User Profile (AdminPortal→Sidebar→Profile <User Name>) and update the groups the userbelongs.
Pro's and Con's of Directory Based Access Control
Directory access control has quite a few advantages that come at the expense of featuresneeded in a full f ledged security model. Let us look some of the pro's and con's of usinggroups and directory level access control.
Pro's:
Simple
Groups provide a access control mechanism that is simple and easy to implement.The concept has been used extensively, from UNIX to web servers. The wideapplication of the concept provides a simpler transition for administrators new to thesystem.
Easy to Setup and Administer
Managing application access via groups is a snap. Users can be added to and deletedfrom groups easily. If our requirements change, a quick reshuffling of screens and anew group is all it takes to get back on track.
Low Cost
Due to its simplicity and ease of use; using groups does not have a steep learningcurve and requires very little upfront setup. These advantages mean a webapplication using group based user authorization can be up and running in a matterof days.
Con's
Inflexible
The advantages that work for group concept when the application was smaller startsturning against it when the application complexity increases. There is no way tocapture shifting user roles or levels of access without creating more groups andslicing the application functionality into smaller compartments.
User Administration 31
© Infusient LLC.
Too Coarse
Screen level access control is fine if the application can be designed into self-contained screens that perform one action that can be controlled by group access. Butonce object level or field level access control is needed then the screen level controlprovided by groups stop working. One symptom of that is a proliferation of screensthat are essentially identical except one or two details usually related to businessprocess.
Intrusive
The requirement to move screens into directories so that they can be accesscontrolled embeds the security model into the application source code. This hassome unintended consequences such as diversified source bases and thecorresponding reduction in code reuse, changes in the application due to changes inthe security model and an increase in development effort and bugs.
As you can see, directory based access control is a simple and time-tested solution thatprovides a quick and low cost path to access control. However, as the applicationfunctionality and the corresponding complexity increases, this approach starts to fallapart. Clearly a new solution that provides fine-grained (object and field level) access-control with a clear separation between policy and mechanism is needed. Alchemy fulfillsthis requirement with a Role based Access Control Mechanism.
Role Based Access ControlAlchemy implements a role based security model for fine-grained, context-based accesscontrol and authorization. It is based on named privileges and Access Control Lists(ACLs) with the following characteristics:
• Access controlled application functions are associated with named privileges (e.g.Create Task, Approve PO etc.)
• Privileges are combined into roles by ACL categories where each ACL category is apotential match between the attributes of the controlled object (e.g. PO) and theattributes possessed by the user. The application only deals with privileges andmakes no assumptions about the ACL categories or the roles available.
• Each user is assigned one or more roles which are combined to derive the user'sprivilege/ACL matrix.
• At run time, whenever the user requests access to a controlled object, the applicationqueries Alchemy for the privilege; Alchemy compares object's attributes against theACL held by the user and, for all matches, checks the user's ACL matrix for theprivilege requested. Access is granted if the privilege is found, denied otherwise.
Do not worry if this description did not immediately make sense, we will expand on eachstep and explain how Alchemy implementation works. For now let us just say thatAlchemy ensures security mechanism (which privilege is required for each action) isseparated from the security policy (how those privileges are granted) so that securitypolicy can be changed without modifying the application code.
Let us first clarify some concepts introduced in the previous paragraphs:
Privilege
Privileges are named tokens tied to controlled actions. Applications that takeadvantage of Alchemy role based access control perform privilege checks prior to
32 Alchemy Administrator's Guide
© Infusient LLC.
performing any restricted operation. For instance an application may require a“Cancel Order” privilege before canceling a work order. The names and applicationof privileges are defined in the application code so it is the responsibility of theapplication developer to set up the security mechanism. Any changes to the securitymechanism, for instance tying a “Send Message” privilege to Send button in your e-mail application requires a corresponding change in the application code.
Access Control List (ACL)
ACLs are lists of key/value pairs that describe an object. In that respect, they aresimilar to fields of a table or attributes of a record. For instance an Alchemy usermay have the following ACL:{ name “John Admin” department Support teams { Engineering Development} }In the above list each key (i.e. name, department, teams) is called an ACL category.As you can see in teams, some categories can have multiple values.
ACL Match
Whenever Alchemy is asked to check for a privilege, it first performs a comparisionbetween the requesting user's ACL and the controlled objects ACL. Any ACLcategory where the corresponding values are identical is a match. For instance if theuser's department matches the department field on the PO then we have a match ondepartment.
Role
A role is just a shorthand for a list of privileges granted by ACL category. It is in theform of a matrix where privileges form the rows and ACL categories make up thecolumns. If there is a check on a cell then it means the corresponding privilege isgranted if user's ACL matches the controlled objects ACL on that category.Administrators define the ACL categories and build roles from them. The set of rolesdefined for an application make up the application's security policy.
Privilege/ACL Matrix
A user's privilege/ACL matrix (or just ACL matrix) is built from all the rolesassigned to the user and represent the total sum of all privileges granted to the user.Alchemy searches the user's ACL matrix for all matching ACL categories to verifythe validity of a requested privilege.
An Example
Let us now look at an example of how role based access control works. We will use POApproval ( a very common action) as our example:
• The Alchemy developer incorporating “PO Approval” functionality accuratelyconcludes that this action needs to be access controlled. The developer adds the newprivilege to the module's PRIVILEGE domain and incorporates the privilege checkto application code.
• During integration testing, the system engineer decides, per the user requirements,PO's can be approved by either requester's manager or the team leader for the teamthat the PO is cut for.
• System Engineer works with the Alchemy administrator to define the ACL categoriesfor Manager and Team.
User Administration 33
© Infusient LLC.
• During user acceptance testing, user roles such as Requester, Team Leader, SupplyChain are built and refined. Users are assigned their initial roles as roll out dateapproaches.
• Application rolls to production. In the first week, users realize that managers areasked to approve requisitions for ball point pens and break room coffee. TheAlchemy administrator adds ACL category “ Cost” and changes Requester role toallow it to self-approve PO's costing less than $100. He does not bother calling thedeveloper.
This somewhat forced scenario illustrates the flexibility, and the potential for savings, ofthe Alchemy Role based security. It requires a higher up front investment - in planningand configuration - compared to the traditional screen level access control approaches.But its ability to evolve and adapt as the business processes evolve makes it worth theeffort.
34 Alchemy Administrator's Guide
© Infusient LLC.
Appendix IAlchemy Schema
Alchemy Framework maintains and uses meta-data regarding its configuration, setup,users, security model, history and other aspects of its functionality. Some of this data issaved in configuration files in the file system (e.g. registry). But the majority ofstructured data needed for proper functioning of Alchemy is captured in database tables.
This appendix provides an overview of tables that are bundled with any Alchemyinstallation. The purpose of each table is described briefly followed by a list of columnsthat make up the table.
Please note that the tables listed below are the bare minimum needed for a functionalAlchemy installation. Each Alchemy application may, and does, have its own set ofdatabase schema objects including tables, views, packages etc. Refer to thedocumentation for a particular Alchemy application for details of its database schemarequirements and makeup.
Table Appendix I-1. Alchemy Framework Tables
Table Name Descr iption
AWS_ACL User Access Control Lists
AWS_ACL_CATEGORY ACL Categories by Module
AWS_ATTACHMENT Document and other Object Attachments
AWS_DIRECTORY Alchemy User Directory
AWS_FILTER Search Filters
AWS_HISTORY Alchemy Change Log
AWS_LOV_REF Application Domain Values
AWS_MENU Application Menus
AWS_MENU_OPT Application Menu Options
AWS_ROLE Application Role Privileges
AWS_USER_ROLE Roles assigned to Users
DS_TEAM Team Definition
DS_TEAM_MEMBERS Team Members
Alchemy Schema 35
© Infusient LLC.
AWS_ACLThis table captures the Access Control Lists (ACL) assigned to users. ACL’s are collectionof tokens grouped by categories that define and limit the scope of the privileges grantedto users. Some ACL categories can be derived from the meta-data about the user, such asuser id, org code or the teams the user belongs to. Yet other categories of ACL’s are notso obvious and need to be defined for each user. For instance, the list of buildings the userhas access to or the names of databases a DBA can work on. Once this information iscaptured for each user, role based access rules can be formulated at the object level suchas:
Grant user entry only if the target building is in user’ s building ACL.
Allow DBA to shutdown the database only if the DBA has the database in his ACL.
The ACL for each user is captured in the ACL column of AWS_ACL table in categorytoken list pairs. For instance if our DBA, Joe Admin, has an Alchemy user id of “ joe”, orgcode of “ IT” and access to databases production and development then his ACL would belike:
{id joe org_code IT database {production development}}
For more information on ACL’s see Also AWS_ACL_CATEGORY and AWS_ROLE.
Table Appendix I-2.AWS_ACL Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value “SYS”
MODULE Character (15) Alchemy Module ID
DOMAIN_NAME Character (15) ACL Owner Domain – Always “USER”
DOMAIN_KEY Character (15) User ID
ACL Character (2000) ACL – List of Category/Value pairs
AWS_ACL_CATEGORYACL’s are captured by category and before we specify any user ACL’s, the administratorneeds to define valid ACL categories for each Alchemy module. This table captures ACLcategories applicable to any role enabled module.
It is possible to have a role enabled module without any additional ACL categoriesbecause a default set of ACL categories are pre-defined based on user meta-data. Theseare:
Category Id Category Descr iption
1 All – Privilege checks against this ACL category always return a match
2 ID – ACL matches if user’s ID matches target’s owner ID
3 Hierarchy – ACL matches if target’s owner reports to user
5 Org – ACL matches if target owner’s org code matches user’s org code
In the previous table category id is the unique identifier for each ACL category. Use asmall integer value greater than 5 for any new ACL category defined inAWS_ACL_CATEGORY.
36 Alchemy Administrator's Guide
© Infusient LLC.
Table Appendix I-3.AWS_ACL_CATEGORY Table Columns
Column Name Type Description
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
SEQ_NO Integer Category order (Left-to-Right) in ACLMatrix
CATEGORY_ID Integer Unique Identifier for the ACL category
CATEGORY_NAME Character (30) Category Label
DOMAIN_NAME Character (30) Validation domain for ACL tokens
AWS_ATTACHMENTAlchemy framework provides a generic API for the creation and management of objectattachments such as documents, notes, messages and other objects. All attachments arecaptured in AWS_ATTACHMENT table by parent object.
Table Appendix I-4.AWS_ATTACHMENT Table Columns
Column Name Type Descr iption
OBJECT_TYPE Character (15) Type of parent object
OBJECT_ID Character (30) Unique identifier for parent object
SEQ_NO Integer Attachment sequence – Used for ordering
ATTACHMENT_TYPE Character (15) Type of attached object
ATTACHMENT_REF Character (500) Unique identifier or other representationof attached object
NOTE Character (500) User’s Comments
USER_NAME Character (30) User ID for attachment creator
TRANS_DATE Timestamp Attachment creation date
AWS_DIRECTORYAWS_DIRECTORY lists all known users in a given Alchemy instance. The directorycaptures user attributes ranging from the obvious - first and last name, to theorganizational – supervisor, org_code and administrative – status, last login date.
Table Appendix I-5.AWS_DIRECTORY Table Columns
Column Name Type Descr iption
USER_ID Character (15) User’s login id – upper case
LAST_NAME Character (30) Last name is initcapped
FIRST_NAME Character (30) First name is initcapped
MIDDLE_INIT Character (1) Middle Initial
JOB_DESC Character (30) Job description or title
DEPARTMENT Character (6) User’s Department
Alchemy Schema 37
© Infusient LLC.
Column Name Type Descr iption
ORG_CODE Character (6) Org Code. Can be used with departmentto capture matrixed org structures
SUPERVISOR Character (30) Supervisor’s user ID. Null if user’ssupervisor is not in the user directory
PHONE Character (15) Phone # in (XXX) XXX-XXXX format
LOCATION Character (15) Location can be office/cubicle #
EMAIL_ID Character (60) User’s E-Mail – used by Alchemy for e-mail notifications
STATUS Character (1) Active or Inactive
CREATE_DATE Timestamp Date user is added to the directory
LAST_LOGIN_DATE Timestamp Last Alchemy login by user
PASSWD_EXP_DATE Timestamp Password Expiration Date – If passwordexpiration is enabled
AWS_FILTER AWS_FILTER captures search filters defined for any Alchemy module by category. Thefilters are specified using SQL expression fragments. Modules load their filters into anAttributeSet named aws::filter on startup. Modules consult this attribute set to pullin the filter definitions as needed.
Table Appendix I-6.AWS_FILTER Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
FILTER_CATEGORY Character (15) Filters are grouped by Category
FILTER_ID Character (15) Filter ID. Unique within a Module andCategory
SEQ_NO Integer Filter Sort/Display Order
FILTER_NAME Character (80) Descriptive Label for the Filter
FILTER_STATUS Character (1) Active or Inactive
CONDITION Character (250) SQL Criteria for the Filter
COMMENTS Character (250) One paragraph or less
AWS_HISTORYAlchemy framework provides a generic API for the capturing changes to object attributesor other milestones by module and object key. All log records are saved inAWS_HISTORY table.
38 Alchemy Administrator's Guide
© Infusient LLC.
Table Appendix I-7.AWS_HISTORY Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
OBJECT_ID Character (30) Unique Identifier for the object being updated
SEQ_NO Integer Log sequence number
CHANGE_TYPE Character (6) Categorizes the change for reporting / analysispurposes
CHANGE_DESC Character (2000) either a descriptive message or a list ofold/new values for updated fields separated by“~”
USER_NAME Character (30) User ID for person performing the change
TRANS_DATE Timestamp Change Date/Time
AWS_LOV_REFAlchemy framework provides a generic API for the capturing changes to object attributesor other milestones by module and object key. All log records are saved inAWS_LOV_REF table.
Table Appendix I-8.AWS_LOV_REF Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
PARAM_NAME Character (30) Domain Name
SEQ_NO Integer LOV Key Sort / Display Order
LOV_KEY Character (30) Unique LOV Key
LOV_DESC Character (150) User visible LOV Label
AWS_MENUAll application menus in Alchemy are captured in a pair of tables, AWS_MENU (header)and AWS_MENU_OPT (detail – options). As modules are initialized, any module menusare loaded automatically into Alchemy and made available to page templates.Administrators can customize menus without changing the underlying application code.The following are some of the customization options available:
Change menu display – e.g. switch a tabbed menu to labeled buttons or list
Enable/disable menu options
Add role based security or other checks to individual options
Change option labels, icons or tool tips.
Reorganize menu option display order.
Alchemy Schema 39
© Infusient LLC.
Table Appendix I-9.AWS_MENU Table Columns
Column Name Type Descr iption
MENU_ID Integer Unique Identifier for menu – systemgenerated
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
MENU_NAME Character (15) Menu name should be unique within amodule - lowercase
MENU_TITLE Character (30) Short description of menu
MENU_DESC Character (80) Purpose and application of menu
ACL Character (30) Authorization required to use menu
MENU_PROP Character(500) List of menu properties – Future
The menu name in the previous table, along with module name, is the handleprogrammer uses to activate the menu. The system assigned menu_id is used internallyand is not needed/referenced in the page templates. For instance if the menu name istasklist and module is Tm then the menu is referenced in the page template as tm.chartPlease note that the handle uses period as the separator between module and menu nameand is in lowercase.
AWS_MENU_OPTThis table is the second part of application menu tables and captures menu options (i.e.tabs, URLs, buttons etc.)
Table Appendix I-10.AWS_MENU_OPT Table Columns
Column Name Type Descr iption
MENU_ID Integer Unique Id of menu
SEQ_NO Integer Menu option sequence
OPT_LABEL Character (30) Option label
OPT_TYPE Character (6) Option type – usually URL, alsoseparator, boiler plate etc.
OPT_STATUS Character (1) Active or Inactive – Inactive options areskipped
IMAGE Character (30) Option icon, where applicable
OPT_DESC Character (255) Tool tip for option
CONDITION Character(500) If condition does not return true, option isskipped
COMMAND Character(500) The action for option i.e. URL
OPT_PROP Character(500) List of option properties – Future
40 Alchemy Administrator's Guide
© Infusient LLC.
AWS_ROLEIn Alchemy, a role is a shorthand for a collection of privileges that can be granted toindividual users. The privileges are assigned to the role by ACL categories and form amatrix. This matrix is captured in AWS_ROLE table for each module and rolecombination.
Table Appendix I-11.AWS_ROLE Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
ROLE_ID Character (15) Role ID, unique within a module
ROLE_DESC Character (30) Textual description of role
ROLE_TYPE Character (1) Reserved, Always “G”
AUTH_KEY Character (30) Privilege/ACL Category matrix in listformat
In the previous table AUTH_KEY column captures the matrix in list format where eachtoken represents a cell of the matrix. The tokens are formed by concatenating privilegekey with the corresponding ACL category id. For instance if we grant “Create Task”privilege to “All” then the corresponding token in AUTH_KEY is NEW1 (Create Task →NEW, All → 1).
AWS_USER_ROLEOnce roles are defined in AWS_ROLE table, they can be granted to individual users.AWS_USER_ROLE table captures the many-to-many mapping between module roles andusers. Alchemy merges the privileges from all the roles assigned to the user into onemaster authorization key and this key determines fine grained access to Alchemyresources.
Table Appendix I-12.AWS_USER_ROLE Table Columns
Column Name Type Descr iption
CONTEXT Character (6) Reserved for future enhancement – value“SYS”
MODULE Character (15) Alchemy Module ID
USER_ID Character (15) User the role is granted to
ROLE_ID Character (15) Role granted to user
DS_TEAMAlchemy framework provides functionality to define teams and their members using itsadministrative screens. This functionality is made available to Alchemy applications touse as they see fit. For instance Task Manager module uses teams for collaboration aswell as for role based access (team membership is an ACL category in ATM) and
Alchemy Schema 41
© Infusient LLC.
resource group definition. Basic team attributes are captured in DS_TEAM table and teammembers are saved in DS_TEAM_MEMBERS table.
Table Appendix I-13.DS_TEAM Table Columns
Column Name Type Descr iption
TEAM_NAME Character (15) Unique team ID
WORKGROUP Character (15) Workgroup is used to categorize teams.This usually defaults to the module.
TEAM_DESC Character (80) Team title
LEADER_NAME Character (30) User ID for team leader
MISSION_DESC Character (200) Team purpose (one paragraph,informational)
TEAM_STATUS Character(1) Active / Inactive
DATE_FORMED Date Date the team is created
DS_TEAM_MEMBERSThis table captures the list of members for teams. Team members need to be Alchemyusers (i.e. in the AWS_DIRECTORY).
Table Appendix I-14.DS_TEAM_MEMBERS Table Columns
Column Name Type Descr iption
TEAM_NAME Character (15) Unique team ID
MEMBER_NAME Character (30) User ID for team member
MEMBER_TITLE Character (40) Member function / title
MEMBER_STATUS Character(1) Active / Inactive
DATE_JOINED Date Date the team member joined the team
42 Alchemy Administrator's Guide
© Infusient LLC.
Appendix I ICommand Reference
This appendix provides the command reference pages for the executables distributed withAlchemy. Each command is briefly described followed by synopsis, command lineoptions, one of two paragraphs of usage description as well as troubleshooting info andexamples where applicable. The reference page format follows that of UNIX man pages.
The commands described here can be found in the bin/ directory under Alchemy home.These commands should only be run by the alchemy UNIX user.
Command Reference 43
© Infusient LLC.
ash - Alchemy ShellInteractive command shell wrapper for Alchemy Framework API
Synopsis
ash [option value].. [scriptfile [args]]
Options
-id ServerId
This option is a shorthand for the default options defined for ServerId. Any duplicateoptions provided on the command line override the defaults defined for the server.
-dblogin DSN
The DSN to be used for initial database connection. Default is alchemy.
-code command
Execute command on startup. This option, when specified, precedes scriptfile.
Alchemy Server Options
Any Alchemy Application Server options (see aws) are also valid for ash and havethe same semantics
scriptfile
Ash executes the script file and exits if one is provided. When omitted ash comes upin interactive mode and prompts user for commands.
args
Any additional arguments after the script file are passed to the script verbatim.
Description
Ash is built around a Tcl core. You can utilize the full functionality of Tcl in ash scripts.The primary use for ash is to take advantage of various Alchemy API’s documented inthe Alchemy Developer's Reference.
Examples
ash -id production
Startup ash with the setup and database connection defined for Alchemy serverproduction.
ash -dblogin db1
Connect to the database defined by DSN db1.
ash
Connect to the database defined by DSN alchemy.
Files
/home/alchemy/etc/ash.rc
Ash startup configuration file
home/alchemy/etc/ash.conf
Ash registry entries
44 Alchemy Administrator's Guide
© Infusient LLC.
aws - Alchemy Application ServerAlchemy Application Server deamon with embedded web server
Synopsis
aws [option value]..
Options
-id ServerId
This option is a shorthand for the default options defined for ServerId. Any duplicateoptions provided on the command line override the defaults defined for the server.
-dblogin DSN
The DSN to be used for initial database connection
-pconf [[true | false] | id]
If pconf attribute is set to true then aws searches and loads <id>.rc and <id>.conffiles where <id> is the server id defined with –id option. You can also specifyanother server id to replace the default configuration with another server’s setup.
-root directory
Web server document root. The default is web/ directory in Alchemy home.
-host hostName
The host name portion of aws URL. The default is the machine name.
-port port#
The port to listen for requests. The default is 80.
-tmpdir directory
The directory for temporary files. The default is web/tmp/ directory in Alchemyhome.
-logdir directory
The directory for server logs. The default is web/log/ directory in Alchemy home.
-auth [basic | digest | ip | custom ]
User authentication mechanism. Basic and digest implement the correspondingHTTP authentication mechanism. IP uses the client's IP address for access controland is used exclusively for dedicated server access. Custom authenticationmechanisms can be implemented by providing a plug-in to handle the authentication.
-userfile passwordFile
User password file. Alchemy application server uses this option to verify userpasswords.
-groupfile groupFile
User groups file. Alchemy application server uses this option to enforce directorylevel access a la Apache.
-listeners number
Number of additional aws processes launched to provide round-robin load balancing.The default is to have a single aws process handle all incoming requests.
Command Reference 45
© Infusient LLC.
Description
Aws is the main Alchemy application server deamon responding to requests fromAlchemy users. It has an embedded web server and can also be configured as a contentsource for Apache web server.
Aws is almost never invoked directly from the command line. Instead Alchemy ServerController – awsctl – launches a separate aws process for each Alchemy applicationserver instance defined in /home/alchemy/etc/servers.
Use command line options and Alchemy server startup and registry files to customize thebehavior of an aws process. Aws does not read its standard input and prints diagnosticsand error messages to its output. awsctl captures the output of aws processes itlaunches in the /home/alchemy/etc/awsctl.log file.
Examples
aws -id production
Start Alchemy Application server with the options defined for server instanceproduction.
aws -id production -dblogin preprod
Start Alchemy Application server with the options defined for server instanceproduction except connect to the database defined for DSN preprod instead.
aws -id production -port 9000
Start production instance at port 9000 instead of its default listener port.
Troubleshooting
Aws may fail to configure itself properly if it can not connect to the database or if thetarget database does not include a valid Alchemy schema. The log file/home/alchemy/etc/awsctl.log captures aws startup and diagnostic messages and is usefulfor troubleshooting server problems.
Files
/home/alchemy/etc/aws.rc
Aws startup configuration file
home/alchemy/etc/aws.conf
Aws registry, includes the default look-and-feel and additional skins
home/alchemy/local/etc/<id>.conf
Alchemy Server instance startup configuration
home/alchemy/local/etc/<id>/
Alchemy server instance configuration directory, holds module startup and registryfiles for the corresponding server.
46 Alchemy Administrator's Guide
© Infusient LLC.
awsctl - Alchemy Server ControllerAlchemy Server Startup and Shutdown Manager
Synopsis
awsctl [start | stop | sync ] [serverId]
Options
start
Starts up the specified server. If the server id is not provided then awsctl starts alldefined Alchemy servers. If a server is already running then it is recycled (i.e. it isshut down and restarted).
stop
Shuts down the specified server. If the server id is not provided then awsctl stopsall Alchemy servers.
sync
Starts up the specified server if it is not already running. If the server id is notprovided then awsctl checks the status of all defined Alchemy servers and starts upany inactive server(s).
Description
awsctl ensures that all Alchemy server instances are started and shutdown in acontrolled manner, performs the needed server status updates and captures the audit trailand diagnostics.
Using awsctl consistently in system startup and shutdown scripts ensures Alchemyserver configuration is always kept in a consistent state. Make sure the command isexecuted with the Alchemy UNIX user effective id. Adding the following line to thecorresponding system startup file should work:
su – alchemy –c “/home/alchemy/bin/awsctl start”
Examples
awsctl start
(Re)start all Alchemy servers.
awsctl stop test
Stop server test if it is running.
Files
/home/alchemy/etc/servers
Alchemy server configuration and status. Do not edit!
home/alchemy/etc/awsctl.rc
Alchemy Server Controller configuration file.
home/alchemy/etc/awsctl.log
Alchemy Server diagnostic and error messages
Command Reference 47
© Infusient LLC.
awsdispatch - Alchemy Server Load BalancerTCP Load Balancer with client affinity and failover
Synopsis
awsdispatch [host:]port shost:sport..
Options
[host:]port
The local address and port to listen for connections. By default awsdispatchlistens to all local addresses.
shost:sport
The address and port of back-end server.
Description
awsdispatch is a load balancer for TCP based protocols such as HTTP. It allowsseveral servers to appear as one to the outside world. It automatically detects servers thatare down and distributes clients among available servers. It also maintains client to backend server affinity while ensuring high availability, automatic failover and scalableperformance.
Alchemy server controller, awsctl, uses awsdispatch to handle load balancing forservers with multiple pre-launched listeners (see -listener attribute to aws).
Examples
awsdispatch 80 server1:80 server2:8000 server2:9000
Split web server traffic between three servers on two machines (server1 andserver2).
48 Alchemy Administrator's Guide
© Infusient LLC.
initdb - Setup Alchemy SchemaInitialize or clone Alchemy schema objects and configuration
Synopsis
initdb target [option value]..
Options
target
The DSN for the target database schema.
-source DSN
Use DSN for the Alchemy meta data and configuration stored in database. Normallyinitdb uses the SQLite database file that comes with the distribution.
-modules list
Limit the module meta data to the modules specified. The list of modules can bespecified as a colon separated single argument (e.g. Aws:Erp:Ats )
-data boolean
This option, when set, causes initdb to copy application data to the new schema ifavailable. The default is not to copy the application data.
Description
This command simplifies the creation and setup of new Alchemy database schemainstances by creating all the database objects (tables, triggers, database procedures,indexes etc.) needed for a functioning Alchemy server. It also populates the tables withthe default meta data and configuration used by Alchemy Application Server.
You can also use it to quickly clone an existing Alchemy server configuration by usingthe -source option.
All RDBMS systems supported by Alchemy provide similar tools for backing up andcloning database schemas and these RDBMS vendor specific tools can also be utilized toachieve the same result. The difference in initdb, and the reason for its existence, is itsability to clone schemas across products from multiple database vendors (e.g. move anAlchemy server with its data from Oracle to Postgres).
Examples
initdb preprod -source production
Copy all Alchemy meta data from production to preprod. Database objects arecreated in preprod if missing.
initdb test -modules Aws:Tm:Wfm
Initialize schema test with schema objects used by Alchemy, Task Manager andWorkflow Modeler modules. Use the schema setup in the latest Alchemydistribution.
Troubleshooting
The target DSN and the corresponding schema should be setup and available with theright database privileges (i.e. resource etc.) before initdb is run. The program printsdiagnostic and error messages to its standard output.
Command Reference 49
© Infusient LLC.
rotate - Rotate Alchemy Server LogsAnalyze and compress Alchemy Server logs, build monthly usage charts
Synopsis
rotate [serverId] [Date]
Options
serverId
The Alchemy server id to perform web usage analysis on. If serverId is omitted(or equal to “*”) then usage logs for all defined Alchemy servers are rotated.
Date
When provided, all usage logs up to and including Date are rotated. Defaults tocurrent date.
Description
rotate analyzes web server usage logs generated in CLF format (the log format ofApache and Alchemy) and generates usage reports and charts in HTML. It alsocompresses and archives the logs at the end of each month.
Rotate does not actually perform the analysis, instead it acts as a driver for third party logfile analysis programs such as webalizer (the default) passing each log file to theanalysis program in turn and taking care of general bookkeeping. You can customize thelog file analysis program used and other aspects of rotate functionality by adjusting itsconfiguration file (rotate.rc).
Examples
rotate production "Last Monday"
Rotate all pending usage logs up to and including last Monday's for serverproduction
rotate
Rotate usage logs for all Alchemy servers
Files
/home/alchemy/etc/rotate.rc
Startup configuration file for rotate.
home/alchemy/web/log/aws_<id>.<year>.<month>.<day>
Daily usage logs for each Alchemy server in CLF format.
home/alchemy/web/log/< id>.<year>.<month>.tar
Tar archive of current month's usage logs for each server.
home/alchemy/web/log/< id>.<year>.<month>.tar.gz
Monthly compressed archive of usage logs for each server.
home/alchemy/web/log/< id>/
12 month rolling usage history charts for each server.
50 Alchemy Administrator's Guide
© Infusient LLC.
Appendix I I IResources
We started the book with the stated assumption that the reader is well versed on manyInternet, open source and UNIX technologies the subject of this book, Alchemy is builtupon. We knew that, in this time of furious technological change, it is impossible for anyindividual to keep up with all the changes surrounding the web.
Here we are going to take a step back and try to make up for our omission of many detailspertinent to our subject by pointing out resources that provide in-dept coverage oftechnologies referenced throughout the book.
Internet ResourcesThe links below are to resources available on the Internet. They were valid at the time ofwriting, but they may well be out of date by the time you read this. If so, try a Googlesearch for general terms.
www.infusient.com
Infusient web site is the place to go to check for document updates, errata as well asgeneral information on Alchemy. Use the support portal to stay on top of newreleases, patches and open bug reports.
www.tcl.tk
Tcl is the main scripting language of Alchemy. It is used in startup and configurationfiles, web template pages and the main interface to Alchemy API. Tcl/Tk portalprovides documentation for Tcl; it is also a launchpad for other Tcl resources.
www.w3.org
World Wide Web Consortium is the driving force behind Internet and thetechnologies that power it. This site provides a treasure trove of information on thestandards that forms the basis of Alchemy such as HTML, CSS, XML, SVG andmany others.
Resources 51
© Infusient LLC.
BooksWelch Brent, Practical Programming in Tcl and Tk (Prentice Hall, 2003)
This is the definite guide to Tcl. It is a must for anyone who programs in Tcl, thelanguage of Alchemy. The book is quite hefty and covers much more than one needsto change the occasional startup file or even write Alchemy applications. However itscompleteness might save you a lot of time searching the web.
52 Alchemy Administrator's Guide