source: trunk/doc/src/docbook/user/project_permission.xml @ 5792

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

References #1590: Documentation cleanup

New and updated screenshots for chapter 6 "Projects and the permission system".

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 32.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: project_permission.xml 5792 2011-10-07 11:14:11Z nicklas $
7
8  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
9
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12
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.
17
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<chapter id="project_permission">
28  <?dbhtml dir="projects" filename="index.html" ?>
29  <title>Projects and the permission system</title>
30    <sect1 id="project_permission.permissions">
31      <?dbhtml filename="permissions.html" ?>
32      <title>The permission system</title>
33      <para>
34        BASE is a multi-user environment that supports cooperation
35        between users while protecting all data against unauthorized
36        access or modification. To make this possible an elaborate
37        permission system has been developed that allows a user to
38        specify exactly the permission to give to other users and at the
39        same time makes it easy to handle the permissions of multiple
40        items with just a few interactions. For this to work smoothly there
41        are a few recommendations that all users should follow. The first
42        and most important recommendation is:
43      </para>
44     
45      <important>
46        <title>Always use a project!</title>
47        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> 
52       
53      <sect2 id="project_permission.permissions.levels">
54        <title>Permission levels</title>
55       
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>
61       
62        <variablelist>
63          <varlistentry>
64            <term>Read</term>
65            <listitem>
66              <para>
67              Permission to read information about the item, such
68              as the name and description.
69              </para>
70            </listitem>
71          </varlistentry>
72         
73          <varlistentry>
74            <term>Use</term>
75            <listitem>
76              <para>
77              Permission to use the information. In most cases this
78              means linking with other items. For example, if you have permission
79              to use a protocol you may specify that protocol as the extraction
80              protocol when creating an extract from a sample. In the case of plug-ins,
81              you need this permission to be able to execute them.
82              </para>
83            </listitem>
84          </varlistentry>
85         
86          <varlistentry>
87            <term>Write</term>
88            <listitem>
89              <para>
90              Permission to change information about the item.
91              </para>
92            </listitem>
93          </varlistentry>
94
95          <varlistentry>
96            <term>Delete</term>
97            <listitem>
98              <para>
99              Permission to delete the item.
100              </para>
101            </listitem>
102          </varlistentry>
103
104          <varlistentry>
105            <term>Change owner</term>
106            <listitem>
107              <para>
108                Permission to change the owner of an item. This is implemented as a
109                <guilabel>Set owner</guilabel> function in the web client
110                (<xref linkend="webclient.items.changeowner" />), where you can
111                change the owner of items that you have permission to do so on.
112              </para>
113            </listitem>
114          </varlistentry>
115
116          <varlistentry>
117            <term>Change permissions</term>
118            <listitem>
119              <para>
120              Permission to change the permissions on the item.
121              </para>
122            </listitem>
123          </varlistentry>
124         
125          <varlistentry>
126            <term>Create</term>
127            <listitem>
128              <para>
129              Permission to create new items. This permission can only be
130              given to roles.
131              </para>
132            </listitem>
133          </varlistentry>
134          <varlistentry>
135            <term>Deny</term>
136            <listitem>
137              <para>
138              Deny all access to the item. This permission can only be given
139              to roles.
140              </para>
141            </listitem>
142          </varlistentry>
143     
144        </variablelist>
145        <note>
146          A user's permissions need to be reloaded for the permissions that have been
147          changed should take effect. This is done either manually with the menu choice
148          <menuchoice>
149            <guimenu>BASE</guimenu>
150            <guimenuitem>Reload permissions</guimenuitem>
151          </menuchoice>
152          or automatically next time the user logs in to BASE.
153        </note>
154
155      </sect2>
156     
157      <sect2 id="project_permission.permissions.checks">
158        <title>Getting access to an item</title>
159     
160        <para>
161          There are several ways that permission to access an item can
162          be granted to you. The list below is a description of how the
163          permission checks are implemented in the BASE core:
164        </para>
165       
166        <orderedlist>
167          <listitem>
168            <para>
169            Check if you are the <emphasis>root user</emphasis>. The root user has full
170            permission to everything and the permission check stops here.
171            </para>
172          </listitem>
173         
174          <listitem>
175            <para>
176            Check if you are a <emphasis>member of a role</emphasis> that gives you access to the
177            item. Role-based permissions can only be specified based on
178            generic item types and is valid for all items of that type.
179            The role-based permissions also include a special deny permission
180            that prevents a user from accessing any item. In that case,
181            the permission check stops here.
182            </para>
183          </listitem>
184         
185          <listitem>
186            <para>
187            Check if you are the <emphasis>owner of the item</emphasis>. As the owner you have full
188            permission to the item and the permission check stops here. This step is not done
189            for items that doesn't have an owner.
190            </para>
191          </listitem>
192         
193          <listitem>
194            <para>
195            Check if you have been granted access to the item by the
196            <emphasis>sharing system</emphasis> (cf. <xref linkend="webclient.items.share"/>).
197            The sharing system can grant access to individual users, groups of
198            users and to projects. We recommend that you always use projects
199            to share your items. This step is not done for items that can't be shared.
200            </para>
201          </listitem>
202         
203          <listitem>
204            <para>
205            Some items implement special permission checks.
206            For example:
207            </para>
208           
209            <itemizedlist>
210              <listitem>
211                <para>
212                <guilabel>News</guilabel>: You always have read access to news if today's date
213                falls between the start and end date of the news item.
214                </para>
215              </listitem>
216           
217              <listitem>
218                <para>
219                <guilabel>Groups</guilabel>: You have read access to all groups where you
220                are a member.
221                </para>
222              </listitem>
223           
224              <listitem>
225                <para>
226                <guilabel>Users</guilabel>: You have read permission to all users that share group
227                membership with, excluding the <emphasis>Everyone</emphasis> group.
228                When a project is active, you also have read permission to all
229                users that are members of that project.
230                </para>
231              </listitem>
232           
233            </itemizedlist>
234           
235            <para>
236              There are more items with special permission checks but
237              we do not list those here.
238            </para>
239           
240          </listitem>
241         
242        </orderedlist>
243      </sect2>
244
245      <sect2 id="project_permission.permissions.plugins">
246        <title>Plug-in permissions</title>
247       
248        <para>
249          Another aspect of the permission system is that plug-ins
250          may also have permissions of their own. The default is that
251          plug-ins run with the same permissions as the user that invoked
252          the plug-in. Sometimes this can be seen as a security risk
253          if the plug-in is not trusted. A malicious plug-in can, for example,
254          delete the entire database if invoked by the root user.
255        </para>
256       
257        <para>
258          An administrator can choose to give a plug-in only those
259          permissions that is required to complete it's task. If the plug-in
260          permission system is enabled for a plug-in the default is to deny
261          all actions. Then, the administrator must assign permissions to
262          the plug-in. There are two variants:
263        </para>
264       
265        <itemizedlist>
266          <listitem>
267            <para>
268            A permission can be granted regardless of if the user that invoked
269            the plug-in had the permission or not. This makes it possible to
270            develop a plug-in that allows users to do things that they normally
271            do not have permission to do directly in the web interface.
272            </para>
273          </listitem>
274         
275          <listitem>
276            <para>
277            A permission can be granted only if the user also has the permission.
278            This is the same as not using the plug-in permission system, except that
279            unspecified permissions are always denied.
280            </para>
281          </listitem>
282        </itemizedlist>
283               
284        <note>
285          Plug-in developers can supply information about
286          the wanted permissions making it easy for the administrator to
287          just check the permissions and accept them with just a single
288          click if they make sense. See <xref linkend="plugins.permissions"/> for more information.
289        </note>
290       
291      </sect2>
292     
293    </sect1>
294   
295    <sect1 id="project_permission.projects">
296      <?dbhtml filename="projects.html" ?>
297   
298      <title>Projects</title>
299     
300      <para>
301        Projects are an important part of BASE and the permission system for several
302        reasons:
303      </para>
304     
305      <itemizedlist>
306        <listitem>
307          <para>
308          They do not require an administrator to setup and
309          use. All regular users may create a project, add items
310          to it and share it with other users. You are in complete
311          control of who gets access to the project, the items it contains
312          and which permission levels to use.
313          </para>
314        </listitem>
315       
316        <listitem>
317          <para>
318          All items in a project are treated as one collection. If a
319          new member joins the team, just give the new person access
320          to the project and that person will be able to access all
321          items in the project.
322          </para>
323        </listitem>
324     
325        <listitem>
326          <para>
327          When you create new items, they are automatically shared
328          using the settings from the active project. There is almost no
329          need to share items manually. All
330          you have to remember is to set an active project, and
331          this is easy accessible from the
332          <link linkend="webclient.intro.menubar">menu bar</link>.
333          </para>
334        </listitem>
335       
336        <listitem>
337          <para>
338          Filter out items that you do not want to see. When you have set
339          an active project you may choose to only see items that are
340          part of that project and no other items
341          (<xref linkend="webclient.itemlist.presets"/>).
342          </para>
343        </listitem>
344       
345        <listitem>
346          <para>
347          It's easy to share multiple items between projects. Items
348          may be part of more than one project. If you create a new
349          project that builds on a previous one you can easily share
350          some or all of the existing items to the new project from one
351          central place, the <guilabel>Items</guilabel> tab on the project's
352          single-item view.
353          </para>
354        </listitem>
355
356        <listitem>
357          <para>
358          It is possible to assign default protocols, software, hardware
359          and other items to a project. This makes it easier when creating
360          new items since BASE will automatically suggest, for example
361          the extraction protocol used when creating a new extract. The default
362          items are also used by the <guilabel>item overview</guilabel>
363          validation functionality, which makes it possible to spot
364          mistakes. See <xref linkend="webclient.itemoverview" />.
365          </para>
366        </listitem>
367   
368      </itemizedlist>
369     
370      <sect2 id="project_permission.projects.create">
371        <title>Creating a project</title>
372     
373        <para>
374          You can list and manage all of your projects by going to
375          <menuchoice>
376            <guimenu>View</guimenu>
377            <guimenuitem>Projects</guimenuitem>
378          </menuchoice>. Use the &gbNew; button to create a new projects.
379        </para>
380       
381      <figure
382        id="project_permission.figures.edit_project">
383        <title>Projects properties</title>
384        <screenshot>
385          <mediaobject>
386            <imageobject>
387              <imagedata
388                fileref="figures/edit_project.png" format="PNG" />
389            </imageobject>
390          </mediaobject>
391        </screenshot>
392      </figure>
393       
394      <helptext external_id="project.edit" 
395        title="Edit project">
396       
397        <para>
398        This tab allows users to enter essential
399        information about a project.
400        </para>
401       
402        <variablelist>
403        <varlistentry>
404          <term><guilabel>Name</guilabel></term>
405          <listitem>
406            <para>
407            The name of the project. We recommend that project names are unique, since
408            at some times it may need to be referenced by name.
409            </para>
410          </listitem>
411        </varlistentry>
412        <varlistentry>
413          <term><guilabel>Default permissions</guilabel></term>
414          <listitem>
415            <para>
416            This setting specify the permissions to give to new items that
417            are created while this project is the active project. The recommended
418            setting is <guilabel>delete</guilabel> permission. Optionally,
419            a permission template may be selected, in which case the permissions
420            are copied from the template to the new item.
421            <nohelp>See <xref linkend="project_permission.templates"/>
422            for more information.</nohelp>
423            </para>
424          </listitem>
425        </varlistentry>
426          <varlistentry>
427          <term><guilabel>Description</guilabel></term>
428          <listitem>
429            <para>
430            A optional description of the project.
431            </para>
432          </listitem>
433        </varlistentry>
434        </variablelist>
435       
436        <seeother>
437          <other external_id="project.edit.members">Project members</other>
438          <other external_id="project.edit.defaults">Default items</other>
439        </seeother>
440       
441      </helptext>
442     
443      </sect2>
444   
445      <sect2 id="project_permission.projects.active">
446     
447        <title>The active project</title>
448       
449        <para>
450          The active project concept is central to the sharing system.
451          You should always, with few exceptions, have a project active
452          when you work with BASE. The most important reason is that
453          new items will automatically be shared using the settings in
454          the active project. This considerably reduces
455          the time needed for managing access permissions. Without an
456          active project you would have to manually
457          set the permission on all items you create. If you have hundreds
458          of items this is a time-consuming and boring task best to be
459          avoided.
460        </para>
461       
462        <para>
463          If you work with multiple projects you will probably find the
464          filtering function that hides items that are not part
465          of the active project to be useful. As a matter of fact, if you
466          try to access an item that is part of another (not active) project
467          you will get an error message saying that you do not have
468          permission to access the item (unless you are the owner).
469        </para>
470     
471        <sect3 id="project_permission.projects.active.set">
472          <title>Selecting an active project</title>
473         
474          <para>
475            Since it's important to always have an active project
476            there are several ways to make a project 
477            the active one.
478          </para>
479         
480          <itemizedlist>
481            <listitem>
482              <para>
483                The easiest way and the one you will probably use most of the time
484                is to use the menu bar shortcut. Look in the menu for the project
485                icon
486                <guiicon>
487                  <inlinemediaobject>
488                    <imageobject>
489                      <imagedata fileref="figures/project.gif" format="GIF" />
490                    </imageobject>
491                  </inlinemediaobject>
492                </guiicon>.
493                Next to it, the name of the active project is displayed. If you see
494                <guiicon>
495                  <inlinemediaobject>
496                    <imageobject>
497                      <imagedata fileref="figures/no_active_project.gif" format="GIF" />
498                    </imageobject>
499                  </inlinemediaobject>
500                </guiicon>
501                <guilabel>- no active project -</guilabel>
502                here, it means that you have not selected a project to work in. Click on the icon or
503                project name to open a drop-down menu and select a project to set as
504                the active project. If another project is already active it will
505                automatically be inactivated.
506              </para>
507              <para>
508                The most recently used projects are listed first, then the list is filled with the
509                rest of your projects up to a maximum of 15. If you have more projects an option to
510                display the remaining projects is activated.
511              </para>
512              <tip>
513                <para>
514                The sort order of the non-recent projects is the same as the sort order on the
515                projects list page. If you, for example, want to sort the newest
516                project first, select to sort by the <guilabel>Registered</guilabel> 
517                column in descending order on the list page. The menu will automatically
518                use the same order.
519                </para>
520              </tip>
521            </listitem>
522         
523            <listitem>
524              <para>
525              Use the <menuchoice><guimenu>BASE</guimenu>
526              <guisubmenu>Select project</guisubmenu></menuchoice>
527              menu and select the project from the submenu that opens
528              up.
529              </para>
530            </listitem>
531           
532            <listitem>
533              <para>
534              Go to the <link linkend="webclient.intro.homepage">homepage</link>
535              using the <menuchoice><guimenu>View</guimenu>
536              <guisubmenu>Home</guisubmenu></menuchoice> menu and select
537              a project from the list displayed there.
538              </para>
539            </listitem>
540          </itemizedlist>
541         
542          <note>
543            Only one project can be active at a time.
544          </note>
545         
546          <caution>
547            If you change the active project while viewing an item
548            that you no longer has access to in the context of the
549            new project an error message about missing permission
550            will be displayed. Unfortunately, this is all that is displayed
551            and it may be difficult to navigate to a working page again.
552            In the worst case, you may have to go to the login page and
553            login again.
554          </caution>
555         
556        </sect3>
557
558        <sect3 id="project_permission.projects.active.autopermissions">
559          <title>Default permissions for the active project</title>
560         
561          <para>
562            When a project is active all new items you create are automatically
563            shared using the settings from the active project. If the active project
564            has a permission template the permissions from the template are copied
565            to the new item. If the project doesn't have a permission template, the
566            new item is shared to the active project with the configured default
567            level. By default, projects doesn't have a permission template
568            and the default permissions are set to
569            <emphasis>read</emphasis>, <emphasis>use</emphasis>,
570            <emphasis>write</emphasis> and <emphasis>delete</emphasis>. It is
571            possible to change the default permission level by modifying the
572            settings for the project. Simply open the edit-view page for the project
573            and select the permissions you want and save. From now on, all new
574            items will be shared with the specified permissions. Items that are
575            already in the project are not affected by the change.
576          </para>
577        </sect3>
578
579      </sect2>
580       
581      <sect2 id="project_permission.projects.share">
582        <title>How to give other users access to your project</title>
583       
584        <para>
585          First, you will need to open the <guilabel>Edit project</guilabel>
586          dialog. Here is how to do that:
587        </para>
588       
589        <orderedlist>
590          <listitem>
591            <para>
592            Navigate to the single-item view of your project
593            from the <menuchoice><guimenu>View</guimenu>
594            <guisubmenu>Projects</guisubmenu></menuchoice> list.
595            </para>
596          </listitem>
597         
598          <listitem>
599            <para>
600            Click on the &gbEdit;
601            button to open the <guilabel>Edit project</guilabel>
602            dialog.
603            </para>
604          </listitem>
605         
606          <listitem>
607            <para>
608            Switch to the <guilabel>Members tab</guilabel>. From this
609            page you can add and remove users and change the access levels
610            of existing ones.
611            </para>
612          </listitem>
613        </orderedlist>
614       
615        <figure id="project_permission.projects.members">
616          <title>Manage members of a project</title>
617          <screenshot>
618            <mediaobject>
619              <imageobject><imagedata fileref="figures/project_members.png" format="PNG" /></imageobject>
620            </mediaobject>
621          </screenshot>
622        </figure>
623       
624       
625        <helptext external_id="project.edit.members" title="Project members">
626         
627          <variablelist>
628            <varlistentry>
629              <term><guilabel>Members</guilabel></term>
630              <listitem>
631                <para>
632                The members list contains users
633                and groups that are already members of the project. The list
634                shows the name and the permission level. The permission level
635                uses a one-letter code as follows:
636                </para>
637                <itemizedlist>
638                <listitem><guilabel>R</guilabel> = Read</listitem>
639                <listitem><guilabel>U</guilabel> = Use</listitem>
640                <listitem><guilabel>W</guilabel> = Write</listitem>
641                <listitem><guilabel>D</guilabel> = Delete</listitem>
642                <listitem><guilabel>O</guilabel> = Set owner</listitem>
643                <listitem><guilabel>P</guilabel> = Set permission</listitem>
644                </itemizedlist>
645              </listitem>
646            </varlistentry>
647           
648            <varlistentry>
649              <term><guilabel>Permissions</guilabel></term>
650              <listitem>
651                <para>
652                When you select an user or group in the
653                list the current permission will be checked. To change the
654                permissions just check the permissions you want to
655                grant or uncheck the permissions you want to revoke.
656                You may select more than one user and/or group
657                and change the permissions for all of them at once.
658                </para>
659               
660                <note>
661                  <para>
662                  In most cases, you should give the project members
663                  <guilabel>use</guilabel> permission. This will allow a user
664                  to use all items in the project as well as add new items to it.
665                  If you give them <guilabel>write</guilabel> or <guilabel>delete</guilabel> 
666                  permission they will be able to modify or delete all items including
667                  those that they do not own.
668                  </para>
669                  <para>
670                  This rule is valid for all items that are shared to the project
671                  with the default <guilabel>delete</guilabel> permission. Items
672                  that are shared with a lower permission, for example,
673                  <guilabel>use</guilabel>, can be accessed with at most that
674                  permission.
675                  </para>
676                </note>
677               
678              </listitem>
679            </varlistentry>
680           
681            <varlistentry>
682              <term><guibutton>Add users</guibutton></term>
683              <listitem>
684                <para>
685                Opens a popup window that allows you to add
686                users to the project. In the popup window, mark
687                one or more users and click on the &gbOk;
688                button. The popup window will only list users that you have
689                permission to read. Unless you are an administrator, this
690                usually means that you can only see users that:
691                </para>
692                <itemizedlist>
693                  <listitem>
694                    <para>
695                    you share group memberships with
696                    (the <emphasis>Everyone</emphasis> group and groups with hidden members
697                    doesn't count)
698                    </para>
699                  </listitem>
700                  <listitem>
701                    <para>
702                    are members of the currently active project, if any.
703                    </para>
704                  </listitem>
705                </itemizedlist>
706                <para>
707                Users that already have access to the project are not included in the
708                list. If you don't see a user that you want to add to the project,
709                you'll need to talk to an administrator for setting up the proper
710                group membership.
711                </para>
712              </listitem>
713            </varlistentry>
714           
715            <varlistentry>
716              <term><guibutton>Add groups</guibutton></term>
717              <listitem>
718                <para>
719                Opens a popup window that allows you to add
720                groups to the project. In the popup window, mark
721                one or more groups and click on the &gbOk;
722                button. Unless you are
723                an administrator, the popup window will only list groups
724                that you are a member of. It will not list groups that
725                are already part of the project.
726                </para>
727              </listitem>
728            </varlistentry>
729           
730            <varlistentry>
731              <term>&gbRemove;</term>
732              <listitem>
733                <para>
734                Click on this button to remove the selected
735                users and/or groups from the project.
736                </para>
737              </listitem>   
738            </varlistentry>
739          </variablelist>
740         
741         
742          <para>
743            Use the &gbSave; button to save your
744            changes or the &gbCancel; button to
745            close the popup without saving.
746          </para>
747
748        <seeother>
749          <other external_id="project.edit">Project properties</other>
750          <other external_id="project.edit.defaults">Default items</other>
751        </seeother>
752
753        </helptext>
754
755      </sect2>
756     
757      <sect2 id ="project_permissions.project.defaults">
758        <title>Default items</title>
759       
760        <helptext external_id="project.edit.defaults" 
761          title="Default items">
762        <para>
763          A number of default item can be assigned to a project. It is possible to
764          select one raw data type and any number of platforms, variants, protocols,
765          hardware, software and array designs. The default items are used by BASE to
766          suggest default values. The subtype <nohelp>(see <xref linkend="subtypes" />)
767          </nohelp> of each item is used as a filter so that, for example, an extraction protocol is
768          suggested when creating an extract, and a hybridization protocol when creating
769          a hybridization. Use the various <guibutton>Add</guibutton> buttons to add
770          items to the project and the <guibutton>Remove</guibutton> button to remove them.
771        </para>
772       
773        <note>
774          <para>
775          Make sure that the items that are selected as default items also are
776          shared to the project with at least <guilabel>use</guilabel> permission.
777          Otherwise the default items will not show up for other members of the
778          project, which may result in registering incorrect data.
779          </para>
780        </note>
781       
782        <seeother>
783          <other external_id="project.edit">Project properties</other>
784          <other external_id="project.edit.members">Project members</other>
785        </seeother>
786       
787        </helptext>
788       
789        <figure
790          id="project_permission.figures.project_defaults">
791          <title>Project default items</title>
792          <screenshot>
793            <mediaobject>
794              <imageobject>
795                <imagedata
796                  fileref="figures/project_defaults.png" format="PNG" />
797              </imageobject>
798            </mediaobject>
799          </screenshot>
800        </figure>
801       
802      </sect2>
803     
804      <sect2 id="project_permission.projects.items">
805        <title>Working with the items in the project</title>
806       
807        <para>
808        If you go to the single-item view for a project you will find
809        that there is an extra tab, <guilabel>Items</guilabel>, on that
810        page.
811        <figure id="project_permission.images.projecttabs">
812          <title/>
813          <screenshot>
814            <mediaobject>
815              <imageobject><imagedata fileref="figures/project_tabs.png" format="PNG" /></imageobject>
816            </mediaobject>
817          </screenshot>
818        </figure>
819        Clicking on that tab will display a page that is similar
820        to a list view. However there are some differences:
821        </para>
822       
823        <itemizedlist>
824          <listitem>
825            <para>
826            The list is not limited to one type of item. It can display
827            all items that are part of the project.
828            </para>
829          </listitem>
830         
831          <listitem>
832            <para>
833              It support only a limited set of columns (id, name, description,
834              owner and a few more) since these are the only properties that are common
835              among all items.
836            </para>
837          </listitem>
838         
839          <listitem>
840            <para>
841              The list cannot be sorted. This is due to a limitation in the
842              query system used to generate the list.
843            </para>
844          </listitem>
845        </itemizedlist>
846       
847        <note>
848          The list only works for the active project. For all other
849          projects it will only display items that are owned by the
850          logged in user.
851        </note>
852       
853        <para>
854          There are also several similarities:
855        </para>
856       
857        <itemizedlist>
858          <listitem>
859            <para>
860              It supports all of the regular multi-item
861              operations such as delete, restore, share
862              and change owner.
863            </para>
864          </listitem>
865         
866          <listitem>
867            <para>
868              Clicking on the name of the item will take you to the
869              single-item view of that item. Holding down <keycap>CTRL</keycap>,
870              <keycap>ALT</keycap> or <keycap>SHIFT</keycap> while clicking,
871              will open the edit popup.
872            </para>
873          </listitem>
874        </itemizedlist>
875       
876        <tip>
877          <para>
878          This list is very useful when you are creating a
879          new project, in which you want to reuse items from
880          an old project.
881          </para>
882         
883          <itemizedlist>
884            <listitem>
885              <para>
886              Activate the old project and go to this view.
887              </para>
888            </listitem>
889           
890            <listitem>
891              <para>
892                Mark the checkbox for all items that you want to
893                use in the new project.
894              </para>
895            </listitem>
896           
897            <listitem>
898              <para>
899                Click on the &gbShare; button
900                and share the items to the new project.
901              </para>
902            </listitem>
903          </itemizedlist>
904          <para>
905            If you have more than one old project, repeat the
906            above procedure.
907          </para>
908        </tip>
909       
910      </sect2>
911   
912    </sect1>
913   
914    <sect1 id="project_permission.templates">
915      <?dbhtml filename="templates.html" ?>
916      <title>Permission templates</title>
917   
918      <para>
919        A <emphasis>permission template</emphasis> is a pre-defined set of permissions
920        for users, groups and/or projects. The template makes it easy to quickly share
921        items to multiple users, groups and projects, possible with different permissions
922        for everyone. There are three major use-cases were permission templates are useful:
923      </para>
924     
925      <itemizedlist>
926        <listitem>
927          <para>
928          A permission template can be associated with project. When the project is selected
929          as the active project, the permissions from the template are copied to any new items
930          that are created. Note that the new items may or may not be shared with the active
931          project, depending on the settings in the permission template.
932          </para>
933        </listitem>
934        <listitem>
935          <para>
936          Permission templates can be selected in the <link linkend="webclient.items.share">share dialog</link>,
937          making it easier to manually share items to multiple users,
938          groups and projects in just a few clicks.
939          </para>
940        </listitem>
941        <listitem>
942          <para>
943          Permission templates can be used with some batch item importers, making it easier
944          for administrators which only needs a single data file even if the data belong to
945          different projects.
946          </para>
947        </listitem>
948      </itemizedlist>
949     
950      <para>
951        Permission templates are managed from the <menuchoice><guimenu>View</guimenu>
952        <guisubmenu>Permission templates</guisubmenu></menuchoice> menu. The template is
953        a very simple item that only has a name (required) and a description (optional).
954        We recommend that the names of the templates are kept unique, but this is not
955        enforced by BASE. To assign permissions to the template use the
956        <guibutton>Set permissions</guibutton> button. This is the same dialog as the
957        <link linkend="webclient.items.share">share dialog</link>.
958      </para>
959     
960      <note>
961        <title>Permissions are copied</title>
962        <para>
963        When a permission template is used the permissions are <emphasis>copied</emphasis>
964        to the items. Modifications to the template that are made afterwards doesn't
965        affect the permissions for the items on which the template was used.
966        </para>
967      </note>
968    </sect1>
969</chapter>
Note: See TracBrowser for help on using the repository browser.