5. 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.

5.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 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 https://lucene.apache.org/pylucene/.

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

Some pre-build binaries are provided by the pylucene-extra project at https://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 7.5.4 supports pylucene 3.6.2

Important

Additionally pylucene requires an installed Java Runtime Environment (JRE) 11

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.

5.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.

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 https://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 https://lucene.apache.org for details on how this affects indexing.

5.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.

5.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 start_servers).

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

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

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 &

5.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 ldap3 package. Ldap3 natively implements an RFC 1823 API (see OpenLDAP https://www.openldap.org).

5.2.1. Installation¶

To install the BSCW LDAP module

The BSCW LDAP module needs the ldap3 Python package. ldap3 implements a native Python LDAP client library.
- On Linux systems the ldap3 package of the distribution should be installed.
  
  Packages name(s) for common Linux distributions:
  - Debian based systems: python3-ldap3
  - EL 8 based systems:
    $ su - # pip-3.8 install ldap3
  - EL 9 based systems: python3-ldap3

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-7.5.4-<rev>-py3*/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) 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
  - 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*)'),

5.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 https://www.ietf.org – we suggest to read the IBM Redbook: Understanding LDAP (SG-244986, June 1998), available at https://www.redbooks.ibm.com.

5.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

5.4. Chat¶

The chat package allows you to send multimedia messages to other BSCW users in real time, creating a feeling similar to a spoken conversation. No further configuration is required.

5.5. 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

5.6. 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: python3-pil python3-reportlab
  - EL 8 based systems:
    
    $ su - # pip-3.8 install pillow reportlab
  - EL 9 based systems:
    
    $ su - # pip-3.9 install pillow 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.

5.7. 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

5.8. 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.

5.8.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 8/9 based systems:

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

5.8.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 8/9 based systems:

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

5.9. 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

5.10. 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

5.11. Online Office¶

The office package provides integration with online office applications. Currently ONLYOFFICE, Microsoft 365 or Collabora Online (deprecated) are supported.

Note

The free versions of ONLYOFFICE or Collabora Online allow editing of 10 documents with 20 concurrents users. For more users a commercial license is required.

5.11.1. ONLYOFFICE configuration¶

To run a ONLYOFFICE Docs Community Edition service a server host with a Debian or Enterprise Linux (EL) based Linux is required. Basically the installation requires the following steps:

Installation of dependencies

NGINX

PostgreSQL with database initialization/creation

RabbitMQ and Erlang

mscorefonts

Installation of ONLYOFFICE

Configuration of ONLYOFFICE

PostgreSQL and RabbitMQ user credential definition

ONLYOFFICE SQL table generation

open firewall ports

For more details, see the ONLYOFFICE documentation. The requirements are described at:

https://helpcenter.onlyoffice.com/de/installation/docs-community-sys-reqs-linux.aspx

To install ONLYOFFICE follow the installation guide for

Debian based systems:

https://helpcenter.onlyoffice.com/installation/docs-community-install-ubuntu.aspx

EL based systems:

https://helpcenter.onlyoffice.com/installation/docs-community-install-centos.aspx

5.11.2. Collabora Online configuration¶

The easiest way to run a Collabora Online instance is to use the pre-configured Docker container image, see https://www.collaboraoffice.com/code/ for details. The container image is deployed using the commands:

$ docker pull collabora/code:4.0.9.4
$ docker run -t -d -p 127.0.0.1:9980:9980 \
    -e 'domain=<dot-escaped-domainname>' \
    -e 'username=admin' \
    -e 'password=<password>' \
    --name "collabora" \
    --restart always --cap-add MKNOD collabora/code:4.0.9.4

The <dot-escaped-domainname> requires “dot-escaping” of the BSCW instance name SERVER_ROOT, e.g.:

bscw.domain.org
=>
bscw\\.domain\\.org

Generally (escaped) regular expressions are allowed as <dot-escaped-domainname>, such as:

.*\.domain\.org
=>
\.*\\.domain\\.org

The Collabora Online instance operates in read only mode and does not allow writing documents. To allow editing (including writing) of documents the host IP address of each BSCW instance must be whitelisted in a configuration file within the container image.

For this purpose, the host IP address of the BSCW instance must be inserted in the file /etc/loolwsd/loolwsd.xml (note you have to escape dot characters (. -> \.)).

For example, suppose the IP address of your BSCW instance is 10.11.12.13. In this case the following entries:

<host desc="BSCW instance (IPv4-mapped IPv6)">::ffff:10\.11\.12\.13</host>
<host desc="BSCW instance (IPv4)">10\.11\.12\.13</host>

