Apr 16, 2007, 1:50:26 PM (15 years ago)
Nicklas Nordborg

References #526: Write "Projects and the permission system"

1 edited


  • trunk/doc/src/docbook/userdoc/project_permission.xml

    r3242 r3245  
    3030  <!-- <?dbhtml dir="project_permission"?> -->
    3131  <title>Projects and the permission system</title>
    32     <sect1>
    33       <title></title>
    34       <para></para>
     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>
    35197    </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="project_permission.projects.active">
     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="project_permission.projects.active.set">
     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 TracChangeset for help on using the changeset viewer.