noah nwnw5

rev:2012/11/18

Users Help Manual

Contents

... Users Frequently Asked Questions: FAQ

What is NOAH?
Quick Start ...
Meta-data
Select Action Buttons:

[Info] field - edit/display meta-data
Searching
Show Recent Changes
Special File Icons
DokuWiki Links
File and Directory Permissions
Admin Group Privileges
File and Directory Locking
Email Notification Option
Client Scripting Option


What is NOAH ?   (top)

Nordicwind Document Management System (NOAH) is a web-based documentation management tool that permits users to upload documents to a web site and share these documents with other members of a team or organization.


Quick Start: (top)

/Weather/bear/clue1.pdf

Meta-data   (top)

Meta-data is the data that is attached to a file or directory to document it's properties for future reference.

When NOAH displays a directory listing, many of these meta-data fields are displayed in a column format.

titlebar

The above image partially shows the title bar of an example directory listing in NOAH with the columns: File, Permissions, Owner, Group,Size and Date.

The Perm permissions field is a shorthand for the 3 permission categories of Group, World and Universe (from left to right). Note that the Owner of the file or directory always has 'write' permission.

In the above image, the file 'shorewall.html' is read-write accessible only to the owner of the document and the file 'france.2003.checklist.xls' s read-write accessible to the owner and to the users that belong to group 'fivestar'. See File and Directory Permissions for more details.

In a large directory listing, the user can select which column the data is sorted on and the sort direction (up or down) by clicking on column names that are underlined. In the example above, the File column is the sort column and the direction is 'down' (as indicated by the down arrow).

A 2nd click on the column name will change the sort direction to 'up'.

In all columns, EXCEPT for the File column, a 3rd click will hide the column from view leaving a rightleft icon which, if clicked on, will un-hide the column.

The columns Perms., Owner, Grp, Size and Date are special columns in that they can be collapsed into a hidden [details] column by clicking on the close icon. This is useful when Title and File name fields get large and the user wants to focus on just a few columns.

In the field called [Info], the user can click on the V link to view and modify Version Data or click on the E link to edit file or directory meta-data. See [Info] field for details.

The following table gives a full description of file and directory meta-data:

Short Name:Description:Char Max:
NAME Filename of document or Directory name of directory.

Input restricted to { a-z A-Z 0-9_} for the first character and for the remaining characters: { a-z A-Z 0-9_-.+# and space } if a file and { a-z A-Z 0-9_-. } if a directory. Trailing { _.+ } characters are removed. All other characters generally get replaced with _ unless a more intelligent substitution is found.

It is permissible to upload files with the same name .. they will appear as multiple entries in directory listings.

It is also permissible to create duplicate directory names. NOTE: When downloading duplicate directory names in a zip file, the sub-directories and files of the duplicate directories will merge together. Duplicate filenames will be appended with the 'docno' to make them unique filenames.

100
TITLETitle of document or directory.
... only restricted characters are ; (semicolon) which gets replaced with a - and " (double quote) which gets replaces with a ' (single quote).
256
AUTHORAuthor of document(s).
... only restricted characters are ; (semicolon) which gets replaced with a - and " (double quote) which gets replaces with a ' (single quote).
50
CATCategory given to document(s). Administrator can 'rename' this field. ... only restricted character is ':' (colon).

The administrator will set up the permitted category fields that map to index numbers. This permits the administrator to 'rename' a category without corrupting the NOAH database!

NOTE: If the administrator does not program this field in the noah.config file, the field will remain hidden.

5
STATStatus given to document(s). Administrator can 'rename' this field. ... only restricted character is : (colon).

The administrator will set up the permitted status fields that map to index numbers. This permits the administrator to 'rename' a status without corrupting the NOAH database!

This field has one other property .. the ability to restrict (lock) certain document states (as tagged with the 'STAT' field) to be changed by an administrator (librarian) to assert some control over document state changes.

NOTE: If the administrator does not program this field in the noah.config file, the field will remain hidden.

10
ABSTRACTAbstract (Description of Document or Directory).
... only restricted characters are ; (semicolon) which gets replaced with a - and " (double quote) which gets replaces with a ' (single quote).
1024
LOCKED_BYUser that locked document (not locked if empty).50
DATE_LOCKEDDate document was locked.
KBSIZESize of current 'default' document in Kbytes.10
DATE_LASTUPDate-time of upload for the 'default' version
DATE_MODIFIEDDate-time that the meta-data was last modified.
OWNEROwner of the document or directory. A Owner of a file or directory automatically has read-write permission.
..... See File and Directory permissions
50
RWGROUPRead-Write Group name that the file or directory belongs to (can be blank).
..... See File and Directory permissions
ROGROUPRead-Only Group access permission.
..... See File and Directory permissions
WORLD_PERMWorld access permission.
..... See File and Directory permissions
UNIV_PERMUniverse access permission.
..... See File and Directory permissions

Select Action Buttons: (top)

select

The Select Actions: buttons (shown above) is a collection of buttons that act on files that have check-boxes checked (as shown below).

box

These actions are described next along with their respective 'Tool Tips':

Select Action: "Tool Tip" and Descriptions:
"Upload selected files as new versions."

Each new version replaces the old version as the default and stores the old version(s) into the version database. Versions are accessed with the V ] hyper-link in the [Info] field.

