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-10-19 06:15:54 -04:00
parent 24d0866d8b
commit 6f6270f11c
11 changed files with 186 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/topics/acls.rst Normal file
View File

@@ -0,0 +1,51 @@
====================
Access control lists
====================
Besides the permissions system explained in :doc:`permissions`, **Mayan EDMS**
provides per object permission granting. This feature is used to grant a
permission to a role, but this permission can only be executed for a limited
number of objects (documents, folders, tags) instead of being effective
system-wide.
.. blockdiag::
blockdiag {
document [ label = 'Document' ];
role [ label = 'Role' ];
permission [ label = 'Permission' ];
role -> document <- permission;
}
Example:
.. blockdiag::
blockdiag {
document [ label = '2015 Payroll report.txt', width=200 ];
role [ label = 'Accountants' ];
permission [ label = 'View document' ];
role -> document <- permission;
}
In this scenario only users in groups belonging to the ``Accountants`` role
would be able to view the ``2015 Payroll report.txt`` document.
Inherited access control
========================
It is also possible to grant a permission to a role for a specific document type.
Under this scheme all users in groups belonging to that role will inherit that
permission for all documents of that type.
Example:
Role ``RH Supervisors`` are given the permission ``document view`` for the
document type ``Payroll reports``. Now all users in groups belonging to the
``RH Supervisors`` role can view all documents of the type ``Payroll reports``
without having to have that permissions granted for each particular Payroll report document.
If access control for the Payroll reports documents need to be updated it only needs
to be done for the document type class object and not for each document of the type
Payroll report.

28
docs/topics/deploying.rst
View File

@@ -3,26 +3,30 @@ Deploying
=========
Like other Django based projects **Mayan EDMS** can be deployed in a wide variety
of ways. The method provided below is only provided as a bare minimum example.
These instructions asume you installed **Mayan EDMS** as mentioned in the
Installation chapter.
of ways. The method provided below is only a bare minimum example.
These instructions asume you installed **Mayan EDMS** as mentioned in the :doc:`installation` chapter.
Install the system dependencies:
Install more system dependencies::
sudo apt-get install nginx supervisor redis-server
sudo apt-get install nginx supervisor redis-server postgresql
- Postgresql pg_hba.conf
- Postgresql user
- Postgresql database
Switch and activate the `virtualenv` where you installed **Mayan EDMS**. Install
the Python client for redis:
the Python client for redis and uWSGI::
pip install redis
pip install redis uwsgi
Install the Python application server gunicorn:
pip install gunicorn
Update the settings/local.py file:
Update the settings/local.py file::
BROKER_URL = 'redis://127.0.0.1:6379/0'
CELERY_ALWAYS_EAGER = False
CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'
- NGINX site
- SUPERVISOR uwsgi
- SUPERVISOR worker

16
docs/topics/development.rst
View File

@@ -347,18 +347,20 @@ Likewise, to see the debug output of the ``tags`` app, just add the following in
Documentation
-------------
**Mayan EDMS**'s documentation is written in `reStructured Text`_ format.
The documentation is written in `reStructured Text`_ format and resides in the
``docs`` directory. In order to build it, you will first need to install
Sphinx_. ::
The documentation lives in the ``docs`` directory. In order to build it, you will first need to install Sphinx_. ::
$ pip install sphinx
$ pip install -r requirements/documentation.txt
Then, to build an HTML version of the documentation, simply run the following from the **docs** directory::
Then, to build an HTML version of the documentation, simply run the following
from the **docs** directory::
$ make html
$ make livehtml
Your ``docs/_build/html`` directory will then contain an HTML version of the documentation, ready for publication on most web servers.
Your ``docs/_build/html`` directory will then contain an HTML version of the
documentation.
You can also generate the documentation in formats other than HTML.

17
docs/topics/document_types.rst Normal file
View File

@@ -0,0 +1,17 @@
==============
Document types
==============
The basic unit of data in **Mayan EDMS** is the ``document type``. A document type
can be interpreted also as a document category, a document class, or a
document template. Document types need to be created before documents can be
uploaded. It is not possible to upload documents without assigning them a
document type. Examples of document type: **invoices**, **blueprints**,
**receipts**.
Settings and attributes are applied to document types and documents will
inherit those settings and attributes based on the document type they were
assigned when uploaded into **Mayan EDMS**. A document can only be of one
type at a given moment, but if needed, the type of a document can be changed.
Upon changing its type, the document will lose its previous settings and
attributes, and will inherit the settings and attributes of its new type.

31
docs/topics/file_storage.rst
View File

@@ -3,15 +3,26 @@ File storage
============
The files are stored and placed under **Mayan EDMS** "control" to avoid
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
filename clashes each file gets renamed to its ``UUID`` (Universally Unique ID),
without extension, and stored in a simple flat arrangement in a directory.
.. blockdiag::
blockdiag {
file [ label = 'mayan_1-1.pdf', width=120];
document [ label = 'mayan/media/document_storage/ab6c1cfe-8a8f-4a30-96c9-f54f606b9248', width=450];
file -> document [label = "upload"];
file -> document;
}
This doesn't stop access to the files but renaming, moving or updating
directly them is not recommended because it would throw the database out
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?
All the other parts don't make any assumptions about the actual file
storage, files can be saved locally, over the network or even across the
internet and everything will still operate exactly the same.
Because **Mayan EDMS** components are as decoupled from each other as possible,
storage in this case is decoupled and its behavior is controlled
not by the project but by the ``Storage`` module class. All the other
modules don't make any assumptions about how the actual document files are
stored. This way files can be saved locally, over the network or even across
the internet and everything will still operate exactly the same.

