Fulford Consulting Ltd.

APP Flare support & training.

0793 572 8612.

Flare help pages.

APP Flare user help pages.

Overview

The page below describes how APP/Flare may be configured to use a web server to provide "Users' Help"

The "User Help" system in APP/Flare defaults to a plain text record that is maintained as part of the APP/Flare system.

There is a limited degree of context sensitivity. Help can be specified, for instance for "Miscellaneous Activities Update" (MAU) but not for the sub-screens on the tabs, nor for "User Defined Windows".

The "User Help" can be configured to use external files. This facility allows the help pages to be externally maintained and formatted, using modern tools.

With a little ingenuity it is possible to use this capability to provide an index into the pages of a web server with or without the use of a shared drive.

System Requirements.

Scripting language

The script can use what ever language you prefer or have available, PHP, Perl, MS DOS (with extensions), MS Basic etc will all provide the functionality required.

I prefer to use Cygwin 's shell commands. Cygwin is free, open source and takes only 10 or 15 minutes to install. I've been 25 years in the business of systems administration and I find the power and flexibility of UNIX / LinUX shell commands are preferable to the complexities and potential errors of programming languages.

Whatever scripting tool is chosen, it needs to be available on all the client PCs. If you have a good distribution system or very few PCs using APP/Flare, I would recommend installing the tools locally in order to harvest the performance benefits. In a situation where you have perhaps 400 PCs using APP/Flare and no method of carrying out remote installs then a shared drive is essential.

Shared drive.

It is possible to use any networked drive that is available to all the APP/Flare clients on your network. I prefer to provide space on the APP/Flare server for a networked file system. This ensures that if the APP/Flare server is up, then the ancillary tools are also available. This system is tightly integrated and unnecessary dependencies which can cripple the service are avoided. The technique will work however with a shared drive from a different server.

APP/Flare expects to be integrated with Microsoft products and uses drive letters or the Microsoft Universal Naming Convention (UNC) for locating files. APP/Flare does not recognise the otherwise ubiquitous internet standard "Universal Resource Identifier" or URI.

This means that when a export type is created for the help pages in EXT, there has to be a file available which the APP/Flare client can access on a local drive or by using a UNC path or a mapped drive letter.

As I have users on the other side of the City and 3rd party organisations using the APP/Flare system through the extra-net, I need to use UNC path names.

I want to make sure that if the APP/Flare server is up, then the shared drive is also available. By exporting the shared file system from the the APP/Flare server I can be very confident that all users will be able to access the shared drive.

If APP/Flare is running on a Windows server then a "folder" may be created and shared using the "Properties" option.

If a UNIX or LinUX box is being used then a free open source solution for file sharing to MS clients called SAMBA may be used. This is my preferred solution. The use of SAMBA on a server for which I have responsibility relieves me of concerns regarding authentication services. I can effectively prevent write access to any of the shared files while make them readable by anyone on the corporate network regardless of their local authentication service.

Downloading and installing SAMBA will be dealt with elsewhere.

I use the same shared disk for a number of APP/Flare related tools. The server has the name "flare" and the shared directory is called "tools".

Configuring EXT

See the screen dump below.

Only the "Document Indexing Configuration" section needs to be completed. The "Classic" option is used as our files have not been installed on the individual APP/Flare clients and so will not be included in the Registry (the integrated option would try to find the program in the registry, if this method were chosen Cygwin would need to be installed on every PC using the APP/Flare system).

The command runs the Bourne Again Shell (BASH) from Cygwin with the identity of the Flare program from which it was called, ($FPROG), as the parameter. Flare assumes that $FPROG is the name of the help file and checks the directory (folder) given at "Location" to see if the file exists. If the file can't be found the file name configured as the "Default File" in CFS (see below) will be used instead of $FPROG.

I've checked "Suppress DOS Prompt" but don't worry if this doesn't work, it doesn't work for me either but it has no impact on functionality.

"Location" is where the Cygwin tools are located, not the location of the help files/web pages. I use the UNC path to the Cygwin shell to make it available to users who do not have the shared drive mapped as the X: drive.

I haven't entered the file "Extension" as the script am going to use can manipulate the name more easily without it.

CFS System Configuration APP/Flare now needs to be configured to use the "help" external file type for "User Help".

Startup CFS and click on "Users' Help". See the screen dump below. The "Export Type" is whatever we have called the EXT definition above. In this case "help".

In my example the "Default file" is set to "\\flare\tools\etc\help", again using the UNC path to avoid tying the path to a particular mapping. Note that once again the file is a script, not an actual help page.

Help pages.

The help pages may be written using whatever tools and formats are preferred.

The web server can reside anywhere in your network or even externally (see City Linux). I prefer to use a web server on the APP/Flare server for similar reasons to those for preferring to putting the shared drive on the same server. I know that every APP/Flare user can resolve the server name and access the box. If the APP/Flare application is up then I can be sure the ancillary services will be too, I have no unnecessary dependencies to cause technical or political problems.

I use Apache which is free, open source and available for both Windows and UNIX/LinUX servers. On LinUX boxes it comes as standard but is simple to install to either type of platform. Configuration of Apache servers is dealt with elsewhere.

Script

This is the bit that make it all work. Recall that the "help" EXT configuration calls bash.exe and passes the parameter $FPROG as the name of the script to run. Thus if we select "Users' Help" from CMU $FPROG will be "cmupd" and the command to run becomes

   	bash.exe cmupd
   

The program name can be found by clicking on "Help" and then "Status" on the top menu bar of a APP/Flare programme.

This is the script for cmupd

   #!/bin/bash
   # Name		: help.sh
   # Author	: C W Fulford 
   # Last Update	: 5/4/2006
   # Copyright	: Copyright (c) C W Fulford 2006. All rights reserved
   ###################################################################### 
   PATH=//flare/tools/cygwin:$PATH
   
   # strip off the path to file name
   p=`basename $0`
   
   # the default page is "index"
   if [ $p != "index" ]; then
   	p="help/$p"
   fi

   # Call internet explorer or a web browser of your choice
   "/cygdrive/c/Program Files/Internet Explorer/iexplore.exe"  "http://flare.nottinghamcity.gov.uk/${p}.php"

   # The next line can be enabled for debugging. Just remove the hash (#)
   #echo "/cygdrive/c/Program Files/Internet Explorer/iexplore.exe  http://flare.nottinghamcity.gov.uk/${p}.php" >/cygdrive/c/Flare/FSS/exports/help.out
   

Note that the Cygwin bash script supports the use of the UNC type of PATH. The slashes are the other way round to those used in an MS environment but this is our shared drive once again.

The parameter APP/Flare created from $FPROG will have the value of "Location" prepended. This is the name of the script that bash is running and is the clever bit that makes the whole thing work so easily.

For each web based help page we create, we need another script file identical to the first but with the name given by $FPROG. Using Cygwin we do this by having only one file but with many different names. This is done with the the "link" command. Eg if the original file is called "help"

   	ln help prupd
	ln help cmupd
   

This web page is copyright to Clifford W Fulford and City Linux Ltd 2006. It is reproduced here under a the terms of the GPL .


The layout and associated style sheets for this page are taken from the World Wide Web Consortium and used here under the W3C software licence.