"Download most recent version of selected files. (.zip for multiple files)"

This download (using check box) will typically cause the browser to ask the user if he wants to store the file rather than open it with a default application.

Selecting more than one file or selecting a directory will cause NOAH to zip the files into a single .zip file download.

NOTE: Link's to NOAH directories are NOT followed in multiple file downloads unless the link is at the top of the selected directory hierarchy.

"Move selected files and dirs to a new directory."

The user must have 'write' permission for both the source directories and the target directories when doing a move.

"Delete selected files and directories to the /WasteBasket directory."

The user must have write permission to the source directory for the delete to succeed. The administrator can set the read and write permissions for the WasteBasket directory to control who can see this WasteBasket directory (read permission) and who can move documents out of this directory (write permission).

The WasteBasket directory is purged periodically by the administrator or a scheduled cleanup job using the 'purge' admin program. This is documented in the 'NOAH Installation and Maintenance Manual'.

"Create document or directory links (short-cuts) for selected files."

This button will create directory ( dirL ) or file ( textL ) links in the current directory for the selected files.

The user can then move these links to the directory that they want the link to reside in to be able to 'link-back' to the file or directory.

NOTES:

  • NOAH will only permit 'one' link per file or directory to exist in a given directory. Thus the user must move the link(s) to the target directory location before creating MORE links for that file or directory.
  • If the user does not have write permission to create the link in the current directory, a target directory dialogue will appear to permit the user to select an appropriate target.
"Create links to selected files for email and slideshows."

By emailing just the link to the file, rather than the file itself, one can reduce the volume of email on the network (especially an issue with dial-up) and ensure that the user of this link is always pointing to the most recent version of the file.

elinks The example on the right is an illustration of a generated elink.

The user can save this elink as a file or copy the window or just the links to an email or web page.

EMAILTO:
An 'EMAILTO:' button also exists on the elinks page which a user can select to load the links into the default email tool launched by the browser. Other email options are available if the NOAH Email license option was purchased.

Permissions
A user needs read permission to download the files or directories in an elink. The user must ensure the directory path permissions are set correctly as well as the read permissions on the file itself for other users to access the file. The NOAH download program will direct a user through a NOAH login page if access is denied.

Slide Shows:
The user also has the option to save the links in a Slide Show format. This file (slideshow.html) can be sent as an attachment in an email and permits the user to click forward through a list of pictures. The user may also want to upload the slideshow.html file to NOAH .. and send the elink to this file!

"Lock selected dirs/files so other users can't create new dirs/files."

Only the owner of the LOCK can unlock a directory or file.

A user must have write permission to be able to lock a directory or file!

