Integrating Collaboration

This chapter describes the features that let you use Collaboration with the Microsoft Windows desktop, back-end groupware server, and Microsoft Project. This helps users work more efficiently by integrating Collaboration into a single work environment. It includes the following sections:

Integrating Collaboration and the Desktop

This section describes the configuration and administration of Collaboration features that provide integration with the Microsoft Windows desktop. It includes the following sections:

Overview of WebDAV Protocol

Collaboration's desktop integration features require the Web-Based Document Authoring and Versioning (WebDAV) protocol. WebDAV is an extension to the HTTP protocol. During installation, the Collaboration installer lets you install and configure a WebDAV service.

Configuring Web Folders

Collaboration lets users manage Collaboration documents directly from their desktop using Microsoft Windows Explorer. After mapping a Web folder, users can access, edit, and share documents in a Collaboration project or create new Collaboration projects. The Web Folder Settings page in Collaboration Settings lets users select the projects whose documents they want to access with Microsoft Windows Explorer.

Documents opened through Windows Explorer are automatically opened in edit mode and checked out in Collaboration. This helps users work more efficiently by removing the need to check out and download the document. All security and version control operations are performed by Collaboration.

Adding Activity Rights

To map a Web folder to Collaboration, users must belong to a group that is granted the Bulk Upload to Collaboration activity right. This activity right also lets users employ the Bulk Upload feature.

Click the Administration tab.
Select the Activity Manager utility.
Click Bulk Upload to Collaboration.
Click Add Group.
Select the groups you want to have this activity right.
Click OK.
Click Finish.

For more information on managing activity rights, see the Administrator Guide for BEA AquaLogic Interaction (Plumtree Foundation).

Using IIS with Web Folders

If you are using the Map a Web Folder feature when the portal is running IIS, you must ensure that the Front Page server extensions are disabled on the IIS Web site where the portal is deployed.

Choose Start | Programs | Administrative Tools | Internet Service Manager.
Right-click on the Web site used by the portal.
Select Properties.
Select the Server Extensions tab.

If you receive a message stating that the server has not been configured to use server extensions, then IIS is configured correctly.

If the Enable authoring checkbox exists, ensure that it is not checked.

Making the Collaboration Office Tools Add-In Installer Available to End Users

The Collaboration Office Tools Add-In lets end users choose from several check-in options and type additional check-in comments. The Add-In dialog appears after users edit and close a document either from WebEdit or within the Web folder on their personal computer.

The Collaboration Office Tools Add-In must be installed on the machine of each user who may want to use the Add-In. WebEdit, however, still functions correctly without the installation of the Add-In. You can either push out the Add-In's installer to your users or have them download it.

To push out the installer to end users, use the .msi file appropriate to your language:

To make the installer available to be downloaded by end users, set the
docman.webEdit.installOfficeTool¯sPopUp.enabled parameter in config.xml to yes.

Mapping Web Folders

This section describes how to map a Web folder. You should test these procedures before rolling out a production version of Collaboration.

Copy the URL in the Web Folder Location box.
Open My Network Places on your desktop.
Double-click Add Network Place. The Add Network Place Wizard appears.
In the Type the location of the Network Place box, paste the URL, then click Next.
If prompted, enter your name and password, then click OK.
In the Enter a name for this Network Place box, type a name, then click Finish.

A new network place is created and Collaboration is mapped on Windows Explorer.

Copy the URL in the Web Folder Location box.
Open My Network Places on your desktop.
Double-click Add Network Place. The Add Network Place Wizard appears.
Click Next.
Select Choose another network location.
In the Internet or network address box, paste the URL, then click Next.
If prompted, enter your name and password, then click OK.
In the Type a name for this network place box, type a name, then click Finish.

A new network place is created and Collaboration is mapped on Windows Explorer.

