 |
| |
 A publication of the Information Development department
Vol 3, Issue 3
July 2003
 Editors' messageThe summer is now upon us and many of you are, no doubt, busy upgrading your systems and organizing accounts, especially education sites. Even though your energies may be directed elsewhere, we encourage you to browse through the new customer support home pages on the FirstClass web site. In this new setup, you will find
• a search-based portal that can be broken down into the various FirstClass product areas (FirstClass Server, IS, VS, Designer and Client)
This portal was created using the FirstClass search capabilities. You'll find articles written by technical support staff on various topics as well as 7.1 documentation in this portal.
• a list of links to help you administer your site
• access to the latest FirstClass software patches and versions
• an overview of the various ways and times to reach support.
Take a tour; we know you will find it useful.
In this issue
With the recent release of the FirstClass server for Mac OS X, many people are looking for information on how to migrate their FirstClass environments from Mac OS 9 to Mac OS X, as well as how to use FirstClass on this new platform. To help you with your transition, we have put together a couple of articles we hope will address some of your questions and introduce some new Mac OS X concepts.
Additionally, we have included an article outlining what you get for your current Maintenance and Support contract, an article on the new Hold and Release backup feature, and advanced batch administration instructions. Also included are our regular informative sections to help you better administer your site.
Enjoy this issue!
Editors
Annette Ferron
Ann Schwartz
 Contents Why migrate your FirstClass server from Mac OS 9 to Mac OS X? Mac OS X conceptsFirstClass Maintenance and Support Frequently asked questions How can I save the contents of my FirstClass address book for use in other programs? What rules does FirstClass use to determine how the "Name" field is shown in the Mailbox? My licenses are on a diskette and my server machine doesn't have a disk drive. What do I do? Tech tipSnapshot Hold and Release
 ToolsBatch admin master class
 In future issues...What to look for in future issues of the FirstClass Newsletter
 We still want to hear from youFeedback? Questions? Topic ideas?
 Contact information ResourcesNew training courses and where to find documentation
 ArchivesWhere to find previous newsletter issues
 Subscribing/UnsubscribingSubscribe other members of your organization
 Copyright noticeWhy migrate your FirstClass server from Mac OS 9 to Mac OS X?Thanks to all for the enthusiasm and interest you've shown in the recently released FirstClass 7.1 server for Mac OS X. Interest is so high that many of you are considering migrating from Mac OS 9 to Mac OS X and want to understand the benefits, and any differences, associated with such a migration. The purpose of this article is to detail that information for you and help you make your decision.
