diff --git a/docs/topics/acls.rst b/docs/topics/acls.rst new file mode 100644 index 0000000000..37b1c116ed --- /dev/null +++ b/docs/topics/acls.rst @@ -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. diff --git a/docs/topics/deploying.rst b/docs/topics/deploying.rst index 53a2f0459f..0cff15ae39 100644 --- a/docs/topics/deploying.rst +++ b/docs/topics/deploying.rst @@ -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 + diff --git a/docs/topics/development.rst b/docs/topics/development.rst index 38f57fa6df..f8836f5a36 100644 --- a/docs/topics/development.rst +++ b/docs/topics/development.rst @@ -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. diff --git a/docs/topics/document_types.rst b/docs/topics/document_types.rst new file mode 100644 index 0000000000..40359e5f38 --- /dev/null +++ b/docs/topics/document_types.rst @@ -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. diff --git a/docs/topics/file_storage.rst b/docs/topics/file_storage.rst index 514aef7141..5478fea9c9 100644 --- a/docs/topics/file_storage.rst +++ b/docs/topics/file_storage.rst @@ -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. diff --git a/docs/topics/index.rst b/docs/topics/index.rst index 8ec133f1e9..c0eed87150 100644 --- a/docs/topics/index.rst +++ b/docs/topics/index.rst @@ -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 diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst index 4a377fa049..b907877e2b 100644 --- a/docs/topics/installation.rst +++ b/docs/topics/installation.rst @@ -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 +:doc:`deploying` chapter. Other database managers diff --git a/docs/topics/metadata.rst b/docs/topics/metadata.rst new file mode 100644 index 0000000000..7ccbdab7df --- /dev/null +++ b/docs/topics/metadata.rst @@ -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. diff --git a/docs/topics/permissions.rst b/docs/topics/permissions.rst index 513c874614..00c1c5b227 100644 --- a/docs/topics/permissions.rst +++ b/docs/topics/permissions.rst @@ -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. diff --git a/docs/topics/sources.rst b/docs/topics/sources.rst new file mode 100644 index 0000000000..78399733d7 --- /dev/null +++ b/docs/topics/sources.rst @@ -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. diff --git a/docs/topics/transformations.rst b/docs/topics/transformations.rst index 8f39d90de4..178c7b895e 100644 --- a/docs/topics/transformations.rst +++ b/docs/topics/transformations.rst @@ -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.