Extending Internet Services with scripting
Extending Internet Services using CGI and ISAPI applications
 NoteCGI and ISAPI scripts are discussed only as they relate to FirstClass. There is no discussion of how to develop applications in any scripting language.
You can extend your site's functionality and make it more dynamic by adding scripting capabilities. Internet Services supports two types of scripting applications:
• Common Gateway Interface (CGI)
• Internet Services API (ISAPI - Windows only).
In both cases, you must have any scripting language (for example, Perl or PHP), in which you create and run an application, already installed on your machine. For example, if you use a recent version of ActiveState Perl distribution, you will see a Perl directory in the root of your C: drive, and the full path to the Perl executable will be c:\Perl\bin\perl.exe.
There are three things you must do to use both types of applications in FirstClass:
• create an application
• place the application in the appropriate place on your hard disk
• add a link to the application to access it, on any HTML document on your website.
The cgi-bin folder
You must place all CGI or ISAPI scripts in the cgi-bin folder for them to work. The cgi-bin folder (an external folder) is located in the same folder as the Internet Services executable and is not created by default, so you must create it. You can also have subfolders separating scripts into different categories, depending on the complexity of the script. Also, if you have two scripts with the same name, you must place them in different subfolders within the cgi-bin folder.
Internet Services also supports a cgi-win folder for executables that conform to the WinCGI protocol (for example, Visual Basic applications). The cgi-win folder is also an external folder that is not created by default, so you must create it in the same location as the cgi-bin folder. Since this folder exists on your Internet Services machine, not in the Internet Services folder on the administrator’s Desktop, only a user with access to your physical machine can add or remove executables.
Using Common Gateway Interfaces (CGIs)
While HTML allows you to create only static content, CGI applications allow you to create active content. For example, you can create interactive forms, such as web counters, or continuously update fields, such as date fields.
You can write a CGI script in any language that will create an executable object on your system. For example, C++, Visual Basic, or Perlscript on Windows and C or C++ compilers on Mac OS X (or any compiled or scripting language that supports read/write standard input and standard output).
Before you begin, verify that there is a directory named "cgi-bin" located in the same directory as the Internet Services executable, and create it if it doesn't exist. This is where your Perl script(s) will be located.
Basic CGI syntax
To use the CGI, simply call it from your HTML document using this syntax:
• /cgi-bin/executable-name?arguments
or
• /cgi-bin/foldername/executable-name?arguments.
where
• cgi-bin is the folder name
• foldername a subfolder name
• executable-name the name of your cgi executable
• arguments any additional arguments attached to the cgi executable
You can place a link on a web page to the executable file.
Adding a CGI script
To add a CGI script:
1 Create a cgi-bin folder in the same folder as the FirstClass server and Internet Services executable files.
2 Create a folder in the cgi-bin folder for your CGI script files.
3 Install all the CGI files in this folder.
4 Follow the information contained in the CGI ReadMe to configure your executable.
5 Add a link to your company home page (or any other HTML document on your website) using the line of code provided in the CGI ReadMe document.
6 Log into your website and test your CGI executable.
You can use the Aliases document, described below, to hide the CGI script files from the browser.
Using Internet Services APIs (ISAPIs)
 WindowsISAPI lets you develop web-based applications that run faster than conventional CGI programs because they're more tightly integrated with Internet Services. This allows you to use dynamic web applications (also called scripts) to enhance your FirstClass system. You can write an ISAPI script in any language that will create an executable object on your system. For example, C++, Visual Basic, or Perlscript on Windows.
