DMSF User's guide

1 Introduction

Document Management System “Features” - DMSF is a plugin for Redmine issue tracking system. It is aimed to replace current Redmine's Documents module.

Redmine DMSF now comes bundled with WebDAV functionality: if switched on within plugin settings this will be accessible from /dmsf/webdav.

Initial development was for Kontron AG R&D department and it is released as open source thanks to their generosity.

Redmine Document Management System "Features" plugin is distributed under GNU General Public License v2 (GPL).

Redmine is a flexible project management web application, released under the terms of the GNU General Public License v2 (GPL) at http://www.redmine.org

Further information about the GPL license can be found at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC1

2 Features

• Directory structure
• Document versioning / revision history
• Email notifications for directories and/or documents
• Document locking
• Multi (drag/drop depending on browser) upload/download
• Multi download via zip
• Direct document or document link sending via email
• Configurable document approval workflow
• Document access auditing
• Integration with Redmine's activity feed
• Wiki macros for quick content linking
• Full read/write WebDAV functionality
• Fulltext search
• Documents and files symbolic links
• Custom fields
• Trash bin
• Documents preview

3 My Account

The following options related to DMS are available in My account:

• Default DMS query - The default query which will be default in the DMS view
• Receive download notifications - You will receive download notifications for watched documents

4 Project settings

4.1 Modules

In order to be DMS available, it is necessary to have checked the DMS module on the Modules tab.

4.2 DMS

Every project member is allowed to customize the DMS module behavior as follows:

Your DMS project's preferences

Notifications – Activated(default), Deactivated – If deactivated, you won't receive any email notifications related to documents and vice versa.

Title format – File names of downloaded documents can be formated using following tags:

• %t – document title
• %d – the date when the document was uploaded
• %v – version of the documentation
• %i – ID number of the document
• %r – revision number of the document

Fast links – If selected, you are expected to enter a document’s ID instead of selecting the document from a pick list when creating a document link.

Default query - You can select an existing query which will be default in DMS view.

4.3 Approval workflows

Definition of approval workflows of the project.

To create a new approval workflow click on the icon New approval workflowin the top left corner. Then you are expected to enter a name of the new approval wokflow:

Now fill in a new workflow name and click on Create button.

Optionally you can select an existing approval workflow to be copied.

Just created workflow appears on the workflow list. In order to change the workflow name or to define workflow steps click on the workflow name. In our case on the text Basic.

Then workflow update form appears. In the top of the form you can update the workflow name. Edit the name there and click on Save button.

Using the New step button you can choose one or more approvals and by clicking on AND or OR button you will add a new approval step to the end or by choosing an existing step from the list to an existing step.

Later on exiting approval steps can be removed, reordered or edited by clicking on corresponding icon next to the step approvals.

5 DMS module

The DMS module allows you to store all documentation relevant to a project at one place, sorted into folders. You can switch on the Documents module by going to the project Settings → Modules tab. Check the check box in front of the DMS item, which is the Document Management System Feature.

5.1 Documents management

The documents are stored in folders, which should have such a structure that provides an easy orientation within the topic.

5.2 New folder

You can create a new folder by clicking the green plus sign Create folder in the right upper corner. This takes you to the following screen:

Type the new folder Title and click the Create button. You can add a description of the folder. You can use various types of text formatting, such as headings, lists, links to web pages, documents etc. If you need help with the text formatting, click the Helpb> tool button and you are provided with a list of commands, including examples. Moreover, you can set folder's custom fields if any. Access to the folder can be driven by selecting certain roles or particular users in Allow access only to section.

A new folder can be also created by copying an existing folder. Go to the folder you wish to create a copy of, and click the Edit icon:

Or click on Edit item in the context menu next to the folder in the main view:

On the folder edit page choose Copy/Move from the context menu:

Select the Target project and Target folder. Click the Copy button.

5.3 Folder permissions

In the new folder form or later in the edit form you can specify an extra folder permissions. By selecting roles and members you can control access to the folder.

Only the selected roles or users will have access to the folder.

5.4 List of folders

• folder's name
• folder's date of creation and author
• folder's context menu

The editing tool uses the same form as is used for creating a new folder. You can change the folder's title, description and permissions.

