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

  1. 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
      
    • and to disable distributed a BSCW package run:

      bin/bsadmin package -d <pkg-name>
      bin/bsadmin package -d ldap
      
  2. 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
      
    • and to disable an external BSCW package run:

      bin/bsadmin package -d <pkg-name>
      bin/bsadmin package -d fhg_fit
      

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/

BSCW 7.0 supports PyLucene 3.6.2

Important

  • Additionally PyLucene requires an installed Java Runtime Environment (JRE) 8
  • (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_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
  1. 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).

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

  1. 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
      • Fedora based systems: python3-ldap3

      Alternatively use the Python package manager pip:

      $ su -
      # pip3.5 install ldap3
      
    • On Windows systems install ldap3 using the Python package manager pip:

      > pip install ldap3
      
  2. Additionally the BSCW LDAP module may need the py-smbpasswd package to create SMB password hashes if the LDAP directory uses LANMAN or NT password hashes.

    • On Linux systems the py-smbpasswd package of the distribution should be installed.

      Packages name(s) for common Linux distributions:

      • Debian based systems: python3-smbpasswd
      • Fedora based systems: python3-smbpasswd

      Alternatively use the Python package manager pip:

      $ su -
      # pip3.5 install smbpasswd
      
    • On Windows systems install py-smbpasswd using the Python package manager pip:

      > pip install smbpasswd
      
    • Alternatively download the py-smbpasswd at https://github.com/barryp/py-smbpasswd and manually install the package.

    Note

    If the py-smbpasswd package is not found and your LDAP schema uses LANMAN or NT password hashes the lmpassword, sambalmpassword and ntpassword, sambantpassword attributes are ignored and the BSCW change password operation will fail.

  3. 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.0.0-???????-py35/bscw/conf/ldap/config.py \
       srv/<bscw-instance>/conf/ldap
    

    and run:

    $ cd srv/<bscw-instance>
    $ bin/bsadmin package -e ldap
    
  4. 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. Desktop Widgets

The airdesktop package provides a feature for BSCW to provide desktop widgets using Adobe Air. Widgets may display information stored within BSCW (folders, tasks etc).

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 airdesktop

6.4. 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.5. 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.6. BSync - Desktop Synchronisation

6.7. Case – File Synchronisation

The case package provides an optional feature for BSCW that allows users to synchronize documents stored in their shared workspaces with their local file system (i.e. Windows PC). You may want to enable this package if you want to offer this additional functionality to your end users.

After the case package is activated a new top-level object ‘Case’ is visible at the user interface (in [Goto] menu/icons)

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 case

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

  • CASE_LOCAL_PATH

    defines default case path on local disk (%s is replaced by the user name):

    CASE_LOCAL_PATH = 'C:\Users\%s\BSCWCase'
    
  • CASE_MAX_VERSIONS

    defines maximum number of versions to be stored in local case

    Note

    • user may choose whether versions of documents shall be downloaded:

      CASE_MAX_VERSIONS = 3
      
    • This feature is only available for Windows Systems (client-side).

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

    See also

    Chapter 8 BSCW Help for further details.

6.8. 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.9. 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:

  1. 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):

    • The ReportLab PDF Library:

    • On Linux systems use preferred the packages of your distribution:

      • Debian based systems: python3-pil python3-reportlab
      • Fedora based systems: python3-pillow python3-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
      
  2. 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.10. 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.11. 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 preforking http service] entry.

6.11.1. Enabling the BSCW HTTP server

  1. Stop the BSCW instance services:

    bin/bsadmin stop
    
  2. Enable the http package:

    bin/bsadmin package -e http
    
  3. 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"
    
  4. 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.

  5. 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
      
    • Fedora based systems:

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

6.11.2. Disabling the BSCW HTTP server

  1. Stop the BSCW instance services:

    bin/bsadmin stop
    
  2. Disable the http package:

    bin/bsadmin package -d http
    
  3. 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
    
  4. Start the BSCW instance services:

    bin/bsadmin start
    

    This starts the BSCW services without the pre-forking BSCW HTTP server again.

  5. 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
      
    • Fedora based systems:

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

6.12. 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.13. 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.14. 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_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.15. Online Office

The office package provides integration with WOPI based office applications, e.g. Collabora Online.

Note

  • The free version of Collabora Online allows editing 10 documents with 20 concurrents users. For more users a commercial license is required (please ask license@orbiteam.de for licensing details).
  • WOPI based office applications require a HTTPS enabled web server.

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
$ docker run -t -d -p 127.0.0.1:9980:9980 \
    -e "domain=<dot-escaped-domain>" \
    -e "username=admin" \
    -e "password=<password>" \
    --name "office" \
    --restart always --cap-add MKNOD collabora/code

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

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

The office package is not enabled by default on new BSCW servers and requires external components. 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_HOST

    defines the IP address of Collabora Online Office service. You must execute bsadmin conf_apache after changing this IP. By default the IP address of Collabora Online Office is 127.0.0.1:

    OFFICE_HOST = '127.0.0.1'
    
  • OFFICE_PORT

    defines the port of the Collabora Online Office service. You must execute bsadmin conf_apache after changing this port. By default the port of Collabora Online Office is 9980.:

    OFFICE_PORT = '9980'
    

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

  • Debian based systems:

    $ su -
    # a2enmod proxy proxy_http proxy_wstunnel ssl
    # systemctl restart apache2
    
  • Fedora based systems:

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

If the OFFICE_HOST or OFFICE_PORT directives have been changed the Apache HTTP server configuration should be recreated with:

bin/bsadmin conf_apache

This updates the Apache HTTP server configuration file (<bscw-runtime-path>/conf/apache24/site.conf) with a Collabora Online configuration block which must be integrated on the virtual host configuration of the BSCW instance in order to run the BSCW servdiscovery service..

6.16. 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.17. 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.17.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

  1. 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 }),
          ]
      }
      
  2. Create a new Apache HTTP server configuration with:

    $ ./bin/bsadmin conf_apache -n
    Configure public prefix '/pub/' (Apache 2)...
     (No authentication)
    Configure secure prefix '/sec/' (Apache 2) ...
     (HTTP_AUTHORISATION passed to BSCW)
     (Cookie authentication enabled)
    Configure secure prefix '/cas/' (Apache 2) ...
     (HTTP_AUTHORISATION passed to BSCW)
     (Cookie authentication enabled)
    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/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.17.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
    • Fedora based systems: python3-openid

    Alternatively use the Python package manager pip:

    $ su -
    # pip3.5 install python3-openid
    
  • On Windows systems install python3-openid using the Python package manager pip:

    > pip install python3-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.17.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.17.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.17.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.18. Sync - MS Outlook Synchronization

The package sync enables PIM synchronisation for MS-Outlook. End users may synchronise their BSCW contacts and calendars with their MS-Outlook client.

The synchronisation feature is implemented as Java applet. Thus Java is required (Java Plugin, JRE 8 or later).

This feature is only available for Windows systems (client-side).

Note

The synchronisation feature uses the BSCW XML-RPC API (X-API). for data exchange between the Java applet and the BSCW-server. This package therefore requires activation of the BSCW XML-RPC API.

By default standard webservice calls are already allowed for registered users - unless this setting is changed in your instance configuration file (<bscw-runtime-path>/conf/config.py). Otherwise make sure that the configuration includes:

ACCEPT_WEBSERVICES = 1

This package is enabled by default in a new BSCW server installation. 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 sync

Note

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

6.19. 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.20. 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.

See also

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