6
docs/topics/index.rst
View File

@@ -6,11 +6,15 @@ Introductions to all the key parts of Mayan EDMS you'll need to know:
.. toctree::
:maxdepth: 1
file_storage
document_types
metadata
permissions
sources
acls
transformations
versioning
signatures
indexes
smart_links
tags
file_storage

2
docs/topics/installation.rst
View File

@@ -129,7 +129,7 @@ Deploy **Mayan EDMS** using the webserver of your preference. For more informati
on deployment instructions and examples, checkout Django's official documentation
on the topic https://docs.djangoproject.com/en/1.6/howto/deployment/
For a simple production deployment setup follow the instructions in the
Deploying chapter <topics/deploying>
:doc:`deploying` chapter.
Other database managers

28
docs/topics/metadata.rst Normal file
View File

@@ -0,0 +1,28 @@
========
Metadata
========
Metadata is the name of the attribute of a document. The concept of metadata is
divided in two: **metadata types** (size, color, distance) and **metadata values** for
those types. Metadata types are defined in the setup menu and associated with
document types. Then when a document is uploaded, a value for that metadata
can be entered. There are two kinds of metadata type to document type relations:
optional and required. When a metadata type is optional for a document type,
it can be left blank for a document being uploaded and the upload will still
be successfull. On the other hand required metadata type must be given a value
or it will not be possible to upload the document at hand.
Examples of metadata type: Invoice number, color, employee id.
The data entry of metadata types can be set to allow any value to be provided
(the default) or a list of possible values can be entered in the ``Lookup``
configuration option and users will be presented with a drop down list of options
instead of the default text entry box.
If metadata types are setup to allow any value to be entered a ``validation`` option
can be choosen to block the entry of invalid data. Metadata types also provide
``parsers`` which will not block the entry of data but are able to interpret and
modify the value provided by the user to a conform to a specific format.
An example of a provided parser is the date parser which will interpret and
correct dates provided by users regardless of the format in which they are
entered.

49
docs/topics/permissions.rst
View File

@@ -2,40 +2,25 @@
Permissions
===========
**Mayan EDMS** provides finegrained control over which activities users can
perform. This control is divided into two levels of operation:
**Mayan EDMS** provides very fine control over which actions users can
perform. Action control works by allowing ``roles``, that are composed of ``groups``
of ``users`` to be granted a ``permission`` such that the holder of that permission
can exercise it throughout the entire system.
2 tier permissions assignement
==============================
.. blockdiag::
This level of activity control works by allowing roles that are composed
of groups or users, to be granted a permission such that the holder of that
permission can exercise it throughout the entire collection of objects
(document, folders, tags, etc). This method could be thought out as a global
permission.
blockdiag {
user [ label = 'Users' ];
group [ label = 'Groups' ];
role [ label = 'Roles' ];
permission [ label = 'Permissions' ];
3 tier access control
=====================
When more control is desired over which roles can exercise an action, this
method should be used. Under this method, roles are granted a permission but
only in relation to a selected object. Example: Granting role
``Accountants`` the ``Document view`` permission for document ``2015 Payroll report.txt``, would
allow only users in groups belonging to the ``Accountants`` role to view this document.
user -> group -> role <- permission;
}
Inherited access control
========================
It is also possible to grant a permission to a role for a specific document type.
Under this scheme all users in groups belonging to that role will inherit that
permission for all documents of that type.
Example:
Role ``RH Supervisors`` are given the permission ``document view`` for the
document type ``Payroll reports``. Now all users in groups belonging to the
``RH Supervisors`` role can view all documents of the type ``Payroll reports``
without having to have that permissions granted for each particular Payroll report document.
If access control for the Payroll reports documents need to be updated it only needs
to be done for the document type class object and not for each document of the type
Payroll report.
In other words, users themselves
can't hold a permission, permissions are granted only to roles. Users can't
directly belong to a role, they can only belong to a group. Groups can be
members of roles. Roles are system permission units and groups are
business organizational units.

11
docs/topics/sources.rst Normal file
View File

@@ -0,0 +1,11 @@
=======
Sources
=======
Document sources define from where documents will be uploaded or gathered.
To 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 form``.
``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.

21
docs/topics/transformations.rst
View File

@@ -1,12 +1,11 @@
=========================
What are transformations?
=========================
===============
Transformations
===============
Transformation are useful to manipulate the preview of the stored documents
in a persistent manner, for example some scanning equipment only produce
landscape PDFs, in this case a default transformation for that document
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, the file being
preserved in it's original state (a requirement in legal environments) and
only the representation being transformed.
Transformation are persistent manipulations to the previews of the stored documents.
For example: a scanning equipment may only produce landscape PDFs.
In this case an useful transformation for that document source would be to
rotate all documents scanned by 270 degress after being uploaded, this way
whenever a document is uploaded from that scanner it will appear in portrait
orientation. Transformations do not physically modify the document file but
are just associated with the document's temporary graphical representation.