The primary difference between an ISAPI program and a CGI program is that an ISAPI program remains loaded in the server after it has first been loaded in memory. Conversely, a CGI program is loaded into memory after each application request from the user's web browser, then unloaded from memory once the programs have been executed. This means that ISAPI programs tend to run faster than CGI programs.
Using the AddHandler document
The AddHandler document determines how to run additional programs in response to special HTTP requests handled by Internet Services. There are two ways of defining how to associate web requests with programs: file associations and Content-Type associations. The file associations specified in this document override any file associations that are set up by the operating system. Content-Type associations work by comparing the Content-Type header in each HTTP request against the values specified in this document, instead of the file extension at the end of the request URL.
The AddHandler document is both helpful and necessary because:
• some interpreters do not automatically set up file associations when installed
• some operating systems do not have an easy way of maintaining file associations
• some types of HTTP requests can handled without having to create dummy documents in the cgi-bin folder.
The AddHandler document is located in the Internet Services folder on the administrator's Desktop and is automatically created when you do a new install or when you upgrade. This document supports two different commands: AddHandler and AddURLHandler. Each command spans multiple lines, with comments and blank lines allowed for documentation and readability. Lines within each command do not have to be specified in a particular order.
This is the syntax for the AddHandler command:
<AddHandler .ext>
Site: sitename or *
If-Content-Type: MIME type/subtype
ISAPI.Ext: full path of ISAPI dll to load
exec: full path of CGI to run
Custom-Header: header identifier: header string
</AddHandler>
where
• ext is the filename extension to handle. Examples: .php and .pl.
• .sitename or * works the same as in the Multiple Sites & Languages form and other configuration documents
• MIME type/subtype is the Content Type to match in HTTP requests
For example
application/vnd.syncml+wbxml
The If-Content-Type is optional and, if specified, overrides the value of .ext. In this case, we recommend that you set .ext to .dummy as a documentation aid.
• ISAPI.Ext is used to run ISAPI extensions (as opposed to ISAPI filters, which are not supported.)
• exec is used to run executables and is an alternative to having to create file associations in Windows. It is also used for running different types of scripts (for example, PHP) where that isn't possible.
• Custom-Header is used to return a custom HTTP header in the response to an HTTP client. Example: Custom-Header: X-SpecialHeader: This is a special header.
Note
Either ISAPI.Ext or exec may be used in a single AddHandler command, but not both.
This is the syntax for the AddURLHandler command:
<AddURLHandler /URL/goes/here>
Site: sitename or *
Templates: template folder name
HTTP-Response-Code: HTTP code
</AddURLHandler>
When Internet Services receives a request for /URL/goes/here that matches the site, it uses the template folder specified to process the request.
HTTP-Response-Code lets you specify an HTTP response code either to alter the response code sent with a redirect or to force a particular error page return for a specific URL. Possible values for the HTTP code are:
301 |
Moved Permanently |
302 |
Found |
303 |
See Other |
307 |
Temporary Redirect |
or any other valid HTTP error code.
The AddURLHandler command is intended to allow Internet Services to easily provide different views of parts of a website. For example, online newspapers and other websites devoted to dynamic information may use Rich Site Summary (RSS) instead of HTML to deliver the content. An RSS reader can be directed to a different set of templates instead of the HTML set.
This command can also be used to simplify configuring CalDAV and CardDAV client connections. Users only have to specify a domain name or IP address, plus user ID and password. They don't have to enter URLs.
 NoteThis will only work for some clients. Others must be manually configured to point to https://domain name/Login/Calendar/ or https://domain name/Login/Contacts/. If SSL is enabled, https:// is required because some clients can't redirect from http:// to https://