The list of folders can by ordered by any column. Just click on the column title and the list will be reordered by the column's values. If you click the same title again the order will be reversed.

5.5 Filtering

You can limit the view to certain folders and documents by defining filter rules. An empty filter for the title is displayed by default. Additionally, you can add more filters using the pick list on the right side. In case of a list of values you can combine multiple values.

5.6 Options

There in Options you can specify visible columns.

5.7 Custom queries

Defined filters and options can be saved as custom queries for later usage.

Firstly, define filters and options. Then, save them as a custom query using the link Save custom query.

Defined custom queries can be then edited, cleared or deleted using corresponding commands: Edit custom query, Clear and Delete custom query.

In My account you can select Default DMS query for your account.

5.8 Download

To download or see a document just click its title.

Documents of display-able types such as PDF, PNG, JPG, ODT,... are displayed inline. If you want to download them use the right mouse button's context menu of your browser and click on Save link as.

Multiple documents and folders can be downloaded at once. Select multiple items using check boxes on the left side or using your mouse and <Shift> button. The open the conext menu using your mouse and click on Download. Selected items will be zipped and offered for downloading.

5.9 Email

Single or multiple documents can be sent by email. Select one or multiple document and choose Email from the context menu.

In the email form fill in email recipients and optionally a body text and click Send.

By default, selected documents are zipped and attached to the email. If you select links only, the documents won't be directly attached but linked into the email's body instead. If you use Public URLs check box, the documents' links will be made public and will be valid for the specified period of time.

5.10 Delete

Select single or multiple items and from the context menu choose Delete.

5.11 Add documents

Click on the green plus icon New document in the top right of the main view. Then you can use the Browse button or simple drag and drop files into the drop-able area. Multiple files (max 10) can be selected.

Recently uploaded files ar listed on the screen. You can delete them, if they were selected by mistake using the trash bin icon. When done, click the Uplad button.

If you use [+] icon, you can specify document's details and then you can directly use Upload and commit button. In that case the following commit screeen will be skipped and uploaded documents will be directly stored.

Once the new files are uploaded, corresponding documents are created. Here you can specify additional attributes of the new documents. E.g. version and custom fields if any. When done, click again on Upload button. Then the new documents are committed and your are redirected to the parent folder with the new documents.

5.12 Update documents

Attributes or content of any document can be altered in the Edit from. Use the context menu and click Edit. Each change means a new revision. Click on the plus button New Revision. Then you can update any of the document's attribute and you can also upoad a new content using New content field.

The version of the document is automatically increased starting from 0.1. Major, minor and patch versions are available. the rabge of each version varies from 0 to 999 and from A to Z.

When all required attributes are set, click Create button.

5.13 Documents links

There is possible to create a link to another document or folder from the same or another folder of the same or another project. Links behave as if operating directly on the target document or folder. It means for example that if you download or email a link, the referenced file is sent to the user.

If the target document is going to be removed or moved the user will be warn about existing links and these links will be automatically removed.

There is a command Link to in the context menu of a document or folder. After a click on that item a new form New document link appears. The user is expected to choose a target project and folder as the destination of the link just being created.

There is a command Link to in the context menu in the top right corner of the main view. After a click on that item a new form New document link appears. The user is expected to choose a sorce project and folder and optionaly document as the target of the link just being created.

Allow to create links to DMS objects.

Allow to create links to external objects using their URL.

5.14 List of documents

• document's name
• document's file
• documnt's size, date of creation, version and author
• document's context menu

Using the context menu you can trigger the following commands:

• Edit
• Copy/Move
• Lock/Unlock
• Assignment/Start/Approval
• Download
• Email
• Edit content
• Watch/Unwatch
• Delete

5.15 Document's details

Document's details are avaiable when you click on the Edit item in the context menu. A new form appears then with a list of existing document's revisions. Each revision is represented by a box containg all attributes related to the revision.

Except visible attributes, there is also a context menu in the top right corner of each revision's box containg a command for displaying dowloading history - Download entries, downloading the particular revision - Download and deleting the revision Delete. The Delete command is only available, if it is not the last revision.

5.16 Notifications