How does the FirstClass server for Mac OS X compare with the FirstClass server for Mac OS 8/9 in general?
The FirstClass server for Mac OS X is up to date with the 7.1 service pack level of the other servers and has the same features as the FirstClass server on Mac OS 9. It runs on both OS X and OS X server machines, and works well in a mixed environment.
What are the main benefits of migrating to FirstClass for Mac OS X?
All FirstClass server installers (Windows, Mac OS 9, and Mac OS X) are fast and easy to use. The FirstClass for Mac OS X installer asks only a few questions and provides default answers for everything, including system-specific questions like the address of the DNS server to use.
Some UNIX features make the FirstClass server for Mac OS X an easier FirstClass system to administer on an ongoing basis. For example, UNIX operating systems directly support remote system access right out of the box via several means, including secure shell (SSH). Selecting the Remote Login option in Apple menu > System Preferences > Sharing enables remote administration of the FirstClass server machine from any machine that can make a network connection to it. The FirstClass services for Mac OS X also support shell-based administration of the server, using the new fcsctl and fcisctl commands.
There are also performance and scalability benefits to migrating to FirstClass for Mac OS X. Performance of the FirstClass server is enhanced on Mac OS X because it uses worker threads to make asynchronous system calls that don't block the core server thread and spread the load across multiple native system threads. The native UNIX calls are expected to perform better than Mac OS 9 calls because they are based on a more complete, advanced operating system offering better system services, caching, and so on. A key benefit of the advanced features with Mac OS X is the preemptive multitasking operating system, as compared with Mac OS 9's voluntary task switching.
Along with preemptive multitasking, Mac OS X has full protected address spaces and support for multiple processors (SMP), enhancing both reliability and scalability. The FirstClass server for Mac OS X will run more smoothly and more reliably with less interference from other programs. For example, on Mac OS 9, if a program crashes it can bring down the whole system. On Mac OS X, this same program crash will not affect other processes because the processes are protected from each other. Further, the limited capacity of FirstClass on Mac OS 9 to 100-250 sessions, due to limitations of the operating system, does not exist with FirstClass on Mac OS X. Finally, if you have a dual processor machine, the FirstClass server for Mac OS X can take advantage of that to increase both scalability and performance.
How does FirstClass for Mac OS X differ from FirstClass on Mac OS 9?
Because the FirstClass server for Mac OS X was developed for an entirely new platform, some aspects of the server differ from the FirstClass server on Mac OS 9, and some features of the FirstClass server for Mac OS 9 are no longer supported in the FirstClass server for Mac OS X. Most of these features have already been replaced, or will be replaced, by alternative, updated features in future releases. For example, the FirstClass server for Mac OS X does not open a window, so there is no console window or server menu. There is still support, however, for a console log, and the functionality provided by the console and menus will be replaced with a more flexible mechanism in a future release. One of the benefits that administrators will receive in exchange for this temporary limitation is the ability to configure the server and Internet
Services to load in the background as system services prior to a user login.
More information
For further discussion about migrating your system to Mac OS X, future migration from other platforms, and other information about FirstClass 7.1 for Mac OS X, see Server and UNIX Team Leader Paul Whittemore's pages on our website. You can also look at the other article in this issue on Mac OS X concepts.
Mac OS X conceptsThe introduction of Mac OS X brings with it some new concepts, including the power of UNIX shell scripting and logical FirstClass volumes. This article discusses these two new concepts and provides examples of each.
Shell scripting
UNIX shell scripting allows custom scripts to run before or after key events in the startup or shutdown of the FirstClass server. A shell script is a set of commands executed by the operating system's shell. Shell scripts can be as small and simple as a single command, or they can perform complex tasks using many lines of code. Shell scripts are written in a syntax similar to, and with many features in common with, programming languages.
The FirstClass server for Mac OS X works with user-defined add-on scripts that are executed during the FirstClass server startup and shutdown. The scripts and the instances when they are executed are:
• /Users/fcadmin/Documents/bootfcsd start
runs prior to starting the server system daemon (at system boot time)
• /Users/fcadmin/Documents/bootfcsd stop
runs after stopping the server system daemon
• /Users/fcadmin/Documents/prefcsd start
runs prior to starting the server during an "fcsctl start"
• /Users/fcadmin/Documents/postfcsd start
runs after starting the server during an "fcsctl start"
• /Users/fcadmin/Documents/prefcsd stop
runs prior to stopping the server during an "fcsctl stop"
• /Users/fcadmin/Documents/postfcsd stop
runs after stopping the server during an "fcsctl stop"
• /Users/fcadmin/Documents/bootfcisd start
runs prior to starting Internet Services system daemon (at system boot time)
• /Users/fcadmin/Documents/bootfcisd stop
runs after stopping Internet Services system daemon
• /Users/fcadmin/Documents/prefcisd start
runs prior to starting Internet Services during an "fcisctl start"
• /Users/fcadmin/Documents/postfcisd start
runs after starting Internet Services during an "fcisctl start"
• /Users/fcadmin/Documents/prefcisd stop
runs prior to stopping Internet Services during an "fcisctl stop"
• /Users/fcadmin/Documents/postfcisd stop
runs after stopping Internet Services during an "fcisctl stop".
You can place any scripts to be used in /Users/fcadmin/Documents/. Since the scripts may contain passwords used for accessing a network server, a private user folder is used as the location for the scripts.
Each of these scripts can be modified to suit your site's requirements. Some typical uses for shell scripts are to mount and unmount network volumes, and to perform basic log file management. Experienced UNIX users may wish to create more complex shell scripts to accomplish specific tasks.
Example FirstClass Server shell script
On Mac OS X, volumes are normally mounted at login and the FirstClass server is usually configured to launch at system startup. Therefore, the FirstClass server may be unable to access the networked volume. The solution we recommend is to modify your server's prefcsd shell script to mount the volume before the FirstClass server starts. Similarly, you can modify the postfcsd script to unmount the volume after the server shuts down.
The prefcsd and postfcsd shell scripts below demonstrate mounting and unmounting a network volume using the mount_afp command.
Note
In this example, you want to use a post office located on a network volume.
Prefcsd script
# Local machine variables
MOUNTPOINT="/Users/fcadmin/MountFolder"
FCVOL="MyVolume"
# Network file server variables
USERID="userid"
PASSWORD="password"
FILESERVER="server"
FILESERVERVOL="volume"
if [ "$1" == "start" ] ; then
mkdir -p "$MOUNTPOINT"
echo "Mounting '$FILESERVER/$FILESERVERVOL' as Master volume..."
/sbin/mount_afp "afp://$USERID:$PASSWORD@$FILESERVER/$FILESERVERVOL" "$MOUNTPOINT"
ln -s "$MOUNTPOINT/Users/userid/FolderWithFCPO" "/Library/FirstClass Server/Volumes/$FCVOL"
fi
Postfcsd script
#!/bin/sh
# Local machine variables
MOUNTPOINT="/Users/fcadmin/MountFolder"
FCVOL="MyVolume"
if [ "$1" == "stop" ] ; then
echo "Unmounting Mirror volume..."
rm "/Library/FirstClass Server/Volumes/$FCVOL"
/sbin/umount "$MOUNTPOINT"
rm -rf "$MOUNTPOINT"
fi
All about logical FirstClass volumes
The FirstClass server for Mac OS X introduces the new concept of logical FirstClass volumes. Since there is only one root file system on UNIX machines, another mechanism must be used to differentiate between volumes on an OS X machine.
The Mac OS X operating system resolves this problem by mounting volumes under a /Volumes path. The FirstClass server could use this list directly; however, that would remove the flexibility of allowing you to control what volumes are visible to FirstClass administrators who can open the FirstClass Volumes list. This is important both for security and performance.
Instead, the FirstClass server allows you to define an explicit list of volumes accessible to the server. These need not correspond directly to physical drives, but in fact could simply be folders or symbolic links to any location visible in the Mac OS X file system hierarchy. They are referred to as logical volumes.
Within the FirstClass Server folder under /Library, there is a subfolder called Volumes. Any folder (or symbolic link to a folder) found under the Volumes folder is considered to be a logical FirstClass volume, and will show up in the FirstClass Volumes list on the FirstClass administrator's Desktop.
In addition to the obvious use of being able to refer to multiple specific physical drives from FirstClass, logical FirstClass volumes can be used to partition users and/or conferences into logical groups (for example, a separate logical volume for Internet newsgroups). These groups can later be split into separate physical devices, if desired, simply by making the folder a link to another location in the file system and moving the existing files to that location instead.
Logical volumes also allow multiple former Mac OS 9 server volumes to be merged onto one or more physical drives simply by putting the post offices in separate folders under the Volumes folder.
And finally, using logical volumes leverages one of the greatest strengths of UNIX-based systems: the logical union of different objects under the single umbrella known as the root file system. Defining a FirstClass volume as either a folder in the file system or a link to an arbitrary location in the root file system allows the FirstClass administrator maximum flexibility.
Creating logical FirstClass volumes
Your post offices can be located wherever you choose. To add a new post office volume to the list of volumes accessible inside FirstClass, you can either place the actual directory tree inside a folder under /Library/FirstClass Server/Volumes, or you can create a symbolic link inside /Library/FirstClass Server/Volumes to the location of your post office volume using the ln -s command.
Note
Finder-created aliases cannot be substituted for symbolic links created using ln -s. Finder-created aliases are simply files and are not a UNIX-style symbolic link. UNIX file system calls handle symbolic links automatically, but aliases are not handled automatically.
Example
In this example, a secondary post office volume is located under /Volumes/HD2/. It must be located in a folder named FCPO. The FCPO folder and all of its subfolders must be real folders and cannot be symbolic links or Finder aliases.
To make this post office available to FirstClass you need to create a logical FirstClass volume using a symbolic link. In this case, if you wanted to add it as a secondary FirstClass volume by the same name, you would open a terminal session while logged in as fcadmin and type:
ln -s "/Volumes/HD2" "/Library/FirstClass Server/Volumes/HD2"
The HD2 volume will now be available to FirstClass.
If instead this volume represented the primary post office volume, it should be linked as "Master", regardless of its actual physical volume name:
ln -s "/Volumes/HD2" "/Library/FirstClass Server/Volumes/Master"
FirstClass Maintenance and SupportNormally, we try to restrict newsletter articles to technical issues. But some admins have told us they're being asked about the value of our Maintenance and Support contracts by their superiors - or at least by the folks who sign the cheques. So we thought you might find it valuable to have the answer documented here. Purchasing a Maintenance and Support contract gives you: technical support, access to the worldwide FirstClass community, fast access to new products as they are released, and input to future releases and the features they will include.
Access to technical support
With a Maintenance agreement we offer unlimited technical support to our registered FirstClass administrators for the term of the contract. This one-to-one support is offered by our technical support team who can be reached via phone and email. If they cannot answer a question or fix your problem immediately, and most of the time they can, they will get assistance from the product development team. Check out the Support page on our website for hours of operation and some useful resources. Every year, when your maintenance contract is renewed, you
can be assured that this support will be there for you.
Involvement in the FirstClass community
We also offer access to a community of FirstClass users and administrators through FirstClass Online (FCOL). Here you have at your fingertips some of the most knowledgeable administrators in the world who regularly participate in conferences, provide advice, ask questions, and share opinions. FCOL contains valuable conferences as well as archived software. Some examples of FCOL conferences include "Enhancement Suggestions" (a forum for administrators to suggest new FirstClass features and enhancements to existing features) and "FirstClass Admins" (a forum for administrators to discuss FirstClass with
fellow admins). For those of you in the Education Sector, there is "Educational Connections" (a forum for educators to discuss how they are using FirstClass products in their classrooms). These conferences are easily searchable and contain years of collective experience. They are sources of information and an effective communications tool for customers to provide input and guidance on the development of the FirstClass product.
Fast product access
Perhaps one of the greatest advantages of Maintenance, however, is your access to the product itself. As stated in our Product Roadmap (found in the last newsletter Volume 3, Issue 2), our goal is to provide one major release and one minor release each year and our record over the past few years supports this. Maintenance is the way to ensure that you are always current with these releases and are able to take advantage of the new features and enhancements as soon as they are available. Some examples of what was made available with 7.1 include
spam management, easy to use but powerful mail rules (both articles can be found in Volume 3, Issue 1), and enhancements to the web interface. Also, as the roadmap for FirstClass Release 8.0 reflects, there are many more powerful features and enhancements to come. As a Maintenance member you are automatically notified of the new release availability. You can then request the appropriate license key be sent to you so you can download the latest version at your convenience.
Making the future
FirstClass features are the result of years of listening to customer input, not just through research studies but daily communications through customer support, sales and FCOL. As a member of the Maintenance program you have a voice in the FirstClass community and input into the product you own. In the more than 13 years since FirstClass 1.0 we have continually worked to improve and enhance the features and functionality of FirstClass. This constant evolution is something we are dedicated to and we look to the involvement of our community of FirstClass Maintenance customers to achieve it. You purchased FirstClass not just for its current features, but for the future it promises. Buying, installing, and disseminating a software package is a huge investment of time, money, and effort. You do this not just for immediate benefits, but
because you believe the product will grow as you grow, meeting your future needs. By purchasing a Maintenance contract, you acquire the ability to influence the future of the product and the direction in which it develops.
Conclusion
In summary, your Maintenance contract buys you technical support, access to an invaluable knowledge repository, opportunities to interact with your FirstClass peers, input to product direction, and the latest release of FirstClass. If you don't purchase a Maintenance and Support agreement, you will not be able to get technical support from FirstClass (there is no alternative method), you will not have access to the worldwide FirstClass community (only registered administrators get accounts with the appropriate privileges), you will not receive automatic notification of new releases and will have to pay for them, and you will not have input into the future direction of FirstClass.
If you would like to contact someone today about renewing your Maintenance agreement please call us at 1.888.808.0388 or email sales@firstclass.com.
Frequently asked questionsHow can I save the contents of my FirstClass address book for use in other programs? Open the address book and right-click the column headings. This will bring up a list of fields that you can include or exclude as columns. Select/deselect fields to get the columns you want. Then, choose Save As... to save the list as a tab-separated text file. You can open the file in a text editor to remove the header lines. What rules does FirstClass use to determine how the "Name" field is shown in the Mailbox? The Name field is taken directly from the From and/or Reply-to message headers, so it's totally dependent on the format of the address from the sending mailer. If the sending mailer uses quotes, so does the FirstClass message envelope. If it uses parentheses, so will the FirstClass message envelope. My licenses are on a diskette and my server machine doesn't have a disk drive. What do I do? You need to use electronic licenses, which are files encoded with the license information and the server's serial number. There is no way to create an electronic license from your diskette license. To obtain an electronic license contact your sales representative.Tech tip: Snapshot Hold & ReleaseThe new snapshot hold and release feature is designed to hold the FirstClass server in a consistent state, take a snapshot of the post office, and release the server back into normal operating mode. Once the hold has been initiated, the server will not respond to any operations except the corresponding snapshot release request until the hold has been released manually or the allotted time has expired.
Many FirstClass servers use external disk devices for storage of the FirstClass content. Some of these devices, such as NetApp Filers, offer what is referred to as a snapshot facility. Other backup solutions, such as those from Compaq or EMC, offer similar features to provide very fast backups of large amounts of data. In some cases this capability is known as a "split mirror", although that form can take slightly longer to create than the copy-on-write alternative used in NetApp snapshots. There are also software-based "instant backup" solutions, such as BackupExec's "Advanced Open File Option" (see this PDF).
In FirstClass terms, a snapshot is any mechanism (typically provided by a network file server) that enables near-instant flagging of the current state of a file system for later retrieval. This does not need to correspond directly to the snapshot services provided by a NetApp, however it is not suitable for use with a traditional backup due to the time required for the backup copy process. The only FirstClass requirement is that this snapshot process take no more than a few seconds to complete (the default is 60 seconds). The hold operation must be quick because the server process is effectively blocked during the snapshot hold operation, and all requests are deferred until the snapshot release. This permits the snapshot hold to be requested, the snapshot to quickly be taken, and the snapshot release to be requested, allowing the server
to function normally while the backup process begins in parallel. This allows you to do an online backup of your FirstClass server without having to worry about open files or mirroring.
You can invoke the hold and release feature in one of two ways: through the server console menu or through batch admin:
Server console menu
This method uses the server console menu (Storage > Snapshot Hold). When you choose this, you are requesting a snapshot hold and the snapshot backup is taken. A few seconds later you request the snapshot release (Storage > Snapshot Release). The server console below shows what happens:
 If the release had not been requested, the server would have automatically resumed normal operations one minute after the hold request was made.