Copy the URL in the Web Folder Location box.
Open My Network Places on your desktop.
Double-click Add Network Place. The Add Network Place Wizard appears.
Click Next.
Select Choose another network location.
In the Internet or network address box, paste the URL, then click Next.
If prompted, enter your name and password, then click Next.
In the Type a name for this network place box, type a name, then click Next.
Click Finish.

A new network place is created and Collaboration is mapped on Windows Explorer.

Working with Web Folder Configuration File Settings

This section explains the configuration file settings for the Web Folder feature.

Table 5-1 config.xml Nodes for Web Folder Feature

Node

Description

fullWebDAVAccessToThisServer

Enables or disables the use of WebDAV. Valid values are:

yes: Causes Collaboration to accept WebDAV requests. This is the default.
no: Causes Collaboration to reject WebDAV requests.

requestsAreGatewayed

Enables or disables WebDAV communication between Windows Explorer and Collaboration. Valid values are true and false.

uiDisplaysServerConfigInfo

Controls how Collaboration displays the New | Web Folder dialog in the Documents tab. Valid values are:

yes: Displays the Web Folder dialog box. This is the default.
no: Does not display the Web Folder dialog box.

useNonGatewayedURL

Determines whether the Web Folder dialog box displays instructions for mapping a gatewayed network drive.

Valid values are:

no: Cause the Web Folder dialog to display information for mapping between Windows Explorer and Collaboration through the gateway. This is the default.

yes: Causes the Web Folder dialog to display information for mapping directly between Windows Explorer and Collaboration.

Note:

If the connection between Windows Explorer and Collaboration is gatewayed, this instance of Collaboration continues to function as the WebDAV service. Therefore, this instance of config.xml must have fullWebDAVAccessToThisServer.enabled set to true and fullWebDAVAccessToThisServer.requestsAreGatewayed set to true.

serverURL

Provides the base URL to Collaboration that acts as the WebDAV service if Collaboration is configured to communicate directly with Windows Explorer.

Configuring WebEdit

WebEdit lets Collaboration users directly edit Microsoft Office documents on their desktop. Users can edit a document directly without having to explicitly check-out and download the document to their machine. Collaboration handles the process of checkouts and security.

Users must be running Microsoft Internet Explorer 5.0 or later. The following types of documents are supported by WebEdit:

Using IIS with WebEdit

If you are using the WebEdit feature when the portal is running IIS, you must ensure the Front Page server extensions are disabled on the IIS Web site where the portal is deployed.

Choose Start | Programs | Administrative Tools | Internet Service Manager.
Right-click on the Web site used by the portal.
Select Properties.
Select the Server Extensions tab.

If you receive a message stating that the server has not been configured to use server extensions, then IIS is configured correctly.

If the Enable authoring checkbox exists, ensure that it is not checked.

Working with WebEdit Configuration File Settings

config.xml

Table 5-2 config.xml Nodes for WebEdit Feature

Node or Attribute

Description

webEdit

Enables or disables WebEdit. Valid values are yes and no.

nonGatewayedAccess

Determines if HTTP communication between Microsoft Office and Collaboration is gatewayed through the portal. Valid values are:

yes: HTTP communication is gatewayed through the portal. This is the default.

no: HTTP communication is not gatewayed through the portal.

serverURL

The base URL Microsoft Word uses to communicate with Collaboration. This attribute is used if enable is set to true.

Example: http://collab.myco.com:8080/collabserver

tokenBasedAuthentication

Determines if token-based authentication is used. In a normal Collaboration implementation, there is no need to change these values. Valid values are:

true: Enables token-based authentication. This is the default.

false: Disables token-based authentication. This setting can only be used when HTTP communication is gatewayed and some other authentication method is being used.

useClustering

Controls the use of message clustering with token-based authentication. Valid values are:

yes: Enables message clustering. This is the default.

no: Disables message clustering. This setting should only be used when message clustering is not required and would degrade performance.

Note:

This setting has no effect if general clustering functionality has been disabled for Collaboration. Therefore we recommend that you enable useClustering at all times.

maxWaitSeconds

Determines how long Collaboration waits for a response from other servers in the cluster. This setting is applicable only if token-based authentication and message clustering are enabled.

Default: 30

truncateFileNames

The number of characters that are allowed in the file name displayed in WebDAV before the characters are truncated.

clsid

Specifies the class ID of the COM object.

Note:

This value should not be modified.

fileSpec

Specifies the name of the distribution file and information about the component.

Note:

This value should not be modified unless a more recent version of the object needs to be deployed.

installOfficeToolsPopUp enabled

Enables or disables the Collaboration Office Tools Add-In installer. Valid values are yes and no.

filetypes.xml

Table 5-3 filetypes.xml Nodes
Node or Attribute	Description
webEdit	Specifies whether this type of file is WebEditable. Unless serious modifications are made to the code, only Microsoft Office applications are WebEditable. Valid values are yes and no.
appCode	Represents the application that opens the document in a WebEdit session. Valid values are: 1 (for Microsoft Word) 2 (for Micrsoft Excel) 3 (for Micrsoft PowerPoint)

Integrating Collaboration and Groupware

Collaboration lets you integrate back-end groupware servers. The Groupware Integration feature lets users:

Back-end groupware connections are configured by Collaboration administrators. If no groupware server is configured, no Groupware Integration functionality is available to end users.

Performing Basic Groupware Integration Tasks

This section describes the basic configuration required for enabling groupware integration. You must:

Edit config.xml

Note:

After initial product installation, you should disable groupware integration in config.xml if you are going to wait to configure your back-end servers. This prevents the integration-related graphical user interface elements from appearing to end users.

You must configure the following fields in config.xml to enable groupware integration:

groupware.enabled
groupware.type
groupware.soapServerURL

Note:

groupware.soapServerURL is applicable only to Microsoft Exchange.

For more information on these fields and config.xml, see Working With Auto-Synchronization. If you chose to integrate groupware during installation, these fields were configured by the Collaboration installer.

Configure a groupware server

Log in to the portal.
Click the Administration tab.
Select the Collaboration Administration utility.
Click Groupware Servers.
Click Add Server.
Enter the configuration information

If you are using Microsoft Exchange, enter the following:

Table 5-4 Collaboration Administration Microsoft Exchange Integration Values

Node or Attribute

Description

Server Name/IP/URL

The server name, IP address, or URL of the groupware server.

Note:

If you are upgrading Collaboration, you should use the value of the serverURL element in the 3.x version of the configuration file and add the http:// protocol prefix.

Example: http://mail.company.com/exchange

Alias

An optional descriptive name for this groupware server.

If you are using Lotus Domino, enter the following:

Table 5-5 Collaboration Administration Lotus Domino Integration Values
Node or Attribute	Description
Server Name/IP/URL	The server name, IP address, or URL of the groupware server. Example: http://mail.company.com/notes
Alias	An optional descriptive name for this groupware server, which will be available to end users. Example: MyCompany Notes Server
Server Port	If your server port number is other than 80, type a port number; otherwise leave this blank.
Proxy Host/Firewall Port	If you are using a proxy server or a firewall, type the host name; otherwise leave this blank.
Use SSL	If you are using https, select the check box.
HTTPS Port	If you are using an https port number other than 443, type the port number; otherwise leave this blank.
Session Based Authentication	If you are using form-based authentication (cookies), select this; if you are using basic authentication, clear the check box.
Notes Server Temp Dir	Type the local directory of the Lotus Domino server that temporarily stores new attachment files. Example: C:\Temp
Notes Server Temp UNC	Type the UNC path of the directory of the Lotus Domino server that stores the attachments. This should be the same directory as in the Notes Server Temp Dir. For example: \\<Lotus Domino server name>\<folder name>.

User account setup

In order to use groupware integration, each user must perform the following steps to configure their account:

Log-in to the portal.
Click My Account.
Click Collaboration Settings.
Click Calendar Synchronization.
Enter the required account information.
Click Finish.

Working With Auto-Synchronization

Collaboration can perform automatic synchronization between groupware and Collaboration calendars for individual users. When groupware appointments are imported or calendar items are exported, Collaboration creates a link between them and updates the entries on the groupware server if they are different from the Collaboration calendar entries.

Users can manually synchronize the groupware and calendar entries using the Synchronize button on the calendar toolbar. Collaboration administrators can also enable automatic synchronization by setting the calendarAutoSynch element to yes. After this feature is enabled, users can specify which calendar items are auto-synchronized from the My Account page.

When automatic synchronization is enabled, Collaboration runs a nightly process to update the specified entries for each user.

Limiting Attachment Size

Collaboration administrators can set a size limit on the attachments each appointment or meeting request can have. This limit applies to the total size of all attachments, not individual attachments. When the total size of the attachments exceeds the size limit, a warning is displayed and the upload process is canceled.

Working with Configuration File Settings for Groupware Integration

This section describes the configuration file settings for groupware integration contained in config.xml.

Table 5-6 config.xml Nodes for Groupware Integration

Node or Attribute

Description

groupware

This node is used to configure groupware integration. Valid values are:

yes: Enables groupware integration.

no: Disables groupware integration. If this setting is used, all other settings in this section are ignored.

type

Indicates the type of back-end server used. Valid values are:

notes: Enables the Lotus Domino groupware server.

exchange: Enables Microsoft Exchange groupware server.

soapServerURL

Specifies the SOAP server URL specified during Collaboration installation.

timeoutInMilliSecond

Specifies the amount of time, in milliseconds, that Collaboration waits for responses from the SOAP server. If the SOAP server does not respond in this amount of time, the current operation is aborted and an exception is returned.

Note:

Due to the performance constraints and the fact that large attachments might be transferred between Collaboration via Exchange, the attribute should be set to a value greater than 10000 (10 seconds).

calendarCachePeriod

Specifies the cache time-out period, in seconds, for groupware items on the My Calendar portlet. When the My Calendar portlet is refreshed, Collaboration checks if the current items have timed out. If they have, Collaboration retrieves the entries from the back-end server. Otherwise, the entries are retrieved from memory.

addressBookReturn

The maximum number of returned addresses from the address search operation.

maxAttachmentSizeinKB

The maximum attachment file size, in kilobytes, that a meeting request or appointment can contain.

Note:

This limit is the total file size of all attachments an item can have.

calendarAutoSynch

The following values are supported:

yes: Enables automatic synchronization between a user's project calendar and their Exchange or Notes calendar.

no: Disables automatic synchronization between a user's project calendar and their Exchange or Notes calendar.

month.Range

The range of months auto-synchronization covers, starting from the current month.

This node is used to configure settings to let users send an e-mail directly to a project from their groupware.

Integrating Collaboration and Instant Messaging

This section describes the configuration file settings for instant messaging integration in config.xml.

Table 5-7 config.xml Nodes for Instant Messaging Integration
Node or Attribute	Description
instant-messaging enabled	This node is used to enable instant messaging.
presence-url	This node returns an image to indicate whether the user is online or not.
send-url	This node includes the URL from which messages are sent. The $user variable includes the e-mail address of the individual user.
contact-url	This node includes the URL at which messages can be received. The $user variable includes the e-mail address of the individual user.
presence-poll-interval	This node includes the number of seconds between presence polls.

Setting Up the IM Handle Property

If your users are required to have an IM handle value that is different than their e-mail address, follow this procedure to create the IM Handle property and add the property to the portal's General Information page for each user profile. After you have added this property, you can add each user's IM handle to their user profile; you can also have each user perform this task on their own.

