Manhattan 3.0 Administrator's Reference
Prev	Chapter 5. Creating Courses - additional details	Next

The Alternative XML format

The format of the roster text file described so far in this manual has been used within Manhattan since 1997. Its origins trace back to an early terminal-based student information system used at Western New England College. In that system, we were able to call up a course roster that would be displayed on the terminal in pretty much the same format as the roster file now supported by Manhattan. A quick "copy and paste" dropped the data into a text file that became input to Manhattan's create-a-course programs. The format continues to be supported, and is a reasonable choice because it's easy to type by hand, or to generate from a student information database.

Starting with version 2.1, Manhattan also supports a more flexible XML based file format for the creation of courses. While this text file format is difficult to type by hand, a capable programmer can write a script to generate the file from a database query. If you're able to find someone to write such a script, the XML format has a number of advantages:

A single XML file can be used to create many courses at a time.
Courses can be created with more than one teacher. While any Manhattan course can have more than one teacher, a limitation of the "legacy" file format is that you can only create the course with a single teacher. You (or that first teacher) must then add the additional teachers using an the "Add a teacher" option on the course's "Configuration menu."
If your student information database contains a username for each student and teacher, you can use that username instead of Manhattan's automatically generated usernames.

What is XML? That's a long story, well beyond the scope of this manual. Suffice it to say that an XML (eXtensible Markup Language) file is a text file marked up with tags enclosed in angle braces like this: <tag>text between the tag</tag>. (XML has some superficial similarities to HTML, the markup language used to create web pages.) One use of XML is to provide a way to move data from otherwise incompatible information systems, for example possibly your school's student information system and Manhattan. Manhattan understands a certain set of tags that must appear in a certain order, which we'll explain by showing you an example.

The XML format by example

Suppose, using the "legacy" roster file format, you're about to create a course on your server. You intend to have Manhattan store the course in:

Course Group: s03
Internal Course Name: phy10101

Both of the above data items are specified on the form you normally use to create courses within the administrative system - see Creating normal courses Here's the "legacy" roster text file you might normally prepare and attach to that same form:

PHY 101 01
Introduction to Physics
Spring 2003
Prof. Einstein
X34322   Albert Einstein
X343888  Neils Bohr
X347332  Isaac Newton
X394032  Michael Jordan

The same course can be described by the following XML file:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>
   <course subdir="s03" id="phy10101">
      <course_no>PHY 101 01</course_no>
      <course_title>Introduction to Physics</course_title>
      <term>Spring 2003</term>
      <teacher_title>Prof. Einstein</teacher_title>
      <users>
        <user id="X34322">
          <first>Albert</first>
          <last>Einstein</last>
          <username></username>
          <group>faculty</group>
        </user>
        <user id="X343888">
          <first>Neils</first>
          <last>Bohr</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X347332">
          <first>Isaac</first>
          <last>Newton</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X394032">
          <first>Michael</first>
          <last>Jordan</last>
          <username></username>
          <group>student</group>
        </user>
      </users>
   </course>
</courses>

Obviously, that is not something a human would type. Using the XML format makes sense only if you can write a program to query your student information system and create the XML file.

Let's begin our analysis of the format with the first line:

<?xml version="1.0" encoding="ISO-8859-1" ?>

The first line of the file identifies it as an XML file and it must be present exactly as it is displayed above. The rest of the file describes the courses you are about to create. The entire body of the file is enclosed between a <courses> and a </courses> closing tag:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>

(XML describing the courses)

</courses>

Theoretically, an unlimited number of courses can be described between the required <courses> and closing </courses> tags. Sandwiched between those tags, a single course's description is enclosed between a <course> and closing </course> pair of tags. (Notice this is singular - the "courses" tags enclose, or contain, "course" tags.) Note in the sample below that the opening <course> tag has two required attributes. The subdir= attribute is used to specify the course group under which this course will reside - see Choosing a group name. The id= attribute is used to specify the internal course name, which is the name of the directory where this course will live on your server - see Choosing an Internal Course Name.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>
   <course subdir="COURSE_GROUP" id="INTERNAL_COURSE_NAME">

      (xml describing this particular course)

   </course>


   <course subdir="COURSE_GROUP" id="INTERNAL_COURSE_NAME">

      (xml describing this particular course)

   </course>


</courses>

Recall that the first four lines of the "legacy" roster text file described the course's course-code-section, it's title, the semester, and the name of the teacher as she prefers to be known within the classroom. The remaining lines described the teacher and students in the class. (See More about the roster text file.) This same information is recorded for each course in the XML version:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>
   <course subdir="COURSE_GROUP" id="INTERNAL_COURSE_NAME">
      <course_no>COURSE-CODE-SECTION</course_no>
      <course_title>COURSE_TITLE</course_title>
      <term>SEMESTER</term>
      <teacher_title>TEACHER_NAME</teacher_title>
      <users>

          (xml representing the teachers and students)

      </users>

   </course>


   <course subdir="COURSE_GROUP" id="INTERNAL_COURSE_NAME">

      (xml describing this particular course - detail omitted for brevity)

   </course>