To enable this simplification, add these entries to the AddHandler document:
<AddURLHandler /.well-known/caldav>
Site: *
Rewrite: /Login/Calendar/
HTTP-Response-Code: 301
</AddURLHandler>
<AddURLHandler /.well-known/carddav>
Site: *
Rewrite: /Login/Contacts/
HTTP-Response-Code: 301
</AddURLHandler>
<AddURLHandler /principals/>
Site: *
Rewrite: /Login/
HTTP-Response-Code: 301
</AddURLHandler>
<AddURLHandler ~ /principals/users/(.+)/>
Site: *
Rewrite: /Login/
HTTP-Response-Code: 301
</AddURLHandler>
<AddURLHandler /dav/principals/>
Site: *
Rewrite: /Login/
HTTP-Response-Code: 301
</AddURLHandler>
<AddURLHandler /calendar/dav/(.+)/user/>
Site: *
Rewrite: /Login/Calendar/
HTTP-Response-Code: 301
</AddURLHandler>
Using the Rewrite command
You can use the Rewrite command to:
• support complex CGI applications (for example, Perl/PHP scripts that provide web log Blog functionality) without you having to extensively edit CGI files to change URLs.
• invoke different template sets to provide additional views on conferences and folders.
This is the syntax for the Rewrite command:
<AddURLHandler [~] /URL/>
Site: sitename or *
Templates: Template folder name
Content-Type: <Mime Type of the content the ISAPI extension returns>
Index: alternate name for the Index page
Rewrite: /replacement URL/
</AddURLHandler>
where
• the optional character [~] indicates the /URL/ is a regular expression that includes the use of tags
• Content-Type is normally set by the CGI or ISAPI extension and the default is text/html.
However, if the Content-type is not the default or, for the URL handler, if you use alternate templates that do not return text/html, specify the Content-type so the browser will correctly interpret it.
• Index allows the use of differently named Index files when /URL/ refers to a container
• Rewrite allows you to redirect the browser to a different location, similar to Location: header used by CGIs
As an example, if you want to provide your users with an RSS view of a News conference on your site you could add this AddURLHandler syntax to the ISAPI document:
<AddURLHandler ~ /News/rss>
Site: *
Templates: .rsstemplates
Content-Type: <the Rich Site Summary (RSS) content type>
Rewrite: /News/
</AddURLHandler>
If you have an URL that is a regular expression that uses tags, you can specify the tagged text in the replacement URL. This is useful if you want to make part of the URL space 'virtual' on your site:
<AddURLHandler ~ /Mobile/(.*)>
Site: *
Templates: mobile.templates
Rewrite: /\1
</AddURLHandler>
Using the Aliases document
You can use the Aliases document to run different scripts from your web server while hiding the paths from users.
Note
While the Aliases document is supported, the AddHandler document is generally preferred as it is more flexible and has more features.
The purpose of the Aliases document is to:
• install a CGI written for a different web server (for example a CGI written for an Apache server) where you don’t have access to the CGI source files or they are too complex to modify
For example, you may have a CGI written in a programming language such as C or C++, and you only have the executable (.exe) file. Or a CGI is written in Perl and you are not a Perl programmer.
• trigger CGIs and hide them behind virtual names
This allows you to hide the source of the CGI and even the fact that you are running CGIs on your system.
• hide or change URLs.
This allows you to change the name of a publicly accessible conference on your FirstClass system. You may want to provide an alias of the old name to the new name, for people who have bookmarks or to support requests made through search engines.
The Aliases document is not a standard item on your system. You must create it in the Internet Services folder on the administrator’s Desktop.
Basic Aliases document syntax
The basic syntax of each line in the Aliases document is:
keyword website URLpattern URLreplacement
where
keyword is the word that begins the code line (for example, ScriptAliasMatch or Alias)
website is either * to indicate all web sites (or the only site if the Multiple Sites & Languages form is not used), or a web site alias optionally followed by a period and a language
URLpattern describes the URL to match (depending on the keyword)
URLreplacement substitutes (internally) for the requested URL if the pattern matches
In all cases, the link in the browser will show the URLpattern, and navigate to the URLreplacement.
Both URLpattern and URLreplacement are case sensitive (and are regular expressions for AliasMatch and ScriptAliasMatch).
Code lines can start with either the ScriptAlias or ScriptAliasMatch keyword, to trigger CGI processing and Alias and AliasMatch keywords for all other HTTP requests.
URLpattern must be enclosed in double quotes (") if it contains spaces or one or more of the following characters:
< > " # { } | \ ^ [ ] ' ` +
In addition, the characters for double quote (") and backslash (\) must be preceded by a backslash (\). For example, /URL with " double quote and \ backslash/ would be inserted in URLpattern as:
"/URL with \" double quote and \\ backslash/"
Hiding a CGI path on a web page
To create an alias to a CGI executable:
1 Create an Aliases document in the Internet Services folder containing the following code, on one line:
ScriptAliasMatch * /[Ll]inks/ /cgi-bin/folder/executable.pl/arguments
where
[Ll]inks is the regular expression to match the link name: Links or links
folder is the name of the CGI folder in the cgi-bin folder
executable.pl is the CGI executable name
arguments are any additional arguments required for the CGI executable (if applicable)
Note
If you don't need to use regular expressions, use ScriptAlias.
2 Close the document.
3 Click Refresh on the Control - General tab of the Internet Services Monitor, to update your changes, or wait a couple of minutes for changes to load automatically.
You do not need to restart Internet Services.
When a browser requests the URL /Links (or /links) from your server, the request is changed internally to /cgi-bin/folder/executable.pl/arguments and the CGI is run as if the requested URL was entered as /cgi-bin/folder/executable.pl/arguments.
Changing a URL to a publicly accessible conference
You can hide or change URL paths to publicly accessible conferences on your FirstClass system.
For example, on the Husky Planes web site we have a conference called Sold Product Customer Support for the different models of planes we sell. We are now moving to a lease-only model for our company. However, we still want to provide support for our customers who have bought our products in the past. Because of our new business direction, the FirstClass administrator has to move the Sold Product Customer Support conference inside another conference called Old Product Support. Since most customers who require customer support have the original conference URL bookmarked in their browsers, we must ensure they can still reach it without having to change their bookmark.
To solve this problem, Husky Planes’ administrator created an alias of the URL /Sold Product Customer Support to the URL /Old Product Customer Support in the Aliases document. Following the basic Aliases document syntax, keyword website
URLpattern URLreplacement, she entered this line in the Aliases document:
AliasMatch * "^/Sold Product Customer Support/" "/Old Product Support/Sold Product Customer Support/"
The above line of code reroutes customers using their old bookmarks to the new location of the conference.
| 
