Add workflow and API chapter. Expand tags chapter.

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>

docs/chapters/api.rst

@@ -0,0 +1,28 @@
+***
+API
+***
+
+Mayan EDMS provides an HTTP REST Application Program Interface (or API). This
+API allows integration with 3rd party software using simple HTTP requests.
+
+Several API authentication methods are provides: **Session**, **Token**,
+and **HTTP Basic**.
+
+The URL for the API can be found via the :menuselection:`Tools --> REST API
+menu. The API is also self-documenting. The live API documentation can be
+found in the :menuselection:`Tools --> API Documentation (Swagger)` menu for
+the Swagger version and in the
+:menuselection:`Tools --> API Documentation (ReDoc)` menu for the ReDoc version.
+
+The are a few ways to structure REST APIs. In the case of Mayan EDMS, API
+endpoints are structured by resource type. Examples:
+
+* /cabinets - To view or create new cabinets
+* /cabinets/<id> - To view the details, edit, or delete an existing cabinet.
+* /cabinets/<id>/documents - To view, add, or remove documents from an existing
+  cabinet.
+* /cabinets/<id>/documents/<id> - To view, add, or remove one document from an
+  existing cabinet.
+
+The API supports the HTTP verbs: **GET**, **POST**, **PUT**, **PATCH**,
+and **DELETE**.

docs/chapters/index_examples.rst

@@ -16,6 +16,7 @@ links to the document of each respective type.
 #. Select :menuselection:`New child node` to create a new level in which the
    following template code will be entered.
    ::
+
        {{ document.document_type }}
 
 #. Save the template.
@@ -63,16 +64,19 @@ sub level for months.
 
 **First level: Year**
 ::
+
     {{ document.metadata_value_of.date_issued|slice:"0:4" }}
 
 
 **Second level: Months**
 ::
+
     {{ document.metadata_value_of.date_issued|slice:"5:7" }}
 
 
 **Optional: Third level: Day**
 ::
+
     {{ document.metadata_value_of.date_issued|slice:"8:10" }}
 
 

docs/chapters/indexes.rst

@@ -1,3 +1,5 @@
+.. _indexes:
+
 Indexes
 =======
 

docs/chapters/metadata.rst

@@ -1,3 +1,5 @@
+.. _metadata:
+
 ********
 Metadata
 ********

docs/chapters/sources.rst

@@ -1,3 +1,5 @@
+.. _sources:
+
 Sources
 =======
 

docs/chapters/tags.rst

@@ -1,8 +1,23 @@
 Tags
 ====
 
+Tags are color coded properties that can be attached or removed from documents.
 Tags allow giving documents a binary property. Documents can also be tagged
-with more than one tag. Once tagged, documents can be searched 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 color.
+with more than one tag.
+
+Tags are created from the :menuselection:`Tags --> Create` menu.
+
+To view all created tags use the :menuselection:`Tags --> All` menu.
+
+Once tagged, documents can be searched by their tags. It is also possible to
+show all the documents tagged with a particular
+tag via the **Documents** link of each tag.
+
+To view, add, or remove tags from a specific document, go to the document view
+and click on the **Tags** tab. This view will show the current tags of a
+document. The **Actions** menu will now show two new options: one to attach
+more tags to the document and another to remove tags from the document.
+
+It is also possible to tag documents in bulk by selecting several documents
+from any view that displays a list documents and selecting the **Attach tag**
+or **Remove tags** from the dropdown menu.

docs/chapters/workflows.rst

@@ -0,0 +1,91 @@
+*********
+Workflows
+*********
+
+Introduction
+============
+
+Workflows provide a structure method for storing a sequence of states over
+which the a document will progress. Workflows keep track how a document has
+been processed so far.
+
+Workflows work by storing a series of states to help you know the "status"
+of a document. To move a workflow from one state to another, transitions are
+used.
+
+Transitions connect two different states and help provide context to know
+which state is possible to transition to, from a previous state. Transitions
+provide and order for the sequence of possible states changes.
+
+Transitions can be executed manually by users if they have the required access
+level as configure by the system administrator.
+
+
+Automation
+==========
+
+Besides being able to be executed manually by users, transitions can also be
+programmed execute automatically based on system events. This is called in
+Mayan EDMS transition triggering and is one of the tools available to
+automate business processes.
+
+For example:
+
+* Move a document from a "scanned" state to a "billed" state
+  when a tag is attached to the document.
+* Move a document from a "uploaded" state to a "OCR ready" state
+  when the OCR engine finishes processing the document.
+
+The other tool provided for process automation is being able to execute an
+action when a workflow state is reached or leaved. These are called state
+events.
+
+Some examples of state actions currently provided are:
+
+* Attach a tag to a document
+* Remove a tag from a document
+* Do an HTTP POST request to an external IP address
+* Edit the label or the description of a document.
+
+Other time more state actions are being added. Some state actions like the one
+that creates an HTTP POST request allow Mayan EDMS to trigger processes in
+external systems based on the state of a document. One example of this is
+triggering the billing process of an accounting system when an invoice is
+scanned in Mayan EDMS.
+
+Workflow state actions and transitions triggers are new features and are still
+evolving.
+
+Workflows allow translating business logic into a series of states. With the
+addition of state actions and transition triggers, the workflows in Mayan EDMS
+are no longer just informative but can be part of your actual business
+automation process.
+
+
+Implementation
+==============
+
+Internally, workflows are implemented as a finite state machines
+(https://en.wikipedia.org/wiki/Finite-state_machine). And have the limitation
+that only one state can be the current active state for a workflow being
+executed. The other limitation of the current implementation is that every
+workflow needs at least one state marked as the initial state. These limitations
+are the result of a compromised in the design between flexilibiy and ease of
+use.
+
+
+Visualizations
+==============
+
+The graphical representation of a workflow (or a finite state machine style
+in Mayan EDMS's case) is similar to a flowchart. The states are presetended
+with circles. The transitions are represented with arrows. Circle with a
+double border represent the initial state of the workflow.
+
+To view the graphical representations of workflow use **Preview** button of
+the workflow in the setup view.
+
+
+
+We are working now on workflow transition trigger filters to have
+the trigger move the state of the workflow on certain conditions. For example: Attach a tag if there is a specific word found in the OCR text.

docs/index.rst

@@ -26,6 +26,7 @@ repository for electronic documents.
     Collaboration <topics/collaboration>
     Settings <topics/settings>
     Storage <topics/storage>
+    Integration <topics/integration>
     Maintenance <topics/maintenance>
     Advanced topics <topics/advanced>
     Development <topics/development>

docs/releases/0.12.rst

@@ -47,7 +47,7 @@ ACL support
   tags and smart links.  What this means is that administrators can now
   grant permissions to users, groups or roles on for specific objects.
   A more in-depth explanation of how this new ACL system can be found in
-  the :doc:`3 tier access control <../topics/permissions>` section of the
+  the :doc:`3 tier access control <../chapters/permissions>` section of the
   permissions chapter.
 
 * Default class ACL support.  Administrators can setup the access control
@@ -107,7 +107,7 @@ in the Initial data loading chapter.
 
 Refactored document indexing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:doc:`The document indexing  <../topics/indexes>` functionality has been
+:doc:`The document indexing  <../chapters/indexes>` functionality has been
 improved and moved from experimental
 stage to beta stage.  Index configuration menus are now available on the
 ``Setup`` menu and allows administrators to create skeleton trees that will

docs/topics/advanced.rst

@@ -3,6 +3,7 @@ Advanced topics
 ###############
 
 
+.. include:: ../chapters/workflows.rst
 .. include:: ../chapters/languages.rst
 .. include:: ../chapters/signatures.rst
 .. include:: ../chapters/metadata.rst

docs/topics/features.rst

@@ -57,12 +57,12 @@ Features
   * Automatic linking of documents based on metadata values or document
     properties.
 
-* :doc:`Roles support <../topics/permissions>`.
+* :doc:`Roles support <../chapters/permissions>`.
 
   * It is possible to create an unlimited amount of different roles not being
     restricted to the traditional admin, operator, guest paradigm.
 
-* :doc:`Fine grained permissions system <../topics/permissions>`.
+* :doc:`Fine grained permissions system <../chapters/permissions>`.
 
   * There is a permission for every atomic operation performed by users.
 
@@ -87,12 +87,12 @@ Features
   * The current language of the document is passed to the corresponding OCR
     engine to increase the text recognition rate.
 
-* :doc:`Plugable storage backends <../topics/file_storage>`.
+* :doc:`Plugable storage backends <../chapters/file_storage>`.
 
   * It is very easy to use 3rd party plugins such as the ones available for
     Amazon EC2.
 
-* Color coded tagging.
+* Color coded <../chapters/tags>`.
 
   * Labeled and color coded tags can be assigned for intuitive recognition.
 

docs/topics/installation.rst

@@ -42,7 +42,7 @@ Direct installation
 
 For users with knowledge of Python, Django, Ubuntu, and databases.
 
-Deployments chapter: :ref:`development`
+Deployments chapter: :ref:`deploying`
 
 
 .. _Docker: https://www.docker.com/

docs/topics/integration.rst

@@ -0,0 +1,6 @@
+###########
+Integration
+###########
+
+
+.. include:: ../chapters/api.rst