</courses>

A list of students and teachers goes between the opening <users> and closing </users> tag. The following data is recorded for each user:

Their ID number.
Their first and last names.
Whether they are a student or a teacher.
Their username, if known.

Comparing this to the "legacy" roster file format, you'll notice that in the XML format each user must be identified as either a student or a teacher. In the legacy format, the first person listed was assumed to be the teacher, and there can only be one teacher in the classroom.

Another difference is that the XML format allows you to specify a username for each person. This is of use to you only if your student information system has a username for each student/teacher at your school, or if the script that generates the XML can otherwise obtain a username for each person from another source. If a username is specified, it will be used as the person's Manhattan username. If it is blank, Manhattan will derive the person's username as it normally does - see ID numbers, usernames and passwords

Here's the XML framework again, with the real data we started with added to the data for the first course. Notice that:

The data for each user is enclosed between an opening <user> and a closing </user> tag.
A user's ID number is specified as an id= attribute to the opening <user> tag.
We included the <username></username> pair but with no content between the tags, since we want Manhattan to use its normal method of automatically deriving usernames
The <group></group> tags are used to specify whether a user is a teacher (expressed with the value faculty) or a student (expressed with the value student).

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>
   <course subdir="s03" id="phy10101">
      <course_no>PHY 101 01</course_no>
      <course_title>Introduction to Physics</course_title>
      <term>Spring 2003</term>
      <teacher_title>Prof. Einstein</teacher_title>
      <users>
        <user id="X34322">
          <first>Albert</first>
          <last>Einstein</last>
          <username></username>
          <group>faculty</group>
        </user>
        <user id="X343888">
          <first>Neils</first>
          <last>Bohr</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X347332">
          <first>Isaac</first>
          <last>Newton</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X394032">
          <first>Michael</first>
          <last>Jordan</last>
          <username></username>
          <group>student</group>
        </user>
      </users>
   </course>
   <course subdir="s03" id="eng10101">
      <course_no>ENG 101 01</course_no>
      <course_title>English Composition I</course_title>
      <term>Spring 2003</term>
      <teacher_title>Prof. Fuller</teacher_title>
      <users>
        <user id="X349933">
          <first>Janet</first>
          <last>Fuller</last>
          <username></username>
          <group>faculty</group>
        </user>
        <user id="X348756">
          <first>John</first>
          <last>Narmontas</last>
          <username></username>
          <group>student</group>
        </user>
      </users>
   </course>
</courses>

In the next section, you'll see how you can use the above XML file to create two courses on your server. Before we move on, here's a few additional details about this file format:

ALL of the tags and attributes MUST exist, and be in the relative order shown in the samples above.
All tags must be in lowercase letters.
Only TWO of the tags can be empty - <teacher_title></teacher_title> and <username></username>
- When <teacher_title></teacher_title> is empty, Manhattan will put the title "Prof." before the last name of the FIRST user it finds on the user list, and use that for the "teacher title".
- When <username></username> is empty, Manhattan will use its usual method for automatically deriving a person's username based on their initials and the last 4 digits of their ID number.
Indentation and whitespace outside of tags has no meaning. It is NOT necessary to have your scripts generate neat looking XML code (although the small additional effort is worth the trouble since it makes it easier to debug your script.)

Using an XML file to create courses

The previous section, The XML format by example, describes a text file format that can be used to create Manhattan classrooms. In this section we'll use that method to create two Manhattan courses from a single XML file. Login to the administrative system and click on the Create courses link. Next, click on the Use Alternative XML format button under the form you usually use when you create courses:

This leads to the page:

As shown in the screenshot above, the page consists of two frames. The top frame has a form that allows you to upload an XML file that describes the course or courses you want to create. After the XML file has been uploaded, you can click on the Create courses based on the displayed XML file button to actually create the courses.

The bottom frame displays the contents of the XML file, which is waiting to be processed. When you first visit this page, there won't be an XML file and you'll get the "Couldn't read/open XML file" message shown in the above screenshot.