Locking a directory or file also locks the meta-data for that dir/file.

The Administrator can configure NOAH to permit uploads on locked files .. with the appropriate warnings during upload. Because uploads don't actually delete any files, no data can be lost if this option is set. Comment fields in the version database would help people sort out these versions.

Locking a Directory prevents others from creating a new file or directory in the locked directory or from changing the grouping of files/directories. See File and Directory Locking for more details.

"Un-lock selected directories or files."

Only the owner of the LOCK or the Administrator can unlock a directory or file.

"Group selected files to show relationships. Single-SELECT defines parent." group

By grouping files together, one can illustrate what files are related or derived from each other as shown on the right.

Files and directories can be added to the group by selecting a file in the target group along with the new group member and clicking on 'group'.

If you want to change who is first (parent) in the group, just select the new parent and click 'group'.

groupred

If a child in the group has an upload date that is 24 hours older than the parent, the arrow will turn red as shown on the right. The black and red arrows have Tool Tips so if in doubt as to the meaning of the arrow, slide your mouse over the arrow for the Tool Tip.

"Ungroup selected files."

Selecting the parent file and clicking on 'ungroup' will ungroup all the files in the grouping.

"Edit info (meta-data) for common fields in selected files."

If you want to change the file info (meta-data) of many files at once, use this command. Selected files will be analyzed for empty or duplicate field entries and permit editing of those fields only.

A bonus side-effect is that empty fields get filled with the one non-empty field for that meta-data field .. so it is like a 'copy meta-data' in these cases.

"Subscribe to receive emails when a new default file version appears."

When a user subscribes to a file, the user will receive an email notification when ever the default version number changes on this file. This will happen when ever a new file version is uploaded with the 'set as default' box checked (default behaviour) or if a user changes the default version number of a file using the V ] link.

If the user subscribes to a directory, then any file within this directory that changes it's default version will generate an email notification to the user. In addition, if a new file is uploaded to this directory, an email notification will also be sent to the user.

Files and directories that a user subscribes to are annotated with subscribe beside the text or directory icon.

NOTE that a user can search for his/her subscribed files/directories in the Advanced Search menu.

"Un-subscribe to email notifications of new versions."

[Info] field - view/edit file/dir info   (top)

info There are three symbols in the [Info] field. The V stand for VIEW in a directory context or VERSIONS in file context. The E stands for EDIT file or directory meta-data. If you are licensed for 'elinks', the third symbol is S and stands for SUBSCRIBERS and will show who else is subscribed to this item.

V Menu:

When the V symbol is clicked, the user is shown the meta-data for the file or directory including fields such as Author, Title, Abstract, Creation and Modification dates as-well as Access Permission fields.

In the case of a file, the V page also prints information on document versions and gives the user the option to access an earlier version of the file or update a version comment or delete a version.

The V page has a number of buttons in the Select Actions: section (shown below) which act on the version listing.

versions

These actions are described next along with their respective 'Tool Tips':

Select Action: "Tool Tip" and Descriptions:
"Edit comment fields of selected versions."

It's often useful to edit the comment fields of previously uploaded versions to 'correct' info on the history of the versions. By editing a group of version comments on one page, the user can keep everyone straight!

"Delete selected versions (scheduled jobs will make deletion permanent)."

Deleting versions is done by setting a flag in the versions table to 'delete'. This makes it possible to 'Retrieve' old deletions (see next button!).

The Administrator will have set up a scheduled job to remove deleted versions with the admin 'purge' program.

"Retrieve recent versions deleted (unless scheduled jobs deleted permanently)."

As suggested above, you can only retrieve a deleted version if it has not been purged from the database by a scheduled cleanup job.

E Menu:

When the E (EDIT) symbol is clicked, a page comes up to edit the file/dir information fields. Most of these fields are self-explanatory except perhaps for the Access Permission fields .. which are described in the next section!

S Menu:

When the S (SUBSCRIBERS) symbol is clicked, a page comes up listing who is currently subscribed to this directory or file. See the Subscribe Button for more information on how subscriber email notification works.