Log in to the portal as the Administrator.
Navigate to Administration | Administrative Resources Folder. Then, from the Create Object drop-down list, choose Property.
On the Main Settings page, leave the default values and selections.
Click Finish.
The Save Object dialog box appears.
Make sure that the Administrative Resources folder is selected and name the object IM Handle.
Click Save.
Click Close.
You are returned to the Administrative Resources folder.
From the Select Utility drop-down list, choose Global Object Property Map.
On the Main Page, click Edit for the User object.
In the Choose Property dialog box, select the IM Handle property, then click OK.
You are returned to the Main Page.
Click Finish.
From the Select Utility drop-down list, choose User Profile Manager.
Under Edit Object Settings, click the User Information - Property Map link.
If the IMUser user information attribute is assigned to the Email Address property, perform the following in sequence:

Click Edit for the property
Delete IMUser, along with the comma that precedes it

Do not delete any other user information attributes that are assigned to the Email Address property.

Click Edit for the Email Address property to return it to a non-editable state

Click Add.
In the Choose Property dialog box, select the IM Handle property, then click OK.
You are returned to the User Information - Property Map page.
Click Edit for the IM Handle property.
Delete IMHandle, then replace it with IMUser.
Click Edit for the IM Handle property to return it to a non-editable state.
Click Finish.
Navigate to Administration | Portal Resources Folder.
Click the Portlet link.
Click the General Information portlet link.
In the Edit Portlet: General Information page, click Edit.
The User Profile Portlet Configuration dialog box appears.
Click Add Property.
Select the IM Handle property name, then click OK.
You are returned to the User Profile Portlet Configuration dialog box.
Click Finish.
You are returned to the Edit Portlet: General Information page.
Click Finish.
You are returned to the Portal Resources Folder. The IM Handle property is added to the portal's user profile, General Information page.

Configuring Microsoft Project Import

The following configuration parameters can be set to customize Microsoft Project imports:

Table 5-8 Configuration Parameters for Customizing Microsoft Project Imports
Node or Attribute	Description
project-import	Contains parameters that are specific to Microsoft Project import.
number-of-tasks-limit	The total number of tasks allowed in an import. The default is 1000.

Configuring E-mail a Project

This section describes how to configure the E-mail a Project feature. The E-mail a Project feature lets users:

The "Relaying E-mail to Collaboration" section provides an example of configuring sendmail on a Linux machine that is also running Collaboration. You can use this example as a guideline for configuring your mail host if it is running on the same machine as Collaboration.

Performing a Basic Configuration

This section discusses how to configure E-mail a Project if you are running your mail host and Collaboration on separate machines.

An IT or network operations employee at your organization needs to add a DNS MX (mail exchange) record that points to Collaboration
The users' e-mail address must be registered in their portal user profile

Either the administrator or user can perform this task. The e-mail address in the portal user profile must exactly match the user's e-mail address; this is case-sensitive.

Optional: If you do not want to use the default values, you can configure the following nodes in the email section of config.xml:

Table 5-9 config.xml Nodes for E-mail a Project Configuration
Node	Description
domain	The e-mail domain. For example: mail.buttercut.plumimap.com Most likely, you configured this node when you ran the Collaboration Installer.
connection-pool	The number of socket handlers for incoming connections. The default value is 10.
mail-processors	The number of threads devoted to processing incoming e-mails. The default value is 5.
maximum-message-size	The maximum size of incoming e-mails. -1 indicates that Collaboration does not perform size checks. When this is the case, the Collaboration API enforces size limits for message bodies and files. The default value is -1.
authorized-connections	The names or IP addresses of hosts, in a comma-delimited format, that are allowed to connect to the SMTP handler. We recommend creating this list of names to enforce security. See the config.xml file for an example of this list. The default value is *, which indicates no limit.
idle-timeout	The time (in minutes) that an incoming connection can remain idle. The default value is 20.

Example: Relaying E-mail to Collaboration

