Software Concepts

From DoKSwiki

Table of contents

Concepts

Introduction

A piece of information in Doks is called a record. Each record consists of a number of named fields. E.g. a FAQ could have a question field and an answer field, while a Discussion could have a subject field and a body field. These fields are defined by the structure of the record. Doks allows you to define your own structures with arbitrary fields. This is explained further in Records and Structures.

Records can be organised in a hierarchy of folders which are very similar to directories in a file system. A folder can contain records and/or sub-folders. Folders are explained in Folders.

Doks also contains a scripting module which makes it both extensible and customisable. The scripting language, BeanShell, is very similar to JavaScript. Work flow actions are user-defined buttons on the user interface that execute such a script when pushed. Work flow actions are further discussed in Scripting.

Doks has a Unix-like permission mechanism to control access to records and folders. This implies that Doks has users and user groups as explained in Access control.

Records and Structures

Structures

A structure defines all the fields for a specific class of records. All the structures are defined in a configuration file (doks_home/conf/structures.xml) and have a unique name.

The fields of a structure have a name and a type. Currently following field types are supported in Doks:

  • string: one line of text
  • text: multi-line text
  • html: text with HTML markup
  • url: text that will be displayed as a HTML anchor
  • choice: a drop down list with predefined values
  • multichoice: a drop down list with predefined values off which more then one can be selected
  • boolean: true or false
  • date: a date in Gregorian calendar
  • integer: an integer number
  • number: a floating point number
  • fileset: a set of files (attachments)
  • record: a record contained within another record (inner record)
  • recordlink: a link to a record
  • recordlinklist: a list of links to records

F.e. the FAQ structure contains a field of type string that is named answer and a field of type fileset that is named attachments.

A field of a structure can be marked as mandatory in which case the application will make sure that a user cannot leave it blank.

Records

As stated before, a record contains all the fields defined by its structure. Beside these (user-defined) fields each record always contains a set of build-in fields:

  • description: a descriptive text, usually a title
  • creationDate: the date and time when the record was created
  • lastModificationDate: the date and time when the record was last modified
  • owner: the user that owns this record
Note
The name of the description field can be changed for a structure. F.e. in the FAQ structure the description field is named question.

Folders

Tree hierarchy

Folders in DoKS are similar to directories in a file system in the sense that they can contain records and other folders. All the folders together form a tree hierarchy. The name of a folder must be unique within the context of its parent folder which means that each folder is uniquely identified by its path (f.e. /Home/subjects/mathematics).

One difference with directories is that a single record can be found in multiple folders at the same time. F.e. it can make sense to have a record about programming in both /subjects/programming and /departments/computer engineering.

In Doks a folder can also contain shortcuts to other folders. These shortcuts are displayed with a different icon.

Structures and folders

Each folder contains a list of structures that are allowed for that folder. Only records with a structure that is listed can be added to this folder.

One cannot add records to a folder with an empty structure list. Only sub-folders can be added to such a folder.

Note
When a structure is removed from a folder and that folder already contains records of that structure, these records will not be removed from the folder. It will however become impossible to add new records with that structure.

Information Record

Each folder can have an information record associated with it. This record can have any structure, although Doks has standard a FolderInfo structure pre-configured.

The information record can a.o. be used to:

  • present a descriptive text about the folder to the users
  • maintain a subscription list for the folder to send an e-mail to all subscribers when a record has been added to the folder
  • etc.

Scripting

The functionality of DoKS can easily be extended by writing custom scripts. These scripts can be used to automate actions, create listings etc.

There are two types of scripts:

  • Compiled scripts: these are plain Java classes that implement the Executable interface.
  • Interpreted scripts: these are BeanShell scripts that can be modified on the fly. Beanshell gives you the choice between a strict Java syntax and a loose javascript-like syntax.

Access control

DoKS has unix-like permissions based on the user that is performing an action. This means that you can associate an owner and a group with each controlled object (folders, records, scripts, users and user groups). Hence permissions can be different based on the fact that a user is the owner, a group member or anyone.

One difference with unix is that there is no predefined root user. Instead any user can have administrator rights which means he has all permissions on all objects.

Users

A user in DoKS has following fields:

  • user name (unique)
  • full name
  • e-mail
  • language
  • administrator flag (tell whether or not this user has administrator permissions)
  • login configuration (determines how the user's password is checked: locally in DoKS, via LDAP, etc.)

Furthermore each user can have an information record associated with it. This record can have any structure so that you can add fields to suite your own needs (address, phone, department, etc.)

User groups

Users can be member off zero or more user groups. In this way the user automatically has access to folders, records etc. that the group has access to (cf. Unix).

A user group is uniquely defined by its name.

User groups don't have information records.

Permissions

There are 6 different types of permissions that are explained in following sections. The access control mechanism is designed to make it possible to add/change permission types, but this requires an in depth knowledge of the system.

Read permission

Objects will only be visible for a user if he has read permission on it.

Read permissions apply to:

  • folders
  • records
  • users
  • user groups
  • scripts
Write permission

A user is allowed to modify an object only if he has write permissions on it.

Write permissions apply to:

  • folders
  • records
  • users
  • user groups
  • scripts
Delete permission

A user is allowed to delete an object only if he has delete permissions on it.

Delete permissions apply to:

  • folders
  • records
  • users
  • user groups
  • scripts
Add permission

Add permissions are required to add a sub folder or a record to a folder.

Read permissions apply only to folders.

Administrate permission

Administrate permissions are required to change the owner, group or permissions of an object.

Administrate permissions apply to:

  • folders
  • records
  • users
  • user groups
  • scripts
Execute permission

Execute permissions are required to execute a script.

Execute permissions apply only to scripts.

File formats

Each file that is attached to a record has a file format associated with it. This file format provides information for long term preservation, independent of the file extension.

File formats can also be used inside scripts to know what type of file you're dealing with.

File formats hold following information:

  • name (unique)
  • description
  • MIME type
  • a list of file extensions

When a user adds a file to a record, the file format is guessed based upon the extension. The user can correct this if necessary.