V. Users, Groups, Roles & ACL

To show how roles and ACLs can be used to simplify Mayan users UX (users experience) we will create two groups. One will be for people uploading and supervising the document flow and another with the users that actually do work with the documents.

I. Users

As for users the ones to be used are for:

  • Control Desk – Will receive and upload the documents
  • Analyst – generates the response to the claim
  • Expert – authorizes or rejects the claim

How To

  • [System-Select] > Setup
  • Click ‘Users’
  • Click on ‘Create new user’ or
    [Action-Select] > Create new user
  • Type (for each user)
    Username, First Name, Last Name, email
    Click ‘Save’
  • In the next screen type twice the password you like. It could be the same for all users in this test. (I use Password54321).
    Click ‘Submit’
    Note: You can enforce different levels of complexity for your passwords in [System-Select] > Setup, Click ‘Settings’ then ‘Django’ button and set ‘AUTH_PASSWORD_VALIDATORS’.
UsernameFIRST NameLAST nameEmail
jsmithJamesSmithjsmith@urexample.com
adowAnnaDowadow@urexample.com
hbrownHectorBrownhbrown@urexample.com

II. Groups

As we said we will use two groups.

How To

  • [System-Select] > Setup
  • Click ‘Groups’
  • Click on ‘Create new group’ or
    [Action-Select] > Create new group
  • Type (for each user)
    Name
    Click ‘Save’

The groups are:

  • Control Desk
  • Workgroup

Associate Users to Groups

How To

  • [System-Select] > Setup
  • Click ‘Groups’
  • On each of the [Item Options] click ‘Users’ Button
    Select from the left panel the ‘Available User’
    Click ‘+Add’
  • To return to the Groups page:
    [Acion-Select] > Groups
Group [Item Option]UserFunction in test
Control DeskjsmithReceiver
Workgroupadow
hbrown
Analyst
Expert

III. Access Control : Role

Mayan posses a Rol-Based Access Control (RBAC) security approach to configure system privileges to users.

How to

  1. Rol‘ granted permissions allow system wide access.
    For our ‘Control Desk’ group we use a ‘Rol’ with all the permissions will be assigned, except for deleting files, emptying the trash and impersonating other users.
  2. For our two ‘Workgroup’ we use ‘Access Control List (ACL)’, we can select items (Workflows, States, Documents, Indexes, Cabinets, Tags) and then choose the group and permissions specific for that object.

How-To [Roles]

  • [System-Select] > Setup
  • Click ‘Roles’
  • Click on the button ‘Create new role’ or
    [Action-Select] > ‘Create new role’
  • Type:
    Label: Control Desk role
    Click ‘Save’

Repeat for ‘Workgroup Role’.

Now associate our roles to our groups

  • [System-Select] > Setup
  • Click ‘Roles’
  • On ‘Control Desk Role’ [Item Option] click ‘Groups’ button
  • On the left panel select ‘Control Desk’
    Click ‘+Add’
  • To return to the role page
    [Action-Select] > Roles

Then repeat the steps but assign:
– ‘Workflow Role’ to group: ‘Workflow’


After setting the permissions that we will do in the following paragraphs for the group that acts like a ‘supervisor’ the Roles page looks like this:

  • [System-Select] > Setup
  • Click ‘Roles’
  • On the ‘Control Desk’ [Item Option] click on ‘Role permissions’
  • Click on the ‘+Add all’ button
  • Now browse on the right panel for each of the following permissions and click on ‘Remove’ button:
    • Documents > Delete documents
    • Documents > Empty trash
    • Documents > Restore trashed documents
    • Authentication > Impersonate users

Those actions should be done by the administrator or an special account. In that way you browsed over many permissions that the system offers.

How-To [ACL]

For ACL our Workgroup will need permissions to see ‘Document types’, ‘Workflows’, ‘indexes’, ‘Tags’.

First associate our ‘Claim’ document type just to the ‘Workflow 1’:

  • [System-Select] > Setup
  • Click ‘Document Types’
  • On the ‘Claims’ [Item Option] click on the ‘ACLs’ button
  • Click on ‘New ACL’ or
    [Action-Select] > New ACL
    Select ‘Workflow Role’
    Click ‘Save’
  • On the ‘Access control list for: Claim’ page
    And on the ‘Workflow Role’ [Item Option] click on the ‘Permissions’ button
  • On the “Role Workflow Role permissions for ‘Clam'”
    Click ‘+Add All
    Then to reduce de buttons available to users, select from the right panel and click ‘Remove’:
    • Common > Copy object
    • Converter > Create new transformations
    • Converter > Delete transformations
    • Converter > Edit transformations
    • Document types > Delete document types
    • Document types > Edit document types
    • Documents > Delete documents

It should look like this:

Now will be setting special permissions for the ‘Workflow’ group.

So it can see the workflow:

  • System-Select] > Setup
  • Click ‘Workflows’
  • On the [Item Option] ‘Claims Workflow’ click on the ‘LCAs’ button
  • Click on ‘New LCA’ or
    [Action-Select] >
    Select ‘Workflow Role’
    Click ‘Save’
  • On the left panel select three available permissions:
    Document Workflows > Execute workflows tools
    Document Workflows > Transition workflows
    Document Workflows > View workflows
    Click ‘+Add’