If you are running your e-mail host on the same machine as Collaboration, you need to configure your e-mail host to relay e-mail to Collaboration. This section provides an example of configuring sendmail to relay e-mail to Collaboration, which you can use as a guideline for configuring your own e-mail host.

In this example, Collaboration uses port 2525 (by default, Collaboration uses port 25, which is the same port that sendmail uses. For this reason, Collaboration's port must be changed.)

Prerequisites

These prerequisites provide an example of the tasks that should be completed before configuring sendmail.

The sendmail-cf rpm package must be installed. To determine if it is installed, run the following as root:

rpm -qa | grep sendmail

The return should appear as follows:

sendmail-8.12.11-4.RHEL3.1

sendmail-cf-8.12.11-4.RHEL3.1

Create a subzone/subdomain under your current domain. For example, collabmail.yourcompany.com.
Create a host entry that points to your Collaboration server.

MX    10    mail.collabmail.yourcompany.com

Create a MX (mail exchange) record so that anything that gets sent to *@collabmail.yourcompany.com goes to the host record that you just created:

MX    10    mail.collabmail.yourcompany.com

The value 10 in the above example represents the priority that allows you to have more MX records. It assures that e-mails go to the higher priority first.

Note:

An alternative to Step 2 (above) is to specify mx 10 X.X.X.X under your subzone.

Configuring Sendmail

These instructions provide an example for configuring sendmail to relay incoming mail to Collaboration:

Log in as root.
Stop the sendmail processes:

/etc/rc.d/init.d/kudzu stop

/etc/rc.d/init.d/sendmail stop

/etc/rc.d/init.d/apmd stop

Verify file "relay-domains" is in etc/mail.

Add your domain:

[machine].[yourimap].com

For example, collab-x5.plumimap.com.

Edit the etc/mail/access file.

Add the following to the access file:

To: [machine].[yourimap].com    RELAY

To: collab-x5.plumimap.com       RELAY

From your terminal, rehash to update the access.db file:

/usr/sbin/makemap hash /etc/mail/access.db < /etc/mail/access

Edit the sendmail.mc file to relay e-mails to Collaboration using a different port.

/etc/mail/sendmail.mc

Add the following before the MAILER lines at end of the file:

FEATURE(`mailertable')

define(`confRELAY_MAILER', `esmtp')

define(`RELAY_MAILER_ARGS', `TCP $h 2525')

Look for the following line in the file:

DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

Comment the above line out so that it appears as follows:

dnl  DAEMON_OPTIONS(`Port=smtp,Addr=127.0.0.1, Name=MTA')dnl

In your terminal, type the following:

m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf

Edit the mailertable file as follows.

/etc/mail/mailertable

Add the following to the mailertable file:

[machine].[yourimap].com    relay:mail.[machine].[yourimap].com

For example:

Collab-x5.plumimap.com  relay:mail.[machine].plumimap.com

Then rehash to update the mailertable.db file by typing the following in your terminal:

/usr/sbin/makemap hash /etc/mail/mailertable.db < 
/etc/mail/mailertable

Start sendmail as follows:

/etc/rc.d/init.d/apmd start

/etc/rc.d/init.d/sendmail start

/etc/rc.d/init.d/kudzu start

Edit the Collaboration config.xml file to enable e-mail and to use port 2525:

email enabled="yes" port="2525"

Restart Collaboration.

The collaboration.log file should show the E-mail Service has started on port 2525 with no errors.

A Telnet to the machine port should return something similar to the following:

220 Collaboration 4.1 Build:198844.20050824 0720.0 SMTP Server (Messaging 
Server ) ready Wed, 24 Aug 2005 14:50:36 -0700 (PDT)

Working With Collaboration E-mail Errors

If Collaboration is down, the mail server queues the e-mail and attempts redelivery a few times before quitting. Collaboration sends an error e-mail to the user who sent the e-mail, then redelivers the e-mail when Collaboration is back up.