Batch admin
The second method uses the new batch admin commands, HOLD and RELEASE, through the FirstClass Provisioning Protocol (FPP).
To request a HOLD, use this syntax:
HOLD OptionalHoldTime
where OptionalHoldTime is the total amount of time, in seconds, until the server will release itself. If not specified, the default is used.
To request a release, use this syntax:
RELEASE
The following result shows both a default (60 seconds) hold request, as well as a timed hold (30 seconds):
 The server console logs these FPP requests.
 Tools: Batch admin master classIn the last newsletter, we looked at batch admin from a beginner's point of view. Now we will look at it from the perspective of an experienced batch admin user. We'll explore ways of using field substitution and exporting content to streamline your administrator tasks.
Introduction
Wouldn't it be wonderful to be able to perform multistep procedures just by filling in a simple form and hitting the send button?
For example, you could:
• create classroom conferences for resources and student collaboration
• create a Portfolio folder where each teacher can develop their classroom material, store files, save favorite web resources, and record feedback
• populate a teacher's Home Page Folder with documents and images.
Before you can jump into performing multistep procedures in one step, though, you'll need to invest time in creating a custom form and a batch admin script. Once the initial work is done, though, multistep procedures can be completed in seconds.
Recommended experience level
If you can create a simple form with FirstClass Designer and you understand how to write a path, you are well on your way. Now you need to learn about the ENABLEFIELDSUBSTITUTION command and how to create one-step EXPORT commands. Once these two commands are mastered you too can claim your batch admin crown.
Field substitution
We're all familiar with a spreadsheet's ability to create formulas using cell addresses instead of values. ENABLEFIELDSUBSTITUTION provides the ability to use field IDs in a script instead of specific parameters.
For example, to create a conference called Power Presentations within the General Conferences folder, you used to issue the command:
NEW "general conferences" "Power Presentations" "" conference 8 -1 -1 +p
Now you can do it using just a form like the one below and the ENABLEFIELDSUBSTITUTION command.
 The editable field labeled "Conference Name" has a field ID of 1001. Now, with field substitution, the commands are:
ENABLEFIELDSUBSTITUTION
NEW "general conferences" "#1001" "" conference 8 -1 -1 +p
When "Power Presentations" is entered into the Conference Name field, the server preprocesses the command and automatically substitutes the contents of field 1001 for the #1001 found in the command. Once the message is sent, a new conference called Power Presentations is created in the General Conferences folder.
Field types to use with field substitution
Editable fields are an obvious choice for this process, but icon fields, number fields, and editable selection lists are also handy. The following form illustrates the use of these fields with field substitution:
 This form uses an icon field ("Choose an icon") to choose the icon for a new conference (field ID 1004), a number field ("Sample Number") to set the location of a new conference (field IDs 1007, 1008), and an editable selection list ("Choose a background") to present a list of suitable images from the Resource Registry (field ID 1006).
Remember, with an editable selection list, although the form may display a selection when it is first opened, you need to explicitly select something from the list. Until you change the selection list, the displayed default value is not saved and the command will not work as desired. Also, an editable selection list does not update automatically; you manually have to add new images to the list.
Caution
Be aware of which commands are based on a user ID and which are based on the user name. The user name is used in the Permissions form, or in the To, Cc, or Bcc fields. CHGALIAS also uses the user name. Most other commands use the user ID.
Exporting in one step
In the past, you've likely used EXPORT in two steps: first, you specify what to export, and second, you add the destination when the script is returned. However, now you can complete the EXPORT command in one step.
Example: populating users' Home Page Folders
To export the contents and view properties of a folder within General Conferences called Home Page Contents to the Home Page Folder of sbram, you used to issue the command:
EXPORT "general conferences:home page contents" +r
You would then replace <ObjDesc> in the returned script with:
desktop sbram "home page folder"
Now you can accomplish the same thing in one step using the following syntax:
EXPORT path address BatchAdminPassword ObjDesc +b
So, to export the contents of "Home Page Contents" to sbram's Home Page Folder in one step, the command is:
EXPORT "general conferences:home page contents" "batch admin" "" desktop sbram "home page folder" +br
The password is left blank because the message is created from the admin account and subadmins cannot use the EXPORT command. The ObjDesc is written without quotation marks, just as it is in the two step process. The +b option will process the script immediately and +r is the recursive option. We could have also added -v to the command if the view properties weren't relevant or desired.
Combining ENABLEFIELDSUBSTITUTION and EXPORT
Now we'll put ENABLEFIELDSUBSTITUTION and EXPORT together in one message in the following example.
A teacher needs to be added to a user group in order for his or her home page to be accessible to nonauthenticated users. The user group has the Home Page Folder on the Model Desktop. Further, a set of helpful documents including preset links and school branded graphics needs to be added to the teacher's Home Page Folder.
The form will include a field to enter the user ID. The field has been assigned an ID of 1201.
 The body of the message contains the following script:
enablefieldsubstitution
//add user to the Home Page Users group
pgadd "#1201" "Home Page Users"
//add documents to user's home page folder
EXPORT "general conferences:home page contents" "batch admin" "" desktop "#1201" "home page folder" +br
Caution
When combining exports and other commands, remember that the server performs the export as it is encountered and then continues onto the next command. If a subsequent command is dependent on exported objects, there is no way to ensure that the objects exist before the command is completed. Both of the examples below deal with this issue.
Examples
The following two examples will help you gain confidence with performing field substitution and exporting content in one step. Feel free to follow along with an Intro server. The first example deals with creating a conference for every teacher, and the second deals with creating a new user with all sorts of customization to the user's Mailbox and Desktop.
Example One: Creating a classroom conference
George Armstrong is the administrator at Avalon Academy. He needs to create a classroom conference for Ms. Susan Bram.
George must do the following to this conference:
• create it based on the teacher's name, Ms Bram's Classroom
• create it in a folder called Classrooms within the General Conferences folder
• set all the view properties and split screens
• set permissions so the teacher is Controller of the conference, employees and students have Contributor access, and all others are Disallowed
• place it in an exact location on the teacher's Desktop and protect the alias
• add a chat and a small set of folders
• add a folder called Classroom Home Page
• link the folder named Classroom Home Page to the WWW folder, and rename the alias to identify the teacher
• include a group calendar and set the permissions
• add it to a User Group and define an organization unit.
George will complete all of the above steps by filling in three fields on a custom form.
This example breaks George's work into five steps:
STEP ONE: Create the necessary user groups and source areas for the exports
STEP TWO: Generate the permissions part of the script
STEP THREE: Assemble the permissions scripts and complete the script
STEP FOUR: Create a form, add the script, and test the process
STEP FIVE: Test for errors
STEP ONE: Create the necessary user groups and source areas for the exports
With the client:
1 George creates a user group called Classroom Conference and sets the Organization unit field to Department.
2 He creates a folder called Classroom Showcase within the Internet Services/WWW folder and sets the folder to display by list.
3 He creates a folder within General Conferences called Classrooms and places an alias of the folder in the Student Area conference.
4 He creates a folder within General Conferences called Master Conference, and within this folder he creates all the subfolders, chats, and documents that need to be in the Classroom conference, and sets the view properties of the Master Conference and all the subfolders.
This is the Master Conference folder:
 Notes
• The Master Conference does not contain the Classroom Home Page folder; George needs to alias this folder to the WWW folder. There is no way to ensure that the import is complete before the server tries to execute the command to link the folder.
• George doesn't create the group calendar within the Master Conference folder. The calendars will need unique names so George will create them using the NEW command.
STEP TWO: Generate the permissions part of the script
George knows that unless he has the field values for the permissions memorized, it's much faster to use the EXPORT command to obtain the field values, particularly if custom permissions are required. George uses test conferences to generate the permissions part of the script.
1 George creates a conference called Permissions Test, and sets the access levels as follows:
Susan Bram: Controller
Employee: Contributor
Student: Contributor
All Users: Disallowed
2 He creates a group calendar called Group Calendar Test.
He sets the access level of Employee and Student to Schedule + Details, then adds Download and Open items.
 3 To determine the permissions of the conference and the calendar, he sends the following commands:
EXPORT "general conferences:conference test" +np
EXPORT "general conferences:group calendar test" +np
4 Within the returned script, he locates the permissions for the conference:
Put Permissions Relative "Permissions Test" 29 0 "Susan Bram" 131071
Put Permissions Relative "Permissions Test" 29 1 "Employee" 122624
Put Permissions Relative "Permissions Test" 29 2 "Student" 122624
Put Permissions Relative "Permissions Test" 29 3 "All Users" 0
For efficiency, he reduces the four lines to one. With ENABLEFIELDSUBSTITUTION, the path and the teacher's name will be replaced by variables, so the script becomes:
Put Permissions "General Conferences:Classrooms:#1000's Classroom" 29 0 "#1001" 131071 29 1 "Employee" 122624 29 2 "Student" 122624 29 3 "All Users" 0
He doesn't want to use the teacher's first name, so the conference will be called Ms Bram's Classroom. In the script Ms Bram is represented by the #1000 variable.
The Permissions form uses the user name, Susan Bram. In the script this is represented by #1001.
5 Within the returned script, he locates the permissions for the group calendar:
Put Permissions Relative "Group Calendar Test" 29 0 "Susan Bram" 2219821
Put Permissions Relative "Group Calendar Test" 29 1 "Employee" 2121472
Put Permissions Relative "Group Calendar Test" 29 2 "Student" 2121472
Put Permissions Relative "Group Calendar Test" 29 3 "All Users" 0
With ENABLEFIELDSUBSTITUTION, the path and teacher's name will be replaced with variables, so the script becomes:
Put Permissions "General Conferences:Classrooms:#1000's Classroom:#1000's Calendar" 29 0 "#1001" 2219821 29 1 "Employee" 2121472 29 2 "Student" 2121472 29 3 "All Users" 0
The only exporting he needs to do is to recreate the structure of the Master Conference to the teacher's new classroom conference The only variable required is the name of the new conference, which is represented by #1000.
EXPORT "general conferences:Master Conference" "batch admin" "" "General Conferences:Classrooms:#1000's Classroom" +br
STEP THREE: Assemble the permissions scripts and complete the script
In this step George writes the script that assembles the permissions scripts and then completes the script. The LINK USER command requires the user ID, represented by #1201.
//Note: User must exist before running this script.
ENABLEFIELDSUBSTITUTION
//create conference within General Conferences/Classrooms
NEW "General Conferences:Classrooms" "#1000's Classroom" "" Conference 8 -1 -1 +p
//sets permissions (Teacher Controller, Employee & Students Contributor, All Users Disallowed)
Put Permissions "General Conferences:Classrooms:#1000's Classroom" 29 0 "#1001" 131071 29 1 "Employee" 122624 29 2 "Student" 122624 29 3 "All Users" 0
//ADD conference TO Classroom Conference group
PGADD "#1000's Classroom" "Classroom Conference"
//create a new calendar
NEW "general conferences:Classrooms:#1000's Classroom" "#1000's Calendar" "" CONFERENCE 24011 325 50 28 +p
//create Classroom Home Page folder
NEW "general conferences:Classrooms:#1000's Classroom" "Classroom Home Page" "" Folder 26093 127 74
// set permissions of calendar, teacher Editor, Employee and Student Sch_Details +, All Users No Access
Put Permissions "General Conferences:Classrooms:#1000's Classroom:#1000's Calendar" 29 0 "#1001" 2219821 29 1 "Employee" 2121472 29 2 "Student" 2121472 29 3 "All Users" 0
//add contents from Master Conference set properties and splits
EXPORT "general conferences:Master Conference" "batch admin" "" "General Conferences:Classrooms:#1000's Classroom" +br
//put new conference on user's desktop - uses field 1201
LINK USER "#1201" "General Conferences:Classrooms:#1000's Classroom"
//protect and place conference on user's desktop - uses field 1201
PUT PROPERTIES DESKTOP "#1201" "#1000's Classroom" 1016 6 1 1306 14 400 1307 14 75
//link the General Conferences / Classrooms / teacher's Classroom / Classroom Home Page to the
//Internet Services / WWW / Classroom Showcase folder.
LINK PATH "internet services:www:classroom showcase" "general conferences:classrooms:#1000's classroom:classroom home page"
//rename folder to teacher's name
rename "internet services:www:classroom showcase:classroom home page" "#1000s Classroom"
STEP FOUR: Create a form, add the script, and test the process
 1 George creates a new form as a user form in the Local Form range (above) and adds fields 1001, 1001, and 1201 to the form. He uploads the form to the administrator's Desktop, double-clicks the attachment and updates the resources.
2 He chooses the new form from Message > New Message Special.
3 He adds the script to the body.
4 He fills in three variables and sends the message to batch admin.
5 He reviews the results and makes any adjustments.
STEP FIVE: Test for errors
In Step Four, George made sure everything was working as planned. Now he purposely tries to create errors. For example, he enters a nonexistent user ID, and creates a situation where the conference and calendar names are duplicates. The understanding of what can go wrong and how to fix problems helps him build confidence in the procedure.
When writing scripts, George sometimes forgets to enclose variables within quotation marks. Therefore, he always tests variables with an entry of more than one word. In this situation, he tests that the script still works if the user ID field contains sbram ps17.
Try it yourself
Teachers transfer, retire, marry and divorce. While this new knowledge is fresh in your mind, write a script that will remove the conference, calendar, and web page alias and another script that renames the objects.
Note
If the script appends container names with a suffix, remember to subtract the suffix from the current character limit of 32. When creating the form in Designer, consider setting a maximum value for the editable fields, or at the very least adding a comment to the form as a reminder of the limit.
Something to think about
Think about all the steps necessary to create a conference: protecting the conference, choosing an icon, setting view properties, setting permissions, adding the conference to a group, and so on. If you can identify a pattern, you can streamline the process. Perhaps more important than saving the two minutes though is the consistency of never missing a step.
Example Two: Creating a new user and performing customization
George creates most of his accounts through batch admin, so when he creates an account manually, it's a struggle to remember the group names and other internal procedures. In this example, George works through the steps necessary to create user accounts so that he doesn't have to go through this exercise again.
George plans to do the following:
• create a new user
• add a mail alias
• place Teachers in the School, Employee, and Faculty groups; place Students in the School and Student groups; and place School Support staff in the School, Employee and School Admin groups
• set Desktop backgrounds, all of different sizes
• create a folder called Working Area on the user's Desktop
• set the Mailbox view properties and create two folders: Spam and Archived Messages
• add two mail rules for each user
• add home page content to the user's Home Page Folder
• place a protected Acceptable Use Policy document on the user's Desktop.
Sneaky George trick
When exporting in one step, the server will send a message when the script has completed. In this example, George's Mailbox would quickly fill with these replies. So George creates a mail rule to file the messages in a folder.
This example breaks George's work into five steps:
STEP ONE: Create the resources necessary for the exports
STEP TWO: Write the script to add the rules to each user's Mailbox and test the export commands
STEP THREE: Create the script to add the user and set the alias, and assemble the rest of the script
STEP FOUR: Create the form and test the script
STEP FIVE: Test for errors
STEP ONE: Create the resources necessary for the exports
Within General Conferences, George creates the following resources:
• three folders
He sets the view properties based on three different Desktop backgrounds.
• an unprotected folder called Working Area
He sets the view properties, chooses an icon, and creates an About this Area document. He places the folder in the same location as it should be placed on the user's Desktop.
• a folder called Mailbox Master
He sets the view properties and creates a subfolder called Friends & Family.
This is the Mailbox Master folder:
 • a conference called Rules Test