To demonstrate, copy/paste the following XML into a new file using a text editor on your PC. (If you're reading a printed copy of this manual, visit http://manhattan.sourceforge.net for an HTML version of this manual.) Save the file.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<courses>
   <course subdir="s03" id="phy10101">
      <course_no>PHY 101 01</course_no>
      <course_title>Introduction to Physics</course_title>
      <term>Spring 2003</term>
      <teacher_title>Prof. Einstein</teacher_title>
      <users>
        <user id="X34322">
          <first>Albert</first>
          <last>Einstein</last>
          <username></username>
          <group>faculty</group>
        </user>
        <user id="X343888">
          <first>Neils</first>
          <last>Bohr</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X347332">
          <first>Isaac</first>
          <last>Newton</last>
          <username></username>
          <group>student</group>
        </user>
        <user id="X394032">
          <first>Michael</first>
          <last>Jordan</last>
          <username></username>
          <group>student</group>
        </user>
      </users>
   </course>
   <course subdir="s03" id="eng10101">
      <course_no>ENG 101 01</course_no>
      <course_title>English Composition I</course_title>
      <term>Spring 2003</term>
      <teacher_title>Prof. Fuller</teacher_title>
      <users>
        <user id="X349933">
          <first>Janet</first>
          <last>Fuller</last>
          <username></username>
          <group>faculty</group>
        </user>
        <user id="X348756">
          <first>John</first>
          <last>Narmontas</last>
          <username></username>
          <group>student</group>
        </user>
      </users>
   </course>
</courses>

Now click on the Browse button in the top frame, and use your browser's "find file" dialogs to locate and open the XML text file you just saved. Then click the Upload roster XML file button. The file will be transferred to the server and you'll be returned to the same page, which will look something like this:

Some web browsers, including later versions of Internet Explorer and Mozilla, are "XML-aware". When they encounter an XML file, they generally look for a "style sheet" that tells how to display the data. If there is no style sheet, the raw XML data is displayed in such a way as to show the structure of the XML file. XML-aware web browsers will also tell you whether or not the XML is "well-formed". "Well-formed-ness" is a simple test which checks for example, that there is a closing tag for each opening tag. However, being "well-formed" is not a sufficient condition for Manhattan being able to create courses using the file. The following is "well-formed" XML, for example, but of course it could not be used by Manhattan to create courses:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<lunch>
   <hotdog>yech!</hotdog>
</lunch>

Nevertheless, the ability for XML-aware web browsers such as Mozilla or Internet Explorer to check XML files to see if they are well-formed can be useful when you are first debugging your scripts that generate XML files to create Manhattan courses. The next screenshot shows the results in Internet Explorer when a </course_title> tag was left out of an uploaded XML file:

After uploading an XML file, and verifying that it is at least well-formed, you can click the Create courses based on the displayed XML file button to proceed to the next step:

As shown in the above screenshot, the next step allows you to:

Manually edit the "course group" and/or the "internal course name" for each course represented in the XML file. (See Choosing a group name and Choosing an Internal Course Name.)
Decide whether you want to create a "normal", "standalone", or "course template". (See Normal, Template and Standalone Courses.)

You can combine two courses into one at this point by manually changing both the "group" and the "Internal course name" to be the same. This is useful when a teacher wants two or more sections of the same course in a single Manhattan classroom.

After reviewing and possibly modifying the elements on this form, click the Create these courses button to complete the process. The courses will be created and you'll get a results page listing the courses including a table of teachers and students who were added to the courses.

Skipping the XML Upload step

The previous sections described how to use the alternative XML file format to create new Manhattan courses. One thing that should be clear about the file format is that while it is easy for humans to read, it is not at all easy for humans to type. Use of the XML format makes sense only if you can develop your own programs or scripts to generate the XML file. Typically, these custom programs/scripts will query your student information system to get the required fields such as course title, semester, and information describing each student and teacher in the course.

It is not always convenient to first download a script generated file to your client PC only so you can upload it to Manhattan via the mechanism described above. You can skip the upload step entirely if you can write your script so that it saves the file directly to the tmp directory of your Manhattan installation. The trick is to:

Write the file to the tmp directory of your Manhattan installation. (This is NOT the same as the /tmp that's a standard part of your Unix filesystem - it's a directory named tmp found as something like /home/manhat/manhat.x.x/tmp.)
Name the file CGI_DATA_<YOUR_SUPER_USERNAME>_roster.xml where you replace <YOUR_SUPER_USERNAME> with the username you use to login to Manhattan's administrative programs.
Make sure the apache process (httpd) has read/write access to the file. If you've followed the installation instructions, this can be done by setting the group of the file to www and giving rw- access to members of that group.

After your script directly writes the XML roster file to Manhattan's tmp, directory you can simply click the Use Alternative XML format button from the Create courses page. If you've named the file correctly, the XML file will appear in the lower frame of the page that appears. Simply click Create courses based on the displayed XML file to process the file.

Prev	Home	Next
Name Mismatch	Up	Configure courses - additional details