6. BSCW Packages¶

This section contains instructions on how to configure the additional packages provided for the BSCW shared workspace system. Each package has to be enabled or disabled using the bsadmin package command, which creates the corresponding BSCW configuration directory (e.g. <bscw-runtime-path>/conf/<package>/) with the necessary package configuration files and changes the PACKAGES list in the <bscw-runtime-path>/conf/config.py file.

Generally all BSCW packages are maintained by the bsadmin package command line script for

management of distributed BSCW packages (as described in the sections below)
- to enable a distributed BSCW package run:
```
bin/bsadmin package -e <pkg-name>
bin/bsadmin package -e ldap
```
- to disable distributed a BSCW package run:
```
bin/bsadmin package -d <pkg-name>
bin/bsadmin package -d ldap
```
- to re-enable a distributed a BSCW package (and update installed resources) run:
```
bin/bsadmin package -r <pkg-name>
bin/bsadmin package -r ldap
```
management of external BSCW packages (e.g. customer developments). An external BSCW package is usually provided as a ZIP archive and enabled as follows
- to enable an external BSCW package run:
```
bin/bsadmin package -e <pkg-name> <path>
bin/bsadmin package -e fhg_fit bsext/fhg_fit
```
- to disable an external BSCW package run:
```
bin/bsadmin package -d <pkg-name>
bin/bsadmin package -d fhg_fit
```
- to re-enable an external BSCW package (and update installed resources) run:
```
bin/bsadmin package -r <pkg-name>
bin/bsadmin package -r ldap
```

Finally the command bsadmin package -l provides an overview about enabled/disabled BSCW packages.

Depending on the particular BSCW package further configuration has to be done either in the BSCW instance configuration file (<bscw-runtime-path>/conf/config.py) or within the BSCW package configuration files (located in <bscw-runtime-path>/conf/<package>/). Please refer the following description for each BSCW package.

6.1. Content Search PyLucIndex¶

Preferably BSCW uses a full text search for BSCW meta data and document contents based on the Lucene Java indexing and search framework. The provided PyLucIndex package is the preferred way to enable search for Windows and Unix based BSCW instances.

The package PyLucIndex uses pylucene, a “JCC” compiled python extension for Lucene Java. You need to download and install pylucene before you activate this package.

Pylucene is maintained under the Apache Lucene project at the Apache Software Foundation. For more information on Pylucene, please visit http://lucene.apache.org/pylucene/.

A source distribution can be downloaded from http://www.apache.org/dyn/closer.cgi/lucene/pylucene/

Some pre-build binaries are provided by the pylucene-extra project at http://code.google.com/a/apache-extras.org/p/pylucene-extra/

Please ask for pre-compiled Python wheel (.whl) packages our support team (support@orbiteam.de).

BSCW 5.2.6 supports pylucene 3.6.2

Important

Additionally pylucene requires an installed Java Runtime Environment (JRE) 8 or 11
(Windows) After upgrading your Java Runtime Environment (JRE) to a new release the new installation path must be adapted manually in the Windows system “Path” environment variable. Afterwards a system restart is required.

We gratefully acknowledge the work of the Lucene group (especially Doug Cutting) and the pylucene group (especially Andi Vajda) who did an excellent job in making Lucene available to the Python developers.

6.1.1. Configuration¶

This package is not enabled by default and requires some software installation (i.e. pylucene - see above) and allows optional configuration.

The main configuration required is for content search, i.e. indexing document contents. You will need to define converters for all document types that should be indexed. BSCW already provides a framework for document conversion which is used by this indexing package.

Please install needed converter programs as described in section Software for BSCW Preview (see Unix or Windows).

After the installation of pylucene enable the BSCW PyLucIndex package with:

bin/bsadmin package -e PyLucIndex

If you installed additional converter programs update the configuration by using:

bin/bsadmin update_defaults -s -v

(as described in section 5.8 conf/config_convert.py) to update the <bscw-runtime-path>/conf/config_convert.py converter file.)

Furthermore the index configuration allows some fine tuning of the pylucene indexer:

FILES_TXT

Directory to store text file representation
INDEX_DIR

Directory to store the index files
INDEX_LOG

Log file for indexing process (set None for no logging)
INDEX_USE_BSDDB

Optionally use Berkeley DB library (bsddb) for storage of lastmod
CREATE_INDEX_ARGS

Arguments for automatic restart of bsadmin create_index
INDEX_QUERY_HELP

link to the query syntax documentation

Note

this actually depends on the installed version of pylucene! (see INDEX_QUERY_OPERATOR_AND below for possible changes in BSCW)

INDEX_QUERY_OPERATOR_AND
default query operator: in pylucene, the OR operator is the default conjunction operator. i.e. a search for “brown sugar” yields all documents that contain any of the words “brown” OR “sugar” - to use this query type set:
INDEX_QUERY_OPERATOR_AND = False
in BSCW we change the default query operator to AND: that way the “Search in Documents” behaves like a search in Google
INDEX_FUZZY_FACTOR
additionally to wildcard search Lucene Fuzzy search is used in text search items, if 0 < INDEX_FUZZY_FACTOR < 1. Fuzzy search is by default turned off:
INDEX_FUZZY_FACTOR = 0
INDEX_NO_FUZZY_KEYS
specifies a list of metadata keys to which fuzzy search should not be applied:
INDEX_NO_FUZZY_KEYS = ['bscw:classname']
INDEX_QUERY_LEADING_WILDCARD

allow leading wildcards (e.g. *ook)

Note

In pylucene leading wildcards are not supported by the QueryParser by default. However they can be enabled. Note that this can be an expensive operation: it requires scanning the list of tokens in the index in its entirety to look for those that match the pattern.
INDEX_OBJECT_MAXLOAD

number of objects to load from DB while indexing (chunk size)
INDEX_OBJECT_MAXBUF

size of internal object buffer (for incremental index update)
INDEX_QUERY_MAXHITS

number of hits to return in one query to indexer during search

