README - ChemSense Server

This document contains instructions on how to run and administer your ChemSense Server, as well as technical notes regarding how you can hook up different databases to your server, if desired.

The ChemSense Server installer will install the ChemSense server application on your computer. The server requires Java 1.4 or higher be installed (separately) in order to run, and at least 256 MB of RAM is recommended.

When the installer prompts you for the location to install, you should change the default path to choose a path with no spaces, for example "C:\ChemSenseServer" (i.e., remove "Program Files" if it is in the path). (One of the open source packages used by the ChemSense server has difficulty with spaces in the pathname.)

Testing Your ChemSense Server with a ChemSense Client

Once you have installed the ChemSense server, you can test it with a ChemSense Studio Client as follows:

  1. Run the ChemSense Server (e.g., double-click the startChemSenseServer icon on the desktop, or the httpd.exe or script in the server bin directory). If you are running the server on Mac OS X, you may want to install Script GUI which allows you to run shell scripts from the finder.

  2. Launch the ChemSense Client (download the ChemSense Studio Client if you have not already).

  3. In the client, click the Options button in the login panel and enter the URL of the ChemSense server. For example, if you are running the ChemSense Server on the same machine as the ChemSense Studio Client, the URL would be:
    If you are running the server on a different computer than the client, substitute the server computer's IP address or domain name for "localhost", above.

  4. Login with the guest account:
    username: guest1
    password: guest
  5. When you are done, log out of the client and then, shut down the ChemSense server.

Administering Your ChemSense Server

The ChemSense Server provides a web interface, called the ChemSense Web Gallery, that allows you to view student work from a web browser, create student groups and individual and batch accounts, manage those accounts, and view aggregate data (e.g., number and types of items, number of comments made, number of logins and most recent login, etc.) by individuals and groups. Students can also log in to the ChemSense Web Gallery to view and comment on each others' work.

To access the administrative functions of the server:

  1. Run the ChemSense Server (e.g., double-click the ChemSense Server icon.

  2. Launch a web browser and enter the URL of the ChemSense server. For example, if you are running the ChemSense Server on the same machine as the web browser, the URL would be:
    If you are running the server on a different computer than the browser, substitute the server computer's IP address or domain name for "localhost", above.

  3. Login with the administrator account:
    username: Admin
    password: (blank)

The first thing you should do is reset the Admin password. To do so, locate the "Logged in as Admin" text on the upper right area of the web browser page, click on "Admin", click on "Change password", and enter a new password. If you forget this password you will not be able to administer the ChemSense server in the future, so chose something you will remember or record the password in a secure location.

Next, explore the interface. At the top of each web page, you will see the word Viewing:" followed by one or more (hierarchical) group names. The group "ChemSense" is the root group of all groups, and hence will always appear beginning of all of the breadcrumb links. Each group name that follows is a subgroup of the previous group in the list. You can use this "breadcrumb" list to navigate up the group hierarchy. When you first set up your server, if you view the ChemSense group, you will see that it has one member, "Admin," and one subgroup, "DemoGroup". If you click on DemoGroup, you will see that it has one member, "guest1."

One of the first things you may want to do is create user accounts. Before you do so, a word about groups. Users reside in groups, and each group may contain one or more users. Actually, each user has what is called a "primary group" and a "root group". A user's primary group is where her account resides. Her root group is the outermost group under which she has permission to see work by others, and is the group that is first displayed when the user logs in. A user's primary group must be either the same as, or reside hierarchically underneath, the root group. For most users, their primary group and root group are the same. That is, their account resides in a particular group, and they can see work only by others in that group. However, you can change a user's root group to allow that user to also see work by users outside of her primary group. For example, suppose a teacher creates a group called "Chemistry classes", and then creates 3 subgroups of this group, called "Period 1", "Period 2", "Period 3", and then creates 20 student accounts inside of each "Period X" group. If she wants her students to only see work by other students in their period, she would make the primary and root groups for each student the same. (This is the default.) However, if instead she would like the students to be able to see work by students in other periods as well, she would make each student's root group the group"Chemistry classes".

Now you're ready to create a new group for a new set of accounts. Navigate to the "ChemSense" group and click the "Create new subgroup" link. Give it a name, nickname, and description/purpose, and click Create Group. The next page you see will be the home page for your new group. From this page you can create individual accounts ("Create new user") one by one, or several accounts at one time ("Create multiple student accounts"), for example, for a whole class. In either case, you will be prompted for user information, and in the case where you create multiple accounts at once, you can elect to have the system generate passwords for you. When you have the system generate passwords, be sure to print the page with the passwords or copy and paste the contents into a file for later reference, because the system will not be able to tell you passwords later. They are encrypted for security reasons and cannot be retrieved after they are generated. If you forget the passwords for any accounts you create, you will need to edit the account (click on the account name) and then change the password for that account (Change password link).

Once you have created your accounts, the next step is to provide the usernames and passwords to the intended users, point them to the ChemSense web site to download the ChemSense Studio Client or install it for them on your classroom computers, and tell them what URL to enter into the ChemSense client Options panel (see above) in order to save and access their work on your ChemSense Server. You may also want to give them the URL to your ChemSense server so that they can log in to change their password, and see and comment on other student's work through the web interface as an alternative to doing so through the ChemSense Client. Students will not be able to access the administrative functions above (such as creating groups or users). Only the Admin account has access to administrative functions.

Note that your ChemSense server must be running for others to use the ChemSense Studio Client, so if you plan to create and distribute user accounts, you may need a dedicated server, that is, one that is always running and accessible at an permanent (non-dynamic) URL address.

Technical Notes

The ChemSense Server is a three-tier application based on the free, open-source Expresso framework, which in turn is based on Apache Struts and uses Java Server Pages technology for the rendering layer.

Expresso includes an object-to-relational layer that permits developers to easily use different databases with the application. The database that comes with the ChemSense server is the free, open-source Hypersonic SQL (hSQL) database. If you would like to change the underlying database for your server, the configuration is in expresso-config.xml and full instructions and sample configurations for all major databases are available at the Expresso web site.

Contact Information

ChemSense software was developed as part of a non-profit research project and is licensed for evaluation purposes only, without warranty. The ChemSense project ended in 2004 and no longer provides technical support. However, the ChemSense source code is available under an open source license. Feel free to extend the code to meet your needs.

Copyright Notice

ChemSense and other material included in the ChemSense distribution are Copyright 1999-2008 SRI International.