Each project with active DMS module, each folder or document ca be set as "watched". Watch/Unwatch command is available from context menus. Watched items are marked with a yellow star.

You will reveive email notifications when watched items are updated, deleted or downloaded. The notifications about downloads must be explicitely switched on in your user's profile.

If a project or folder is marked as watched, notifications are sent for all folders and documents under the given project or folder.

5.17 Approval workflow

Thanks to approval workflows we can applied an approval process on each document. Approval workflows can be defined in the project's settings or in the administration.

The approval workflow state is indicated by workflow status in the Workflow column. The initial state is empty. If you move your mouse cursor over the status text and the approval workflow hasn't been finished yet, you will see a list of users who are expected to do an approval. If the workflow is in the stat of Waiting for an approval and the approval steps have assigned names, you will see the name of the current approval step.

You can check your open approval workflows on My Page Using the context menu you can approve documents directly from there. If the command is missing, it means that you are not expected to do an approval in the current approval step.

The process itself is clearly described on the diagram below.

And now step by step:

1. Assign an existing approval workflow to the selected document by clicking on Assignment. Then a workflow assignment form appears:

   

   All project's and global approval workflows are selectable. To manage approval workflows, see Approval Workflow of Project settings. Select a workflow and click on Submit button. The selected workflow is assigned to the document.

2. In the next step the assigned workflow must be started by on Start.

3. When the workflow is started, all approvers in particular steps are expected to do an approval. The document is locked to prevent all changes.

   If you are one of the approvers of the current approval step, you can do an approval by clicking on Approval. Then the approval form appears:

   

   You have three options here, either approve, reject or delegate the current approval step. In case of rejection or delegation you are obliged to comment it in the text field Your note.... Only members of the project are offered for delegation. Your decision will be confirmed by clicking the Submit button.

4. If you has just approved the document and you are the last person of the approval chain, the document is approved as a consequence of your approval. The status is changed to Approved.
5. If you has just rejected the document, the approval chain is finished immediately and the document is in the state of Rejected.
6. If you approve it and you are not the last approver or you delegate your approval to someone else, the workflow approval continues.

Approved an rejected documents remain locked depending on the plugin’s settings.

All workflow approvals are stored and are available in the log window. You can open the window by clicking the workflow status text:

Email notifications

Email notifications are sent according to the table as follows:

Retrieving/Reassigning of an approval workflow

In case of a wrong approval workflow assigning or a need to restart the workflow, just add a new empty revision from the document details. Then you can assign a new approval workflow to the document. The approval workflow is always related to the last document revision.

5.18 Trash bin

If documents or folders are deleted by a user, they are moved into the Trash bin only in fact and can be restored again or definitively removed from the Trash bin.

The Trash bin is available from the main context menu.

The user interface of the trash bin is very similar to the documents view except available command. Only commands for restoring and deleting are available.

If you use Restore, the selected items are restored to their original position in DMS.

6 Activity module

All changes related to a file revision and all downloads are recorded as activities. You can list any of them on Activity tab.

7 WebDAV

The document module of the project can be mounted as a web folder. In a mounted folder is available a complete document and folder structure. When a user does an operation such as download/upload a document or creating a new folder it is automatically recorded in DMS and it has the same effect as the operation would be done in the web interface of DMS.

A URL to mount has the following format:

https://[your domain]/dmsf/webdav/[project identifier]

Authentication

Basic

If you switch the authentication method to Basic in the plugin's settings, users are authenticated by their login and password that are sent from a client to the server as a text. From that reason it is not considered as secure.

Digest

It's the default authentication method. Users are authenticated using a digest that is auto-generated after a successful login to Redmine or they can reset it in their user's profile (My account). To log in from a client, they again use their login and password. Login is case-sensitive.

8 REST API

DMS exposes some of its data through a REST API. This API provides access and basic CRUD operations (create, update, delete) for documents and folders. The API supports both XML and JSON formats.

Detailed description can be found here togeather with a sample shell scrit.

9 Wiki macros

You can use DMS macros to link DMS documents and folders in Wiki formatted text. The wiki toolbar is extended with a DMS button. The popup menu contains all available macros togeather with their description under the Help command.