So it can see indexes:

  • [System-Select] > Setup
  • Click ‘Indexes’
  • On the [Item Option] ‘Claims’ click on the ‘LCAs’ button
  • Click on ‘New LCA’
    Select ‘Workflow Role’
    Click ‘Save’
  • On the left panel select
    Indexes > View document index instances
    Indexes > View document indexes’
    Click ‘+Add’

And to see the Tags:

  • [left-menu] > Tags
  • Click ‘All’
  • On the [Item Option] ‘On Claim Review’ click on the ‘LCAs’ button
  • Click on ‘New ALC’ button
    Select ‘Workflow Role’
    Click ‘Save’
  • On the left panel select
    Tags > View tags
    Click ‘+Add’
  • [left-menu] > Tags
  • Click ‘All’
  • On the [Item Option] ‘On Expert’ click on the ‘LCAs’ button
  • Click on ‘New ALC’ button
    Select ‘Workflow Role 1’
    Click ‘Save’
  • On the left panel select
    Tags > View tags
    Click ‘+Add’

That is for our example but now you can assign permission to access just a State or documents in that state/tag. With another document type you can work with the same workflow or another one special documents that the other workgroups wont see. And with transitions you can even change privileges (ACL) or even send emails or ask Mayan or other systems to to perform actions via their API.

IV. Mayan EDMS – Workflow, State, Transitions & Automation

I. Workflow

Workflow implementation in Mayan EDM consist of:

  • States. Similar to ‘Activities’ in BPMN 2 notation
  • Transitions between States: named ‘Connections’ in BPMN 2.

With these two elements anyone can build a ‘sequence flow’ or ‘Workflow’. This is a great strength as you won’t need a specialist for modifications.

Now all you need is to assign a ‘Document Type’ to a ‘Workflow’ and you can move your document between States accordingly to your defined transitions.

How To

  • [System-Select] > Setup
  • Click ‘Workflows’
  • Click ‘Create a Workflow’ or
    Click [Action-Select] > ‘Create a Workflow’
  • Type:
    Label: Claims Workflow
    Internal name: ClaimsWorkflow
    Click ‘Save’

II. States

How To

Instructions to create our States for our example.

  • [System-Select] > Setup
  • Click ‘Workflows’
  • On ‘Claims Workflow’ [Item-Option] Click ‘States’
  • Click ‘Create State’ or
    [Action-Select] > ‘Create State’
  • Type:
    Label, Completion (that is an informative percent)
    Click ‘Save’

Use the following table

LabelCompletion (%)Initial
1. Received0Checked
2. Claim Review25
3. Expert50
4. Vault100

III. Transition

The transitions for our model are:

  • 1. Received > 2. Claim review
    We model just one analyst but you could add more states and transitions so the receiver can select bu type or you coul send the document automatically depending on your metadata. This one just shows the manual transition.
  • 2. Clain review > 3. Expert
    In this state a response will be added using a new version. You could use smart links also.
  • 3. Expert > 2. Clain review
    This will let us go backward in the flow.
  • 3. Expert > 4. Vault
    End of the workflow

How to

  • [System-Select] > Setup
  • Click ‘Workflows’
  • On the [Item Option] ‘Claims Workflow’ click on the ‘Transitions’ button.
  • For each transition:
  • [Action-Select] > Create transition
  • Type: Name, select ‘Origin State’ and ‘Destination State’
    Do not use the condition text area. In it you can type an expression so the transition is not enabled if the result is not empty.
    Click ‘Save’.
NameOriginDestination
To Claim Analyst1. Received2. Claim Review
To Expert2. Claim Review3. Expert
Reject3. Expert2. Claim Review
Archive3. Expert4. Vault

The Transitions on the workflow page (ordered by ‘Origin state) will look like this:


Associate a ‘Document type’ to a ‘Workflow’

Next lets associate the Workflow to a ‘Document type’

  • [System-Select] > Setup
  • Click ‘Workflows’
  • On the [Item Option] ‘Claims Workflow’ click on the ‘Document types’ button.
  • Select ‘Claim’ from the left panel and click on the ‘+Add’ button

IV. Automation

To place and remove Tags for classification, we can use actions that triggers on State entry or exit. Only The ‘Analyst’ and ‘Expert’ will hold Tags so the initial and last State will be outside this classification mechanism.

We will only use the place Tag and remove Tag events but there are plenty more, you can even call APIs with ‘Perform a POST request’ to Mayan itself or other systems.

