CollabraSuite
®
Developer Guide
Copyright
Copyright © 2000-2008 CollabraSpace, Inc. All Rights Reserved.
Restricted Rights Legend
This software is protected by copyright, and may be protected by patent laws. No copying or other use of this software is permitted unless you have entered into a license agreement with CollabraSpace authorizing such use. This document is protected by copyright and may not be copied photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form, in whole or in part, without prior consent, in writing, from CollabraSpace, Inc.
Information in this document is subject to change without notice and does not represent a commitment on the part of CollabraSpace. THE DOCUMENTATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, COLLABRASPACE DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE DOCUMENT IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.
Contents
Overview
Single Sign On . . . . 1-1 Two way SSL Authentication . . . 1-2 Single Application Server Deployment . . . 1-2 Multiple Application Server Deployment. . . 1-2
Web Applications
Using Hyperlinks . . . 2-1 Using IFrames . . . . 2-2 Using the JavaScript API . . . 2-3
MediaWiki Integration
Prerequisites . . . 3-1 Installation . . . 3-1 Troubleshooting . . . 3-2
Appendices
Changing the Authentication Method . . . 4-1 Changing the Session Tracking Cookie Name . . . 4-2 CollabraSuite HTML Page. . . 4-3 User Creation Parameters. . . 4-3 Login Parameters . . . 4-4 Components . . . . 4-5
C H A P T E R
1
Overview
An effective collaborative environment not only brings people together, it provides seamless access to important data by tightly integrating with other business critical systems. CollabraSuite components can be integrated into existing applications using a variety of techniques. CollabraSuite can be integrated into web applications using hyperlinks, iframes or the CollabraSuite JSP tag library. CollabraSuite ships with JSR-168 compliant portlets for integrating into portal applications such as WebLogic Portal. CollabraSuite portlets support Web Services for Remote Portlets (WSRP) in order to support federated portal environments. CollabraSuite also ships with remote portlets for use with WebCenter Interaction. CollabraSuite can be integrated into Wiki environments such as Media Wiki with the CollabraSuite Media Wiki Extension. Applications deployed using the Eclipse Rich Client Platform (RCP) can be enhanced with CollabraSuite functionality with the CollabraSuite Eclipse Plugin. Finally,
CollabraSuite can be integrated with other enterprise services via the CollabraSuite Integration API.
Single Sign On
Regardless of the strategy used to integrate CollabraSuite with an existing web application, it is usually desirable to achieve single sign on (SSO) between CollabraSuite and the web application so end users are not required to login twice. There are several architecture decisions that affect how single sign on should be implemented. For example, whether both applications deployed into the same or different application servers; what authentication mechanism is being used; or if perimeter authentication has been implemented by a third party SSO provider.
O v e r v i e w
Two way SSL Authentication
When using SSL with two way authentication, the client browser is asked to present the user’s certificate in order to authenticate the user. In this case, the browser can automatically present the certificate to both applications, relieving the user of having login separately to each application. In this case, CollabraSuite must be modified to use the CLIENT-CERT authentication method as described in the Changing the
Authentication Method appendix.
Single Application Server Deployment
When CollabraSuite and the web application are deployed into the same application server or into a homogeneous cluster of application servers using BASIC or FORM based authentication, both applications must use the same session tracking cookie name. CollabraSuite uses the default name of JSESSIONID, and if the web application uses this same default value, nothing else has to be configured. Once the user has been authenticated with one of the web applications, they will automatically be considered authenticated with the other application. Refer to the Changing the Session Tracking Cookie Name appendix for details on changing the cookie name used by CollabraSuite.
Multiple Application Server Deployment
When CollabraSuite and the web application are deployed into different application servers or into a heterogeneous cluster of application servers, then perimeter
authentication must be provided by a third party SSO provider such as CA SiteMinder or RSA AccessManager. To support this configuration, the session tracking cookie name must be changed so that CollabraSuite and the web application use different cookie names. Because there are two application servers involved, they will each use their own HTTP cookie for session tracking. If the cookies have the same name, they will interfere with each other. Refer to the Changing the Session Tracking Cookie Name appendix for details on changing the cookie name used by CollabraSuite. In order to support perimeter authentication, CollabraSuite must also be modified to use the CLIENT-CERT authentication method as described in the Changing the Authentication Method
C H A P T E R
2
Web Applications
CollabraSuite can be integrated into existing web applications in a variety of ways. An application can simply link to one of the supplied HTML pages using hyperlinks. Another strategy is to use iframes that point to either a custom page or to one of the pages delivered with the product. Yet another strategy is to use the CollabraSuite JSP tag library to embed collaboration components directly in a web page.
Note: Regardless of the technique used to integrate CollabraSuite, an end user may only have one page containing CollabraSuite components open at a time. This does not include any popup pages opened through CollabraSuite itself.
Using Hyperlinks
The easiest form of integration is simply linking to the predefined HTML page. For example:
<a href="http://host:port/csuite/ui/client/component.jsp? campus=SampleCampus&component=Workplace&toolbar=true" target="CSWorkplace">
CollabraSuite Workplace</a>
The available components are listed in the Components appendix. Any additional parameters listed in the Login Parameters and User Creation Parameters appendices may also be specified.
Advantages
W e b A p p l i c a t i o n s
z Only minor changes required to an existing application.
Limitations
z This is a very loose form of integration.
z Users are not in the collaborative environment unless they explicitly click on the
hyperlink to open the page.
z Collaborative components appear in a separate page instead of appearing directly
on the page along with other relevant information.
Using IFrames
This is still a simple form of integration, and with the proper styling, the iframe is nearly undetectable to the user. To use an iframe, place it in the web page as desired and point the iframe’s source attribute to the predefined CollabraSuite HTML page. For example:
<iframe src="http://host:port/csuite/ui/client/component.jsp? campus=SampleCampus&component=Workplace&toolbar=true"
style="width:100%; height:400px; border:0px;" frameborder="0"> <p>Your browser does not support iframes.</p>
</iframe>
The available components are listed in the Components appendix. Any additional parameters listed in the Login Parameters and User Creation Parameters appendices may also be specified.
Advantages
z Ease of implementation.
z Only minor changes required to an existing application.
z The CollabraSuite content appears in-line with other relevant information.
Limitations
z Not everyone wants to use iframes.
z CollabraSuite content such as dialog boxes and context menus are limited to the
boundary of the iframe.
U s i n g t h e J a v a S c r i p t A P I
z Popup windows opened from within iframes can't remain open when the main
page is reloaded. Popup windows opened from the top level window will remain open during a main page refresh and will remain connected to the server.
Using the JavaScript API
CollabraSuite provides a JavaScript API that allows developers to easily embed CollabraSuite components directly into their web pages. To use the API, developers must first include the following line in their web pages:
<script type="text/javascript"
src="http://host:port/csuite/ui/boot.jsp"></script>
Developers can then use the CollabraSuite JavaScript API to login, logout and place UI components on the page.
Logging In
The login method logs the user into the CollabraSuite environment so they appear online to other users without rendering any CollabraSuite UI components. After the login method executes; users are available to receive collaborative events such as Sidebar sessions. This method is only necessary if no other UI components are to be displayed on the page.
csuite.login({
campus: 'SampleCampus' // The campus name (required)
});
For a complete list of parameters to the login method, refer to the Component Login Parameters appendix.
Logging Out
The logout method logs the user out of the CollabraSuite environment so they appear offline to other users. After the logout method executes; users will no longer receive collaborative events.
W e b A p p l i c a t i o n s
Creating UI Components
Developers can place multiple CollabraSuite UI components on a page using the create method. HTML DIV elements and CSS can be used to arrange the components on the page together with existing content.
<script rel="CollabraSuite"> csuite.create({
campus: 'SampleCampus' component: {
xtype: csuite.types.Workplace }
}); </script>
Where xtype is one of the components listed in the Components appendix with a prefix of csuite.types. For a full list of the create method parameters refer to the Login Parameters and Component Parameters appendices.
Advantages
z The CollabraSuite content is embedded in-line with other relevant information
Limitations
C H A P T E R
3
MediaWiki Integration
CollabraSuite provides a MediaWiki extension to embed CollabraSuite components within a wiki page by simply using the wiki extension tags defined in the CollabraSuite MediaWiki extension. A sample for adding a CollabraSuite chat component to a wiki page would be:
<CollabraSuite component=”Chat”/>
Prerequisites
The following prerequisites must be satisfied before installing CollabraSuite MediaWiki extension.
z A MediaWiki distribution is installed, configured and working properly. Detailed
instructions can be found on the mediawiki website (http://www.mediawiki.org/).
z A CollabraSuite instance is deployed and running.
z The CollabraSuite instance is reachable via http://host:port/csuite/ui.
z Although not required, knowledge of PHP is useful.
Installation
1. Copy the CollabraSuite.php script to
<mediawiki-dir>/extensions/CollabraSuite/CollabraSuite.php
2. Edit the <mediawiki-dir>/LocalSettings.php script and add the following lines to the end of the file:
M e d i a W i k i I n t e g r a t i o n
require_once("$IP/extensions/CollabraSuite/CollabraSuite.php"); $wgCollabraSuiteServerUrl = "http://host:port";
$wgCollabraSuiteCampus = "CampusName";
Note: Host and port above indicate where CollabraSuite is installed and
CampusName is the name of the desired campus within the CollabraSuite environment.
3. Remember to remove or comment out the loading of any previous versions of the CollabraSuite MediaWiki extension.
4. Restart the web server hosting the MediaWiki application.
5. Create a new or modify an existing wiki page and add the following tag to verify the extension is working properly:
<CollabraSuite/>
6. CollabraSuite should load in the page.
7. Copy the text in the /MediaWiki/CollabraSuite-wiki.txt file found in the CollabraSuite installation into a wiki page to describe the capabilities and tag attributes to your wiki community.
Troubleshooting
1. The page loads but reports an error that "Campus <some campus name> does not exist.".
– The default campus defined in the LocalSettings.php script or the campus attribute used in the CollabraSuite tag is incorrect.
2. The page does not load but the browser appears to have completed loading the page.
– This is an indication that there is an error in the PHP script. View the apache or IIS error log and correct the error reported. This often happens whenever the attributes defined in the CollabraSuite PHP script contain a syntax error.
C H A P T E R
4
Appendices
Changing the Authentication Method
The J2EE specification defines four methods for controlling how users supply authentication credentials. Those methods are BASIC, DIGEST, FORM and CLIENT-CERT. By default, CollabraSuite supports the BASIC and CLIENT-CERT authentication methods. The following steps should be taken in order to change the authentication method used by CollabraSuite:
1. Extract the web applications from the ear:
> jar -xvf CollabraSuite.ear csuite-client-webapp.war csuite-ui-webapp.war
2. Extract the web.xml file from csuite-client-webapp.war: > jar -xvf csuite-client-webapp.war WEB-INF/web.xml 3. Edit web.xml and change:
<login-config>
<auth-method>BASIC,CLIENT-CERT</auth-method> <realm-name>default</realm-name>
</login-config> 4. Repackage the war:
> jar -uvf csuite-client-webapp.war WEB-INF/web.xml 5. Extract the web.xml file from csuite-ui-webapp.war:
A p p e n d i c e s
> jar -xvf csuite-ui-webapp.war WEB-INF/web.xml 6. Edit web.xml and change:
<login-config>
<auth-method>BASIC,CLIENT-CERT</auth-method> <realm-name>default</realm-name>
</login-config> 7. Repackage the war:
> jar -uvf csuite-ui-webapp.war WEB-INF/web.xml 8. Repackage the CollabraSuite.ear file:
> jar -uvf CollabraSuite.ear csuite-client-webapp.war csuite-ui-webapp.war
9. Redeploy the CollabraSuite.ear file.
Changing the Session Tracking Cookie Name
Because HTTP is a stateless protocol, an HTTP cookie is often used by application servers to maintain a user’s session. CollabraSuite ships using the default cookie name of JSESSIONID. The following steps should be taken in order to change the session tracking cookie name used by CollabraSuite:
1. Extract the web applications from the ear:
> jar -xvf CollabraSuite.ear csuite-client-webapp.war csuite-ui-webapp.war
2. Extract the weblogic.xml file from csuite-client-webapp.war: > jar -xvf csuite-client-webapp.war WEB-INF/weblogic.xml 3. Edit weblogic.xml and add:
<wls:session-descriptor>
<wls:cookie-name>CSJSESSIONID</wls:cookie-name> <wls:cookie-path>/</wls:cookie-path>
</wls:session-descriptor>
4. Repackage csuite-client-webapp.war:
C o l l a b r a S u i t e H T M L P a g e
5. Extract the weblogic.xml file from csuite-ui-webapp.war: > jar -xvf csuite-ui-webapp.war WEB-INF/weblogic.xml 6. Edit weblogic.xml and add:
<wls:session-descriptor>
<wls:cookie-name>CSJSESSIONID</wls:cookie-name> <wls:cookie-path>/</wls:cookie-path>
</wls:session-descriptor> 7. Repackage csuite-ui-webapp.war:
> jar -uvf csuite-ui-webapp.war WEB-INF/web.xml 8. Repackage the CollabraSuite.ear file:
> jar -uvf CollabraSuite.ear csuite-client-webapp.war csuite-ui-webapp.war
9. Redeploy the CollabraSuite.ear file.
CollabraSuite HTML Page
CollabraSuite includes a web page which can be used to provide specific CollabraSuite functionality. The page can display any predefined CollabraSuite component and also includes parameters used to configure the components. The pages can be accessed via http://host:port/csuite/ui/client/component.jsp.
Additional parameters may be specified on the URL to configure the components. Below is a list of components available, along with the names, descriptions and default values for their configuration parameters. Required parameters are listed in bold.
User Creation Parameters
The following parameters can be passed to the component.jsp page to dynamically create or update a CollabraSuite user’s information:
A p p e n d i c e s
Note: This requires Auto Account Creation to be enabled on the campus. See the
CollabraSuite Administration Guide for details.
Login Parameters
The following parameters may be specified on the components.jsp page as well as used by the JavaScript csuite.login() method. Bold fields are required.
Name Description Default
Value
createUser Dynamically create the user if they don’t already exist false
updateUser Dynamically update the user’s info when they login false
loginId The user’s login ID None
name The user’s full name None
campus The name of the user’s campus None
building The name of the user’s home building None
floor The name of the user’s home floor None
room The name of the user’s home room None
emailAddress The user’s email address None
workPhone The user’s work phone number None
cellPhone The user’s cell phone number None
homePhone The user’s home phone number None
organization The user’s organization None
Name Description Default
Value
campus The name of the user’s campus None
C o m p o n e n t s
Components
The following components may be specified on the components.jsp page as well as used by the JavaScript csuite.create() method.
debug Use uncompressed JavaScript and CSS code for
debugging
false
floor The name of the floor to enter None
room The name of the room to enter None
session The name of the session the components belong to default
Name Description Default
Value
Name Description
ActiveSessions The ActiveSessions component
Admin The Administration component
AdminDetail Administration component without tree navigation
Alerts The Alerts component
Associates The Associates component
Briefcase The Briefcase component
Chat The Chat Monitor and Chat Input components
ChatInput The ChatInput component
ChatMonitor The ChatMonitor component
FileCabinet The FileCabinet component
Navigator The Navigator component
OccupantsChat The Occupants and Chat components
A p p e n d i c e s
Component Parameters
The following parameters are common to all of the components:
OnlineUsersLite The OnlineUsers component that displays only the user
name.
PageComposer The PageComposer component
PageViewer The PageViewer component
Presenter The Presenter component
Presentation The RoomOccupants, Presenter and Chat components
RecallSession The RecallSession component
Reports The Reporting component
RoomContributors The RoomContributors component
RoomOccupants The RoomOccupants component
SessionMonitor The SessionMonitor component
Suggestions The Suggestions component
Toolbar The Toolbar component
ToolbarLite The pulldown toolbar component
Whiteboard The Whiteboard component
Workplace The Toolbar, RoomOccupants, RoomContributors, Chat,
FileCabinet and Briefcase components
Name Description
Name Description Default
Value
enableApplet Enable a Java applet for certain operations true
C o m p o n e n t P a r a m e t e r s
building The name of the building to enter None
debug Use uncompressed code for debugging false
enableBrowserPopups Enable content to be displayed in new browser windows
true
floor The name of the floor to enter None
height The height of the component in pixels None
room The name of the room to enter None
session The name of the session the components belong to default
showActiveSessions Display the Active Sessions button in the toolbar true
showAdmin Display the Admin button in the toolbar true
showAlerts Display the Alerts button in the toolbar true
showAssociates Display the Associates button in the toolbar true
showBriefcase Display the Briefcase button in the toolbar true
showChat Display the Chat button in the toolbar true
showConference Display the Audio/Video Conference button in the
toolbar
true
showFileCabinet Display the FileCabinet button in the toolbar true
showHelp Display the Help button in the toolbar true
showInviteUser Display the Invite User button in the toolbar true
showNavigator Display the Navigator button in the toolbar true
showOnlineUsers Display the OnlineUsers button in the toolbar true
showPageViewer Display the Page Viewer button in the toolbar true
showPageUser Display the PageUser button in the toolbar true
showPhoneUser Dislpay the Phone User button in the toolbar true
Name Description Default
A p p e n d i c e s
showPreferences Display the Preferences button in the toolbar true
showPresenceState Display the Presence State button in the toolbar true
showPresenter Display the Presenter button in the toolbar true
showPriority Enable priority in chat and page messages true
showRecallSession Display the Recall Session button in the toolbar true
showReports Display the Reports button in the toolbar true
showRoomLock Display the RoomLock button in the toolbar true
showRoomOccupants Display the RoomOccupants button in the toolbar true
showSessionMonitor Display the Session Monitor button in the toolbar true
showSidebarUser Display the SidebarUser button in the toolbar true
showUserIcons Display custom icons for users in various components true
showUserProfile Display the UserProfile button in the toolbar true
showVideoTransmit Display the Video Transmit button in the toolbar true
showWhiteboard Display the Whiteboard button in the toolbar true
theme The theme used to render components. Available
themes are “blue”, “gray” and “access”
blue
toolbar Display a toolbar above the component false
width The width of the component in pixels None
Name Description Default
