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

Last change on this file since 3246 was 3246, checked in by Martin Svensson, 16 years ago

The output files of docbook will be sorted into subdirectories and figures now has a relative uri

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 16.7 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 3246 2007-04-16 14:12:23Z martin $
8  Copyright (C) Authors contributing to this file.
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 2
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 this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
29<chapter id="project_permission">
30  <?dbhtml dir="project_permission"?>
31  <title>Projects and the permission system</title>
32    <sect1 id="project_permission.introduction">
33      <title>Introduction</title>
34      <para>
35        BASE is a multi-user environment that supports cooperation
36        between users while protecting all data against unauthorized
37        access or modification. To make this possible an elaborate
38        permission system has been developed that allows users to
39        specify exactly the permission to give to other users and at the
40        same time makes it easy to handle the permissions of multiple
41        items with just a few interactions. For this to work smoothly there
42        are a few recommendations that all users should follow. The first
43        and most important recommendation is:
44      </para>
46      <important>
47        Always use a project! By collecting items in a project the life
48        will be a lot easier when you want to share your data with others.
49        This is because you can always treat all items in a project as one
50        collection and grant or revoke access to the project as a whole.
51      </important> 
53      <sect2 id="project_permission.introduction.levels">
54        <title>Permission levels</title>
56        <para>
57          Whenever you try to create or access existing items in BASE the core will
58          check that you have the proper permission to do so. There
59          are several permission levels:
60        </para>
62        <variablelist>
63          <varlistentry>
64            <term>Read</term>
65            <listitem>
66              Permission to read information about the item, such
67              as the name and description.
68            </listitem>
69          </varlistentry>
71          <varlistentry>
72            <term>Use</term>
73            <listitem>
74              Permission to use the information. In most cases this
75              means linking with other items. For example, if you have permission
76              to use a protocol you may specify that protocol as the extraction
77              protocol when creating an extract from a sample. In the case of plugins,
78              you need this permission to be able to execute them.
79            </listitem>
80          </varlistentry>
82          <varlistentry>
83            <term>Write</term>
84            <listitem>Permission to change information about the item.</listitem>
85          </varlistentry>
87          <varlistentry>
88            <term>Delete</term>
89            <listitem>Permission to delete the item.</listitem>
90          </varlistentry>
92          <varlistentry>
93            <term>Change owner</term>
94            <listitem>
95              Permission to change the owner of an item. This is implemented
96              as a <guilabel>Take ownership</guilabel> function in the web
97              client, where you can take the ownership of an item that you
98              don't already own.
99            </listitem>
100          </varlistentry>
102          <varlistentry>
103            <term>Change permissions</term>
104            <listitem>Permission to change the permissions.</listitem>
105          </varlistentry>
107          <varlistentry>
108            <term>Create</term>
109            <listitem>
110              Permission to create new items. This permission is only be used
111              for roles.
112            </listitem>
113          </varlistentry>
114          <varlistentry>
115            <term>Deny</term>
116            <listitem>
117              Deny all access to the item. This permission is only be used
118              for roles.
119            </listitem>
120          </varlistentry>
122        </variablelist>
124      </sect2>
126      <sect2 id="project_permission.introduction.checks">
127        <title>How access permissions are checked</title>
129        <para>
130          There are several ways that permission to access an item can
131          be granted to you. The list below is a description of how the
132          permission checks are implemented in the core.
133        </para>
135        <orderedlist>
136          <listitem>
137            Check if you are the root user. The root user has full
138            permission to everything and the permission check stops here.
139          </listitem>
141          <listitem>
142            If you are a member of a role that gives you access to the
143            item. Role-based permissions can only be specified based on
144            generic item types and is valid for all items of that type.
145            The role-based permissions also include a special deny permission
146            that can prevent a user from accessing any item. In that case,
147            the permission check stops here.
148          </listitem>
150          <listitem>
151            If you are the owner of the item. As the owner you have full
152            permission to the item and the permission check stops here.
153          </listitem>
155          <listitem>
156            If you have been granted access to the item by the sharing system.
157            The sharing system can grant access to individual users, groups of
158            users and to projects. We recommend that you always use projects
159            to share your items.
160          </listitem>
162          <listitem>
163            <para>
164            Some items implement special permission checks.
165            For example:
166            </para>
168            <itemizedlist>
169              <listitem>
170                News: You always have read access to news if today's date
171                falls between the start and end date of the news item.
172              </listitem>
174              <listitem>
175                Groups: You have read access to all groups where you
176                are a member.
177              </listitem>
179              <listitem>
180                Users: You have read permission to all users that are members
181                of at least one group where you also are a member. When a project
182                is active, you also have read permission to all users of
183                that project.
184              </listitem>
186            </itemizedlist>
188            <para>
189              There are more items with special permission checks but
190              we don't list those here.
191            </para>
193          </listitem>
195        </orderedlist>
196      </sect2>
197    </sect1>
199    <sect1 id="project_permission.projects">
201      <title>Projects</title>
203      <para>
204        Projects are an important part of the permission system for several
205        reasons:
206      </para>
208      <itemizedlist>
209        <listitem>
210          They don't require an administrator to setup and
211          use. All regular users may create a project, add items
212          to it and share it with other users. You are in complete
213          control of who gets access to it and which permission levels
214          to use.
215        </listitem>
217        <listitem>
218          All items in a project are treated as one collection. If a
219          new member joins the team, just give the new person access
220          to the project and that person will be able to access all
221          items in the project.
222        </listitem>
224        <listitem>
225          Items are automatically added to the active project so
226          there is almost no need to share items manually. All
227          you have to remember is to set an active project, and
228          this is easy accessible from the
229          <link linkend="webclient.intro.menubar">menu bar</link>.
230        </listitem>
232        <listitem>
233          Filter out items that you don't want to see. When you have set
234          an active project you may choose to only see items that are
235          part of that project and no other items
236          (<xref linkend="webclient.itemlist.presets"/>).
237        </listitem>
239        <listitem>
240          It's easy to share multiple items between projects. Items
241          may be part of more than one project. If you create a new
242          project that builds on a previous one you can easily share
243          some or all of the existing items to the new project from one
244          central place, the <guilabel>Items</guilabel> tab on the project's
245          view page.
246        </listitem>
248      </itemizedlist>
251      <sect2 id="">
253        <title>The active project</title>
255        <para>
256          The active project concept is central to the sharing system.
257          You should always, with few exceptions, have a project active
258          when you work with BASE. The most important reason is that
259          new items will automatically be included in the active project.
260          This considerably reduces the time needed for managing access
261          permissions. Without an active project you would have to manually
262          set the permission on all items you create. If you have hundreds
263          of items this is a time-consuming and boring task best to be
264          avoided.
265        </para>
267        <para>
268          If you work with multiple projects you will probably find the
269          filtering function that hides items that are not part
270          of the active project to be useful. As a matter of fact, if you
271          try to access an item that is part of another (not active) project
272          you will get an error message saying that you don't have
273          permission to access the item (unless you are the owner).
274        </para>
276        <sect3 id="">
277          <title>Setting the active project</title>
279          <para>
280            Since it important to always have an active project
281            there are several ways to make a project to become
282            the active one.
283          </para>
285          <itemizedlist>
286            <listitem>
287              The easiest way and the one you will probably
288              use most of the time is to use the
289              <link linkend="webclient.intro.menubar">menu bar</link> shortcut.
290              Look in the menu for the project icon (<inlinemediaobject>
291              <imageobject><imagedata fileref="figures/project.gif" format="GIF" /></imageobject>
292              </inlinemediaobject>). Next to it, the name of the active project
293              is displayed. If you see <guilabel>- none -</guilabel> here, it
294              means that no project is active. Click on the icon or project name
295              to open a drop-down menu and select a project to set as the active
296              project. If another project is already active it will automatically
297              be unactivated.
298            </listitem>
300            <listitem>
301              Use the <menuchoice><guimenu>File</guimenu>
302              <guisubmenu>Select project</guisubmenu></menuchoice>
303              menu and select the project from the submenu that opens
304              up.
305            </listitem>
307            <listitem>
308              Go to the <link linkend="webclient.intro.homepage">homepage</link>
309              using the <menuchoice><guimenu>View</guimenu>
310              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
311              a project from the list displayed there.
312            </listitem>
313          </itemizedlist>
315          <note>
316            Only one project can be active at a time.
317          </note>
319          <warning>
320            If you change the active project while viewing an item
321            that you no longer has access to in the context of the
322            new project an error message about missing permission
323            will be displayed. Unfortunately, this is all that is displayed
324            and it may be difficult to navigate to a working page again.
325            In the worst case, you may have to go to the login page and
326            login again.
327          </warning>
329        </sect3>
330      </sect2>
332      <sect2 id="project_permission.projects.share">
333        <title>How to give other users access to your project</title>
335        <para>
336          First, you will need to open the <guilabel>Edit project</guilabel>
337          dialog. Here is how to do that:
338        </para>
340        <orderedlist>
341          <listitem>
342            Navigate to the single-item view page of your project
343            from the <menuchoice><guimenu>View</guimenu>
344            <guisubmenu>Projects</guisubmenu></menuchoice> list.
345          </listitem>
347          <listitem>
348            Click on the <guibutton>Edit&hellip;</guibutton>
349            button to open the <guilabel>Edit project</guilabel>
350            dialog.
351          </listitem>
353          <listitem>
354            Switch to the <guilabel>Members tab</guilabel>. From this
355            page you can add and remove users and change the access levels
356            of existing ones.
357          </listitem>
358        </orderedlist>
360        <figure id="project_permission.projects.members">
361          <title>Manage members of a project</title>
362          <screenshot>
363            <mediaobject>
364              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
365            </mediaobject>
366          </screenshot>
367        </figure>
370        <helptext external_id="project.edit.members" title="Project members">
372          <variablelist>
373            <varlistentry>
374              <term><guilabel>Members</guilabel></term>
375              <listitem>
376                <para>
377                The members list contains users
378                and groups that are already members of the project. The list
379                shows the name and the permission level. The permission level
380                uses a one-letter code as follows:
381                </para>
382                <itemizedlist>
383                <listitem><guilabel>R</guilabel> = Read</listitem>
384                <listitem><guilabel>U</guilabel> = Use</listitem>
385                <listitem><guilabel>W</guilabel> = Write</listitem>
386                <listitem><guilabel>D</guilabel> = Delete</listitem>
387                <listitem><guilabel>O</guilabel> = Take ownership</listitem>
388                <listitem><guilabel>P</guilabel> = Set permission</listitem>
389                </itemizedlist>
390              </listitem>
391            </varlistentry>
393            <varlistentry>
394              <term><guilabel>Permissions</guilabel></term>
395              <listitem>
396                <para>
397                When you select a user or group in the
398                list the current permission will be checked. To change the
399                permissions just check the permissions you want to
400                grant or uncheck the permissions you want to revoke.
401                You may select more than one user and/or group
402                and change the permissions for all of them at once.
403                </para>
405                <note>
406                In most cases, you should give the project members
407                <emphasis>use</emphasis> permission. This will allow a user
408                to use all items in the project as well as add new items to it.
409                If you give them write or delete permission they will be able
410                to modify or delete all items including those that they don't
411                own.
412                </note>
414                <note>
415                The above note is not always true since the permission to
416                an item in the project also depends on the permission that
417                was set when adding the item to the project. The default
418                permission is <emphasis>delete</emphasis> and the above note
419                holds true. If the item's permission is manually changed to for
420                example, <emphasis>use</emphasis>, no project member can get
421                higher permission to the item.
422                </note>
424              </listitem>
425            </varlistentry>
427            <varlistentry>
428              <term><guibutton>Add users</guibutton></term>
429              <listitem>
430                <para>
431                Opens a popup window that allows you to add
432                users to the project. In the popup window, mark
433                one or more users and click on the <guibutton>Ok</guibutton>
434                button. Unless you are an administrator, the popup window
435                will only list users that are members of at least one of the
436                groups where you also are a memberm. It will not list users that
437                are already part of the project.
438                </para>
439              </listitem>
440            </varlistentry>
442            <varlistentry>
443              <term><guibutton>Add groups</guibutton></term>
444              <listitem>
445                <para>
446                Opens a popup window that allows you to add
447                groups to the project. In the popup window, mark
448                one or more groups and click on the <guibutton>Ok</guibutton>
449                button. Groups that are already part of the project
450                are not displayed in the popup window. Unless you are
451                an administrator, the popup window will only list groups
452                that you are a member of. It will not list groups that
453                are already part of the project.
454                </para>
455              </listitem>
456            </varlistentry>
458            <varlistentry>
459              <term><guibutton>Remove</guibutton></term>
460              <listitem>
461                <para>
462                Click on this button to remove the selected
463                users and/or groups from the project.
464                </para>
465              </listitem>   
466            </varlistentry>
467          </variablelist>
470          <para>
471            Use the <guibutton>Save</guibutton> button to save your
472            changes or the <guibutton>Cancel</guibutton> button to
473            clost the popup without saving.
474          </para>
475        </helptext>
477      </sect2>
479      <sect2 id="project_permission.projects.items">
480        <title>Working with the items in the project</title>
482        <para>
483        TODO
484        </para>
486      </sect2>
488    </sect1>
Note: See TracBrowser for help on using the repository browser.