GPMSWiki/CoreDocumentation/Implementation: Difference between revisions

From BRF-Software
Jump to navigation Jump to search
imported>LutzKrause
No edit summary
imported>LutzKrause
No edit summary
Line 40: Line 40:
used to model individual properties and features of special types of
used to model individual properties and features of special types of
projects (e.g. a textitProject::GENDB defines an additional genetic code.  
projects (e.g. a textitProject::GENDB defines an additional genetic code.  
GenDB~citeGENDB:03 is an annotation system developed at the Center for
GenDB is an annotation system developed at the Center for
Genome Research, Bielefeld University).
Genome Research, Bielefeld University).


Line 325: Line 325:
|  add a new  Host to the GPMS
|  add a new  Host to the GPMS
|-
|-
| add_datasource_type
| add_datasource_!type
|  register a new  DataSource
|  register a new  DataSource
|-
|-
| add_db_api_type
| add_db_api_!type
|  register a new  API_Type
|  register a new  API_Type
|-
|-
| add_dbms_type
| add_dbms_!type
|  create a  DBMS_Type
|  create a  DBMS_Type
|-
|-
Line 373: Line 373:
|  remove a  Host
|  remove a  Host
|-
|-
| del_datasource_type
| del_datasource_!type
|  delete a  DataSource_Type  
|  delete a  DataSource_Type  
|-
|-
Line 379: Line 379:
|  remove a  DataSource from the GPMS
|  remove a  DataSource from the GPMS
|-
|-
| del_db_api_type
| del_db_api_!type
|  delete a  DB_API_Type
|  delete a  DB_API_Type
|-
|-
| del_dbms_type
| del_dbms_!type
|  remove a  DBMS_Type from the GPMS
|  remove a  DBMS_Type from the GPMS
|-
|-
Line 462: Line 462:
example: add_datasource2project -D gendb_test -p gendbtest
example: add_datasource2project -D gendb_test -p gendbtest


=== add_datasource_type ===
=== add_datasource_!type ===


add a Datasource_Type to project management database
add a Datasource_Type to project management database


usage: add_datasource_type -y <name> [-s <SQL_dump_file> -v]
usage: add_datasource_!type -y <name> [-s <SQL_dump_file> -v]


where: -y <name> the Datasource_Types name
where: -y <name> the Datasource_Types name
Line 474: Line 474:
       -h print this help message
       -h print this help message


example: add_datasource_type -y GENDB -s /vol/gendb/src/dbschema/GenDB.sql  
example: add_datasource_!type -y GENDB -s /vol/gendb/src/dbschema/GenDB.sql  


=== add_db ===
=== add_db ===
Line 480: Line 480:
add a Database (Datasource::DB) to project management database
add a Database (Datasource::DB) to project management database


usage: add_db -H <hostname> -t <dbms_type> -y <datasource_type>
usage: add_db -H <hostname> -t <dbms_!type> -y <datasource_!type>
               -A <db_api_type> ( -D db_name | -p <project> )
               -A <db_api_!type> ( -D db_name | -p <project> )
               [-d <description> -e -v]
               [-d <description> -e -v]


where: -H <hostname> name of the Databases Host
where: -H <hostname> name of the Databases Host
       -t <dbms_type> name of the Databases DBMS_Type
       -t <dbms_!type> name of the Databases DBMS_Type
       -y <datasource_type> name of the Databases Datasource_Type
       -y <datasource_!type> name of the Databases Datasource_Type
       -A <db_api_type name> name of the Datasourced DB_API_Type
       -A <db_api_!type name> name of the Datasourced DB_API_Type
       -D the Databases name
       -D the Databases name
           if -D is omitted Database gets same name as Project
           if -D is omitted Database gets same name as Project
Line 500: Line 500:
example: add_db -D gendb_test -H dbhost -t MySQL-3.23.27 -y GENDB -A O2DBI2
example: add_db -D gendb_test -H dbhost -t MySQL-3.23.27 -y GENDB -A O2DBI2


=== add_dbms_type ===
=== add_dbms_!type ===


add a DBMS_Type to project management database
add a DBMS_Type to project management database


usage: add_dbms_type -t <name> -V <version number>
usage: add_dbms_!type -t <name> -V <version number>


where: -t <name> the DBMS_Types name
where: -t <name> the DBMS_Types name
Line 510: Line 510:
       -h print this help message
       -h print this help message


example: add_dbms_type -t MySQL -V '3.23.27'
example: add_dbms_!type -t MySQL -V '3.23.27'


=== add_project2meta_project ===
=== add_project2meta_project ===
Line 697: Line 697:
example: del_datasource.pl -D gendb_test -z
example: del_datasource.pl -D gendb_test -z


=== del_datasource_type ===
=== del_datasource_!type ===


removes a Datasource_Type from project management database
removes a Datasource_Type from project management database


usage: del_datasource_type.pl -y <datasource_type name>
usage: del_datasource_!type.pl -y <datasource_!type name>


where: -y <datasource_type name> name of the Datasource_Type to be removed
where: -y <datasource_!type name> name of the Datasource_Type to be removed
       -h print this help message
       -h print this help message


example: del_datasource_type.pl -y GENDB  
example: del_datasource_!type.pl -y GENDB  


=== del_dbms_type ===
=== del_dbms_!type ===


removes a DBMS_Type from project management database
removes a DBMS_Type from project management database


usage: del_dbms_type -n <dbms_type_name> -V <version> [-v]
usage: del_dbms_!type -n <dbms_!type_name> -V <version> [-v]


where: -n <dbms_type_name> name of the DBMS_Type
where: -n <dbms_!type_name> name of the DBMS_Type
       -V <version> the DBMS_Types version
       -V <version> the DBMS_Types version
       -v verbose
       -v verbose
       -h print this help message
       -h print this help message


example: del_dbms_type -n MySQL -V 3.23.48
example: del_dbms_!type -n MySQL -V 3.23.48


=== del_host ===
=== del_host ===
Line 839: Line 839:
where: -h print this help message
where: -h print this help message


=== add_db_api_type ===
=== add_db_api_!type ===


add a DB_API_Type to project management database
add a DB_API_Type to project management database


usage: add_db_api_type -A <db_api_type name> -d <description> [-v]
usage: add_db_api_!type -A <db_api_!type name> -d <description> [-v]


where: -A <db_api_type name> the DB_API_Types name
where: -A <db_api_!type name> the DB_API_Types name
       -d <description> text describing the DB_API_Type
       -d <description> text describing the DB_API_Type
       -v verbose
       -v verbose
       -h print this help message
       -h print this help message


example: add_db_api_type -A O2DBI -d "The O2DBI I database api"
example: add_db_api_!type -A O2DBI -d "The O2DBI I database api"


=== list_user_projects ===
=== list_user_projects ===
Line 863: Line 863:
example: list_user_projects -l juser
example: list_user_projects -l juser


=== del_db_api_type ===
=== del_db_api_!type ===


removes a DB_API_Type from project management database
removes a DB_API_Type from project management database


usage: del_db_api_type -A <db_api_type_name>  
usage: del_db_api_!type -A <db_api_!type_name>  


where: -A <db_api_type_name> name of the DB_API_Type
where: -A <db_api_!type_name> name of the DB_API_Type
       -h print this help message
       -h print this help message


example: del_db_api_type -A O2DBI  
example: del_db_api_!type -A O2DBI  


=== list_project_members ===
=== list_project_members ===
Line 1,045: Line 1,045:
           project rights defined for the current user.
           project rights defined for the current user.


     o projectDB_by_datasource_type_name($datasource_type_name)
     o projectDB_by_datasource_!type_name($datasource_!type_name)
           Use this method to retrieve the database of a project
           Use this method to retrieve the database of a project
           for a specified datasource_type.
           for a specified datasource_type.
Line 1,103: Line 1,103:
project. It is also possible to change the role of an existing
project. It is also possible to change the role of an existing
member. For reasons of security, only those roles can be assigned
member. For reasons of security, only those roles can be assigned
that do not include administrative privileges and are therefore marked as
that do not include administrative privileges and are therefore marked as extern.
extern.
 
= Implementation =
This chapter contains details about the implementation of the GPMS. We
describe the datamodel for the relational database and explain the attributes
of each class. Sample descriptions for the definition of roles and
rights complement this section by illustrating the implementation of
fine-grained access control.
 
