The Zip Service User's Manual

1 Overview

This article describes how to use the Zip Service. It is intended for users who need an easy way to insert collections of files into a MIRC site.

Some institutions have teaching files kept on a computer system in a tree of directories. At the top level, there may be a directory called "Teaching Files". This directory may contain subdirectories organized anatomically or by subspecialty. Within those subdirectories, there may be additional layers at increasing levels of specificity until at the very bottom, there are directories for individual cases. A case directory may contain files of any kind, including images, text files, article reprints in the form of PDFs, etc.

The Zip Service allows collections of this type to be compiled into a zip file and submitted to the MIRC site, where the Zip Service will unpack the zip file and create a MIRC document for each case. MIRCdocuments created by the Zip Service can be edited using the Author Service, making it an easy way to produce a starting draft for subsequent authoring work.

2 Creating the Zip File

The first step in using the Zip Service is to store all the files for inclusion in MIRCdocuments in directories on your local disk. In the example shown below, many files have been organized into a tree of directories under the top-level directory called Neuro Teaching File.

Error creating thumbnail: Unable to save thumbnail to destination

On a Windows system, the easiest way to construct the zip file to submit to the Zip Service is to drag the top-level folder onto the WinZip icon. This will create a new zip archive and store all the files in it, preserving the directory structure.

The directory structure is important not only because it separates the files into individual MIRCdocuments but also because the title of a document is the name of its directory and the keywords are the names of all its ancestor directories. For more information on how to use this capability, see Advanced Topics.

3 Submitting the Zip File

To submit a zip file to the Zip Service, go to the query page of a MIRC site and select the storage service to which you wish to submit the file. Then click the Zip Service button on the query page. The Zip Service requires authentication, and the user must have the author role on the storage service to be allowed to submit a zip file.

After authentication, you will see a form like the one below.

Error creating thumbnail: Unable to save thumbnail to destination

The author's name, affiliation, contact information, and username are pre-loaded with the information known to the Author Service, but you can change it in the Zip Service form without changing the data in the Author Service.

If you wish to make several users owners of the documents to be produced, enter their usernames in the owners field.

In each of the permissions fields, enter any of the following:

• If you want non-authenticated users to have a permission, enter an asterisk in the field.
• If you want to restrict a permission to owners of a document, make the field blank.
• If you want to restrict a permission to specific classes of users, enter the roles associated with those classes in the field. Consult your MIRC administrator to find out the names of the roles that have been defined on your system.
• If you want to restrict a permission to specific individuals, enter their usernames in the field, enclosing each username in square brackets, e.g. [...].

You can combine usernames and roles in a single field, e.g., staff,resident,[jones],[smith].

For a discussion of the use of the Text file extensions and Skip file extensions fields, see Advanced Topics.

When you have filled out the form, click the Browse button on the Select the zip file line. In the file chooser which appears, navigate to the zip file, select it, and click OK or Open, depending on your computer. Then click the Submit button at the bottom of the form. The browser will send the zip file to the Zip Service, which will unpack it and start a background process to create MIRCdocuments for all the files it contains.

Depending on the load on your MIRC site and the size of the zip file, it can take from several seconds to several minutes to produce the MIRCdocuments. Since the process occurs in the background, you are free to continue interacting with the MIRC site or doing other work with your browser. You will not receive any notification that the process has finished; the documents will just appear in the index as they are created.

4 Advanced Topics

4.1 Using the folder hierarchy to create keywords

In the MIRCdocument created for a directory, the Zip Service inserts the names of all the ancestor directories in the keywords section. By naming the directories in the tree appropriately, as shown in the example in the "Creating the Zip File" section, you can create meaningful keywords.

4.2 Sending only part of the folder hierarchy

If you have a large number of directories and files and you wish to submit only part of it, you can simply create a zip file starting at the top-level folder of the section that you wish to submit. This has the unfortunate consequence of omitting the folders above that level, making their names unavailable as keywords. If you want to prevent this loss, you can do the following:

Drag or place the entire directory tree in the root of a disk drive. For example, if you have the folder tree stored on your desktop as shown in the example, move it to the root of the "C" drive. Navigate to the place in the folder hierarchy which you wish to select as the root of the submission and drag it onto the WinZip icon. In the WinZip dialog, check the "Save full path info" checkbox.

This will include only the selected files, but it will include the names of all their ancestor directories, allowing the Zip Service to create the full set of keywords.

4.3 Text files

The Zip Service checks each file that it adds into a MIRCdocument to determine whether it is a text file. The test simply compares the last part of the filename with the list of extensions specified in the "Text file extensions" field on the submission form. The default extension is .txt. If, for example, you have some text files in the folder hierarchy with extensions .text, you can add this extension to the list by changing the field to .txt,.text.

Text files must contain true character text information without the formatting that is associated with word processors.

For each text file, the Zip Service will copy its contents into the "Notes" section of the MIRCdocument, thus making it visible to the reader as well as making it discoverable in a query.

4.4 File types

Any file that is determined to be an image is put into the image section of the MIRCdocument. Any file that is determined to be a text file is processed as described above. A link to every non-image file is added to the "Files" section in the MIRCdocument, allowing all such files (including text files) to be downloaded. This is especially useful for preprints in PDF format, but it is useful for all file types.

4.5 Document templates

The Zip Service uses a default template for the format of each MIRCdocument it produces. The template file is stored in the MIRC site's storage service. You can override this template by creating your own and including it in the zip file. A Zip Service template must be named template.xml. While processing a zip file, if the Zip Service encounters a template.xml file, it uses that template for the current directory and all directories below it in the hierarchy.

For information on creating templates, see MIRC Templates.