The following directives allow fine tuning of Lucene indexer: (see http://lucene.apache.org for details)
INDEX_RAM_BUFFER
Buffer Size in MB (default: 16 MB)

For the added documents, flushing is now triggered either by RAM usage of the documents or the number of added documents. Lucene developers recommend for faster indexing performance to flush by RAM usage instead of document count and use as large a RAM buffer as you can.
Note
- setting INDEX_RAM_BUFFER to a negative value will set DISABLE_AUTO_FLUSH which prevents triggering a flush due to RAM usage (and uses document count instead - see MaxBufferedDocs below)
- if flushing by document count is also enabled (via MaxBufferedDocs), then the flush will be triggered by whichever comes first.
INDEX_MERGE_FACTOR

MergeFactor - must never be less than 2. The default value is 10. Determines how often segment indices are merged by addDocument(). With smaller values, less RAM is used while indexing, and searches on unoptimized indices are faster, but indexing speed is slower. With larger values, more RAM is used during indexing, and while searches on unoptimized indices are slower, indexing is faster. Thus larger values (> 10) are best for batch index creation, and smaller values (< 10) for indices that are interactively maintained.
INDEX_MAX_BUFFEREDDOCS

MaxBufferedDocs - must never be less than 2. The default value is 10.

Determines the minimal number of documents required before the buffered in-memory documents are merged and a new Segment is created. Since Documents are merged in a RAMDirectory, large value gives faster indexing. At the same time, mergeFactor limits the number of files open in a FSDirectory.
INDEX_MAX_MERGEDOCS

MaxMergeDocs - default value is Integer.MAX_VALUE.

Determines the largest number of documents ever merged by addDocument(). Small values (e.g., less than 10,000) are best for interactive indexing, as this limits the length of pauses while indexing to a few seconds. Larger values are best for batched indexing and speedier searches.
INDEX_MAX_FIELD_LENGTH

MaxFieldLength - limits number of terms to store per field

By default Lucene stores first 10.000 terms (“words”) this may restrict search results on document content (especially for longer documents)

Note

INDEX_MAX_FIELD_LENGTH = None will allow unlimited number of terms per field
INDEX_MAX_CLAUSE_COUNT

MaxClauseCount - set the maximum number of clauses permitted per BooleanQuery.

Default value is 1024.
INDEX_LANGUAGE_DEPENDANT_FIELDS

define a list of fields to be indexed with a special language dependent analyzer.

Warning

This is currently still experimental (and only supported for English and German)

If you want to alter one of this configuration directives append the directive to the end of the instance configuration file (<bscw-runtime-path>/conf/config.py).

The following configuration directive is configured in the BSCW package configuration file <bscw-runtime-path>/conf/PyLucIndex/config.py

INDEX_JVM_MAXHEAP
Max heap for Java VM (lucene only) (default: '512m'). Increase this value if you experience OutOfMemoryError exceptions while index creation, e.g.:
INDEX_JVM_MAXHEAP = '2048m'
LUCENE_JVM_ARGS
additional arguments passed to lucene’s JVM via lucene.initVM(vmargs) should be list of string arguments or empty list:
INDEX_JVM_ARGS = ['-Djava.awt.headless=true',]
INDEX_MAX_TXTSIZE
Max document size for text documents to be indexed. Lucenes Java VM may fail with OutOfMemoryError on very large documents that are typically binary files with wrong MIME-Type. BSCW uses some heuristics to detect binary files, but will also skip files with certain size anyway. Default limit is 50 MB text file size (= 52428800 bytes):
INDEX_MAX_TXTSIZE = 52428800

There you may also change the directories to contain the text file representations and the Lucene index itself. You may want to adjust some of the index parameter (such as merge factors) - see http://lucene.apache.org for details on how this affects indexing.

6.1.2. Command line tools¶

You may run the indexer using the provided command line tool:

$ bin/bsadmin create_index

You may query the indexer using the command line tool:

$ bin/bsadmin search

bsadmin create_index - generates the pylucene index

First make sure that no other indexing process is running. You may check the status of the indexer using

$ bin/bsadmin create_index -v

and stop a running indexer process using

$ bin/bsadmin create_index -x

To start the indexing process on Unix systems you may use for example:
```
$ nohup bin/bsadmin create_index -cqt >/dev/null 2>&1 &
```
The commandline usage is as follows:
```
$ bin/bsadmin create_index
Usage:
 bsadmin create_index -c [-u] [-otU] [-{v|q}] [-r <min>] [-R <hour>]
 bsadmin create_index -{i|s}  [-otU] [-{v|q}] [-r <min>] [-R <hour>]
 bsadmin create_index -x [-u] [-z]
 bsadmin create_index -v
 bsadmin create_index [-h]

options:
 -c        create new index (forced if no index exists)
 -cu       create new index & force update of document
           text representations
 -i        incremental index update
 -s        scan database continuously
 -o        suppress periodic optimization (optimize only on start)
 -t        display timer info at exit
 -U        unlock at first (dangerous)
 -v        verbose mode (or status report if used as single option)
 -q        quiet
 -r <min>  report interval (default 30 min, 0: no report)
 -R <hour> automatic restart in '+<hour>' or at 0 < <hour> < 24
 -x        stop indexer
 -xu       stop indexer and cleanup document text representations
 -xz       stop indexer and cleanup index files
 -xuz      stop indexer and cleanup all indexer files
 -h        show this help message and exit
```
Note

option -u is only possible in conjunction with option -c (i.e. all text files will be removed before new Index is created) or in conjunction with option -x (i.e. all text files will be removed after indexer is stopped - allows fresh restart).

The bsadmin create_index script will create / update the pylucene index. If no index exists yet it will be newly created. By default the script will update an existing index when it is invoked (use option -c to force creation of a new index).

Option -i will perform an incremental index update (default), i.e. only documents that have been modified or added (since last index run) will be (re-)indexed. Outdated (i.e. deleted) documents will be removed from the index.

Option -v can be used (as single option) to check the indexer status. The indexer is typically running as a background process and automatically started with the BSCW server. More details may also be found in the indexer logfile (in <bscw-runtime-path>/var/log/index.log)

The indexing process will automatically create/update text representations of documents during indexing. This requires configuration of according converters (to text/plain format - see above).

A document conversion will be performed when necessary, i.e. documents that have been modified will be updated; text representation of outdated (i.e. deleted) documents will be removed (use option -u to force removal of all text representations initially).
bsadmin search - performs a query on the pylucene index:
```
$ bin/bsadmin search
usage: bsadmin search [-h] [-s] [-a] [-i] [-c] [-v] [-l lang] [query]

query pylucene index

positional arguments:
query       query

optional arguments:
-h, --help  show this help message and exit
-s          show index statistics
-a          search all fields (default: content search)
-i          search by ID only
-c          show hit count only
-v          verbose
-l lang     language
```
This script passes a query to the pylucene index and returns a list of results as BSCW object IDs. It may be used for testing. Here verbose mode delivers extra document info on the results.
Note
- option -i allows to check if an object (BSCW ID) is contained in the index.
- option -a allows to search in multiple fields (e.g. name, description etc.)
You may use any valid Lucene query, e.g.:
```
$ bin/bsadmin search -v "contents:bscw AND class:Document"
```
The command line search does not check any access rights, i.e. you will receive all results that match the query. When using the search in the web front-end, of course access rights are checked and only filtered results show up.

6.1.3. Index creation and update¶

If the package is enabled and an index is already created (and not locked) BSCW attempts to automatically start the indexer when the BSCW server process is started (via bsadmin start [Windows] or start_servers [Unix]).

The bsadmin create_index tool provides an option (-s) to continuously scan the database and thereby update the index (while BSCW server is running). This option is used when BSCW starts the indexer itself (actually option -sqr60 is used).

Thus recommended usage of the indexer is to initially create the index manually by invoking the following commands:

$ bin/bsadmin package -e PyLucIndex
$ bin/bsadmin create_index -cqt

and then let BSCW update the index continuously.

For this purpose you only need to (re)start your BSCW server after the bsadmin create_index finished to create the initial index e.g.:

$ bin/start_servers -k          # UNIX
$ bin/start_servers

> bin\bsadmin stop [-s]         # Windows
> bin\bsadmin start [-s]

Note

The indexer logs progress and errors to the configured log file (in <bscw-runtime-path>/var/log/index.log). Startup (or failure to start the indexer) during start/stop of the BSCW server is also logged in the main BSCW log file (in <bscw-runtime-path>/var/log/bscw.log).

If the indexer was not started upon BSCW start due to a failure (e.g. a missing IndexPos file) run:

$ bin/bsadmin create_index -iU

manually to incrementally index all missing objects. Again, after bsadmin create_index finished updating the index restart your BSCW server, e.g.:

$ bin/start_servers -k          # UNIX
$ bin/start_servers

> bin\bsadmin stop [-s]         # Windows
> bin\bsadmin start [-s]

Note

If (for some reason) you ever want to completely re-build the index there are two options:

option -xz will stop the indexer and remove the index files. This allows a quick rebuild without updating text representations (which is time consuming).
option -xuz will stop the indexer and remove the index files and all document text representations. This is the ultimate “from-scratch” solution as all index-related data is cleaned up before rebuilding the index (you may also want to rm var/log/index.log).

In both cases you may then re-create the index using bsadmin create_index -cqt.

Finally restart the BSCW server again as described above, to let BSCW update the index continuously (see create_index above). This method will result in a ‘fresh’ (and up-to-date) index and newly created text representation of all indexable documents (if option -u is given).

To re-create the index simply use the following command sequence:

$ nohup /bin/sh -c "bin/bsadmin create_index -xz; bin/bsadmin create_index -cq; bin/start_servers" > /dev/null 2>&1 &

6.2. LDAP¶

The Lightweight Directory Access Protocol (LDAP) is a protocol for accessing online directory services. It runs directly over TCP, and can be used to access a standalone LDAP directory service or to access a directory service that is back-ended by X.500. The BSCW system implements an interface to LDAP servers based on the python-ldap package. Python-ldap wraps an underlying LDAP C library that provides an RFC 1823 API, such as OpenLDAP (http://www.openldap.org).

6.2.1. Installation¶

To install the BSCW LDAP module

The BSCW LDAP module needs the python-ldap package. Python-ldap 3.1.0 provides functionality for accessing LDAP servers from Python. It wraps an underlying LDAP C library that provides an RFC 1823 API, and requires at least OpenLDAP 2.4.11 or later (http://www.openldap.org).
- On Linux systems the python-ldap package of the distribution should be installed.
  
  Packages name(s) for common Linux distributions:
  - Debian based systems: python-ldap
  - EL based systems: python-ldap
- On Windows systems install python-ldap using the Python package manager pip:
  
  > pip install python-ldap

To enable the BSCW ldap copy the default template file to the instance configuration directory as follows

# su - bscw
$ cd $HOME
$ mkdir -p srv/<bscw-instance>/conf/ldap
$ cp lib/bscw-5.2.6-<rev>-py27/bscw/conf/ldap/config.py    srv/<bscw-instance>/conf/ldap

and run:

$ cd srv/<bscw-instance>
$ bin/bsadmin package -e ldap

Adapt the configuration file <bscw-runtime-path>/conf/ldap/config.py to your needs, especially the "hosts" map and the "auto_registration" list:
- hosts is a dictionary mapping distinguished names (DNs) to hostname[:portnumber] when an LDAP object is searched (referred by a DN), this table is looked up for a corresponding LDAP server address. The DNs should be in a ‘canonical’ form (lower case, no spaces before or after ‘,’ and ‘=’).
- certificate_files is an dictionary containing for each LDAPS URI hostname[:portnumber] value from the hosts dictionary a path name to a file containing the CA certificates needed to validate server certificates.
- may_register_ldap is a list of BSCW users that have the right to register LDAP users - i.e. invite new users to the system or to a workspace. This is in addition to SERVER_ADMINS, who have this right anyway.
  
  There are two special cases: if may_register_ldap is
  
  []: then registration of new LDAP users is allowed for all users. This allows all users and anonymous to invite new users to the system.
  
  None: then registration of new LDAP users is allowed for all but anonymous.
  Note
  - only may_register_ldap = [], allows self-registration by LDAP user login
  - may_register_ldap behaves equal to MAY_REGISTER for found LDAP user objects. By default self-registration of found LDAP user objects is allowed (which is the behaviour of previous BSCW versions)
  - alternatively may want to use the setting of MAY_REGISTER also for may_register_ldap. In this case define:
    from conf.config import MAY_REGISTER may_register_ldap = MAY_REGISTER
- auto_registration defines DN patterns and search patterns for auto_registration during login. If a user is not registered at BSCW but her DN can be found on a LDAP server with one of the patterns listed in auto_registration, then BSCW makes an attempt to register the user automatically and assigns (binds) the DN to the user object if the registration process succeeds. three patterns are possible here (%s is substituted by the login name):
  - a pattern that expands to the DN directly:
    'cn=%s,o=snakeoil,c=de'
  - a 2-tuple that specifies the LDAP server default binding (base DN) and a search expression for user name search:
    ('o=snakeoil2,c=de', '(uid=%s)')
  - a 3-tuple that specifies the LDAP server default binding (base DN) and a search expression for user name search and a search expression for email address search:
    ('o=snakeoil2,c=de', '(uid=%s)', '(mail=%s)')
  The latter two patterns result in a 2-step process for the required binding: At first the DN is looked up on the LDAP-server using the default binding. Then a bind is tried with the resulting DN (must be unique) and the given password. In case a 3-tuple is given the search pattern is determined by the given login name. If the login name contains a '@' character the mail address search pattern ('mail=%s'), otherwise the user name search pattern is used.
- auto_registration_email allows to send a registration mail. Use auto_registration_email = 'reg_done' if you want the standard registration mail sent to an automatically registered user. You might set the registration mail language using: auto_registration_email_lang = 'de'
- auto_registration_roles defines initial roles, quota limit class or auto-invitation to communities for automatically registered users. The list consists of tuples:
```
('attribute=value', 'R[012]rolename'),
('attribute=value', 'R[012]rolename', 'limitclass'),
('attribute=value', 'R[012]rolename', 'limitclass', 'community-id').
```
  Note
  - the role 'R[012]rolename' must be assignable for user objects i.e. it must appear in the list cl_action.user_roles.
  - the quota limit class 'limitclass' must be defined with bsadmin quota limit in advance.
  - the community with the object-id 'community-id' must be created in advance.
  - at the moment the 'attribute=value' string is only looked up in the DN (user.ldap_bind) of the user. The LDAP attributes of the user are ignored. This might be changed in the future.
  Possible patterns:
  ('ou=pupil', 'R2restricted'), ('ou=development', 'R2manager', '@manager'), ('ou=development', '', '@manager'), # No user role is assigned ('ou=development', 'R2manager', '@manager', '12345'),
- auto_may_register defines DN patterns and search patterns to determine if an user has the right to register mail addresses (see <bscw-runtime-path>/conf/config.py: MAY_REGISTER). If an user matches a given DN or search pattern in auto_may_register and the configuration directive MAY_REGISTER restricts the registration of mail addresses, this user is additionally allowed to register mail. Three patterns as described above at auto_registration are possible here.
- use_ldap_passwords defines how BSCW handles users with LDAP binding and local BSCW users (without LDAP binding):
  - If use_ldap_passwords is 1, then for all users passwords are verified against the LDAP-server. Hence an existing user who is not found on an LDAP server cannot login to the system any more.
  - If use_ldap_passwords is 2, then the user password is verified against the LDAP-server only for users with a LDAP binding or users found on a LDAP server. Note the following implications:
    - a local BSCW user who is not found on a LDAP server and who does not have a LDAP binding can still login to the system.
    - a local BSCW user who is found on a LDAP server and provided the correct LDAP credentials will take over the local user (by adding a LDAP binding).
  - If use_ldap_passwords is 3, then the user password is verified against the LDAP-server only for users that have a LDAP binding.
  Note
  - BSCW does password checking by LDAP only if the BSCW server and not the HTTP server does authentication, e.g. when cookie authentication is enabled or BSCW gets the HTTP_AUTHORIZATION value). Because this is not a very fast way to do authentication, it might be an alternative to configure the HTTP server to do LDAP authentication (e.g. via the Apache HTTP server auth_ldap module) instead of setting use_ldap_passwords = 1 which requires all users to pass LDAP authentication.
  - If the Apache HTTP Server auth_ldap module is used use_ldap_passwords must be set to 3, otherwise the BSCW change password action interferes with the auth_ldap modules internal password cache.
  - When using BSCW authentication, digest authentication is not possible in combination with LDAP, because BSCW requires the plain (textual) password to authenticate the credential against LDAP.
- ldap_searches defines a list of member search options (qid, pattern) or (qid, pattern, pattern_args) or (qid, pattern, rdnfilter) for the workspace invite member action (op_addmb):
  - qid is an unique identifier for the search and must be translated in <bscw-runtime-path>/conf/msg/*/ldap/lg_msgconfig.py.
  - pattern is a LDAP query where '%(query)s' is replaced by the user input of the addmb search form
  - pattern_args (optional) defines additional query input fields, which substitute '%s' occurrences within the query pattern. Pattern arguments are 3- or 4-tuples:
    ('entry-name-0', 'entry-default-val-0', 'entry-query-0'), ('entry-name-1', 'entry-default-val-1', 'entry-query-1', [ 'entry-dropdown-0', 'entry-dropdown-1', ...]),
  - rdnfilter (optional) defines an optional filter for a relative DN type, which allows to additionally remove query results which do not match the given RDN value list
  - search subtree of defined base DN(s) for the given query:
    ('mb_search_ldap_uid', 'cn=*%(query)s*'), ('mb_search_ldap_uid', '(|(cn=*%(query)s*)(uid=*%(query)s*))'), ('mb_search_ldap_uid', '(sAMAccountName=*%(query)s*)'),
  - search subtree with 2 input fields 'mb_search_ldap_cn' and 'mb_search_ldap_uid'.:
    ('mb_search_ldap', '(|(cn=%s)(uid=%s))', ('cn', '', '*%(query)s*'), ('uid', '', '*%(query)s*'), ),
  - search subtree of defined base DN(s) for query 'ou=*%(query)s*'' and remove results which relative DN of type 'ou' does not match the given list ['sales', 'ext']:
    ('mb_search_ldap_org', '(ou=*%(query)s*)', ('ou', ['sales', 'ext'])),

6.2.2. LDAP Browser¶

After installation of the ldap package, a small “organisational browser” is enabled. When opening a user info window (e.g. by clicking on a user name in the web interface) the users’ LDAP binding (if defined) is shown. By selecting the link of the LDAP binding field the user information (as retrieved from the LDAP server) is displayed.

If the ldap package is installed and activated, the [Goto]-Menu contains an entry [Organisation Info] that invokes the organisational browser. The browser connects to the LDAP servers in the hosts map and allows operation on LDAP objects. The operations search, view and attribute editing are supported.

Note

ORG_INFO_URL must not be set in <bscw-runtime-path>/conf/config.py, because this will override the handler invoked by the [Organisation Info] menu entry.
You need basic knowledge of directory services in general and especially need to know some details about LDAP in order to configure BSCW for LDAP. Besides the more technical IETF RFCs and Drafts about LDAP – which can be found at http://www.ietf.org – we suggest to read the IBM Redbook: Understanding LDAP (SG-244986, June 1998), available at http://www.redbooks.ibm.com.

6.3. Document Approval¶

The approval package supports a standardized quality approval process while document production. After document creation the document may be checked by one more persons and is finally released. The state of documents running through this approval process is displayed at the user interface.

You may want to provide different global defaults for your users in the by creating the configuration file <bscw-runtime-path>/conf/approval/config.py. The possible configuration directives and their defaults are as follows:

MAY_RESET_APPROVAL

controls if the approval process is reset after an approved document is edited or replaced. (Default: True)
APPROVAL_UNIQUE_REVIEWER

enforce if reviewers must be unique in an approval, i.e. when enabled any reviewer may participate only once in a review process. (Default: False)

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e approval

6.4. Blog (Weblogs)¶

The blog package extends BSCW by blog functionality. You either can create personal blogs, group blogs or public blogs.

At creation of a blog or in the blog properties one can define some handling options and set up default access right, i.e. who should add blog entries and who should read the blog. By default everyone who could read blog entries also can make comments. The access rights may can be changed individually by editing the roles.

Also it is possible to specify the layout of a blog, either as default layout, as a layout with BSCW navigation or as a user defined layout with an own template and an own style sheet file.

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e blog

6.5. Easy¶

The easy package enables an optional user interface which allows a simplified access to BSCW by providing only basic actions.

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e easy

After the easy package is enabled a link to the easy interface is integrated on the BSCW index page. Recreate the index page with:

bin/bsadmin index_page

6.6. Expire¶

The expire package sends an email notification to the user when the account was expired with additional informations. The notification email may be customized by creating the configuration file <bscw-runtime-path>/conf/expire/config.py with the following configuration directives:

EXPIRE_DELETE_DAYS
defines the number of days after expiration when the account will be deleted:
EXPIRE_DELETE_DAYS = 30
Note

This defines just a hint for the email notification, account deletion must be done manually by the administrator.
EXPIRE_CONTACT_MAIL
defined an email address for questions (defaults to SERVER_ADMIN):
EXPIRE_CONTACT_MAIL = None

How to enable automatic account expiry see user account expiry.

This package is not enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. The package may be enabled by running:

bin/bsadmin package -e expire

6.7. Export PDF¶

The exportpdf package provides an optional feature for BSCW that allows users to export container views to PDF format. With PDF export enabled the listings of many container objects, i.e. objects that can contain other objects, may be exported in PDF format for printing. Examples are folders, blogs and contact lists. You may want to enable this package if you want to offer this additional functionality to your end users.

For installation and configuration of the package proceed as follows:

Make sure the required third-party software is available on your system (server). The package requires the following python extensions:
- Python Imaging Library (PIL/Pillow):
  
  https://pypi.python.org/pypi/Pillow
- The ReportLab PDF Library:
  
  https://pypi.python.org/pypi/reportlab
  
  Attention
  
  Due to a critical vulnerability in the ReportLab library a version >= 3.5.55 ist required.
- On Linux systems use preferred the packages of your distribution:
  - Debian based systems: python-pil python-reportlab
  - EL based systems: python-pillow python-reportlab
- On Windows systems or if your Linux distribution does not provide packages you need the Python package manager pip to install the packages:
```
> pip install pillow
> pip install reportlab
```
To enable the BSCW exportpdf package run:
```
bin/bsadmin package -e exportpdf
```

Note

This feature is only available in the professional edition of BSCW.

6.8. Flow-Folder¶

Flow folders allow you to manage work flows where documents follow a certain work process and are forwarded from one user to another for subsequent processing. Each flow folder has a number of tasks which are to be carried out by the users responsible in the order specified. Flow folders - like normal folders - may contain objects of all types, e.g. documents, other folders or discussion forums.

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e FlowFolder

6.9. Http¶

The http package implements a pre-forking BSCW HTTP server. This means a master process pre-loads the BSCW code library, spawns a pool of separate worker HTTP processes and routes requests to spare worker processes.

Using this technique greatly speeds up request processing. Incoming requests are immediately served on arrival without the overhead of creating new processes or loading BSCW code modules. Load tests have shown an average performance increase of 30% compared to the traditional Apache HTTP server CGI.

This package is not enabled by default in a new BSCW server instance and is only available on Unix based BSCW systems. No additional software installation is required on server-side.

To enable the pre-forking BSCW HTTP server the HTTP_LOCAL_PORT_START directive must be defined and the http package must be enabled as follows:

Important

When using the pre-forking BSCW HTTP server all configuration changes become only active after a restart of the BSCW HTTP server, which is performed from the CLI running:

bin/bsadmin http restart

or on the administration BSCW status page [Options ‣ Admin ‣ Status] by clicking the [Restart integrated http service] entry.

6.9.1. Enabling the BSCW HTTP server¶

Stop the BSCW instance services:
```
bin/bsadmin stop
```
Enable the http package:
```
bin/bsadmin package -e http
```
Edit the instance configuration file <bscw-runtime-path>/conf/config.py and define a unused localhost port for the pre-forking BSCW HTTP server, e.g.:
```
HTTP_LOCAL_PORT = 8080
```
Note

The localhost port must be free and may not be occupied by another service (such as the Apache HTTP server).

Next define a BSCW HTTP server start command, e.g.:
```
HTTP_LOCAL_PORT_START = "-p 100 -r 128"
```
Start the BSCW instance services:
```
bin/bsadmin start
```
Beside the usual BSCW services additionally this starts a pre-forking BSCW HTTP server with a maximum of 100 worker processes and a maximum listen queue length of 128 requests.

Update your Apache HTTP server configuration:

bin/bsadmin conf_apache

Ensure your Apache HTTP server enabled the proxy and proxy_http modules and restart the HTTP server as root user:

Debian based systems:

$ su -
# a2enmod proxy proxy_http
# systemctl restart apache2

EL based systems:

$ su -
# vim /etc/httpd/conf.modules.d/00-base.conf
# vim /etc/httpd/conf.modules.d/00-proxy.conf
# systemctl restart httpd

6.9.2. Disabling the BSCW HTTP server¶

Stop the BSCW instance services:
```
bin/bsadmin stop
```
Disable the http package:
```
bin/bsadmin package -d http
```
Restore in the instance configuration file <bscw-runtime-path>/conf/config.py the HTTP_LOCAL_PORT to a Apache HTTP server controlled localhost port, e.g.:
```
HTTP_LOCAL_PORT = 80
```
and set a BSCW HTTP server start command to None:
```
HTTP_LOCAL_PORT_START = None
```
Start the BSCW instance services:
```
bin/bsadmin start
```
This starts the BSCW services without the pre-forking BSCW HTTP server again.

Update your Apache HTTP server configuration:

bin/bsadmin conf_apache

Disable the Apache HTTP server proxy and proxy_http modules (if not longer required) and restart the HTTP server:

Debian based systems:

$ su -
# a2dismod proxy proxy_http
# systemctl restart apache2

EL based systems:

$ su -
# vim /etc/httpd/conf.modules.d/00-base.conf
# vim /etc/httpd/conf.modules.d/00-proxy.conf
# systemctl restart httpd

6.10. Incognito¶

The incognito package provides an optional feature for BSCW to anonymize read events in a certain workspace. When enabled each role shows an additional access right “Get (Incognito)”. When activated all read event in this workspace are anonymized.

This package is not enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. The package may be enabled again by running:

bin/bsadmin package -e incognito

6.11. Metaprofiles¶

The metaprofiles package allow to provide user-defined metadata profiles for BSCW objects.

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e metaprofiles

6.12. Microblogging¶

The microblog package supports instant team communication and improved awareness of other user’s activities.

You may want to provide different global defaults for your users in the by creating the configuration file (<bscw-runtime-path>/conf/microblog/config.py). The possible configuration directives and their defaults are as follows:

MICROBLOG_POLL_INTERVAL

defines update interval of microblog view. Smaller values: faster updates in microblog views, but higher server load
MICROBLOG_SHOW_EVENTS

defines default value for microblog views: show events (False/True)
MICROBLOG_WS_FILTER

defines default value for microblog views: apply workspace filter (False/True)

MICROBLOG_AW_DEFAULT

defines default value for microblog awareness preferences: (choose a sum of the bitmask values in brackets):

inbox: [x] personal messages            (1)
inbox: [x] replies                      (2)
inbox: [x] mentions (@name)             (4)
inbox: [ ] other posts                  (8)

periodic mail: [ ] personal messages   (16)
periodic mail: [x] other posts        (128)

direct mail: [x] personal messages    (256)
direct mail: [ ] replies              (512)
direct mail: [x] mentions (@name)    (1024)

MICROBLOG_WSREPORT_LIMIT

defines default value for maximum number of microblog threads to be shown in the periodic report (both for direct messages and general posts)
MICROBLOG_ALLOW_SOCIAL_NETWORK_POSTS
if True, users can send microblog posts to their whole social network. Otherwise, all users are strictly forced to either
- define a default workspace (as target for posts without a special context) in the user’ settings
- select a target workspace individually for each post (but not the social network!)

This package is enabled by default in a new BSCW server instance. No additional software installation or configuration is required on server-side. If disabled, the package may be enabled again by running:

bin/bsadmin package -e microblog

6.13. Mobile access¶

The mobile package provides an alternative mobile user interface to BSCW, especially designed for modern smart phones with HTML & JavaScript browsers.

On each login, users can decide which interface they want to use, while BSCW already proposes the interface that fits best to the requesting browser.

As the mobile interface is tightly coupled with the BSCW core, it doesn’t offer any package-local settings.

The mobile package is enabled by default on new BSCW servers

Note

The mobile package requires cookie authentication as authentication method

See also

Section 5.2.4 web/proxy server settings for more details

If disabled, the package may be enabled again by running:

bin/bsadmin package -e mobile

6.14. Poll¶

The poll package provides several types of opinion surveys in BSCW. These surveys can be left open to the public (Poll) or limited to a closed participant group (Voting).

Appointment Schedulings provide a convenient way to agree on meeting dates with a larger group of participants. While Polls are available in all editions of BSCW, Votings and Appointment Schedulings require a professional license.

The poll package is enabled by default on new BSCW servers and requires no external components. If disabled, the package may be enabled again by running:

bin/bsadmin package -e poll

When the package is activated a new object ‘Poll’ is enabled at the user interface (in [File ‣ New] menu).

There is no special configuration required for this package. However you may change some defaults and system behaviour in the instance configuration file (<bscw-runtime-path>/conf/poll/config.py) by appending configuration directives. The possible configuration directives and their defaults are as follows:

VOTING_TOKEN_EXP

Voting participants receive email notifications with links to access the Voting. Each link includes an individual security token with temporary validity. After the token has expired, the access to the Voting is denied. The token’s lifetime usually depends on the specified end date of the Voting to allow access (and voting) at least until the end of the Voting. If no Voting end is specified, the token’s lifetime is calculated from the start date (or the current time, if no start date is specified). VOTING_TOKEN_EXP allows to specify the lifetime of tokens in case no clear end date can be calculated.

Possible values are strings which may be specified in seconds or minutes (hours, days, weeks) by using an additional s, m (h, d, w) suffix.

Example: VOTING_TOKEN_EXP = '1w' would specify one week
SCHEDULE_SUGGESTIONS_ENABLED

defines if the option ‘New participants may suggest others for voting’ should be available for Appointment Schedulings. (Otherwise, SCHEDULE_SUGGESTIONS_DEFAULT will apply)
SCHEDULE_SUGGESTIONS_DEFAULT

defines the default value for the option ‘New participants may suggest others for voting’.
SCHEDULE_CONFIRMATION_ENABLED

defines if the option ‘Suggested participants need to be confirmed by me’ should be available at all. (Otherwise, SCHEDULE_CONFIRMATION_DEFAULT will apply)
SCHEDULE_CONFIRMATION_DEFAULT

defines the default value for the option ‘Suggested participants need to be confirmed by me’
SCHEDULE_CONDITIONALVOTE_ENABLED

defines if the option ‘Participants may vote with Maybe’ should be available at all. (Otherwise, SCHEDULE_CONDITIONALVOTE_DEFAULT will apply)
SCHEDULE_CONDITIONALVOTE_DEFAULT

defines the default value for the option ‘Participants may vote with Maybe’

6.15. Portal¶

The portal package provides an optional feature for BSCW that allows users to configure a personal portal page - as well as to add a portal to a shared workspace. Within a portal various portlets may be added and configured. Portlets may display information stored within BSCW (folders, tasks etc.) as well as information stored in other sources.

When the package is activated a new top-level object ‘Portal’ is enabled at the user interface (in [Goto] menu/icons)

Note

This feature is only available in the professional edition of BSCW.

For installation and configuration of the package proceed as follows:

Enable the Portal package

If disabled, the package may be enabled again by running:
```
bin/bsadmin package -e portal
```
Optional step: change the Portal configuration

You may change the portlet configuration by creating the configuration file <bscw-runtime-path>/conf/portal/config.py to override the defaults. The following settings may be changed to your need:
- PORTAL_DEBUG
  may be used to set (some of) the portlets in debug mode
  Note
  
  to enable full debugging of the portal, set in your config.py:
  
  BSCW_LOGGING = { 'portal': ('DEBUG', 'portal.log'), }
- PORTAL_SHOWATLOGIN
  
  determines if the user portal page is immediately displayed after the user logs in. (By changing this setting to False the users’ home folder is shown after login instead.)
- PORTAL_WIDGETS_ITEMS
  number of items to show per page used by (most) internal (BSCW) widgets user configurable. Default value is:
  PORTAL_WIDGETS_ITEMS = 10
- PORTAL_MAX_ITEMS
  
  maximum number of items to load into one (BSCW) widgets this is mainly used to reduces the traffic and may be centrally configured (it is not user configurable)
- PORTAL_PORTLETS
  
  list of available/enabled portlets - i.e. portlets users may add using [File ‣ New ‣ Portlet]. This may include predefined portlets as well as your own portlets from.
- PORTAL_AUTO_CONFIG_USR_PORTAL
  a list of portlets that will be automatically (initially) added to a users’ personal portal
  Note
  
  all settings will take effect for all users on this BSCW server. Automatic initialization will only take effect for new portals/users.
  
  you may (as administrator) check the current settings by using the bsadmin getconfig and query for example the PORTAL_PORTLETS:
  
  $ bin/bsadmin getconfig PORTAL_PORTLETS
Optional step: provide additional portlets

You may also add further portlets to the list of available portlets and thereby make them available to your users in the BSCW portal(s) by editing the file:
```
<bscw-runtime-path>/conf/portal/config_portlets.py
```
and finally defining a list of your own custom portlets in the central configuration file:
```
<bscw-runtime-path>/conf/portal/config.py
```
These additional portlets will become available for all users, e.g.:
```
CUSTOM_PORTLETS = [
    'weather_portlet',
    'vimeo_portlet',
]
```
Note

each additional portlet listed in your CUSTOM_PORTLETS configuration must also be defined in the custom portlet config file:
```
<bscw-runtime-path>/conf/portal/config_portlets.py
```
Initially a sample configuration file for additional portlets is created as default configuration in:
```
<bscw-runtime-path>/conf/portal/config_portlets.py
```
The suggested procedure is to first adapt config_portlets.py to your needs, i.e. define your own portlets (see below), and then define the CUSTOM_PORTLETS list in <bscw-runtime-path>/conf/config.py to add the portlets you want to provide.
Note

You may want to provide translation for the new portlets you’ve added. You may define the portlet title in different languages as well as its description and settings. You need to add an according message files in:
```
<bscw-runtime-path>/bsext/msg/en/portal/custom_portlets.py
<bscw-runtime-path>/bsext/msg/de/portal/custom_portlets.py
...
```
For example the title and description of the sample weather_portlet could be defined in a message file (like custom_portlets.py) as follows:
```
weather_portlet = 'Weather (Germany)'
weather_portlet_desc = 'watch German weather forecast'
```
Regarding definition of custom portlets, currently the following options exist
- static content: allows you to define a portlets with static HTML content this is the most simple extension and useful for showing messages.
  
  Note
  
  the content will be copied once the portlet is added by the user (see helloworld_portlet for example)!
- iframe integration: allows you to integrate external sources - either from external websites or even from your (possibly internal) websites use PORTLET_CLASS: "URLFramePortlet" as basic setting (see doodle_portlet for example).

Disclaimer: External Widgets

When using external widgets you may have to check the terms of use of the widget provider before inserting the widget into the portal! OrbiTeam is not reliable for any damages incurred by external widgets or any interruption of external services used by integrated widgets.

Integration of external widgets using GoogleMaps or IFrame technology has been done according to current web standards. External widgets should not be allowed to access any private information stored within the BSCW shared workspace system due to current web security standards (and their implementation in JavaScript and todays Web Browser technology). However there is still a risk of potential security vulnerability by external widgets. We therefore recommend to only integrate external content and/or services from trusted providers.

Google®, Facebook®, Twitter® etc. are registered trademarks of the according companies in different countries of the world. OrbiTeam is not a partner, affiliate, or licensee of those companies. OrbiTeam acknowledges the terms of use of the provided services of those companies.

By using any of the integrated services provided via the BSCW portal you (as provider of the local BSCW) - and possibly your end users (as registered users of the external services) - have to accept the terms of services of the external provider of the integrated services. At any time you may disable any of the external services provided via the BSCW portal by changing the configuration file on your BSCW server.

OrbiTeam is not reliable for any consequences that occur from not accepting the terms of services of the external service providers or even from any abuse of the external services by end users.

Note

This feature is only available in the professional edition of BSCW.

6.16. Presence¶

The package presence indicates the “BSCW presence” of other members in your shared workspaces. In order to use this feature you may activate a presence toolbar which shows the presence status of each member. The toolbar is shown below the navigation bar of the shared workspace.

The “BSCW presence” is measured by the activity of a user in his/her web browser window where BSCW is used, i.e. if an user activates this window, moves the mouse over this window or types any keys on this browser window he becomes active in the sense of “BSCW presence”. The different states of the user presence result on different time periods defined in the configuration file. If a user is active the presence toolbar is updated automatically.

To enable the BSCW presence package run:

bin/bsadmin package -e presence

You may need to adapt the presence configuration by editing the instance configuration file (<bscw-runtime-path>/conf/config.py) and appending configuration directives. Possible configuration directives and their defaults are as follows:

P_TOOLBAR

defines the default view of the toolbars for users which have not changed it by themselves: 0 - hide, 1 - show all, 2 - show online. Default P_TOOLBAR = 0
P_SHOW_ALL_LIMIT

If a folder has more members than the P_SHOW_ALL_LIMIT the view of the presence toolbar changed to the ‘show online’ mode. Default: P_SHOW_ALL_LIMIT = 100
P_REFRESH

gives the refresh timeout of the presence toolbar. Default: P_REFRESH = 60
P_AVAILABLE_TIMEOUT, P_RECENTLY_TIMEOUT, P_INACTIVE_TIMEOUT
defines time periods after how much seconds the user state will changed if the user is inactive. Defaults:
P_AVAILABLE_TIMEOUT = 300 P_RECENTLY_TIMEOUT = 3600 P_INACTIVE_TIMEOUT = 7200

6.17. Readers¶

The package readers gives an action to select and filter the BSCW events to answer questions like

Who has read my documents?
Which documents I have read?

In the selection box at the end of the form you can select the documents which has been created, modified or read by a selected member. If an indexer is installed the content of the selected documents can be filtered by an search pattern. Initially the action shows you all members which have read documents created by yourself.

The results of the selection or all documents of the folder can be visualized by a graph. This graph may answers the questions

Who are the most active users?
Which are the important documents?

For visualisation the HyperGraph applet is used (http://hypergraph.sourceforge.net). It requires Java installed in your browser and JavaScript to control the HyperGraph applet.

No additional software installation or configuration is required on server-side. This package is not enabled by default. To enable the BSCW readers package run:

bin/bsadmin package -e readers

6.18. RSS¶

The package rss is implemented using the PyRSS2Gen.py library of Andrew Dalke and the Universal feed parser library by Mark Pilgrim. See file PyRSS2Gen-LICENSE.txt and feedparser.py for licensing and copyright conditions.

BSCW’s RSS package supports:

import of external RSS feeds into BSCW via “RSS Feed” objects BSCW’s “RSS Feed” objects allow subscription to arbitrary RSS feeds which will then be treated like BSCW folders.
export of BSCW event histories as RSS news feed BSCW events are rendered as a RSS 2.0 news feed which external RSS “aggregators” (or RSS “readers”) may poll for RSS formatted news items.

For a (comprehensive) description of the RSS 2.0 protocol see http://blogs.law.harvard.edu/tech/rss

Numerous RSS feed readers can be found in the web. Many modern web browsers like Firefox, Opera, or Safari allow to directly import and read external RSS feeds. See your browser’s documentation for more information.

6.18.1. Export of BSCW event histories¶

Depending on your server configuration http://<server>/sec/bscw.cgi/?op=rss will render an XML formatted RSS news channel of all events which the authenticated user has access to.

You may adapt the rss configuration by creating the configuration file <bscw-runtime-path>/conf/rss/config.py and appending the following configuration directives

RSS_AUTHENTICATION
determines the used authentication method:
- if set to 1 always authentication credentials are required from the RSS news reader;
- if set to 0 unauthenticated reading of BSCW’s RSS events using token authentication is allowed. This is the default (see section 6.20.3 Reading of RSS event feeds below)
RSS_TIME_SPAN

is the age of the event from now in seconds. By default, RSS_TIME_SPAN is set to a 7 day period.
RSS_MINFETCH

defines the minimal time between two feed fetch attempts (in minutes).
RSS_FEEDTIMEOUT

defines the maximal time to wait for an feed to respond (in seconds).

No additional software installation or configuration is required on server-side. This package is enabled by default. If disabled, the package may be enabled again by running:

bin/bsadmin package -e rss

6.18.2. RSS reference links¶

The rss package, if activated, also includes an RSS reference into any of BSCW’s container HTML rendering. Thus:

<link rel="alternate"
    type="application/rss+xml" title="BSCW RSS 2.0 NewsFeed"
    href="http://<server>/sec/bscw.cgi/?op=rss" />

(depending on your server configuration) is included in the HTML head section. This allows RSS compatible browsers, like Firefox, Opera or Safari, to display an icon which indicates that an RSS news feed is supported: end-users click on that icon to create a LiveBookmark in Firefox or directly open the BSCW news feed in their browser (Opera and Safari). Firefox also offers a number of plugins which display news feeds more nicely. See http://addons.mozilla.org/ extensions and search for “RSS”.

Please note you will at least need the following web browser version to support RSS: Firefox: version 1+, Opera: version 8+, Safari: version 2+, Internet Explorer 7+. Mozilla Thunderbird 2+ is also capable of displaying RSS 2.0 news feeds.

6.18.3. Reading of RSS event feeds¶

Not all external RSS news aggregators are capable of requesting authentication credentials. Therefore, the rss package can be configured to allow for unauthenticated access via public script, using, e.g.

http://<server>/pub/bscw.cgi/?op=rss&token=123:aksddf34sd$tt

where “token” consists of a pair (user id: her encrypted password). Btw. encrypted passwords can be obtained using the system administrator’s shell command bsadmin users -p user_name.

At the user interface, menu command [GoTo ‣ Events] will either render a secure script URL (http://<server>/sec/bscw.cgi/?op=rss) or a public script URL (http://<server>/pub/bscw.cgi/?op=rss&token=123:aksddtt), depending on the value of RSS_AUTHENTICATION.

This also holds true for the RSS reference link included in BSCW containers’ HTML source code rendering, cf. section 6.20.2 RSS reference links above.

6.19. SSO – Single Sign On¶

BSCW supports different mechanisms for integration with an existing Single Sign On (SSO) infrastructure. By using SSO a BSCW server may be integrated into an IT infrastructure where different applications share the same user base and provide a central login mechanism the end users (e.g. in a web portal).

BSCW now supports CAS (Central Authentication Server), an open source SSO server developed by Yale University (see https://www.apereo.org/products/cas), Shibboleth, a standards-based, open source middleware software which provides SSO even across organizational boundaries (see https://www.shibboleth.net/) and OpenID (see https://openid.net).

6.19.1. CAS Authentication¶

CAS authentication allows users to authenticate at a central authentication server. In combination with a LDAP service first time CAS users are automatically registered at their first login at the BSCW server. To configure CAS

Edit the main server configuration file <bscw-runtime-path>/conf/config.py as follows:

Define the URL of the CAS Single Sign On service, e.g.:
```
CAS_URI = 'http://sso.domain.org:8080/cas'
```
Define a Single Sign On prefix and enable cookie authentication for this prefix:
```
SSO_PREFIX = '/cas/'
SSO_COOKIE = ('bscw_cas', None, 120)
```

To define an alternate secure authentication path for CAS enter the tuple:

(SSO_PREFIX, { 'mode': AUTH_MODE, 'cookie': SSO_COOKIE })

in SCRIPTS_ALIASES, e.g.:

SCRIPTS_ALIASES = {
    '/sec/': [
        (SSO_PREFIX,
            {'mode': AUTH_MODE, 'cookie': SSO_COOKIE }),
    ]
}

Create a new Apache HTTP server configuration with

$ ./bin/bsadmin conf_apache -n
Configure 'gzip' compression ...
Configure 'static' resources 'var/www/20221006-1545-2ba118f'...
 (Long time future expire dates)
Configure secure prefix '/sec/' (Apache 2) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 2)...
 (No authentication)
Configure secure prefix '/cas/' (Apache 2) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure secure prefix '/sec/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
Configure public prefix '/pub/' (Apache 24)...
 (No authentication)
Configure secure prefix '/cas/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)

Creating Apache HTTP server configuration files in
<bscw-runtime-path>/conf/apache{2,24}
 mod.conf ... module configuration file
site.conf ... virtual host site configuration file
bscw.conf ... BSCW configuration file

and restart your web server to reload its configuration, e.g.:

> su -
# systemctl restart apache2
# systemctl restart httpd

6.19.2. OpenID¶

In order to activate OpenID single-sign-on registration and authentication see https://openid.net.

The BSCW OpenID module needs the python-openid Python package.

On Linux systems the python-openid package of the distribution should be installed.

Packages name(s) for common Linux distributions:
- Debian based systems: python-openid
- EL based systems: python-openid
Alternatively use the Python package manager pip:
```
$ su -
# pip install python-openid
```
On Windows systems install python-openid using the Python package manager pip:
```
> pip install python-openid
```

Afterwards edit the main server configuration file <bscw-runtime-path>/conf/config.py and define:

OPEN_ID_DEFAULT = ("openid.net", "http://openid.net/get-an-openid")

This will show a link to the “default provider” openid.net in the login page. This enables a user to get an OpenID URL if he does not have one. If you do not want to give a link to a default provider set:

OPEN_ID_DEFAULT = ("", "")

Note

COOKIE_AUTHENTICATION must be set and location (see above) must be None when OpenIDs are used.

OpenID registration and authentication is disabled with:

OPEN_ID_DEFAULT = None

6.19.3. Shibboleth Authentication¶

Shibboleth allows users to log in via Single Sign-On as well as normal users to log in via user name and password. First time Shibboleth users can be automatically registered and their profile can be updated on every login, so that their user details always up-to-date.

6.19.3.1. Shibboleth Service Provider configuration¶

In order to use BSCW with Shibboleth a Shibboleth Service Provider (e.g. Apache mod_shib) has to be installed on the same host like BSCW. Please refer to the deployment guides of your federation or to the official Shibboleth Wiki https://wiki.shibboleth.net/confluence/display/SHIB2/ on how to install and configure a Shibboleth Service Provider in your environment. Another good source of information with configuration examples are the “guides for SWITCHaai” at https://www.switch.ch/aai/guides/.

BSCW needs at least the following values for an authenticated Shibboleth user:

Application ID (Shib_Application_ID)
Identity Provider (Shib_Identity_Provider)
Email address (mail)

The environment variables Shib_Application_ID and shib_Identity_Provider should be automatically set by mod_shib (BSCW automatically switches back to HTTP_SHIB_APPLICATION_ID and HTTP_SHIB_IDENTITY_PROVIDER for old (not recommended) Shibboleth 1.3 installations, see below).

Please make sure that the mail attribute is available for all Shibboleth users once they are authenticated. Also ensure that the Shibboleth 2.x attribute-map.xml maps the above attributes to a web server environment variable with the name given between parentheses.

6.19.3.2. BSCW configuration¶

You must add an entry for your federations at two places within the instance configuration file (<bscw-runtime-path>/conf/config.py). In the example we show it for the federation 'SnakeOilProviders' and also as a commented entry for 'BscwTest':

FEDERATIONS = {
    'SnakeOilProviders': ('login_shib', '/snakeoil-login.gif', (
        (r'[^@]*@snake-oil\.com', 1),
        (r'[^@]*@snake-oil\.de', 1),
    )),
    # Another federation
    #'BscwTest': ('login_shib', '/bscwtest-login.gif', ()),
}

SCRIPTS = {
    ...
    '/pub/snakeoil/':
        ('SnakeOilProviders', '', CREATE_SCRIPTS, SECURE_SCRIPTS),
    # Another federation
    #'/pub/bscwtest/':
    #    ('BscwTest', '', CREATE_SCRIPTS, SECURE_SCRIPTS),
}

Note

If you need more than one federation you must configure them with different Application Ids in the Shibboleth configuration. The Application Ids must be ‘default’ or match the name given in FEDERATIONS and SCRIPTS.
If you make changes like this to the instance configuration file (<bscw-runtime-path>/conf/config.py) you have to regenerate the Apache configuration and index pages with bsadmin conf_apache and bsadmin index_page respectively. This also requires a restart of the Apache server.
If Shibboleth is the only/primary authentication system for BSCW, we also recommend setting:
```
SERVER_LOGOUT = '/Shibboleth.sso/Logout?return=/pub/'
```
(it depends on your Shibboleth configuration and we have not a good idea yet how to do it with more than one federation).

This then destroys not only the BSCW but also the Shibboleth session and sends the user back to the BSCW start page. This should work even if a user does not have a Shibboleth session.

The following CGI environment variables are interpreted by BSCW:

Shibboleth 2.x	Shibboleth 1.3	BSCW key
Shib_Application_ID	HTTP_SHIB_APPLICATION_ID	shib_app_id
Shib_Identity_Provider	HTTP_SHIB_IDENTITY_PROVIDER	shib_idp
mail	HTTP_SHIB_INETORGPERSON_MAIL	email
givenName	HTTP_SHIB_INETORGPERSON_GIVENNAME	givenname
sn	HTTP_SHIB_PERSON_SURNAME	surname
org-dn	HTTP_SHIB_SWISSEP_HOMEORGANIZATION	org
telephoneNumber	HTTP_SHIB_PERSON_TELEPHONENUMBER	phone
homePhone	HTTP_SHIB_INETORGPERSON_HOMEPHONE	homephone
mobile	HTTP_SHIB_INETORGPERSON_MOBILE	mobile
preferredLanguage	HTTP_SHIB_INETORGPERSON_PREFERREDLANGUAGE	language

BSCW needs only values for shib_app_id, shib_idp, and email. The others are optional. If your Shibboleth installation sets other CGI environment variables, e.g. Shib-IDP instead of Shib_Identity_Provider and Mail instead of mail (i.e. you don’t want to use an Attribute alias) then you can redefine the environment keys in the instance configuration file (<bscw-runtime-path>/conf/config.py) by adding:

HTTP_SHIB_ENVIRONMENT = [
    #(bscw_key, evironment_key)
    ('shib_idp', 'Shib-IDP'),
    ('email', 'Mail'),
]

6.20. Tasks¶

This package provides an optional feature for BSCW that allows users to create tasks that may be combined to ad-hoc (mini-)workflows.

The tasks package is enabled by default on new BSCW servers and requires no external components. If disabled, the package may be enabled again by running:

bin/bsadmin package -e Tasks

After activation a new top-level object ‘Tasklist’ is enabled at the user interface (in ‘Goto’ menu/icons).

Note

This feature is only available in the professional edition of BSCW.

See also

Chapter 8 BSCW Help for further details.

6.21. Timeline¶

This package provides an optional feature for BSCW that allows users to view time aware object in a Timeline view. You may want to enable this package if you want to offer this additional functionality to your end users.

When the package is activated a new menu item (and optional toolbar item) [Goto ‣ Timeline] is enabled at the user interface.

By selecting the menuselection:[Timeline] action a new window opens that will show all time aware objects in the given context (i.e. the current folder, including all sub-folders) on a Timeline. The user may select what kind of time aware objects to show.

Time aware objects especially include: Project, Phase, Appointment, Task, and Opinion Polls (including Voting, Poll and Appointment Scheduling).

See also

Chapter 8 BSCW Help for further details.

This package is not enabled by default. To enable the Timeline package run:

bin/bsadmin package -e Timeline

6.22. WebFolder¶

The WebFolder package provides an optional feature for BSCW that allows users to create so-called Website Folders, special folders containing a website, rather similar to a Wiki system.

The WebFolder package is enabled by default on new BSCW servers and requires no external components. If disabled, the package may be enabled again by running:

bin/bsadmin package -e WebFolder

There is no required configuration, the configuration defaults should work on all systems. You may define additional configuration details by creating the configuration file <bscw-runtime-path>/conf/WebFolder/config.py and appending one of the following variables:

WF_DEFAULT_SAMPLE

Number (beginning with 0) of default WebFolder sample content, which is offered in “New Website Folder”. A usual BSCW server comes with four sample contents: “basic” (0), “project” (1), “faq” (2) and “demo” (3). It is also possible to extend the offered sample contents. Please contact the BSCW support for detailed information.
WF_DEFAULT_DESIGN

Number (beginning with 0) of the default WebFolder design, which is selectable in “New Website Folder”. An off-shelve BSCW server has four designs built-in: Tree navigation (0), Query navigation (1), Tree in orange color (2) and Query in orange color (3). If you wish to add more designs, please contact the BSCW support.
WF_MAX_VERSIONS

Specifies the predefined setting for auto-versioning in Website Folders. Possible values:

1: New documents are not set under version control.

0: New documents are automatically set under version control and all revised versions will be stored.

-1: Use global (server-wide) MAX_VERSIONS setting.

>1: New documents are automatically set under version control, but only the given number of latest versions will be kept. Saving a new version will remove the oldest version if the limit has been reached. The default setting is to keep 10 versions.
WF_DEFAULT_TEMPLATE_DOC

Name of the default layout page, as offered in “New Layout Page”. The layout pages newTreetemplate and newQuerytemplate are part of any standard BSCW server and implement different navigation types.
WF_DEFAULT_TEMPLATE_DOC_NAME

Default name for new layout pages inside of BSCW. Note that the page itself might contain information about a different name, which is used at higher priority.
WF_DEFAULT_STYLE_DOC

Name of the default style definition, as offered in “New Style Definition”. Pre-defined style definition are classicDefaultstyle and newDefaultstyle.
WF_DEFAULT_STYLE_DOC_NAME

Default name of new style definitions inside of BSCW.
WF_DEFAULT_TEMPLATE_FOLDER_NAME

Default name of the template folder inside of Website Folders. Template folders are optional, but useful to hold templates for empty pages or other often-used page types.

See also

Chapter 8 BSCW Help for end-user help concerning Website Folders.