Searching   (top)

There are two search modes: a Simple Search and an Advanced Search.

Simple Search:

search

The above image illustrates a Simple Search of the word 'hardware' in all filenames, directory names and title fields.

Entering multiple words narrows the scope so a search with the words 'hardware software' will match all files and directories where 'hardware' and 'software' both occur in at least one of the three fields.

If the Noah License includes the Content Search option, the 'Content' checkbox will appear next to the 'Go' button. If this 'Content' checkbox is checked, the search will match files that have the words 'hardware' and 'software' in the file content provided the file is a supported content type. 'Content' searching in this Simple Search ignores the meta-data fields.

At the time of writing, the supported content types for Content Searching are: text files, Microsoft Word, Microsoft Excel, PDF (portable Document Format by Adobe), OpenOffice Writer (.sxw) and Calc (.sxc) and limited support for Postscript format.

NOTE that in Windows server installations, the Content Search indexing occurs as a scheduled job which means it may typically take up to 5 minutes before a new file has been indexed and ready for content searching.

The search options described above may not always give enough search control and so a more advanced search option is available and is described next!

Advanced Search:

An Advanced Search permits the user to specify search criteria in almost every field in the meta-data for files or directories. The following image captures a portion of this search menu:

searchadv

The trick with the advanced search is that the user has an option to do an 'AND' search or an 'OR' search.

An 'AND' search means that each of the non-empty fields in the search menu must match the word(s) in the designated fields for a file or directory to be found as a match. This might be called an intersect of multiple sets or an 'AND' set.

An 'OR' search means that if ANYONE of the non-empty fields in the search menu finds a word match in there respective fields, then the file or directory found is deemed a match. This might be called a union of multiple sets or 'OR' set.

NOTE that partial words may be entered into the search fields. This includes the Start Date and Stop Date so one can specify a year of say 2004 and this gets expanded to 20040101 for the first day of the year 2004.

If the Noah License includes the Content Search option, a File Content: section will also appear permitting the user to do content searching of the files in the database. The more words you enter in the 'Search for:' field, the tighter the search criteria.

See the Simple Search notes (above) describing supported file types and Windows indexing issues.


Show Recent Changes   (top)

showrecent

The most common question one has of a document database is 'show me the most recent changes to project X'.

The NOAH solution to this is the 'Show recent changes' link illustrated in the image above.

This link calls the program getrecent.cgi which opens up the NOAH log file and finds all the files that have changed in the last 7 days that reside in the current directory OR ANY SUBDIRECTORY of the current directory.

If you don't have permission to read a file, the filename field comes up with '(access denied)'.

The really cool thing about getrecent.cgi is that it can be called directly from any webpage or wiki (not just within NOAH) and there are a ton of parameters that you can play with to control which fields are display and in what order, the definition of 'change', the number of days to look back in time and more.

A common way to use getrecent.cgi in a wiki is to enable HTML mode and insert an 'in-line frame' in your wiki document with the call to getrecent.cgi to load the frame.

If the user does not have access permission to a recently changed file, the returned filename is censored with the phrase '( access denied )'. If an organization decides that revealing a filename to all that can access NOAH is not a security threat, you may want to call getrecent.cgi with a password which will display the filename uncensored.

NOTE that even if the filename is uncensored, the user will still have to pass the access permission restrictions of the directory path that the file sits under to actually download or read the file.

getrecent.cgi parameters:

    docno=D'n' or F'n' : document or directory #

    mode=L             : return a line for every 'changed' document.
 or mode=C             : return only the count of how many 'changed'.

    filter=NVLS        : N=new uploads, V new version uploads D version default
                         where letters can be in any order. (default is NVLS)

    fields=DFCWNV      : D=Date, F=Filename, C=Change, W=Who, N=document #, V=version
                         where letters can be in any order to change field order.
                         (default is DFCWNDV)

    password='password': to enable display of 'access denied' filenames.

    period=7           : number of days to go back searching for 'changes' in NOAH logs
                         (default is 7 days)

    max='n'            : limit return to 'n' lines

    target='target'    : open links in new page or tab (usually set to _blank)

