source: trunk/doc/src/docbook/userdoc/project_permission.xml @ 5706

Last change on this file since 5706 was 5706, checked in by Nicklas Nordborg, 10 years ago

References #1590: Documentation cleanup

User documentation chapter 10 to 15. Added new chapter about "Item subtypes". Removed sections about protocol types, hardware types and software types. Merged "Hardware" and "Software" into a single chapter.

Added some menu separators in the New annotation type menu.

As usual, screen shots have not yet been updated.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 27.3 KB
1<?xml version="1.0" encoding="UTF-8"?>
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
6  $Id: project_permission.xml 5706 2011-08-23 13:20:30Z nicklas $
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
10  This file is part of BASE - BioArray Software Environment.
11  Available at
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  GNU General Public License for more details.
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <>.
27<chapter id="project_permission">
28  <?dbhtml dir="project_permission"?>
29  <title>Projects and the permission system</title>
30    <sect1 id="project_permission.permissions">
31      <title>The permission system</title>
32      <para>
33        BASE is a multi-user environment that supports cooperation
34        between users while protecting all data against unauthorized
35        access or modification. To make this possible an elaborate
36        permission system has been developed that allows an user to
37        specify exactly the permission to give to other users and at the
38        same time makes it easy to handle the permissions of multiple
39        items with just a few interactions. For this to work smoothly there
40        are a few recommendations that all users should follow. The first
41        and most important recommendation is:
42      </para>
44      <important>
45        <title>Always use a project!</title>
46        By collecting items in a project the life
47        will be a lot easier when you want to share your data with others.
48        This is because you can always treat all items in a project as one
49        collection and grant or revoke access to the project as a whole.
50      </important> 
52      <sect2 id="project_permission.permissions.levels">
53        <title>Permission levels</title>
55        <para>
56          Whenever you try to create or access existing items in BASE the core will
57          check that you have the proper permission to do so. There
58          are several permission levels:
59        </para>
61        <variablelist>
62          <varlistentry>
63            <term>Read</term>
64            <listitem>
65              <para>
66              Permission to read information about the item, such
67              as the name and description.
68              </para>
69            </listitem>
70          </varlistentry>
72          <varlistentry>
73            <term>Use</term>
74            <listitem>
75              <para>
76              Permission to use the information. In most cases this
77              means linking with other items. For example, if you have permission
78              to use a protocol you may specify that protocol as the extraction
79              protocol when creating an extract from a sample. In the case of plug-ins,
80              you need this permission to be able to execute them.
81              </para>
82            </listitem>
83          </varlistentry>
85          <varlistentry>
86            <term>Write</term>
87            <listitem>
88              <para>
89              Permission to change information about the item.
90              </para>
91            </listitem>
92          </varlistentry>
94          <varlistentry>
95            <term>Delete</term>
96            <listitem>
97              <para>
98              Permission to delete the item.
99              </para>
100            </listitem>
101          </varlistentry>
103          <varlistentry>
104            <term>Change owner</term>
105            <listitem>
106              <para>
107                Permission to change the owner of an item. This is implemented as a
108                <guilabel>Set owner</guilabel> function in the web client
109                (<xref linkend="webclient.items.changeowner" />), where you can
110                change the owner of items that you have permission to do so on.
111              </para>
112            </listitem>
113          </varlistentry>
115          <varlistentry>
116            <term>Change permissions</term>
117            <listitem>
118              <para>
119              Permission to change the permissions on the item.
120              </para>
121            </listitem>
122          </varlistentry>
124          <varlistentry>
125            <term>Create</term>
126            <listitem>
127              <para>
128              Permission to create new items. This permission can only be
129              given to roles.
130              </para>
131            </listitem>
132          </varlistentry>
133          <varlistentry>
134            <term>Deny</term>
135            <listitem>
136              <para>
137              Deny all access to the item. This permission can only be given
138              to roles.
139              </para>
140            </listitem>
141          </varlistentry>
143        </variablelist>
144        <note>
145          A user's permissions need to be reloaded for the permissions that have been
146          changed should take effect. This is done either manually with the menu choice
147          <menuchoice>
148            <guimenu>BASE</guimenu>
149            <guimenuitem>Reload permissions</guimenuitem>
150          </menuchoice>
151          or automatically next time the user logs in to BASE.
152        </note>
154      </sect2>
156      <sect2 id="project_permission.permissions.checks">
157        <title>Getting access to an item</title>
159        <para>
160          There are several ways that permission to access an item can
161          be granted to you. The list below is a description of how the
162          permission checks are implemented in the BASE core:
163        </para>
165        <orderedlist>
166          <listitem>
167            <para>
168            Check if you are the root user. The root user has full
169            permission to everything and the permission check stops here.
170            </para>
171          </listitem>
173          <listitem>
174            <para>
175            Check if you are a member of a role that gives you access to the
176            item. Role-based permissions can only be specified based on
177            generic item types and is valid for all items of that type.
178            The role-based permissions also include a special deny permission
179            that can prevents a user from accessing any item. In that case,
180            the permission check stops here.
181            </para>
182          </listitem>
184          <listitem>
185            <para>
186            Check if you are the owner of the item. As the owner you have full
187            permission to the item and the permission check stops here.
188            </para>
189          </listitem>
191          <listitem>
192            <para>
193            Check if you have been granted access to the item by the
194            sharing system (cf. <xref linkend="webclient.items.share"/>).
195            The sharing system can grant access to individual users, groups of
196            users and to projects. We recommend that you always use projects
197            to share your items.
198            </para>
199          </listitem>
201          <listitem>
202            <para>
203            Some items implement special permission checks.
204            For example:
205            </para>
207            <itemizedlist>
208              <listitem>
209                <para>
210                News: You always have read access to news if today's date
211                falls between the start and end date of the news item.
212                </para>
213              </listitem>
215              <listitem>
216                <para>
217                Groups: You have read access to all groups where you
218                are a member.
219                </para>
220              </listitem>
222              <listitem>
223                <para>
224                Users: You have read permission to all users that share group
225                membership with, excluding the <emphasis>Everyone</emphasis> group.
226                When a project is active, you also have read permission to all
227                users that are members of that project.
228                </para>
229              </listitem>
231            </itemizedlist>
233            <para>
234              There are more items with special permission checks but
235              we do not list those here.
236            </para>
238          </listitem>
240        </orderedlist>
241      </sect2>
243      <sect2 id="project_permission.permissions.plugins">
244        <title>Plug-in permissions</title>
246        <para>
247          Another aspect of the permission system is that plug-ins
248          may also have permissions of their own. The default is that
249          plug-ins run with the same permissions as the user that invoked
250          the plug-in has. Sometimes this can be seen as a security risk
251          if the plug-in is not trusted. A malicious plug-in can, for example,
252          delete the entire database if invoked by the root user.
253        </para>
255        <para>
256          An administrator can choose to give a plug-in only those
257          permissions that is required to complete it's task. If the plug-in
258          permission system is enabled for a plug-in the default is to deny
259          all actions. Then, the administrator can give the plug-in the same
260          permissions as listed above. There is one additional twist to
261          the plug-in permission system. A permission can be granted regardless
262          of if the user that invoked the plug-in had the permission or not, or
263          a permission can be granted only if the user also has the permission.
264          The first case makes it possible to develop a plug-in that allows
265          users to do things that they normally do not have permission to do.
266          The second case is the same as not using the plug-in permission system,
267          except that unspecified permissions are always denied when the
268          plug-in permission system is used.
269        </para>
271        <note>
272          Plug-in developers can supply information about
273          the wanted permissions making it easy for the administrator to
274          just check the permissions and accept them with just a single
275          click if they make sense.
276        </note>
278        <para>
279          See <xref linkend="plugins.permissions"/> for more information.
280        </para>
282      </sect2>
284    </sect1>
286    <sect1 id="project_permission.projects">
288      <title>Projects</title>
290      <para>
291        Projects are an important part of the permission system for several
292        reasons:
293      </para>
295      <itemizedlist>
296        <listitem>
297          <para>
298          They do not require an administrator to setup and
299          use. All regular users may create a project, add items
300          to it and share it with other users. You are in complete
301          control of who gets access to the project, the items it contains
302          and which permission levels to use.
303          </para>
304        </listitem>
306        <listitem>
307          <para>
308          All items in a project are treated as one collection. If a
309          new member joins the team, just give the new person access
310          to the project and that person will be able to access all
311          items in the project.
312          </para>
313        </listitem>
315        <listitem>
316          <para>
317          When you create new items, they are automatically shared
318          using the settings from the active project. There is almost no
319          need to share items manually. All
320          you have to remember is to set an active project, and
321          this is easy accessible from the
322          <link linkend="webclient.intro.menubar">menu bar</link>.
323          </para>
324        </listitem>
326        <listitem>
327          <para>
328          Filter out items that you do not want to see. When you have set
329          an active project you may choose to only see items that are
330          part of that project and no other items
331          (<xref linkend="webclient.itemlist.presets"/>).
332          </para>
333        </listitem>
335        <listitem>
336          <para>
337          It's easy to share multiple items between projects. Items
338          may be part of more than one project. If you create a new
339          project that builds on a previous one you can easily share
340          some or all of the existing items to the new project from one
341          central place, the <guilabel>Items</guilabel> tab on the project's
342          single-item view.
343          </para>
344        </listitem>
346      </itemizedlist>
349      <sect2 id="">
351        <title>The active project</title>
353        <para>
354          The active project concept is central to the sharing system.
355          You should always, with few exceptions, have a project active
356          when you work with BASE. The most important reason is that
357          new items will automatically be shared using the settings in
358          the active project. This considerably reduces
359          the time needed for managing access permissions. Without an
360          active project you would have to manually
361          set the permission on all items you create. If you have hundreds
362          of items this is a time-consuming and boring task best to be
363          avoided.
364        </para>
366        <para>
367          If you work with multiple projects you will probably find the
368          filtering function that hides items that are not part
369          of the active project to be useful. As a matter of fact, if you
370          try to access an item that is part of another (not active) project
371          you will get an error message saying that you do not have
372          permission to access the item (unless you are the owner).
373        </para>
375        <sect3 id="">
376          <title>Selecting an active project</title>
378          <para>
379            Since it's important to always have an active project
380            there are several ways to make a project 
381            the active one.
382          </para>
384          <itemizedlist>
385            <listitem>
386              <para>
387                The easiest way and the one you will probably use most of the time
388                is to use the menu bar shortcut. Look in the menu for the project
389                icon
390                (<guiicon>
391                  <inlinemediaobject>
392                    <imageobject>
393                      <imagedata fileref="figures/project.gif" format="GIF" />
394                    </imageobject>
395                  </inlinemediaobject>
396                </guiicon>).
397                Next to it, the name of the active project is displayed. If you see
398                <guiicon>
399                  <inlinemediaobject>
400                    <imageobject>
401                      <imagedata fileref="figures/no_active_project.gif" format="GIF" />
402                    </imageobject>
403                  </inlinemediaobject>
404                </guiicon>
405                <guilabel>- no active project -</guilabel>
406                here, it means that you have not selected a project to work in. Click on the icon or
407                project name to open a drop-down menu and select a project to set as
408                the active project. If another project is already active it will
409                automatically be inactivated.
410              </para>
411              <para>
412                The most recently used projects are listed first, then the list is filled with the
413                rest of your projects up to a maximum of 15. If you have more projects an option to
414                display the remaining projects is activated.
415              </para>
416              <tip>
417                <para>
418                The sort order of the non-recent projects is the same as the sort order on the
419                projects list page. If you, for example, want to sort the newest
420                project first, select to sort by the <guilabel>Registered</guilabel> 
421                column in descending order on the list page. The menu will automatically
422                use the same order.
423                </para>
424              </tip>
425            </listitem>
427            <listitem>
428              <para>
429              Use the <menuchoice><guimenu>BASE</guimenu>
430              <guisubmenu>Select project</guisubmenu></menuchoice>
431              menu and select the project from the submenu that opens
432              up.
433              </para>
434            </listitem>
436            <listitem>
437              <para>
438              Go to the <link linkend="webclient.intro.homepage">homepage</link>
439              using the <menuchoice><guimenu>View</guimenu>
440              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
441              a project from the list displayed there.
442              </para>
443            </listitem>
444          </itemizedlist>
446          <note>
447            Only one project can be active at a time.
448          </note>
450          <warning>
451            If you change the active project while viewing an item
452            that you no longer has access to in the context of the
453            new project an error message about missing permission
454            will be displayed. Unfortunately, this is all that is displayed
455            and it may be difficult to navigate to a working page again.
456            In the worst case, you may have to go to the login page and
457            login again.
458          </warning>
460        </sect3>
462        <sect3 id="">
463          <title>Default permissions for the active project</title>
465          <para>
466            When a project is active all new items you create are automatically
467            shared using the settings from the active project. If the active project
468            has a permission template the permissions from the template are copied
469            to the new item. If the project doesn't have a permission template, the
470            new item is shared to the active project with the configured default
471            level. By default, projects doesn't have a permission template
472            and the default permissions are set to
473            <emphasis>read</emphasis>, <emphasis>use</emphasis>,
474            <emphasis>write</emphasis> and <emphasis>delete</emphasis>. It is
475            possible to change the default permission level by modifying the
476            settings for the project. Simply open the edit-view page for the project
477            and select the permissions you want and save. From now on, all new
478            items will be shared with the specified permissions. Items that are
479            already in the project are not affected by the change.
480          </para>
481        </sect3>
483      </sect2>
485      <sect2 id="project_permission.projects.share">
486        <title>How to give other users access to your project</title>
488        <para>
489          First, you will need to open the <guilabel>Edit project</guilabel>
490          dialog. Here is how to do that:
491        </para>
493        <orderedlist>
494          <listitem>
495            <para>
496            Navigate to the single-item view of your project
497            from the <menuchoice><guimenu>View</guimenu>
498            <guisubmenu>Projects</guisubmenu></menuchoice> list.
499            </para>
500          </listitem>
502          <listitem>
503            <para>
504            Click on the &gbEdit;
505            button to open the <guilabel>Edit project</guilabel>
506            dialog.
507            </para>
508          </listitem>
510          <listitem>
511            <para>
512            Switch to the <guilabel>Members tab</guilabel>. From this
513            page you can add and remove users and change the access levels
514            of existing ones.
515            </para>
516          </listitem>
517        </orderedlist>
519        <figure id="project_permission.projects.members">
520          <title>Manage members of a project</title>
521          <screenshot>
522            <mediaobject>
523              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
524            </mediaobject>
525          </screenshot>
526        </figure>
529        <helptext external_id="project.edit.members" title="Project members">
531          <variablelist>
532            <varlistentry>
533              <term><guilabel>Members</guilabel></term>
534              <listitem>
535                <para>
536                The members list contains users
537                and groups that are already members of the project. The list
538                shows the name and the permission level. The permission level
539                uses a one-letter code as follows:
540                </para>
541                <itemizedlist>
542                <listitem><guilabel>R</guilabel> = Read</listitem>
543                <listitem><guilabel>U</guilabel> = Use</listitem>
544                <listitem><guilabel>W</guilabel> = Write</listitem>
545                <listitem><guilabel>D</guilabel> = Delete</listitem>
546                <listitem><guilabel>O</guilabel> = Set owner</listitem>
547                <listitem><guilabel>P</guilabel> = Set permission</listitem>
548                </itemizedlist>
549              </listitem>
550            </varlistentry>
552            <varlistentry>
553              <term><guilabel>Permissions</guilabel></term>
554              <listitem>
555                <para>
556                When you select an user or group in the
557                list the current permission will be checked. To change the
558                permissions just check the permissions you want to
559                grant or uncheck the permissions you want to revoke.
560                You may select more than one user and/or group
561                and change the permissions for all of them at once.
562                </para>
564                <note>
565                In most cases, you should give the project members
566                <emphasis>use</emphasis> permission. This will allow an user
567                to use all items in the project as well as add new items to it.
568                If you give them write or delete permission they will be able
569                to modify or delete all items including those that they do not
570                own.
571                </note>
573                <note>
574                The above note is not always true since the permission to
575                an item in the project also depends on the permission that
576                was set when adding the item to the project. The default
577                permission is <emphasis>delete</emphasis> and the above note
578                holds true. If the item's permission is manually changed to for
579                example, <emphasis>use</emphasis>, no project member can get
580                higher permission to the item.
581                </note>
583              </listitem>
584            </varlistentry>
586            <varlistentry>
587              <term><guibutton>Add users</guibutton></term>
588              <listitem>
589                <para>
590                Opens a popup window that allows you to add
591                users to the project. In the popup window, mark
592                one or more users and click on the &gbOk;
593                button. The popup window will only list users that you have
594                permission to read. Unless you are an administrator, this
595                usually means that you can only see users that:
596                </para>
597                <itemizedlist>
598                  <listitem>
599                    <para>
600                    you share group memberships with
601                    (the <emphasis>Everyone</emphasis> group doesn't count)
602                    </para>
603                  </listitem>
604                  <listitem>
605                    <para>
606                    are members of the currently active project, if any.
607                    </para>
608                  </listitem>
609                </itemizedlist>
610                <para>
611                Users that already have access to the project are not included in the
612                list. If you don't see a user that you want to add to the project,
613                you'll need to talk to an administrator for setting up the proper
614                group membership.
615                </para>
616              </listitem>
617            </varlistentry>
619            <varlistentry>
620              <term><guibutton>Add groups</guibutton></term>
621              <listitem>
622                <para>
623                Opens a popup window that allows you to add
624                groups to the project. In the popup window, mark
625                one or more groups and click on the &gbOk;
626                button. Unless you are
627                an administrator, the popup window will only list groups
628                that you are a member of. It will not list groups that
629                are already part of the project.
630                </para>
631              </listitem>
632            </varlistentry>
634            <varlistentry>
635              <term>&gbRemove;</term>
636              <listitem>
637                <para>
638                Click on this button to remove the selected
639                users and/or groups from the project.
640                </para>
641              </listitem>   
642            </varlistentry>
643          </variablelist>
646          <para>
647            Use the &gbSave; button to save your
648            changes or the &gbCancel; button to
649            close the popup without saving.
650          </para>
651        </helptext>
653      </sect2>
655      <sect2 id ="project_permissions.project.defaults">
656        <title>Default items</title>
658        <para>TODO</para>
660      </sect2>
662      <sect2 id="project_permission.projects.items">
663        <title>Working with the items in the project</title>
665        <para>
666        If you go to the single-item view for a project you will find
667        that there is an extra tab, <guilabel>Items</guilabel>, on that
668        page.
669        <figure id="project_permission.images.projecttabs">
670          <title/>
671          <screenshot>
672            <mediaobject>
673              <imageobject><imagedata fileref="figures/project_tabs.png" format="PNG" /></imageobject>
674            </mediaobject>
675          </screenshot>
676        </figure>
677        Clicking on that tab will display a page that is similar
678        to a list view. However there are some differences:
679        </para>
681        <itemizedlist>
682          <listitem>
683            <para>
684            The list is not limited to one type of item. It can display
685            all items that are part of the project.
686            </para>
687          </listitem>
689          <listitem>
690            <para>
691              It support only a limited set of columns (id, name, description and
692              owner) since these are the only properties that are common
693              among all items.
694            </para>
695          </listitem>
697          <listitem>
698            <para>
699              The list cannot be sorted. This is due to a limitation in the
700              query system used to generate the list.
701            </para>
702          </listitem>
703        </itemizedlist>
705        <note>
706          The list only works for the active project. For all other
707          projects it will only display items that are owned by the
708          logged in user.
709        </note>
711        <para>
712          There are also several similarities:
713        </para>
715        <itemizedlist>
716          <listitem>
717            <para>
718              It supports all of the regular multi-item
719              operations such as delete, restore, share
720              and change owner.
721            </para>
722          </listitem>
724          <listitem>
725            <para>
726              Clicking on the name of the item will take you to the
727              single-item view of that item. Holding down <keycap>CTRL</keycap>,
728              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
729              will open the edit popup.
730            </para>
731          </listitem>
732        </itemizedlist>
734        <tip>
735          <para>
736          This list is very useful when you are creating a
737          new project, in which you want to reuse items from
738          an old project.
739          </para>
741          <itemizedlist>
742            <listitem>
743              <para>
744              Activate the old project and go to this view.
745              </para>
746            </listitem>
748            <listitem>
749              <para>
750                Mark the checkbox for all items that you want to
751                use in the new project.
752              </para>
753            </listitem>
755            <listitem>
756              <para>
757                Click on the &gbShare; button
758                and share the items to the new project.
759              </para>
760            </listitem>
761          </itemizedlist>
762          <para>
763            If you have more than one old project, repeat the
764            above procedure.
765          </para>
766        </tip>
768      </sect2>
770    </sect1>
772    <sect1 id="project_permission.templates">
773      <title>Permission templates</title>
775      <para>
776        A <emphasis>permission template</emphasis> is a pre-defined set of permissions
777        for users, groups and/or projects. The template makes it easy to quickly share
778        items to multiple users, groups and projects, possible with different permissions
779        for everyone. There are three major use-cases were permission templates are useful:
780      </para>
782      <itemizedlist>
783        <listitem>
784          <para>
785          A permission template can be associated with project. When the project is selected
786          as the active project, the permissions from the template are copied to any new items
787          that are created. Note that the new items may or may not be shared with the active
788          project, depending on the settings in the permission template.
789          </para>
790        </listitem>
791        <listitem>
792          <para>
793          Permission templates can be selected in the <link linkend="webclient.items.share">share dialog</link>,
794          making it easier to manually share items to multiple users,
795          groups and projects in just a few clicks.
796          </para>
797        </listitem>
798        <listitem>
799          <para>
800          Permission templates can be used with some batch item importers, making it easier
801          for administrators which only needs a single data file even if the data belong to
802          different projects.
803          </para>
804        </listitem>
805      </itemizedlist>
807      <para>
808        Permission templates are managed from the <menuchoice><guimenu>View</guimenu>
809        <guisubmenu>Permission templates</guisubmenu></menuchoice> menu. The template is
810        a very simple item that only has a name (required) and a description (optional).
811        We recommend that the names of the templates are kept unique, but this is not
812        enforced by BASE. To assign permissions to the template use the
813        <guibutton>Set permissions</guibutton> button. This is the same dialog as the
814        <link linkend="webclient.items.share">share dialog</link>.
815      </para>
817      <note>
818        <title>Permissions are copied</title>
819        <para>
820        When a permission template is used the permissions are <emphasis>copied</emphasis>
821        to the items. Modifications to the template that are made afterwards doesn't
822        affect the permissions for the items on which the template was used.
823        </para>
824      </note>
825    </sect1>
Note: See TracBrowser for help on using the repository browser.