must be added in the <post_allow>...</post_allow> section of the loolwsd.xml file as follows:

<net desc="Network settings">
  <proto type="string" default="all" desc="Protocol to use IPv4, IPv6 or all for both">all</proto>
  <listen type="string" default="any" desc="Listen address that loolwsd binds to. Can be 'any' or 'loopback'.">any</listen>
  <service_root type="path" default="" desc="Prefix all the pages, websockets, etc. with this path."></service_root>
  <post_allow desc="Allow/deny client IP address for POST(REST)." allow="true">
    <host desc="The IPv4 private 192.168 block as plain IPv4 dotted decimal addresses.">192\.168\.[0-9]{1,3}\.[0-9]{1,3}</host>
    <host desc="Ditto, but as IPv4-mapped IPv6 addresses">::ffff:192\.168\.[0-9]{1,3}\.[0-9]{1,3}</host>
    <host desc="The IPv4 loopback (localhost) address.">127\.0\.0\.1</host>
    <host desc="Ditto, but as IPv4-mapped IPv6 address">::ffff:127\.0\.0\.1</host>
    <host desc="The IPv6 loopback (localhost) address.">::1</host>
    <host desc="BSCW instance (IPv4-mapped IPv6)">::ffff:10\.11\.12\.13</host>
    <host desc="BSCW instance (IPv4)">10\.11\.12\.13</host>
  </post_allow>
</net>

You may also want to disable the signing server endpoint URL by removing the URL https://app.vereign.com from the <document_signing_url></document_signing_url> entry as follows:

<document_signing_url desc="The endpoint URL of signing server, if empty the document signing is disabled" type="string" default=""></document_signing_url>

Edit the /etc/loolwsd/loolwsd.xml file within the Collabora Online container as follows:

Copy the loolwsd.xml file from the Collabora container to your local host and enter the above mentioned entries for the BSCW instance host IP address:

$ docker ps -a
CONTAINER ID        IMAGE                   ...     NAMES
ea5740114e13        collabora/code:latest   ...     <containername>

$ docker cp <containername>:/etc/loolwsd/loolwsd.xml .

Edit the loolwsd.xml file and add the additional IP entries as described above.:
```
$ vi loolwsd.xml
```
Be aware the docker run from above altered the following entries in the loolwsd.xml file:
- the domain= definition edits the <wopi></wopi> and the <webdav></webdav> entries.
- the admin= definition edits the <admin_console></admin_console> entries.

Copy the loolwsd.xml file back to the Collabora Online container:

$ docker cp loolwsd.xml <containername>:/etc/loolwsd/loolwsd.xml~
$ docker exec -u 0 <containername> chown lool:lool /etc/loolwsd/loolwsd.xml~
$ docker exec <containername> mv /etc/loolwsd/loolwsd.xml~ /etc/loolwsd/loolwsd.xml

Restart the Collabora Online container:

$ docker stop <containername>
<containername>
$ docker start <containername>
<containername>

To update the Collabora Online image proceed as follows:

$ docker stop <containername>
$ docker rm <containername>

and repeat all steps from above.

5.11.3. BSCW office package configuration¶

The office package is not enabled by default on new BSCW servers and requires external components. Before enabling the office the following additional packages pyjwt and pycryptodome are required.

Packages name(s) for these Linux distributions:

Debian based systems: python3-pycryptodome python3-jwt

EL 8 based systems:

$ su -
# pip-3.8 install pycryptodome pyjwt

EL 9 based systems: python3-pycryptodome python3-jwt

If disabled, the package may be enabled by running:

bin/bsadmin package -e office

After the package is activated, the package must be configured using the following directives in the instance configuration (<bscw-runtime-path>/conf/config.py):

OFFICE_PROVIDER

defines the office provider, either “OO” for ONLYOFFICE or “MS” for Microsoft 365 or “C” for Collabora Office (deprecated).
OFFICE_VERSION

allows to set the configuration for a specific version of the Online Office provider. The value default uses the preconfigured settings. For details see the configuration file <bscw-runtime-path>/conf/config_<provider>.py (e.g. config_oo.py for ONLYOFFICE)
OFFICE_HOST