In-line Frame Example:

 <iframe src="http://somehost/cgi-bin/noah/getrecent.cgi?docno=F125250&period=3&target=_blank" align=middle width=800 height=300></iframe>

Notice how each parameter is started with an '&' except the first parameter which is a '?'.

Ask your administrator for the password (getrecent_pwd setting in noah.config) if you decide to use the 'password' parameter.


Special File Icons   (top)

showrecent

Notice the special icon beside the 'wiki.html' file in the above image?

NOAH can be configured to treat special filenames as 'special' and place them ahead of the Directories or Files in directory listings.

This is like raising a file to the head of the class so everyone can see it quickly.

The NOAH installation installs a default icons.tab file that defines three default filenames 'wiki.html', 'index.html' and 'webpage.html' with the 'W' icon in the image above.

A very common use of a special file icon is to have it jump to another webpage or wiki to link the user to a related site like a Wiki Project Page.

A way to make this transparent to the user is to use java-script to seamlessly open the target page when you click on the NOAH file.

Here is an example page:

<html>
<head>
<title>Wiki</title>

<script language="javascript1.3" type="text/javascript">
<!--
    LinkPath = 'http://somehost/wiki/doku.php'
    LinkPage = 'start'
    popWin = window.open(LinkPath+'?id='+LinkPage,"popWin")
    popWin.focus()
    history.back()
// -->
</script>

</head>

<body>

<p>If you see this page, then the javascript did not work!</p>

</body>
</html>

DokuWiki Links   (top)

If you have installed DokuWiki on your server, you can setup a job that will periodically sync the Special Files, described above, to include the DokuWiki linked pages to NOAH's content search engine. Ask your administrator to look at the wiki-update.pl program in the NOAH admin directory.


File and Directory Permissions   (top)

Every directory and file in the NOAH database has a set of attributes called 'Access Permissions'. Access permissions determine who can modify or read the file or directory contents. If a user does not have 'read-access' to a file or directory, the entry is not listed in a directory listing.

These options are best illustrated in the following image:

perms

As you can see, there are four Access Categories which are defined as follows:

In addition to the 'Access Categories' are the 'Access Permissions' described next:

With these definitions, one can set the permissions for each of the Access Categories and decide if the file or directory should belong to a group.

Note that the 'Admin User' or a user belonging to the 'Admin Group' can also change the 'Owner' or the 'Locked By' fields.

Hierarchical Permissions

The important point to remember is that permissions are 'hierarchical'. If a user does not have access permission to the directory the file is sitting in, then permission to download, edit etc. would be be denied.

This means that a user can block off a complete directory hierarchy from access by other users simply by changing the permissions of the root directory.

A common approach taken by an Administrator is to set the 'home' (dir) directory of the NOAH database to deny 'Universe' read access to keep people not logged into NOAH from accessing files.

Inheritance:

When a new file is uploaded to a directory, the permissions taken by the file are inherited from the directory the new file is sitting in at the time of the upload. Of-course the user can change these permissions after the upload if something special is required. You can think of this feature as a way to set the permissions template for all new uploads.

Admin User restrictions:

Over-riding the above access permissions is a rule that states that only an Admin User (i.e. username exactly equal to 'admin') is permitted to create a directory, upload a new file or delete a file or dir in the home (dir) directory. In addition, only an Admin User may move a directory or file into the home directory.


Admin Group Privileges   (top)

To distribute the administrative load throughout the organization, the NOAH administrator may decided to add key users to the 'admin' group. The Admin User can do this in the NOAH Administration Menu called 'manage users/groups'.

If you are a member of this 'admin group', you will see AG beside your username in the upper right corner of the main directory listing page.

This 'admin group' allots you special privileges and responsibilities and givens you over-riding read/write permission to all files and directories in the database EXCEPT for those files and directories that are owned by the Admin User.