How To

  • [System-Select] > Setup
  • Click ‘Workflows’
  • On the ‘Claims Workflow’ [Item Option click on ‘States’
  • On the [Item Option] ‘2. Claim Review’ click on ‘<>Actions’ button
  • Click ‘Create action’ button or
    [Action-Select] > Create action
  • Select ‘Tags > Attach Tag’
    Click ‘Submit’ button
  • Type:
    Label: Claim Review Entry
    Select on When: On Entry
    Select Tags: On Claim Review
    Click ‘Save’
  • Now remove the Tag on exit:
  • [Action-Select] > Create action
  • Select ‘Tags > Remove Tag’
    Click ‘Submit’ button
  • Type:
    Label: Claim Review Exit
    Select on When: On Exit
    Select Tags: On Claim Review
    Click ‘Save’
    To return to the States page click [Action-Select] > States

To save time the options for the Expert State the steps are:

StateActionLabelWhenTag
3. ExpertAttach tagExpert EntryOn EntryOn Expert
3. ExpertRemove tagExpert ExitOn ExitOn Expert

There is also an additional automatic action we can configure on the ‘1. Received’ State. Usually a scan document is named with a consecutive number, lets use our Metadata ID to rename the file.

  • [System-Select] > Setup
  • Click ‘Workflows’
  • On the ‘Claims Workflow’ [Item Option click on ‘States’
  • On the [Item Option] ‘1. Received’ click on ‘<>Actions’ button
  • Click ‘Create action’ button or
    [Action-Select] > Create action
  • Select ‘Workflows > Modify documents properties’
    Click ‘Submit’ button
  • Type:
    Label: Rename
    Select on When: On Exit
    Document label: {{ document.metadata_value_of.claimId }}
    Click ‘Save’

Diagram

To see a diagram with States, Transitions and Actions:

  • [System-Select] > Setup
  • Click ‘Workflows’
  • [Action-Select] > Preview

This is what we should have:

III. Mayan EDMS – Cabinets, Index and Tags

Catalog structure is a key factor in a document archival system. In Mayan EDMS we can use a fixed structure that we create or we can use a dynamic structure that can depend on the value of a metadata field.


I. Cabinet

If you want to use a predefined folder structure like the one you create in your computer with a file manager then you use ‘Cabinets’.

How To

First level is created by using:
[left-menu] > Cabinets > Create cabinet
Type the Label. Click ‘Save’

For Level 2:
In ‘Cabinets’ page.
On your recent [item option] click on the ‘Add new label’ button
Type the Label. Click ‘Save’

For further levels:
On your [item option] click on the ‘Details’ button
Select the level you want on the ‘Details of cabinets’ page.
Click on the ‘Add new level’ button
Type the Label. Click ‘Save’

To use a cabinet, on the file upload Step 4, you’ll select one or several ‘Cabinets’ from a drop down list:
Level 1
Level 1 / Level 2
Level 1 / Level 2 / level 3

This will not be implemented in our example.


II. Index

There is a better way to classify your documents, that is an automatic structure. You can use values on the metadata and the document will end up there. If you change the values, the file will be reclassified.

An example could be: 1st level is the Department and the net level would be the date received. The file will be named with the Claim number.

How to

We need to define a ‘Tree template’, first the Name or Label that we will use to refer to it:

  • [System-Select] > Setup
  • Click ‘Indexes’
  • [Action-Select] > Create Index
  • Type:
    Label: Claims
    Slug: claims
    Keep check on ‘Enabled’
    Click ‘Save’

Now lets define the first one will be the department:

  • [System-Select] > Setup
  • Click ‘Indexes’
  • Click on the ‘Tree Template’ button on the ‘Claims’ [Item option]
  • Click on the ‘New child node’ button
  • Type in Template:
    {{ document.metadata_value_of.department }}
    Keep the check mark in ‘Enabled’
    Click ‘Save’

For the second level will be based on reception date in the format year-month:

  • Click in the button ‘New child node’ (on the new level)
  • To extract the data that is stored in the date field with the format: YYYY/MM/DD, type in the template:
  • {{ document.metadata_value_of.dReceived|slice:”0:4″ }}-{{ document.metadata_value_of.dReceived|slice:”5:7″ }}
    Keep the check mark in ‘Enabled’
    Mark ‘Link documents’.
    As the text explains that instruct Mayan to put the document link here.
    Click ‘Save’

The last step is the association of this Index structure to be used with the ‘Document type’: Claim

  • [System-Select] > Setup
  • Click ‘Indexes’
  • On the Claims [option] click in the button ‘Document types’
  • In the next page
    Select ‘Claim’ from the left panel
    Click on the button ‘+Add’

The index will be built when you upload your first document.


III. Tags

Tags allow to identify documents easily. You can even use colors. In our example I’m using two TAGs, one to identify the state used by the analyst and one for the Expert so they can locate documents tagged for them in the workflow.

Note: When you design your workflow you usually model the activities (States) and Transitions, then you elaborate tagging. But for this post the introduction of Tags came first. In the Workflow section we will see how to automate tag’s setting and removal.

How To

  • [left-menu] > tags > Create new tag
  • Type in the ‘Create tag’ page:
    Label: Name
    Choose a color
    Click button ‘save’
LabelColor
On Claim ReviewOrange
On ExpertGreen

I associate Tags to a State so a user can click on it to find documents on that state. You only need two clicks to check the number of documents with a tag:

[left-menu] > Tags > All

To reduce the number of buttons available for your users in the image above we will use permissions so they will only see the number of documents and the ‘Documents’ button.