Alchemy Administrator's Guide - Infusient LLC · ' Infusient LLC Preface This book is the...

Infusient

Alchemy Administrator's Guide

Alchemy

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:

[email protected]

Preface v

© Infusient LLC

vi Alchemy Administrator's Guide

© 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


© 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.


© 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.


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


© Infusient LLC.


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.


© 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.


© 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


-dbname Postgres database name.


-port Postgres listener port

Sybase:



-server Sybase database server.

MySQL:



-db Schema name.


-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


© 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


© 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.


© 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.


© 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.


© 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


© 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


© 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


© Infusient LLC.


© 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


© 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.


© 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>


© 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.


© 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


© 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.


© 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.


© 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.


© Infusient LLC.

Table Appendix I-3.AWS_ACL_CATEGORY Table Columns

Column Name Type Description

CONTEXT Character (6) Reserved for future enhancement – value“SYS”


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


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


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.


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




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.


© Infusient LLC.

Table Appendix I-7.AWS_HISTORY Table Columns




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




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


MENU_ID Integer Unique Identifier for menu – systemgenerated



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


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


© 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




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




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


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


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


© 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


© 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.


© 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.


© 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


© 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).


© 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.


© 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.


© 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.


Date post:	01-May-2018
Category:	Documents
Upload:	lytruc
View:	223 times
Download:	0 times