matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation updates

Browse Source
This commit is contained in:
Roberto Rosario
2015-01-29 18:34:27 -04:00
parent 8cdf98fcb4
commit 754c79b010
9 changed files with 106 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/topics/file_storage.rst
View File

@@ -3,24 +3,15 @@ File storage
============
The files are stored and placed under **Mayan EDMS** "control" to avoid
filename clashes (each file gets renamed to its UUID and with an extension)
and stored in a simple flat arrangement in a directory. This doesn't
filename clashes (each file gets renamed to its UUID and without extension)
and stored in a simple flat arrangement in a directory. This doesn't
stop access to the files but it is not recommended because moving,
renaming or updating the files directly would throw the database out
of sync. For direct access to the files the recommended way is to create an
:doc:`index <indexes>`, use the indexing mirroring feature and share the result via
file serving software [#f1]_.
of sync.
**Mayan EDMS** components are as decoupled from each other as possible,
storage in this case is very decoupled and its behavior is controlled
not by the project but by the Storage progamming class. Why this design?
not by the project but by the Storage progamming class. Why this design?
All the other parts don't make any assumptions about the actual file
storage, so that **Mayan EDMS** can work saving files locally, over the
network or even across the internet and still operate exactly the same.
The file storage behavior is controlled by the :setting:`DOCUMENTS_STORAGE_BACKEND`
and should be set to a class or subclass of Django's ``django.core.files.storage.Storage`` class.
.. rubric:: Footnotes
.. [#f1] http://en.wikipedia.org/wiki/File_server
storage, files can be saved locally, over the network or even across the
internet and everything will still operate exactly the same.

90
docs/topics/getting_started.rst
View File

@@ -2,52 +2,45 @@
Getting started
===============
This chapter will guide you through the initial steps needed to get **Mayan EDMS**
up and running after installation.
Before starting to use **Mayan EDMS**, two things need to be configured:
The easy 2 step setup
=====================
- At least one document source
- At least one document type
Document sources
----------------
Before anything else you must define from where you will feed **Mayan EDMS**
documents for it to process and store. To do this first go to the ``Setup`` tab
then to the ``Sources`` button. To obtain the fastest working setup, create a
new source of type ``Web forms``. This source will open a browser file upload
dialog, hence the name ``Web forms``. Name it something simple like ``Local documents``,
choose an icon to visually identify this document if you so wish and select whether or not
Document sources define from where documents will be uploaded or gathered.
To do add a document source go to the ``Setup`` section, then to the ``Sources`` section.
To obtain the fastest working setup, create a new source of type ``Web forms``.
``Web forms`` are just HTML forms with a ``Browse`` button that will open the file upload
dialog when clicked. Name it something simple like ``Local documents`` and select whether or not
compressed files uploaded from this source will be automatically decompressed and
their content treated as individual documents.
Document types
--------------
The longer custom setup
=======================
Setting your document types
---------------------------
If none of the available bootstrap setups fit your needs and your wish to
setup **Mayan EDMS** from scratch, the first thing to consider is what your document
types will be. Examples of document types are: ``Legal documents``,
``Internal documents``, ``Medical records``, ``Designing specifications``, ``Permits``.
A document type represents a group, a type, a class of documents which share some
common properties. A good indicator that can help you determine you document types
is what kind of information or ``metadata`` is attached to the documents.
Examples of document types are: ``Legal documents``, ``Internal documents``, ``Medical records``, ``Designing specifications``, ``Permits``.
A document type represent a class of documents which share some common property.
A good indicator that can help you determine your document types is what kind of
information or ``metadata`` is attached to those documents.
Once a document source and a document type have been created you have all the minimal
elements required to start uploading documents.
Defining metadata
-----------------
With your document types defined it should be much easier now to define the required
``metadata`` for each of these document types. When creating ``metadata`` types,
``metadata`` for each of these document types. When creating ``metadata`` types,
the first thing that will be needed is the internal name with which this metadata
type will be referenced in other areas of **Mayan EDMS**. Internal name is like a
variable so it should not contain spaces or uppercase characters. After the internal name,
type will be referenced in other areas of **Mayan EDMS**. Internal name is like a
variable so it should not contain spaces or uppercase characters. After the internal name,
enter the name that will be visible to you and your users, this is usually the same as the
internal name but with proper capitalization and spacing. ``metadata`` types
can have default values to speed up data entry, default static values are enclosed in
quotes, ie::
internal name but with proper capitalization and spacing. The ``metadata types``
can have default values to speed up data entry. They can be single number or a
words enclosed in quotes, ie::
"Building A"
@@ -60,24 +53,33 @@ Default values can also be defined as ``Python`` statements or functions such as
current_date()
If you want to restrict or standardize the values for a metadata type, use the ``Lookup`` field to
define the list of options that are allowed. Define the lookup list using a ``Python``
define the list of options that are allowed. Define the lookup list using a ``Python``
list of quoted values, for example::
["2000", "2001", "2002", "2003", "2004"].
Instead of a free entry text field, your users will get a dropdown list of years.
You can also use a ``Python`` expression to generate the lookup list.
Instead of a free entry text field, your users will get a dropdown list of years,
this will ensure an unified data entry formatting. You can also use a
``Python`` expression to generate the lookup list.
When you are uploading a new document, a choice of metadata types will be presented
and you choose which of those you wish to enter for the document you are about
to upload. To speed data entry you can also match which metadata types will
be preselected when uploading a document of a certain type. To match metadata types
to document types, go to the ``setup`` tab, ``document types`` button, and
lastly ``Default metadata``. Choose the desired metadata for the document type
currently selected and press ``Add``. From now on whenever you upload a document of
this type, the related metadata types for this document type will be preselected.
Metadata types can be assigned in two ways to a document type, by making it an
optional or a required metadata type for a specific document. This method
allows metadata that is very important to some types of documents, like Invoice
numbers to Invoices to be required in other for an Invoice to be able to be uploaded.
Accordingly optional metadata types will presented but users are not required to
enter a value in other to be able to upload a document.
After defining all your metadata types you can also define your indexes to
let **Mayan EDMS** automatically categorize your documents based on their metadata.
Refer to the chapter named :doc:`Indexes </topics/indexes>` for examples on how to
use the document indexes.
Indexes
-------
After defining all your metadata types you can also define indexes to
let **Mayan EDMS** to automatically categorize your documents based on their metadata values.
To create an index to organize invoices by a year metadata field do the following:
- Create a year metadata type with the name ``year`` and the label ``Year``.
- Create an invoice document type and assign it the ``year`` metadata type as a required metadata type.
- Create a new index, give it the name ``invoices_per_year`` and the label ``Invoices per year``.
- Edit the index's ``Tree template``, add a ``New child node``, and enter ``document.metadata_value_of.year`` as the ``Indexing expression``, check the ``Link documents`` checkbox and save.
- Link this new index to the invoice document type using the ``Document types`` button of the index.
Now every time a new invoice upload or an existing invoice's ``year`` metadata value is changed, a new folder will be created in the ``Invoices`` index with the corresponding invoices for that year.

4
docs/topics/indexes.rst
View File

@@ -2,7 +2,7 @@
Indexes
=======
Indexes are an automatic method to hierarchically organize documents in relation to their metadata and to each other.
Indexes are an automatic method to hierarchically organize documents in relation to their properties.
Index templates
===============
@@ -11,7 +11,7 @@ Since multiple indexes can be defined, the first step is to create an empty inde
Administrators then define the tree template showing how the index will be structured.
Each branch can be a pseudo folder, which can hold other child 'folders' or
a document container which will have all the links to the documents that
matched the path to reach the document container.
matched the criteria of the document container.
Index instances
===============

57
docs/topics/permissions.rst
View File

@@ -3,56 +3,45 @@ Permissions
===========
**Mayan EDMS** provides very exact control over what activies users can
perform. This control is divided into two levels of operation:
perform. This control is divided into two levels of operation:
2 tier permissions assignement
==============================
This level of activity control works
by allowing roles that are composed of users and group, to be granted
a permission such that the holder of that permission can exercise it
throught the entire collection of objects (document, folders, tags, etc),
this method could be thought out as a global permission granting level.
Example: Roles being granted the ``Document view`` permission will be able to view
**all** documents in existance.
This level of activity control works by allowing roles that are composed
of users or groups, to be granted a permission such that the holder of that
permission can exercise it throught the entire collection of objects
(document, folders, tags, etc), this method could be thought out as a global
permission.
3 tier access control
=====================
When more control is desired over which objects
actors(user, groups and roles) can exercise an action this method should be
used. Under this level, actors are granted a
permission but only in relation to a selected object. Example: Granting user
``Joe`` the ``Document view`` access control for document ``Payroll``,
would allow him to view this document only.
When more control is desired over which objects actors
(user, groups and roles) can exercise an action, this method should be
used. Under this method, actors are granted a permission but only in relation
to a selected object. Example: Granting user
``Joe`` the ``Document view`` access control for document ``Payroll``, would
allow him to view this document only.
The permission system enforces inheritance by first checking if the user
has a global permission, is a member of a group or a role that has a global
permission and if not then checks to see if that user, a group or role to
which he belongs, has been granted access to the specific object to which
he is desiring to perform a given action that requires a permission.
Only when these checks fails the user
is forbidden to perform the action and a generic message indicating this is
displayed to avoid providing any information that could be used to sidetrack
the permission system or obtain any kind of information about the object
from which the user was not allowed access.
Only when these checks fails the user is forbidden to perform the action and
a generic message indicating this is displayed to avoid providing any information
that could be used to sidetrack the permission system or obtain any kind of
information about the object from which the user was not allowed access.
Default Access Control Lists (Default ACLs)
-------------------------------------------
One of the specifics of the 3 tier access control in contrast with the 2 tier access control are so called Default Access Control Lists.They allow assigment to Users an access to a particular object - the class or instance of the class. The document ``Payroll`` is example of instance of class ``Documents``. A user can be granted with access to only one instance of the class ``Documents`` or to the whole class ``Documents``. And not only that but Default ACLs give the possibility to grant access to class before it is instantiated. It will be explained with the following example.
Default Access Control Lists allow assigment of an access control list to an a
type of object (Document, Tags, Folders) before it is created. It is the default
permissions an object will have when it is created. With Default Access Control Lists
specific permissions can be granted to the creator of a document por example.
**Example 1.** Each user have to access only the documents that he uploads
The example will show how to restrict a user in order not to view documents uploaded by other users, but only by himself. For that purpose we have to restrict the access to something that does not exist yet. The system must know that before the actual upload in order to act accordingly. This is where Default ACLs come in place.
Follow the steps:
1. Enter **Mayan EDMS** with user that has administrative rights.
2. Go to Setup menu. Enter Default ACLs submenu.
3. Click ``New holder`` next to the class Documents. From the list of users choose the special user Creator. Give the permission ``View Documents`` to the Creator.
4. Go back to Setup menu. Go to Users and create the users ``Pedro`` and ``Sancho``.
5. Go back to Setup menu. Go to Groups and create the group ``Employees``. Click to members of the groups and add ``Pedro`` and ``Sancho`` to that group.
6. Go back to Setup menu. Go to Roles submenu. Create the role ``Uploaders``. Give the permission ``Create documents`` to the role. Add the group ``Employees`` as a member to that role.
7. Now enter **Mayan EDMS** with ``Pedro`` and ``Sancho`` one after another and upload documents. Pedro should not see the documents that ``Sancho`` uploaded and vice versa. He should see only documents uploaded by himself.
The above example will work only for documents that are uploaded after the activation of the restriction. It will not work for documents prior to the activation of the restriction.
Changes to the Default Access Control Lists (Default ACLs) only affect objects
created after the change, it will not work for documents previously uploaded.

36
docs/topics/signatures.rst
View File

@@ -2,31 +2,23 @@
Document signatures
===================
**Mayan EDMS** supports two types of document signatures, these are embedded and
detached signatures. When a document with an embedded signature is
uploaded, this signature is readily detected as part of the document
inspection step. If the public key corresponding to the signee of the
document is not found, **Mayan EDMS** will try to obtain it from the list of
keyserver specified in the config option :setting:`SIGNATURES_KEYSERVERS`.
Failing that, **Mayan EDMS** will indicate that the document is signed
but that it has no way to verify such signature.
Existing non signed documents can be signed in one of two way:
by downloading the document, signing it, and uploading the signed document
as a new version of the existing one using **Mayan EDMS** :doc:`versioning support <versioning>`
or by creating a detached signature for the non signed document and uploading
such detached signature file using the option likewise named menu option.
**Mayan EDMS** supports two types of document signatures, these are embedded and
detached signatures. When a document with an embedded signature is
uploaded, this signature is readily detected as part of the document
inspection step, the status of the signature can then be verified by accessing the
signatures sections of a documents.
Maintenance of the public keyring can be done using the ``Key management``
functionality in the ``Setup menu``
Existing non signed documents can be signed in one of two ways:
by downloading the document, signing it, and uploading the signed document
as a new version of the existing one or by creating a detached signature for
the non signed document and uploading such detached signature file.
From this menu, key servers can be queried
and the results imported. Public keys no longer needed can also be deleted
from this menu.
Maintenance of the public keyring can be done using the ``Key management``
functionality in the ``Setup menu``.
Only `GNU Privacy Guard`_ signatures are support at the moment. In case
your installation of GnuPG is non-standard, you can use the :setting:`SIGNATURES_GPG_HOME`
configuration option to let **Mayan EDMS** find your GPG instance's home directory, used to
store keyrings and other GPG configuration files.
From this menu, key servers can be queried and the results imported. Public
keys no longer needed can also be deleted from this menu.
Only `GNU Privacy Guard`_ signatures are support at the moment.
.. _`GNU Privacy Guard`: www.gnupg.org/

163
docs/topics/smart_links.rst
View File

@@ -3,165 +3,12 @@ Smart links
===========
Smart links are usefull for navigation between documents. They are rule
Smart links are usefull for navigation between documents. They are rule
based but don't create any organizational structure, just show the documents
that match the rules as evaluated against the metadata of the currently
displayed document.
**Details**
To create a Smart Link, a user with adequate permissions first clicks on the
"Settings" tab in the top menu, then click on the "Smart Links" button. The screen
for creating a new (or editing an existing) Smart Link requires you to name the
Link and to ensure it is enabled if you wish to user it. Optionally, "Dynamic title"
may be created. The Dynamic title is entended to contain references to attributes
of a document or it's metadata. Let's cover some simpler cases and come back to
dynamic references below.
*Static Links*
Smart links don't actually have to be overly smart. As a gentle introduction, lets
create a simple "static" link which will show all the documents added in the year
2014. We'll use the title "Added in 2014", leave the dynamic title empty, and ensure
that "Enabled" is checked.
To have the link actually do something, we have to add one or more "condition".
Conditions are translated by the system into clauses in a query (search) of the
document database. There is a "Create condition" link in the right-bar of the Smart
Link screen. For our simple case, the value of the "Inclusion" drop down does not
matter; we can leave it at the default "AND". For "Foreign document data" we will
enter:
document.date_added
For "Operator" we will select "contains".
For "Expression" we will enter:
2014
Underneath this field, "negated" should be unchecked and "enabled" should be checked.
Save the condition then go to the documents tab. Click on the filename of any file
listed there. Click on the "Smart link" tab under the submenu. A list of all
documents entered in 2014 (if any) should be shown.
There are a number of other document attributes which can be used in searches, with
some important caveats:
* date_added: (discussed above)
* comments: this is next to useless at present, since instead of searching through
text of all comments you can instead search for the "id" of comments.
* description: enclose the text you want to search for in 'single' or "double" quotes.
* document_type: can be used if Document Types have been defined and assigned to docs
as they have been uploaded. The search is performed against the "id" of the document_type
and not against the textual description of the Document Type. This limitation,
however, is hidden if used in a dynamic link as demonstrated below.
* documentcheckout: a meaningful query clause can be consructed by choosing this
documnet attribute and testing if it "is equal to" 1 (for "true" or "is checked out")
or 0 (for "false" or "is not checked out")
* documentrenamecount: this attribute is reported by the system as available for
searching but it's utility is not clear
* folderdocument: This attribute searches agains the "id" of the folder to which
a document may have been added, not against the textual name of a folder and thus
is useful primarily in dynamicly defined links (see below).
* id: each document has a unique numeric id which can be used in searches
* indexinstancenode: ??
* metadata: ?? (see below)
* queuedocument: ??
* recentdocument: this attibute appears to hold an integer (simple number like 1,2,3)
indicating the relative order in which documents were added to the system. This
may be of some use for finding documents which were added before or after a given
document.
* tagged_items: using this attribute by entering in an integer value appears to
perform a search equivalent to "if document has at least one tag and this id number"
* tags: the "id" value of the corresponding tags are used. A tag will be matched if it
is alone or among several tags assigned to a document.
* uuid: of little value, since these are by definition unique.
* versions: ??
You can also define Smart Links based on Metadata types and values which you have
defined. For this to work, it appears to be necessary to give the metadata type "Name"
(also known as "Internal name") which is all lowercase. The "Title" can be uppercase.
For instance, if a metadata type is defined with these values:
Name: priority
Title: Priority
Default: 5
Lookup: (1,2,3,4,5,6,7,8,9,10)
Then I can assign various documents different priorities and create a "Smart Link"
to find the high priority links by defining the condition as
Inclusion: and
Foreign document data: is greater or equal to
Expression: 5
*Dynamic Smart Links*
Links which are truly Smart are created by referencing the current value of the
document you are viewing and not a static value in at least one of the conditions.
For instance, the last example above can be modified so that the Smart Link is:
Inclusion: and
Foreign document data: is greater or equal to
Expression: metadata.priority
By including "metadata.priority" as the Expression instead of a static value, we
now have a Smart Link which will find all other documents with a Priority metadata
value greater than or equal to the one we are viewing.
Here's an example by Mathias from the forums
(<https://groups.google.com/forum/#!topic/mayan-edms/nO5DFB1udhc>) which
demonstrates how to find other documents in the same project, if "project" has
been defined as a Metadata type. This example shows how to use the Dynamic Title
feature also.
Title: Same project
Dynamic title: u'All documents of: %s' % getattr(metadata, 'project', 'None')
Condition:
Inclusion: and
Foreign document data: metadata.project
Operator: equal
Expression: metadata.project
The document attributes listed above which use the "id" value to do matching are
more useful for dynamic than static conditions. For instance we can set both the
foreign and current document Expressiong to "document.document_type" to get a
Smart Link to all other documents of the same Document Type as the current one.
*Combining Conditions*
In theory we should be able to add multiple conditions and choose "and" or "or"
to define how they interact with the previous condition. There does not appear
to be a mechanism for defining parenthises to group conditions, but such subtleties
are far beyond the current state of this funcitonality as even the simplest cases
appear not to work. Defining to conditions, each of which yeild a set with
documents in common, and then combining them with "and" yeilds no documents at all.
Switching to "or" returns the same documents multiple times.
*Tricky Smart Links*
Advanced users can explore ways to use regular expressions in Smart Links. For
example, one might want easy access to documentation for software features not
yet in production by using:
Foreign document data: document.description
Operator: is in regular expression (case insensitive)
Expression: r'test|experimental|development'
Smart links are usefull when a patient file in a patients index needs to be linked
to the medical documentation of a prescription the patient is using, but that medical
documentation is in it's own prescription index. Smart links can provide a reference
between documents of different indexes without any change in the indexes' structures.

6
docs/topics/tags.rst
View File

@@ -2,8 +2,8 @@
Tags
====
Tags allow giving documents a toggable property. Documents can also be tagged
with more than one tag. Once tagged, documents can be search also by their tags
Tags allow giving documents a toggable property. Documents can also be tagged
with more than one tag. Once tagged, documents can be search also by their tags
and from the tags main menu a list of all the documents with a particular tag
can be obtained easily. Aside from their texts, tags can be assigned a particular
can be obtained easily. Aside from their texts, tags can be assigned a particular
color.

2
docs/topics/transformations.rst
View File

@@ -9,4 +9,4 @@ source would be "rotation: 270 degress", this way whenever a document is
uploaded from that scanner it appears in portrait orientation.
The transformation remains attached to the document, this way the file
is preserved in it's original state (a requirement in legal environments)
but only the representation is transformed to make it look right to the user.
but only the representation is transformed.

20
docs/topics/versioning.rst
View File

@@ -3,20 +3,12 @@ Document versioning
===================
**Mayan EDMS** has the ability to store different versions of the same
document. Users are provided with a very comprehensive but easy to use
version numbering system that allows specifying a major, minor or micro
version number increase.
A comment field is also provided to allow users
to summarize the new verdion changes in comparison with the previous
one. If a new version was uploded by mistake or such new version is no
longer necessary **Mayan EDMS** provides the option to revert to a previous
version of the document.
document. A comment field is provided to allow users to summarize the new
version changes in comparison with the previous one. If a new version was
uploded by mistake or such new version is no longer necessary the option to
revert to a previous version of the document is provided.
To upload a new document version, select an existing document, click on the
version tab of the document, and click on the 'upload new version' on the
side bar. A new view very similar to the new document upload view will
appear show the same interactive document sources that have been defined,
but with new options to specify the new version number and an optional
comment.
side bar. A new view very similar to the new document upload view will
appear, showing the same interactive document sources that have been defined.