All provider definitions assume a scheme (http:// or https:// before the domain or IP address). OFFICE_HOST defines
- for the “OO” provider
  
  the URL to the ONLYOFFICE documentserver (e.g. http://localhost).
- for the “MS” provider
  
  the full WOPI discovery URL, as provided by a Microsoft 365 provider. To enable Microsoft 365 with your BSCW instance a DNS entry into the domain wopi.bscw.de is required, ask support@orbiteam.de for details.
- for the “C” provider
  
  the IP address of Collabora Online Office service (deprecated). By default, the IP address of Collabora Online Office is set to ‘127.0.0.1’.
  
  Note
  
  Due to lack of customer demand, only versions up to 4.0.9 are supported.
OFFICE_PORT

defines the port of the Online Office service. By default, Collabora uses port 9980, and MS Office and ONLYOFFICE use port 443. With OFFICE_PORT = None (default) these values are used.
OFFICE_SERVER_ROOT

defines an alternative URL to the BSCW instance for use in DMZ environments. If OFFICE_SERVER_ROOT = None (default), SERVER_ROOT is used.
OFFICE_JWT_SECRET

defines a shared secret between BSCW and ONLYOFFICE for secure data exchange. Compare the ONLYOFFICE definitions (see /etc/onlyoffice/documentserver/local.json: services.secret.{inbox|outbox|session}.string). Additionally requires PyJWT (default: OFFICE_JWT_SECRET = None).
OFFICE_JWT_HEADER

defines the name of the HTTP header where the JSON web token (JWT) is stored. Compare the ONLYOFFICE definitions (see /etc/onlyoffice/documentserver/local.json: services.token.{inbox|outbox}.header) (default: OFFICE_JWT_HEADER = None).
OFFICE_FORCE_SAVE

(for “OO” provider only) If set to True, the edited document will be saved before another user may take over the document lock (default: OFFICE_FORCE_SAVE = True).

Ensure your Apache HTTP server modules authn_core, authz_core, filter, proxy, proxy_wstunnel, proxy_http, ssl, and substitute are enabled and restart the HTTP server as root user:

Debian based systems:

$ su -
# a2enmod authn_core authz_core filter
# a2enmod proxy proxy_http proxy_wstunnel ssl substitute
# 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
# vim /etc/httpd/conf.modules.d/00-ssl.conf
# systemctl restart httpd

Note

If you use HTTPS, both BSCW and the online office services must be able to validate each other’s SSL certificates. In particular, the required intermediate certificates (chain) to the certificate issuer certification authority must be provided.

After each change of one of a OFFICE_` directive the Apache HTTP server configuration must be recreated with:

bin/bsadmin conf_apache

This updates the Apache HTTP server configuration file (<bscw-runtime-path>/conf/apache24/site.conf) with a online office configuration block (resp. includes a file <bscw-runtime-path>/conf/apache24/service_token.conf) for the selected provider which must be integrated into the virtual host configuration of the BSCW instance.

5.12. 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’

5.13. 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).

5.13.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 = 'https://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/20230203-1041-c217ad7'...
 (Long time future expire dates)
Configure public prefix '/pub/' (Apache 24)...
 (No authentication)
Configure secure prefix '/sec/' (Apache 24) ...
 (HTTP_AUTHORISATION passed to BSCW)
 (Cookie authentication enabled)
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/apache24
 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

5.13.2. OpenID¶

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

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

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

Packages name(s) for common Linux distributions:
- Debian based systems: python3-openid
- EL 8 based systems:
```
$ su -
# pip-3.8 install python3-openid
```
- EL 9 based systems:
```
$ su -
# pip-3.9 install python3-openid
```

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

OPEN_ID_DEFAULT = ("openid.net", "https://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

5.13.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.

5.13.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.

5.13.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'),
]

5.14. Task¶

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

The task 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 task

Note

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

5.15. 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 is newDdefaultstyle.
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.

Table of Contents

Previous topic

Next topic

5. BSCW Packages¶

5.1. Content Search PyLucIndex¶

5.1.1. Configuration¶

5.1.2. Command line tools¶

5.1.3. Index creation and update¶

5.2. LDAP¶

5.2.1. Installation¶

5.2.2. LDAP Browser¶

5.3. Document Approval¶

5.4. Chat¶

5.5. Expire¶

5.6. Export PDF¶

5.7. Flow-Folder¶

5.8. Http¶

5.8.1. Enabling the BSCW HTTP server¶

5.8.2. Disabling the BSCW HTTP server¶

5.9. Incognito¶

5.10. Metaprofiles¶

5.11. Online Office¶

5.11.1. ONLYOFFICE configuration¶

5.11.2. Collabora Online configuration¶

5.11.3. BSCW office package configuration¶

5.12. Poll¶

5.13. SSO – Single Sign On¶

5.13.1. CAS Authentication¶

5.13.2. OpenID¶

5.13.3. Shibboleth Authentication¶

5.13.3.1. Shibboleth Service Provider configuration¶

5.13.3.2. BSCW configuration¶

5.14. Task¶

5.15. WebFolder¶