== Database schema for the GPMS ==
The GPMS was developed as an object-oriented
application based on the data model described in the previous
section. Since the GPMS required a persistent storage backend we
decided to use the [http://www.cebitec.uni-bielefeld.de/groups/brf/software/wiki/O2DBIWiki O2DBI-2] system
which automatically maps the XML class descriptions onto tables that can be stored in a relational
database (auto-generated object-relational mapping of Perl objects). At the same time,
O2DBI-2 provides a client-server architecture that allows remote
connections to the system via a Perl or C++ client. The automatically
generated Perl server modules for all described classes have been
extended with additional functionality and thus form the GPMS-API. MySQL is currently
used as the database backend but other relational database management
systems (RDBMS) can be used as they are supported by the O2DBI-2
software. Figure 1 displays the current database
schema for the GPMS database (GPMSDB) as it has been generated by O2DBI-2.
 
[[Image:GPMSWiki$$CoreDocumentation$$Implementation$DBSchemaGPMS.png]]
 
== Class descriptions ==
The following sections briefly describe the relevant classes of the
data schema (see figure 1). The five core classes Project,  User,  Member,  Role and
[[DataSource]] are complemented by several simple classes that store
additional information.
 
=== Project ===
projects are the central components of the GPMSDB. They connect all
relevant classes. projects have a unique name, an additional
description, special configurations (e.g. global project settings),
and a list of datasources. Each project belongs to a specific
projectclass that is described later in this document. The general
class project has been extended by several subclasses that can be
used to model individual properties and features of special types of
projects (e.g. a textitProject::GENDB defines an additional genetic code.
GenDB~citeGENDB:03 is an annotation system developed at the Center for
Genome Research, Bielefeld University).
 
=== [[ProjectClass]] ===
A projectclass arranges projects of the same type into
groups. Additionally, a projectclass determines the available roles and
rights for the individual projects. Hence roles and
rights do not have to be defined for every project but only once
for all projects of the same projectclass. This approach reduces
the complexity of the system and the required work when administering
projects. At the same time a concise representation 
of all project related data is achieved and a consistent use of
roles and their corresponding permissions can be ensured. A
projectclass has a name and a description. An optional default
configuration file can be specified that contains standard
configuration parameters. The max_instance_number can be set to
define a maximal number of projects of a projectclass an application can
open at the same time.
 
=== User ===
Basic user data is stored in user objects. Each user object has to
provide a name, a login and an email address. A special flag can be
set to determine whether the user is an internal or external (e.g. has
access only via web frontends) user.
 
=== Member ===
A user has to become a member of a project in order to
gain access to a  Project's data. Therefore, a member object relates
a user to a project. Each member is also assigned a role that
defines the level of access for that project (see description of
Role below). Individual configurations for a project can be
stored in the User_Project_Configs.
 
=== Affiliation ===
Affiliations allow to associate users and projects with an institution
(e.g. [[CeBiTec]]). In the various web portals (e.g. MGE Portal) at the [[CeBiTec]]
users may only request access to projects that belong to the same affiliation.
Each user and project is assigned to an affiliation.
 
=== Role ===
Each member of a project has a specific role that determines
the level of access and the  User's permissions for that
project. For example, access can be granted on a very low level with
read-only permissions or with complete access onto all data, even with
the right to delete everything. Therefore, roles have a list
of rights that further define such privileges. Note that roles
are defined for a projectclass, not for each single project. An
additional "extern" flag can be used to allow setting this
role via the web frontend by external project managers. The "script" attribute can
be used to store some code that is automatically executed for newly created members
with this role.
 
=== Rights ===
rights determine the permissions of a member for a specific
project. rights are associated with database privileges. If a user is
added to a project as a member all the 
privileges determined by the rights of the corresponding role
will be granted to the user. rights are defined for a projectclass, not
for a single project. This approach does not
only simplify the maintenance of projects but also ensures a
consistent use of roles for all users that have access to projects of
a specific projectclass.
 
=== DB_Privileges ===
DB_Privileges refer to a gpmsright and represent the DBMS-specific access
privileges. They are always defined for a specific datasourcetype (see
below).
 
=== [[DataSource]] ===
Applications often need to access and store persistent external
data. These are provided as a datasource which is attached to a
project. datasources have a name, a description, a host and a
datasourcetype. The class "[[DataSource]]" has been extended by two
special types of data-sources, a database ( DB) and a so called
Application Server (see description of
[[DataSource]]::[[ApplicationServer]] below).
 
=== Host ===
Information about the host of a typical datasource are stored in
host objects. Each host has a name, a port and a description.
 
=== DataSource_Type ===
The datasourcetype determines the specific type
of a datasource. For databases the datasourcetype can also
contain a reference to a file that defines the database schema so that a
newly created database can be filled with all tables automatically
after creation. A project may only have one  DB and one
[[ApplicationServer]] of each datasourcetype so that the connection to
the correct datasource can be established automatically.
 
=== [[DataSource]]::[[ApplicationServer]] ===
An [[ApplicationServer]] is a generic datasource that can provide data for an
application. The class inherits all attributes of the datasource
class and has an additional url and a socket. Note that a project may only
have one [[ApplicationServer]] of each datasourcetype (see description
of DataSource_Type). 
 
=== [[DataSource]]::DB ===
This class represents all kinds of databases and extends the datasource
class. In addition to all inherited attributes of the
datasource class a textitDataSource::DB is described by a dbmstype and a
dbapi. Note that a project may only have
one textitDataSource::DB of each individual datasourcetype (see
description of DataSource_Type). 
 
=== DBMS_Type ===
The dbmstype describes the database management system that is used
to store the databases (e.g. mysql). A dbmstype has a name and a
version number.
 
=== DB_API_Type ===
The dbapi is a special class that can be used to define an
api for accessing a database ( [[DataSource]]::DB). For our purposes this is
in most cases an O2DBI or an OI interface.
 
=== Project::Meta ===
Project::Meta is a generic project subclass that combines several arbitrary
projects to a new project. A meta-project provides a list of
member-projects and inherits all the attributes of project.
 
== Role and Right definitions ==
The following paragraphs describe the roles and rights
as defined for the genome annotation system GenDB-2.0 which
extensively uses different roles for a sophisticated access control.
 
<!-- # -->
<!-- # ROLES defined for GenDB-2.0  -->
<!-- # -->
 
PROJECT_CLASS GENDB
 
<!-- # user with read only permissions and almost completely restricted access -->
<!-- # toles with the tag ext'' can be assigned to members via the external -->
<!-- # GPMS web frontend. Roles without this tag are not listed in the ext. -->
<!-- # web frontend. -->
ROLE Guest ext
        RIGHT basic_access
 
<!-- # user who is allowed to write annotations and recompute the observations -->
<!-- # for a single region -->
ROLE Annotator ext
        RIGHT basic_access
        RIGHT annotate
        RIGHT export_region_data
        RIGHT recompute
 
<!-- # (external) user who is allowed do most of the necessary tasks to maintain a project -->
<!-- # (e.g. import/export/edit/delete sequence, add tools and submit all jobs) -->
<!-- # this role should be used if several persons have to edit the sequence e.g. to correct frameshifts -->
ROLE Maintainer
        RIGHT basic_access
        RIGHT recompute
        RIGHT submit_jobs
        RIGHT contig_import_export             
        RIGHT edit_sequence
        RIGHT add_tools
        RIGHT export_region_data
        RIGHT delete_contig
        RIGHT annotate
        RIGHT region_prediction
 
<!-- # user who is responsible for the database and for the solution of bugs and problems -->
<!-- # can do almost everything and also MODIFY THE DATABASE (e.g. alter table) -->
ROLE Developer
        RIGHT contig_import_export
        RIGHT region_prediction
        RIGHT submit_jobs
        RIGHT recompute
        # frame-shift correction and contig update
        RIGHT edit_sequence
        RIGHT add_tools
        RIGHT export_region_data
        RIGHT delete_contig
        RIGHT configure_project
        RIGHT basic_access
        RIGHT annotate
        RIGHT modify_db
 
<!-- # user who is responsible for the project (in the majority of cases this is one of the  -->
<!-- # GenDB developers in Bielefeld), can do everything (e.g. configure project) except  -->
<!-- # modifying the database -->
<!-- # has to add Maintainers, Annotators and Guests but cannot add Developers -->
ROLE Chief
        RIGHT annotate
        RIGHT add_user
        RIGHT contig_import_export
        RIGHT region_prediction
        RIGHT submit_jobs
        RIGHT recompute
        # frame-shift correction and contig update
        RIGHT edit_sequence
        RIGHT add_tools
        RIGHT export_region_data
        RIGHT delete_contig
        RIGHT configure_project
        RIGHT basic_access
 
<!-- #################################### -->
<!-- ### RIGHTS defined for GenDB-2.0 ### -->
<!-- #################################### -->
 
PROJECT_CLASS GENDB
 
RIGHT basic_access
        DS_TYPE GENDB
                DB select
        DS_TYPE GPMSDB
                DB select
                TABLE sessions delete update insert
                TABLE sessions_not_permanent delete update insert
                TABLE sessions_permanent delete update insert
                TABLE Member_User_Project_Configs update delete insert
                TABLE Member_User_Project_Configs_hash_value update delete insert     
                TABLE ProjectManagement_counters update
 
RIGHT annotate
        DS_TYPE GENDB
                DB insert update
 
RIGHT export_region_data
 
RIGHT recompute
        DS_TYPE GENDB
                DB delete update insert
 
RIGHT submit_jobs
        DS_TYPE GENDB
                DB insert update delete
 
RIGHT contig_import_export
        DS_TYPE GENDB
                DB insert update delete
 
<!-- # may only be granted to user if user has right annotate -->
RIGHT edit_sequence
        DS_TYPE GENDB
                DB update insert
 
RIGHT add_tools
        DS_TYPE GENDB
                DB insert update
 
RIGHT delete_contig
        DS_TYPE GENDB
                DB delete
 
RIGHT region_prediction
        DS_TYPE GENDB
                DB insert update delete
 
RIGHT configure_project
        DS_TYPE GENDB
                DB insert update delete
 
RIGHT modify_db
        DS_TYPE GENDB
                DB insert update delete alter index create drop references
 
RIGHT add_user
        DS_TYPE GENDB
                DB grant insert update delete
        DS_TYPE GPMSDB
 
== Interfaces ==
In this section we describe several ways for accessing and using the GPMS.
In addition to the API that allows programmers to directly manipulate all objects
stored in the database we provide a number of scripts for
maintaining the system and a Gtk graphical user interface for the
management of users and project members. A simplified web frontend was also
implemented that supports a restricted user management for "external"
maintainers of projects.
 
=== GPMS scripts ===
The scripts listed in table 1 can be used to
initially set up the system and for maintaining projects, users, and their
memberships.
 
{| border="1" cellpadding="2" cellspacing="0"
|  name
|  description
| 
|-
| add_host
|  add a new  Host to the GPMS
|-
| add_datasource_type
|  register a new  [[DataSource]]
|-
| add_db_api_type
|  register a new  API_Type
|-
| add_dbms_type
|  create a  DBMS_Type
|-
| add_db
|  create a new  Database
|-
| add_project_class
|  create a new  [[ProjectClass]]
|-
| add_project
|  create a new  Project
|-
| add_datasource2project
|  add a  [[DataSource]] to a  Project
|-
| add_project_config
|  add configurations to a  Project
|-
| add_role
|  read and store the  Role definitions for a  [[ProjectClass]]
|-
| add_rights
|  parse a  Right definition-file and store it in the GPMS
|-
| add_user
|  register a new  User
| 
|-
| add_member
|  add an existing  User as a new  Member to a  Project
|-
| add_meta_project
|  create a new  [[MetaProject]]
|-
| add_project2meta_project
|  add a  Project to a  [[MetaProject]]
|}
 
{| border="1" cellpadding="2" cellspacing="0"
| del_host
|  remove a  Host
|-
| del_datasource_type
|  delete a  DataSource_Type
|-
| del_datasource
|  remove a  [[DataSource]] from the GPMS
|-
| del_db_api_type
|  delete a  DB_API_Type
|-
| del_dbms_type
|  remove a  DBMS_Type from the GPMS
|-
| del_project_class
|  delete a  [[ProjectClass]] from the GPMS
|-
| del_project
|  delete a  Project
|-
| del_project_config
|  remove configurations from a  Project
|-
| del_role
|  remove roles from a  [[ProjectClass]]
|-
| del_rights
|  delete rights from a  [[ProjectClass]]
|-
| del_user
|  remove a  User from the GPMS
| 
|-
| del_member
|  remove a  User from a  Project
|}
 
{| border="1" cellpadding="2" cellspacing="0"
| change_member_role
|  change the  Role of an existing  Member
|-
| export_members
|  print a list of all  Members of a  Project or
|-
|  all  Members of all  Projects of a  [[ProjectClass]] to a file
| 
|-
| rem_datasource_from_project
|  remove a  [[DataSource]] from a  Project
|-
| rem_project_from_meta_project
|  remove a  Project from a  [[MetaProject]]
|-
| list_project_members
|  print a list of all  Members of a  Project
|-
| list_projects
|  print a list of all  Projects and  Roles available for the  Project
|-
| list_user_projects
|  display a list of all  Projects that can be accessed by a  User
|-
| list_extern_user
|  print list of all extern  Users
| 
|}
 
Available scripts for manipulating the GPMS. All currently
implemented scripts for manipulating the GPMS are listed above. Executing a
script without parameters will print a detailed description and a complete
list of available options.
 
All scripts listed above are executed using the wrapper script GPMS
which sets several installation specific environment
variables. Executing this script without parameters will list all available
scripts and print a usage message. The following paragraphs describe the use
of each script and introduce their options.
 
=== add_datasource2project ===
 
add a Datasource to a Project in the GPMS
 
usage: add_datasource2project -D <datasource name> -p <project name> [-v]
 
where: -D <datasource name> name of the Datasource
      -p <project name> the Proejcts name
      -v verbose
      -h print this help message
 
example: add_datasource2project -D gendb_test -p gendbtest
 
=== add_datasource_type ===
 
add a Datasource_Type to project management database
 
usage: add_datasource_type -y <name> [-s <SQL_dump_file> -v]
 
where: -y <name> the Datasource_Types name
      -s <SQL_dump_file> SQL dump file, with SQL statements creating
                          a Database of this Type
      -v verbose
      -h print this help message
 
example: add_datasource_type -y GENDB -s /vol/gendb/src/dbschema/GenDB.sql
 
=== add_db ===
 
add a Database (Datasource::DB) to project management database
 
usage: add_db -H <hostname> -t <dbms_type> -y <datasource_type>
              -A <db_api_type> ( -D db_name | -p <project> )
              [-d <description> -e -v]
 
where: -H <hostname> name of the Databases Host
      -t <dbms_type> name of the Databases DBMS_Type
      -y <datasource_type> name of the Databases Datasource_Type
      -A <db_api_type name> name of the Datasourced DB_API_Type
      -D the Databases name
          if -D is omitted Database gets same name as Project
      -p <project> name of Project the Database shall be added to
                    Note that either -D or -p or both must be specified
      -d <description> text describing the Database
      -e register existing Database to gpms and therefore
          without creating MySQL Database
      -v verbose
      -h print this help message
 
example: add_db -D gendb_test -H dbhost -t MySQL-3.23.27 -y GENDB -A O2DBI2
 
=== add_dbms_type ===
 
add a DBMS_Type to project management database
 
usage: add_dbms_type -t <name> -V <version number>
 
where: -t <name> the DBMS_Types name
      -V <version number> the DBMS_Types version
      -h print this help message
 
example: add_dbms_type -t MySQL -V '3.23.27'
 
=== add_project2meta_project ===
 
add a Project to a META Project in the GPMS
 
usage: add_project2meta_project -p <project_name> -m <meta_project_name> [-v]
 
where: -p <project_name> the Projects name
      -m <meta_project_name> name of the META Project
      -v verbose
      -h print this help message
 
example: add_project2meta_project -p gendb_test -m meta_test
 
=== del_project ===
 
removes a Project and the project members from the GPMS
 
usage: del_project -p <project name> [-z -v]
 
where: -p <project name> name of the Project
      -z drop and remove the Projects Databases and Datasources not used by
          any other Project from the gpms databases
      -v verbose
      -h print this help massage
 
example: del_project -p gendb_test
 
=== add_host ===
 
add a Database Host to project management database
 
usage: add_host -H <hostname> [-P <port number>] [-d <description>]
 
where: -H <hostname> the Hosts name
      -P <port number> the Hosts port number
      -d <description> text decribing the Host
      -h print this help message
 
example: add_host -H dbhost
 
=== add_member ===
 
add a new Member to a Project in project management database
 
usage: add_member -l <user login> -p <project name> -r <role> [-v]
 
where: -l <user login> User login of new Member
      -p <project name> name of Project the User shall be added to as Member
      -r <role> the new Members Role
      -v verbose
      -h print this help message
 
example: add_member -l juser -p gendb_test -r Annotator
 
=== add_meta_project ===
use add_project with -m option!
 
=== add_project ===
 
add a new Project to project management database
 
usage: add_project -p <name> -c <project_class> -d <description>
      [-v -s <project sub class>]
 
where : -p <name> the Projects name
        -c <project_class> the Projects Project_Class
        -d <description> Project description
        -s <project sub class> subclass of [[ProjectManagement]]::Project
          available subclasses: EMMA, GenDB, ProDB, Biomake, GPMS, META, WHOIS
        -v verbose
        -h print this help message
 
example: add_project -p gendb_test -c GENDB -d "The GenDB DB" -s GenDG
 
=== del_rights ===
 
removes single Right or all Rights of a Project_Class from the GPMS
 
Note: before script can be used all Roles using the Rights of the Project_Class
      must be removed!
 
usage: del_rights -c project_class (-r <right_name> | -a) [-v]
 
where: -r <right_name> name of a single Right to be removed
      -a remove all rights of the Project_Class
      -v verbose
      -h print this help message
 
example: del_rights -r use_gpmsdb -c GENDB
 
=== add_project_class ===
 
add a Project_Class to project management database
 
usage: add_project_class -c <project class name> [-d description]
                        [-i <max instance number> -u <config file>]
 
where : -c <project class name> name of new Project_Class
        -d <description> description of new Project_Class
        -i <max instance number> maximal number of Projects a
          Meta Project of this Project_Class may contain
        -u <config file> default config file for new Projects of this Class
        -h print this help message
 
example: add_project_class -c GENDB  -d GENDB Projects
 
=== add_project_config ===
 
add Project Configs to project management system
 
usage: add_project_config -p <project> -k <config_key> -V <config_value>
 
where: -p <project> the Projects name
      -k <config_key> the key of the Config to be added,
                      since Project Configs are a hash
      -V <config_value> the Configuration values
      -h print this help message
 
example: add_project_config -p gendb_test -k genetik_code -V 11
 
=== add_rights ===
 
adds new Rights to Project_Class to project management database
 
usage: add_rights  -f <file name> [-v]
 
where: -f <file name> name of file defining the Rights
      -v verbose
      -h print the help message
 
example: add_rights.pl -f "/vol/gendb/src/rights"
 
=== add_role ===
 
add new Roles to a Project_Class in project management database
 
usage: add_role -f <file_name> [-v]
 
where: -f <file name> name of file defining the Roles to be added
      -v verbose
      -h print this help message
 
example: add_role -f roles.txt
 
=== add_user ===
 
add a User to project management database
 
usage: add_user -l <login> -f <full name> [-e <email address> -x]
 
where: -l <login> the Users login
      -f <full name> the Users surname and first name
      -e <email address> the Users email adress
      -x User is extern
      -h print this help message
 
example: add_user -l juser -f 'Joe User' -e juser@Genetik.Uni-Bielefeld.DE
 
=== change_member_role ===
 
change the Role from a Project Member
 
usage: change_member_role.pl -l <user login> -p <project> -r <role> [-v]
 
where: -l <user login> the Members login
      -p <project> name of the Project
      -r <role> the new Role the Member shall get
      -v verbose
      -h print this help message
 
example: change_member_role.pl -l juser -p gendbtest -r Annotator
 
=== del_datasource ===
 
removes a Datasource from project management database
 
usage: del_datasource.pl -D <datasource name> [-z -v]
 
where: -D <datasource name> the Datasouces name
      -z drop database from the MySQL DB
      -v verbose
      -h print this help message
 
example: del_datasource.pl -D gendb_test -z
 
=== del_datasource_type ===
 
removes a Datasource_Type from project management database
 
usage: del_datasource_type.pl -y <datasource_type name>
 
where: -y <datasource_type name> name of the Datasource_Type to be removed
      -h print this help message
 
example: del_datasource_type.pl -y GENDB
 
=== del_dbms_type ===
 
removes a DBMS_Type from project management database
 
usage: del_dbms_type -n <dbms_type_name> -V <version> [-v]
 
where: -n <dbms_type_name> name of the DBMS_Type
      -V <version> the DBMS_Types version
      -v verbose
      -h print this help message
 
example: del_dbms_type -n MySQL -V 3.23.48
 
=== del_host ===
 
removes a Host from project management database
 
usage: del_host -H <host_name> name
 
where: -H <host_name> name of Host to be removed
      -h print this help message
 
example: del_host -H dbhost
 
=== del_member ===
 
removes single or all Members from a Project
 
usage: del_member ( -a | -l <user login> [-q] ) -p <project name> [-f -v]
 
where: -p <project name> name of the Project
      -a remove all Members from Project
      -l user login from single Member to be removed
      -q do not revoke MySQL privileges when removing single Member
      -f force: Member is deleted even if the db privileges
                can not be revoked
      -v verbose
      -h print this help message
 
example: del_member -l jouser -p gendbtest
 
=== del_role ===
 
removes one or all Roles of a Project_Class from the GPMS
 
usage: del_role -c <project_class> (-a | -r <role name> ) [-f -v]
 
where: -c <project_class> name of the Project_Class
      -a remove all Roles of the Project_Class
      -f force, Members of all Projects of Project_Class first
      -v verbose
      -h print this help message
 
example: del_role -r User -c GENDB
 
=== del_project_class ===
 
removes a Project_Class from project management database
 
usage: del_project_class -c <project_class name>
 
where: -c <project_class name> name of the Project_Class
      -h print this help message
 
example: del_project_class -c GENDB
 
=== del_project_config ===
 
delete Project Configs from project management system
 
usage: del_project_config -p <project_name> -k <config key>
 
where: -p <project_name> name of the Project
      -k <config key> the key value of configuration entry to be removed
      -h print this help message
 
example: del_project_config -p gendb_test -k genetik_code
 
=== export_members ===
 
print a list of all Members of a Project or all Members of all
                Projects of a Project_Class to a file
 
usage: export_members (-p <project name> | -c <project_class> | -a)
                      -f <file_name>
 
where: -p <project name> Print all Members of this Project to a file
      -c <project_class name> Print all Members of Projects of this
                              Project_Class to a file
      -a Print all Members of every Project to a file
      -h print this help message
 
example: export_members -p gendbtest -f gendbtest_members
 
=== del_user ===
 
removes a User of project management database
 
usage: del_user -l <login> [-v]
 
where: -l <login> the Users login
      -v verbose
      -h print this help message
 
example: del_user -l jouser
 
=== rem_datasource_from_project ===
 
removes a Datasource from a Project
 
usage: rem_datasource_from_project -D <datasource_name> -p <project_name>
                                  [-f -v]
 
where: -D <datasource_name> name of the Datasource to be removed from Project
      -p <project_name> name of the Project
      -f force: also remove datasource even if not all member privileges
                could be revoked
      -v verbose
      -h print this help message
 
example: rem_datasource_from_project -D gendb_test -p gendb_test_project
 
=== list_projects ===
 
list Projects with available Roles from
                project management database
 
usage: list_projects
 
where: -h print this help message
 
=== add_db_api_type ===
 
add a DB_API_Type to project management database
 
usage: add_db_api_type -A <db_api_type name> -d <description> [-v]
 
where: -A <db_api_type name> the DB_API_Types name
      -d <description> text describing the DB_API_Type
      -v verbose
      -h print this help message
 
example: add_db_api_type -A O2DBI -d "The O2DBI I database api"
 
=== list_user_projects ===
 
get Projects of a User from project management database
 
usage: list_user_projects -l <user login>
 
where: -l <user login> the Users login
      -h print this help message
 
example: list_user_projects -l juser
 
=== del_db_api_type ===
 
removes a DB_API_Type from project management database
 
usage: del_db_api_type -A <db_api_type_name>
 
where: -A <db_api_type_name> name of the DB_API_Type
      -h print this help message
 
example: del_db_api_type -A O2DBI
 
=== list_project_members ===
 
list Project Members with their Role
 
usage: list_project_members -p <Project name> [-r]
 
where: -p <Project name> the Projects name
      -r sort Members by Role
      -h print this help message
 
example: list_project_members -p gendb_test
 
=== list_extern_users ===
 
list_extern_user - list all extern Users and genereates MySQL statements to obtiain
                  consistent MySQL privileges for extern users
 
usage: list_user_projects [-g]
 
where: -g generate MySQL statements
      -h print this help message
 
example: list_user_projects -l juser
 
=== rem_project_from_meta_project ===
 
removes a Project from a META Project
 
usage: rem_project_from_meta_project -p <project_name> -m <meta_project_name>
 
where: -p <project_name> name of Project to be removed from META Project
      -m <meta_project_name> name of META Project
      -h print this help message
 
example: rem_project_from_meta_project -p gendb_test -m gendb_meta
 
===  Using an Application Frame ===
In addition to the standard classes of the GPMS
we have implemented a general framework that
simplifies the necessary steps for accessing a project's data. Such an
Application Frame uses the GPMS for accessing the
datasources of a project and it also provides a number of useful
methods that are often needed by the end applications. The following
description was directly included from the documentation of the Perl module.
inputapplication_frame
 
Description
    An Application_Frame provides a general framework that
    simplifies using the General Project Management System
    (GPMS). It should be used for all O2DBI connections based on
    the GPMS (see documentation of O2BI by B. Linke for further
    details about master objects etc.).
 
Concepts
    An Application_Frame acts as a container for all GPMS data
    that are required by an application for connecting to an
    O2DBI database. It provides access to:
 
    o a [[ProjectManagement]] master object
    o an application master object
    o a [[ProjectManagement]]::Project object
    o a [[ProjectManagement]]::User object
    o a [[ProjectManagement]]::Member object
    o the users password
 
    For using the Application_Frame a subclass has to be created
    that contains an application specific _init_application
    method, that provides the application master (see the
    documentation for _init_application for more detail).  The
    Application_Frame was initially introduced for some
    bioinformatics applications developed at Center for Genome
    Research, Bielefeld University. But it may be used as well
    with every other GPMS based application.
 
Methods
    o new($login, $passwd [,$gpms_master] [,$errh])
          Constructor, used for creating a new
          GPMS::Application_Frame object that provides the O2DBI
          master objects and all GPMS data relevant for an
          application. $errh is an optional error handler method,
          which is executed if an error occurs. As an argument
          $errh receives a string containing the error message.
          When $errh is specified it will be executed in every
          method called on the object whenever an error occurs.
          The optional argument $gpms_master is a
          [[ProjectManagement]] master object. It may be used when
          several Application_Frame objects are supposed to share
          the same GPMS master.
 
    o errh([$errh])
          Method used to get/set the error handler method. $errh
          is a reference on a subroutine that is executed if an
          error occurs. The only argument that is returned is the
          error message string.
 
    o login
          This method returns the login name of an user that was
          specified in the constructor method.
 
    o passwd
          The users password is required for establishing the
          connection to a database. Therefore the password is
          provided by this method.
 
    o gpms_master([$master])
          This method can be used to get/set the O2DBI master
          object for the GPMS.
 
    o application_master([$master])
          Get/set the O2DBI master object specific for the
          application or hash of O2DBI master objects if a
          project uses more than one database.
 
    o user
          Use this method to get the [[ProjectManagement]]::User
          object.
 
    o project([$project])
          This method can be used to get/set the project.
          $project can be a [[ProjectManagement]]::Project object or
          simply the name of a project.
 
    o get_available_projects($type)
          This method returns an array reference of all usable
          projects for the specified user. The type can be used
          to specify a subclass of [[ProjectManagement]]::Project
          (e.g. [[ProjectManagement]]::Project::GENDB).
 
    o user_name
          Get the full name of the current user.
 
    o user_email
          Get the email address of the current user.
 
    o error
          Default error method that can be used to get/set an
          error message if an error occured.
 
    o _init_application($project)
          This method has to be overloaded when a new subclass is
          created. The derived method can implement project
          specific initializations. It should always return an
          application master or a reference on a hash of
          application masters if a project uses more than one
          database. Since the Application_Frame is only
          applicable for projects using the second generation of
          the O2DBI tool other applications that use the old
          version by J. Clausen have to return 1 for successful
          connections or 0 if an error occured. The $project
          argument specifies a [[ProjectManagement]]::Project for
          which the Application_Frame should be initialized.
 
    o project_name
          Get the name of the project for which the
          Application_Frame was created.
 
    o project_description
          Get the description of the currently used project.
 
    o member([$member])
          Use this method to get/set the current member.
 
    o right($right_name)
          This method returns the value for a given project right
          for the current user.  Use this method to check the
          individual permissions (rights).
 
    o rights
          This method returns a reference on a hash of all
          project rights defined for the current user.
 
    o projectDB_by_datasource_type_name($datasource_type_name)
          Use this method to retrieve the database of a project
          for a specified datasource_type.
 
    o project_dbs
          This method returns a reference on an array of all
          databases in the current project.
 
    o project_datasources
          Use this method to retrieve a reference on an array of
          all available datasources for the current project.
 
    o user_project_config([$config])
          Use this method to get/set the complete project
          configurations for the current member of a project.
          $config is a hash of hash containing the configuration
          parameters and values for different configuration
          sections.
 
    o destroy
          Delete the Application_Frame object and clean up
          everything.
 
== Graphical User Interfaces for maintaining the gpms ==
In addition to the scripts the GPMS can be maintained via a graphical
user interface implemented in Perl Gtk (see figure reffig:gpms_gui).
 
beginfigure[H]
  begincenter
    includegraphics[width=0.8columnwidth]figures/GPMS_GUI
  endcenter
  caption[Graphical user interface for the gpms.]The Gtk frontend
    of the GPMS can be used to maintain users and projects and
    provides an immediate overview.
  labelfig:gpms_gui
endfigure
 
The tree-view on the left displays all members of a selected project
sorted by the roles that were defined for the corresponding projectclass.
Another subtree shows the rights that have been defined for
each role. The tree also contains a list of all users that are
registered in the gpms. New users and members can be added via
a simple input form.
 
beginfigure[H]
  begincenter
    includegraphics[width=0.95columnwidth]figures/gpms_web
  endcenter
  caption[Web frontend for the gpms.]The web frontend
    of the GPMS can be used to maintain users and projects.
  labelfig:gpms_web
endfigure
 
Figure reffig:gpms_web shows four screenshots of different operations that
can be performed with the web frontend. All members of a project can be listed,
new users and members can be added, or existing members can be removed from a
project. It is also possible to change the role of an existing
member. For reasons of security, only those roles can be assigned
that do not include administrative privileges and are therefore marked as
extern.

Revision as of 12:31, 25 April 2005

Implementation

This chapter contains details about the implementation of the GPMS. We describe the datamodel for the relational database and explain the attributes of each class. Sample descriptions for the definition of roles and rights complement this section by illustrating the implementation of fine-grained access control.

Database schema for the GPMS

The GPMS was developed as an object-oriented application based on the data model described in the previous section. Since the GPMS required a persistent storage backend we decided to use the O2DBI-2 system which automatically maps the XML class descriptions onto tables that can be stored in a relational database (auto-generated object-relational mapping of Perl objects). At the same time, O2DBI-2 provides a client-server architecture that allows remote connections to the system via a Perl or C++ client. The automatically generated Perl server modules for all described classes have been extended with additional functionality and thus form the GPMS-API. MySQL is currently used as the database backend but other relational database management systems (RDBMS) can be used as they are supported by the O2DBI-2 software. Figure 1 displays the current database schema for the GPMS database (GPMSDB) as it has been generated by O2DBI-2.

File:GPMSWiki$$CoreDocumentation$$Implementation$DBSchemaGPMS.png

Class descriptions

The following sections briefly describe the relevant classes of the data schema (see figure 1). The five core classes Project, User, Member, Role and DataSource are complemented by several simple classes that store additional information.

Project

projects are the central components of the GPMSDB. They connect all relevant classes. projects have a unique name, an additional description, special configurations (e.g. global project settings), and a list of datasources. Each project belongs to a specific projectclass that is described later in this document. The general class project has been extended by several subclasses that can be used to model individual properties and features of special types of projects (e.g. a textitProject::GENDB defines an additional genetic code. GenDB is an annotation system developed at the Center for Genome Research, Bielefeld University).

ProjectClass

A projectclass arranges projects of the same type into groups. Additionally, a projectclass determines the available roles and rights for the individual projects. Hence roles and rights do not have to be defined for every project but only once for all projects of the same projectclass. This approach reduces the complexity of the system and the required work when administering projects. At the same time a concise representation of all project related data is achieved and a consistent use of roles and their corresponding permissions can be ensured. A projectclass has a name and a description. An optional default configuration file can be specified that contains standard configuration parameters. The max_instance_number can be set to define a maximal number of projects of a projectclass an application can open at the same time.

User

Basic user data is stored in user objects. Each user object has to provide a name, a login and an email address. A special flag can be set to determine whether the user is an internal or external (e.g. has access only via web frontends) user.

Member

A user has to become a member of a project in order to gain access to a Project's data. Therefore, a member object relates a user to a project. Each member is also assigned a role that defines the level of access for that project (see description of Role below). Individual configurations for a project can be stored in the User_Project_Configs.

Affiliation

Affiliations allow to associate users and projects with an institution (e.g. CeBiTec). In the various web portals (e.g. MGE Portal) at the CeBiTec users may only request access to projects that belong to the same affiliation. Each user and project is assigned to an affiliation.

Role

Each member of a project has a specific role that determines the level of access and the User's permissions for that project. For example, access can be granted on a very low level with read-only permissions or with complete access onto all data, even with the right to delete everything. Therefore, roles have a list of rights that further define such privileges. Note that roles are defined for a projectclass, not for each single project. An additional "extern" flag can be used to allow setting this role via the web frontend by external project managers. The "script" attribute can be used to store some code that is automatically executed for newly created members with this role.

Rights

rights determine the permissions of a member for a specific project. rights are associated with database privileges. If a user is added to a project as a member all the privileges determined by the rights of the corresponding role will be granted to the user. rights are defined for a projectclass, not for a single project. This approach does not only simplify the maintenance of projects but also ensures a consistent use of roles for all users that have access to projects of a specific projectclass.

DB_Privileges

DB_Privileges refer to a gpmsright and represent the DBMS-specific access privileges. They are always defined for a specific datasourcetype (see below).

DataSource

Applications often need to access and store persistent external data. These are provided as a datasource which is attached to a project. datasources have a name, a description, a host and a datasourcetype. The class "DataSource" has been extended by two special types of data-sources, a database ( DB) and a so called Application Server (see description of DataSource::ApplicationServer below).

Host

Information about the host of a typical datasource are stored in host objects. Each host has a name, a port and a description.

DataSource_Type

The datasourcetype determines the specific type of a datasource. For databases the datasourcetype can also contain a reference to a file that defines the database schema so that a newly created database can be filled with all tables automatically after creation. A project may only have one DB and one ApplicationServer of each datasourcetype so that the connection to the correct datasource can be established automatically.

DataSource::ApplicationServer

An ApplicationServer is a generic datasource that can provide data for an application. The class inherits all attributes of the datasource class and has an additional url and a socket. Note that a project may only have one ApplicationServer of each datasourcetype (see description of DataSource_Type).

DataSource::DB

This class represents all kinds of databases and extends the datasource class. In addition to all inherited attributes of the datasource class a textitDataSource::DB is described by a dbmstype and a dbapi. Note that a project may only have one textitDataSource::DB of each individual datasourcetype (see description of DataSource_Type).

DBMS_Type

The dbmstype describes the database management system that is used to store the databases (e.g. mysql). A dbmstype has a name and a version number.

DB_API_Type

The dbapi is a special class that can be used to define an api for accessing a database ( DataSource::DB). For our purposes this is in most cases an O2DBI or an OI interface.

Project::Meta

Project::Meta is a generic project subclass that combines several arbitrary projects to a new project. A meta-project provides a list of member-projects and inherits all the attributes of project.

Role and Right definitions

The following paragraphs describe the roles and rights as defined for the genome annotation system GenDB-2.0 which extensively uses different roles for a sophisticated access control.


PROJECT_CLASS GENDB

ROLE Guest ext 

       RIGHT basic_access

ROLE Annotator ext 

       RIGHT basic_access
       RIGHT annotate
       RIGHT export_region_data
       RIGHT recompute

ROLE Maintainer 

       RIGHT basic_access
       RIGHT recompute
       RIGHT submit_jobs
       RIGHT contig_import_export              
       RIGHT edit_sequence
       RIGHT add_tools
       RIGHT export_region_data
       RIGHT delete_contig
       RIGHT annotate
       RIGHT region_prediction

ROLE Developer 

       RIGHT contig_import_export
       RIGHT region_prediction
       RIGHT submit_jobs
       RIGHT recompute
       # frame-shift correction and contig update
       RIGHT edit_sequence 
       RIGHT add_tools
       RIGHT export_region_data
       RIGHT delete_contig
       RIGHT configure_project
       RIGHT basic_access
       RIGHT annotate
       RIGHT modify_db

ROLE Chief 

       RIGHT annotate
       RIGHT add_user
       RIGHT contig_import_export
       RIGHT region_prediction
       RIGHT submit_jobs
       RIGHT recompute
       # frame-shift correction and contig update
       RIGHT edit_sequence 
       RIGHT add_tools
       RIGHT export_region_data
       RIGHT delete_contig
       RIGHT configure_project
       RIGHT basic_access


PROJECT_CLASS GENDB

RIGHT basic_access 

       DS_TYPE GENDB
               DB select
       DS_TYPE GPMSDB
               DB select
               TABLE sessions delete update insert 
               TABLE sessions_not_permanent delete update insert
               TABLE sessions_permanent delete update insert
               TABLE Member_User_Project_Configs update delete insert
               TABLE Member_User_Project_Configs_hash_value update delete insert       
               TABLE ProjectManagement_counters update

RIGHT annotate 

       DS_TYPE GENDB
               DB insert update

RIGHT export_region_data

RIGHT recompute 

       DS_TYPE GENDB
               DB delete update insert

RIGHT submit_jobs 

       DS_TYPE GENDB
               DB insert update delete

RIGHT contig_import_export 

       DS_TYPE GENDB
               DB insert update delete

RIGHT edit_sequence 

       DS_TYPE GENDB 
               DB update insert

RIGHT add_tools 

       DS_TYPE GENDB
               DB insert update

RIGHT delete_contig 

       DS_TYPE GENDB
               DB delete

RIGHT region_prediction 

       DS_TYPE GENDB
               DB insert update delete

RIGHT configure_project 

       DS_TYPE GENDB
               DB insert update delete

RIGHT modify_db 

       DS_TYPE GENDB
               DB insert update delete alter index create drop references

RIGHT add_user 

       DS_TYPE GENDB
               DB grant insert update delete 
       DS_TYPE GPMSDB

Interfaces

In this section we describe several ways for accessing and using the GPMS. In addition to the API that allows programmers to directly manipulate all objects stored in the database we provide a number of scripts for maintaining the system and a Gtk graphical user interface for the management of users and project members. A simplified web frontend was also implemented that supports a restricted user management for "external" maintainers of projects.

GPMS scripts

The scripts listed in table 1 can be used to initially set up the system and for maintaining projects, users, and their memberships.

name description
add_host add a new Host to the GPMS
add_datasource_!type register a new DataSource
add_db_api_!type register a new API_Type
add_dbms_!type create a DBMS_Type
add_db create a new Database
add_project_class create a new ProjectClass
add_project create a new Project
add_datasource2project add a DataSource to a Project
add_project_config add configurations to a Project
add_role read and store the Role definitions for a ProjectClass
add_rights parse a Right definition-file and store it in the GPMS
add_user register a new User
add_member add an existing User as a new Member to a Project
add_meta_project create a new MetaProject
add_project2meta_project add a Project to a MetaProject
del_host remove a Host
del_datasource_!type delete a DataSource_Type
del_datasource remove a DataSource from the GPMS
del_db_api_!type delete a DB_API_Type
del_dbms_!type remove a DBMS_Type from the GPMS
del_project_class delete a ProjectClass from the GPMS
del_project delete a Project
del_project_config remove configurations from a Project
del_role remove roles from a ProjectClass
del_rights delete rights from a ProjectClass
del_user remove a User from the GPMS
del_member remove a User from a Project
change_member_role change the Role of an existing Member
export_members print a list of all Members of a Project or
all Members of all Projects of a ProjectClass to a file
rem_datasource_from_project remove a DataSource from a Project
rem_project_from_meta_project remove a Project from a MetaProject
list_project_members print a list of all Members of a Project
list_projects print a list of all Projects and Roles available for the Project
list_user_projects display a list of all Projects that can be accessed by a User
list_extern_user print list of all extern Users

Available scripts for manipulating the GPMS. All currently implemented scripts for manipulating the GPMS are listed above. Executing a script without parameters will print a detailed description and a complete list of available options.

All scripts listed above are executed using the wrapper script GPMS which sets several installation specific environment variables. Executing this script without parameters will list all available scripts and print a usage message. The following paragraphs describe the use of each script and introduce their options.

add_datasource2project

add a Datasource to a Project in the GPMS

usage: add_datasource2project -D <datasource name> -p <project name> [-v]

where: -D <datasource name> name of the Datasource 

      -p <project name> the Proejcts name
      -v verbose 
      -h print this help message

example: add_datasource2project -D gendb_test -p gendbtest

add_datasource_!type

add a Datasource_Type to project management database

usage: add_datasource_!type -y <name> [-s <SQL_dump_file> -v]

where: -y <name> the Datasource_Types name 

      -s <SQL_dump_file> SQL dump file, with SQL statements creating
                         a Database of this Type
      -v verbose
      -h print this help message

example: add_datasource_!type -y GENDB -s /vol/gendb/src/dbschema/GenDB.sql

add_db

add a Database (Datasource::DB) to project management database

usage: add_db -H <hostname> -t <dbms_!type> -y <datasource_!type> 

             -A <db_api_!type> ( -D db_name | -p <project> )
             [-d <description> -e -v]

where: -H <hostname> name of the Databases Host 

      -t <dbms_!type> name of the Databases DBMS_Type
      -y <datasource_!type> name of the Databases Datasource_Type
      -A <db_api_!type name> name of the Datasourced DB_API_Type
      -D the Databases name
         if -D is omitted Database gets same name as Project
      -p <project> name of Project the Database shall be added to
                   Note that either -D or -p or both must be specified
      -d <description> text describing the Database
      -e register existing Database to gpms and therefore
         without creating MySQL Database
      -v verbose
      -h print this help message

example: add_db -D gendb_test -H dbhost -t MySQL-3.23.27 -y GENDB -A O2DBI2

add_dbms_!type

add a DBMS_Type to project management database

usage: add_dbms_!type -t <name> -V <version number>

where: -t <name> the DBMS_Types name 

      -V <version number> the DBMS_Types version
      -h print this help message

example: add_dbms_!type -t MySQL -V '3.23.27'

add_project2meta_project

add a Project to a META Project in the GPMS

usage: add_project2meta_project -p <project_name> -m <meta_project_name> [-v]

where: -p <project_name> the Projects name 

      -m <meta_project_name> name of the META Project
      -v verbose
      -h print this help message

example: add_project2meta_project -p gendb_test -m meta_test

del_project

removes a Project and the project members from the GPMS

usage: del_project -p <project name> [-z -v]

where: -p <project name> name of the Project 

      -z drop and remove the Projects Databases and Datasources not used by 
         any other Project from the gpms databases
      -v verbose 
      -h print this help massage

example: del_project -p gendb_test

add_host

add a Database Host to project management database

usage: add_host -H <hostname> [-P <port number>] [-d <description>]

where: -H <hostname> the Hosts name 

      -P <port number> the Hosts port number
      -d <description> text decribing the Host
      -h print this help message

example: add_host -H dbhost

add_member

add a new Member to a Project in project management database

usage: add_member -l <user login> -p <project name> -r <role> [-v]

where: -l <user login> User login of new Member 

      -p <project name> name of Project the User shall be added to as Member
      -r <role> the new Members Role
      -v verbose 
      -h print this help message

example: add_member -l juser -p gendb_test -r Annotator

add_meta_project

use add_project with -m option!

add_project

add a new Project to project management database

usage: add_project -p <name> -c <project_class> -d <description> 

      [-v -s <project sub class>]

where : -p <name> the Projects name 

       -c <project_class> the Projects Project_Class
       -d <description> Project description
       -s <project sub class> subclass of ProjectManagement::Project
          available subclasses: EMMA, GenDB, ProDB, Biomake, GPMS, META, WHOIS
       -v verbose
       -h print this help message

example: add_project -p gendb_test -c GENDB -d "The GenDB DB" -s GenDG

del_rights

removes single Right or all Rights of a Project_Class from the GPMS

Note: before script can be used all Roles using the Rights of the Project_Class 

     must be removed!

usage: del_rights -c project_class (-r <right_name> | -a) [-v]

where: -r <right_name> name of a single Right to be removed 

      -a remove all rights of the Project_Class
      -v verbose
      -h print this help message

example: del_rights -r use_gpmsdb -c GENDB

add_project_class

add a Project_Class to project management database

usage: add_project_class -c <project class name> [-d description] 

                        [-i <max instance number> -u <config file>]

where : -c <project class name> name of new Project_Class 

       -d <description> description of new Project_Class
       -i <max instance number> maximal number of Projects a
          Meta Project of this Project_Class may contain 
       -u <config file> default config file for new Projects of this Class
       -h print this help message

example: add_project_class -c GENDB -d GENDB Projects

add_project_config

add Project Configs to project management system

usage: add_project_config -p <project> -k <config_key> -V <config_value>

where: -p <project> the Projects name 

      -k <config_key> the key of the Config to be added,
                      since Project Configs are a hash
      -V <config_value> the Configuration values
      -h print this help message

example: add_project_config -p gendb_test -k genetik_code -V 11

add_rights

adds new Rights to Project_Class to project management database

usage: add_rights -f <file name> [-v]

where: -f <file name> name of file defining the Rights 

      -v verbose
      -h print the help message

example: add_rights.pl -f "/vol/gendb/src/rights"

add_role

add new Roles to a Project_Class in project management database

usage: add_role -f <file_name> [-v]

where: -f <file name> name of file defining the Roles to be added 

      -v verbose
      -h print this help message

example: add_role -f roles.txt

add_user

add a User to project management database

usage: add_user -l <login> -f <full name> [-e <email address> -x]

where: -l <login> the Users login 

      -f <full name> the Users surname and first name
      -e <email address> the Users email adress
      -x User is extern
      -h print this help message

example: add_user -l juser -f 'Joe User' -e juser@Genetik.Uni-Bielefeld.DE

change_member_role

change the Role from a Project Member

usage: change_member_role.pl -l <user login> -p <project> -r <role> [-v]

where: -l <user login> the Members login 

      -p <project> name of the Project
      -r <role> the new Role the Member shall get
      -v verbose
      -h print this help message

example: change_member_role.pl -l juser -p gendbtest -r Annotator

del_datasource

removes a Datasource from project management database

usage: del_datasource.pl -D <datasource name> [-z -v]

where: -D <datasource name> the Datasouces name 

      -z drop database from the MySQL DB
      -v verbose
      -h print this help message

example: del_datasource.pl -D gendb_test -z

del_datasource_!type

removes a Datasource_Type from project management database

usage: del_datasource_!type.pl -y <datasource_!type name>

where: -y <datasource_!type name> name of the Datasource_Type to be removed 

      -h print this help message

example: del_datasource_!type.pl -y GENDB

del_dbms_!type

removes a DBMS_Type from project management database

usage: del_dbms_!type -n <dbms_!type_name> -V <version> [-v]

where: -n <dbms_!type_name> name of the DBMS_Type 

      -V <version> the DBMS_Types version
      -v verbose
      -h print this help message

example: del_dbms_!type -n MySQL -V 3.23.48

del_host

removes a Host from project management database

usage: del_host -H <host_name> name

where: -H <host_name> name of Host to be removed 

      -h print this help message

example: del_host -H dbhost

del_member

removes single or all Members from a Project

usage: del_member ( -a | -l <user login> [-q] ) -p <project name> [-f -v]

where: -p <project name> name of the Project 

      -a remove all Members from Project
      -l user login from single Member to be removed
      -q do not revoke MySQL privileges when removing single Member
      -f force: Member is deleted even if the db privileges
                can not be revoked
      -v verbose
      -h print this help message

example: del_member -l jouser -p gendbtest

del_role

removes one or all Roles of a Project_Class from the GPMS

usage: del_role -c <project_class> (-a | -r <role name> ) [-f -v]

where: -c <project_class> name of the Project_Class 

      -a remove all Roles of the Project_Class
      -f force, Members of all Projects of Project_Class first
      -v verbose
      -h print this help message

example: del_role -r User -c GENDB

del_project_class

removes a Project_Class from project management database

usage: del_project_class -c <project_class name>

where: -c <project_class name> name of the Project_Class 

      -h print this help message

example: del_project_class -c GENDB

del_project_config

delete Project Configs from project management system

usage: del_project_config -p <project_name> -k <config key>

where: -p <project_name> name of the Project 

      -k <config key> the key value of configuration entry to be removed
      -h print this help message

example: del_project_config -p gendb_test -k genetik_code

export_members

print a list of all Members of a Project or all Members of all 

                Projects of a Project_Class to a file

usage: export_members (-p <project name> | -c <project_class> | -a) 

                     -f <file_name>

where: -p <project name> Print all Members of this Project to a file 

      -c <project_class name> Print all Members of Projects of this
                              Project_Class to a file
      -a Print all Members of every Project to a file
      -h print this help message

example: export_members -p gendbtest -f gendbtest_members

del_user

removes a User of project management database

usage: del_user -l <login> [-v]

where: -l <login> the Users login 

      -v verbose
      -h print this help message

example: del_user -l jouser

rem_datasource_from_project

removes a Datasource from a Project

usage: rem_datasource_from_project -D <datasource_name> -p <project_name> 

                                  [-f -v]

where: -D <datasource_name> name of the Datasource to be removed from Project 

      -p <project_name> name of the Project
      -f force: also remove datasource even if not all member privileges
                could be revoked
      -v verbose
      -h print this help message

example: rem_datasource_from_project -D gendb_test -p gendb_test_project

list_projects

list Projects with available Roles from 

               project management database

usage: list_projects

where: -h print this help message

add_db_api_!type

add a DB_API_Type to project management database

usage: add_db_api_!type -A <db_api_!type name> -d <description> [-v]

where: -A <db_api_!type name> the DB_API_Types name 

      -d <description> text describing the DB_API_Type
      -v verbose
      -h print this help message

example: add_db_api_!type -A O2DBI -d "The O2DBI I database api"

list_user_projects

get Projects of a User from project management database

usage: list_user_projects -l <user login>

where: -l <user login> the Users login 

      -h print this help message

example: list_user_projects -l juser

del_db_api_!type

removes a DB_API_Type from project management database

usage: del_db_api_!type -A <db_api_!type_name>

where: -A <db_api_!type_name> name of the DB_API_Type 

      -h print this help message

example: del_db_api_!type -A O2DBI

list_project_members

list Project Members with their Role

usage: list_project_members -p <Project name> [-r]

where: -p <Project name> the Projects name 

      -r sort Members by Role
      -h print this help message

example: list_project_members -p gendb_test

list_extern_users

list_extern_user - list all extern Users and genereates MySQL statements to obtiain 

                  consistent MySQL privileges for extern users

usage: list_user_projects [-g]

where: -g generate MySQL statements 

      -h print this help message

example: list_user_projects -l juser

rem_project_from_meta_project

removes a Project from a META Project

usage: rem_project_from_meta_project -p <project_name> -m <meta_project_name>

where: -p <project_name> name of Project to be removed from META Project 

      -m <meta_project_name> name of META Project
      -h print this help message

example: rem_project_from_meta_project -p gendb_test -m gendb_meta

Using an Application Frame

In addition to the standard classes of the GPMS we have implemented a general framework that simplifies the necessary steps for accessing a project's data. Such an Application Frame uses the GPMS for accessing the datasources of a project and it also provides a number of useful methods that are often needed by the end applications. The following description was directly included from the documentation of the Perl module. inputapplication_frame

Description 

    An Application_Frame provides a general framework that
    simplifies using the General Project Management System
    (GPMS). It should be used for all O2DBI connections based on
    the GPMS (see documentation of O2BI by B. Linke for further
    details about master objects etc.).

Concepts 

    An Application_Frame acts as a container for all GPMS data
    that are required by an application for connecting to an
    O2DBI database. It provides access to:

    o a ProjectManagement master object
    o an application master object
    o a ProjectManagement::Project object
    o a ProjectManagement::User object
    o a ProjectManagement::Member object
    o the users password

    For using the Application_Frame a subclass has to be created
    that contains an application specific _init_application
    method, that provides the application master (see the
    documentation for _init_application for more detail).  The
    Application_Frame was initially introduced for some
    bioinformatics applications developed at Center for Genome
    Research, Bielefeld University. But it may be used as well
    with every other GPMS based application.

Methods 

    o new($login, $passwd [,$gpms_master] [,$errh])
         Constructor, used for creating a new
         GPMS::Application_Frame object that provides the O2DBI
         master objects and all GPMS data relevant for an
         application. $errh is an optional error handler method,
         which is executed if an error occurs. As an argument
         $errh receives a string containing the error message.
         When $errh is specified it will be executed in every
         method called on the object whenever an error occurs.
         The optional argument $gpms_master is a
         ProjectManagement master object. It may be used when
         several Application_Frame objects are supposed to share
         the same GPMS master.

    o errh([$errh])
         Method used to get/set the error handler method. $errh
         is a reference on a subroutine that is executed if an
         error occurs. The only argument that is returned is the
         error message string.

    o login
         This method returns the login name of an user that was
         specified in the constructor method.

    o passwd
         The users password is required for establishing the
         connection to a database. Therefore the password is
         provided by this method.

    o gpms_master([$master])
         This method can be used to get/set the O2DBI master
         object for the GPMS.

    o application_master([$master])
         Get/set the O2DBI master object specific for the
         application or hash of O2DBI master objects if a
         project uses more than one database.

    o user
         Use this method to get the ProjectManagement::User
         object.

    o project([$project])
         This method can be used to get/set the project.
         $project can be a ProjectManagement::Project object or
         simply the name of a project.

    o get_available_projects($type)
         This method returns an array reference of all usable
         projects for the specified user. The type can be used
         to specify a subclass of ProjectManagement::Project
         (e.g. ProjectManagement::Project::GENDB).

    o user_name
         Get the full name of the current user.

    o user_email
         Get the email address of the current user.

    o error
         Default error method that can be used to get/set an
         error message if an error occured.

    o _init_application($project)
         This method has to be overloaded when a new subclass is
         created. The derived method can implement project
         specific initializations. It should always return an
         application master or a reference on a hash of
         application masters if a project uses more than one
         database. Since the Application_Frame is only
         applicable for projects using the second generation of
         the O2DBI tool other applications that use the old
         version by J. Clausen have to return 1 for successful
         connections or 0 if an error occured. The $project
         argument specifies a ProjectManagement::Project for
         which the Application_Frame should be initialized.

    o project_name
         Get the name of the project for which the
         Application_Frame was created.

    o project_description
         Get the description of the currently used project.

    o member([$member])
         Use this method to get/set the current member.

    o right($right_name)
         This method returns the value for a given project right
         for the current user.  Use this method to check the
         individual permissions (rights).

    o rights
         This method returns a reference on a hash of all
         project rights defined for the current user.

    o projectDB_by_datasource_!type_name($datasource_!type_name)
         Use this method to retrieve the database of a project
         for a specified datasource_type.

    o project_dbs
         This method returns a reference on an array of all
         databases in the current project.

    o project_datasources
         Use this method to retrieve a reference on an array of
         all available datasources for the current project.

    o user_project_config([$config])
         Use this method to get/set the complete project
         configurations for the current member of a project.
         $config is a hash of hash containing the configuration
         parameters and values for different configuration
         sections.

    o destroy
         Delete the Application_Frame object and clean up
         everything.

Graphical User Interfaces for maintaining the gpms

In addition to the scripts the GPMS can be maintained via a graphical user interface implemented in Perl Gtk (see figure reffig:gpms_gui).

beginfigure[H] 

 begincenter
   includegraphics[width=0.8columnwidth]figures/GPMS_GUI
 endcenter
 caption[Graphical user interface for the gpms.]The Gtk frontend
   of the GPMS can be used to maintain users and projects and
   provides an immediate overview.
 labelfig:gpms_gui

endfigure

The tree-view on the left displays all members of a selected project sorted by the roles that were defined for the corresponding projectclass. Another subtree shows the rights that have been defined for each role. The tree also contains a list of all users that are registered in the gpms. New users and members can be added via a simple input form.

beginfigure[H] 

 begincenter
   includegraphics[width=0.95columnwidth]figures/gpms_web
 endcenter
 caption[Web frontend for the gpms.]The web frontend
   of the GPMS can be used to maintain users and projects.
 labelfig:gpms_web

endfigure

Figure reffig:gpms_web shows four screenshots of different operations that can be performed with the web frontend. All members of a project can be listed, new users and members can be added, or existing members can be removed from a project. It is also possible to change the role of an existing member. For reasons of security, only those roles can be assigned that do not include administrative privileges and are therefore marked as extern.

Retrieved from "https://wiki.cebitec.uni-bielefeld.de/brf-software/index.php?title=GPMSWiki/CoreDocumentation/Implementation&oldid=2060"