Uploading, compiling and deploying

To create and run a course, you need to go through the following steps:

  • Write
  • Upload
  • Select
  • Compile
  • Test
  • Release
  • (Delete)

The meanings of the steps are pretty much what the words suggest. You write your course in a file. You upload it to the server over FTP. Then you log in to the server and select the course you’re working with. You compile it to find out if it’s correctly written. If it is, you move it to the test area so that you can actually run it. When you’re happy that it’s doing what it’s supposed to do, you release it so that other people can use it too.

Let’s look at these operations one at a time.

Writing

You write your course in a plain text file. If this is your first course, start by copying the toy Hello World example. First, there are a couple of trivial but important things you need to make sure you get right, otherwise the server won’t know what to do with your course. One is file format and the other is directory structure. We’ll talk about those first. Then we’ll say a bit about the actual structure of your course.

File format

You need to write your course in a plain text file which you save with a .txt extension. The simplest way to do this to use WordPad or NotePad.

Note

Don’t use Word, LibreOffice or similar word processing tools. Unless you’re very careful, they won’t save your course in the right format, so the server won’t even be able to read it. They’ll also keep doing things like capitalizing words which really will not help you.

Directory structure

The server expects you to upload directories with a specific structure. If you don’t use this structure, it won’t be able to find your files and it will refuse to accept the upload.

When you were given your account, you’ll have been assigned a namespace along with your userid and password. The namespace is the name of the directory that holds all your CALL-SLT files. When you upload material, you always have to upload a complete namespace directory. Let’s say that your namespace is called mynamespace.

Under your namespace directory, you have one or more course directories. You need one course directory for each course. Let’s say that your course directory is called mycourse.

Under each course directory, you can have up to four directories. These need to have specific names. The only one that’s obligatory is grammars. The directory names are as follows:

grammars
This is going to hold the actual course description file.
multimedia
If you’re using multimedia files (JPEGs, MPEGs or similar), you put them here.
scripts
If you have scripts (see Level 3), they go here.
doc
If you have help files, they go here.

So to sum up, the general directory structure looks like this:

                                       mynamespace
                                            |
                   --------------------------------------------------------------- ...
                   |                             |                   |
                mycourse                    (mycourse2)         (mycourse3)
                   |                             |                   |
   ---------------------------------       --------------       ------------
   |            |         |        |       |       |    |       |     |    |
grammars   multimedia   scripts   doc   grammars  ...  ...  grammars ...  ...

When you start, you’ll probably only have one course with only a grammars directory, so the directory structure will be very simple:

                mynamespace
                   |
          ------------------
          |
        mycourse
          |
   ----------------
   |
grammars

Structure of the course file

Start by looking at the Hello world course file to get a simple example. Here are some specific things to note.

Comments

Lines which start with a hash sign # are comments. They are only there to make the text more readable and explain what things are for. You don’t need to add comments to a course file, but it’s usually a good idea.

For example, the following lines are comments:

# ---------------------------------------------------
# Course

Course declaration

The Course declarations specifies the name of the course and a few things about it, like the language being learned and the student language or languages supported. You must have a Course declaration, otherwise the server won’t know where to put your course.

The Hello World Course declaration looks like this:

Course
Name           hello_world_course
L2             english
Languages      french
EndCourse

Lesson declarations

Since every prompt/response pair belongs to a lesson, you need to define at least one Lesson declaration.

The Hello World Lesson declaration looks like this:

Lesson
Name           hello_world
PrintName      Hello world
EndLesson

Prompts

The main content of the course is in the Prompt units. In a level 1 course, each prompt has a designated Lesson, a piece of Text which is shown to the student, at least one Response, and, optionally, a Group line which gives the order in which the prompts are presented.

The Hello World course is unusual in that it only has a single Prompt. Since there are no other prompts, we don’t need a Group line:

Prompt
Lesson         hello_world
Text/french    Bonjour tout le monde
Response       hello world
EndPrompt

There will be more about the format of course files later.

Uploading

When you’ve written your course, the next step is to upload it. Use FileZilla or some other SFPT client to connect to your upload directory, then drag-and-drop the whole namespace directory from your local machine to the server.

Note

Even if you only want to upload one course, don’t just drag-and-drop the course directory. The server won’t know what to do with it. If you have other courses in the namespace directory that you don’t want to upload, you can copy the namespace directory, remove the other courses, and then upload the copy containing the one course you’re interested in.

Here’s how it works in FileZilla (the details will be slightly different if you use another SFPT client). As an illustrative example, I created a new course called pokemon in the visual namespace. On my machine, the visual directory I’m using is in C:\cygwin64\home\manny\CALLSLTContent, but it doesn’t matter where I have it; the whole point is that I’m immediately going to upload the directory to the server. I start by opening Filezilla and setting the left-hand (local) side to point to C:\cygwin64\home\manny\CALLSLTContent:

_images/Filezilla1Screenshot.jpg

Next, I use the login data I received when I got my account and connect to the server. (The first time you log in you should connect as follows:

Host
sftp://www.issco.unige.ch
Username
your assigned username
Password
your assigned password
Port
22

FileZilla stores this information for you so you can log in next time using the Quickconnect button).

Note

The host URL changed on June 27 2016. If you had an account before that date, you will need to update the information in your FTP client the first time you use it after the change.

After I connect, the FileZilla display looks like this:

_images/Filezilla2Screenshot.jpg

I’m now connected to my home directory on the server, but this isn’t where I’m going to put my data: to get to the right place, I click on the link Call-SLT-data. This changes the remote location to export/data/callslt/manny, which is my CALL-SLT upload directory. Yours will be the same, except that the last bit will be your userid instead of manny:

_images/Filezilla3Screenshot.jpg

Now I grab the folder visual from the lower left-hand panel and drop it into the lower right-hand panel.

Note

There’s an important distinction here between the namespace directory and the FTP upload directory. In this particular case, my namespace directory is visual and my FTP upload directory is manny, so there’s not much chance of mixing them up. But it’s quite likely that you have two directories with similar names; for example, if your name is Frodo Baggins, the FTP upload directory you’ve been assigned is probably baggins and your namespace directory is probably frodo. Remember that they are different: the namespace directory is where you put your course directories on your own machine, and you drag-and-drop it into the FTP directory on the remote machine. As soon as you’ve done this once, it’ll seem obvious.

A lot of stuff happens as FileZilla tells me about all the files it’s uploading:

_images/Filezilla4Screenshot.jpg

When it’s finished, I can see the folder visual displayed in the remote (right-hand) window:

_images/Filezilla5Screenshot.jpg

Just to make sure that my new pokemon course has been uploaded, I click on both windows to see what’s inside the visual folder:

_images/Filezilla6Screenshot.jpg

Good! I can see pokemon on the right, along with visual1 and the other course directories.

Selecting

Having completed the uploading step, you will now have your course material on the server. Next, go to the CALL-SLT Developer page and click on one of the links. They are for different kind of clients, depending on what kind of course you’re working with.

For Level 1 courses, you want the ‘translation game’ client. Log in as yourself (you have to log in as yourself so that the server knows where to look for your uploaded material).

_images/LoginScreenshot.jpg

You will get a dialogue box asking you to give the application access to your camera and microphone:

_images/AllowScreenshot.jpg

Click Allow, and open the Compile & Redeploy tab.

_images/SelectScreenshot.jpg

Now press Refresh to get a tree of namespaces and courses. Select the course you’re currently working with. Let’s say we just uploaded the toy course visual3_course, in the visual namespace.

If your uploaded material is in the wrong form, you may not be able to see it in the tree. In this case, you’ll probably get an error message. Common errors are:

No grammar directory
Your course must have a grammar directory.
Unknown subdirectory in course directory
Your course directory can only have subdirectories called grammar, multimedia, scripts or doc.
Unknown type of file in grammar directory
The grammar directory can only contain plain text files with a .txt extension.
No Course declaration found
A file in the grammar directory must contain a Course declaration.

Here, though, everything is fine and the screen looks like this:

_images/SelectScreenshot2.jpg

Click on the visual node to expand it:

_images/SelectScreenshot3.jpg

and then click on visual > visual3_course > english:

_images/SelectScreenshot4.jpg

You have now selected your namespace (visual), course (visual3_course) and L1 (english).

Compiling

When you’ve selected your course, you next move to the Compile step. Press the Compile button to compile your course; in fact, for technical reasons it compiles the whole namespace that contains the course.

_images/CompileScreenshot.jpg

If things worked, you will get a green border in the feedback panel.

_images/CompileScreenshot2.jpg

If things didn’t work, you will get a red border and you’ll need to look the trace output. This will tell you what went wrong.

Most of the time, it will give you a specific line number in your course file and complain about it, so you need to have some way of editing the file which shows line numbers.

Testing

When you have got your course to compile, you can move to the Test tab:

_images/TestScreenshot.jpg

Here, you will be able to run your course on the Staging Server, accessing it through a browser and testing speech recognition and other capabilities. Pressing the Test button copies your course to the Staging Server, compiles it, and restarts the speech recognition software with your new material added. This takes two or three minutes, and it updates you on how things are going using the progress bar on the bottom right. Again, if everything worked, all the black bars will turn green, and you will eventually will get a green border:

_images/TestScreenshot2.jpg

Note

The Staging Server is intended only for testing purposes, and you should NOT use it for teaching or demoing. The reason is that the compilation and redeployment operation initiated by pressing the Test button takes the whole system offline while the speech recogniser is being restarted, typically for about two to three minutes. Since you are sharing the server with other users who are also developing their own courses, you must be prepared to accept these breaks in continuity.

Releasing

You will usually want to test your course on the Staging Server for a while and fix the various problems that arise. You run it by first going to the Domain tab and selecting your course:

_images/SelectDomainScreenshot.jpg

You can then to Use The Application and try it out:

_images/UseTheAppScreenshot.jpg

You might have to go back to the beginning again a few times to fix things and upload and compile modified versions. When you think your course is working well enough that it’s worth showing to other people, you can move to the final Release tab:

_images/ReleaseScreenshot.jpg

Pressing the Release button copies your course material to the Production Server, which is on a separate machine to the Staging Server.

Note

The Production Server is intended for stable use. Since redeployment takes the server offline for a few minutes, you should not do this often, and you should try to avoid doing it at times when other people might be using the server.

As in the Test phase, the course is compiled and the system is redeployed, and the feedback is similar. If all goes well, things should again turn green:

_images/ReleaseScreenshot2.jpg

Your course is now available for general access.

Deleting

You can delete a course from the Select tab. Go to Select:

_images/Delete1Screenshot.jpg

Switch from ‘FTP’ to ‘Loaded’ and press Refresh to see the loaded courses you control.

_images/Delete2Screenshot.jpg

Select the course you wish to delete.

_images/Delete3Screenshot.jpg

Press Delete and wait. (It takes a minute or so to clean up the tables). Then press Refresh again to check that it’s worked.

_images/Delete4Screenshot.jpg

It should have disappeared from the menu.