The Admin Group Users :


File and Directory Locking   (top)

File Locking

If a file is locked and the Administrator has configured NOAH to 'disable uploads on lock' (default config.), then only the Owner or Admin User or the Admin Group can upload a new file version or edit (E ]) the meta-data of this file.

If a file is locked and the Administrator has configured NOAH to NOT 'disable uploads on lock', then any user with 'write' permission can upload a new file version or edit ([E]) the meta-data of this file.

If NOAH allows a user to upload a new file version when the file is locked, the new file upload will NOT become the default version (i.e. current default version does not change).

Directory Locking

Directory Locking is similar to File Locking in that when a directory is locked, only the owner of the lock is allowed to edit (E ]) the meta-data of this directory.

In addition, Directory Locking prevents others from creating a directory or uploading a new file INSIDE the locked directory. This does NOT prevent an owner of an EXISTING directory or file INSIDE the locked directory from editing the meta-data of that directory or file.

If a Directory is locked, only the owner of the lock can change the default version of a file inside this locked directory. This is the only exception to editing meta-data described in the previous paragraph. When uploading new file versions, this means that the default version will NOT change.

If a Directory is locked, the directories and files inside the locked directory can only be moved or deleted by the owner of the directory lock.

NOTE that Directory Locking is NOT hierarchical which means once a directory has been created below a locked directory (i.e. a sub-directory), others can create new directories or upload new files inside this sub-directory provided the Access Permissions are valid.

A directory is locked in the same manner as locking a file: by selecting the directory with the check-box and clicking on the 'lock' Select Action button. When a directory is locked the directory icon changes to a (dir) icon. Hovering the mouse over the icon raises the tool tip telling the user who has locked the directory.

Delete and Move restrictions

If a file or directory is locked by another user, the file or directory can only be deleted by the owner of the lock or by the Admin User or by a user from the Admin Group.

This also means that a user can not delete a directory that contains a locked file or directory in it's hierarchy.

NOTE: This lock behaviour applies to the Delete command only, not the Move command. However, your Administrator can change the default behaviour on Delete and Move commands to be more restrictive or less restrictive with the noah.config file.


Email Notification Option   (top)

If the Email Notification Option is enabled by the NOAH License Key, new version uploads and elink menus will display email notification buttons.

New Version Upload

When uploading a new file version, the user has the option of sending email notification to a group. To assist the user in selecting an appropriate group, NOAH displays the Read-Write and Read-Only groups of the Upload files and permits the user to query who is in a selected group.

If the user chooses GROUP notification, all the email addresses of users that belong to this GROUP will be sent an email telling the recipients that the file has a new version. The email will include various meta-data from the file and also include the Comment field filled out by this upload menu and a HTTP link to the file for quick navigation to the file contents.

Similarly, the 'Email to World' button will send the email change notification to all NOAH users. This WORLD email notification feature can be disabled by the administrator in the noah.config file.

Elinks

When files are chosen and displayed with the Elinks feature, the user is given a 'Email Comment' field and additional buttons to permit the user to 'Email to Group' or 'Email to World'. Again, the 'Email to Group' will not appear if the GROUP field is empty.

Similarly, the 'Email to World' button, if not disabled by administrator, will send the email change notification to all NOAH users.

Administration Issues

The NOAH administrator will need to set up the 'efetch' and 'esend' programs to run on a periodic schedule to service the Email Notification Queue as described in the 'NOAH Installation Manual'. The frequency at which these programs run will determine how quickly notifications are sent out.


Client Scripting Option   (top)

If the Client Scripting option is enabled by the NOAH License Key, the users will be permitted to run client programs on their desktop computers to simplify the task of keeping files up-todate either on the NOAH server or on the clients desktop computer.

The Client Scripting option provides WINDOWS and LINUX compatible executables for general file upload, download and re-synchronization. See the Noah Client Scripting description on the NOAH website for more information.


contact: noah@nordicwind.ca Copyright © 2004-2012 Nordicwind Inc. - All rights reserved.