He adds the two rules needed by the user.
• a folder called Home Page Contents
He creates a generic Personal Web Page.
• a folder called Acceptable Use Policy.
He creates a document containing the policy.
STEP TWO: Write the script to add the rules to each user's Mailbox and test the export commands
George writes the section of the script that will add the rules to each user's Mailbox and test all the export commands.
1 George sends the following command to construct the rules part of the script:
EXPORT "general conferences:rules test" +ne -v
2 He locates the part of the script that creates the rule:
New Relative "" "File Conference Mail" "" FormDoc 23047 112 15 23 23 -U
Put Previous 8120 7 1252 8140 0 8141 0
Put Previous 9 "" -T
Put Previous 13801.0 7 1 13810.0 7 11 13806.0 7 21 13821.0 7 2 13830.0 7 1 13832.0 0 "archived messages" -T
// Reference: 1:11262
New Relative "" "Spam Rule" "" FormDoc 23047 194 15 23 23 -U
Put Previous 8120 7 1252 8140 0 8141 0
Put Previous 9 "" -T
Put Previous 13810.0 7 29 13821.0 7 23048 13807.0 7 0 13810.1 7 29 13821.1 7 23049 13830.0 7 1 13832.0 0 "Spam" -T
He only needs the NEW command and the PUT command that populate the form. He also adds the RULES keyword so the rules are active immediately. The only variable is the user ID (#1201), so the commands become:
New DESKTOP "#1201" Mailbox "File Conference Mail" "" FormDoc 23047 112 15 23 23 -U
PUT RULES desktop "#1201" mailbox "File Conference Mail" 13801.0 7 1 13810.0 7 11 13806.0 7 21 13821.0 7 2 13830.0 7 1 13832.0 0 "archived messages" -T
New DESKTOP "#1201" Mailbox "Spam Rule" "" FormDoc 23047 194 15 23 23 -U
PUT RULES desktop "#1201" mailbox "Spam Rule" 13810.0 7 29 13821.0 7 23048 13807.0 7 0 13810.1 7 29 13821.1 7 23049 13830.0 7 1 13832.0 0 "Spam" -T
The mail rules require the existence of two folders: Spam and Archived Messages. George must make sure the folders are created before the mail rules are added. He can't depend on the EXPORT command to do this because there is no way to guarantee that the export will be complete before batch admin gets to the part of the script that contains the mail rules commands.
Now he needs to compose and test all the other export commands.
3 He exports the view properties from the three different Desktop folders:
EXPORT "general conferences:teacher desktop"
4 He locates the section of returned script that sets the view properties:
Put Relative "" 900 0 901 200 902 451 903 582 904 992
Put Relative "" 13000.0 122 0007000500100009000C000A000C0007008200060028000800DC00020064 -S
Put Relative "" 13075.0 7 -1 13016.0 7 0 13015.0 0 "" 13065.0 14 -2147483646 13062.0 7 15 13063.0 7 15 13064.0 7 0 13074.0 7 2 13084.0 7 1 13053.0 7 0 13003.0 7 24 13082.0 7 112 13083.0 0 "wwfcdesktop.jpg"
5 He changes the first line (the size and location of the window) to include a variable for the user ID. The path to the Desktop is set by using the empty quotation marks.
Put desktop "#1201" "" 900 0 901 200 902 451 903 582 904 992
6 He changes the last line (the view properties) to include a variable for the user ID. The path to the Desktop is set by using the empty quotation marks.
Put desktop "#1201" "" 13075.0 7 -1 13016.0 7 0 13015.0 0 "" 13065.0 14 -2147483646 13062.0 7 15 13063.0 7 15 13064.0 7 0 13074.0 7 2 13084.0 7 1 13053.0 7 0 13003.0 7 24 13082.0 7 112 13083.0 0 "wwfcdesktop.jpg"
7 He repeats the process for the other two sample Desktop folders.
8 Next he wants to export the Working Area folder to the user's Desktop. Again, the only variable is the user ID. He completes the command in one step. The +n option will create a folder on the user's Desktop in the same location as the folder with General Conferences:
EXPORT "general conferences:working area" "batch admin" "" desktop "#1201" "" +nb
9 He creates the Mailbox view properties and the folders with the following command (+r will recreate the subfolder within Mailbox Master):
EXPORT "general conferences:Mailbox Master" "batch admin" "" desktop "#1201" "mailbox" +rb
10 He creates the folders for the mail rules:
NEW desktop "#1201" "Mailbox" "Archived Messages" "" Folder 13303 42 9
NEW desktop "#1201" "Mailbox" "Spam" "" Folder 23048 46 61
The user's Mailbox now looks like this:
 11 He populates the Home Page Folder from the Home Page Contents folder:
EXPORT "general conferences:home page contents" "batch admin" "" desktop "#1201" "Home Page Folder" +rb
12 He use the -v option to eliminate the view properties from the folder containing the Acceptable Use Policy. Without the -v, the view properties from the folder would be applied to the user's Desktop.
EXPORT "general conferences:Acceptable Use Policy" "batch admin" "" desktop "#1201" "" +b -v
STEP THREE: Create the script to add the user and set the alias, and assemble the rest of the script
All that is left to be done is to create the script to add the user and set the alias and assemble the rest of the script. George will set up the custom form to reuse the field IDs from the User Info form.
Sneaky George trick
George has memorized a number of field IDs (for example, 1201 is the user ID field), so he assigns the fields the same IDs. He finds that scripts are easier to write and read if he uses field IDs that already mean something to him. This also allows him to copy fields from the standard forms in Example.fc.
ENABLEFIELDSUBSTITUTION
//create new network user
add network "#1201" "#1202" "#1203" "#1204" "" "#1217" "" "" "" 3 "#1006" "#1007" "#1008"
//add the alias(es)
put user "#1201" 1252 0 "#1252"
//set view properties
EXPORT "general conferences:Mailbox Master" "batch admin" "" desktop "#1201" "mailbox" +rb
//folders must exist before the addition of rules
NEW desktop "#1201" "Mailbox" "Archived Messages" "" Folder 13303 42 9
NEW desktop "#1201" "Mailbox" "Spam" "" Folder 23048 46 61
//set Desktop size and position
Put desktop "#1201" "" 900 0 901 200 902 451 903 582 904 992
//set view properties including background image
Put desktop "#1201" "" 13075.0 7 -1 13016.0 7 0 13015.0 0 "" 13065.0 14 -2147483646 13062.0 7 15 13063.0 7 15 13064.0 7 0 13074.0 7 2 13084.0 7 1 13053.0 7 0 13003.0 7 24 13082.0 7 112 13083.0 0 "wwfcdesktop.jpg"
//add Working Area folder to user's Desktop
EXPORT "general conferences:working area" "batch admin" "" desktop "#1201" "" +nb
/set view properties and add folder to user's Mailbox
EXPORT "general conferences:Mailbox Master" "batch admin" "" desktop "#1201" "mailbox" +rb
//add contents to user's Home Page Folder
EXPORT "general conferences:home page contents" "batch admin" "" desktop "#1201" "Home Page Folder" +rb
//add AUP to user's Desktop
EXPORT "general conferences:Acceptable Use Policy" "batch admin" "" desktop "#1201" "" +b -v
//Add 2 mail rules to user's Mailbox
New DESKTOP "#1201" Mailbox "File Conference Mail" "" FormDoc 23047 112 15 23 23 -U
PUT RULES desktop "#1201" mailbox "File Conference Mail" 13801.0 7 1 13810.0 7 11 13806.0 7 21 13821.0 7 2 13830.0 7 1 13832.0 0 "archived messages" -T
New DESKTOP "#1201" Mailbox "Spam Rule" "" FormDoc 23047 194 15 23 23 -U
PUT RULES desktop "#1201" mailbox "Spam Rule" 13810.0 7 29 13821.0 7 23048 13807.0 7 0 13810.1 7 29 13821.1 7 23049 13830.0 7 1 13832.0 0 "Spam" -T
STEP FOUR: Create the form and test the script
 George begins by testing the script against a teacher account. Once the tests are complete, he creates stationery for each of the three user types, and adjusts the script to include the appropriate Desktop image. He changes the NEW command to accommodate the different number of groups for each user type.
 STEP FIVE: Test for errors
1 George creates a user with a duplicate user ID and makes note of the error message on the Server console.
2 He creates a user with a duplicate name and makes note of the error message on the Server console.
3 He tests each of the variables to ensure that the script contains appropriate quotation marks.
4 He confirms that the view properties are appropriate for a Desktop.
Next time a user is added he'll be assured that all the steps are completed. In the past, the extra steps of creating folders and setting custom backgrounds likely added too many manual steps to the process. But now, once the script is written, it's no extra work at all. Instead of exporting all of the source folders every time a user is created, the returned script can simply be adjusted and added to the message body.
The "one step export" has the advantage that the script does not need to be adjusted every time a new requirement is added. For example, if a third folder needs to be added to the new user's Mailbox, George can simply create it in the Mailbox Master folder; the script needs no adjustment.
Try it yourself
For extra credit, or if you're quite mad, combine example one and example two.
In future issues...Certain features mentioned here may not yet be released, and may not be currently available in all geographic regions. Open Text Corporation reserves the right to modify or cancel any features mentioned here.
• FirstClass site case studies
• Directory syncing over FirstClass gateways
• Outbound Call Detail Recording in Voice Services
We still want to hear from youShare your thoughts and ideas
Do you have additional knowledge to share? New information or handy tricks to reveal? Please send them to us. In addition, send us questions you want answered by developers and technical staff, suggestions for articles and content, queries about how to perform tasks that may make your job easier, and general comments about our newsletter.
We are always looking for feedback on our documentation. If you would like to contribute any ideas or comments, please email FirstClass ID.
Site visits
The Information Development team conducts site visits to gain feedback from administrators and users of FirstClass. Previous visits have proved successful, and were found to be mutually beneficial. If you would like to schedule a site visit at your company, send us an email (currently in the Greater Toronto area only*).
*If you are outside of the Greater Toronto Area, we can organize a teleconference so you can still take advantage of the benefits these meetings provide.
Please send all correspondence to the TechNewsMail conference (TechNewsMail@firstclass.com).
Contact informationEditors: Ann Schwartz, Annette Ferron
TechNewsMail@firstclass.com (TechNewsMail conference)
sales@firstclass.com (Sales)
support@firstclass.com (FirstClass Customer Support)
Please send all correspondence to the TechNewsMail conference (TechNewsMail@firstclass.com).
Main number: 905.762.6000
Main fax number: 905.762.6151
Toll-free number: 1.888.588.3444
Our address is:
Open Text Corporation
FirstClass Division
38 Leek Crescent
Richmond Hill, ON
Canada, L4B 4N8
ResourcesDocumentation
Looking for new documentation? Existing documentation? Check out Documentation on our web site.
Check our online help for copies of the documentation that correspond to your server version.
Training
The Richmond Hill office holds customized training courses throughout the year. For a training schedule or course descriptions, including prerequisites, see Training on our web site. If you have any questions, please address them to FirstClass Training or training@firstclass.com.
ArchivesPrevious newsletters can be found at Welcome to The FirstClass Newsletter on our web site.
Subscribing/UnsubscribingWe want this newsletter to reach all of the people in your organization who will directly benefit from it. If you would like to subscribe anybody else to this newsletter, please provide us with their email address or FirstClass account. Enter SUBSCRIBE as the subject line.
If you would like to unsubscribe to this newsletter, send us an email with the subject line UNSUBSCRIBE.
Please send all correspondence to the TechNewsMail conference (TechNewsMail@firstclass.com).
Copyright noticeInformation in this document is subject to change without notice. Certain features and products described in this document may not yet be released, and may not be currently available in all geographic regions.
All rights reserved. FirstClass is a registered trademark of Centrinity Inc. The FirstClass logo is a trademark of Centrinity Inc. All other trademarks are property of their respective owners.
This document is bound by international copyright law and the FirstClass Software License Agreement and Limited Warranty included with every FirstClass product.
Copyright 2003 by Open Text Corporation.
|