IBM Connections 4: Customize, Security, Performance, and Integration
- Customize
- User interface customization
- Customization best practices
- Customize the user interface
- Customize the navigation bar
- Customize images
- Add styles to the IBM Connections stylesheet
- Making extensive color and style changes
- Customize the login page
- Customize the footer
- Customize the error page
- Customize the Get Started view
- Customize product strings
- Overriding and extending JavaScript in IBM Connections
- Extend JSP files with custom tags
- Customize notifications
- Customize a blog theme
- Add a custom theme to Communities
- Use Profiles and Communities business cards
- Customize Profiles
- Add new ways to share content
- Required post-customization step
- Customize Metrics reports
- Security
- Allow third-party applications access to data via the OAuth2 protocol
- Enable virus scanning
- Forcing users to log in before they can access an application
- Configure single sign-on
- Set the single sign-on domain name
- Enable single sign-on for Tivoli Access Manager
- Enable single sign-on for SiteMinder
- Enable single sign-on for Lotus Quickr
- Enable single sign-on for Domino
- Enable single sign-on for standalone LDAP
- Enable single sign-on for the Windows desktop
- Enable single sign-on for Tivoli Access Manager with SPNEGO
- Enable single sign-on for SiteMinder with SPNEGO
- The customAuthenticator element for back-end inter-service communication
- Configure the AJAX proxy
- Securing applications from malicious attack
- Forcing traffic to be sent over SSL
- Performance
- Integrate with other products
- Install plug-ins to use IBM Connections in other applications
- IBM Connections Plug-in for IBM Sametime
- IBM Connections Portlets for WebSphere Portal
- What's New in the IBM Connections Portlets for WebSphere Portal
- Deploying the IBM Connections portlets
- Configure the resource environment provider
- Configure the DynaCache
- Set up an authentication alias for the portlets
- Configure portlets to use common directory services
- Import a certificate to support SSL
- Configure authentication for the portlets
- Enable single sign-on for the portlets using a stand-alone LDAP server
- Configure single sign-on for portlets with TAM and SPNEGO
- Configure single sign-on with TAM
- Configure single sign-on for portlets with Siteminder and SPNEGO
- Configure single sign-on for portlets with SPNEGO
- Change the realm name
- Enable basic authentication
- Update the portlet theme
- Install the IBM Connections Portlets for IBM WebSphere Portal
- Configure the application-specific AJAX proxy to support authentication
- Uninstall the IBM Connections portlets
- Optional and recommended configuration
- Community Pages
- Configure search integration
- Display action buttons and links for anonymous users
- Conditional Loading of the Lotus CSS bundle
- Configure the Connections business card
- Configure links to open Connections in the same browser window
- Enable logging for the portlets
- Pinning portlet content to a tag
- Configure and wiring the Tags portlet
- Addressing IBM Connections content from a portlet
- IBM Connections Business Card
- IBM Connections Desktop Plug-ins for Microsoft Windows
- Performing a user installation
- Performing a silent installation
- Repairing or removing the IBM Connections Desktop plug-ins
- Preferences and policies for the IBM Connections Desktop Plug-ins for Microsoft Windows
- Manage policies and preferences with a group policy
- Configure dynamic feeds for the Outlook Social Connector
- IBM Connections Plug-in for Microsoft SharePoint
- IBM Connections Status Updates Plug-in for Lotus Notes
- IBM Connections Files Plug-in for Lotus Notes
- Install the IBM Connections Files plug-in for Lotus Notes
- Install the Files plug-in on a Windows client
- Silently installing the IBM Connections Files plug-in (Windows)
- Install the Files plug-in on a Mac client
- Silently installing the IBM Connections Files plug-in (Mac)
- Viewing the log files
- Uninstall the IBM Connections Files plug-in
- IBM Lotus Notes Activities sidebar
- Install plug-ins to use other applications in IBM Connections
- IBM Lotus Quickr Library widgets for IBM Connections
- IBM Connections Widget for Microsoft SharePoint
- IBM Connections Connector for Lotus Quickr
- Install the IBM Connections Connector for Lotus Quickr
- Supporting Lotus Quickr authenticated feeds
- Edit the Lotus Quickr configuration file
- Configure roles for Lotus Quickr places
- Enable SSL access to the Lotus Quickr server
- Integrate with SiteMinder and Tivoli Access Manager
- Use the Lotus Quickr Delayed Synchronizer
- Uninstall the Lotus Quickr connector
- Upgrading the Lotus Quickr connector
- Optional: defining a list of supported Lotus Quickr servers for Communities
- Use plug-ins from IBM Connections in other products
- Use the IBM Connections Plug-in for IBM Sametime
- Use the IBM Connections Portlets for WebSphere Portal
- Personalizing a portlet
- The Activities portlet
- The Blogs portlet
- The Blogs Summary portlet
- The Bookmarks portlet
- The Bookmarks Summary portlet
- The Profiles Portlet
- The Profiles Summary portlet
- The Tags portlet
- The Wikis portlet
- The Community Overview portlet
- The Forums portlet
- The Forums Summary portlet
- Use the IBM Connections Desktop Plug-ins for Microsoft Windows
- Connecting to an IBM Connections site
- Use the IBM Connections Plug-in for Microsoft Office
- Add documents to Files
- Add documents to Communities
- Add documents to Activities
- Add documents to Wikis
- Add Word documents to Blogs
- Add IBM Connections profiles to Word documents
- Add IBM Connections bookmarks to Word documents
- Add bookmarks to IBM Connections from Word documents
- Search from Office for IBM Connections content
- Use the IBM Connections Plug-in for Microsoft Outlook
- Viewing IBM Connections user business cards
- Add Outlook emails to Files
- Add Outlook emails to Communities
- Add Outlook emails to Activities
- Add Outlook emails to Wikis
- Add IBM Connections users to Outlook emails
- Search from Outlook for IBM Connections content
- Use IBM Connections with the Outlook Social Connector
- Use the IBM Connections Plug-in for Microsoft Windows Explorer
- Search IBM Connections from Microsoft Office and Outlook
- Set preferences for IBM Connections Plug-ins for Microsoft Windows
- Use the IBM Connections Status Updates Plug-in for Lotus Notes
- Use the IBM Connections Files plug-in for Lotus Notes
- Use the IBM Lotus Notes Activities sidebar
- Use plug-ins from other products with IBM Connections
IBM Connections 4 Part 4: Customize, Security, Performance, and Integration
IBM® Connections 4 Part 4: Customize, Security, Performance, and Integration
Customize
Customize IBM Connections to fit your environment.
- This documentation is provided to help you customize your deployment of IBM Connections. IBM Support can address questions about the customization process, but cannot address questions about the particulars of your customization.
- If you customized a previous release of IBM Connections, note that there is no migration path provided for importing your changes into IBM Connections 4. Any customization work performed at the EAR folder level will be overwritten after you upgrade to a new version of the product. In addition, customization work carried out in the customization directory may no longer be valid if the customized file has been updated in the new fix pack or by applying a later interim fix.
Before upgrading to IBM Connections 4, ensure that you review and make a note of your existing customizations so that you can verify them post-migration and rework if necessary.
User interface customization
You can customize the IBM Connections user interface to meet the needs of your organization.
For information about how to customize specific areas of the user interface, refer to the task-specific topics that are referenced at the end of this topic.
If you customized the IBM Connections user interface in a previous release of the product, note that there is no migration path provided for importing your changes into IBM Connections 4. Before upgrading to IBM Connections 4, review and make a note of your existing customizations so that you can verify them post-migration and rework if necessary.
Customization best practices
Use the following guidelines to help you to implement and manage customizations in your deployment of IBM Connections.
Most of the changes that you make to product files are stored in the customization directory, the location of which is defined by the IBM WebSphere® Application Server variable, CONNECTIONS_CUSTOMIZATION_PATH. It is best practice to make your customization changes within the customization directory only. Changes that cannot be made using the customization directory are known as product modifications.
The type of changes that you can make using the customization directory include:
- Changes to static files, such as images, CSS, HTML, and text files.
- Changes to real files, that is, files that are not generated at runtime and which get served directly to the browser.
- Changes to JSP files using a standard include request, for example, <jsp:include page="myjspfragment.jspf" .../> and <c:import url= myjspfragment.jspf/>.
The following types of change cannot be made using the customization directory:
- Changes to JSP files using the JSP include directive. For example: <%@ include file="myjspfragment.jspf"%>.
- Changes to files within a Java. Archive (JAR) file. For example, adding custom strings to the ui.properties file in the lc.profiles.web.app-3.0.jar archive to customize error messages for field validation.
- Changes to Java classes (Java class files).
- Changes to TAG files. These files are used in the Communities and Forums applications.
- Changes to TLD files.
- Changes to most XML configuration files in the WEB-INF directory. This includes web.xml.
Customization guidelines
- Keep your customization directory under source control to allow you to maintain it and track your changes over time.
- Copy only the resources files to modify to your customization directory. This makes it easier for you to track which files you changed and when.
- Always add comments to your customized files to describe where and why changes were made.
- Use a web inspector to help you to locate the CSS rules that you want to change. For example, Firebug on Mozilla Firefox, Webkit Inspector on Google Chrome or Apple Safari, or Weinre for Mobile.
- Use documented, public APIs where possible.
- Do not modify JSP files inside web modules or JAR files. Instead, use supported extension points where available, for example, for login pages or error pages, and so on.
- Back up the customization directory before a product upgrade:
For more information, see Saving your customizations.
- Rename the customization directory to a temporary name.
- Apply the IBM Connections interim fix or fix pack.
- Verify the functionality.
- Compare the updated files to the customized copy and then merge the changes.
- Change the name of the customization directory back to the original name.
- Test your customizations.
Customize the user interface
The steps that you must perform to customize IBM Connections are the same no matter what part of the product you are customizing. You need to find the relevant source file, save a copy of the file in the appropriate customization directory, edit the file, and then validate your changes.
Start IBM Connections and review the product user interface to determine which areas of the product you want to customize. Use the steps outlined here as a general guide to the process for customizing the product user interface. For additional detail on how to customize specific areas of the user interface, refer to the task-specific topics that are referenced at the end of this topic. For information about best practices to follow when customizing your deployment, see Customization best practices.
The IBM Connections user interface style is based on the IBM Lotus® User Interface Toolkit 3.0.
- Find the file that serves as the source of the area of the product to edit. For a list of the web application source directories and OSGi bundles that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Copy the file to customize and past it into the appropriate customization directory. For more information, see Determining where to save your customizations.
The following table identifies the files that serve as the source for user interface areas that are popular targets for customization. The files are located in the nav folder of the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.warwhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
Table 1. Popular customization areas
Feature File location Cascading stylesheets
- To add custom styles to the product, edit the following files:
If your users view the product in Arabic, Hebrew, or another right-to-left language, copy the defaultTheme_rtl.css file too.
For more information, see Add styles to the IBM Connections stylesheet.
- /nav/common/styles/defaultTheme/custom.css
- /nav/common/styles/defaultTheme/custom_rtl.css
- To make extensive changes to the colors used in the product, edit the following file:
/nav/common/styles/defaultTheme/defaultTheme.cssFor more information, see Making extensive color and style changes.
Error page /nav/templates/error.jsp For more information, see Customize the error page.
Footer /nav/templates/footer.jsp For more information, see Customize the footer.
Login page /nav/templates/login.jsp For more information, see Customize the login page.
Navigation bar /nav/templates/header.jsp For the menus available from the navigation bar:
/nav/templates/menu/people.jsp /nav/templates/menu/communities.jsp /nav/templates/menu/apps.jspFor more information, see Customize the navigation bar.For example:
- To edit the footer and have the same footer be displayed in all of the applications, store the updated footer file in the following directory:
customizationDir/common/nav/templates/footer.jsp
- To change the login page of a single application, store the updated login page file in the directory where customizations that are specific to that application are stored. For example, to change the login page of the Files application only, store the login.jsp file in the files subdirectory instead of the common subdirectory:
customizationDir/files/nav/templates/login.jsp
- Edit the file stored in the customizationDir directory to make your changes.
- Test your changes by refreshing the web browser. You might also need to clear your browser cache to see the changes.
- When you are ready to publish your changes, turn off the customization debugging capability.
- Use the WebSphere Application Server Integrated Solutions Console, stop and restart each application EAR file.
- Force all user web browsers to refresh all cached content and display your changes by running the command that updates the product version stamp. For more information, see Required post-customization step.
What to do next
See the following topics for more information about customizing specific areas of the product.
Determine where to save your customizations
When you are customizing your deployment of IBM Connections, you must save your customized files to the appropriate directory to ensure that your customizations override the default settings. The base directory where you need to store your customizations is defined during installation, when it is saved as an IBM WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. By default, this variable is set to installDir/data/customization. This customization base directory is referenced as customizationDir throughout the documentation
To determine the location of your customization directory, check the value of the CONNECTIONS_CUSTOMIZATION_PATH variable for your deployment. After you have determined the base directory location, you can then identify the subdirectory where you need to save your customizations.
- Log in to the IBM WebSphere Application Server Integrated Solutions Console.
- Expand Environment and select WebSphere variables.
- Look for CONNECTIONS_CUSTOMIZATION_PATH in the list of variable names and make a note of the value. For example, it might look like /local/IBM/Connections/data/shared/customization.
- Save your customized files in the appropriate subdirectory of the customization directory:
- To save customizations that apply to all the applications, copy the file into the common subdirectory:
customizationDir/common
- To save customizations that apply to a single application only, copy the file into the subdirectory for that application:
Table 2. Application-specific customization directories
Directory path Description customizationDir/common Stores files to be applied to all of the applications. You most often copy edited files to this directory. customizationDir/activities Stores files to be applied to the Activities user interface only. customizationDir/blogs Stores files to be applied to the Blogs user interface only. customizationDir/bookmarks Stores files to be applied to the Bookmarks user interface only. customizationDir/communities Stores files to be applied to the Communities user interface only. customizationDir/files Stores files to be applied to the Files user interface only. customizationDir/forums Stores files to be applied to the Forums user interface only. customizationDir/homepage Stores files to be applied to the Home page user interface only. customizationDir/metrics Stores files to be applied to the Metrics page user interface only. customizationDir/moderation Stores files to be applied to the Moderation page user interface only. customizationDir/news Stores files to be applied to the News user interface only. customizationDir/profiles Stores files to be applied to the Profiles user interface only. customizationDir/search Stores files to be applied to the Advanced Search user interface only. customizationDir/wikis Stores files to be applied to the Wikis user interface only. The following table identifies where to store customized versions of files when the customizations apply to all the applications.
Table 3. Directory location for popular customization targets
Directory path Description customizationDir/themes/defaultTheme/custom.css Customized styles customizationDir/themes/defaultTheme/defaultTheme.css Customized themes customizationDir/common/nav/templates/login.jsp Customized login page customizationDir/common/nav/templates/footer.jsp Customized footer file customizationDir/common/nav/templates/error.jsp Customized error page customizationDir/themes/images Customized images The following table identifies where to store application-specific versions of customized CSS files:
Table 4. Directory location for application-specific CSS files
Directory path Description customizationDir/themes/base/applications/activities.css Customized styles for Activities. customizationDir/themes/base/applications/blogs.css Customized styles for Blogs. customizationDir/themes/base/applications/dogear.css Customized styles for Bookmarks. customizationDir/themes/base/applications/bookmarklet.css Customized styles for the Bookmarklet. customizationDir/themes/base/applications/communities.css Customized styles for Communities. customizationDir/themes/base/applications/files.css Customized styles for Files. customizationDir/themes/base/applications/forums.css Customized styles for Forums. customizationDir/themes/base/applications/homepage.css Customized styles for the Home page. customizationDir/themes/base/applications/metrics.css Customized styles for Metrics. customizationDir/themes/base/applications/moderation.css Customized styles for Moderation. customizationDir/themes/base/applications/news.css Customized styles for News. customizationDir/themes/base/applications/profiles.css Customized styles for Profiles. customizationDir/themes/base/applications/wikis.css Customized styles for Wikis.
- For information about where to save customized application properties files, see Property file strings.
- For information about where to save customized JavaScript files, see JavaScript resource strings.
Enable and disable customization debugging
By enabling customization debugging mode, you can force applications to reload override files every time a browser request is made. This capability allows you to see your customization changes in the product instantly.
Do not leave the product in customization debugging mode when you are using it in a production environment. This capability is extremely resource intensive and has a major impact on product performance. Only use debugging mode while you are making and testing changes to the user interface during the testing phase. Ensure that you disable this feature after you have validated your customizations. If you forget to disable customization debugging, an error is written to the log to remind you.
- To turn on the customization debugging capability, add a WebSphere Application Server environment variable named CONNECTIONS_CUSTOMIZATION_DEBUG and set it to true.
- Open the IBM WebSphere Application Server Integrated Solutions Console, expand Environment, and then click WebSphere variables.
- In the Scope section, select cell 1 from the list, and then click New.
- Set the following values into the fields:
- Name
- CONNECTIONS_CUSTOMIZATION_DEBUG
- Value
- true
- Click Apply, and then OK to return to the previous page.
- Restart the server for your changes to take place.
- To disable customization debugging, set the CONNECTIONS_CUSTOMIZATION_DEBUG variable to false.
- Open the Integrated Solutions Console, expand Environment, and then click WebSphere variables.
- In the Scope section, select cell 1 from the list.
- Select CONNECTIONS_CUSTOMIZATION_DEBUG and enter false in the Value field.
- Click Apply, and then click OK.
- Restart the server for your changes to take place.
Application WAR files and OSGi bundles
The following web application directories and OSGi bundles are packaged as part of IBM Connections.
Application WAR files
The default location for the web application directory for each application is:
WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.warwhere:
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is one of the following file names:
Table 5. Application WAR files
File Description oawebui.war WAR file for the Activities application blogs.war WAR file for the Blogs application dogear.webui.war WAR file for the Bookmarks application comm.web.war WAR file for the Communities application files.web.war WAR file for the Files application forum.web.war WAR file for the Forums application homepage.war WAR file for the Home page application lc.metrics.ui.war WAR file for the Metrics application sn.moderation.ui.war WAR file for the Moderation application news.web.war WAR file for the News application lc.profiles.app.war WAR file for the Profiles application search.war WAR file for the Search application wikis.web.war WAR file for the Wikis application
OSGi bundles
The following OSGi bundles are packaged as part of IBM Connections,...where version_stamp is a version stamp that may change depending on the interim fix:
Table 6. OSGi bundles
OSGi bundle Description com.ibm.dwa.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Communities Events application. This bundle contains many of the "calendar view" related user interface handling code for the Communities Events widget.
com.ibm.lconn.activities.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Activities application user interface. com.ibm.lconn.activitystreams.search.admin.web.resources_version_stamp.jar Contains all the HTML, JavaScript, and CSS files used by the activity stream search administration user interface. com.ibm.lconn.blogs.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Blogs application. This bundle contains user interface handling code for the Blogs application.
com.ibm.lconn.calendar.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Communities Events application. This bundle contains user interface handling code for most of the features for the Communities Events widget, and code for the Events widget that displays in the Home page.
com.ibm.lconn.communities.catalog.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Communities Places catalog user interface. com.ibm.lconn.communities.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Communities application user interface. Includes resources for the Bookmarks, Feeds, Members, and Subcommunities navigator widgets. com.ibm.lconn.communityblogs.web.resources_version_stamp.jar Contains JavaScript code that is specific to the community Blog widget and Ideation Blog widget. This bundle contains user interface handling code for the Blog and Ideation Blog widgets that are available in the Communities application.
com.ibm.lconn.communityfiles.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Files widget user interface in Communities application. com.ibm.lconn.core0.web.resources_version_stamp.jar Contains core JavaScript widgets, which are mostly a hard copy of the com.ibm.lconn.core.web.resources_version_stamp.jar source. This bundle will be deprecated in a future release.
com.ibm.lconn.dogear.web.resources_version_stamp.jar Containing JavaScript code that is specific to the Bookmarks application. This bundle contains user interface handling code for the Bookmarks application.
com.ibm.lconn.ecmpicker.web.resources_version_stamp.jar Contains the JavaScript code for the document picker that is used to connect to ECM repositories. com.ibm.lconn.files.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Files application user interface. com.ibm.lconn.forums.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Forums application. This bundle contains the user interface handling code for Forums, and also code for the Forums widgets in Communities.
com.ibm.lconn.homepage.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Home page application. This bundle contains the Home page specific elements of the activity stream, user interface handling code for the Home page, and also code for the Home page widgets.
com.ibm.lconn.librarywidget.web.resources_version_stamp.jar Contains the user interface code for the Linked Library widget. com.ibm.lconn.metrics.plugins.web.resources_version_stamp.jar Contains JavaScript code that is needed to bind to other IBM Connections applications for Metrics requirements: track read events in Files and Activities. com.ibm.lconn.metrics.reports.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Cognos® report page. com.ibm.lconn.metrics.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Metrics application: actions (dialogs), beans, scenes, utility classes, custom widgets, and core application code that implements scenes life-cycle. com.ibm.lconn.moderation.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Moderation application. com.ibm.lconn.news.digest.web.resources_version_stamp.jar Contains JavaScript and strings for the user interface elements that are specific to the News application, including the language selector that is used on the Sets page in News. com.ibm.lconn.news.microblogging.sharebox.form_version_stamp.jar Contains code for the microblogging widget that displays before the activity stream. This bundle also contains code that provides the gadget used for the Share dialog, and strings that are used in the microblogging widget and dialog.
com.ibm.lconn.oauth.web.resources_version_stamp.jar Contains JavaScript resources for the OAuth administration application. com.ibm.lconn.profiles.web.resources_version_stamp.jar Contains JavaScript and resource strings for the Profiles application user interface in places like the general user interface, widgets, and business card. com.ibm.lconn.recomm.web.resources_version_stamp.jar Contains strings and JavaScript resources for the Related Communities widget. com.ibm.lconn.share0.web.resources_version_stamp.jar Contains base classes (dialogs, widgets, and utils) for the com.ibm.lconn.wikis.web.resources__version_stamp.jar file. com.ibm.lconn.wikis.web.resources_version_stamp.jar Contains JavaScript code that is specific to the Wikis application: actions (dialogs), beans, scenes, utility classes, custom widgets, and core application code that implements the scenes life-cycle.
Language codes
Use the language codes listed in the table to identify the language-specific version of the JavaScript or properties files to customize.
Set the language code as a suffix to the file name using the format _language_code.For example, customizationDir/strings/com.example.resources_de.properties,
...where the language code _de indicates that the resource strings are in German.
Table 7. Language codes
Code Language ar Arabic ca Catalan cs Czech da Danish de German el Greek en English es Spanish fi Finnish fr French hu Hungarian it Italian iw Hebrew ja Japanese kk Kazakh ko Korean nl Dutch no Norwegian pl Polish pt Iberian Portuguese pt-BR Brazilian Portuguese ru Russian sl Slovenian sv Swedish th Thai tr Turkish zh Simplified Chinese If you provide translated strings in Simplified Chinese, be sure to also provide strings in Traditional Chinese. When the customer's language preference is set to Traditional Chinese, but that language is not provided, Simplified Chinese is displayed by default.
zh-TW Traditional Chinese
Customize the navigation bar
You can edit the files that control the content of the IBM Connections navigation bar to add to the bar's functionality. For example, you can add extra links to the navigation bar, remove the Log Out link, or insert extra drop-down menus.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- To add a link to the list of links in the navigation bar, for example, a link called IBM software that links to that website:
- Make a copy of the header.jsp file, which defines the content of the main navigation bar. You can access the file from the following directory:
application_name.war/nav/templatesFor information about how to find the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
The header.jsp file is the same for each application so you only need to make a copy of one of the header.jsp files.
You might want to copy your header changes to the login.jsp and error.jsp files for consistency across your deployment. See Customize the login page and Customize error page for more information.
- Paste the copy of the header.jsp file into the appropriate subdirectory in the customization directory, most likely the common directory. See Determining
...where to save your customizations for more details about customization subdirectories.
For example, to change the look of the navigation bar in all the applications, copy the file into the following directory:
customizationDir/common/nav/templates
- Open the copy of the header.jsp file in a text editor and look for the following section:
Links to each installed application are displayed here. To add a link to another website, add the following markup: <li> <a href="http://mycompany.com/link">My Company Site</a> </li> to the end of the following <UL>. This section replaces the macro "{{application links: li }}" in the previous version of the header.
- Add the following HTML code before the closing </ul> tag:
<li><a href="http://www.ibm.com" >IBM website/a></li>
- After making your updates, save and close the copy of the header.jsp file. You do not need to restart the applications to see the links display.
- If you want to remove the Log Out link from the drop-down menu, for example, when single sign-on is enabled, you can prevent the link from being displayed by editing the logoutContainer element in the user.jsp file:
- Copy the user.jsp file from application_name.war/nav/templates/menu/ to the following location:
customizationDir/common/nav/templates/menu/user.jsp
- Modify the following line in the copied file to add a lotusHidden style:
--%><td class="lotusNowrap lotusHidden" id="logoutContainer"</><%--
- Save and close the customized user.jsp file.
- To add a new drop-down menu:
- Copy the user.jsp file from application_name.war/nav/templates/menu/ to the following location:
customizationDir/common/nav/templates/menu/user.jsp
- Copy one of the existing menu sections and change the "src" attribute to point to an servlet, JSP, or static HTML page containing the markup to use. Be sure to change the ID of the new element to avoid having duplicate IDs on the page.
For example:
<tr role="menuitem"> <td class="lotusNowrap" id="logoutContainer"> <a href="http://www.ibm.com">IBM Homepage</a> </td> </tr>
- Save and close the customized user.jsp file.
- To make changes to Communities, Profiles, and Apps menus, copy or remove code sections to render links in the respective JSP files:
- Copy one of the menu files from the following locations:
- Profiles menu: application_name.war/nav/templates/menu/people.jsp
- Communities menu: application_name.war/nav/templates/menu/communities.jsp
- Apps menu: application_name.war/nav/templates/menu/apps.jsp
- Paste the copied file into the following directory:
customizationDir/common/nav/templates/menu/
- Open the copied file in a text editor and make your changes.
- Save and close the customized file.
The Apps menu is always visible by default. If you remove all the applications that are listed by this menu, you also need to comment out this section in the header.jsp file:
<li id="lotusBannerApps" class="<c:if test="${first}">lotusFirst</c:if> <c:if test="${'communities' != appName && 'profiles' != appName && 'homepage' != appName}">lotusSelected</c:if>"><%-- --%><a onmouseover="dojo.require('lconn.core.header');lconn.core.header.menuMouseover(this);" onclick="dojo.require('lconn.core.header');lconn.core.header.menuClick(this);" onfocus="dojo.require('lconn.core.header');lconn.core.header.menuFocus(this);" role="button" _lconn_menuid="lconnheadermenu-apps" aria-label="<fmt:message key="label.menu.apps.name" />" src="<lc-cache:uri template="{staticLanguageRoot}/nav/templates/menu/apps.jsp" />" href="javascript:;" errormessage="<fmt:message key="${appName}.error.unavailable.title" />"><%-- --%><fmt:message key="label.menu.apps.name" /><%-- --%> <img role="presentation" src="<lc-ui:blankGif />" class="lotusArrow lotusDropDownSprite"><span class="lotusAltText">▼</span><%-- --%></a><%-- --%> </li>
- Optional: If you enabled customization debugging in step 1, turn off this capability when you are ready to publish your changes. Test whether your changes were added successfully by restarting the applications, and then refreshing the web browser. A browser refresh only shows you your changes if you turned on debugging. See Enabling and disabling customization debugging for more details.
- See Required post-customization step for information about how to update the product version stamp and ensure that your users see the changes the next time that they log in to IBM Connections.
Customize images
You can update the images used in IBM Connections to suit the needs of your organization. For example, you can replace the IBM logo with your company logo, or customize the sprited images and file type icons that are used in the product interface to fit with your company's branding.
Replace images
Customize the product by replacing images specific to IBM Connections with your own company images.
The procedure described here applies to non-sprited images only. For information about how to make changes to sprited images in IBM Connections, see Customize sprited images.
- Copy the image to replace and paste it to a new location.
Tip: To find the source file for the image to change, use one of the web inspector tools listed in Customization best practices to inspect the image. The image name displays in the img tag. If the image is sprited, you can see the class that has the image or icon
- Open the copied image file and update it as needed.
- Replace the original image with your new image by saving the updated file into the images subdirectory of the appropriate customization directory. See Determining
...where to save your customizations for more details about customization directories.
- Optional: To change the size of the image, do one of the following:
- If the dimensions of the image are specified in a CSS file, update the CSS file to customize the dimensions of the image.
- If the dimensions of the image are specified in a JSP or HTML file, update the relevant JSP or HTML file to customize the dimensions of the image.
- Stop and restart the Common.ear file in order to pick up the CSS changes.
- Test whether your custom image is being displayed successfully by refreshing the web browser and opening the page where the image is displayed.
- See Required post-customization step for information about how to update the product version stamp and ensure that your users see the changes the next time that they log in to IBM Connections.
Example
For an example of how to replace images in IBM Connections, see Changing the IBM Connections logo, which details how to replace the logos that are used in the product.
Change the IBM Connections logo
To customize IBM Connections so that it has the look and feel of your organization, you can specify a CSS override that replaces the IBM Connections logo with your company logo. Two IBM logos display in the product by default. The first logo contains the text IBM Connections and second logo is the graphical IBM logo. You can replace both logos with your company logo.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Create a CSS file named custom.css and store it in the following subdirectory of the customization directory:
customizationDir/themes/defaultThemeFor information about how to find out where your customizationDir directory is located, see Determining where to save your customizations.
- Save your company logo in the following directory:
customizationDir/themes/defaultTheme/images
- Open the CSS file in a text editor and add the following lines:
- To replace the IBM Connections text-based logo
with your company logo, add the following lines to the file:
.lotusui30 .lotusBanner .lotusLogo { background-image: url("images/logo.png"); height: image_heightpx; width: image_widthpx; } .lotusui30 .lotusBanner .lotusLogo .lotusAltText { display: none; }Where
- logo.png is the file name of your company logo.
- image_height is the height of the logo.
- image_width is the width of the logo.
- To replace the IBM graphic logo
with your company logo, add the following lines to the file:
.lotusui30 .lotusBanner .lotusIBMLogo { background-image: url("images/logo2.png"); background-position 0px 0px; height: image_heightpx; width: image_widthpx; }Where
- logo2.png is the file name of your company logo.
- image_height is the height of the logo.
- image_width is the width of the logo.
If you are supporting right-to-left languages, such as Arabic or Hebrew, you must make equivalent changes to the customRTL.css file and save that in the customizationDir/themes/defaultTheme directory as well.
- Save and close the custom.css file.
- Stop and restart the Common.ear file in order to pick up the CSS changes.
- When you are ready to publish your changes, turn off the customization debugging capability. Test whether your changes were added successfully by restarting the applications, and then refreshing the web browser. A browser refresh only shows you your changes if you turned on debugging. See Enabling and disabling customization debugging for more details.
- See Required post-customization step for information about how to update the product version stamp and ensure that your users see the changes the next time that they log in to IBM Connections.
Customize file type icons
You can add new file extensions to an existing file type icon, or add a new file extension with a new icon. Custom file type icons display in the Activities, Files, and Communities applications. They also display in the activity stream.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Add the new icon files to the following directory:
customizationDir/themes/imageswhere customizationDir is the base directory where your customizations should go. For more information, see Determining where to save your customizations.
- Make a copy of the sprite-lconn.css file. You can access the file from the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.war/nav/common/styles/basewhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
- Paste the sprite-lconn.css file into the appropriate subdirectory of the customizationDir directory:
- When you want the edited file to be used by all the applications, post it to the customizationDir/themes/images/common directory.
- For the file to be used by a specific application only, post it to the customizationDir/themes/images/application_name directory.
- Open the new copy of the sprite-lconn.css file in a text editor and do one of the following:
- Add a new extension and associate it with an existing icon:
- Find the line with extensions that currently use the icon. For example, this is the line for extensions that use the "document" icon:
.lconn-ftype16-doc,.lconn-ftype16-docm,.lconn-ftype16-docx, .... {background-position: 0 -408px;}
- Add the new extension in the appropriate format. Make it lowercase, and replace non-alpha numeric characters (a through z and 0 through 9) with a dash ("-"). For example, add the extension .DocFormat_2010 to the list like this:
.lconn-ftype16-docformat-2010, .lconn-ftype16-doc,.lconn-ftype16-docm,.lconn-ftype16-docx, .... {background-position: 0 -408px;}
- Repeat steps a and b in the 32 and 64 pixel list. For example:
.lconn-ftype32-docformat-2010, .lconn-ftype32-doc,.lconn-ftype32-docm,.lconn-ftype32-docx, .... {background-position: 0 -1112px;}.lconn-ftype64-docformat-2010, .lconn-ftype64-doc,.lconn-ftype64-docm,.lconn-ftype64-docx, .... {background-image: url(../images/ftWordProcessing64.png);}
- Add a new extension and a new icon by creating new rules for 16, 32, and 64 pixel icons, for example:
.lconn-ftype16-docformat-2010 { background-image:url(myCustomExtensionIcon16.png) !important; background-position: 0 0; }.lconn-ftype32-docformat-2010 { background-image:url(myCustomExtensionIcon32.png) !important; background-position: 0 0; }.lconn-ftype64-docformat-2010 { background-image:url(myCustomExtensionIcon64.png) !important; background-position: 0 0; }
- When you are ready to publish your changes, turn off the customization debugging capability. Test whether your changes were added successfully by restarting the applications, and then refreshing the web browser. A browser refresh only shows you your changes if you turned on debugging. See Enabling and disabling customization debugging for more details.
- See Required post-customization step for information about how to update the product version stamp and ensure that your users see the changes the next time that they log in to IBM Connections.
File type icons
These icons are provided by IBM Connections for displaying files.
Table 8. IBM Connections file type icons
Icon Description File extensions (partial list) ![]()
generic
Anything not covered by other images.
![]()
text
.323, .asc, .bas, .c, .etx, .h, .jw, .log, .mcw, .msg, .ow, .pfs, .qa, .rtf, .sow, .text, .tsv, .tw, .txt, .uls, .vw3, .ws, .xy
![]()
document
.doc, .docm, .docx, .dot, .dotm, .dotx, .en4, .enw, .leg, .lwp, .lwp7, .manu, .msw, .mwp, .mwp2, .mwpf, .odc, .odg, .odt, .ort, .otg, .oth, .otm, .ott, .pages, .pcl, .rtx, .std, .stw, .sxd, .sxq, .sxw, .w6, .w97, .wm, .wp5, .wp6, .wpf
![]()
data
.123, .12m, .acs, .csv, .dbs, .dez, .ens, .fcd, .fcs, .mwkd, .mwks, .odf, .ods, .oss, .otf, .ots, .qad, .smd, .sms, .stc, .sxc, .sxm, .wg2, .wk4, .wk6, .xla, .xlam, .xlc, .xlm, .xls, .xlsb, .xlsm, .xlsx, .xlt, .xltm, .xltx, .xlw
![]()
presentation
.flw, .key, .mass, .odp, .ope, .otc, .otp, .pot, .potm, .potx, .pp2, .pp97, .ppam, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .prz, .shw3, .sti, .sxi
![]()
Adobe PDF
.pdf, .ai, .eps, .ich, .ich6, .iwp, .ps
![]()
flash
.swf, .fla
![]()
code
.asp, .axs, .css, .htc, .htm, .html, .js, .jsp, .php, .sct, .stm, .wml, .xml, .xsl
![]()
graphic
.bmp, .cgm, .cmx, .cod, .djv, .djvu, .drw, .dxf, .eshr, .gif, .hgs, .ico, .ief, .img, .jfif, .jpe, .jpeg, .jpg, .odi, .oti, .pbm, .pcx, .pgl, .pgm, .pic, .pict, .png, .pnm, .pntg, .ppm, .psd, .psp6, .ras, .rgb, .sdw, .svg, .svgz, .tga, .tif, .tif6, .tiff, .wbmp, .wpg, .xbm, .xpm, .xwd
![]()
audio
.aac, .aif, .aifc, .aiff, .au, .kar, .m3u, .m4a, .mid, .midi, .mp3, .mpga, .ra, .ram, .rm, .rmi, .rpm, .snd, .wav, .wma
![]()
video
.asf, .asr, .asx, .avi, .divx, .flv, .lsf, .lsx, .mov, .movie, .mp2, .mp4, .mpa, .mpe, .mpeg, .mpg, .mpv2, .qt, .svi, .wmv
![]()
compressed
.cab, .dmg, .gtar, .gz, .jar, .rar, .sit, .sqx, .tar, .taz, .tgz, .z, .zip
![]()
contact
.crd, .vcard, .vcf, .vcrd
Customize sprited images
You can customize the sprited images used in IBM Connections by modifying the images and copying them to the appropriate customization directory.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Download the following file:
- Extract the contents of Spriting.zip to a local working directory.
- Modify the sprited images as needed using an image editor of your choice. The images are located in the resources/imageLibrary folder.
- From within your working directory, run the following command to build the sprites:
WAS_HOME/bin/ws_ant.sh target...where:
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- target is the name of the image that you want to sprite. You must specify this parameter when you run the ws_ant.sh command. For a full list of the targets that you can specify, see Sprite targets.
The first time you run the command, set the target to all. This is the default setting if you do not specify a target. For example:
/opt/IBM/WebSphere/AppServer/bin/ws_ant.sh allThe next time you run the command, you can specify a particular target to update specific sprites instead of all of them. For example:/opt/IBM/WebSphere/AppServer/bin/ws_ant.sh iconStates16
- From the working directory, run the following command to compile the final CSS for the sprited images:
./spriteCat.sh
- A css folder is created inside the resources directory. Copy all of the contents of this directory to the following location:
customizationDir/themes/
- When you are ready to publish your changes, turn off the customization debugging capability. Test whether your changes were added successfully by restarting the applications, and then refreshing the web browser. A browser refresh only shows you your changes if you turned on debugging. See Enabling and disabling customization debugging for more details.
- Update the version stamp and restart the application. For more information, see the topic, Required post-customization step.
Sprite targets
When you are customizing sprited images, you need to specify the sprite target as a parameter when you run the ws_ant.sh command.
The following table lists the sprites that you can customize for IBM Connections. You can also specify any of the specifically labeled components, such as iconsOther48, as a target for the ws_ant.sh command.Table 9. Sprite targets
Target Includes all branding, icons, and other branding brandingLogos and brandingOther brandingLogos brandingLogos15, brandingLogos23, and brandingLogos30 brandingOther brandingOther16, brandingOther24, and brandingOther32 icons iconsActions, iconsComponents, iconsComponentsBlue, iconsComponentsGray, iconsComponentsWhite, iconsComponentTypes, iconsDisplayControls, iconsFileTypes, iconsMessages, iconsOther, and iconsStates iconsActions iconsActions16 and iconsCKActions16 iconsComponents iconsComponents16, iconsComponents32, iconsComponents64, and iconsComponents128 iconsComponentsBlue iconsComponentsBlue16, iconsComponentsBlue24, and iconsComponentsBlue32 iconsComponentsGray iconsComponentsGray16, iconsComponentsGray24, and iconsComponentsGray32 iconsComponentsWhite iconsComponentsWhite16, iconsComponentsWhite24, and iconsComponentsWhite32 iconsComponentTypes iconsComponentTypes16 iconsDisplayControls iconsDisplayControls16 iconsFileTypes iconsFileTypes16, iconsFileTypes32, and iconsFileTypes64 iconsMessages iconsMessages16 and iconsMessages48 iconsOther iconsOther16 and iconsOther48 iconsStates consStates16 other otherColumnHeadings, otherFramework, otherMediaPlayer, otherPeople, otherStatus, and otherTree otherColumnHeadings otherColumnHeadings16 otherFramework otherFramework16 and otherFramework32 otherMediaPlayer otherMediaPlayer16, otherMediaPlayer32, otherMediaPlayer45, and otherMediaPlayer75 otherPeople otherPeople16, otherPeople24, otherPeople32, otherPeople48, otherPeople64, otherPeople128, and otherPeople155 otherStatus otherStatus9 otherTree otherTree16
Add styles to the IBM Connections stylesheet
You can change the look of the IBM Connections pages to give them a custom look by adding new style definitions in the cascading stylesheet and applying that style to different parts of the product user interface. To add a custom style to the IBM Connections stylesheet, you need to create a CSS file containing your customized styles and store it in the customizationDir/themes/defaultTheme folder.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Create a CSS file named custom.css and store it in the appropriate subdirectory of the customization directory.
For example, to change the style of a class in all the applications, you copy the file into the following directory:
customizationDir/themes/defaultThemeFor information about how to find out where your customizationDir directory is located, see Determining where to save your customizations.
A custom.css file is present in the WAR file for each application, but the file does not contain any useful content by default, so it is easier to create a custom.css file from scratch.
- Open the CSS file in a text editor, and define any new styles to apply to the product user interface.
You might want to use the defaultTheme.css file as a resource for styles that have already been defined for the application. You can find this file in the following location:
http://server_name/connections/resources/web/com.ibm.oneui3.styles/css/defaultTheme/defaultTheme.cssAlternatively, you can copy it from any of the application WAR directories:
application_war/nav/common/styles/defaultTheme/defaultTheme.cssFor a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- Add new style definitions or edit the style specified for the class definition that you copied from the defaultTheme.css file.
- Save and close the custom.css file.
- Stop and restart the Common.ear file in order to pick up the CSS changes.
- To test your style changes, reference your new style from a user interface element, and then refresh your web browser.
- Optional: If you enabled customization debugging in step 1, turn it off when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for information about how to apply your changes permanently.
Making extensive color and style changes
Edit the defaultTheme.css file to make extensive changes to the product user interface, such as changing the font style and background color.
Some applications define styles and colors beyond those that are specified in the defaultTheme.css file. These additional and application-specific styles are defined in files named after the applications, for example, activities.css. The styles and colors defined in these application-specific styles override those specified in the defaultTheme.css. When you want to customize a UI control that is only used in a particular application, you might need to edit the application-specific .css file rather than the defaultTheme.css file. If so, you can overwrite the version of that file in the product by storing your updated version in the defaultTheme customization directory for that application.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Create a defaultTheme directory in the customizationDir directory.
For example: customizationDir/themes/defaultThemeFor information about how to find out where your customizationDir directory is located, see Determining where to save your customizations.
- Navigate to the web application defaultTheme directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.war/nav/common/styles/defaultThemewhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
- Copy the defaultTheme.css file and any other files required to change, and then paste them into the common customization defaultTheme directory.
For example:customizationDir/themes/defaultTheme/defaultTheme.cssNotes:
- Pasting the defaultTheme.css file into the common customizationDir directory makes it available to all the applications.
- To customize the theme for a specific application, you must override the application-specific .css file in the following directory:
customizationDir/themes/base/applications/application_name.cssFor a list of the customization locations for application-specific themes and styles, see Determining where to save your customizations.
- Copy and paste files only, do not copy and paste the directory.
- Open the copy of the defaultTheme.css file in a text editor.
- Edit the style specified for the class definition that you want to change. For example, let's say to update the following lines of text:
body.lotusui30 {color:#222;background:none;background-color:#cee1fc} .lotusContent{background-color:#fff;}
- To change the default color of standard text, change the value defined for the body color from #222, which is black, to a color of your choosing.
The font color that you define for the body text will only be applied to text that is contained within basic body tags, such as <p> tags. User interface items such as page headings, subheadings, and links are formatted differently elsewhere.
- To change the default background color, change the value defined for the .lotusContent background-color from #fff, which is white, to a color of your choosing.
- Save and close the CSS file.
- To test your style changes refresh the web browser.
- Optional: If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for information about how to apply your changes permanently.
Customize the login page
Customize the login page in IBM Connections to have the appropriate style and content for your organization. You can change the appearance of the IBM Connections login page to meet your organization's needs. For example, you might want to replace the IBM logo that is displayed on the login page with your own company logo. Or you might want to include a link that enables users to have their user IDs or passwords sent to them through email.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Copy the login.jsp file from the WAR file of one of the applications. You can access the file from the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/ application_name.ear/application_name.war/nav/templateswhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
The login.jsp file is the same for each application. You only need to make a copy of one instance of the file.
- Paste the login.jsp file into the appropriate subdirectory of the customizationDir directory.
See Determining where to save your customizations for more information about locating your base customization directory.
- To use the same login page for all of the applications, copy it into the common directory:
customizationDir/common/nav/templates/login.jsp
- To create a different login page per application, copy the file into the appropriate subdirectory for each application:
customizationDir/application_name/nav/templates/login.jsp
- Edit the login.jsp file or files to contain the information you want.
For information on how to replace the logo on the login page, refer to the steps covered in Changing the IBM Connections logo.
- Save and close the login page.
- To test your changes, log out of the product. Refresh the web browser, and then go to a login page.
- Optional: If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for details about how to apply your changes permanently.
Customize the footer
You can edit the files that control the content of the IBM Connections footer to improve the footer's functionality.
The footer.jsp file defines the content of the footer in IBM Connections. The style used by the footer is defined in the defaultTheme.css file. In addition to defining the style of IBM Connections, this file also sets the font color and background color of the navigation bar and footer.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Make a copy of the footer.jsp file. You can access the file from the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/ application_name.ear/application_name.war/nav/templateswhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
The footer.jsp file is the same for each application. You only need to make a copy of one instance of the footer.jsp file.
- Paste the copy of the footer.jsp file into the appropriate subdirectory in the customization directory, which is most likely the common directory. See Determining where to save your customizations for more details.
For example, to change the look of the footer in all applications, copy the file into the following directory:
customizationDir/common/nav/templates
- Open the copied footer.jsp file in an editor, and then determine the section of the footer to which you want to add your link.
For example, if you want to add a link to your company's help page to the Help section of the footer, find the Help section of the footer by searching for the following HTML markup:
The help links. Points to the end-user help for the current application, and to the public IBM forums for IBM Connections --%><lc-ui:templateLink key="help.help" appname="${appName}"><fmt:message key="label.footer.help.help" /> </lc-ui:templateLink><%-- --%><li><%-- --><a href="<c:out value="http://www-10.lotus.com/ldd/lcforum.nsf" />"><%-- --%><fmt:message key="label.footer.help.forums" /><%-- --%></a><%-- --%></li>Add your company help link to the section by adding the link as an <li> element to the <td> block.The help links. Points to the end-user help for the current application, and to the public IBM forums for IBM Connections --%><lc-ui:templateLink key="help.help" appname="${appName}"><fmt:message key="label.footer.help.help" /> </lc-ui:templateLink><%-- --%><li><%-- --%><a href="<c:out value="http://www-10.lotus.com/ldd/lcforum.nsf" />"><%-- --%><fmt:message key="label.footer.help.forums" /><%-- --%></a><%-- --%></li> <li> <a href="http://www.mycompany.com/help">My Company Help</a> </li><%--You do not need to add the <lc-ui:templateLink> or <fmt:message> elements. You can just add your link within a standard <li> element.
- Save and close the footer.jsp file.
- Restart the applications, and then refresh your web browser to see your changes.
- Optional: If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for information about how to apply your changes permanently.
Customize the error page
Customize the text on the error page in IBM Connections. You can change the text that is displayed on the IBM Connections error page to more closely reflect what users should do when they run into a problem. For example, you might want to replace the phrase "Contact your administrator" with details about who to contact, including an email address or other contact information.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Copy the error.jsp file from the WAR file of one of the applications. You can access the file from the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.war/nav/templateswhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
The error.jsp file is the same for each application. You only need to make a copy of one instance of the file.
- Paste the file into the appropriate subdirectory in the customization directory, which is most likely the common directory. See Determining
...where to save your customizations for more details.
For example, to use the same error page in all the applications, copy the file into the following directory:
customizationDir/common/nav/templatesIf you want to create an application-specific error page, copy the file into the following directory:
customizationDir/application_name/nav/templates
- Open the copied error.jsp file in an editor and make your changes.
For example, you might want to change the generic text in the message that says "Contact your administrator" to provide a more meaningful message for your organization, such as "Add a ticket in the Acme IT Support Database <link>" or .Copy the following error information and email it to lcadmin@mycompany.com." To do so, look for the following block of HTML:
<p id="lconnErrorDetails" style="display:none;" class="lconnErrorDetails"> <label for="lconnErrorText"> <fmt:message key="error.details.info" /> </label> <textarea id="lconnErrorText" readonly="readonly" class="lotusText" wrap="off"> </textarea> </p>Replace the <fmt:message> element with the text to have displayed in the message box. For example:<p id="lconnErrorDetails" style="display:none;" class="lconnErrorDetails"> <label for="lconnErrorText"> Copy the following error information and email it to <a href="mailto:lcadmin@mycompany.com">lcadmin@mycompany.com</a>. </label> <textarea id="lconnErrorText" readonly="readonly" class="lotusText" wrap="off"> </textarea> </p>
- Save and close the error.jsp file.
- To test your changes, refresh the web browser, and then perform an action that will generate an error message.
- Optional: If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for information about how to apply your changes permanently.
Customize the Get Started view
Help your users get started with your implementation of IBM Connections by customizing the Get Started view that is displayed in the Home page.
The Get Started view is only available from the Home page. If you do not install the Home Page application, then the Get Started view is not available in the product.
To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. The gettingstarted-config.xml file defines the content of the Get Started view in the Home page. By default, the view identifies the following steps in vertical tabs:
You can edit the content that is displayed in each tab and you can add or remove tabs.
- Welcome
- Share
- Explore
- Open a command window, and then start the wsadmin command line tool.
- Access the configuration files for the Home page application:
execfile("homepageAdmin.py")
- Check out the Get Started view configuration files :
HomepageCellConfig.checkOutGetstartedConfig("working_directory","cell_name")...where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX® and Linux only: The directory must grant write permissions or the command will not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX/Linux:
HomepageCellConfig.checkOutGetstartedConfig("/opt/act/temp","foo01Cell01")
- Microsoft
Windows:
HomepageCellConfig.checkOutGetstartedConfig("c:/act/temp","foo01Cell01")
- From the temporary directory to which you checked out the gettingstarted-config.xml file, open it in a text editor.
- Make any of the following updates that you want:
- To remove one of the vertical tabs, find the <step> element that represents the tab and change the value of its enabled attribute from true to false.
- To add another tab to the list:
- Copy one of the existing <step> elements and paste it into the <steps> block. The order of the vertical tabs reflects the order of the steps in the <steps> element block, so copy it before and after the steps you want it to be displayed between on the page.
- Change the content of the copied <step> element:
- Change the tab title by adding your title text directly to the element in place of the jsp.start.step1.tab.title key or by specifying a key that you define in a corresponding resource bundle that you also define. For example, the title of the first tab is Welcome. It is defined by the jsp.start.step1.tab.title key that is stored in the com.ibm.lconn.homepage.resources.nls.jsp.jsp_resources resource bundle. It is specified in the title element for that step in the configuration file. The bundle attribute identifies where the resource bundle is stored and the title element itself contains the key value for the title string.
<title bundle="com.ibm.lconn.homepage.resources.nls.jsp.jsp_resources"> jsp.start.step1.tab.title </title>
- Define what should be displayed in the tab body using the <body-links> element. The <body-links> element must reference a web page that can be accessed over http and https. The page must be in the same domain as the Home page, for example an HTML page on the HTTP server of the IBM Connections deployment.
- To specify the page, provide its web address as the value of the secure and unsecure attributes. For example:
<step enabled="true"> ... <body-links secure="https://w3.example.com/peoplepages/myProfile.wss" unsecure="http://w3.example.com/peoplepages/myProfile.wss" /> </step>
- To change what is displayed in a tab, edit the title and content of the page. See the previous bullet for details.
- Save and close the gettingstarted-config.xml file.
- Run the following command to check the configuration files back in. You must check the files back in during the same wsadmin session in which you checked them out for the changes to take effect.
HomepageCellConfig.checkInGetstartedConfig("working_directory", "cell_name")...where the working_directory and cell_name parameters contain the same values you specified for the checkout location.
- Update the version stamp property to force a refresh of your users' web browsers, so that they will see the changes you made to the Get Started view the next time they access the product. See Required post-customization step.
Customize product strings
You can replace a word or phrase in the product user interface with terminology that better suits your environment.
Notes:
Many of the product strings in the IBM Connections user interface are represented by key-value pairs defined in the properties files stored in the application JAR files. Before you can redefine the value of a string, you must find out which key is used to represent it. After you have identified the key-value pair to customize, you can create a properties file that contains the key-value pairs corresponding to your custom strings, and copy it into the customizationDir/strings directory.
- You cannot use this method to customize the default notification messages in emails that are sent from IBM Connections applications. See Customize notifications for information about how to customize notifications.
- You cannot use the customization debugging capability to test edited strings.
- Find the key that is used to represent the value of the string to customize. For a list of the application properties files that contain strings you can customize, see Property file strings.
- Create a properties file in which to store the key-value pair for the custom string. Give the properties file the same name as the properties file that is used to store that key by the application. For example, if you copy the templates.properties file, and paste it into the customizationDir/strings directory, name it as follows:
com.ibm.lconn.core.strings.templates.propertiesYou must create the file with the full file name; that is, it must not be a series of directories containing the templates.properties file, such as, com/ibm/lconn/core/strings/templates.properties.
Also, specify a language code for the properties file in the file name. If you do not provide a _language_code value at the end of the properties file name, the value you specify for the key in the properties file is used despite the locale of the web browser accessing the application.
For example, if you change the key with the current value of "Help" to "Ayuda" and define it in a file named com.ibm.lconn.files.strings.ui.properties (without the _es suffix), then anyone who accesses the product will see Aydua in place of the Help string even if their browser locale is not set to es. In some cases, you might want the same value applied to all languages. If you want to change the term "IBM Connections" to a company name, for example, then you might store the customized key in a properties file without the _language_code suffix and the company name shows as-is to all browsers.
For a full list of the language codes supported by IBM Connections, see Language codes.
- Save the properties file that you created in the following directory:
customizationDir/strings...where customizationDir is the root directory for customization files. See Determining
...where to save your customizations for more details. Unlike some of the other areas of the product, the strings directory in the customization root does not have a subdirectory for each application. Each application uses unique properties file names so all of the strings that you replace can be stored in this common strings directory.
- Use the IBM WebSphere Application Server Integrated Solutions Console, stop and restart each application EAR file.
- Test your changes by clearing your browser cache, and then refreshing the browser.
- To force all user web browsers to refresh all cached content and display your changes, run the command that updates the product version stamp.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Enter the following command to increment the value of the versionStamp property: LCConfigService.updateConfig("versionStamp","gmt_timestamp") where gmt_timestamp is the GMT time. You can specify an empty string for the time stamp or provide a GMT value string. When you specify an empty string, the client calculates the current GMT time and updates the version stamp with that value. If you choose to provide the time, specify it using the following format: yyyyMMdd.HHmmss and specify the time in GMT. It is best to provide an empty string and let the client format the time stamp. For example: LCConfigService.updateConfig("versionStamp","").
- After making changes, you must check the configuration files back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
Property file strings
Use the information in the tables to locate the customizable strings contained in property files and to determine where to save the customized files.
The following tables list the application properties files containing strings that you can customize.Notes:
- To customize the source properties files, you must first extract the contents of the JAR file files using a compression program.
- In the paths listed here:
- installedApps refers to the following directory path:
WAS_HOME/profiles/profile_name/installedApps
where:
- WAS_HOME is the directory to which you installed IBM WebSphere® Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
For example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/standaloneCell01/
- webresources refers to the web resources provisioning directory for IBM Connections created during installation. By default, it is created in the following directory:
CONNECTIONS_HOME/data/shared/provision/webresourcesFor example: /opt/IBM/Connections/Data/shared/provision/webresources/
- customizationDir refers to the base customization directory where you need to save your customized files. This base directory is defined during the installation of IBM Connections, when it is saved as a WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. This variable is set to shared_data_directory_root/customization by default.
For example: local/opt/IBM/Connections/Data/shared/provision/customization/
- _version refers to the file version and timestamp, for example, _3.0.0.20120307-0100 in the following file name:
com.ibm.lconn.activities.web.resources_3.0.0.20120307-0100.jar
- The customized files are saved in the customizationDir/strings/customized_properties_file_name directory,
...where any slashes in the source file name location are replaced by dots.
For example, when you customize the ui.properties source file for Blogs from the Blogs.ear/blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ui.properties source location, you must save the customized properties file in the following location:
customizationDir/strings/com.ibm.lcon.blogs.strings.ui.properties.
- When you want to customize a locale-specific version of one of the source files listed, look in the same source directory for a file of the same name but with the relevant language code appended before the .properties file extension. When you save the customized version of the file, ensure that you append the language code to the file name before the file extension.
For example, to customize German strings for Blogs, look for the ui_de.properties file in the Blogs.ear/blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ui.properties source location and save the customized strings in the following location:
customizationDir/strings/com.ibm.lcon.blogs.strings.ui_de.properties
- The following features do not have any properties files associated with them:
- Blog widget (Communities)
- ECM document picker (Communities)
- Ideation Blog widget (Communities)
For a list of the JavaScript files associated with these features, see JavaScript resource strings.
Common areas
Table 10. Common string locations
Description Source location Save customizations in Common widget strings In installedApps/application_name.ear/war/WEB-INF/
lib/lc.util.web-3.0.jar:
com.ibm.lconn.core.strings.templates.propertiescustomizationDir/strings/com.ibm.lconn.core.strings.templates.properties Core activity stream strings used in the Home page, Profiles, Communities, IBM Lotus Notes®, and other consumers of the activity stream gadget In installedApps/Common.ear/connections.web.resources
.war/WEB-NF/eclipse/plugins/com.ibm.social.as.web.
resources_version.jar:
properties/activitystream_resources.propertiescustomizationDir/strings/com.ibm.social.as.activitystream_resources.properties Core activity stream strings used in the Home page, Profiles, Communities, IBM Lotus Notes, and other consumers of the activity stream gadget In installedApps/Common.ear/connections.web.resources
.war/WEB-INF/eclipse/plugins/com.ibm.social.as.lconn.web.
resources_version.jar:
properties/activitystream_lconn.propertiescustomizationDir/strings/com.ibm.social.as.lconn.activitystream_lconn.properties Strings used by the Application Access and Access Request interfaces that prompt users to grant, deny, and revoke access to their IBM Connections data for third-party applications protected by OAuth In installedApps/Common.ear/connections.web.resources
.war/WEB-INF/eclipse/plugins/com.ibm.social.as.lconn.web.
resources_version.jar:
com.ibm.lconn.oauth.strings.ui.propertiescom.ibm.lconn.oauth.strings.ui.properties
Activities
Table 11. Activities
Description Source location Save customizations in Activities user interface strings Most user interface strings are in strings.js. This file is in the Activities resource jar located in the PROVISION folder sample: C:\IBM\Connections\Data\provision\webresources\
com.ibm.lconn.activities.web.resources_version.jarIf you cannot find the string here, check the Activities resource bundle in installedApps\Activities.ear\oawebui.war\WEB-INF\lib\oawebui.jar:
com\ibm\openactivities\web\coreui\resources\resources.propertiesSee Customize strings sourced in JavaScript for more information.
customizationDir/strings/com.ibm.openactivities.web.coreui.resources.
resources.propertiesActivities notification strings Notification strings and some user interface strings are in \LotusConnections-config\notifications\activities\resources\nls\notification_<locale>.properties where <locale> is the language code, for example notification _en.properties. If no locale is specified then use notification.properties. Edit and save the customized file in the source location.
Blogs
Table 12. Blogs
Description Source location Save customizations in User interface strings Blogs.ear/blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/ui.properties customizationDir/strings/com.ibm.lcon.blogs.strings.ui.properties Log strings Blogs.ear/blogs.war/WEB-INF/classes/com/ibm/lconn/blogs/strings/log.properties customizationDir/strings/com.ibm.lcon.blogs.strings.log.properties
Bookmarklet
The bookmarklet is the window that displays when you add a bookmark. It is located in the Common.ear file. The bookmarklet allows users to add bookmarks to different applications, such as Communities or Activities. Users can add a button to their browser that allows them to access the bookmarklet window. Every page in IBM Connections has a Bookmarking Tools link in the page footer that allows users to install this toolbar button.
Table 13. Bookmarklet
Description Source location Save customizations in Bookmarklet user interface strings (JSP files) In installedApps/common.ear/lc-bookmarklet.war/WEB-INF/lib/lc-
bookmarklet.jar:
com.ibm.lconn.bookmarklet.strings.ui.propertiescustomizationDir/strings/com.ibm.lconn.bookmarklet.strings.ui.properties Bookmarklet user interface strings (Java files) In installedApps/common.ear/lc-bookmarklet.war/WEB-INF/lib/lc-
bookmarklet.jar:
com.ibm.lconn.bookmarklet.resources.jspresources.propertiescustomizationDir/strings/com.ibm.lconn.bookmarklet.resources.jspresources.properties
Bookmarks
Table 14. Bookmarks
Description Source location Save customizations in Bookmarks user interface strings (JSP files) In installedApps/Dogear.ear/dogear.webui.war/WEB-INF/lib/dogear.svc.jar:
com/ibm/lconn/dogear/strings/uilabels.propertiescustomizationDir/strings/com.ibm.lconn.dogear.strings.uilabels.properties Bookmarks user interface strings (Java files) In installedApps/Dogear.ear/dogear.webui.war/WEB-INF/lib/dogear.svc.jar:
com/ibm/lconn/dogear/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.dogear.strings.ui.properties
Communities
Table 15. Communities
Description Source location Save customizations in Main Communities application user interface In installedApps/Communities.ear/comm.web.war/WEB-INF/lib/comm.web.jar:
com/ibm/lconn/communities/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.communities.strings.ui.properties Communities email text In installedApps/Communities.ear/comm.web.war/WEB-INF/lib/comm.web.jar:
com/ibm/lconn/communities/strings/uiemail.propertiescustomizationDir/strings/com.ibm.lconn.communities.strings.uiemail.properties Communities business card (used by the IBM Connections applications) In installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.web.resources_version.jar:
_properties/com/ibm/lconn/core/web/resources/commbizcard.propertiescustomizationDir/strings/com.ibm.lconn.core.web.resources.commbizcard.properties Communities widget titles installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.web.resources_version.jar:
_properties/com/ibm/lconn/widgets/resources/ui_resources.propertiescustomizationDir/strings/com.ibm.lconn.widgets.resources.ui_resources.properties Linked Library widget and Media Gallery widget In webresources/com.ibm.lconn.librarywidget.web.resources_
version.jar:
_properties/com/ibm/quickr/lw/nls/LibraryWidgetMessages.propertiescustomizationDir/strings/com.ibm.quickr.lw.nls.LibraryWidgetMessages.properties Related Communities widget In installedApps/Communities.ear/recomm.web.war/WEB-INF/classes/com/ibm/lconn/recomm/strings/ui.properties customizationDir/strings/com.ibm.lconn.recomm.strings.ui.properties
Files
Table 16. Files
Description Source location Save customizations in Main Files application user interface and the Files widget in Communities In webresources/com.ibm.lconn.files.web.resources
_version.jar:
_properties/com/ibm/lconn/files/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.files.strings.ui.properties Help pop-ups In webresources/com.ibm.lconn.files.web.resources
_version.jar:
_properties/com/ibm/lconn/files/strings/uihelp.propertiescustomizationDir/strings/com.ibm.lconn.files.strings.uihelp.properties About and Metrics pages In webresources/com.ibm.lconn.files.web.resources
_version.jar:
_properties/com/ibm/lconn/files/strings/uitemplates.propertiescustomizationDir/strings/com.ibm.lconn.files.strings.uitemplates.properties
Forums
Table 17. Forums
Description Source location Save customizations in User interface strings Forums.ear/forum.web.war/WEB-INF/lib/forum.web.jar/com/ibm/forum/web/resources/resources_en.properties customizationDir/strings/com.ibm.forum.web.resources.resources.properties Log strings Forums.ear/forum.web.war/WEB-INF/lib/forum.svc.jar/com/ibm/lconn/forum/internal/resources/resources.properties customizationDir/strings/com.ibm.lconn.forum.internal.resources.resources.properties Log strings Forums.ear/forum.web.war/WEB-INF/lib/forum.svc.jar/com/ibm/lconn/forum/internal/service/core/core.properties customizationDir/strings/com.ibm.lconn.forum.internal.service.core.core.properties
Home page
Table 18. Home page
Description Source location Save customizations in Most strings appearing in the user interface, except for the stories in the river of news In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/jsp/jsp_resources.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.nls.jsp.jsp_resources.properties Activity Stream strings In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/activitystream/activitystream_resources.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.nls.activitystream.
activitystream_resources.propertiesActivity Stream filters In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/activitystream/config/activitystreamconfig_resources.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.nls.activitystream.
config.activitystreamconfig_resources.propertiesNotification strings In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/ui/ui_resources.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.
nls.ui.ui_resources.propertiesStrings related to widgets, such as widget titles and the strings that are displayed in the customization palette In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/catalog/service/ui/CatalogServiceUIMessages.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.nls.catalog.service.
ui.CatalogServiceUIMessages.propertiesWidget resources In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
/com/ibm/lconn/homepage/resources/nls/widgets/widgets_resources.propertiescustomizationDir/strings/com.ibm.lconn.homepage.resources.nls.widgets.
widgets_resources.propertiesCore activity stream filter resources In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/lc.services.gadgets.osapiclient.jar:
com/ibm/lconn/services/gadgets/osapiclient/activitystream/config/activitystreamconfig.propertiescustomizationDir/strings/com.ibm.lconn.services.gadgets.osapiclient.
activitystream.config.activitystreamconfig.properties
Metrics
Table 19. Metrics
Description Source location Save customizations in Main Metrics application user interface, not including metrics reports provided by Cognos In webresources/com.ibm.lconn.metrics.web.resources
_version.jar:
_properties/com/ibm/connections/metrics/ui/strings/ui.propertiescustomizationDir/strings/com.ibm.connections.metrics.ui.strings.ui.properties About page In webresources/com.ibm.lconn.metrics.web.resources
_version.jar:
_properties/com/ibm/connections/metrics/ui/strings/uitemplates.propertiescustomizationDir/strings/com.ibm.connections.metrics.ui.strings.uitemplates
.properties
Moderation
Table 20. Moderation
Description Source location Save customizations in Main Moderation application In installedApps/moderation.ear/sn.moderation.ui.jar:
com.ibm.lconn.moderation.ui.strings.ui.propertiescustomizationDir/strings/com.ibm.lconn.moderation.ui.strings.ui.properties Online help In installedApps/moderation.ear/sn.moderation.ui.jar:
com.ibm.lconn.moderation.ui.strings.uihelp.propertiescustomizationDir/strings/com.ibm.lconn.moderation.ui.strings.uihelp.properties About page In installedApps/moderation.ear/sn.moderation.ui.jar:
com.ibm.lconn.moderation.ui.strings.uitemplates.propertiescustomizationDir/strings/com.ibm.lconn.moderation.ui.strings.uitemplates.properties
News
Table 21. News
Description Source location Save customizations in Template resource strings for use in activity stream event titles In installedApps/News.ear/news.common.jar:
com/ibm/lconn/news/nls/templatePlaceholders.propertiescustomizationDir/strings/com.ibm.lconn.news.nls.templatePlaceholders.properties JSP resources for email digest settings page In installedApps/News.ear/news.common.jar:
com/ibm/lconn/news/nls/jsp_resources.propertiescustomizationDir/strings/com.ibm.lconn.news.nls.jsp_resources.properties Notification strings displayed in the Home page In installedApps/News.ear/news.common.jar:
com/ibm/lconn/news/nls/ui_resources.propertiescustomizationDir/strings/com.ibm.lconn.news.nls.ui_resources.properties
Profiles
Table 22. Profiles
Description Source location Save customizations in Used in the Atom APIs for informational use only, not for the end user In installedApps/Profiles.ear/lc.profiles.app.war/WEB-INF/lib/lc.profiles.web.app.jar:
com/ibm/lconn/profiles/api/actions/resources.propertiescustomizationDir/strings/com.ibm.lconn.profiles.api.actions.
resources.propertiesMain resource string file for user interface display in Profiles In installedApps/Profiles.ear/lc.profiles.app.war/WEB-INF/lib/lc.profiles.web.app.jar:
com/ibm/lconn/profiles/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.profiles.strings.ui.properties Strings for profile field labels In installedApps/Profiles.ear/lc.profiles.app.war/WEB-INF/lib/lc.profiles.web.app.jar:
com/ibm/lconn/profiles/strings/uilabels.propertiescustomizationDir/strings/com.ibm.lconn.profiles.strings.uilabels.properties
Search
Table 23. Search
Description Source location Save customizations in Search application user interface strings In installedApps/Search.ear/search.common.jar:
com/ibm/lconn/search/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.search.strings.ui.properties
Social analytics
Table 24. Social analytics
Description Source location Save customizations in Strings for the Who Connects Us, Things in Common, and Do You Know widgets In installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.sand.web.resources_version.jar:
_properties/com/ibm/lconn/sand/resources/sand.propertiescustomizationDir/strings/com.ibm.lconn.sand.resources.sand.properties
Wikis
Table 25. Wikis
Description Source location Save customizations in Main Wikis application user interface In installedApps/Wikis.ear/wikis.web.jar:
com/ibm/lconn/wikis/strings/ui.propertiescustomizationDir/strings/com.ibm.lconn.wikis.strings.ui.properties Help tooltips In installedApps/Wikis.ear/wikis.web.jar:
com/ibm/lconn/wikis/strings/uihelp.propertiescustomizationDir/strings/com.ibm.lconn.wikis.strings.uihelp.properties About page and Server Metrics page In installedApps/Wikis.ear/wikis.web.jar:
com/ibm/lconn/wikis/strings/uitemplates.propertiescustomizationDir/strings/com.ibm.lconn.wikis.strings.uitemplates.properties These resource bundles contain the majority of the Wikis user interface strings, but the strings for the Communities Widget are provided in JavaScript. See Customize strings sourced in JavaScript for more information.
Customize strings sourced in JavaScript
Replace a word or string in the product user interface that is sourced in JavaScript as opposed to a strings resource bundle. Many strings in the IBM Connections user interface are represented by key and value pairs defined in JavaScript files that are stored in the application JAR files. You can customize these strings by locating the appropriate JavaScript source file, copying it into the corresponding subdirectory of the customization directory, and overwriting the key and value pair in the copied file with your custom text.
Notes:
- You cannot use the customization debugging capability to test edited strings.
- Follow the steps outlined here when you want to update the text in the JavaScript files in your deployment. When you want to change the functionality of the JavaScript code, follow the procedure covered in the topic, Overriding JavaScript in IBM Connections.
- To use the external resource bundle loader for adding and updating strings in the user interface, see Add custom strings for widgets and other specified scenarios.
- Locate the JavaScript source file for the application to customize, based on the information in the topic, JavaScript resource strings.
- Determine the base directory where your customizations should go. For more information, see Determining
...where to save your customizations.
- Copy and paste the file to customize into the appropriate subdirectory of the customization root directory. For information about where to place your customizations, see JavaScript resource strings.
For example, for Activities, save the customized JavaScript file in the following location:
customizationDir/javascript/lconn/act/nls/strings.jsFor locale-specific strings, create a folder in the customizationDir/javascript/lconn/act/nls directory, name it with the corresponding language code, and save the JavaScript file in the new folder. For example, to save German strings for Activities, save the customized JavaScript file in the following location:
customizationDir/javascript/lconn/act/nls/de/strings.jsFor a full list of the language codes supported by IBM Connections, see Language codes.
- Open the copied JavaScript file for editing. Find the key and value pair to overwrite, and replace the value with your custom text.
- Repeat the previous step until you have replaced all of the strings to change.
- Remove any key and value pairs that you did not edit. Those will be read from the version of the JavaScript file in the application's product directory.
- Save and close the JavaScript file.
- Use the WebSphere Application Server Integrated Solutions Console, restart the application associated with the file that you have changed.
- Test your changes by clearing your browser cache, and then refreshing the browser.
- See Required post-customization step for information about how to apply your changes permanently.
JavaScript resource strings
Use the information in the tables to help you find the customizable strings that are sourced in JavaScript files and to determine where to save the customized JavaScript files.
Notes:
- In the paths listed here:
- installedApps refers to the following directory path:
WAS_HOME/profiles/profile_name/installedApps
where:
- WAS_HOME is the directory to which you installed IBM WebSphere® Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
For example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/standaloneCell01/
- webresources refers to the web resources provisioning directory for IBM Connections that is created during installation. By default, it is created in the following directory:
CONNECTIONS_HOME/data/shared/provision/webresourcesFor example: /opt/IBM/Connections/Data/shared/provision/webresources
- customizationDir refers to the base customization directory where you need to save your customized files. This base directory is defined during the installation of IBM Connections, when it is saved as a WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. This variable is set to shared_data_directory_root/customization by default.
For example: local/opt/IBM/Connections/Data/shared/provision/customization/
- version refers to the file version and timestamp, for example, _3.0.0.20120307-0100 in the following file name:
com.ibm.lconn.activities.web.resources_3.0.0.20120307-0100.jar
- language_code identifies the language-specific version of the strings to customize. For a list of the language codes supported by IBM Connections, see Language codes.
- The following applications do not have any associated JavaScript resource strings:
- Files
- Linked Library widget (Communities)
- Media Gallery
- Metrics
- Moderation
- News
- Profiles
Common
Table 26. Common JavaScript files
Description Source location Place customizations in Upload file dialog related strings installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.web.resources_version.jar/resources/upload/nls/upload.js customizationDir/javascript/lconn/core/upload/nls/upload.js
Activities
Table 27. Activities JavaScript files
Description Source location Place customizations in Activities application strings webresources/com.ibm.lconn.activities.web.resources_version.
jar/resources/nls/strings.jscustomizationDir/javascript/lconn/act/nls/strings.js
Blogs
Table 28. Blogs JavaScript files
Description Source location Place customizations in Blogs application strings webresources/com.ibm.lconn.blogs.web.resources_version.jar/resources/nls/strings.js customizationDir/javascript/lconn/blogs/nls/strings.js Blog widget (Communities) webresources/com.ibm.lconn.communityblogs.web.resources/resources/nls/strings.js customizationDir/javascript/lconn/communityblogs/nls/strings.js Ideation Blog widget (Communities) webresources/com.ibm.lconn.communityblogs.web.resources/resources/ideation/nls/strings.js customizationDir/javascript/lconn/communityblogs/ideation/nls/strings.js
Bookmarks
Table 29. Bookmarks JavaScript file
Description Source location Place customizations in Bookmarks application strings webresources/com.ibm.lconn.dogear.web.resources_version.jar/resources/nls/strings.js customizationDir/javascript/lconn/dogear/nls/strings.js
Bookmarklet
The bookmarklet is the window that displays when you add a bookmark. It is located in the Common.ear file. The bookmarklet allows users to add bookmarks to different applications, such as Communities or Activities. Users can add a button to their browser that allows them to access the bookmarklet window. Every page in IBM Connections has a Bookmarking Tools link in the page footer that allows users to install this toolbar button.
Table 30. Bookmarklet JavaScript file
Description Source location Place customizations in Bookmarklet application strings installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.bookmarklet.web.resources_version.jar/resources/nls/strings.js customizationDir/javascript/lconn/bookmarklet/nls/strings.js
Communities
Table 31. Communities JavaScript files
Description Source location Place customizations in Communities application strings webresources/com.ibm.lconn.communities.web.resources_
version.jar/resources/nls/strings.jscustomizationDir/javascript/lconn/comm/nls/strings_xx.js ECM document picker (used to configure the Linked Library to point to a specific library or folder) webresources/com.ibm.lconn.ecmpicker.web.resources_
version.jar/resources/nls/language_code/picker.jscustomizationDir/javascript/quickr/picker/nls/
language_code/picker.jsCalendar widget strings webresources/com.ibm.lconn.calendar.web.resources_version.jar/resources/CalendarData/nls/templateStrings.js customizationDir/javascript/lconn/calendar/CalendarData/nls/templateStrings.js Calendar widget strings (grid view) webresources/com.ibm.dwa.web.resources_version.jar/resources/cv/nls/calendarView.js customizationDir/javascript/dwa/cv/nls/calendarView.js Calendar widget strings (grid view) webresources/com.ibm.dwa.web.resources_version.jar/resources/date/nls/calendar.js customizationDir/javascript/dwa/date/nls/calendar.js Calendar widget strings (grid view) webresources/com.ibm.dwa.web.resources_version.jar/resources/date/nls/datepick.js customizationDir/javascript/dwa/date/nls/datepick.js Related Communities widget strings webresources/com.ibm.lconn.recomm.web.resources_version.jar/resources/nls/strings.js customizationDir/javascript/lconn/recomm/nls/strings.js
Forums
Table 32. Forums JavaScript files
Description Source location Place customizations in Forums application strings webresources/com.ibm.lconn.forums.web.resources_version.jar/resources/nls/strings.js customizationDir/javascript/lconn/forums/nls/strings.js Forums widget (Communities) installedApps/cellName/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.web.resources_version.jar/resources/nls/strings.js
where cellName is the name of the cell to which the Common.ear node belongs.customizationDir/javascript/lconn/core/nls/strings.js
Profiles
Table 33. Profiles JavaScript files
Description Source location Place customizations in Profiles business card installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.web.resources_version.jar customizationDir/javascript/lconn/communities/bizCard/nls/ui Profiles JavaScript-defined strings come from property files; all Dojo dijits used in Profiles are defined in core.ui (bizcard, invite) and their strings are stored in core.web.resources.
Search
In the source location, com.ibm.lconn.search.web.resources is the name of the JAR file beginning with com.ibm.lconn.sand.web.resources.Table 34. Search JavaScript files
Description Source location Place customizations in Sorting control on the Search Results page installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.search.web.resources/resources/nls/Sorting.js customizationDir/javascript/lconn/search/nls/Sorting.js Strings used when rendering the data from the feed for the search results installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.search.web.resources/resources/nls/searchData.js customizationDir/javascript/lconn/search/nls/searchData.js Search Results page installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.search.web.resources/resources/nls/searchResults.js customizationDir/javascript/lconn/search/nls/searchResults.js Trending widget on the Search Results page installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.search.web.resources/resources/nls/trendData.js customizationDir/javascript/lconn/search/nls/trendData.js
Social analytics
In the source location, com.ibm.lconn.sand.web.resources is the name of the JAR file beginning with com.ibm.lconn.sand.web.resources.Table 35. Social analytics JavaScript files
Description Source location Place customizations in Recommendations widgets (Communities and Home page) installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.lconn.sand.web.resources/resources/nls/RecommendWidget.js customizationDir/javascript/lconn/sand/nls/RecommendWidget.js
Wikis
Table 36. Wikis JavaScript files
Description Source location Place customizations in Wiki widget (Communities) Wikis.ear/wikis.web.war/iwidgets/CommunityWidget/nls/en/WikiWidget.js customizationDir/javascript/wikis/iwidgets/CommunityWidget/nls/en/WikiWidget.js
Add custom strings for widgets and other specified scenarios
You can add custom strings or modify existing strings when performing certain IBM Connections tasks.
When adding custom strings, you must use the wsadmin client. See Start the wsadmin client for details.
IBM Connections provides a external resource bundle loader for adding and updating strings to Profiles, Communities, and the Home page. You can only use this process when performing the following tasks:
You can add custom strings for other tasks using the procedure outlined in Customize product strings. To add custom strings for the listed tasks, create a bundle containing the custom strings and save it in the customization_dir/strings directory that is created at installation time. You then register the file in LotusConnections-config.xml. For performance reasons, include all the resource strings in a single bundle.
- Add custom extension attributes to profiles
- Customize the Profiles business card
- Add custom widgets to Communities, Profiles, and the Home page
- Configure the vCard export application
- Renaming the tabs in the Home page
- Add custom themes to Communities
For a complete example, see Creating a simple profile data model and template customization.
- Create a properties file containing the strings that you want to add in the customization_dir/strings directory.
- To specify the name of the default properties file, use the following syntax:
resource_bundle_name.properties_file_name
- To specify custom strings in multiple languages, append an underscore followed by the appropriate language code to the resource bundle name using the following syntax:
resource_bundle_name_language_code.properties_file_nameFor example, if your string bundle is named com.example.resources, you might create a file in the strings directory that looks like the following:
customization_dir/strings/com.example.resources.properties
This file contains the strings used for the default locale. When there is no specific bundle for the user's locale, the labels in this default properties file are used.To include an English version of the strings, you might create the following file:
<customization_dir>/strings/com.example.resources_en.propertiesAnd to include a Slovakian version of the strings, you might include the following file:
customization_dir/strings/com.example.resources_sk.propertiesThe following sample string is contained in the properties file.
label.vcard.encoding.cp943c=Japanese Encoding
- Register the resource bundle in LotusConnections-config.xml:
- Open a command window and start the wsadmin command-line tool as described in the topic, Starting the wsadmin client.
- Enter the following command to access the IBM Connections configuration file:
execfile("<$WAS_HOME>/profiles/<DMGR>/config/bin_lc_admin/connectionsConfig.py")
- Enter the following command to check out the IBM Connections configuration file:
LCConfigService.checkOutConfig(working_directory, cell_name)
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied. The files are kept in this working directory while you make changes to them.
- cell_name is the name of the IBM WebSphere Application Server cell hosting the IBM Connections application. This argument is required. It is also case-sensitive, so type it with care.
LCConfigService.checkOutConfig("/temp", "foo01Cell01")
- From the temporary directory to which you just checked out the IBM Connections configuration files, open LotusConnections-config.xml in a text editor.
- Add the following line of code into the <resources> element block to register the resource bundle:
<widgetBundle prefix=bundle_prefix name=bundle_name />...where
The following sample code is used to register the com.example.resources bundle:
- bundle_prefix is a globally unique name that identifies the bundle. This is a string value. The bundle prefix is used to uniquely scope the keys in each bundle. The prefix must be unique across all registered widget bundles.
This bundle prefix maps to the bundle ID reference that you specify when you define a custom resource attribute or widget. For more information about defining custom resource attributes, see Enabling custom extension attributes for Profiles. For information about defining custom widgets, see Enabling custom widgets for Communities or Enabling custom widgets for Profiles.
- bundle_name is the Java package name. This parameter takes a string value. When you name the resource bundle, the elements in the bundle name must correspond to the file name of the properties file that you created in step 1.
For example, if the strings customization directory contains the files com.example.resources.properties, com.example.resources_en.properties, and com.example.resources_sk.properties, the name of the bundle is com.example.resources.
<resources> <!-- Example: The attribute 'prefix' must be globally unique as it identifies the bundle when used in IBM Connections. --> <widgetBundle prefix="example" name="com.example.resources"/> </resources>
- Save your changes to LotusConnections-config.xml.
- To check in the updated file, use the following command:
LCConfigService.checkInConfig()
- To exit the wsadmin client, type exit at the prompt.
What to do next
After completing this procedure, you can use the labels in other configuration settings or in your JavaScript code. For example, you can use the strings when customizing the business card in Profiles (to add labels for custom extension attributes) and adding widgets to Profiles, Communities, and the Home page (to provide widget titles and descriptions). You can also use the strings to rename the Updates, Widgets, and Administration tabs in the Home page.Note that when you specify external labels for attributes, editable attributes, or custom extension attributes, the labels are only applied to the user interface element that the configuration object represents. For example, if you apply a custom label to a business card <attribute> element, the label does not automatically apply to the same element in the advanced search page layout.
For information about how to apply the label configuration to each user interface element individually, see Specifying external labels for attributes.
Customize notification strings
Customize the strings that are used in the notifications that are sent to IBM Connections users by the system. You can customize the text used in the notification messages sent to your users to include information specific to your organization. All of the strings used in notification templates are contained in the following directory:
profile_root/config/cells/cell_name/LotusConnections-config/notifications
- Find the file that serves as the source of the notification string to edit. You can locate the strings used in notifications in one of the following directories:
- Strings that are shared across templates are contained in the following directory:
LotusConnections-config/notifications/resources/nls/notification_*.properties
- Strings that are specific to templates from a particular application, such as Activities or Files, are contained in the following directory:
LotusConnections-config/notifications/application_name/resources/nls/notification_*.properties
- Open the file and edit the string directly to make the required changes.
- Save your changes and close the file.
- To test out your customizations, restart the News application before sending new notifications.
Overriding and extending JavaScript in IBM Connections
IBM Connections supports a mechanism that allows you to override or extend the JavaScript that is used in the different applications.
You can override JavaScript files when you want to provide very targeted fixes. Extending allows you to package your JavaScript files and have them loaded with IBM Connections in such a way that they do not disrupt existing code or prevent you from applying interim fixes.
Overriding JavaScript in IBM Connections
You can override the JavaScript files used by IBM Connections when you want to completely change the behavior of a Dojo module and you need the change to take effect as soon as the module is loaded.
To override JavaScript files, you must set up an IBM Connections deployment with the customization directory configured. For information about locating the customization directory, see Customize the user interface. After you have located your customization directory, create the following subdirectory:
customizationDir/javascriptFiles placed in this directory will override the JavaScript that is loaded for the main IBM Connections applications. This directory is loaded first and takes precedence over the content that is deployed as part of each application. Changes to this directory take effect immediately except when the JavaScript is loaded and cached statically.
Files in the customization directory are not updated when interim fixes are installed. If you add an override file and deploy an interim fix that also affects the file, copy that new change into your override file to maintain your customization.
To override JavaScript files, complete the following steps.
- Identify the JavaScript file to override.
Most of the JavaScript used by IBM Connections is located inside one of the web resources JAR files inside the provisioning directory (typically CONNECTIONS_HOME/data/shared/provision/webresources), or inside the Common.ear file. Each JAR file corresponds to a base package in Dojo. For example, com.ibm.lconn.core.web.resources corresponds to the Dojo package lconn.core. Open the JAR file and locate the JavaScript file to override.
For example:
- Find com.ibm.lconn.core.web.resources_*.jar inside the deployed Common.ear file.
- Open the JAR file with a zip program.
- Extract the resources/SearchBar.js file to a location on your hard drive.
- Copy the source file to the customization directory or create an empty file in the correct location.
For IBM Connections to detect an override JavaScript file, the path of the file in the customization directory must match the name of the Dojo JavaScript module. The name of a module is determined by its path and vice versa. You can convert the name of a module to a path by replacing all the periods in the module name with slashes.
For example:
- Use a text editor, open the SearchBar.js file from the example in step 1.
- Look for a line similar to the following one at the start of the file:
dojo.provide("lconn.core.SearchBar");This line indicates that the name of the module is lconn.core.SearchBar.
- Copy SearchBar.js to the following directory:
customizationDir/javascript/lconn/core/Ensure that you use the correct case in case-sensitive file systems.
- Make the required changes to the file.
Changes saved to the file take effect immediately. IBM recommends that you never directly edit the files in your JavaScript customization directory on a production system. Instead, copy them in with an automated task. For example:
- Edit SearchBar.js to put an alert statement at the start of the file:
alert("This file has been customized.");
- Clear your browser's cache and refresh your IBM Connections web application.
The SearchBar.js file in the example is used by most of the applications, so when you refresh the page after clearing your browser cache, the alert added in the previous step should immediately pop up.
What to do next
To remove a JavaScript customization, delete the file from the customization directory and refresh your browser cache. Most applications have a very short cache (20 seconds) before they check again for new JavaScript customizations. For regular users who are not clearing their browser cache, your changes are only guaranteed to be active after you update the version stamp in LCC.xml and restart each affected application, including Common.ear. For more information, see Required post-customization step.
Extend JavaScript in IBM Connections
You can extend the JavaScript files used by IBM Connections when you want to add new functionality, widgets, or scripts to the product.
IBM Connections uses the shared resources WAR file, connections.web.resources.war, to aggregate and serve all JavaScript files. This WAR file is based on the OSGi extension model, which allows new capabilities to be added to a system via a plug-in mechanism. IBM Connections leverages this mechanism to provide the following capabilities:
- Expose custom JavaScript in a new Dojo module package
- Ensure that custom JavaScript loads when another module is loaded
To extend the JavaScript used in IBM Connections, first you must put your JavaScript files into an OSGi bundle (a JAR file with a special MANIFEST.MF file and some directories), and deploy the bundle into IBM Connections. Then, you need to link your JavaScript to ensure that it is loaded at the same time as the rest of the JavaScript in IBM Connections.
The easiest way to extend the JavaScript used in IBM Connections is to start with a sample bundle, add files to it, and deploy it in your IBM Connections environment.
If you want to change a file in the JAR file, stop the Common.ear file, update the JAR file, and then restart the EAR file. You can also unzip the JAR file into a new directory with the same name as the JAR file minus the .jar extension and make changes there, but you might have to restart the EAR file to see new versions of files appear.
Complete the following steps to extend the JavaScript used in IBM Connections using a sample bundle.
- Download the following sample bundle:
com.mycompany.example_1.0.0.jar
- Deploy the sample bundle.
- Locate your web resources provisioning directory for IBM Connections. The installer creates this directory at the following location:
CONNECTIONS_HOME/data/shared/provision/webresourcesThis directory contains many different JAR files, including at least one for each application, and utility bundles.
- Copy the sample bundle into the webresources directory.
- Restart the Common.ear file.
- Enter the following URL in your web browser:
http://server/connections/resources/web/com.mycompany.example/readme.txtYou should see the readme.txt file from the JAR in the resources/ folder display in the browser window.
- Add files to the sample bundle.
You can update the JAR file by adding new files. Put the files in the resources/ directory and view the contents by entering the following URL in your web browser:
http://server/connections/resources/web/com.mycompany.example/
- Stop Common.ear.
- Add your new JavaScript, HTML, image, or CSS files into the JAR file in the resources/ directory.
- Restart Common.ear.
- Clear your browser cache and access the new file directly by viewing it on your server.
For example:http://server/connections/resources/web/com.mycompany.example/newfile
- Ensure that the JavaScript is loaded when an IBM Connections module is loaded by updating the plugin.xml file to add a new <dojoModuleBinding> element. Set the "to" attribute in the binding to the name of the class to load your custom files after.
Most customizations need to be loaded at a certain time, along with other IBM Connections JavaScript. To ensure that your module is loaded, you must update plugin.xml to add a new <dojoModuleBinding> element.
In the example, "com.mycompany.example.demonstration" (demonstration.js) is bound to a file that all IBM Connections applications load, bundle_common.js. Whenever any application loads bundle_common.js, demonstration.js will also be loaded. The demonstration module prints a line to the Firebug console, which you can see in IBM Connections.
- Restart Common.ear to pick up the changes in the plugin.xml file.
- Change the name of the bundle.
- In the META-INF/MANIFEST.MF file, change Bundle-SymbolicName and, optionally, Bundle-Name.
Do not remove the ;singleton:=true text at the end of the line. This text is necessary for the plugin.xml file to get parsed and your JavaScript to be loaded.
- Change each Dojo JavaScript module in the resources/ folder to have a different base package. Alternatively, you can change the <alias> in plugin.xml to define an arbitrary base package.
When IBM Connections tries to look up your modules, it will first look for the base package (the name of the bundle, or the <alias value="" /> defined in plugin.xml) and then look inside the resources/ folder. However, the dojo.provide(...) statement inside each JavaScript file must match the expected name or IBM Connections cannot load your JavaScript.
- Change the name of the JAR file to new-name_version.jar.
When you rename the JAR file, ensure that the version that is described by Bundle-Version in MANIFEST.MF matches the version at the end of the JAR name. If they do not match, IBM Connections will not be able to load your JAR file.
- Remove the old JAR file from the webresources directory, and copy your new JAR file into the directory.
Optional: You can also reference custom bundles that are saved to another location outside your customization directory by using a customresources.link file that is saved in your webresources directory. The customresources.link is a text file that specifies a list of additional directories to search. You can specify as many directories as you like in the file, for example:
/local/opt/myCustomBundles C:\customBundles
- Restart Common.ear.
- Check your changes by accessing the following URL from your browser. You should see the same file that is in the JAR file.
http://server/connections/resources/web/new name/readme.txt
Extend JSP files with custom tags
You can extend IBM Connections by adding your own custom JSTL tags to meet your company's needs.
- Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.
- Copy the .jsp file from the WAR file of one of the applications that you would like to customize. You can access the file from the following directory:
WAS_HOME/profiles/profile_name/installedApps/cell_name/ application_name.ear/application_name.war/nav/templateswhere:
For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.
- WAS_HOME is the directory to which you installed IBM WebSphere Application Server.
- profile_name is the profile to which you installed one of the IBM Connections applications.
- cell_name is the cell to which you installed the application.
- application_name.ear is the EAR file name for the application.
- application_name.war is the WAR file name for the application.
- Paste the .jsp file into the appropriate subdirectory in the customization directory.
See Determining
...where to save your customizations for more information about locating your base customization directory.
- Copy the content of the .tag file containing the custom tags to add, then open the .jsp file and paste the content where it needs to be rendered.
- Save and close the .jsp file.
- To test your changes, refresh the web browser, and then access the page from the product.
- Optional: If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes. For more information, see Enabling and disabling customization debugging.
- See Required post-customization step for information about how to apply your changes permanently.
Customize notifications
The content of the notifications sent by IBM Connections is defined in templates that are processed by the FreeMarker engine.
You can customize notifications by modifying the existing template files or by replacing the files with custom templates that you create yourself. You can also edit the text strings and images used in the notifications.
Customize standard notifications
You can customize the standard email messages that are sent by the applications in IBM Connections, including the auto-generated notifications that are generated by the News application. The content of individual notifications is defined in templates that are processed by the FreeMarker engine. You can customize the content of notifications by modifying the existing template files or by replacing the files with custom templates that you create yourself. You can also modify the notification properties files to add custom strings to the templates and modify the images used in the notifications.
Customize the content of an email message by completing the following steps.
- To customize an existing template file:
- Locate the FreeMarker template that corresponds to the notification to customize. For more information about the notification types used in IBM Connections, see Configuring notifications.
Notifications are stored in the following location:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You can find folders for each application in this location and a shared resources folder. Look for the FreeMarker template for the notification to customize in the relevant application folder. When you find the template to modify, open the .ftl file in a text editor.
- Make your customizations to the template as needed. For information about editing the templates, refer to the FreeMarker documentation on the following web page: http://freemarker.sourceforge.net/docs/index.html
The FreeMarker version currently used is 2.3.15.
- Save your changes and then close the file.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
- To edit the text strings used in the notification:
- Use a text editor, open the notification_language_code.properties files in one of the following directories and make your changes:
- Application-specific strings:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/application_name/resources/nls
- Shared strings:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/resources/nlsWhere language_code is the locale of the language. For example, notification_fr.properties.
Tip: To see where each string that you are editing is used, look at the .ftl template files in the same directory and check the statements with the following format:u.resource("key")...where key is the key of a translated string in the resource bundle notification_language_code.properties files. Note that the notification framework will look in the application-specific resources folder before moving to the shared strings in the shared resources folder.
- Save your changes and then close the files.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
- To customize the images used in the notification:
- Locate the images in one of the following directories:
Note that the application-specific images are loaded before images in the shared location. If an image is loaded from the application-specific folder, the shared location is not checked for that image.
- Application-specific images:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/application_name/resources/images
- Shared images:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/news/notifications/resources/images
- Replace any image to customize with your own version using the same file name. The images are sent as MIME attachments to each email digest, so ensure that the image size is small.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
Customize email digests
You can customize the email message that is sent to users as part of the daily and weekly email digests. The content of the daily and weekly email digests is defined in templates that are processed by the FreeMarker engine. These templates are used for each recipient of the daily or weekly email digest. You can customize the content of the email digests by modifying the existing template files or by replacing the files with custom templates that you create yourself. You can also modify the notification properties files to add custom strings to the email digests and modify the images used in email digests.
The property named emailDigestBean is passed to the daily and weekly email digest templates. This property stores information about the digest related to email digest recipient. It is an instance of the class IEmailDigestStoriesContainer. For more information about the IEmailDigestStoriesContainer class, refer to the following web page:
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/IBM_Connections_3.0.1_Email_Digest
Customize the content of the email message used for the daily and weekly email digests by completing one or more of the following steps.
- To customize the existing template files:
- Use a text editor, open the dailyDigest.ftl and weeklyDigest.ftl template files from the following location:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/news...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
- Make your customizations to the templates as needed. For information about editing the templates, refer to the FreeMarker documentation on the following web page:
http://freemarker.sourceforge.net/docs/index.htmlThe Freemarker version currently used is 2.3.15. The main templates used are dailyDigest.ftl and weeklyDigest.ftl. To change the styles and structure of both weekly and daily digests, make your customizations to the style.ftl file in the aggregated folder.The aggregated folder is shared by the daily and weekly digest and is specific to them. The folder is located in notifications/news/aggregated.
- Save your changes and then close the files.
- Synchronize all the nodes using the IBM WebSphere Application Server Integrated Solutions Console.
- Stop and restart the News application.
- To use your own custom templates instead of the default templates:
- Create the templates by following the instructions provided in the FreeMarker documentation on this web page:
http://freemarker.sourceforge.net/docs/index.htmlThe Freemarker version currently used is 2.3.15.
- Save the templates in the following directory:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/news
- Register the custom templates in the notification-config.xml file.
- Open a command prompt, and then change to the following directory on the system on which you installed the Deployment Manager:
app_server_root/profiles/dm_profile_root/bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on
Windows:
C:/Program Files/IBM/WebSphere/AppServer/profiles/Dmgr01/binYou must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
- Enter the following command to start the wsadmin client:
- AIX or Linux:
./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
- Microsoft
Windows:
wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.
- In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
For example:
- AIX or Linux:
./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879
- Microsoft
Windows:
wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879
- Access the IBM Connections configuration files:
execfile("connectionsConfig.py")
- Check out the notification-config.xml file :
LCConfigService.checkOutNotificationConfig("temp_dir","cell_name")...where:
- temp_dir is the temporary directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The temporary directory must grant write permissions or the command will not run successfully.
- cell_name is the WebSphere Application Server cell to which you installed the application for which you are enabling mail. This argument is case-sensitive, so type it with care.
- Use a text editor, open the notification-config.xml file from the temporary directory to which you checked it out.
- Look for the following section of code and replace the value of the ftl property for each digest type with the file name of your new templates:
<type name="dailyDigest" notificationType="FOLLOW"> <channel name="email" enabled="true"> <property name="sender">news_admin@emea.relay.example.com</property> <property name="ftl">dailyDigest.ftl</property> </channel> </type> <type name="weeklyDigest" notificationType="FOLLOW"> <channel enabled="true" name="email"> <property name="sender">news-admin@emea.relay.example.com</property> <property name="ftl">weeklyDigest.ftl</property> </channel> </type>
- Save your changes and close the notification-config.xml file.
- Check the configuration files back in :
LCConfigService.checkInNotificationConfig("temp_dir","cell_name")
- To exit the wsadmin client, type exit at the prompt.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart all the IBM Connections application servers.
- To edit the text strings used in the email digest:
- Use a text editor, open the notification_language_code.properties files from one of the following directories and make your changes:
Where language_code is the locale of the language. For example, notification_fr.properties.
- News strings:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/news/resources/nls
- Shared strings:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/resources/nlsTip: To see where each string that you are editing is used, look at the .ftl template files in the same directory and check the statements with the following format:u.resource("key")...where key is the key of a translated string in the resource bundle notification_language_code.properties files. Note that the notification framework will look in the application-specific resources folder before moving to the shared strings in the shared resources folder.
- Save your changes and then close the files.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
- To customize the images used in the email digest:
Email digests include an IBM Connections logo image and individual application icons.
- Locate the images in the following directory:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/resources/images
- Replace any image to customize with your own version using the same file name. The images are sent as MIME attachments to each email digest, so ensure that the image size is small.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
Customize shared resources for notifications
You can customize the common style and structure documents that are used by notifications in IBM Connections. The notifications used in IBM Connections share common style and structure documents, and are stored in the same location, allowing you to write your customizations once for all notifications, except for email digests. For information about customizing the daily and weekly email digests that are sent to users, see Customize email digests.
You can customize notifications in IBM Connections by updating the shared resources stored at this location:
app_server_root/profiles/dm_profile_root/config/cells/cell-name/LotusConnections-config/notifications/resourcesTable 37. Shared resources for notifications
Resource Description images Folder containing all the shared images referenced in templates. nls Folder containing all localized strings shared between templates. commonEEStructure.ftl Template used for generating the Embedded Application MIME part. commonHeader.ftl Used in templates to import common .ftl files into scope. Uses acquisition look-up. commonStructure.ftl Holds the main FreeMarker macros and functions that make up the individual notification components. For example, action, metadata, header, and footer. commonStyle.ftl One CSS style file used in all individual notification templates. commonUrlUtil.ftl Specific utility functions for URL link handling. Contains the linkify function. commonUtil.ftl Provides a common set of utility functions. Note on Freemarker acquisition: The template files that exist in the resources folder can also be stored in the notifications folders for specific applications. For example, if you want to customize Activities templates, you place commonStyle.ftl at the following location:
app_server_root/profiles/dm_profile_root/config/cells/cell-name/LotusConnections-config/notifications/activities/resourcesSaving the style file in this location allows the Activities templates to pick up different styles that override the default shared ones. Acquisition look-up ensures that templates are imported to a directory that is local to the currently generated template. If the templates do not exist, the parent folders are scanned and the templates from the shared resources folder are loaded. Similarly, the images and nls resources can be stored in a directory that is local to an application folder. The notification framework ensures that local resources are checked and used first before checking the shared resources location.
To customize the content of a shared resource, complete one or more of the following steps.
- To customize the existing template files:
- Make your customizations to the templates as needed. For information about editing the templates, refer to the FreeMarker documentation on the following web page:
http://freemarker.sourceforge.net/docs/index.html
The FreeMarker version currently used is 2.3.15.
- Save your changes and then close the files.
- Synchronize all the nodes using the IBM WebSphere Application Server Integrated Solutions Console.
- Synchronize all the nodes using the Integrated Solutions Console.
- To edit the text strings used in the notifications:
- Use a text editor, open the notification_language_code.properties files in the following directory and make your changes:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/resources/nls...where language_code is the locale of the language. For example, notification_fr.properties.
Tip: To see where each string that you are editing is used, look at the .ftl template files in the same directory and check the statements with the following format:u.resource("key")...where key is the key of a translated string in the resource bundle notification_language_code.properties files. Note that the notification framework will look in the local application resource folder before moving to the shared strings in the shared resources folder.
- Save your changes and then close the files.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
- To customize the images used in notifications:
- Locate the images in the following directory:
app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/resources/images
- Replace any image to customize with your own version using the same file name. The images are sent as MIME attachments to each email digest, so ensure that the image size is small.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
- To customize notifications for a specific application:
- Move the resource to customize from the location app_server_root/profiles/dm_profile_root/config/cells/cell-name/LotusConnections-config/notifications/resources to the resources folder contained in the application-specific notifications folder. For example, notifications/activities/resources.
- Save your changes and then close the files.
- Synchronize all the nodes using the Integrated Solutions Console.
- Stop and restart the News application.
Customize a blog theme
Customize a blog theme to change the look of a blog. Or create a new theme and make it available to your blog users.
The theme for a blog controls the look and the layout of the blog. You can customize the theme for a blog to change the look of it by editing the templates files that make up the theme. For example, you might add a corporate logo or change the background color for a theme. You should be comfortable editing HTML files and cascading style sheets (CSS files) to modify a blog theme. Also note the following:
- To make a site-wide change, edit the Blogs Homepage theme.
- You can extend a theme so it can use a different color scheme or different content but use the same templates.
- You can create a new theme based on an existing theme and add it to the list of available themes that your users can choose.
CAUTION:The ability for blog owners to customize their blog themes is disabled by default. Although the setting to enable this application is on the Configurations page on the Administration tab, we strongly recommend you do not enable it, because end-user theme customization is not a supported application. End-user customized theme migration will be the customer's responsibility for future releases. The setting is provided for backward compatibility with the IBM Connections 1.x releases. If your end users customized themes in an earlier release, enable this application so they can retrieve their customized themes.If you customized blog themes in a previous release of IBM Connections, there is no migration path provided for importing your changes into IBM Connections 4. Before upgrading to IBM Connections 4, ensure that you review and make a note of your existing customizations to blog themes so you can verify them post-migration and rework if necessary.
The following topics describe how to access and modify the templates for a theme and how to make a new theme available for use.
Standard Blogs theme components
A Blogs theme is made up of a collection of templates, graphics, and macros that you can modify. This topics describes some of the basic theme components.
Theme templates
Although the templates that make up a theme can vary, each theme contains some required templates (you cannot change the template name or delete the template from the theme) and some standard templates. Your theme may contain some or all of the following:
Table 38. Common theme template files
Template Description weblog A required template that defines the main page of your blog. The weblog template specifies blog components such as a links to entries, feed links, a calendar, and paging controls, _day A required template that defines how each day's worth of blog entries is displayed on the main page of your blog. _css The cascading style sheet (CSS) used by the blog. The CSS controls the fonts and spacing that structure the blog pages. _header Controls variables such as text and background color, and image placement. _footer Controls items that display in the footer of a blog, such as links to other web pages. _options Used to enable applications such as the inclusion of Bookmarks. This template should not be edited. _myfavorites defines the look of the My Recommendations page. allblogs Look of the Blogs Listing view. mynotificationreceived Look of the Notifications Received list on the My Updates page. mynotificationsent Look of the Notifications Sent list on the My Updates page. myupdates Look of the My updates page.
Theme macros
Some theme content, for example the comment form and paging controls, is not customizable via the theme templates. This content is specified in a site-wide macro file: WAS HOME/profiles/profile_name/installedApps/Cell Name/Blogs.ear/blogs.war/WEB-INF/velocity/weblog.vm. You can customize these macros, but be aware that changes made to the macros affect all Blogs themes.
Theme graphics
Most image files are found in the common, core images directory: <WAS_home>/profiles/<profile_name>/installedApps/<cell_name>/Blogs.ear/blogs.war/nav/common/styles/images.
Connections Blogs include an images directory as well: WAS HOME/profiles/<profile_name>/installedApps/<Cell Name>/Blogs.ear/blogs.war/roller-ui/images. Changes to these images will affect all Blog and Homepage themes, although additional images can be added and referenced without affecting other themes.
Change the theme used in a blog
A theme controls the layout and color-scheme of your blog. When you create a new blog, you choose from one of the built-in themes.
You must be a blog owner or administrator to edit the blog theme.
This application is disabled by default for blog users. To enable it for blog owners, site administrators must enable it on the Administration Configuration page. It's recommended that site administrators handle theme customization. Change the theme to update the look of your blog.
- From the My Blogs page, click Sets for the blog you want to customize.
- Click Theme.
- Select a different theme for the blog. A preview window shows you what your blog will look like with the new theme.
- Click Save to apply the new theme.
- Optional: Select Customize to alter the theme for the selected blog.
Customize a theme requires that you edit HTML template files. Do not customize unless you are comfortable working with HTML. When you click the Customize button the templates that define your current theme will be copied into your blog where you can edit them from the Templates page. Also note that you can only customize one theme at a time. Clicking Customize overwrites any previous customization.
Customize a blog template
A blog theme is made from a collection of templates that control the look of the blog. You can customize theme templates and save a new theme for a blog.
You must be a blog owner or administrator to edit blog templates.
Blog-level customization is turned off by default. If you enable this feature and allow users to customize their blog templates, the end user is then responsible for updating the templates following a migration. Some customized templates may not work after migration. You can edit the templates that define the layout, colors and fonts of your blog. Before you can edit the templates for the theme, choose to customize the theme. Customize theme templates involves editing the source HTML for the template files. You should only do this if you are comfortable editing HTML files.
Restriction: Only modification to the HTML is supported. Do not change any calls that retrieve data from the blog system or your blog may fail to work.
- From the My Blogs page, click Sets for the blog you want to customize.
If you are the Blogs site administrator and want to edit the theme for the Blogs home page, find the blog which serves as Blogs Homepage on the Site Sets section, on the Configuration page of the Administration tab. You can customize the theme for the home page in the same way you customize the theme for any blog.
- Click Theme.
- Choose the theme you want to customize and click Customize. The templates for that theme are now available for you to edit from the Templates page. Note that the Customize button is only available if the Allow custom themes setting is enabled for the site.
- Click Templates. The templates for the current blog display.
- Click Edit to modify a template. See the examples for guidelines about how to make common customization changes.
- Save changes you make to the template.
- Click Remove to remove a template. You cannot delete a required template.
Example: Add a logo to a blog theme
Customize a theme by adding a logo to the design.
You must be a blog owner or administrator to customize the theme for the blog and the setting to customize a theme must be enabled for the site. These steps illustrate how to add a logo, or any image, to a blog theme.
- From the My Blogs tab, click Sets for the blog to add a logo to.
- Click Theme.
- Choose the theme you want to customize and click the Customize button. The templates for that theme are now available for you to edit from the Templates page. Note that if custom themes are not enabled for the site, the Customize button will not display.
- Click Templates. The templates for the current blog display.
- Click the Edit icon next to the weblog template to open the template file for editing.
- Locate the string <!-- content --> using the browser Find option and add your <img> tag after the line that begins with <a id="mainContent" name="mainContent"></a>. For example:
[ <!-- content --> <!--<td valign="top">--> <a id="mainContent" name="mainContent"></a> <img src="http://www.mycompany.com/logo.gif"/> <div id="content"> ]
- Save changes you make to the template. When you open your blog, you will see the logo displayed with the blog title.
Extend a theme
You can extend an existing theme to use a different color scheme or to display different content.
Templates can be reused in multiple themes and still maintain a different color scheme or content by using the _options.vm file. The _options.vm file stores variables that can be used in the other templates in order to include or ignore content or file imports. Include the _options.vm file in the weblog.vm template in order to set values in the _header.vm template.
Example
The Khaki_Standard theme reuses the blog theme templates, but contains an _options.vm file with one line: #set ($lookAndFeel = "khaki")
The _header.vm checks for the $lookAndFeel variable, and includes the appropriate .css file:
#if ($lookAndFeel) <link rel="stylesheet" type="text/css" href="$url.site/roller-ui/styles/${lookAndFeel}.css" /> #endThe result is two themes, with two different color schemes, based on the same set of templates.
Making a custom theme available to your users
You can create custom themes and make them available to your blog users. Customize themes requires experience editing HTML and CSS files. Follow these steps to make a custom theme available to your users from the Blogs theme field on the Create Blog form.
To define a theme.
- Create a copy of the existing default theme.
For example, to create a new corporate theme: Copy the blog theme directory from WAS HOME/profiles/AppSrv Name/installedApps/Cell Name/Blogs.ear/blogs.war/themes/blog/ to the following directory: customization_dir/blogs/themes/corporateBlogTheme/
The customization_dir folder is the default directory in which customized files are stored. This location is defined during installation, and is saved as a WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. By default, the variable is set to Connections_installdir\data\shared\customization.
- Modify or add template files to create the desired look, layout, and content for your theme.
- Create an image to display as a preview thumbnail so that users can see what the theme looks like from the Create Blog form. The naming convention is sm-theme-blog_directory_name.png. For example, the preview image for the default blog theme is named sm-theme-blog.png.
- Edit the Blogs string resource file com.ibm.lconn.blogs.strings.ui_xx.properties and add a new string for the name of your new theme, as follows:
- Add the com.ibm.lconn.blogs.strings.ui_xx.properties file to customization_dir/strings.
- Locate the #themes section of the file and enter the theme directory name in the format ventura.theme.yourThemeDirectoryName. For example, ventura.theme.MyTheme=My Theme.
Add the new theme directory name to the ui.properties file makes the new theme work in English. For international support, edit the ui_language.properties file,
...where language is the ISO country code associated with the language in which you want to specify the custom label. For example, to support Chinese, you should also edit the ui_zh.properties file.
- Copy the default style sheet, defaulttheme.css from its location in WAS HOME/profiles/AppSrv Name/installedApps/Cell Name/Blogs.ear\blogs.war\roller-ui\styles. Make any changes you want to the theme, then save it to the same directory with the name of your new theme: <myNewThemeName>.css.
Delete a Blogs theme
Delete a Blogs theme if you do not want it to be available to your users.
You can delete either a default theme or a custom theme.
- To remove a default theme, delete the theme from the folder containing the default themes: WAS HOME/profiles/AppSrv Name/installedApps/Cell Name/Blogs.ear/blogs.war/themes.
- To remove a custom theme, delete the theme from the folder containing the custom themes: customization_dir/blogs/themes/.
If you delete a theme that is use, users will get a Page Note Found error when they try to access the blog. The blog owner can correct this by selecting a new theme for the blog.
Add a custom theme to Communities
Community owners can customize the appearance of a community by choosing from a selection of themes that change the colors used in the community. Administrators can modify or add to the selection of default themes provided with Communities by customizing the existing themes, or by defining custom themes and adding them to the Communities configuration file, communities-config.xml.
If you are performing other customizations that apply to all the applications in IBM Connections, for example, if you are customizing the header and footer used in the product, you might need to alter or customize the themes available in Communities to ensure that they work as expected in your environment. Consider adding themes that match the customizations that you have made in other areas, for example, themes that match your customized header and footer.
To configure community themes to work with your corporate branding and best meet the needs of your organization, consider the following options:
- No themes defined. If you remove all the community themes defined in the communities-config.xml file, your corporate branding is applied throughout the IBM Connections applications, and community owners are no longer given the option of choosing a theme when creating or editing a community.
- Multiple themes defined. If multiple themes are defined in the communities-config.xml file, community owners can apply one of these themes when creating or editing a community. That theme then takes precedence for that community over any global customizations or branding that have been applied to all the applications.
- One theme defined. If the communities-config.xml file contains a single theme, any corporate customizations are applied to pages that are not community-specific, for example, the Public Communities page, and that single theme is applied to all community-specific pages. Because only one theme is available, the option to choose a theme does not display when users are creating or editing a community.
If you customized community themes in a previous release of IBM Connections, there is no migration path provided for importing your changes into IBM Connections 4. Before upgrading to IBM Connections 4, ensure that you review and make a note of your existing customizations to community themes so you can verify them post-migration and rework if necessary.
Related
Administer Communities
Define a community theme
To define a custom theme for Communities, you typically start by copying an existing theme. The stylesheets for Communities are compartmentalized so that the color information is stored separately from the overall structure of the page. This separation makes it easy to change the page's color without disrupting the layout.
To test your style changes, you might find it helpful to use a web development tool such as the Mozilla Firefox browser extension, Firebug. Firebug allows you to modify colors and styles dynamically on the page so that you can preview what the page looks like when your new style is applied to it.
To define a theme.
- Create a copy of the existing default theme.
For example, to create a new corporate theme:
- Copy the com.ibm.oneui3.styles_build stamp.jar file from app server\installedApps\madoneNode03Cell\Common.ear\connections.web.resources.war\WEB-INF\eclipse\plugins\ to a temporary location.
Here is an example of the path where you might find the JAR file: /local/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins
If the installDir/customizationDir/themes/ directory does not already exist, create it now.
The customizationDir folder is the default directory in which customized files are stored. This location is defined during installation when it is saved as a WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH. By default, the variable is set to installDir/data/customization. Find it by logging into the WebSphere Application Server Admin Console, and navigating to Environment > WebSphere Variables. Look for the CONNECTIONS_CUSTOMIZATION_PATH. For example, it might look like this: /local/IBM/Connections/data/shared/customization.
- Rename the new directory to corporateTheme. This gives you a directory path that looks like this one: installDir/customizationDir/theme/corporateTheme.
- Rename the defaultTheme.css stylesheet inside this new directory to corporateTheme.css. Rename the defaultThemeRTL.css stylesheet inside this new directory to corporateThemeRTL.css.
Notes:
- The defaultTheme directory contains stylesheets named defaultTheme.css and defaultThemeRTL.css. In other theme directories, the stylesheets are named themeNameTheme.css and themeNameThemeRTL.css.
- The new themes must be saved in the common customization directory so they can be used from all the applications
- Update the corporateTheme.css file and other CSS files in the new directory as needed. The corporateTheme.css file is now the main stylesheet where you'll be making changes. For example, you might want to modify the color settings to match your organization's corporate colors.
If you're using a tool such as Firebug to test your changes, be sure to copy the settings that you've modified into your new CSS files.
- Save your changes.
- To associate a thumbnail image with your custom theme, upload a theme.jpg file to the following directory:
installDir/customizationDir/communities/images/ This image will be displayed in the Theme Palette.
What to do next
After defining a new theme, you need to add it to the Communities configuration file, communities-config.xml. For more information, see Add a theme to the Communities configuration file.
Add a theme to the Communities configuration file
After defining a custom theme, you need to add it to the Communities configuration file, communities-config.xml.
To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. The list of themes displayed in the theme palette in Communities comes from list of themes defined in the Communities configuration file, communities-config.xml. When you define a new theme, add a corresponding theme entry to the configuration file for it to display in the user interface. The placement of the theme in the configuration file list matches its placement in the Communities theme palette. Typically, you might add new themes to the end of the list, but if you want to make your new theme the default community theme, you need to add it to the beginning of the list. This placement means that the theme is used whenever another theme has not been explicitly set.
To add a theme to the Communities configuration file, complete the following steps.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Communities Jython script interpreter.
- Use the following command to access the Communities configuration files:
execfile("communitiesAdmin.py")If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Check out the Communities configuration files :
CommunitiesConfigService.checkOutConfig("working_directory", "cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied. The files are kept in this working directory while you make changes to them.
AIX and Linux only: The directory must grant write permissions or the command will not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is required. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommServerNode01Cell")
- Open communities-config.xml in a text editor.
- Add a new <comm:theme> element to include the properties for the new theme in the list of themes that are already defined in the file:
For example:
<comm:theme> <comm:themeUuid>corporate</comm:themeUuid> <comm:displayNameKey>label.theme.name.corporate</comm:displayNameKey> <comm:isScriptKey>false</comm:isScriptKey> <comm:cssUrl>/themes/corporateTheme/corporateTheme.css</comm:cssUrl> <comm:cssRtlUrl>/themes/corporateTheme/corporateThemeRTL.css</comm:cssRtlUrl> <comm:thumbnailUrl>/images/corporate.png</comm:thumbnailUrl> </comm:theme>...where:
- <comm:themeUuid> is the unique identifier of the theme that is stored in the database when the theme is selected. It should not contain spaces or special characters. It must be 36 characters or less.
- <comm:displayNameKey> is the resource key for the display name. For information about how to create property strings for the displayNameKey, see Specifying the name of a custom theme.
- <comm:isScriptKey> is set to true when the display name is found in a JavaScript resource file.
- <comm:cssUrl> is the location of the theme stylesheet.
- <comm:cssRtlUrl> is the location of the theme stylesheet for right-to-left languages, such as Arabic and Hebrew.
- <comm:thumbnailUrl> is the location of the thumbnail image that is displayed in the Theme Palette. The image must be included in the following location:
/customization/communities/images/
- Save the communities-config.xml file.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for your configuration changes to take effect. You must also stop and restart the Communities server. See Applying property changes in Communities for information about how to save and apply your changes.
What to do next
- Test your changes by refreshing the web browser.
- When you are ready to make the custom theme available to others, refer to steps 6-8 of Customize the user interface for information about how to publish your changes and make them permanent.
Set the name of a custom theme
After adding a custom community theme to the Communities configuration file, specify the name of your new theme by adding a custom string that contains the theme label to IBM Connections.
To specify the name of a custom community theme, complete the following steps.
- Create a properties file containing the string for the community theme name and add it to the customization directory for Communities. For instructions about how to name the file, see step 1 of the topic, Add custom strings for widgets and other specified scenarios.
For example: customization/strings/com.ibm.lconn.communities.strings.ui.properties
If you have an existing file in this location, add your new string to this file rather than creating a new file.
- Open the properties file from the customization subdirectory for Communities and add the name of the custom theme that you defined in the <comm:displayNameKey> element in the communities-config.xml file.
For example:label.theme.name.corporate=Corporate Theme
- Save your changes and close the properties file.
- To test your changes and to force all user web browsers to refresh cached content and display your changes, complete steps 5-8 of the topic, Customize product strings.
- Restart the Communities server.
Remove community themes
If you want to make a specific community theme unavailable to your users, or you want to disable all community themes, you can do so by editing the Communities configuration file, communities-config.xml.
To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. The list of themes displayed in the theme palette in Communities corresponds to the list of themes defined in the Communities configuration file, communities-config.xml. If you want to remove a specific theme from the palette, you can do so by removing the theme or commenting out the relevant section in the configuration file. Or, if you have applied corporate branding to all of IBM Connections, and you want to disable community theming so that the branding applies to all communities, you can do so by removing all of the theme information from the communities-config.xml file. When you remove all of the theme information, the option to choose a theme no longer displays when users are creating or editing communities.
To remove community themes, complete the following steps.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Communities Jython script interpreter.
- Use the following command to access the Communities configuration files:
execfile("communitiesAdmin.py")If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Check out the Communities configuration files :
CommunitiesConfigService.checkOutConfig("working_directory", "cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied. The files are kept in this working directory while you make changes to them.
AIX and Linux only: The directory must grant write permissions or the command will not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is required. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommServerNode01Cell")
- Open communities-config.xml in a text editor.
- Do one of the following:
- To remove a specific theme, find the <comm:theme> element that corresponds to the theme to remove, and either delete that section or comment it out.
For example:
<!-- <comm:theme> <comm:themeUuid>corporate</comm:themeUuid> <comm:displayNameKey>label.theme.name.corporate</comm:displayNameKey> <comm:thumbnailUrl>/images/CorporateTheme.jpg</comm:thumbnailUrl> </comm:theme> -->
- To remove all community themes, delete or comment out all of the <comm:theme> elements in the file.
- Save the communities-config.xml file.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for your configuration changes to take effect. You must also stop and restart the Communities server. See Applying property changes in Communities for information about how to save and apply your changes.
Use Profiles and Communities business cards
Extend your web application by integrating the Profiles and Communities business cards in to the application.
The Profiles business card provides a snapshot of your profile information and contact details. You can adapt the card to change the information that it includes. For example, you can add or remove links, and customize the contact and location information that displays on the card. The Communities business card displays the image associated with the community, and includes key links that allow users to quickly navigate to a community from the application in which the card is deployed.
The use of JavaScript Object Notation with padding (JSONP) technology in the Profiles and Communities business card will be deprecated in future releases. Although JSONP will continue to be supported, if you are integrating the business card in to your web application and you want to prevent JSONP data from being transmitted by IBM Connections, you must use an Ajax proxy.IBM WebSphere Application Server Application Pack for web 2.0 includes an Ajax proxy. For more information, go to: http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.web20fepParent.multiplatform.doc/welc6tech_web20.html
IBM WebSphere Portal Server also includes an Ajax proxy. For more information, go to: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/index.jsp?topic=/com.ibm.wp.ent.doc_v6101/dev/ajax_proxy_cfg.html
Common configuration properties
Integrate the Communities business card
Include the Communities business card in your web application so that users can quickly navigate to a community from the application.
The CSS files loaded with the Communities business card do not include font style information. To ensure that the business card appears fully integrated with your web application from a visual perspective, define your own font styles globally so that the styles used in your application are also applied to the business card
The use of JavaScript Object Notation with padding (JSONP) technology in the business card will be deprecated in future releases. Although JSONP will continue to be supported, if you are integrating the business card in to your web application and you want to prevent JSONP data from being transmitted by IBM Connections, you must use an Ajax proxy.
For information about how to configure the Communities business card on a Lotus Domino® 8.5 server, see Configuring the Communities business card on a Domino server. The Communities business card displays basic community information, such as the name of the community, the image associated with the community, and the links for the widgets associated with the community. By including the card in your web application, you enable users to access a community directly from your application using the links in the card.
The CSS files loaded with the Communities business card do not include font style information. To ensure that the business card appears fully integrated with your web application from a visual perspective, define your own font styles globally so that the styles used in your application are also applied to the business card. To add the Communities business card to your web application:
- Include the following reference to the semanticTagService.js file in your code:
<script type="text/javascript" src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js"></script>Notes
- The body element must exist and be instantiated before the script's JavaScript executes, thus if the script resource is included within the head element of your html code, it must use the defer attribute (defer="defer") so that it executes after the page is loaded. Otherwise, the script resource request must be included within the body element.
- The business card uses Dojo 1.4. If Dojo 1.4 is already included in your application, add the ?inclDojo=false URL parameter to the JavaScript include as follows, otherwise the business card will not work.
<script type="text/javascript" src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js?inclDojo=false"></script>
- The business card can be loaded with or without CSS. If you already have the IBM Connections CSS files loaded in your application and do not want to include the CSS again, add the loadCssFiles=false parameter to the JavaScript include like this:
<script type="text/javascript" src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js?loadCssFiles=false"></script>
- Use and modify the following code to render the card with community details:
<span class="vcomm X-community-display-inline"> <span class="name" style="display:none;"><community_name></span> <span class="uuid" style="display:none"><community_uuid></span> <span class="selectedWidgetId" style="display:none;"><widget_id></span> </span>...where:
For example:
- <community_name> is the name of the community. This parameter is a text string.
- <community_uuid> is the UUID of the community.
- <widget_id> is a text string that corresponds to the widgetDefId of the widget that has been added to the community. This text string is used to highlight the menu item in the navigation bar. The <widget_id> element is optional, and must only be provided for iWidgets that are integrated into Communities. The widget ID is defined by the iWidget developer, and you need to request it from your administrator or the iWidget developer.
<span class="vcomm X-community-display-inline"> <span class="name" style="display:none;">Snowboarders</span> <span class="uuid" style="display:none">b307369e-7e60-403b-b850-206a28d6c19e</span> <span class="selectedWidgetId" style="display:none;">HelloWorldExtFullpage</span> </span>
- Optional: If you are building a web application that constructs its user interface using Ajax, you can make the business card user interface available by adding LiveName programmatically using JavaScript. Use the following API example:
This step only applies when you are building an application that constructs its user interface using Ajax. The business card code only scans the HTML when the page is first loaded so, if you dynamically alter the page, you need to manually specify the DOM elements that the code rescans for business card vcard class attributes. If you are developing a completely static page, you can ignore this step.
var htmlContent = "<span class="vcomm X-community-display-inline">"+ "<span class="name" style="display:none;"/><community_name></span>"+ "<span class="uuid" style="display:none"><community_uuid></span>"+ "<span class="selectedWidgetId" style="display:none;"><widget_id></span>"+ "</span>"; document.getElementById("containerId").innerHTML += htmlContent; setTimeout("SemTagSvc.parseDom(null, 'containerId')", 500 );
Configure the Communities business card on a Domino server
If you are adding the Communities business card to a web application that is deployed on an IBM Lotus Domino 8.5 server, perform the following steps to configure the card so that it works correctly. To deploy the Communities business card on a Domino 8.5 server, complete the following steps:
- Define the JavaScript configuration options for the business card by following the steps in the topic, Integrating the Communities business card.
- When you create the script tag reference, include the full host path to the Connections server.
Integrate the Profiles business card
Include the Profiles business card in your web application so that users can access your profile information and contact details.
The CSS files loaded with the Profiles business card do not include font style information. To ensure that the business card appears fully integrated with your web application from a visual perspective, define your own font styles globally so that the styles used in your application are also applied to the business card.
The use of JavaScript Object Notation with padding (JSONP) technology in the business card will be deprecated in future releases. Although JSONP will continue to be supported, if you are integrating the business card in to your web application and you want to prevent JSONP data from being transmitted by IBM Connections, you must use an Ajax proxy. You can integrate the Profiles business card with your web application based on one of the following:
- User ID, using the x-lconn-userid parameter
- email address, using the email parameter
The x-lconn-userid parameter is any unique identifier for the user defined by the administrator and originating from the corporate LDAP directory. Many LDAP directories contain users who do not have email addresses and using the x-lconn-userid parameter is a way of preemptively avoiding a dependency on the email address. In addition, administrators can edit configuration property settings to prevent email addresses from being displayed in IBM Connections. Hide email is a way to prevent the scraping of email addresses and protect the privacy of users. You can architect your web application so that it does not rely on email addresses for retrieving user data, such as the contextual business card.
Two types of business card are available to add to your web application:
To integrate the Profiles business card with your web application, complete the following steps:
- Inline. This type of business card is embedded in the user interface. Only one inline card can be displayed at a time on the page.
- Pop-up. This type of business card displays when users click a link in the user interface. Only one popup card can be displayed at a time.
- Include the following reference to the semanticTagService.js file in your code:
<script type="text/javascript" src="src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js"></script>Notes:
- The body element must exist and it must be instantiated before the script's JavaScript executes. So, if the script resource is included within the head element of your HTML code, it must use the defer attribute (defer="defer") so that the JavaScript executes after the page is loaded. Otherwise, the script resource request must be included within the body element.
- The business card uses Dojo. If Dojo is already included in your application, add the ?inclDojo=false URL parameter to the JavaScript include as follows, otherwise the business card will not work.
<script type="text/javascript" src="src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js?inclDojo=false"></script>If you use the ?inclDojo=false setting, ensure that you include the Javelin JavaScript after you include Dojo on your web page.
- The business card can be loaded with or without CSS. If you already have the IBM Connections CSS files loaded in your application and do not want to include the CSS again, add the loadCssFiles=false parameter to the JavaScript include like this:
<script type="text/javascript" src="src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js?loadCssFiles=false"></script>
- The business card cannot be run from the file system; your HTML file must reside on a web server. This server does not need to be in the same domain as Profiles. Use the following sample syntax to call your HTML file.
<script type="text/javascript" src="src="protocol://connections_server/profiles_app/ibm_semanticTagServlet/javascript/semanticTagService.js"></script>
- Use and modify one of the following code examples to render the card with your personal details.
To add the inline card:
To add the pop-up card:
Option Description Based on user ID <div class="vcard X-person-display-inline"> <span class="fn" style="display:none;">user_name</span> <span class="x-lconn-userid" style="display: none;">user_id</span> </div>For example:
<div class="vcard X-person-display-inline"> <span class="fn" style="display:none;">Joe Todd</span> <span class="x-lconn-userid" style="display: none;">91ae7240-8f0a-1028-737f-db07163b51b2</span> </div>Based on email address <div class="vcard X-person-display-inline"> <span class="fn" style="display:none;">user_name</span> <span class="email" style="display:none;">user_email_address</span> </div>For example:<div class="vcard X-person-display-inline"> <span class="fn" style="display:none;">Joe Todd</span> <span class="email" style="display:none;">todd@mycomp.com</span> </div>
Option Description Based on user ID <span class="vcard"> <a href="javascript:void(0);"class="fn url">user_name</a> <span class="x-lconn-userid" style="display: none;">user_id</span> </span>For example:
<span class="vcard"> <a href="javascript:void(0);"class="fn url">Joe Todd</a> <span class="x-lconn-userid" style="display: none;">91ae7240-8f0a-1028-737f-db07163b51b2</span> </span>Based on email address <span class="vcard"> <a href="javascript:void(0);"class="fn url"><user_name></a> <span class="email" style="display: none;"><user_email_address></span> </span>For example:<span class="vcard"> <a href="javascript:void(0);"class="fn url">Joe Todd</a> <span class="email" style="display: none;">todd@mycomp.com</span> </span>
- Optional: If you are using the standalone business card, include the following code to provide support for bidirectional languages:
<script type="text/javascript"> var SemTagSvcConfig = { isBidiRTL: true}; </script>
- Optional: If you are building a web application that constructs its user interface using Ajax, do one of the following to make the business card user interface and a person's profile data available:
This step only applies when you are building an application that constructs its user interface using Ajax. The business card code only scans the HTML when the page is first loaded so, if you dynamically alter the page, you need to manually specify the DOM elements that the code should rescan for business card vcard class attributes. If you are developing a completely static page, you can ignore this step.
Do one of the following:
- For applications that construct HTML dynamically, you can add LiveName programmatically using JavaScript. Use the following API example:
var htmlContent = "<span class='vcard'>"+ "<a href='javascript:void(0);' class='fn url'>user_name</a>"+ "<span class='email' style='display: none;'>"+ "user_name@company.com"+ "</span>'+ "</span>"; document.getElementById("containerId").innerHTML += htmlContent; setTimeout("SemTagSvc.parseDom(null, 'containerId')", 500 );For example:var htmlContent = "<span class='vcard'>"+ "<a href='javascript:void(0);' class='fn url'>Joe Todd</a>"+ "<span class='email' style='display: none;'>"+ "todd@mycomp.com"+ "</span>'+ "</span>"; document.getElementById("containerId").innerHTML += htmlContent; setTimeout("SemTagSvc.parseDom(null, 'containerId')", 500 );
- To make the business card user interface and a person's profile data available on your server:
- Verify the following files are in the WAS_HOME\profiles\WAS_Profile\config\cells\Host_name\LotusConnections-config directory:
- service-location.xsd
- LotusConnections-config.xsd
- LotusConnections-config.xml
- Ensure that the profile service reference in LotusConnections-config.xml points to a running profile server. For example:
<sloc:serviceReference serviceName="profiles" href="http://localhost:9080/profiles" enabled="true" ssl_href="https://localhost:9443/profiles" ssl_enabled="true" person_card_service_url_pattern="/html/simpleSearch.do?searchFor={email}&searchBy=email" person_card_service_name_js_eval="generalrs.label_personcard_profilelink"/>
Customize the Profiles business card
Customize the Profiles business card to meet the needs of your organization.
You can change the look of the Profiles business card and the information that it includes:
- Add or remove links that display on the card
- Customize contact and location information
Related
Administer Profiles
Add third-party links via the XML configuration file
You can extend the Profiles business card by adding links to applications from another vendor.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. You can specify links to services acquired from another vendor in the WAS_HOME\profiles\WAS_Profile\config\cells\Host_name\LotusConnections-config \LotusConnections-config.xml file. The service reference must have a person_card_service_url_pattern attribute and a person_card_service_name_js_eval attribute. Without these attributes, the service link does not display in the inline or pop-up business cards.
To extend the Profiles business card:
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the IBM WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Open LotusConnections-config.xml, and modify it to include the following attributes:
Table 39. Third-party service reference attributes
For example:
Attribute Description person_card_service_url_pattern Represents the URL pattern that is used when users click the service link. The ampersand character (&) must be expressed using the actual character in the pattern. This attribute takes a string value. The following parameters inside the URL pattern are placeholders. When the business card is rendered at runtime, the parameters are replaced by the real values.
- {email}. The profile user's email address.
- {userid}. The profile user's user ID.
- {uid}. The profile user's UID.
- {displayName}. The profile user's full name.
- {workPhoneNumber}. The profile user's work telephone number.
person_card_service_name_js_eval Represents a JavaScript statement that is used by the framework to generate the text displayed in the business card for the given service. This attribute takes a string value.
You can add a resource string as the value for this attribute. The resource string must include "generalrs." before the resource bundle key. See Add custom strings for widgets and other specified scenarios for information about how to add resource strings to the business card.
<sloc:serviceReference serviceName="googleService" href="http://www.google.com" enabled="true" ssl_href="http://www.google.com" ssl_enabled="false" person_card_service_url_pattern="/search?hl=en&q={email}&btnG=Google+Search" person_card_service_name_js_eval="'Google Me'"/> <sloc:serviceReference serviceName="quickr" href="http://quickrdomino.tap.ibm.com/servlet" enabled="true" ssl_href="https://quickrdomino.tap.ibm.com/servlet" ssl_enabled="true" person_card_service_url_pattern="/QuickrEntry?email={email}" person_card_service_name_js_eval="generalrs.label_personcard_quickrlink"/> <sloc:serviceReference serviceName="communities" href="http://wd40.lotus.com/communities" enabled="true" ssl_href="https://wd40.lotus.com/communities" ssl_enabled="true" person_card_service_url_pattern="/service/html/allcommunities?email={email}" person_card_service_name_js_eval="generalrs.label_personcard_communitieslink"/> <sloc:serviceReference serviceName="profiles" href="http://wd40.lotus.com/profiles" enabled="true" ssl_href="http://wd40.lotus.com/profiles" ssl_enabled="true" person_card_service_url_pattern="/html/simpleSearch.do?searchFor={email}&searchBy=email" person_card_service_name_js_eval="generalrs.label_personcard_profilelink"/>
- Edit the service-location.xsd file to define the service names used. For example:
<xsd:simpleType name="serviceNames"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="activities" /> <xsd:enumeration value="blogs" /> <xsd:enumeration value="communities" /> <xsd:enumeration value="directory" /> <xsd:enumeration value="dogear" /> <xsd:enumeration value="personTag" /> <xsd:enumeration value="presenceAwareness" /> <xsd:enumeration value="profiles" /> <xsd:enumeration value="sametimeLinks" /> <xsd:enumeration value="homepage" /> <xsd:enumeration value="googleService" /> <xsd:enumeration value="quickr" /> </xsd:..> </xsd:..>
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
If you added third-party links to the Profiles business card and those links are no longer needed, you can remove them by modifying the LotusConnections-config.xml configuration file to undo or comment out what was done to add them. You cannot remove third-party links using JavaScript.
Remove third-party links from the business card
If you added third-party links to the Profiles business card and those links are no longer needed, you can remove them by modifying the LotusConnections-config.xml configuration file. You cannot remove third-party links using JavaScript.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. You can remove links to services acquired from another vendor by deleting the relevant section from LotusConnections-config.xml.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Open LotusConnections-config.xml in a text editor.
- Find the <sloc> element that corresponds to the service for which you want to delete the link, and either delete the element from the file or comment it out.
For example:
<!-- <sloc:serviceReference serviceName="googleService" href="http://www.google.com" enabled="true" ssl_href="http://www.google.com" ssl_enabled="false" person_card_service_url_pattern="/search?hl=en&q={email}&btnG=Google+Search" person_card_service_name_js_eval="'Google Me'"/> --> <sloc:serviceReference serviceName="quickr" href="http://quickrdomino.tap.ibm.com/servlet" enabled="true" ssl_href="https://quickrdomino.tap.ibm.com/servlet" ssl_enabled="true" person_card_service_url_pattern="/QuickrEntry?email={email}" person_card_service_name_js_eval="generalrs.label_personcard_quickrlink"/> <sloc:serviceReference serviceName="communities" href="http://wd40.lotus.com/communities" enabled="true" ssl_href="https://wd40.lotus.com/communities" ssl_enabled="true" person_card_service_url_pattern="/service/html/allcommunities?email={email}" person_card_service_name_js_eval="generalrs.label_personcard_communitieslink"/> <sloc:serviceReference serviceName="profiles" href="http://wd40.lotus.com/profiles" enabled="true" ssl_href="http://wd40.lotus.com/profiles" ssl_enabled="true" person_card_service_url_pattern="/html/simpleSearch.do?searchFor={email}&searchBy=email" person_card_service_name_js_eval="generalrs.label_personcard_profilelink"/>
- Open the service-location.xsd file and delete the relevant service name.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
Add third-party links using JavaScript
Add third-party links to the Profiles business card using JavaScript. In addition to defining services in LotusConnections-config.xml, you can include additional services in the Profiles business card using JavaScript. Your code can add a service either using a widget from another vendor or if your vendor-acquired application includes the business card as part of the application. These services do not need to be defined in the LotusConnections-config.xml configuration file.
To extend the Profiles business card using JavaScript, see Integrating the Profiles business card.
If you added third-party links to the Profiles business card and those links are no longer needed, you can remove them by modifying the LotusConnections-config.xml configuration file to undo or comment out what was done to add them. You cannot remove third-party links using JavaScript.
Integrate Profiles with Lotus Quickr
You can configure LotusConnections-config.xml to include a link to IBM Lotus Quickr® on the Profiles business card. Users can then click the Quickr link in another person's business card to open that person's personal file library in Lotus Quickr.
For related information about Lotus Quickr integration, see IBM Connections Connector for Lotus Quickr and the following Lotus Quickr product documentation topics:
For the Connections business card to appear in Lotus Quickr, complete the following steps on your Lotus Quickr server as well as the steps outlined in this document:
- See Enable Lotus Connections features in Lotus Quickr for information about integration with Lotus Quickr for Domino.
- See Integrate with Lotus Connections Profiles business card for information about integration with Lotus Quickr for WebSphere Portal.
In previous releases, you could configure LotusConnections-config.xml to include a link to IBM Lotus Quickr on the Profiles business card. Users could then click the Quickr link in another person's business card to open that person's personal file library in Lotus Quickr. This configuration is not available in Quickr Domino 8.5 or later, which no longer supports the Quikr Entry Place feature.
The Profiles business card serves as an interface that other applications can leverage to integrate with IBM Connections. You can enable integration with Lotus Quickr in the business cards by enabling a service reference to LotusConnections-config.xml. Users can then click the Quickr link in another person's business card to access that person's public files and the files that they've shared with the user in Lotus Quickr.
- To find out what versions of Lotus Quickr are supported, see Detailed system requirements for IBM Connections.
- When you add a Quickr link to the Profiles business card in a Lotus Quickr for Lotus Domino deployment, the link only works with Entry places. The link does not work with regular places. The Lotus Quickr Domino administrator must run the qptool to create Entry places for users on the server; users cannot create Entry places for themselves. For information about how to create Lotus Quickr entry places, go to:
http://publib.boulder.ibm.com/infocenter/lqkrdom/v8/index.jsp?topic=/com.ibm.lotus.quickr.dominov82.doc/config/qp_inst_entry_create_places.htmlQuickr Domino 8.5 and later no longer supports the Quikr Entry Place feature.
When adding a Quickr link to the business card, if you have enabled SSL in IBM Connections by setting forceconfidentialcommunication to true in LotusConnections-config.xml, you should also enable SSL on the Lotus Quickr server so that the link will work when users access IBM Connections using HTTPS.
- To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin tool.
To enable a Lotus Quickr link on the business card, complete the following steps.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Open LotusConnections-config.xml with a text editor and search for the following entry:
<sloc:serviceReference enabled="false" person_card_service_name_js_eval="generalrs.label_personcard_quickrlink" person_card_service_url_pattern="/allfiles/people/{email}" serviceName="quickr" ssl_enabled="false"> <sloc:href> <sloc:hrefPathPrefix>/places</sloc:hrefPathPrefix> <sloc:static href="admin_replace" ssl_href="admin_replace"/> <sloc:interService href="admin_replace"/> </sloc:href> </sloc:serviceReference>Enable the Quickr service reference in the file by adding the Quickr server host name, and setting enabled and ssl_enabled to true as in the following steps:
- Change enabled="false" to enabled="true".
- Change ssl_enabled="false"> to ssl_enabled="true">.
- Change <sloc:static href="admin_replace" to <sloc:static href="http://quickrServer.mycompany.com:port".
- Change ssl_href="admin_replace"/> to ssl_href="https://quickrServer.mycompany.com:port"/>.
- Change <sloc:interService href="admin_replace"/> to <sloc:interService href="https://quickrServer.mycompany.com:port"/>
Step c. specifies http while steps d. and e. specify https.
- Lotus Quickr for Lotus Domino: No additional changes to LotusConnections-config.xml are required.
This configuration is not available in Quickr Domino 8.5 or later, which no longer supports the Quickr Entry Place feature.
- Lotus Quickr for WebSphere Portal: Make the following additional change to LotusConnections-config.xml:
- Change person_card_service_url_pattern="/allfiles/people/{email}" to person_card_service_url_pattern="/search?#owner={userid}|{displayName}".
- After making these changes, check the configuration files back in during the same wsadmin session in which you checked them out. See Applying common configuration property changes for information about how to save and apply your changes.
Customize action links on the business card
Customize the action links that display on the Profiles business card by editing settings in the Profiles configuration file.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin tool. The Profiles business card displays links that allow you to perform different actions directly from the card. For example, you can configure the card to display a link that allows users to send mail to the profile owner or a link that allows users to add the profile owner to their network.
Use the following procedure to customize the action links that display on the business card:
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the profiles-config.xml file using a text editor.
- Locate the <businessCardLayout> element, and specify the actions to include in the <actions> element. Each <action> element must contain the following attributes:
The <action> element can, optionally, include an <icon> subelement. In addition, the <label> and <alt> elements can have an optional bundleIdRef attribute, which references an external resource bundle.
- labelkey. Specifies the label to display for the action.
- href. This attribute supports the same substitutions as the business card URL patterns, that is, email, userid, displayName, and uid. It also supports '${[service=name]SvrRef}' url patterns using what is defined in LotusConnections-config.xml.
For example:
<businessCardLayout profileType="default"> ... <actions> ... <action urlPattern="mailto:{email}" emailEnabledRequired="true" liClass="lotusSendMail"> <label labelKey="personCardSendMail"/> <icon href="{profilesSvcRef}/nav/common/styles/images/iconSendMail.gif"> <alt labelKey="personCardSendMail"/> </icon> </action> ... </actions> </businessCardLayout>
- Save your changes.
- After making changes, check the configuration files in during the same wsadmin session in which you checked them out. See Applying property changes in Profiles for information about how to save and apply your changes.
Customize Profiles
Customize the Profiles application to define the core data model for people within your deployment and tailor the presentation of profile content to meet your organization.s requirements.
Use this section of the product documentation to deploy a unique Profiles model for your organizations IBM Connections users.
Customize the Profiles data model
The Profiles application provides the social directory structure leveraged by all other IBM Connection applications. You can use a combination of standard properties and extension properties to customize the data in Profiles to meet the unique needs of your deployment.
Each person in Profiles is described by a set of properties that are grouped into a type definition. The type definition can include standard properties defined by default, or you can add extension properties defined by you to meet your organization's needs.
Mapping from the LDAP directory (or other source) to the Profiles database can also be customized, as can mapping from the Profiles database to the user interface. For more information on mapping LDAP data to Profiles database fields, see Mapping fields manually.
Related tasks
Map fields manually Manually populating the Profiles database
Standard properties in the data model
The Profiles component defines a set of standard properties to support common organization directory needs.
Property information is presented in the following table as:
- Label . The information represented by the property, if a compound set of values are represented then all are listed
- Property . The property syntax as it would appear in the profile type configuration
- Editable . Indicates if the property can support editing by the end user in the user interface; TRUE = yes, FALSE = no
- Full text indexed - Indicates if the property supports inclusion in the search index; TRUE = yes, FALSE = no
Table 40. Job information attributes
Label Property Editable Full text indexed Address 1
Address 2
City
State
Postal code
workLocationCode
FALSE
TRUE
Assistant number*
Assistant name
Assistant email
secretaryUid
TRUE
TRUE
Country code*
Country
countryCode
TRUE
TRUE
Department number*
Department title
deptNumber
TRUE
TRUE
Employee number
employeeNumber
TRUE
TRUE
Employee type
employeeTypeCode
FALSE
TRUE
Is Manager
isManager
FALSE
TRUE
Job title
jobResp
TRUE
TRUE
Manager number
managerUid
FALSE
TRUE
Organization
orgId
FALSE
TRUE
Shift
shift
TRUE
TRUE
* The attributes assistant number, country code, and department number are editable. The assistant name and email, country, and department title are resolved from the associated value.
Table 41. Contact Information properties
Label Property Editable Full text indexed Alternate email
groupwareEmail
TRUE
TRUE
Alternate last name
alternateLastname
TRUE
TRUE
Building
bldgId
TRUE
TRUE
Calendar link
calendarUrl
TRUE
TRUE
Courtesy title
courtesyTitle
TRUE
TRUE
Fax number
faxNumber
TRUE
TRUE
Floor
floor
TRUE
TRUE
Free or busy time link
freeBusyUrl
TRUE
TRUE
IP telephony number
ipTelephoneNumber
TRUE
TRUE
Mobile number
mobileNumber
TRUE
TRUE
Name
displayName
FALSE
TRUE
Native first name
nativeFirstName
TRUE
TRUE
Native last name
nativeLastName
TRUE
TRUE
Office
officeName
TRUE
TRUE
Office email
TRUE
TRUE
Office number
telephoneNumber
TRUE
TRUE
Pager ID
pagerId
TRUE
TRUE
Pager number
pagerNumber
TRUE
TRUE
Pager service provider
pagerServiceProvider
TRUE
TRUE
Pager type
pagerType
TRUE
TRUE
Preferred first name
preferredFirstName
TRUE
TRUE
Preferred language
preferredLanguage
TRUE
TRUE
Preferred last name
preferredLastName
TRUE
TRUE
Time zone
timezone
TRUE
TRUE
None
uid
FALSE
FALSE
None
guid
FALSE
TRUE
None
key
FALSE
FALSE
None
tenantKey
FALSE
FALSE
None
loginId
FALSE
FALSE
None
distinguishedName
FALSE
FALSE
None
givenName
FALSE
TRUE
None
surname
FALSE
TRUE
None
title
FALSE
TRUE
None
lastUpdate
FALSE
FALSE
None
profileType
FALSE
TRUE
None
sourceUrl
FALSE
FALSE
None
userid
FALSE
FALSE
Table 42. Associated information properties
Label Property Editable Full text indexed About me
description
TRUE
TRUE
Background
experience
TRUE
TRUE
Blog link
blogUrl
TRUE
TRUE
Extension properties in the data model
You can define a set of custom extension properties to further customize Profiles for your deployment.s unique needs.
Each extension property is defined using a unique identifier. Declare extension properties in the profileExtensionAttributes section of the profiles-config.xml file.
The following extension properties types are supported:
- Simple properties . a string value in the range of 0-256 bytes
- Rich text properties . a rich text value in the range of 0-1,000,000 bytes
- XML properties . an XML blob; if the attribute is marked for full text search then a series of element and attribute values may be defined for inclusion in the search index
The application will resolve all simple and rich text extension fields for the Profile. XML extension fields are not currently made available to the template author.
The following XML snippets provide examples of declaring an extension attribute for each type. These examples are assumed to be in the http://www.ibm.com/profiles-config namespace:
Table 43. Extension point property declarations and their behavior
Samples . Property declaration Description
<profileExtensionAttributes> <simpleAttribute extensionId=.college. length=.256./> </profilesExtensionAttributes>Defines a custom string property with the college identifier whose maximum length is 256 bytes.
<profileExtensionAttributes> <richtextAttribute extensionId=.publications. maxBytes=.1000000./> </profilesExtensionAttributes>Defines a rich text property with the publications identifier whose maximum length is 1,000,000 bytes.
<profileExtensionAttributes> <xmlFileAttribute extensionId=.catalog. schemaFile=.catalog.xsd. indexBindingExpr=./catalog/entry/@name. <indexFields> <indexField fieldName=.catalogName. fieldExpr=./catalog/entry/@name./> /xmlFileAttribute> </profilesExtensionAttributes>Defines a custom XML property with the catalog identifier. Instances of this property must validate against the supplied XSD file catalog.xsd. The administrator must place the catalog.xsd file in the Connections-config/profiles-extensions directory. In this example, a specific section is requested to be included in the Profiles search index with the field name catalogName. The value of the field, is resolved by the supplied XPath expression.
Populate custom extension attributes
To map custom extension attributes to fields in your source LDAP directory, configure settings in the tdi-profiles-config.xml file for each custom extension attribute.
To populate custom extension attributes into the Profiles database:
- Open the tdi-profiles-config.xml file. After the Tivoli® Directory Integrator Solution files are extracted, the file is located in the following directory:
TDI/conf/LotusConnections-config
- Modify the file to indicate the property to extend, the property's name, data type, and key. Use the following parameters:
Table 44. Custom extension attribute parameters
For example, to add an attribute called spokenLangs, the configuration would look similar to the following configuration in the profiles-config.xml file:
Parameter Description extensionId The ID of the extension attribute. This parameter is required.
sourceKey The name of the LDAP attribute that maps to the extension attribute. This parameter is required.
userLabel An administrator-defined label for the extension attribute that is populated into the database. This string does not display in the user interface or API. This parameter is optional.
userTypeString An administrator-defined string defining the data type of the extension attribute. This string does not display in the user interface or API. This parameter is optional.
<simpleAttribute extensionId="spokenLangs" length="64" userLabel="Spoken Languages" userTypeString="String" sourceKey="spokenLang"/>The formatting is compatible between the tdi-profiles-config.xml file and the profiles-config.xml file, allowing you to copy and paste configuration information between the files.
- Save your changes to tdi-profiles-config.xml and then close the file.
- To populate the custom extension attributes, run one of the following scripts:
- IBM AIX or Linux:
./sync_all_dns.sh
- Microsoft
Windows:
sync_all_dns.bat
- AIX or Linux:
./populate_from_dn_file.sh
- Microsoft
Windows:
populate_from_dn_file.bat
Profile-types
A profile-type defines a set of properties, also referred to as a schema, that are inherent to all profiles of that type. This set of properties is used internally to group objects and enforce overall system constraints. Examples of common profile-types are customer, employee, and contractor.
The set of properties reference your supplied standard properties or custom extension properties.
All profile records are classified by their profile-type property. If a property is not specified in a profile record's profile-type property definition, it is not exposed to the Profiles user, either in the user interface or API. The deployer uniquely identifies each profile type using a 64 byte profile-type identifier string.
Profile-type definitions are declared and managed in profiles-types.xml.
Profile-types are managed in an object hierarchy with the following rules:
- Profiles defines a single base type of snx:person that enumerates the set of fields required on all profile records.
- You can define subtypes of snx:person (such as customer, employee, or contractor) to add your own unique properties.
- A profile-type inherits all the property references from its parent type.
- A profile-type hierarchy cannot contain circular loops. The application will fail to start if any loops are detected in the configured hierarchy.
- A profile-type declaration that omits a parentId implicitly inherits from snx:person.
There are important consideration when assigning profile type id values. These values will appear as URL parameters in the Profiles API, and should accordingly facilitate a valid URL encoding. The following rules will help avoid encoding issues in the API.
- Use ASCII characters and avoid special URL characters.
- Do not use spaces or plus symbols (+); there are known URL encoding problems specific to these characters.
The following XML code sample provides an example of declaring a profile-type that contains hierarchy and inheritance. The sample is assumed to reside in the http://www.ibm.com/profiles-types namespace.
Table 45. Table 1. Profile-type declaration using hierarchy and inheritance
Sample . Profile-type declaration with hierarchy and inheritance Description
<config> <type> <parentId>snx:person</parentId> <id>customer</id> ... </type> </config>Defines the profile-type identifier customer; this profile-type inherits from the system type snx:person. The customer type can add additional <property/> declarations that reference your standard properties or extension properties or extension properties that were declared in the profiles-config.xml file.
Profile-type property definitions
A profile-type property definition contains inherited property definitions and may contain additional property definitions. A valid profile-type property definition contains the following elements:
Table 46. Profile-type property definitions
Name Type Description ref
Enum
References a standard profile data attribute or a globally defined extension attribute.
updatability
Enum
Indicates if the value of this property may be updated. Options are:
- read . specifies that the property value cannot be modified using either a user interface or API element. This is applicable for a system property that is either maintained or computed by the application, Tivoli Directory Integrator (TDI), or the administrator API.
- readwrite . specifies that the property value can be modified using either a user interface or API element.
hidden
Boolean
If set to TRUE, the property is not serialized when rendering profile results in the application public REST API. The default setting is FALSE.
richText
Boolean
If set to TRUE, the property is treated as rich text in the application. If the property references an extension attribute that was declared as richText, the value is always TRUE. Otherwise, the default setting is FALSE.
fullTextIndexed
Boolean
If set to TRUE, and the property supports inclusion in the search index (see Standard properties in the data model), the property is included in the search index for Profiles full text search. The default setting is TRUE for extension properties.
If set to FALSE, the standard or extension property value is omitted from the search index for profile records with a matching profile-type.
This property is only enforced if support for variable indexing of profile attributes is enabled. For more information, see Specifying properties to expose in the search index.
The following XML code sample provides an example of declaring a profile-type property definition. The sample is assumed to reside in the http://www.ibm.com/profiles-types namespace.
Table 47. Table 1. Profile-type declaration
Sample . Profile-type property definition Description
<property> <ref>telephoneNumber</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <fullTextIndexed>true</fullTextIndexed> </property>Adds the property identifier telephoneNumber to the associated profile-type.
The updatability=readwrite setting means that the property value can be modified using either a user interface or API element.
The hidden=false setting means that the property is serialized when rendering profile results in the application public REST API; the property can be modified using the API.
The fullTextIndexed=true setting means that the property is included in the search index for Profiles full text search; it is added to the full text search index for profiles that are of this type.
Configure profile types for widget layout
To configure widget layout, you can add a profile type containing the widget layout configuration to Profiles in the widgets-config.xml file.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
To add a new profile type for widget layout, perform the following steps.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Use the following command to check out the widget configuration file:
ProfilesConfigService.checkOutWidgetConfig("<working_directory>", "<cell_name>")
...where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files will be copied. The files are kept in this working directory while you make changes to them.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required.
ProfilesConfigService.checkOutWidgetConfig("/wsadminoutput", "jdoe30Node02Cell")
- Save a copy of the widgets-config.xml file.
- Open the file in a text editor.
- Add a widget layout under the <widgets> element, as in the following example:
<layoutConfiguration> <widgets xmlns:tns="http://www.ibm.com/profiles-config"> <layout resourceSubType="debug"> <page pageId="profilesView"> <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="tabsWidget1"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="board"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="contactInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="backgroundInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="multiFeedReader"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="socialTags"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="sand_thingsInCommon"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="sand_socialPath"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="reportStructure"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="friends"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="linkRoll"/> </page> </layout> <layout resourceSubType="restricted"> <page pageId="profilesView"> <!-- <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="mw1"/> --> <widgetInstance uiLocation="col2" defIdRef="contactInfo" instanceId="ci1"/> <widgetInstance uiLocation="col1" defIdRef="reportStructure"/> </page> </layout> <layout resourceSubType="mobile"> <page pageId="profilesView"> <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="tabsWidget1"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="board"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="contactInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="backgroundInfo"/> <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="tabsWidget2"/> <widgetInstance uiLocation="tabsWidget2" defIdRef="multiFeedReader"/> <widgetInstance uiLocation="col1" defIdRef="socialTags"/> <widgetInstance uiLocation="col1" defIdRef="sand_thingsInCommon"/> <widgetInstance uiLocation="col1" defIdRef="sand_socialPath"/> <widgetInstance uiLocation="col3" defIdRef="reportStructure"/> <widgetInstance uiLocation="col3" defIdRef="friends"/> <widgetInstance uiLocation="col3" defIdRef="linkRoll"/> </page> </layout> <layout resourceSubType="default"> <page pageId="profilesView"> <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="tabsWidget1"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="board"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="contactInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="backgroundInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="multiFeedReader"/> <widgetInstance uiLocation="col1" defIdRef="socialTags"/> <widgetInstance uiLocation="col1" defIdRef="sand_thingsInCommon"/> <widgetInstance uiLocation="col3" defIdRef="sand_socialPath"/> <widgetInstance uiLocation="col3" defIdRef="reportStructure"/> <widgetInstance uiLocation="col3" defIdRef="friends"/> <widgetInstance uiLocation="col3" defIdRef="linkRoll"/> </page> <page pageId="searchResultView"> <widgetInstance uiLocation="col1" defIdRef="commonTags"/> </page> <page pageId="searchView"> <widgetInstance uiLocation="col1" defIdRef="sand_DYK"/> <widgetInstance uiLocation="col1" defIdRef="commonTags"/> <!-- <widgetInstance uiLocation="col3" defIdRef="sand_recomItems"/> --> </page> <page pageId="networkView"> <widgetInstance uiLocation="col1" defIdRef="sand_DYK"/> </page> <page pageId="editProfileView"> ... </layout> </widgets> </layoutConfiguration>
- Save your changes and check the widgets-config.xml file back in :
ProfilesConfigService.checkInWidgetConfig()
- To exit the wsadmin client, type exit at the prompt.
- Stop and restart the Profiles server.
Person profile-type
Profiles defines a single snx:person base profile-type that all profile-types inherit from.
The following properties are defined in the base profile-type and present in all profile records.
Table 48. Person profile-type properties and settings
ref fullTextIndexed displayName
TRUE
guid
TRUE
key
FALSE
surname
TRUE
tenantKey
FALSE
uid
FALSE
managerUid
TRUE
profileType
TRUE
userid
FALSE
sourceUrl
FALSE
distinguishedName
FALSE
givenName
TRUE
isManager
TRUE
loginId
FALSE
Default profile-type
To maintain compatability with earlier versions, Profiles maintains the concept of a default profile-type.
It is strongly encouraged that you explicitly map a defined profile-type to each profile record in the Profiles database as a part of the Profiles population process
If no profile-type is associated with the profile record, the Profiles application will interpret the empty profile-type value as equivalent to the default value.
If the declaration of the default profile-type has been removed from profiles-types.xml, the application assigns the profile record the snx:person profile type. As a consequence, when rendering profile data in the user interface, the application onlys present the minimal set of attributes defined in the snx:person profile-type.
For more information on the default properties supported in this scenario, see Person profile-type.
As stated, if a profile record contains an empty or null profile-type value, the profile-type label is assumed to be set to the default value as defined in the associated profile-types.xml file. If the default profile-type is not found, the snx:person profile type definition is used.
Specify a custom field as required and declaring maximum field length
You can make a custom field a required field by editing the validation.xml file. You must declare a maximum length definition for all custom fields.
When upgrading to a newer IBM Connections release, be aware that custom fields are not included in the migration tools for the standard Connections configuration files. As well, the validation.xml file is also not automatically migrated when you upgrade from an earlier release of Connections. This file is needed by the Struts validation framework and is accessed at Connections startup. To ensure that your custom fields and files are usable after a release upgrade, see the Save your customizations and Post-migration tasks topics.
IBM Connections is built on Struts, allowing you to leverage the Struts validation framework to validate form data. The files validation.xml and validation-rules.xml are both part of the Struts validation framework. The validation.xml file defines the validation types that are applied to form fields; validation-rules.xml defines a set of standard validation routines. Validation routines, such as required and maximum length, are included in the validation framework.
All custom extension attributes must have a maximum length definition to ensure that values are within the limits of the database.
To make a custom extension field a required field, perform the following steps.
- Save a copy of the was_profile_root\installedApps\cell_name\profiles.ear\lc.profiles.app.war\WEB-INF\validation.xml file.
- Open the file in a text editor, and specify your validation requirements using the information in the following table.
Table 49. Validator attributes
Attribute Role property The name of the field to make required. You obtain the field name by viewing the source of the rendered page. depends The name of the validation to run. msg name Overrides the default required error message. Matches the validator's name attribute. msg key The message to be displayed if the validation fails. The key in the property file contains the error message to display if validation fails. You need to add the key to the property file. For example, to specify the maximum length of the custom extension attribute:
<field property="attribute(school)" depends="maxbytelength,nonce"> <msg name="maxbytelength" key="errors.maxlength" /> <arg position="0" name="maxbytelength" key="label.editprofile.contactinformation.school" /> <arg position="1" name="maxbytelength" key="(maxbytelength)" resource="false" /> <var> <var-name>maxbytelength</var-name> <var-value>16</var-value> </var> <var> <var-name>subEditForm</var-name> <var-value>contactInfo</var-value> </var>For example:
<form-validation> <formset> <form name="editProfileForm"> <field property="attribute(contactInformation.extattr.property1)" depends="required"> <msg name="required" key="errors.required" /> </field> <field property="attribute(associatedInformation.description)" depends="maxlength"> <msg name="maxlength" key="errors.aboutMe" /> <var> <var-name>maxlength</var-name> <var-value>1500</var-value> </var> </field>
- Add the following code to the validation.xml file to enable the Struts validator to recognize the tab that you are editing.
<var> <var-name>subEditForm</var-name> <var-value>sectionName</var-value> </var>...where sectionName is one of the following values:
- contactInfo. For contact or job information fields.
- aboutMe. For associated information fields.
For example:
<form-validation> <formset> <form name="editProfileForm"> <field property="attribute(contactInformation.extattr.property1)" depends="required"> <msg name="required" key="errors.required" /> <var> <var-name>subEditForm</var-name> <var-value>contactInfo</var-value> </var> </field> <field property="attribute(associatedInformation.description)" depends="maxlength"> <msg name="maxlength" key="errors.aboutMe" /> <var> <var-name>maxlength</var-name> <var-value>1500</var-value> </var> <var> <var-name>subEditForm</var-name> <var-value>aboutMe</var-value> </var> </field>These section identifiers also relate to the profileEdit.ftl display template as described in Customize edit display fields. The display sections specified in the profileEdit.ftl file must correspond to the section name defined in the validator attributes.
- Define a label for the required field. To do so, make a note of the ID of the extension, which is the value after .extrattr. in the attribute definition for the field.
For example, the value for this field is property1:
<field property="attribute(contactInformation.extattr.property1)" ...>Set the extensionIdRef attribute of the <extensionAttribute> element to define the field in the profiles-config.xml file equal to the value you noted here. See Enabling custom extension attributes for Profiles for more details.Do not hide any required attribute fields; if a user edits their profile contact information and required field information is hidden for that user type, the edited profile form cannot be saved.
You should define a label for any custom fields that you add, but it is especially important to define a label for a required field because if the user does not enter a value in the field, but tries to save the form, a message is displayed telling them that x is required,
...where x is the field label. If you do not define a label for the field, the term null is used instead. As a result, users will see a null is required message when they try to save the page, and will not know which field to fill in before they can save the page successfully.
Customize the Profiles user interface
Specify which attributes should display in Profiles based on the needs of your organization.
In prior releases, customizing attributes for Profiles user interface display was done using the profiles-config.xml file. That customization is now done using a set of supplied template files and the FreeMarker Templating Language (FTL). This method provides greater customization flexibility.
Customize display using templates
Customize various sections of the Profiles application using the supplied template files. You can choose to modify the set of standard and extension attributes that are rendered in the user interface for a profile record. Extension attributes of type XML are not provided for use by template authors. You can also modify the structure of the layout of content using the flexibility provided by the FreeMarker Template Language.
To edit configuration files, use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
The customization templates are as follows:
- businessCardInfo.ftl . controls layout of main section of the business card
- profileDetails.ftl . controls display of profile properties
- profileEdit.ftl . controls display of the edit form for a profile
- searchResults.ftl . controls display of profile fields in select views that render lists of users
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the needed configuration file, for example to edit the main section of the business card display, open the Connections-config/profiles/templates/businessCardInfo.ftl file.
- Modify the file contents to include any custom HTML or fields.
- Save your changes.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying property changes in Profiles for information about how to save and apply your changes.
- If you have enabled template reloading, your changes are reflected immediately in the user interface. If not, restart the application to recompile the template and display your customization changes.
Customize profile page display
Edit the profileDetails.ftl file to customize the display of profile properties on the main profile page.
To edit configuration files, use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
Use the profileDetails.ftl template to render multiple sections of the main profile page.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles business card configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the LotusConnections-config/profiles/templates/profileDetails.ftl file.
- Modify the file contents to include any custom HTML or fields.
Table 50. Section titles and descriptions for the profileDetails.ftl template
Section Description jobInformation
Content in this section is rendered on the main profile page data section and appears after the user name.
Required; do not remove.
contactInformation
Content in this section is rendered in the Contact Information widget.
Required if the Contact Information widget is deployed in the widgets-config.xml file.
associatedInformation
Content in this section is rendered in the Background Information widget.
Required if the Background Information widget is deployed in the widgets-config.xml file.
customSection
You can define new sections to render in alternate widgets or in HTML format that is available to a REST API request.
For more information about using these settings, see Example . Creating a simple profile data model and template customization.
- Save your changes.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying property changes in Profiles for information about how to save and apply your changes.
- If you have enabled template reloading, your changes are reflected immediately in the user interface. If not, restart the application to recompile the template and display your customization changes.
Customize business card information
Edit the businessCardInfo.ftl file to customize business card display.
To edit configuration files, use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
Use the businessCardInfo.ftl template to control how profile fields are presented in the business card.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the LotusConnections-config/profiles/templates/businessCardInfo.ftl file.
- Modify the file contents to include any custom HTML or fields.
- Save your changes.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying property changes in Profiles for information about how to save and apply your changes.
- If you have enabled template reloading, your changes are reflected immediately in the user interface. If not, restart the application to recompile the template and display your customization changes.
Customize profile field display in search lists
Edit the searchResults.ftl file to customize the display of profile fields in views that render lists of users.
To edit configuration files, use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin tool.
Use the searchResults.ftl template to customize the display of fields in either the Report-to Chain or Directory views.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles business card configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the LotusConnections-config/profiles/templates/searchResults.ftl file.
- Modify the file contents to include any custom HTML or fields.
The views that use this template are listed in the Section column in the following table.
Table 51. Section titles and descriptions for the searchResults.ftl template
Section Description reportTo
Applies to the Full Report-to Chain view and Same Manager view available in the Report-to Chain section of the profile page.
directory
Applies to the profile directory search results available from the Directory view.
By default, both views render the same results. To customize one of the view but not the other, use the supplied renderSection macro. For example, to customize only the directory results, the following macro should surround the code section being customized:
<@util.renderSection sectionLabel=.directory.> . mark-up specific to the directory view ... </@util.renderSection>For more information about using these settings, see Example . Creating a simple profile data model and template customization.
- Save your changes.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying property changes in Profiles for information about how to save and apply your changes.
- If you have enabled template reloading, your changes are reflected immediately in the user interface. If not, restart the application to recompile the template and display your customization changes.
Customize edit display fields
Edit the profileEdit.ftl file to customize edit display fields.
To edit configuration files, use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
Use the profileEdit.ftl template to customize the profile field display on the profile edit page.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Use the wsadmin client to access and check out the Profiles business card configuration files.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Open the LotusConnections-config/profiles/templates/profileEdit.ftl file.
- Modify the file contents to include any custom HTML or fields.
Table 52. Section titles and descriptions for the profileEdit.ftl template
Section Description contactInformation
Content in this section is rendered in the Contact Information tab on the Edit Profile page.
Required; do not remove.
associatedInformation
Content in this section is rendered in the About Me tab on the Edit Profile page.
Required; do not remove.
For more information about using these settings, see Create a simple profile data model and template customization.
- Save your changes.
- After making changes, check the configuration files back in, and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying property changes in Profiles for information about how to save and apply your changes.
- If you have enabled template reloading, your changes are reflected immediately in the user interface. If not, restart the application to recompile the template and display your customization changes.
Template data model
Learn about the data made available for use by your customization templates.
The following data is provided as input to your customization templates. Make use of this data to build custom logic to meet your business needs using the FreeMarker Templating Language (FTL).
Configuration data
As a part of template processing, it is important to understand how the Profiles application is configured. The following elements are always provided as input to the template processor:
Table 53. Configuration data fields
Field Type Description config.sametime.enabled
boolean
Set to TRUE if Sametime awareness is enabled.
config.sametime.href
string
Set the HREF value if Sametime awareness is enabled.
config.sametime.sslHref
string
Set the SSL HREF value if Sametime awareness is enabled.
config.sametime.inputType
string
Set the needed input type value if Sametime awareness is enabled.
config.exposeEmail
boolean
Set to TRUE if email address is allowed in the user interface.
Localization data
To support string localization, the template data model includes the ability to look up strings from a resource bundle by key. Macros are also provided to simplify interaction with data for localization.
Table 54. Localization data fields
Field Type Description nls.template.<nlsKey>
string
Look-up string from the default templates resource bundle using the specified nlsKey value.
nls.<nlsBundleId>.<nlsKey>
string
Look-up string from a custom NLS bundle ID using the specified nlsKey value.
Request data fields
Use these fields if your user interface templates must build URL's to other resources, or must perform specific processing based on the incoming request.
Table 55. Request data fields
Field Type Description request.contextPath
String
Specifies the application context path.
request.path
String
Specifies the application context path.
request.query.<queryParameter>
Map
Specifies the map containing all query parameters and their values from the incoming request.
request.lang
String
Specifies the language of the incoming request.
Profile-type definition fields
Use these fields to indicate whether a given field exists in the profile data model definition. The profile-type definition of the profile to be rendered is provided to the template as input data.
Table 56. Profile-type definition fields
Field Type Description profileType.<ref>.isExtension
Boolean
Specify as TRUE if the property is an extension property.
profileType.<ref>.isHidden
Boolean
Specify as TRUE if the property is hidden.
profileType.<ref>.isRichText
Boolean
Specify as TRUE if the property is rich text.
profileType.<ref>.updatability
Enum (String)
Specify as READ if the value is read-only or READWRITE if the value is editable.
For example, to reference information for the experience profile-type definition, either of the following statements are valid:
profileType.experience.isExtension profileType[experience].isExtension
Associated data fields
When rendering a profile, we may want to show additional related data. This data is provided based on which fields are populated in the profile record. All associated data is stored in a data map container relative to a root FreeMarker Template model, and further grouped based on the underlying associated field as follows, where dataId is the data container identifier, and dataKey is the container value:
data.<dataId>.<dataKey>Use the following if the profile-type contains the secretaryUid property and the profile has a populated value:Table 57. Fields available if secretaryUid property is used
Field Type Description data.manager.secretaryName
String
Specifies the name of the secretary.
data.manager.secretaryEmail
String
Specifies the email address of the secretary.
data.manager.secretaryKey
String
Specifies the internal key of the secretary.
data.manager.secretaryUid
String
Specifies the unique identifier of the secretary.
data.manager.secretaryUserid
String
Specifies the user identifier of the secretary.
Use the following if the profile-type contains the managerUid property and the profile has a populated value:
Table 58. Fields available if managerUid property is used
Field Type Description data.secretary.managerName
String
Specifies the name of the manager.
data.secretary.managerEmail
String
Specifies the email address of the manager.
data.secretary.managerKey
String
Specifies the internal key of the manager.
data.secretary.managerUid
String
Specifies the unique identifier of the manager.
data.secretary.managerUserid
String
Specifies the user identifier of the manager.
Use the following if the profile-type contains the workLocationCode property and the profile has a populated value:
Table 59. Fields available if workLocationCode property is used
Field Type Description data.workLocation.address1
String
Specifies the first line of address.
data.workLocation.address2
String
Specifies the second line of address.
data.workLocation.city
String
Specifies the city.
data.workLocation.state
String
Specifies the state.
data.workLocation.postalCode
String
Specifies the postal code.
Use the following if the profile-type contains the countryCode property and the profile has a populated value:
Table 60. Fields available if countryCode property is used
Field Type Description data.country.countryDisplayValue
String
Specifies the country name.
Use the following if the profile-type contains the deptNumber property and the profile has a populated value:
Table 61. Fields available if deptNumber property is used
Field Type Description data.department.departmentTitle
String
Specifies the department name.
Use the following if the profile-type contains the employeeNumber property and the profile has a populated value:
Table 62. Fields available if employeeNumber property is used
Field Type Description data.employeeType.employeeTypeDesc
String
Specifies the employee type.
Use the following if the profile-type contains the orgID property and the profile has a populated value:
Table 63. Fields available if orgID property is used
Field Type Description data.organization.organizationTitle
String
Specifies the organization name.
Profile data fields
Fields that are associated with the profile object are stored in a profile map container relative to the FreeMarker Template model root.
Table 64. Profile data fields
Field Type Description profile.<ref>
Literal
Fetches the value of a standard profile field using the property ref declared in the associated profile-type definition.
profile.extension.<ref>
String
Fetches the value of an extension field using the property ref declared in the associated profile-type definition.
Extension fields of type XML are not made available for use in the presentation templates.
For example, to reference the value of the experience field on a given profile, either of the following statements are valid:
profile.experience profile[experience]For example, to reference the value of the extension field hobbies on a given profile, either of the following statements are valid:
profile.extension.hobbies profile.extension[hobbies]
Display fields based on connection status
When rendering the business card and profile data templates, it is possible to determine the network connection status between the user viewing the profile and the profile being viewed. This enables you to selectively filter attributes from the user interface based on a network relationship.
Table 65. Connection status fields
Field Type Description connection.status
String
Determines the status of the connection between the viewer and target profile, available options are:
- accepted
- pending
- unconfirmed
The connection status is available when rendering the content on the main profile page. To make the connection status information available when rendering the business card, you must do the following:
- Open the profiles-config.xml file using a text editor.
- Locate the <template/> element for businessCardInfo.
- Modify the <templateDataModel/> to include the following: statement:
<templateData>connection</templateData>
- Save your changes.
- Check in your configuration file update.
- Restart the server.
Display fields based on user status
Information is made available to the templates to drive behavior based on the current user viewing the profile to be rendered. Use the following fields to determine the current user and build dynamic behavior.
Table 66. User status fields
Field Type Description currentUser.authenticated
Boolean
Specify as TRUE if the current user is authenticated.
currentUser.key
String
Specifies the internal key of the user viewing the application. This value is only supplied if the user is authenticated.
Template configuration options
You can configure how templates are used in your deployment.
You can configure and specify resource bundles, required input fields, and reloading options for your customized templates.
Configure template reloading
Edit the profiles-config.xml file to configure template reloading.
When developing your presentation templates, it is useful to see your changes immediately reflected in the user interface without stopping and starting the application. This enables you to make updates to any of the template files, and see the changes immediately in the application without requiring restarts.
In a production environment, set this value to 0 so templates are compiled once and performance is optimal.
- Open the profiles-config.xml file using a text editor.
- Locate the <templateReloading/> element
- Edit the value to define how frequently (in seconds) the template processor should look for updates to the templates on disk.
- Save your changes.
- Check in the configuration update.
- Restart the application.
Configure template custom resource bundles for processing
Edit the profiles-config.xml file to configure template custom resource bundles.
To take advantage of custom resource bundles in your templates, register the bundles with the application to specify that they be included during template processing. The specified bundles will be provided as input to all the templates that are processed.
- Open the profiles-config.xml file using a text editor.
- Locate the <templateNlsBundles/> element
- Edit the value with a space-delimited set of bundle identifiers for the custom resource bundles tto make available in your FreeMarker Template Language (FTL) templates. The bundle identifier maps to the bundle prefix that you defined when you registered the resource bundle in LotusConnections-config.xml.
- Save your changes.
- Check in the configuration update.
- Restart the application.
Configure required fields for processing
Edit the profiles-config.xml file to configure additional required fields for template processing.
When rendering the profile details or edit form templates, all the information about a user profile is retrieved and made available to the template.s author. This enables you to reference the additional data required for your templates.
To optimize system performance, you can use a limited set of data to render the profile business card and profile search results pages if the application templates do not require these fields.
Table 67. Template data types used to specify required data
Template data Description codes
The application will resolve the related fields for work location, organization, and department information so it may be used in the template.
extensions
The application will resolve all simple and rich text extension fields for the profile. XML extension fields are not currently made available to the template author.
secretary
The application will resolve the secretary name and email address if the profile has an associated secretary.
manager
The application will resolve the manager name and email address if the profile has an associated manager.
connection
The application will resolve the connection status between the profile and the user viewing the profile. This is only supported for the businessCardInfo template.
- Open the profiles-config.xml file using a text editor.
- Locate the <template/> element for the business card or search results.
- Add a <templateData/> element with one of the required template data values to the template elements <templateDataModel/> container.
For example, the following configuration states that when rendering the business card template, all the profile record data including resolved codes, extension values, secretary, manager, and connection information is resolved for use by the template code.
<template name="businessCardInfo"> <templateDataModel> <templateData>codes</templateData> <templateData>extensions</templateData> <templateData>secretary</templateData> <templateData>manager</templateData> <templateData>connection</templateData> </templateDataModel> </template>
- Save your changes.
- Check in the configuration update.
- Restart the application.
Customize Profiles search
Determine the properties that users can specify when performing an advanced search of profiles. Specify which properties the Profiles application exposes in its search index.
Related tasks
Manage the Profiles search operation
Customize settings for the search type-ahead
You can configure tuning parameters to adjust the behavior of the type-ahead tool that is used for Profiles search on the Directory page.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool. The type-ahead tool that is used for Profiles search makes it easier for users to find people by suggesting names from the company directory as they type in the search field. You can configure settings in the profiles-config.xml file to adjust the performance of the type-ahead tool.
To configure tuning parameters for the search type-ahead in Profiles.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Profiles Jython script interpreter.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Navigate to the temporary working directory specified in the previous step, and then open the profiles-config.xml file in a text editor.
- Locate the <properties> element, and then add the following property elements to it if they are not already present, or edit the values of the properties as required, if they are present.
Table 68. Type-ahead properties
Property Description com.ibm.lconn.profiles.config.ui.ptas.fireOnKeys Specifies the number of keys that must be pressed before the search request is submitted. com.ibm.lconn.profiles.config.ui.ptas.delayBetweenKeys Specifies the delay in milliseconds after the last key is pressed before the search request is submitted. com.ibm.lconn.profiles.config.ui.ptas.maxResults Specifies the number of search results to display. com.ibm.lconn.profiles.config.ui.ptas.liveNameSupport Specifies whether to attach a Profiles business card to each name. This property can be set to true or false. com.ibm.lconn.profiles.config.ui.ptas.expandThumbnails Specifies whether to expand the profile picture provided in the search results. This property can be set to true or false. Note that when users mouse over a profile picture, there is a delay before the picture is expanded. com.ibm.lconn.profiles.config.ui.ptas.blankOnEmpty Specifies whether the search results remain on display if the contents of the search field are deleted. This property can be set to true or false. When set to true, the search results are removed. The following code provides an example of the settings for the type-ahead feature:
<!-- directory page: people type-ahead search (ptas) --> <property name="com.ibm.lconn.profiles.config.ui.ptas.fireOnKeys" value="1" /> <property name="com.ibm.lconn.profiles.config.ui.ptas.delayBetweenKeys" value="0" /> <property name="com.ibm.lconn.profiles.config.ui.ptas.maxResults" value="10" /> <property name="com.ibm.lconn.profiles.config.ui.ptas.liveNameSupport" value="true" /> <property name="com.ibm.lconn.profiles.config.ui.ptas.expandThumbnails" value="true" /> <property name="com.ibm.lconn.profiles.config.ui.ptas.blankOnEmpty" value="true" />
Specify properties to expose in the search index
You can manually configure which properties are made available in the search index in order to meet organizational specific search requirements.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
You can control which fields are made available to the search index on a per profile-type basis. To do so, enable support for the variable full text index in the profiles-config.xml file and then specify the properties to omit from the search index in profiles-types.xml.
By default, all properties on the profile record are made available to the search index if the individual property itself supports inclusion in the index. For a list of fields that are included in the search index by default, see Standard properties in the data model.
You can manually configure the properties that are made available in the search index in order to meet your specific search requirements. For example, your organization may need to not index a particular property in order to protect sensitive personal information that should not be exposed in search, but that is maintained in the Profiles application.
To specify which fields are indexed for search:
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\binwhere app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Profiles Jython script interpreter.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required and is case-sensitive. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()For example:
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Navigate to the temporary working directory specified in the previous step, and then open the profiles-config.xml file in a text editor.
- Locate the <properties> element, and then add the following property elements to it if they are not already present, or edit the values of the properties as required, if they are present.
Option Description Property Description com.ibm.lconn.profiles.config.variableFullTextIndexEnabled If set to true, the search index is comprised of fields that are marked as searchable in profiles-types.xml.
If set to false, the search index is comprised of all fields that support search.
The default setting is false.
- Navigate to the temporary working directory specified in the previous step, and then open profiles-types.xml in a text editor.
- For each property that should not get included in the search index, add <fullTextIndexed>false</fullTextIndexed> to the property reference.
For example, to remove description from the search index, do the following:
<property> <ref>description</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <richText>true</richText> <fullTextIndexed>false</fullTextIndexed> </property>
- Check in the configuration files using the wsadmin command ProfilesConfigService.checkInConfig().
- Restart the application.
- If the search index was previously built, you will need to delete the existing index. See Managing the search index for more details.
Customize login attributes
By default, Profiles looks at the login table and various login attributes in the Profiles database. To improve performance, comment out login attributes that are not used in your environment.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for information about how to start the wsadmin command-line tool.
Default mappings for uid and mail are provided. To use a mapping for loginId, replace ADMIN_REPLACE in the loginField element with the appropriate login attribute specified in WebSphere Application Server. This section should only contain those login attributes that will be used in a deployment. For example, if users only log in with email, then the mappings for uid and loginId should be commented out or removed.
For more information on enabling and disabling access, see Forcing users to log in before they can access an application.
The login attributes described here refer to the Profiles database table, not the LDAP; the values you enter in the Admin Console refer to the LDAP. Thus if an LDAP field has been added using the Admin Console, you would not need to add it to the Profiles database using the procedure described here.
When editing the login table in the Profiles database, you can comment out login attributes that you do not need, but you should not use the login table to add new login attributes.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Profiles Jython script interpreter.
- Enter the following command to access the Profiles configuration files:
execfile("profilesAdmin.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Enter the following command to check out the Profiles configuration files:
ProfilesConfigService.checkOutConfig("working_directory", "cell_name")where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes (/) to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not complete successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the Profiles application. This argument is required. It is also case-sensitive, so type it with care. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- AIX or Linux:
ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")
- Microsoft
Windows:
ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")
- Locate the Profiles configuration file, profiles-config.xml, in the local working directory specified in the checkOutConfig command. The Profiles configuration file contains the various configuration settings for the Profiles application. The following section of the file can be used for customizing login attributes:
<loginAttributes> <loginAttribute>uid</loginAttribute> <loginAttribute>email</loginAttribute> <loginAttribute>loginId</loginAttribute> </loginAttributes>
The uid, mail, and loginId options are on the first side of the + in the map_dbrepos_from_source.properties file and refer to data in the Profiles database table. The value on the other side of the = is the LDAP (or function) name.
- The uid value pertains to the EMPLOYEE PROF_UID column.
- The email value pertains to the PROF_MAIL column.
- The loginId value pertains to the EMPLOYEE PROF_LOGIN column and the PROF_LOGIN table and refers to the mappings loginId= and logins=. For example, you could set logins= to employee number.
- Comment out any attributes that are not used in your environment, as in the following example:
<loginAttributes> <loginAttribute>uid</loginAttribute> <! -- The following login attribute is not used <loginAttribute>email</loginAttribute> --> <loginAttribute>loginId</loginAttribute> </loginAttributes>
Create a simple profile data model and template customization
This example demonstrates the required steps for customizing the profile data model and template files to complete a simple customization.
In this example, an administrator will add a new Education section to the master profile page. The new section will be available to all users and will contain the following new fields:
Profile owners can edit these fields using their Edit Profile page. The fields are searchable.
- College . simple text input field for college name
- High School . simple text input field for high school name
- Publications . rich text field to describe any patents or publications, for example linking and attachments are allowed in this field
For related information and information about using the wsadmin client to make these changes, see Customize display using templates.
- Modify LotusConnections-config.xml to register your custom resource bundle to provide new labels for your custom properties by adding the following into the <resources/> section.
<widgetBundle prefix="customBundle" name="com.example.resources.customBundle"/>For related information, see Extension properties in the data model.
- Declare the new extension properties in the profiles-config.xml file.
<profileExtensionAttributes> <!-- sample extension --> <simpleAttribute extensionId="highSchool" length="256"/> <simpleAttribute extensionId="college" length="256"/> <richtextAttribute extensionId="publications" maxBytes="1000000"/> </profileExtensionAttributes>For related information, see Profile-types.
- Declare the usage of a custom resource bundle in the profiles-config.xml file that will be used for custom property labels in your template files.
<templateNlsBundles>customBundle</templateNlsBundles>For related information, see Customize profile page display.
- Create a new file in <IBM_Connections_Customization_Dir>/stringscalled com.example.resources.customBundle.properties and add the following key/value pairs.
Education=Education label.highSchool=High School: label.college=College: label.publications=Publications:For related information, see Configuring template custom resource bundles for processing.
- Add properties to the associated profile-type definition by editing profiles-types.xml. For example, add the following to the default profile type definition.
<property> <ref>college</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <fullTextIndexed>true</fullTextIndexed> </property> <property> <ref>highSchool</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <fullTextIndexed>true</fullTextIndexed> </property> <property> <ref>publications</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <fullTextIndexed>true</fullTextIndexed> </property>For related information, see Configuring profile types for widget layout.
- Modify profileDetails.ftl to define a custom section for the new information that will render the fields with labels from your custom resource bundle.
<#-- for custom scenario --> <@util.renderSection sectionLabel="education"> <div class="lotusSectionBody"> <table class="lotusVertTable"> <tbody> <@util.renderProperty ref="highSchool" nlsBundle="customBundle" nlsKey="label.highSchool" hideIfEmpty=false ; ref, dataId, dataKey, nlsKey, nlsBundle> <tr> <th scope="row"> <@util.renderNls nlsKey=nlsKey nlsBundle=nlsBundle/> </th> <td> <@util.renderValue ref=ref/> </td> </tr> </@util.renderProperty> <@util.renderProperty ref="college" nlsBundle="customBundle" nlsKey="label.college" hideIfEmpty=false ; ref, dataId, dataKey, nlsKey, nlsBundle> <tr> <th scope="row"> <@util.renderNls nlsKey=nlsKey nlsBundle=nlsBundle/> </th> <td> <@util.renderValue ref=ref/> </td> </tr> </@util.renderProperty> <@util.renderProperty ref="publications" nlsBundle="customBundle" nlsKey="label.publications" hideIfEmpty=false ; ref, dataId, dataKey, nlsKey, nlsBundle> <tr> <th scope="row"> <@util.renderNls nlsKey=nlsKey nlsBundle=nlsBundle/> </th> <td> <@util.renderValue ref=ref/> </td> </tr> </@util.renderProperty> </tbody> </table> </div> </@util.renderSection>For related information, see Customize edit display fields.
- Edit the widget-config.xml file to define the new widget definition to present this data, associate it with your custom resource bundle, and add the widget to the profileView page.
The widget definition and reference ID cannot be repeated.
... <widgetDef defId="Education" url="{contextRoot}/widget-catalog/profile-details.xml?version={version}" modes="view fullpage" helpLink="{helpSvcRef}/topic/com.ibm.lotus.connections.profiles.help/c_pers_profiles.html" bundleRefId="customBundle"> <itemSet> <item name="section" value="education"/> </itemSet> </widgetDef> .... <page pageId="profilesView"> <widgetInstance uiLocation="col2" defIdRef="multiWidget" instanceId="tabsWidget1"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="Education"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="Updates"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="contactInfo"/> <widgetInstance uiLocation="tabsWidget1" defIdRef="backgroundInfo"/> ... </page>
- Edit the profileEdit.ftl file to allow the user to edit the field values by adding the following to the end of the contactInformation and associatedInformation sections.
<@util.renderSection sectionLabel="contactInformation"> ... <@util.renderFormControl ref="highSchool" singleColumnLayout=false nlsBundle="customBundle" nlsKey="label.highSchool"/> <@util.renderFormControl ref="college" singleColumnLayout=false nlsBundle="customBundle" nlsKey="label.college"/> </@util.renderSection> <@util.renderSection sectionLabel="associatedInformation"> ... <@util.renderFormControl ref="publications" singleColumnLayout=true nlsBundle="customBundle" nlsKey="label.publications"/> </@util.renderSection>
- Restart the server. View your changes on the profile page and profile edit form.
- Stop the server. You.ll now and make the following changes to make the High School field required when making edits in the web interface.
- Save a copy of the was_profile_root\installedApps\cell_name\profiles.ear\lc.profiles.app.war\WEB-INF\validation.xml file.
- Open the file in a text editor and add the following field validation syntax to the <form/> section. Save the file, and ensure your changes are pushed to each node in a cluster.
<field property="attribute(highSchool)" depends="required,nonce"> <msg name="required" key="errors.required" /> <arg position="0" name="required" key="label.editprofile.highSchool" /> <var> <var-name>subEditForm</var-name> <var-value>contactInfo</var-value> </var> </field>
- Open the installedApps/Profiles.ear/lc.profiles.app.war/WEB-INF/lib/lc.profiles.web.app.jar: com/ibm/lconn/profiles/strings/ui.properties file and extract the version of each resource file for each locale and save a copy for each locale using the following sample as a guide:
<IBM_Connections_Customization_Dir>/strings/com.ibm.lconn.profiles.strings.ui.properties
- Edit the properties file for each locale, and add the following key/value pair for localization:
label.editprofile.highSchool=High School
- Restart the server and navigate to a user profile for edit. The High School field is now required and the error message is applied with your custom field label key.
Add new ways to share content
IBM Connections provides a quick way to share content with others. From anywhere in IBM Connections, users can click Share. To enable an opensocial gadget to surface in the Share dialog you need to specify feature requirements in the gadget xml and add the gadget using the Administration option on the Home page.
You can create your own gadgets and add them to the Share dialog. In this context, your gadgets should probably allow a user to share content with other users, but you can add anything.
You can optionally add the following features to your gadget:
- A feature to close the share dialog from the gadget, for example allowing you to add a Close button to your gadget that closes the dialog.
- A feature to inform the dialog of a submit state, for example allowing you to show a progress indicator while something is being submitted.
- Ensure that gadgets loaded in the Share dialog have their gadget XML conform to the following OpenSocial feature requirements.
<Require feature="dynamic-height" /> <Require feature="dynamic-width" /> <Require feature="views" />
- Require the ibm.connections.sharedialog feature, for example:
<Require feature="ibm.connections.sharedialog" />This feature only should be used by gadgets rendered in the Share dialog.
- Include the actions feature and define an action with a path of "container/sharebox".
<Optional feature="actions"> <Param name="action-contributions"> <![CDATA[ <actions> <action id="customAction" path="container/sharebox" label="Read Only Sample" tooltip="used to show Share dialog gadget loading concept" /> </actions> ]]> </Param> </Optional>Where:
- The action element's id attribute must be unique across all gadgets that you intend to surface in the dialog. If more than one gadget has an action element with the same id attribute value, then each gadget after the first one loaded with the same id will fail to load. If this issue exists and you have a JavaScript console available for your browser, you will see a message similar to the following in the JavaScript console:
Duplicated gadget action [gadget-name] detected. make sure the gadget actions have unique ids.
- In the path attribute, use the value container/sharebox to have the gadget display in the Share something dialog.
- In the label attribute, add the name of the gadget to display as a tab in the dialog, for example the value label="MyGadget" means the dialog will display the following tabs: Status Update | Files | MyGadget.
- In the tooltip attribute, add more descriptive text about the gadget to display as tooltip text that appears when hovering over the tab for the gadget.
- Define your action and a callback function to be called when the action has been invoked (such as when a tab has been selected for this gadget to be displayed or to perform some action. For example:
<script type="text/javascript"> gadgets.util.registerOnLoadHandler(function() { if (gadgets.actions) { var customAction = { id: "customAction", /* The id matches the id of the action from the ModulePrefs section - Example: <action id="customAction" path="container/sharebox" label="Custom Action" /> */ callback: updateContext /* The callback function will get called each time the action is invoked(Sharebox Example: Every time the tab is selected.*/ }; gadgets.actions.updateAction(customAction); } }); function updateContext(selection) { if(selection.type == "com.ibm.social.sharebox.context") initCustomContent(selection.dataObject); /*Perform gadget initialization with the "context' that is available via "selection.dataObject".*/ } </script>The selection object will consist of atype and dataObject attribute. When an action is invoked in the Share dialog, a selection object will be provided to the action callback (updateContext in this case) and the object will have a type of com.ibm.social.sharebox.context. If the type value is not com.ibm.social.sharebox.context, then this selection did not come from Sharebox. The actual context object is available via the dataObject attribute. Example selection.dataObject: {type: "global"}
The callback defined for your action ( "updateContext" function in this example) will get called each time the user visits your gadget's tab in the Share dialog. The following scenarios will result in the callback being called:
- User visits tab of gadget. The first time this happens, you will want to initialize your gadget contents. Each additional time, you will only want to do an update if desired.
- User closes the Share dialog while your tab is in focus and then reopens the Share dialog without leaving the current page or performing a page refresh. The callback will get called when the Share dialog is opened.
- Design your gadget so that the contents will have a width that does not exceed 500px.
- Each time the contents of your gadget's DOM (document object model) change, then call the following code to force the gadget to resize:
if (gadgets.window.adjustHeight) gadgets.window.adjustHeight(); if (gadgets.window.adjustWidth) gadgets.window.adjustWidth(500); /*Pass in 500 so that gadget will know the preferred width is 500px*/
Add a Gadget to the Share dialog
To add widgets to the Home page, you must be logged in as an administrator. If you do not see an Administration option display under the My Page option in the navigation sidebar on the Home page. This task shows how to add an OpenSocial gadget to the Share dialog, resulting in an additional tab being displayed in the Share dialog.
- Open the Administration view.
- Click Add another widget to display the Add new widget form.
- For the Share dialog
- Select that the widget is based on theOpen Social Gadget specification.
- Select Trusted as the security type because the gadget will need access to the ibm.connections.sharedialog container feature
- Select Show in Share dialog for UI integration point and select in the drop-down the name of the gadget that your gadget should follow in the Share dialog tab order.
- Enter a name for the widget in the Widget Title field.
- Enter a short description of the widget in the Description field.
- Enter the web address for the XML widget descriptor in the URL Address field. This address must be an absolute web address.
- Enter the widget location in the Secure URL Address field. This address must be an absolute web address.
- The Icon URL web address does not apply to adding gadgets to the Share dialog so you can ignore it.
- The Icon Secure URL address does not apply to adding gadgets to the Share dialog so you can ignore it.
- The IBM Connections specific tags option does not apply to adding gadgets to the Share dialog so you can ignore it.
- The Display in the My Page view does not apply to adding gadgets to the Share dialog so you can ignore it.
- The Display in the Updates view does not apply to adding gadgets to the Share dialog so you can ignore it.
- The option Opened by default does not apply to adding gadgets to the Share dialog so you can ignore it.
- To enable multiple instances of the widget to be used, select Multiple widgets. Each widget instance has its own properties, which can be useful. For example, if you are using a widget that displays bookmarks for a specific tag, you might want to enable multiple instances of the widget so that you can follow different tags in each widget.
This setting is only applicable for iWidgets. Only one instance of an OpenSocial gadget may be loaded at a time.
- Select opensocial as a required application in the Prerequisites area.
- Click Save.
- Open the Administration view and in the Disabled widgets area, select the gadget to enable, and click Enable.
Optional features for custom sharing gadgets
Add features to your gadgets for interacting with the Share dialog.
Constants
These features are available for all open social sharebox gadgets and used by Files Sharebox Gadget, Status Update Sharebox Gadget, and third party gadgets.
Table 69. Constants names and descriptions
Name Description MessageTypeParam.ERROR
Display message with Error styling as defined by the One UI standard.
MessageTypeParam.SUCCESS
Display message with Success styling as defined by the One UI standard.
MessageTypeParam.WARNING
Display message with Warning styling as defined by the One UI standard.
Methods
Table 70. Method signatures and descriptions
Method Signature and Example Description close()
Example:
ibm.connections.sharedialog.close();This call tells the share dialog to close. This impacts all gadgets in the share dialog that have registered a close listener.
displayMainPageMessage(messageType, message)
Example:
ibm.connections.sharedialog.displayMainPageMessag( ibm.connections.sharedialog.MessageTypeParam.SUCCESS, "The message was successfully posted.");This call specifies that a message be displayed outside of the Share dialog.
Message types to display are of the following format:
ibm.connections.sharedialog.MessageTypeParam.SUCCESS ibm.connections.sharedialog.MessageTypeParam.INFO ibm.connections.sharedialog.MessageTypeParam.ERROR messageregisterCloseListener(listenerFunc)
Example:
ibm.connections.sharedialog.registerCloseListener(function(){ //Clear gadget contents });This call registers the functions to be called when the Share dialog is about to close. Set the logic to return the gadget to the default state in the function registered.
onActivityEntryAddition(itemId)
Example:
ibm.connections.sharedialog.onActivityEntryAddition("d0bd18eb-b55c-46e3-b116-2a77c4344b44");This call indicates that a performed task will result in an activity entry of the specified item ID.
This enables the activity stream to refresh because there is potentially a new activity entry to display.
setDirty(actionId, isDirty)
Example:
ibm.connections.sharedialog.setDirty("actionId", true); ibm.connections.sharedialog.setDirty("actionId", false);The gadget calls this when the dirty state has changed.
The actionId corresponds to the tab that is dirty.
Set to true when data has been entered in one or more fields in the gadget. Set to false when no changes from the user exist in the gadget.
If the gadget dirty state is true, when a user tries to close the Share dialog by using means outside of the dirty gadget, they are prompted to confirm the current action and lose changes.
setSubmitState(inProgress)
Example:
ibm.connections.sharedialog.setSubmitState(true); ibm.connections.sharedialog.setSubmitState(false);Gadget calls the share dialog whether or not the gadget is in a submit state. This is needed if the gadget can prevent the user from switching tabs while a submission is in process.
Set to true when the item in the submission state. Set to false when the item is not in the submit state.
If set to true, then the user cannot switch to a different gadget tab.
Required post-customization step
Edit a configuration property to make sure that your users will see the changes you have made to the product the next time they log in without having to clear the cache of their web browser.
Only perform this procedure if you made customization changes to the product user interface.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for details.
Each product web page downloads static script and stylesheets that do not change often. To optimize performance, it is recommended that these pages are cached for extended periods of time so that end users only need to download them once per product upgrade. After you make customizations, you can instruct the server to ensure that all web browsers download new copies of these files. To force web browsers to refresh all cached content on the next visit, run the following command to update the product version stamp. The version stamp is automatically updated when you install any ifixes or major product version upgrades.
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Enter the following command to increment the value of the versionStamp property: LCConfigService.updateConfig("versionStamp","gmt_timestamp") where gmt_timestamp is the GMT time. You can specify an empty string for the time stamp or provide a GMT value string. When you specify an empty string, the client calculates the current GMT time and updates the version stamp with that value. If you choose to provide the time, specify it using the following format: yyyyMMdd.HHmmss and specify the time in GMT. It is best to provide an empty string and let the client format the time stamp. For example: LCConfigService.updateConfig("versionStamp","").
- After making changes, you must check the configuration files back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
Customize Metrics reports
Metrics data displays as reports, which you can customize for your organization. When you install IBM Cognos Business Intelligence to support the Metrics application, a set of standard reports is immediately available. You can customize the standard reports by editing the configuration file that defines each report.s layout. In addition, you can use IBM Cognos Report Studio to create new reports.
Modify reports
IBM Connections provides several ways to customize the reports that display in the Metrics user interface. In addition to creating new reports, you can modify the text labels and links used in existing reports, as well as nest reports or group them under a custom title.
Modify report labels
In the Metrics user interface, a report is identified with a text label. You can change a report.s label by modifying the text label by modifying the reports-config.xml file.
You can customize the labels associated with reports by editing the reports-config.xml file and modifying the value specified for the label property. You can modify an existing label property by assigning a new value to it, or you can create a new label property with its own value.
- On the computer where Cognos BI Server is installed, open the reports-config.xml file for editing.
The file is typically located in the following directory:
IBM\WebSphere\AppServer\profiles\Profile_Name\config\cells\Cell_Name\LotusConnections-config\metricsfor example:IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics
- In the reports-config.xml file, locate the section that represents the report you want to modify.
The description for each report begins with an XML entry tag that specifies the report ID and label.
< entry id="customized_report" type="report" label="CUSTOMIZED_REPORT_LABEL">
- Modify the report.s label by replacing the text value specified for the label property.
<entry id="customized_report" type="report" label=" Type a label for the report here ">
- Save and close the file.
- Refresh the browser before viewing the report to verify the new label.
There is no need to restart the Cognos BI Server.
- If you added a new label, make sure that the new property is defined either in the shipped resource bundle (for example, if it is already used in another standard report) or in the customization bundle file.
For example, if you created a new label value called CUSTOMIZED_REPORT_LABEL, you should define this value in the string customization properties file as CUSTOMIZED_REPORT_LABEL=customized report. The customization properties file is stored in the following location: ..\IBM\LotusConnections\data\shared\customization\strings\com.ibm.connections.metrics.ui.strings.ui.properties.
Modify report links
When you create a report, make it available to users by adding an entry, including a link to the report, to the reports-config.xml file. If you later create a different version of the report, you can modify an existing entry.s link to the point to the new report.
Edit a report.s link or add new links for custom reports in the reports-config.xml file.
- On the computer where Cognos BI Server is installed, open the reports-config.xml file for editing.
The file is typically located in the following directory:
IBM\WebSphere\AppServer\profiles\Profile_Name\config\cells\Cell_Name\LotusConnections-config\metricsfor example:IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics
- In the reports-config.xml file, locate the section that represents the report you want to modify.
The description for each report begins with an entry tag that specifies the report ID and label so you can identify it.
< entry id="customized_report" type="report" label="CUSTOMIZED_REPORT_LABEL">
- Add a link for a custom report by inserting a child node named link within the entry tag (add a node for each report link).
For a custom global report, insert a child node named link within the <entry> tag (add a node for each new report.s link).
In the link, format the URL as a CDATA element and omit the domain and port as shown in the example that follows.
<entry id="global_customized_report_1" type="report" label="GLOBAL_CUSTOMIZED_REPORT_LABEL_1"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry>For a custom community report, only need to specify the report name, without the URL:
<entry id="commuity_customized_report_1" type="report" label="COMMUNITY_CUSTOMIZED_REPORT_LABEL_1"> <link> Community_report_name </link> </entry>
- Save and close the file.
- Refresh the browser before viewing the report to verify the new link.
There is no need to restart the Cognos BI Server.
Create a report from a predefined layout
Use IBM Cognos Report Studio to create a simple report, based on a predefined layout, for the Metrics application to display.
The instructions that follow demonstrate the procedure for creating a simple report using Cognos Report Studio. Follow the steps in the example to create a column chart showing the total number of times items were updated ("update" events) for each Connections applications. The report will use three basic sets of data:
T
- The Measure is the quantity; the example report shows the total number of times an event occurred (EVENT_COUNT).
- The Dimensions are the qualifiers that describe what is being counted, for example the Connections applications where events occurred.
The Categories are subsets of a dimension; for example the SOURCE dimension contains categories for all of the Connections applications (Bookmarks, Forums, Profiles, and so on).
- The Data Series is the measure being tracked; the example report will track "update events" (UPDATE) across multiple applications so you can compare the totals.
For more information on the dimensions (Measures and Categories) available in the Metrics PowerCube, see PowerCube dimensions. For more information on working with Cognos Report Studio, see the Report Studio User Guide.
- Choose a unique name for the report:
For best results, use a unique name for every report. This is required for community metrics because the job list that controls report updates cannot contain duplicate names. Before you create a report, check the list of existing community reports to make sure your new report will have a unique name.
- Open a browser and navigate to the Cognos dashboard using the following address: http://cognosserver.example.com:9083/cognos/servlet/dispatch/ext
- Log in to Cognos as the Cognos administrator.
- Click Public Folders > IBMConnectionsMetrics > Metrics > static.
- In the Name column, locate the job called jobtemplate and click its Set properties
icon.
- Click the Job tab.
- Review the list of reports; if you see a name matching the planned report, choose a different name for the new report.
- Click Cancel and exit the job.s properties page.
- Open Cognos Report Studio:
- Return to the Cognos dashboard.
- Click Launch > Report Studio.
- When prompted to select a data package, select IBMConnectionsMetrics > Metrics to create a report that queries the PowerCube containing Metrics data.
- In the Report Studio Welcome window, click Create a new report or template.
- Select a report type:
- In the New window, select a type of report by clicking the image that represents the general type of display the report will generate.
For this example, select Column; this displays the available formats for a column chart.
- In the Insert chart window, select a specific format from the display corresponding to the type of chart you selected in the previous step.
For this example, select any column chart format. Because the example tracks a very limited data series, there is no data to stack and all of the column formats will appear similar in the output.
- Click OK.
- Select a Measure for the chart to track along the Y-axis:
The Y-axis displays measures of quantitative data, such as sales figures or quantities.
- Click the Source
tab.
- In the packages list, expand the METRICS_TRX_CUBE datasource.
- Select EVENT_COUNT and drag it to the Default measure (y-axis) area of the chart.
- Select the specific categories (applications, in this example) to be tracked along the X-axis:
The X-axis displays categories (groups of related data) that are plotted on the X-axis so you can compare them. Categories are qualitative because they represent things rather than quantities. For this example, events (on the Y-axis) are tracked for activities within Connections applications. Each application is s category and is plotted along the X-axis. The "source" of the categories includes all Connections applications. There are two ways to select the categories; use the method that is simplest for the your report:
Begin with all categories and exclude the categories you do not want in the report:
- Return to the METRICS_TRX_CUBE datasource.
- Expand SOURCE and select the SOURCE hierarchy; drag it to the Categories (x-axis) area of the chart.
- Click All Members to begin by including the complete list of categories.
- On the Categories (x-axis) area of the chart, click <#SOURCE#> tag.
- In the Properties window, click the Edit button for the "Set Definition" property.
- In the Set Definition window, right-click the SOURCE hierarchy and select New > Exclude.
- In the Exclude window, expand the METRICS_TRX_CUBE datasource.
- Select SOURCE in the Available members list and click the right-arrow icon to copy it to the excluded Members list.
- Select DEFAULT in the Available members list and click the right-arrow icon to copy it to the excluded Members list.
DEFAULT represents a special calculation that is not needed for this simple report, so you should exclude it.
- Click OK.
Begin with no categories and include only the categories you want in the report:
- Return to the METRICS_TRX_CUBE datasource.
- Expand SOURCE and select the SOURCE hierarchy.
- Expand Members and select SOURCE.
- Click a category to include in the report; Ctrl+Click each additional category to add it to the selection; then drag the selection to the Categories (x-axis) area of the chart.
- Click OK.
- Select the data series:
A data series is a group of related data points that are plotted in a chart. This example reports on updated items, which uses the UPDATE type of the EVENT measure as the data series. Because this report only tracks the total number of updates for each Connections application, the data series contains only the one measure (UPDATE). A more complex report might chart the total number of updates for each application over a series of months or years; in that case the data series would include each month or year being reported.
- Expand the METRICS_TRX_CUBE > EVENT measure.
- Expand Members > EVENT.
- Select UPDATE and drag it to the Series area of the chart.
- Click Save and store the report in Public Folders > IBMConnectionsMetrics > Metrics > customReports.
All custom reports should be stored in the this location to make them available to the Metrics application.
- Click Run > Run Report - HTML to test the report by viewing it in the Cognos Viewer; then close the viewer when ready to proceed.
- Determine the URL for the new report so you can add it to the Metrics user interface:
- Return to the Cognos dashboard.
- Navigate to the location where you saved the report, and select the new report.
- Click the Set properties icon
.
- In the Set properties window, click the General tab.
- On the General tab, click View the search path, ID and URL.
- In the View the search path, ID and URL window,
- Copy the entire URL from the Default action url field.
- Click Close.
- Leave the Cognos dashboard open so you can return to it in step 11.
- Modify the report URL and add it to the Metrics user interface:
- Paste the copied URL into a text editor.
- In the URL, replace http://localhost:80/ibmcongos/cgi-bin/cognos.cgi with /servlet/dispatch/ext.
The remainder of the URL (everything from ?b_action= through the end of the URL) stays the same.
For example:
http://localhost:80/ibmcognos/cgi-bin/cognos.cgi ?b_action=cognosViewer&ui.action=run&ui.object=%2fcontent%2ffolder%5b%40name%3d%27IBMConnectionsMetrics%27%5d%2fpackage%5b%40name%3d%27Metrics%27%5d%2ffolder%5b%40name%3d%27customReports%27%5d%2freport%5b%40name%3d%27test1%27%5d&ui.name=test1&run.outputFormat=&run.prompt=truebecomes:/servlet/dispatch/ext ?b_action=cognosViewer&ui.action=run&ui.object=%2fcontent%2ffolder%5b%40name%3d%27IBMConnectionsMetrics%27%5d%2fpackage%5b%40name%3d%27Metrics%27%5d%2ffolder%5b%40name%3d%27customReports%27%5d%2freport%5b%40name%3d%27test1%27%5d&ui.name=test1&run.outputFormat=&run.prompt=true
- Use the revised URL, add an entry for the new report in the reports-config.xml file as explained in Add custom reports to the Metrics reports list.
Your new report will not be available to users until you have added it to the reports-config.xml file.
- (Community metrics) If the new report is for use in community metrics, add it to the job list so it can be updated from the Community Metrics user interface:
Global reports are updated automatically whenever an authorized user views them. Community reports are used by a much larger set of users, so they are updated only when a community owner or other authorized user clicks Update in the Community Metrics user interface; at that point all of the community reports specified in the job list are refreshed. To ensure that the new report will be refreshed whenever Update is clicked, add the report to the job list.
- Return to the Cognos dashboard.
If you closed the dashboard you can access it at the following address: http://cognosserver.example.com:9083/cognos/servlet/dispatch/ext.
- Click Public Folders > IBMConnectionsMetrics > Metrics > static.
- In the Name column, locate the job called jobtemplate and click its Set properties
icon.
- Click the Job tab.
- Click Add.
- Locate the new report in the Available entries list and click the right-arrow icon to add the report to the Selected entries list.
- Click OK.
- Repeat substeps c through g and add the same report to the job named jobtemplate1.
Create a report from a blank layout
Use IBM Cognos Report Studio to create a report from a blank layout for the Metrics application to display. Creating a report from a blank layout requires you to add report components manually; although this type of report involves more work than a predefined layout, it provides greater flexibility.
The instructions that follow demonstrate how to create a report from a blank layout using Cognos Report Studio and then add different features to the base layout. The examples are independent and do not have to be completed in sequence.
Create a blank report from the PowerCube model
Rather than creating a report based on a predefined layout, you can create a blank layout and then choose which report components to include.
A blank layout is an empty report container. After you create the blank layout, you can choose which reporting components to include; for example, you can add formatting objects, data items, and charts to the layout to create your custom report.
- Choose a unique name for the report:
For best results, use a unique name for every report. This is required for community metrics because the job list that controls report updates cannot contain duplicate names. Before you create a report, check the list of existing community reports to make sure your new report will have a unique name.
- Open a browser and navigate to the Cognos dashboard using the following address: http://cognosserver.example.com:9083/cognos/servlet/dispatch/ext
- Log in to Cognos as the Cognos administrator.
- Click Public Folders > IBMConnectionsMetrics > Metrics > static.
- In the Name column, locate the job called jobtemplate and click its Set properties
icon.
- Click the Job tab.
- Review the list of reports; if you see a name matching the planned report, choose a different name for the new report.
- Click Cancel and exit the job.s properties page.
- Open Cognos Report Studio:
- Return to the Cognos dashboard.
- Click Launch > Report Studio.
- In the Report Studio Welcome window, click Create a new report or template.
- In the New window, select Blank
report, and then click OK.
- Complete the report design by adding data and text components to the blank report.
For instructions on adding some basic components to the report, see the following topics:
- Add a layout component to a blank report
- Add a chart to a blank report
- Add a crosstab to a blank report
- Add dimensional calculations to a blank report
- Click Save and store the report in Public Folders > IBMConnectionsMetrics > Metrics > customReports.
All custom reports should be stored in the this location to make them available to the Metrics application.
- When the report is complete, determine its URL so you can add the report to the Metrics user interface:
- Return to the Cognos dashboard.
- Navigate to the location where you saved the report, and select the new report.
- Click the Set properties icon
.
- In the Set properties window, click the General tab.
- On the General tab, click View the search path, ID and URL.
- In the View the search path, ID and URL window,
- Copy the entire URL from the Default action url field.
- Click Close.
- Modify the report URL for use within the Metrics user interface:
- Paste the copied URL into a text editor.
- In the URL, replace http://localhost:80/ibmcongos/cgi-bin/cognos.cgi with /servlet/dispatch/ext.
The remainder of the URL (everything from ?b_action= through the end of the URL) stays the same.
For example:
http://localhost:80/ibmcognos/cgi-bin/cognos.cgi ?b_action=cognosViewer&ui.action=run&ui.object=%2fcontent%2ffolder%5b%40name%3d%27IBMConnectionsMetrics%27%5d%2fpackage%5b%40name%3d%27Metrics%27%5d%2ffolder%5b%40name%3d%27customReports%27%5d%2freport%5b%40name%3d%27test1%27%5d&ui.name=test1&run.outputFormat=&run.prompt=truebecomes:/servlet/dispatch/ext ?b_action=cognosViewer&ui.action=run&ui.object=%2fcontent%2ffolder%5b%40name%3d%27IBMConnectionsMetrics%27%5d%2fpackage%5b%40name%3d%27Metrics%27%5d%2ffolder%5b%40name%3d%27customReports%27%5d%2freport%5b%40name%3d%27test1%27%5d&ui.name=test1&run.outputFormat=&run.prompt=true
- Use the revised URL, add an entry for the new report in the reports-config.xml file as explained in Add custom reports to the Metrics reports list.
Your new report will not be available to users until you have added it to the reports-config.xml file.
Add a layout component to a blank report
The layout defines the appearance of the report, including formatting, style, and design.
The example report will use a table to control the placement of report components. A table is a simple formatting tool that lets you place report objects into a basic layout by inserting objects such as charts and labels into different cells within the table. Use the Toolbox feature in Cognos Report Studio to add a table to the blank report.
- Create a blank report as described in Create a blank report from the PowerCube model.
- Click the Toolbox
tab.
- In the Toolbox window, select the Table object
and drag the it to the report.s layout.
- In the Insert Table dialog box, specify values in the Number of rows and Number of columns fields, and then click OK.
- (Optional) Format the table.
There are a variety of formatting options available in Report Studio; you might want to try some of the following simple formatting commands:
- Apply a predefined style to an entire table object by clicking Table > Apply Table Style and selecting a style from the Table Styles dialog box.
- Set only specific attributes for the table by clicking the table object and selecting settings in the Attributes window (you can set attributes for cell also).
- Merge cells within the table by selecting the cells and clicking Table > Merge Cells.
- To see how the table can control the report layout, experiment with adding other report objects such as legends and charts, into the various cells within the table.
- Click Save to save the updated layout.
Add a chart to a blank report
Add a data chart to a report.s layout.
The instructions that follow demonstrate the procedure for adding a chart to an empty report layout using Cognos Report Studio. Follow the steps in the example to create a trend chart within the existing report layout. Trends show patterns in data; for example by tracking totals over time or comparing totals for different categories. The trend chart created for this example report will show the total number of "create" events for all Connections applications for the years 2010, 2011, and 2012. The report will use three basic sets of data:
- The Measure is the quantity; the example report shows the total number of times an event occurred (EVENT_COUNT).
- The Dimensions are the qualifiers that describe what is being counted, for example the DATE when an event occurred.
The Categories are subsets of a dimension; for example the DATE dimension contains categories for the years 2010, 2011, and 2013.
- The Data Series is the measure being tracked; the example report will track "create events" (CREATE) across multiple years to show the overall trend (all "create" events across all Connections applications will be counted for each year).
For more information on the dimensions (Measures and Categories) available in the Metrics PowerCube, see PowerCube dimensions. For more information on working with Cognos Report Studio, see the Report Studio User Guide.
- Create a blank report as described in Create a blank report from the PowerCube model.
- Place a "line graph" style of chart in the report layout:
A line graph displays a point for each data item (the intersection between a measure and a category) and connects these data points with a line. Line graphs are useful for showing trends because it is easy to see how the line moves up or down (or not at all) over time.
- Click the Toolbox
tab.
- In the Toolbox window, select the Chart
object and drag it to the design area.
- In the Insert Chart dialog box, select Line from the list of chart styles, select the Line with markers icon; then click OK.
- Select the Measure to display on the Y-axis:
In this example, the measure is EVENT_COUNT.
- Click the Sources
tab.
- In the packages list, expand the METRICS_TRX_CUBE datasource.
- In the Measures list, select EVENT_COUNT; drag it to the Default measure (y-axis) area of the chart.
- Select the Categories to display across the X-axis:
In this example, the categories are the years for which "create" events are being counted (the DATE): 2010, 2011, and 2012.
- Return to the METRICS_TRX_CUBE datasource and expand the DATE dimension.
- Expand Members > DATE.
- Select 2010 and drag it to the Categories (x-axis) area of the chart.
- Select 2011 and drag it to the Categories (x-axis) area of the chart, placing it after 2010.
- Select 2012 and drag it to the Categories (x-axis) area of the chart, placing it after 2011.
- Select the data series:
In this example, the data series is the type of event being counted: the CREATE.
- Return to the METRICS_TRX_CUBE datasource and expand the EVENT dimension.
- Expand Members > EVENT.
- Select CREATE and drag it to the Series area of the chart.
- Click Save to save the updated report.
- Click Run > Run Report - HTML to test the report by viewing it in the Cognos Viewer; then close the viewer when ready to proceed.
Add a crosstab to a blank report
A crosstab (cross table) shows the relationship between two or more sets of data; for example the number of wikis added compared to the number of forums added in the past year. The simplest form of crosstab shows one Measure, one set of Categories, and one Data series. The example report created in the instructions that follow uses a crosstab to display the same data as in the example trend chart created in Add a trend chart to a report; in this example the report will display as a table instead of a line chart.
Earlier examples added the Measures to a report first but in a crosstab, the measure appears within each cell of the table.s data area, so it will be added last to keep the instructions clear.
For more information on the dimensions (Measures and Categories) available in the Metrics PowerCube, see PowerCube dimensions. For more information on working with Cognos Report Studio, see the Report Studio User Guide.
- Create a blank report as described in Create a blank report from the PowerCube model.
- Place a crosstab object in the report layout:
A crosstab displays as a table with areas marked for you to add rows, columns, and measures to the report.
- Click the Toolbox
tab.
- In the Toolbox window, select the Crosstab
object and drag it to the design area.
- Select the Categories to display in the rows of the crosstab:
In this example, the categories are the years for which "create" events are being counted (the DATE): 2010, 2011, and 2012; each row in the crosstab will represent a year.
- Click the Sources
tab.
- In the packages list, expand the METRICS_TRX_CUBE datasource, and then expand the DATE dimension.
- Expand Members > DATE.
- Select 2010 and drag it to the Rows area of the crosstab.
- Select 2011 and drag it to the Rows area of the crosstab, placing it after 2010.
- Select 2012 and drag it to the Rows area of the crosstab, placing it after 2011.
- Select the data series to display in the column of the crosstab:
In this example, the data series is the type of event being counted: the CREATE; the data series appears in a column of the table (if your report includes multiple data series, each data series would be placed in a different column).
- Return to the METRICS_TRX_CUBE datasource.
- Expand Members > EVENT, and then expand the EVENT dimension.
- Select CREATE and drag it to the Columns area of the crosstab.
- Select the Measure to display on column of the crosstab:
In this example, the measure is EVENT_COUNT; each cell within the crosstab will display the number of "create" events for the year represented by the current row.
- Return to the METRICS_TRX_CUBE datasource.
- Expand Measures and select EVENT_COUNT; then drag it to the Measures area of the crosstab.
- Click Save to save the updated report.
- Click Run > Run Report - HTML to test the report by viewing it in the Cognos Viewer; then close the viewer when ready to proceed.
Add a dimensional calculation to a blank report
Create a report using a dimensional calculation to query the PowerCube and retrieve the tuple representing the intersection between different dimensions of the data.
In reports, basic data items use counts drawn directly from the PowerCube. The example reports showing total "update" and "create" events for the Connections applications simply query the Metrics PowerCube directly for those totals and require no additional calculation. A more complex report might present the number of "create" events for the "file" item in the Files application only (that is, it would show the number of new files created in the Files application). This count is not stored directly in the PowerCube; however the "create" event counts, the different data items, and the different Connections applications are all included in the PowerCube. Each of those values is represented in a dimension of the PowerCube; the point
...where they intersect is called a tuple. You can create a dimensional calculation for a report to query the PowerCube for the value stored in the tuple that represents that intersection.
The instructions that follow demonstrate the procedure for creating a report using a dimensional calculation to query the PowerCube and retrieve a tuple. Follow the steps in the example to create a report using a dimensional calculation to query the Metrics PowerCube and retrieve the tuple representing "new files created in the Files application for the years 2010, 2011, and 2012" and then display the result in a trend chart.
For more information on the dimensions available in the Metrics PowerCube, see PowerCube dimensions. For more information on working with Cognos Report Studio, see the Report Studio User Guide.
- Create a blank report as described in Create a blank report from the PowerCube model.
- Add a trend chart to the report showing the total number of "create" events for all Connections applications for the years 2010, 2011, and 2012, as described in Add a chart to a blank report.
- View the PowerCube query that generates the data for the basic trend chart:
When you created the trend chart, the query was generated automatically based on the measure, categories, and data series that you placed in the chart.
- Click View > Queries to display the queries used in the report.
- Double-click Query1 to open the query definition window.
- In the Properties window, expand Data and locate the Query attribute.
- Define the tuple to display in the report:
For this example, the tuple represents the intersections of the following data items:
- The FILES category (the Connections application being report on)
- The FILE item (the report will only count files in the selected application and will ignore other others such as comments)
- The CREATE measure (the report will only count "create" events)
- Click the Toolbox
tab.
- In the Toolbox window, select the Data Items
object and drag it to the Data Items area within the query definition window.
You can use the Intersection (Tuple)
object to define a tuple but the Data Item object because is more flexible and because it supports more functions and calculations.
- In the Data Item Expression window, type tuple(...) in the Expression field.
- Click the Sources
tab.
- Expand SOURCE and click FILES; drag it to the Expression field and drop it between the ( ) in the expression.
The expression now reads tuple([FILES]) and represents the Files application.
- Return to the Sources tab, expand ITEMS and click FILE; drag it to the Expression field and drop it between the ( ) in the expression.
The expression now reads tuple([FILES],[FILE]) and represents the intersection of the Files application and the file item.
- Return to the Sources tab, expand EVENT > EVENT > Members > EVENT nd click CREATE; drag it to the Expression field and drop it between the ( ) in the expression.
The expression now reads tuple([FILES],[FILE],[CREATE]) and represents the intersection of the Files application, the file item, and the create event. This expression merely retrieves the value that resides at the intersection of the three data items; it does not actually perform any calculations on that value. For a list of the functions available for use in the data item expression, click the Functions
tab.
- Click OK to save the expression and close the Data Item Expression window.
- Rename the new data item so you can easily find and work with it later:
- Click the data item (the tuple) that you just created.
- In the Properties window, locate the Data Item section.
Data items are named in the order in which they were created. This report has a single data item, named DataItem1 by default.
- In the data item, locate the Name attribute; edit the name and replace it with a meaningful name; for example: NumOfNewFiles.
The new data item name is reflected in the Data Items area within the query definition window.
- Modify the trend chart to use the new NumOfNewFiles data item:
- Click View > Report Pages.
- Double-click Page1 to return to the base report.
- In the chart, delete the CREATE date item from the Series area.
- Click the Data Items
tab.
This tab appears now that you have a data item defined.
- In the list of data items, click NumOfNewFiles and drag it to the Series area of the chart to replace the CREATE data item that you deleted.
- Click Save to save the updated report.
- Click Run > Run Report - HTML to test the report by viewing it in the Cognos Viewer; then close the viewer when ready to proceed.
Add custom reports to the Metrics reports list
After you create a custom report, edit the reports-config.xml and add an entry for the new report. The entries in this file determine which reports appear in the list that displays in the Metrics user interface.
The list of reports that displays in the Metrics user interface is based on the report entries in the reports-config.xml; the label associated with each report ID displays in the list of available reports. When you create a new report, you can add it to the file with a new entry tag.
- On the computer where Cognos BI Server is installed, open the reports-config.xml file for editing.
The file is typically located in the following directory:
..\WebSphere\AppServer\profiles\Profile_Name\config\cells\Cell_Name\LotusConnections-config\metrics
- In the reports-config.xml file, add a new entry tag into the <!-- Definition of customized reports --> section of either the global reports section or the community reports section, remembering to end it with the closing </entry> tag.
For example, to add a custom report to the global set of reports, insert the new entry within the global tags but outside of the existing entries that appear for the standard reports, as shown in the example that follows:
<global defaultReportId="overview"> <!-- Definition of built-in reports. Built-in reports don't have link property. --> <entry id="overview" type="report" label="METRICS.NAVIGATION.SYSTEM.OVERVIEW.NAME"> <entry id="people" type="report" label="METRICS.NAVIGATION.PEOPLE.NAME" /> <entry id="participation" type="report" label="METRICS.NAVIGATION.PARTICIPATION.NAME" /> <entry id="content" type="report" label="METRICS.NAVIGATION.CONTENT.NAME" /> </entry> <!-- Definition of customized reports --> <entry id="customized_report_1" type="report" label="CUSTOMIZED_REPORT_LABEL_1_NEW"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.object=%2fcontent%2fpackage<%40name%3d%27Metrics%27]%2ffolder<%40name%3d%27metricsCustomReports%27]%2freport<%40name%3d%27visitForApps%27]&ui.name=visitForApps&run.outputFormat=&run.prompt=true]]> </link> </entry> </global>You can insert the new entry anywhere within the appropriate section; the reports are listed in the user interface in the order in which they appear in this file. Each report needs an entry tag that describes it, with a link node indicating
...where the report is stored. You can copy the code from an existing report as a starting point and then modify it for the new entry.Provide the following information for the new report:
- id . Provide a brief description that will not change even if you modify the report.s label later. This ID must match the value used in the report itself so that the Metrics application can locate it.
<entry id="customized_report_1" type="report" label="CUSTOMIZED_REPORT_LABEL_1_NEW">
- type . Set the type of entry that you are creating; use report as the value.
<entry id="customized_report_1" type="report" label="CUSTOMIZED_REPORT_LABEL_1_NEW">
- label . Provide a text label that will appear as the report.s name in the user interface.
<entry id="customized_report_1" type="report" label="CUSTOMIZED_REPORT_LABEL_1_NEW" >
- link . The value of the link depends on whether you are adding an entry for a global metrics eport or for a community metrics report:
- Global metrics report: Provide a link to the report. Format the URL as a CDATA element and omit the domain and port as shown in the example that follows.
<entry id="customized_report_1" type="report" label="CUSTOMIZED_REPORT_LABEL_1_NEW"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry>
- Community metrics report: Provide the report name only, as in the example that follow. The report name must match the report name that you added to the community job list for this report as described in Create a report from a predefined a layout and Create a blank report from the PowerCube model.
<entry id="customized_report_2" type="report" label="CUSTOMIZED_REPORT_LABEL_2_NEW"> <link>your_report_name</link> </entry>
- Save and close the file.
- Refresh the browser before viewing the report to verify the new link.
There is no need to restart the Cognos BI Server.
Nesting reports in the Metrics user interface
You can nest reports in the Metrics reports listing by nesting the corresponding entries in the reports-config.xml file. For example, if you create several custom reports related to a particular theme, you can nest them in the reports listing so that users can easily see that the indented reports are related.
When you nest reports, the additional reports are indented under another, more general report to which they are related. If you want to group related reports without creating a general report to collect them, you should create a report category instead of nesting the reports.
When a user views the Metrics user interface, each report.s name is displayed as a link; the user clicks a link to view the corresponding report. If you create a set of related reports, you may want to nest their names in the Metrics user interface so that users can easily see which reports are related. Nested reports display as indented under the main report. You can nest reports by editing the reports-config.xml file and adding an entry tag for each nested report within the entry tag for the main report.
- On the computer where Cognos BI Server is installed, open the reports-config.xml file for editing.
The file is typically located in the following directory:
IBM\WebSphere\AppServer\profiles\Profile_Name\config\cells\Cell_Name\LotusConnections-config\metricsfor example:IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics
- In the reports-config.xml file, locate the section that represents the main report where you want to nest the additional reports.
The description for each report begins with an entry tag that specifies the report ID and label.
< entry id="snow_sports_products" type="report" label="PRODUCTS.SNOW.SPORTS">
- Add an entry tag for each nested report between the beginning of the main report.s <entry tag and its closing </entry> tag.
The example that follows nests two specific product reports under the snow_sports_products report; in the Metrics user interface the links for the sleds and skis reports will display as indented under the more general snow sports products report.
<entry id="snow_sports_products" type="report" label="PRODUCTS.SNOW.SPORTS"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> <!-- SLEDS report --> <entry id="snow_sports_products_sleds" type="report" label="PRODUCTS.SNOW.SPORTS.SLEDS"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry> <!-- SKIS report --> <entry id="snow_sports_products_skis" type="report" label="PRODUCTS.SNOW.SPORTS.SKIS"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry> </entry>
- Save and close the file.
- Refresh the browser before viewing the Metrics user interface to verify the nested reports.
There is no need to restart the Cognos BI Server.
Create categories for reports
You can group related reports in the Metrics reports listing by adding the report entries under a special category entry in the reports-config.xml file. For example, if you create several custom reports related to a particular theme, you can group them in the reports listing so that users can easily see that the reports are related.
When you categorize reports, the reports display below a text label that does not link to any additional report. If you want to group related reports under a more general report without creating an extra text label, you should nest the reports instead of creating a report category.
When a user views the Metrics user interface, each report.s name is displayed as a link; the user clicks a link to view the corresponding report. If you create a set of related reports, you may want to group their names in the Metrics user interface so that users can easily see which reports are related. You can group reports by editing the reports-config.xml file and creating a special category entry, and then adding an entry tag for each related report within the category.s entry tag. Note that a category is simply a text label that appears in the user interface, so it does not have a link associated with it.
- On the computer where Cognos BI Server is installed, open the reports-config.xml file for editing.
The file is typically located in the following directory:
IBM\WebSphere\AppServer\profiles\Profile_Name\config\cells\Cell_Name\LotusConnections-config\metricsfor example:IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics
- In the reports-config.xml file, locate the section where you want to add the new report category.
The description for each report begins with an <entry tag that specifies the report ID and label, and ends with a closing </entry> tag. Be sure to add your new entry between existing entries and not within one.
<entry id="snow_sports_products" type="report" label="PRODUCTS.SNOW.SPORTS"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry>
- Create an entry tag for the new category, remembering to end it with the closing </entry> tag.
Provide the following information for the new category:
- id . Provide a brief description that will not change even if you modify the report.s label later. This ID must match the value used in the report itself so that the Metrics application can locate it.
<entry id="seasonal_products" type="category" label="PRODUCTS.SEASONAL">
- type . Set the type of entry that you are creating; use category as the value.
<entry id="seasonal_products" type="category" label="PRODUCTS.SEASONAL">
- label . Provide a text label that will appear as the report.s name in the user interface.
<entry id="seasonal_products" type="category" label="PRODUCTS.SEASONAL" >For example:
<entry id="seasonal_products" type="category" label="PRODUCTS.SEASONAL"> </entry>
- Add an entry tag for report that belongs in the new category, inserting the entry between the beginning of the category.s <entry tag and its closing </entry> tag.
The example that follows groups two specific product reports under the seasonal_products category; in the Metrics user interface the links for the spring and autumn product reports will display below the "Seasonal products" title. Notice that there is no link associated with the seasonal products category.
<entry id="seasonal_products" type="category" label="PRODUCTS.SEASONAL"> <!-- SPRING report --> <entry id="seasonal_products_spring" type="report" label="PRODUCTS.SEASONAL.SPRING"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry> <!-- AUTUMN report --> <entry id="seasonal_products_autumn" type="report" label="PRODUCTS.SEASONAL.AUTUMN"> <link> <!<CDATA</servlet/dispatch/ext?b_action=cognosViewer&ui.action=run&ui.name=main&run.outputFormat=&run.prompt=false&cv.header=false&cv.toolbar=false&ui.object=%2fcontent%2fpackage%5b%40name%3d%27metrics%27%5d%2ffolder%5b%40name%3d%27global%27%5d%2ffolder%5b%40name%3d%27customized%27%5d%2freport%5b%40name%3d%27main%27%5d]]> </link> </entry> </entry>
- Save and close the file.
- Refresh the browser before viewing the Metrics user interface to verify the grouped reports.
There is no need to restart the Cognos BI Server.
PowerCube dimensions
The data collected by IBM Collections is stored in a PowerCube that is administered by IBM Cognos Business Intelligence. The PowerCube stores data in dimensions, which provide descriptive information as well as quantitative measures of the data. When designing reports for displaying Metrics data in IBM Connections, you can include data from both the Regular (categories) and the Measure dimensions.
Regular dimensions
Regular dimensions represent descriptive data that provides context for the data that is modeled in the Measure dimensions. Each dimension contains categories; for example, the SOURCE dimension provides the name of the Connections application that triggered an event.
- DATE
- This is a time dimension, which indicates the time that an event was generated. This dimension break down time into year, month, week, and day levels.
- SOURCE
- This dimension indicates the application that generated the event.
- SCOPE
- This dimension indicates the scope of the content that is referred to by the event.
- ITEM
- This dimension indicates the type of the content that referred by the event.
- EVENT
- This dimension indicates the action of the event.
- COMMUNITY
- This dimension indicates the community that the event happens.
- UNIQUE EVENT
- This dimension indicates the action of the event in the calculation of unique people and content.
- ATTRIBUTE1
- The categories of this dimension comes from the specified attribute of profile, and this can be customized by system administrator.
- ATTRIBUTE2
- The categories of this dimension also comes from the specified attribute of profile, and this can be customized by system administrator.
- ATTRIBUTE3
- The categories of this dimension also comes from the specified attribute of profile, and this can be customized by system administrator.
Measure dimensions
Measure dimensions represent the quantitative data described by regular dimensions; for example, the MONTHLY_UNIQUE_CONTENT provides a count of unique content events for a month, and can be associated with a Regular dimension such as COMMUNITY to provide the number of unique content items generated for a particular community in a specified month.
- EVENT_COUNT
- This measure dimension is used for the calculation of event counting.
- DAILY_UNIQUE_USER
- This measure dimension is used for the calculation of unique user number in day level.
- WEEKLY_UNIQUE_USER
- This measure dimension is used for the calculation of unique user number in week level.
- MONTHLY_UNIQUE_USER
- This measure dimension is used for the calculation of unique user number in month level.
- DAILY_UNIQUE_CONTENT
- This measure dimension is used for the calculation of unique content number in day level.
- MONTHLY_UNIQUE_CONTENT
- This measure dimension is used for the calculation of unique content number in month level.
- WEEKLY_UNIQUE_CONTENT
- This measure dimension is used for the calculation of unique content number in week level.
- INITIAL_COUNT
- This measure dimension is used for the calculation of initial count.
- ZERO
- This measure dimension represents 0 in the calculation.
Security
IBM Connections provides a flexible security infrastructure that supports an open, easily shareable data model.
Find out what security applications are provided by default in IBM Connections and how to implement further security measures to protect sensitive information.
Allow third-party applications access to data via the OAuth2 protocol
Allow third-party applications to ask your IBM Connections users for access to their data.
IBM Connections now supports the OAuth 2.0 standard authorization protocol. Third-party applications ("consumer" applications) can use a combination of OAuth and the IBM Connections API to access IBM Connections data.
Before a consumer application can access a user's IBM Connections data, an IBM Connections administrator must register the application. Then the user must give the application permission. Once a consumer application is registered and has permission it can employ the user's data, and push its own data to a user's status updates. "IBM Connections data" here means all of the user's data, including photographs, personal profile information, and any content they have added anywhere. For example, a social networking application could display a user's profile picture and personal information. It could also push status updates the user makes in the consumer application to the IBM Connections activity stream and status updates.
As an IBM Connections administrator you create and manage a list of registered consumer applications. List membership might depend upon agreements with the consumer application companies. You can use commands to add, edit, view information on, count, and delete consumer applications from the list.
When users open the consumer application they are prompted to give or deny the application permission to access the user's IBM Connections data. Permission is granted by a token which expires in six months if not renewed by the user. When a permission expires users must visit the consumer application again and go through the authorization process. Users also can remove an application's permission at any time in Connections by clicking Sets > Application Access. This authorization management interface is customizable.
For general information on OAuth, see the OAuth web site at http://oauth.net/.
If you wish to add gadgets deployed externally, such as iGoogle gadgets, configure locked domains. Locking domains isolates semi-trusted gadgets and prevents them from accessing SSO tokens or via DOM access to the parent page of the gadget iFrame that can be used to forward sensitive data to external sites. For more information on locked domains, refer to Enable locked domains.
Manage the client application list
Use commands to manage the list of client applications that are allowed to prompt users for access to their IBM Connections data, using the OAuth authentication protocol.
See the topic Running administrative commands for steps on executing oauthAdmin.py before running OAuth commands in IBM Connections.
Perform any of the following tasks using the appropriate command:
- Add client applications to the consumer list
- Edit client application information
- Viewing all client applications
- Viewing one client application
- Counting client applications
- Delete client applications
Add client applications to the consumer list
- OAuthApplicationRegistrationService.addApplication(String appId, String appName, String redirectURI)
- Adds a new client application to the list, and prints a success message containing the client ID.
- appId
- The identifier of the client application.
- appName
- The display name of the client application.
- redirectURI
- A URL used to return authorization credentials responses to the client the resource owner user-agent.
Example:
wsadmin>OAuthApplicationRegistrationService.addApplication("sample_application", "Sample Application", "http://www.renovations.com/oauth/redirect") An application was added with the new id c2834676-c8b6-4748-9fdc-7c639979f326.
Edit client application information
- OAuthApplicationRegistrationService.editApplication(String appId, String appName, String redirectURI)
- Edits a client application in the list, and prints the client ID.
- appId
- The identifier of the client application.
- appName
- The display name of the client application.
- redirectURI
- A URL used to return authorization credentials responses to the client the resource owner user-agent.
Example:
wsadmin>OAuthApplicationRegistrationService.editApplication("c2834676-c8b6-4748-9fdc-7c639979f326", "Edited Application", "An edited client application", "http://www.renovations.com/oauth/edited/redirect") The application with the id c2834676-c8b6-4748-9fdc-7c639979f326 was updated successfully.
Viewing all client applications
- OAuthApplicationRegistrationService.browseApplications()
- Prints a list containing the information on all client applications, displaying the client ID, display name, and redirect URI of each item. There are no parameters.
Example:
wsadmin>OAuthApplicationRegistrationService.browseApplications() [{display_name=Sample Application, client_id=c2834676-c8b6-4748-9fdc-7c639979f326, client_secret=xxxxxxxxxxxxxxxxxxxxxxxx, redirect_uri=http://www.renovations.com/oauth/redirect}, {display_name=Yet Another Application, client_id=456, client_secret=xxxxxxxxxxxxxxxxxxxxxxxx, redirect_uri=http://www.yetanother.com/the/oauth/redirect}]
Viewing one client application
- OAuthApplicationRegistrationService.getApplicationById(String appId)
- Prints the information on a single application, displaying the client ID, display name, and redirect URI.
- appId
- The identifier of the client application.
Example:
wsadmin>OAuthApplicationRegistrationService.getApplicationById("c2834676-c8b6-4748-9fdc-7c639979f326") {display_name=Sample Application, client_id=c2834676-c8b6-4748-9fdc-7c639979f326, client_secret=xxxxxxxxxxxxxxxxxxxxxxxx, redirect_uri=http://www.renovations.com/oauth/redirect}
Counting client applications
- OAuthApplicationRegistrationService.getApplicationCount()
- Returns a count of known client applications. There are no parameters.
Example:
wsadmin>OAuthApplicationRegistrationService.getApplicationCount() 2
Delete a client application
- OAuthApplicationRegistrationService.deleteApplication(String appId)
- Deletes a single application from the list, and prints a success message containing the client ID.
- appId
- The identifier of the client application.
Example:
wsadmin>OAuthApplicationRegistrationService.deleteApplication("c2834676-c8b6-4748-9fdc-7c639979f326") The application with the id c2834676-c8b6-4748-9fdc-7c639979f326 was deleted successfully.
Related tasks
Run administrative commands
Install and enabling OAuth TAI
You need to install and enable the OAuth TAI in IBM Connections.
- Before installing IBM Connections 4.0 be sure to install the IBM WebSphere Application Server and apply the WebSphere Application Server iFix (APAR) PM65486 for releases 7.0.0.21 or 7.0.0.23 to your WAS implementation.
- Optional: Export customizable OAuth provider properties using the import/export commands AdminTask.exportOAuthProps providerName fileName and AdminTask.importOAuthProps providerName fileName. Additional properties can be configured but properties should not be customized unless required: authOnly is used to indicate whether a client request should fail if no Oauth token or authentication could be performed with other available authentication methods.
Table 71. OAuth provider properties
Property Default value Description oauthjdbc.CleanupInterval 3600 (1h) Interval in seconds after which expired tokens are cleared from the database. This time elapses from the startup of the provider application. oauth20.max.authorization.grant.lifetime.seconds 15768000 (6mo) Max lifetime of authorization grant. Provides an upper limit to lifetime of all tokens. oauth20.code.lifetime.seconds 60 (1m) Lifetime of authorization code. For security reasons, this value must not exceed a few minutes. oauth20.code.length 30 Length of authorization code (max is 2048). oauth20.token.lifetime.seconds 43200 (12h) Lifetime of access token. When an access token expires, a client must request a new access token by exchanging the refresh token. oauth20.access.token.length 40 Length of access token (max is 2048). oauth20.issue.refresh.token true If set to true, clients will receive a refresh token. If set to false, clients must request authorization when the access token expires. oauth20.refresh.token.length 50 Length of refresh token (max is 2048). oauth20.allow.public.clients false *FUTURE USE* If set to true, public clients are allowed. Omit from documentation? oauth20.authorization.form.template {oauthSvcUrl}/authorize *DO NOT EDIT* Authorization template URL oauth20.authorization.error.template {oauthSvcUrl}/error *DO NOT EDIT* Error page template URL oauth20.authorization.loginURL {oauthSvcUrl}/authenticate *DO NOT EDIT* Authentication URL
- Optional: You can modify the TAI filter for Connections applications by enabling WebSphere global security, including Application security, as follows:
TAI filter rules should be modified only when the context root for components is changed. The default rule is set by the Connections Installer.
- Use the WebSphere Application Server administrative console, navigate to Security > Global Security > Web and SIP Security > Trust Association > Interceptors > com.ibm.ws.security.oauth20.tai.OAuthTAI . The TAI filter property provider_n.filter is used to choose an Oauth service provider when a client invokes a protected web resource. The filter property specifies a set of conditions that are compared against the client's HTTP request. Each condition is specified by three elements:
Conditions are evaluated from left to right, as specified by the comparison value. If all the filter conditions specified by an OAuth provider are met in an HTTP request, the OAuth provider is selected for the HTTP request. The input element identifies an HTTP request header field to extract from the request and its value is compared with the value specified in the filter property according to the operator specification. If the header field identified by the input element is not present in the HTTP request, the condition is treated as not being met. Any standard HTTP request header fields can be used as the input element in the filter condition. Refer to the HTTP specification for the list of valid headers. In addition to the standard HTTP header fields, the following special input elements can be used in the filter property:
- input required: The input element typically specifies an HTTP header name, but request-url, remote-address, and refereer can also be used as special elements.
- operator: The operator element specifies one of the following values: ==, !=, %=, ^=, <, >.
Table 72. Filter property operators
Operator Condition Example = = This operator specifies an exact match. The input element must be equal to the comparison value. From==jones@my.company.com or
provider_1.filter=From==samluser@xyz.com
provider_3.filter=applicationNames==DefaultApplication
%= This operator specifies a partial match. The input contains the comparison value. user-agent%=IE 6 or
provider_2.filter=request-url%=ivtlanding.jsp
^= The input contains one of the comparison values. request-url^=urlApp1|urlApp2|urlApp3 != The input does not contain the comparison value. request-url!=Snoop > The input is greater than the comparison value. remote-address>192.168.255.130 < The input is less than the comparison value. remote-address<192.168.255.135
- comparison value: This element typically specifies a string, but IP address ranges are also allowed.
- request-url: The comparison value of this input is compared against the URL address that is used by the client application to make the request.
- remote-address: The comparison value of this input is compared against the TCP/IP address of the client application that sent the HTTP request.
- referer: The comparison value of this input is compared against the referer in the request.
- Add custom properties for the TAI filter for the connectionsProvider. Using | to separate URLs, the following example uses the ^= operator to request urls for one of listed Connections applications:
the request-url^=activities/oauth|blogs/oauth|dogear/oauth|communities/calendar/oauth|communities/service/atom/oauth|communities/recomm/oauth|connections/opensocial/oauth|files/oauth|forums/oauth|homepage/oauth|metrics/oauth|moderation/oauth|news/oauth|news/follow/oauth|profiles/oauth|wikis/oauth|search/oauth|/connections/core/oauth/
- After updating the TAI properties provider_1.name and provider_1.filter, restart the WebSphere Application Server.
- Optional: (SPNEGO) Add OAuth Protected API Endpoints to the ignore list. This SPNEGO criterion must be appended as one of the exclusive SPNEGO filters for a SPNEGO -related environment: request-url!=/oauth.
Table 73. OAuth API endpoints for IBM Connections components.
The SPNEGO criterion request-url!=/oauth should be appended as one of the exclusive SPNEGO filters for SPNEGO-related environments.
Refer to Configuring SPNEGO on WebSphere Application Server.
Component OAuth API Endpoint Activities /activities/oauth Blogs /blogs/oauth Bookmarks /dogear/oauth Calendar /communities/calendar/oauth
Communities /communities/oauth /communities/service/atom/oauth
Related Communities /communities/recomm/oauth /communities/service/opensocial/oauth
CRE /connections/opensocial/oauth /connections/core/oauth/
Files /files/oauth Forums /forums/oauth Homepage /homepage/oauth Microblogging N/A (Located in News and Common ear) Metrics /metrics/service/oauth Moderation /moderation/oauth News /news/oauth /news/follow/oauth
Profiles /profiles/oauth Wikis /wikis/oauth Search /search/oauth
Register an OAuth client with a provider
You need to register any OAuth clients with an OAuth provider. To allow a seamless user experience while using the Activity Streams, IBM Connections 4 supports automatic authorization of trusted gadget clients. Users will not be prompted to authorize a trusted gadget the first time that it tries to access their Connections data. The only trusted gadget client out of the box in IC4 is the Connections Embedded Experience gadget.
- To register an arbitrary client:
- Start wsadmin.
./wsadmin.sh -lang jython -user wasadmin -password passw0rd
- Load oauth admin commands
execfile('oauthAdmin.py')
- Register the client as follows:
OAuthApplicationRegistrationService.addApplication(String appId, String appName, String redirectURI)Where:
- appId is an identifier for the application you are registering. It can be anything you like such as my-test-client.
- appName is is a descriptive name for your client such as My Test Client.
- redirectURI is where to redirect to when the gadget has been granted authorization. When Connections is the client, the URL must be set to this templated value. The placeholder opensocialSvcUrl in the following URL will be replaced at runtime with the value of the URL of the opensocial service defined in LotusConnections-config.xml.
wsadmin>OAuthApplicationRegistrationService.addApplication("my-test-client", "My Test Client", "{opensocialSvcUrl}/gadgets/oauth2callback") An application was added with the new id my-test-client.
- Obtain the client secret from the recently registered application ( copy it and save it in a text file). This will be used to register the gadget on the consumer proxy.
clientSecret = OAuthApplicationRegistrationService.getApplicationById(appId).get('client_secret')
- To enable auto-authorization for this gadget, the provider has to be configured to make it a privileged client. Modify the connectionsProvider-43.xml used to configure the provider to add the appId previously used to the trusted auto-auth client list, for example:
<parameter name="oauth20.autoauthorize.clients" type="ws" customizable="true"> <value>my-test-client</value> </parameter>
- Recreate the provider using this wsadmin command, substituting the appropriate path for connectionsProvider.xml and wasadmin credentials:
./wsadmin.sh -lang jython -conntype SOAP -c "print AdminTask.createOAuthProvider('[-providerName connectionsProvider -fileName /opt/IBM/WebSphere/AppServer1/profiles/AppSrv01/bin/connectionsProvider.xml]')" -user wasadmin -password PASS
- Consider whether the default configuration settings for OAuth provider token lifetime are appropriate for your implementation. The defaults are as follows:
- access token=12 hours
- refresh token=6 months
- cleanup interval=1 hour
Authorization Management Commands
Once client applications are registered with the OAuth provider in IBM Connections, they are allowed to request authorization from Connections users to access and interact with their data. Connections administrators can run wsadmin commands to manage authorizations issued to registered client applications, in order to revoke authorizations granted to malicious applications, or to remove a compromised access token.
Launching the wsadmin shell
Administrators can launch the wsadmin shell by running oauthAdmin.py as follows:wsadmin>execfile('oauthAdmin.py')Once the OAuth Administration successfully starts, the admin object OAuthAuthorizationService becomes available:Connecting to WebSphere:name=OAuthApplicationRegistrationService,type=LotusConnections,cell=guadalupeNode02Cell,node=guadalupeNode02,* OAuth Administration initialized.The following commands are available:
- Get an authorization
- Browse authorizations by granting user
- Revoke an authorization
- Revoke authorizations by granting user
- Revoke authorizations by granted application
Get an authorization
- OAuthAuthorizationService.getAuthorizationsById(String authorizationId)
- Administrators can retrieve an authorization by id by running this command. The command takes the argument authorizationId The identifier of the authorization, for example:
wsadmin>OAuthAuthorizationService.getAuthorizationsById('Cc4sBWo0p9PgDTjiFv0ddEMoCSkHViWFXMNlEpRr')This command prints details about the authorization.
{token=Cc4sBWo0p9PgDTjiFv0ddEMoCSkHViWFXMNlEpRr, redirect_uri=https://renovations.ca.ibm.com:9445/oauthclient/redirect.jsp, id=Cc4sBWo0p9PgDTjiFv0ddEMoCSkHViWFXMNlEpRr, username=aalain, client_id=notes-ee}
Browse authorizations by granting user
- OAuthAuthorizationService.browseAuthorizationsByUser(String username)
- Takes the argument username. The username, i.e. the J2EE principal associated with the desired granting user.
wsadmin>OAuthAuthorizationService.browseAuthorizationsByUser('aalain')
- This command prints a list of authorization granted by the user.
[{token=kDDjH5UaXKkXlEIiuXItfDHXDAyFPSSdiN63CU4w, redirect_uri=https://vicpcvm663.mul.ca.renovations.com:9445/oauthclient/redirect.jsp, id=kDDjH5UaXKkXlEIiuXItfDHXDAyFPSSdiN63CU4w, username=aalain, client_id=notes-ee}, {token=1injJ5JmpRWTxi9kPLe4vbdyjGoyIINAuWXxoykM45rZSMKivX, redirect_uri=https://vicpcvm663.mul.ca.renovations.com:9445/oauthclient/redirect.jsp, id=1injJ5JmpRWTxi9kPLe4vbdyjGoyIINAuWXxoykM45rZSMKivX, username=aalain, client_id=notes-ee}, {token=Cc4sBWo0p9PgDTjiFv0ddEMoCSkHViWFXMNlEpRr, redirect_uri=https://vicpcvm663.mul.ca.renovations.com:9445/oauthclient/redirect.jsp, id=Cc4sBWo0p9PgDTjiFv0ddEMoCSkHViWFXMNlEpRr, username=aalain, client_id=notes-ee}, {token=Pb2SsdmXkp99Sfo7Lau7N1JZVawPRUAMUSreTMcsOZazRBsw4U, redirect_uri=https://vicpcvm663.mul.ca.renovations.com:9445/oauthclient/redirect.jsp, id=Pb2SsdmXkp99Sfo7Lau7N1JZVawPRUAMUSreTMcsOZazRBsw4U, username=aalain, client_id=notes-ee}]
Revoke an authorization
- OAuthAuthorizationService.revokeAuthorization(String authorizationId)
- An administrators can revoke a compromised authorization by id executing this command. It takes the argument:
- authorizationId - The identifier of the authorization
wsadmin>OAuthAuthorizationService.revokeAuthorizations('kDDjH5UaXKkXlEIiuXItfDHXDAyFPSSdiN63CU4w') The authorization with the id kDDjH5UaXKkXlEIiuXItfDHXDAyFPSSdiN63CU4w was revoked successfully.
Revoke authorizations by granting user
- OAuthAuthorizationService.revokeAuthorizationsByUser(String username)
- An administrator can revoke all authorizations granted by a user by running this command. It takes the argument:
- username - The J2EE principal associated with the desired granting user.
- For example, running this command revoked authorizations that the user aalain had granted.
wsadmin>OAuthAuthorizationService.revokeAuthorizationsByUser('aalain') All authorizations granted by user aalain were successfully revoked.
Revoke authorizations by granted application
- OAuthAuthorizationService.revokeAuthorizationsByApplication(String username, String appId)
- An administrator can revoke all authorizations granted to an application by a user by running this command.
- Arguments this command takes are as follows:
- username - The J2EE principal associated with the desired granting user.
- appId - The id of the granted application.
- For example, running this command revoked authorizations granted to an application by the granting user aalain:
wsadmin>OAuthAuthorizationService.revokeAuthorizationsByApplication('aalain', 'conn-ee') All authorizations granted by user aalain to application conn-ee were successfully revoked.
CRE Mashups Proxy Configuration
The Common Rendering Engine (CRE) proxy is a simple set of extensions over the Mashups 3.0 proxy that is specifically designed to solve gadget use cases. IBM Connections uses a modified proxy plugin configuration that can parse the older Connections Mum Proxy 1.0 format including the Connections extensions.
Purpose
For communication, the CRE proxy leverages two files:
- The external proxy configuration is used to communicate between gadgets and external servers. This is the proxy-config.tpl file located in the LotusConnections-config directory. The file can be customized to meet your needs. For more information about the external proxy, refer to Configuring the AJAX proxy.
- The internal proxy configuration is leveraged for internal server-to-server communication by Shindig/CRE. This file is hidden by default but can overridden by placing a proxy-opensocial-internal-config.xml file into the LotusConnections-config directory. Rarely, if ever, would you have to modify this file, but if setting changes are found to be needed during performance testing, these changes should be included into the default file.
The external Proxy configuration: proxy-config.tpl
For the external proxy configuration, CRE has been extended to read the proxy-config.tpl file. This file works with the extension of gadget-specific proxy constructs. These gadget specific constructs are ignored by the standard Connections proxy, but utilized by the CRE proxy. The companion file proxy-config.dynamic controls which of those endpoints the gadget is permitted to make outbound requests to, while the proxy-config.tpl file controls the characteristics (headers/cookies/and so on) of your gadget's communication to that endpoint.
Gadget-specific proxy constructs
- managed-headers
- Purpose: Provides a set of headers that will be specially rewritten and passed to the gadget. The proxy helps to ensure that these headers are as follows:
Placement is as a peer of //policy/headers
Content contains <managed-header> element. This element contains a text node that specifies the 'header' that is to be managed.
For example:
<proxy:actions> ... </proxy:actions> <proxy:headers /> <proxy:managed-headers> <proxy:managed-header>X-LConn-Auth</proxy:managed-header> <proxy:managed-headers> ... <proxy:policy>
- managed-cookies
- Purpose: Provides a set of headers that will be specially rewritten and passed to the specific gadget. The cookie rewriting ensures that multiple gadgets loaded in the same domain do not overwrite cookie values for each other. The proxy then handles rewriting the cookie back to its original form.
- Placement is as a peer of //policy/cookies
- Content contains <managed-cookie> element. This element contains a text node that specifies the 'cookie' that is to be managed.
- For example:
<proxy:policy ..> <proxy:actions> ... </proxy:actions> <proxy:headers /> <proxy:managed-headers /> <proxy:mime-types /> <proxy:cookies /> <proxy:managed-cookies> <proxy:managed-cookie>DomAuthSessId</proxy:managed-cookie> </proxy:managed-cookies> ... <proxy:policy>
The Internal Proxy Config: proxy-opensocial-internal-config.tpl file
Typically you should not have to modify this file. For performance testing however, the ability to modify the file can be extremely useful if modifications need to be made. In order to override the default configuration, paste the following sample into a file called proxy-opensocial-internal-config.tpl in the LotusConnections-config directory. The following is a sample proxy-opensocial-internal-config.tpl file:<?xml version="1.0" encoding="UTF-8"?> <proxy:config id="proxy-opensocial-internal-config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.0"> <proxy:proxy-rules> <proxy:mapping contextpath="/*" /> <proxy:policy url="*" acf="none" basic-auth-support="true" auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> <proxy:method>POST</proxy:method> <proxy:method>PUT</proxy:method> <proxy:method>DELETE</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>*</proxy:header> <proxy:header>Authorization</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>DomAuthSessId</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> <proxy:cookie>Shimmer</proxy:cookie> <proxy:cookie>ShimmerS</proxy:cookie> <proxy:cookie>JSESSIONID</proxy:cookie> </proxy:cookies> </proxy:policy> <proxy:meta-data> <proxy:name>socket-timeout</proxy:name> <proxy:value>30000</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>connection-timeout</proxy:name> <proxy:value>30000</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>retries</proxy:name> <proxy:value>2</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>max-connections-per-host</proxy:name> <proxy:value>100</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>max-total-connections</proxy:name> <proxy:value>200</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>unsigned_ssl_certificate_support</proxy:name> <proxy:value>true</proxy:value> </proxy:meta-data> </proxy:proxy-rules> </proxy:config
Configure OAuth for gadgets
The IBM Connections 4.0 release supports an OAuth 2.0 consumer proxy that allows the Homepage component to surface gadgets in an OpenSocial container that can interact with an OAuth 2.0 protected service. In order for this proxy to function, there are a series of new administration commands that are exposed in the News service to define OAuth 2.0 providers, clients, and the associated gadget that will interact with the protected service.
See the topic Running administrative commands for steps on executing newsAdmin.py before running OAuth proxy configuration commands in IBM Connections.
Perform any of the following tasks using the appropriate command:
- Counting providers
- Returning a list of providers
- Returning a single provider
- Register or updating a provider
- Delete a provider
- Counting clients
- Returning a single client
- Returning a list of clients
- Register or updating a client
- Delete a client
- Binding a gadget
- Delete a binding
- Returning bindings
- Counting bindings
- Returning a single binding by gadgetUri
- Returning a single binding by widgetId
- Purging all tokens
Counting providers
- NewsOAuth2ConsumerService.countProvider()
- Returns the total number of OAuth 2.0 providers registered with the consumer proxy. There are no parameters.
Example:
wsadmin>NewsOAuth2ConsumerService.countProvider() 20
Returning a list of providers
- NewsOAuth2ConsumerService.browseProvider(int pageSize, int pageNumber)
- Returns a list of Map objects that represent each OAuth 2.0 provider registered with the consumer proxy, in ascending ordered by provider name. The following information is returned for each map object in the returned list:
- authHeader: "true" or "false"
- authUrl: the authentication url endpoint for the provider
- clientAuth: the client authentication method in use
- name: the name of the provider
- tokenUrl: the token url endpoint for the provider
- urlParam: "true" or "false"
- pageSize
- The maximum number of providers to list per page. The default value is 20. This parameter is optional.
- pageNumber
- The number of the page to display. For example, if you specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. The default value is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseProvider(50, 1)
Returning a single provider
- NewsOAuth2ConsumerService.findProvider(string providerName)
- Returns a Map with information about the registered OAuth 2.0 provider with the specified name.
- providerName
- The unique provider name.
Example:
wsadmin>NewsOAuth2ConsumerService.findProvider("provider123")
Register or updating a provider
- NewsOAuth2ConsumerService.registerProvider(string providerName, string clientAuth, string authHeader, string urlParam, string authUrl, string tokenUrl)
- Registers or updates an existing OAuth 2.0 provider by name with the associated parameters.
- providerName
- The unique provider name.
- clientAuth
- The client authentication method for accessing this provider. Supported values out of the box are "standard" and "basic" per the specification.
- authHeader
- Value of "true" if credentials must be encoded in the authorization header, otherwise "false".
- urlParam
- Value of "true" if credentials must be specified as query parameters on the URI, otherwise "false".
- authUrl
- The authentication endpoint for the provider.
- tokenUrl
- The token endpoint for the provider.
Example:
wsadmin>NewsOAuth2ConsumerService.registerProvider("provider123", "standard", "true", "false", "???", "???")
Delete a provider
- NewsOAuth2ConsumerService.deleteProvider(string providerName)
- Deletes a provider by name if it exists, and has no existing associated clients or gadget bindings.
- providerName
- The unique provider name.
Example:
wsadmin>NewsOAuth2ConsumerService.deleteProvider("provider123")
Counting clients
- NewsOAuth2ConsumerService.countClient(string providerName)
- Returns the total number of OAuth 2.0 clients registered with the consumer proxy.
- providerName
- An optional filter to only count clients associated with the specified provider.
Example:
wsadmin>NewsOAuth2ConsumerService.countClient("provider123")
Returning a single client
- NewsOAuth2ConsumerService.findClient(string clientName)
- Returns a Map with information about the registered OAuth 2.0 client with the specified name.
- providerName
- The client name.
Example:
wsadmin>NewsOAuth2ConsumerService.findClient("client123")
Returning a list of clients
- NewsOAuth2ConsumerService.browseClient(string providerName, int pageSize, int pageNumber)
- Returns a list of Map objects that represent each OAuth 2.0 clients registered with the consumer proxy, in ascending ordered by provider name. The following information is returned for each map object in the returned list:
- clientId: the identifier issued by the authorization server when registering your client
- clientSecret: the secret issued by the authorization server when registering your client
- ctype: the client type, "confidential" or "public" are the supported values per the specification
- grantType: "code" per specification, or "client_credentials" per specification
- name: the name of the client
- providerName: the name of the associated provider that was previously registered
- redirectUri: the client redirection uri
- providerName
- An optional filter to only browse clients associated with the specified provider.
- pageSize
- The maximum number of clients to list per page. The default value is 20. This parameter is optional.
- pageNumber
- The number of the page to display. For example, if you specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. The default value is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseClient("provider123", 50, 1)
Register or updating a client
- NewsOAuth2ConsumerService.registerClient(string clientName, string providerName, string ctype, string grantType, string clientId, string clientSecret, string redirectUri)
- Registers or updates an existing OAuth 2.0 client by name with the associated parameters.
- clientName
- The name to associate with the client that must be unique in a deployment.
- providerName
- The name of the registered provider to associate with this client.
- ctype
- The client type. Supported values are "confidential" or "public" per LINKspecification/LINK.
- grantType
- The authorization grant type. Supported values are "code" or "client_credentials" per specification??
- clientID
- The identifier issued by the authorization server when registering your client.
- clientSecret
- The secret issued by the authorization server when registering your client.
- redirectUri
- The client redirection URI.
Example:
wsadmin>NewsOAuth2ConsumerService.registerClient("client123", "provider123", "confidential", "code", "my-client", "my-secret", "https://{opensocial}/gadgets/oauth2callback")
Delete a client
- NewsOAuth2ConsumerService.deleteClient(string clientName)
- Deletes a client by name if it exists, and has no existing associated gadget bindings that leverage this client.
- clientName
- The name of the client to remove.
Example:
wsadmin>NewsOAuth2ConsumerService.deleteClient("client123")
Binding a gadget
- NewsOAuth2ConsumerService.bindGadget(string widgetId, string serviceName, string clientName, string allowModuleOverride)
- Binds a gadget to a client with the specified service name and client name.
- widgetId
- The id of the widget.
- serviceName
- The name to associate with the gadget. The widgetId and service name must create a unique composite key for the deployment.
- clientName
- The name of the client to associate with this gadget.
- allowModuleOverride
- Value is "true" if the gadget overrides the provider default endpoint urls, else "false".
Example:
wsadmin>NewsOAuth2ConsumerService.bindGadget("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service", "client123", "false")
Delete a binding
- NewsOAuth2ConsumerService.unbindGadget(string widgetId, string serviceName)
- Deletes a gadget binding by widgetId and serviceName.
- widgetId
- The id of the widget.
- serviceName
- The name to associate with the gadget. The widgetId and service name must create a unique composite key for the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.unbindGadget("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service")
Returning bindings
- NewsOAuth2ConsumerService.browseGadgetBinding(string widgetId, string clientName, int pageSize, int pageNumber)
- Returns a list of Map objects that represent each OAuth 2.0 gadget bindings registered with the consumer proxy ordered by service name ascending. The following information is returned for each map entry in the returned list:
- clientName: the name of the associated client
- allowModuleOverride: "true" or "false"
- serviceName: the name of the associated service
- uri: the gadget uri
- widgetId
- An optional filter to browse bindings only associated with a specific widget.
- clientName
- An optional filter to browse gadgets only associated with the specified client.
- pageSize
- The maximum number of bindings to list per page. The default value is 20. This parameter is optional.
- pageNumber
- The number of the page to display. For example, if you specify in the pageSize parameter that each page will have 50 items, page 1 will contain items 1-50. The default value is 1. This parameter is optional.
Example:
wsadmin>NewsOAuth2ConsumerService.browseGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "client123", 50, 2)
Counting bindings
- NewsOAuth2ConsumerService.countGadgetBinding(string widgetId, string clientName)
- Returns the total number of OAuth 2.0 bindings registered with the consumer proxy.
- string widgetId, string clientName
- widgetId is an optional filter to count only bindings associated with a specific widget.
Example:
wsadmin>NewsOAuth2ConsumerService.countGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_servicex")
Returning a single binding by gadgetUri
- NewsOAuth2ConsumerService.findGadgetBindingByUri(string gadgetUri, string serviceName)
- Returns a Map with information about the registered OAuth 2.0 gadget bindings with the specified gadgetUri and service name.
- gadgetUri
- The uri for the gadget.
- serviceName
- The name associated with the gadget. A gadgetUri and service name create a unique composite key for a gadget in the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.findGadgetBinding("http://www.acme.com/mygadget", "connections_service")
Returning a single binding by widgetId
- NewsOAuth2ConsumerService.findGadgetBindingByWidgetId(string widgetId, string serviceName)
- Returns a Map with information about the registered OAuth 2.0 gadget bindings with the specified widget id and service name.
- widgetId
- The id of the widget.
- serviceName
- The name associated with the gadget. A widgetId and service name create a unique composite key for a gadget in the deployment.
Example:
wsadmin>NewsOAuth2ConsumerService.findGadgetBinding("aad20aa1-c0fa-48ef-bd05-8abe630c0012", "connections_service")
Purging all tokens
- NewsOAuth2ConsumerService.purgeAllTokens()
- Purges all tokens persisted in the repository. This operation should be executed if the underlying encryption method has been modified.
Example:
wsadmin>NewsOAuth2ConsumerService.purgeAllTokens()
Customize the Application Access and Access Request interfaces
You can customize the header, footer, login, and error pages that prompt IBM Connections users to grant/deny and revoke access to their Connections data for third-party applications protected by OAuth. Also, you can edit the text strings that display on the Application Access and Access Request interfaces. With the OAuth runtime configured, IBM Connections users can allow applications access to their data without sharing credentials and revoke that access at any time. Also, they can report malicious applications to an administrator, who can remove them from the list of applications enabled for OAuth. Users are prompted to either grant or deny access to applications when an attempt is made to access their data.
- To customize the header and the footer of the Application Access page and to the login page presented to users trying to authorize third party applications requesting access to Connections data, place a custom header.jsp, footer.jsp, and login.jsp in the <CUSTOMIZATION_DIR>/oauth/ folder.
- To customize the strings for both the Application Access and Access Request interfaces, you can edit the strings in the com.ibm.lconn.oauth.strings.ui_en.properties property file. For more information about customizing interface strings, refer to Customize property strings.
Enable virus scanning
Edit configuration property settings to force the applications that handle uploaded files to scan all files for viruses.
IBM Connections does not provide virus scanning software, but it does enable you to use existing virus scanning services implemented within your corporate infrastructure. Before you begin this procedure, find out the location of the virus scanning service.
IBM Connections supports the Internet Content Adaptation Protocol (ICAP) and its applications use this protocol to communicate with virus detection products. Ensure that the virus detection product used in your enterprise supports the ICAP 1.0 protocol. IBM Connections is certified to work with Symantec AntiVirus Scan Engine 5.1 and McAfee web Security Appliance (3400) and (3300).
Disable any file cleaning services that are provided by the virus scanning product you are using. Cleaning must be disabled for the virus scanner to interact properly with IBM Connections. See the documentation for the virus scanner to determine how to disable file cleaning.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for details.
The Bookmarks and Home page applications do not implement virus scanning because no files or images are uploaded to those application DBs. To enable virus scanning for Activities, Blogs, Communities, Files, Forums, Profiles, and Wikis:
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- From the temporary directory to which you just checked out the IBM Connections configuration files, open LotusConnections-config.xml in a text editor.
- Uncomment the following block of XML, which can be found in the avFilter section:
<!--avFilter class="AVScannerICAP"> <property>av.scanner.servers=myscanner.host.com</property> <property>exception.on.virus=yes</property> <property>av.scanner.service=scanner.service</property> </avFilter-->
- Replace references to scanner.service with the name of the ICAP response modification service on the ICAP-enabled scanner. Select one of the following options:
Or add the ICAP response modification service for the virus scanning software to support.
- RESPMOD
- Represents McAfee virus scanning software
- AVSCAN
- Represents Symantec virus scanning software
- Replace references to myscanner.host.com with the server name or IP address of the system hosting the virus scanner. To specify more than one server, separate multiple server names or IP addresses with commas. For example:
<avFilter class="AVScannerICAP"> <property>av.scanner.servers=my.virus.scanning.server.com</property> <property>exception.on.virus=yes</property> <property>av.scanner.service=RESPMOD</property> </avFilter>
- To support scanning large files, specify values for the av.chunk.size and first.read.timeout properties: For example:
<avFilter class="AVScannerICAP"> ... <property>av.chunk.size=50000</property> <property>first.read.timeout=120000</property> </avFilter>If the scanner is not available, uploads are rejected to prevent someone from executing a denial of service attack against the scanner, intending to then upload an infected file. In the first.read.timeout property, you can set the number of milliseconds to allow a service to attempt to reach the scanner before rejecting the request.
- Save your changes to LotusConnections-config.xml.
- After making changes, check the configuration files back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
What to do next
Once virus scanning is running in your environment, any scanning-related errors are written to the SystemOut.log file. See Troubleshooting virus scanning for information about possible errors and their causes.
Related tasks
Change common configuration property values Apply common configuration property changes Forcing users to log in before they can access an application
Change the access levels of members or groups to require them to provide credentials before they can access an IBM Connections application.
Do not perform this task if you plan to use the IBM Connections Multi-Service Portlet plug-in. This extension does not function as expected when IBM Connections is configured to force authentication.
The reader role of the Communities application is set to Everyone by default. If you perform this procedure to change the reader role access level for any of the applications that have widgets that are displayed within the Communities application, you must also make the same change to the Communities reader role or the widget will no longer work in Communities.
In an effort to invite people to join the social networking community, many of the IBM Connections applications allow users to read public information, such as public blogs or user profiles without requiring users to log in to the application first. In many cases, it is not until you want to edit your own profile or blog that credentials are required. If you do not want people or a subset of people to be able to freely browse through public information, you can force them to log in to each application before they can view any content. If you force authentication for an application, you should consider enabling it for all applications. To force users to log in before they can access an application:
- Open the Integrated Solutions Console of the WebSphere Application Server hosting the application for which you want to restrict access.
- Expand Applications > Application Types, and then select WebSphere enterprise applications.
- Select the application.
If you select the Profiles application and the Profiles directory service extension is enabled, you must also enable single sign-on for LDAP. See Enabling single sign-on for standalone LDAP for more details.
- Click Security role to user/group mapping.
- Select the check box in the Select column next to the reader role.
- Click Map Special Subjects > All Authenticated in Application's Realm.
- Repeat the previous steps for each application that you want to force users to authenticate with before using.
- Activities, Home page, and Search require users to authenticate by default; the other applications do not. As a result, you do not need to perform this procedure on the Activities, Home page, or Search applications. However, if you do decide to change the reader role in Search to be mapped to "All Authenticated in Application's Realm," then you must map the reader role for all other applications to at least the same level of security as the Search reader role. The reason for this is that the public Atom feeds in Search are secured by the reader role which is mapped to "Everyone" in Search by default and all of the other applications use these atom feeds. Their reader roles must have at least the same level of security as the Search reader role.
- As long as you have configured single sign-on between the applications, requiring authentication for each application does not prompt the same users for credentials as they move from one application to another within a single session. It only prompts for credentials when users log in to the first application. See Enabling single sign-on between all applications for more information.
- Click OK. Click Apply, and then click OK.
- If forcing authentication for Blogs (and Profiles, unless you are using something other than the Profiles database as the user directory): Create rewrite rules in the configuration file for the IBM HTTP Server to redirect Atom API and feed requests so that they are authenticated properly. Open the httpd.conf file which is stored in the ibm_http_server_root/conf directory, and then add the following rules to the file:
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/feed/(.*) RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L]
Related tasks
Use the Profiles database as the user directory Configure single sign-on
Set up single sign-on integration between IBM Connections and other IBM products and third-party security products.
How single sign-on works
IBM Connections uses single sign-on (SSO) to secure the transfer of user ID and password information that is used to authenticate with the system. With SSO, users can switch to different applications without needing to authenticate again.
SSO is automatically enabled when IBM Connections is installed on a single WebSphere Application Server profile or when different profiles are federated into the same cell.
Server-to-server authentication
SSO solutions can inadvertently block back-end server-to-server communication. IBM Connections uses a server-to-server authenticator to prevent internal communication being blocked by your SSO solution. The configuration settings for the authenticator are stored in the customAuthenticator element in LotusConnections-config.xml.
Set the single sign-on domain name
Set the single sign-on (SSO) domain name for your IBM WebSphere Application Server environment.
Choose the type of domain name to configure from the following options:
To set your SSO domain name, complete the following steps:
- Single SSO Domain
- Specify one domain name for all single sign-on hosts.
For example, if you administer a system named test4 that is registered as part of the example.com network domain, its fully qualified host name is test4.example.com. If SSO is enabled for the example.com domain, only cookies that originate in this domain are authenticated and can be stored on the test4.example.com system.
- Blank (Use local host as SSO Domain)
- If you do not define an SSO domain name, the Web browser defaults the domain name to the host name where the web application is running. Single sign-on is then restricted to the application server host name and does not work with other application server host names in the domain.
- Multiple SSO domains
- You can specify multiple domains separated by a semicolon (;), space ( ), comma (,), or pipe (|). The host name of each HTTP request is compared with each domain until the first match is located. For example, if you specified example.com;production.example.com as the SSO domain names and a match is found in the example.com domain first, the application server does not try to find a match in the production.example.com domain. However, if a match is not found in either example.com or production.example.com, the application server does not set a domain for the Ltpa Token cookie.
- Arbitrary SSO domain (Use URL domain as SSO domain)
- If you enter UseDomainFromURL in the Domain name field, the application server sets the SSO domain name value to the domain of the host that is used in the web address. For example, if an HTTP request comes from server1.example.com, the application server sets the SSO domain name value to example.com.
The UseDomainFromURL value is not case-sensitive. You can enter usedomainfromurl to use this value.
- Log in to the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.
- Select Security > Global security > Web and SIP security > Single sign-on (SSO).
- Enter a value for the SSO Domain name.
- Click Apply and then click Save.
- Perform a full synchronization of all the nodes.
What to do next
Ensure that you have enabled Interoperability Mode and Use available authentication data when an unprotected URI is accessed. For more information, see the Set up federated repositories topic.
Enable single sign-on for Tivoli Access Manager
Configure IBM Connections to use single sign-on with IBM Tivoli Access Manager.
Install IBM Tivoli Access Manager for e-business, version 6.1.1.
Ensure that you can access the installed IBM Connections applications from a web browser.
Set the IBM WebSphere Application Server single sign-on domain to the same value as that of the Tivoli Access Manager server.
- If you are enabling SSO between IBM Connections and a product that is deployed with a stand-alone LDAP configuration on WebSphere Application Server, or if the product is using IBM Lotus Domino, you must first complete the steps described in the Enabling SSO with stand-alone LDAP topic.
- The connectionsAdmin J2C alias specified during installation must correspond to a valid account that can authenticate with Tivoli Access Manager. It may map to a back-end administrative user account but is not intended to be used as a user account for IBM Connections. This account must be capable of authenticating for single sign-on against Tivoli Access Manager. If you need to update the userid or credentials for this alias, see the Changing references to administrative credentials topic
- IBM Connections supports the WebSphere cookie-based lightweight third-party authentication (LTPA) mechanism as an SSO solution for Tivoli Access Manager. IBM Connections does not support other SSO solutions that WebSEAL supports such as WebSphere Trust Association Interceptor (TAI), Forms SSO, Cross-domain SSO, or E-community SSO.
- IBM Connections supports the use of SSL Transparent Path junctions with Tivoli Access Manager. IBM Connections does not support TCP type junctions or Tivoli Access Manager Standard junctions.
- For more information about IBM Tivoli Access Manager, go to the Tivoli Access Manager information center.
Single sign-on (SSO) enables users to log in to one application of IBM Connections and switch to other applications and resources without having to authenticate again.
There are several different ways to configure SSO. This procedure describes one approach. It uses a WebSphere Application Server LTPA key and WebSEAL Transparent Junctions.
To set up SSO using Tivoli Access Manager, complete the following steps:
- To support SSO with the Lightweight Third-Party Authentication (LTPA) key, the same keys and passwords must be shared by the Tivoli Access Manager and WebSphere Application Server. To export the keys from WebSphere Application Server, complete the following steps:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator, expand Security, and then click Global security. In the Authentication mechanisms and expiration area, click LTPA.
- In the Cross-cell single sign-on section, provide values for the following fields:
- Password . Enter a secure password and then confirm the password. You need to provide this password later
- Fully qualified key file name . Specify a valid path and a file name for the file that will hold the exported keys
For example:
p*ssw*rd
C:\WAS_ltpa.keys
- Click Export keys.
If you have modified your federated repository properties, such as the realm name of the federated repository, re-export your LTPA keys and copy them to the Tivoli Access Manager server, to the same location that you used to create the Tivoli Access Manager junctions. See Step 4 for more details.
- Use available authentication data when an unprotected URI is accessed: On the Global security page, expand Web and SIP security, and then click General settings. Click Authenticate only when the URI is protected and select Use available authentication data when an unprotected URI is accessed, if it is not already selected. Click Apply and then click OK.
- Import your IBM HTTP Server certificate into the Tivoli Access Manager keystore. To import the certificate, complete the following steps:
- Copy the WebSEAL certificate key file to the system
...where IBM HTTP Server is installed.
You can discover the location of the WebSEAL certificate key file by examining the WebSEAL configuration file (Tivoli_install_root/PDWeb/etc/webseald-default.conf). To discover the location of the key file, search the file for the webseal-cert-keyfile keyword.
For example:copy "C:\Program Files\Tivoli\PDWeb/www-default\certs\pdsrv.kdb on the Tivoli Access Manager server to C:\pdsrv.kdb on the system where IBM HTTP Server is installed.
- On the system where IBM HTTP Server is installed, run the following command to start the IBM Key Management utility: ibm_http_server_root/bin/ikeyman.sh|bat
For example: C:\IBM\HTTPServer\bin\ikeyman.bat
- Open the IBM HTTP Server key file: Click Key Database File - Open, using the following values:
- Key database type
- CMS
- File Name
- plugin-key.kdb
- File Location
- ibm_http_server_root/Plugins/config/webserver_name/
For example: C:\IBM\HTTPServer\Plugins\config\webserver1\
Click OK and enter the password for your IBM HTTP Server key file. The default password is WebAS.
- Under Key database content, select Personal Certificates.
- Click Extract Certificate and specify a file name and location for storing the certificates. Leave the Field Data type unchanged.
For example:
- Certificate file name: cert.arm
- Location: C:\
- Use the iKeyman utility, open the WebSEAL certificate key file. When you are prompted for the password, enter the password of your WebSEAL key file. The default password is pdsrv.
- Under Key database content, select Signer Certificates.
- Click Add and then locate the extracted IBM HTTP Server certificate file. Enter a label for this certificate; for example: LC3_IHS_cerficate.
If you have already imported other IBM HTTP Server certificates into the WebSEAL certificate file, you must delete them before you can add a new certificate.
- Click Key Database File - Close to save your changes to the WebSEAL pdsrv.kdb certificate file and close the file.
- Copy the modified pdsrv.kdb WebSEAL certificate file to the same location on the WebSEAL server.
For example: C:/Program Files/Tivoli/PDWeb/www-default/certs/pdsrv.kdb
For more information about importing certificates, see the Add certificates to the WebSphere trust store topic.
- Use the exported LTPA key to configure the transparent path junctions in Tivoli Access Manager. To do so, complete the following steps:
- Copy the LTPA keys that you exported in Step 1 to the Tivoli Access Manager server.
For example: C:\WAS7_ltpa.keys
- Open the pdadmin command line utility, which is installed as part of the Tivoli Access Manager runtime package.
- Configure a transparent path junction for each installed application. Enter the following command once for each junction:
Do not include the carriage returns in the command. They are added here for display purposes.
server task WebSEAL-instance-name create -t ssl
-h backend-server-name -x -p backend-server-port -i -b ignore -f -A -2
-F ltpa-token -Z ltpa-password -k transparent-path-jct
where:
- WebSEAL-instance-name is the name of the WebSEAL server. Use the following syntax:
WebSEAL_instance-webseald-tam_server
For example: default-webseald-server.name.example.com
- backend-server-name is the domain name of the IBM Connections server for which Tivoli Access Manager is managing authentication. For example, IBM HTTP Server configured for IBM Connections.
- backend-server-port is the port used by the backend server.
- ltpa-token is the name of the file that you created to store the keys that you exported from WebSphere Application Server.
- ltpa-password is the password that you defined to encrypt the key file.
- transparent-path-jct is the transparent path junction for the application. Must match the URL pattern and must be created once for each URL pattern:
- /activities
- /blogs
- /cognos
- /communities
- /connections
- /dogear
- /files
- /forums
- /help
- /homepage
- /metrics
- /mobile
- /moderation
- /news
- /oauth2
- /profiles
- /search
- /wikis
For example:
server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password /profiles
Notes:
- The -2 parameter is needed only if you are using LTPA type 2. WebSphere Application Server allows both LTPA 1 and LTPA 2.
- When you create the junction for Blogs, use the -k parameter. Add this parameter prevents a potential problem if you graduate an Ideation Blog entry to an Activity.
- If your deployment of IBM Connections is integrated with Quickr® J2EE, add the -k parameter to the command for the Activities and Communities junctions. For example, adapt the following command for the Activities junction:
server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password -k /activities
- If an invalid certificate error occurs, import your backend-server-name certificate into the WebSEAL certificate store before you create the junctions.
- The transparent path junctions include /help even though it is not an independent IBM Connections application. It is an integral part of the News application but must be configured as a separate junction.
For more information about using the pdadmin command line utility, go to the Use pdadmin to create junctions web page in the Tivoli Access Manager information center.
- If your deployment of IBM Connections is integrated with Quickr® J2EE, add the -k parameter to the command for the Activities and Communities junctions. For example, adapt the following command for the Activities junction:
- Create a default IBM Connections ACL to override the default WebSEAL ACL by running the following commands:
acl create lc3-default-acl
acl modify lc3-default-acl set user sec_master TcmdbsvaBRlrx
acl modify lc3-default-acl set any-other Tmdrx
acl modify lc3-default-acl set unauthenticated T
acl modify lc3-default-acl set group iv-admin TcmdbsvaBRrxl
acl modify lc3-default-acl set group webseal-servers Tgmdbsrxl
- Attach default ACLs to resources that are protected by form-authentication.
- Attach the default ACL to application root URLs:
acl attach /WebSEAL/tam_server-WebSEAL_instance/app_root lc3-default-acl
where:
- tam_server is the host name of the Tivoli Access Manager server
- WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage IBM Connections; for example: default
- app_root is the root path to the IBM Connections applications, including the following:
- /activities
- /blogs
- /cognos
- /communities
- /dogear
- /files
- /forums
- /homepage
- /news
- /metrics
- /mobile
- /moderation
- /profiles
- /search
- /wikis
- lc3-default-acl is the access control list (ACL) that you defined in Step 5
For example: acl attach /WebSEAL/tam.example.com-default/activities example-default-acl
- Attach the default ACL to other resources that are protected by form-authentication. Run the following commands:
acl attach /WebSEAL/tam_server-WebSEAL_instance/object-path lc3-default-acl
where:
- tam_server is the host name of the Tivoli Access Manager server
- WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage IBM Connections; for example: default
- object-path is the path to the resource on that domain
- lc3-default-acl is the access control list that you defined in Step 5. Replace this variable with the name of your default ACL.
For example: acl attach /WebSEAL/tam.example.com-default/activities/service/getnonce/forms example-default-acl
See the Resources that require form-authentication table for a list of URLs that are protected by form-authentication.
Table 74. Resources that require forms authentication
Application Protected URL Activities /activities/seedlist/myserver /activities/service/atom2/communityEvent /activities/service/atom2/forms /activities/service/download/forms /activities/service/getnonce/forms Blogs /blogs/seedlist/myserver Bookmarks /dogear/seedlist/myserver Common resources /connections/opensocial/rest Communities /communities/calendar/seedlist/myserver /communities/forum/service/atom/forms /communities/recomm/ajax /communities/recomm/atom_form
/communities/service/atom/forms
Forums /forums/atom/forms /forums/seedlist/myserver Metrics /metrics /cognos
Profiles /profiles/atom/forms
/profiles/atom2/forms
- Define the unprotected access control list and then attach unprotected resources and resources that require basic-authentication to it using the pdadmin command line utility, so that Tivoli Access Manager passes HTTP requests for these resources through to WebSphere Application Server for authentication.
- To define the unprotected access control list, enter the following commands:
acl create ic-bypass-acl
acl modify ic-bypass-acl set user sec_master TcmdbsvaBRlrx
acl modify ic-bypass-acl set any-other Tmdrx
acl modify ic-bypass-acl set unauthenticated Tmdrx
acl modify ic-bypass-acl set group iv-admin TcmdbsvaBRrxl
acl modify ic-bypass-acl set group webseal-servers Tgmdbsrxl
where ic-bypass-acl is the name of the unprotected access control list; for example, connections-acl-bypass.
The any-other parameter refers to authenticated users who are not defined by other parameters such as sec_master or iv-admin.
- To attach the access control list to resources that do not require authentication, run the following command:
acl attach /WebSEAL/tam_server-WebSEAL_instance/object-path ic-bypass-acl
where:
- tam_server is the host name of the Tivoli Access Manager server
- WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage IBM Connections; for example: default
- object-path is the path to the resource on that domain
- ic-bypass-acl is the access control list that you defined in Step 7 a
See the Resources that do not require authentication table for a list of unprotected URLs .
Table 75. Resources that do not require authentication
Application Unprotected URL Activities /activities/auth /activities/authverify /activities/images /activities/service/html/mainpage /activities/oauth /activities/service/html/images /activities/service/html/servermetrics /activities/service/html/serverstats /activities/static /activities/service/html/styles /activities/service/html/themes /activities/serviceconfigs Blogs /blogs/static /blogs/oauth /blogs/serviceconfigs Bookmarks /dogear/bookmarklet/tagslike/proxy /dogear/oauth /dogear/peoplelike /dogear/serviceconfigs /dogear/static /dogear/tagslike /dogear/tagrecs Common resources /connections/bookmarklet/tools/blet.js /connections/bookmarklet/tools/discussThis.js /connections/bookmarklet/tools/rlet.js /connections/core/oauth /connections/oauth /connections/opensocial/oauth /connections/resources/socmail-client /connections/resources/ic /connections/resources/web /connections/resources/socpim /nav/common Communities /communities/calendar/Calendar.xml /communities/calendar/oauth /communities/images /communities/recomm/oauth /communities/service/atom/oauth /communities/service/opensocial/oauth /communities/serviceconfigs /communities/service/html/community/autoCompleteMembers.do /communities/service/html/singleas /communities/static /communities/stylesheet /communities/tools/embedAS.html Files /files/app /files/basic/anonymous/api /files/basic/anonymous/cmis /files/basic/anonymous/opensocial /files/form/anonymous/api /files/form/anonymous/cmis /files/form/anonymous/opensocial /files/oauth /files/static Forums /forums/oauth /forums/serviceconfigs /forums/static Home page /homepage/oauth /homepage/search /homepage/serviceconfigs /homepage/static /homepage/web/updates/ Metrics /metrics/service/eventTracker /metrics/service/oauth /cognos/servlet Moderation /moderation/oauth News /help /news/microblogging/isPermitted.action /news/follow/oauth /news/oauth /news/serviceconfigs /news/sharebox/config.action /news/static OAuth Provider /oauth2 Profiles /profiles/images /profiles/oauth /profiles/serviceconfigs /profiles/static Search /search/atom/search/* /search/oauth /search/static Widget container /connections/opensocial/anonymous/rest /connections/opensocial/common /connections/opensocial/gadgets /connections/opensocial/ic /connections/opensocial/rpc /connections/opensocial/social /connections/opensocial/xrds /connections/opensocial/xpc Wikis /wikis/basic/anonymous/api /wikis/form/anonymous/api /wikis/oauth /wikis/static
- The Atom feeds on IBM Connections servers use basic authentication because most feed readers are unable to authenticate with form-authentication. WebSphere Application Server and IBM Connections applications authenticate these Atom HTTP requests through basic authentication as required. To attach the unprotected ACL to resources that IBM Connections protects with basic authentication, run the following command:
acl attach /WebSEAL/tam_server-WebSEAL_instance/object-path ic-bypass-acl
where:
- tam_server is the host name of the Tivoli Access Manager server
- WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage IBM Connections; for example: default
- object-path is the path to the resource on that domain
- ic-bypass-acl is the access control list that you defined in Step 7 a
For example: acl attach /WebSEAL/example.com-default/activities/service/atom example-bypass-acl
See the Resources that require basic authentication table for a list of protected URLs .
Table 76. Resources that require basic authentication
Application Protected URL Activities /activities/follow/atom /activities/service/atom /activities/service/atom2 /activities/service/download /activities/service/getnonce /activities/service/html/autocompleteactivityname /activities/service/html/autocompleteentryname /activities/service/html/autocompletemembers Blogs /blogs/api /blogs/atom /blogs/follow/atom /blogs/issuecategories /blogs/roller-ui/blog /blogs/roller-ui/feed /blogs/roller-ui/BlogsWidgetEventHandler.do /blogs/roller-ui/rendering/api /blogs/roller-ui/rendering/feed /blogs/services/atom Bookmarks /dogear/api/app /dogear/api/deleted /dogear/api/notify /dogear/atom /dogear/people.do Common resources /connections/opensocial/basic/rest Communities /communities/calendar/atom /communities/calendar/handleEvent /communities/calendar/ical /communities/follow/atom /communities/forum/service/atom /communities/recomm/atom /communities/recomm/handleEvent /communities/service/atom /communities/service/atom/communities/my /communities/service/json /communities/service/opensocial Files /files/basic/api /files/basic/api/myuserlibrary/feed /files/basic/cmis /files/basic/opensocial /files/follow/atom Forums /forums/atom /forums/follow/atom Home page /homepage/atom/mysearch /homepage/atom/search News /news/atom/service /news/atom/stories/community /news/atom/stories/newsfeed /news/atom/stories/public /news/atom/stories/save /news/atom/stories/saved /news/atom/stories/statusupdates /news/atom/stories/top /news/atom/watchlist /news/atomfba/stories/public Profiles /profiles/atom /profiles/atom2 /profiles/atom/forms/tagCloud.do If you use case-insensitive junctions in your Tivoli Access Manager configuration, specify tagcloud.do instead of tagCloud.do.
/profiles/follow/atom /profiles/json /profiles/vcard /profiles/photo.do /profiles/audio.do Wikis /wikis/basic/api /wikis/follow/atom
- Specify a dynamic URL pattern to support the Blogs application and mail notification:
- Create a dynurl configuration file named dynurl.conf. The dynurl.conf file is a plain text file that contains mappings from objects to patterns. Using a text editor, add the following content to the file:
/blogs/blogsfeed /blogs/*/feed/*
/blogs/blogsapi /blogs/*/api/*
Save the file in the webseal-instance-docroot/lib directory. For example:
- AIX: /usr/Tivoli/PDweb/www-default/lib
- Linux: /opt/Tivoli/PDweb/www-default/lib
- Windows: C:\Program Files\Tivoli\PDweb\www-default\lib
- To attach the bypass ACL that you defined in Step 7 a to the dynurl ACL, open the pdadmin command line utility and enter the following commands:
acl attach /WebSEAL/tam_server-WebSEAL_instance/blogs/blogsfeed ic-bypass-acl
acl attach /WebSEAL/tam_server-WebSEAL_instance/blogs/blogsapi ic-bypass-acl>
where:
- tam_server is the host name of the Tivoli Access Manager server.
- WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage IBM Connections; for example: default.
- ic-bypass-acl is the name of the access control list that you defined earlier.
For example:
acl attach /WebSEAL/server.name.example.com -default/blogs/blogsfeed open
- To allow large Blogs posts, open the webseald.conf file and add the following parameter:
dynurl-allow-large-posts = yes
- To enable the uploading of PDF files, add the following parameter to the webseald.conf file:
suppress-dynurl-parsing-of-posts = yes
- Configure Tivoli Access Manager to use form-authentication over HTTPS by updating the webseald-server-name.conf file. Add the following line to the [forms] stanza:
forms-auth = https
You cannot specify HTTP-only authentication. To specify both HTTP and HTTPS, add the following line: forms-auth = both.
- (Do not complete this step for Tivoli Access Manager with SPNEGO) Add a Tivoli Allow access to the Embedded Experience gadget by adding the following line to the [ba] stanza in the webseald-server-name.conf file:
ba-auth = none
- Configure content filtering by adding the following lines to the webseald-server-name.conf file:
[filter-content-types]
type = text/xml
type = application/atom+xml
[script-filtering]
script-filter = yes
rewrite-absolute-with-absolute = yes
- Configure Tivoli Access Manager as the reverse proxy for IBM Connections. Update the webseald-server-name.conf file:
Add the following line to the [server] stanza:
web-host-name = fully-qualified-host-name
Add the following line to the [session] stanza:
use-same-session = yes
Stop and restart your WebSEAL instance.
- Update the values for the dynamicHosts and interService URL attributes in the LotusConnections-config.xml configuration file:
- Use the following command to check out LotusConnections-config.xml:
execfile("app_server_root/profiles/DMGR/bin/connectionsConfig.py")LCConfigService.checkOutConfig("working_directory","cell_name")
If you are prompted to specify which server to connect to, type 1.
where:
For example: LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- working_directory is the temporary working directory to which configuration files are stored while you edit them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case sensitive. If you do not know the cell name, enter the following command in the wsadmin client to determine it:
print AdminControl.getCell()
- Update the dynamicHosts values by running the following commands:
Enable dynamicHosts:
LCConfigService.updateConfig("dynamicHosts.enabled","true")
Enter the WebSEAL host name in the values for the dynamicHosts.href and dynamicHosts.ssl_href attributes:
LCConfigService.updateConfig("dynamicHosts.href","http://WebSEAL_host")
LCConfigService.updateConfig("dynamicHosts.ssl_href","https://WebSEAL_host")
where WebSEAL_host is the fully qualified host name of the WebSEAL server.
Notes:
Each href attribute in LotusConnections-config.xml is case-sensitive and must specify a fully-qualified domain name.
- The fully-qualified host name for the WebSEAL server and the dynamicHosts configuration must be identical.
- (Do not complete this step for Tivoli Access Manager with SPNEGO) Update the interService URL values by running the following command:
LCConfigService.updateConfig("application_interService_key","https://WebSEAL_host")
where:
- WebSEAL_host is the fully qualified host name of the WebSEAL server
- application_interService_key is the href attribute for the application and includes the following applications:
- activities.interService.href
- blogs.interService.href
- communities.interService.href
- dogear.interService.href
- files.interService.href
- forums.interService.href
- help.interService.href
- homepage.interService.href
- mobile.interService.href
- moderation.interService.href
- news.interService.href
- personTag.interService.href
- profiles.interService.href
- quickr.interService.href
- sametimeLinks.interService.href
- sametimeProxy.interService.href
- search.interService.href
- wikis.interService.href
- Check LotusConnections-config.xml in by running the following command:
LCConfigService.checkInConfig()
You can also complete this step by running the connectionsConfig.py script in the wsadmin client.
- Determine how you want the system to behave when users log out of IBM Connections. By default, when users click Log out in the SSO environment, they are not fully logged out of IBM Connections. Edit the IBM HTTP Server httpd.conf configuration file to implement the post-log out behavior. By default, the file is located in the following directory:
- AIX: /usr/IBM/HTTPServer/conf
- Linux: /opt/IBM/HTTPServer/conf
- Windows: C:\IBM\HTTPServer\conf
To capture requests to /ibm_security_logout and redirect them to /pkmslogout, add the following rewrite rules to the httpd.conf file:
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteRule ^/(.*) /pkmslogout [noescape,L,R]
You must add these rules to both the HTTP and HTTPS entries.
Ensure that the line that enables mod_rewrite is not commented out by removing the preceding # symbol. For example:
LoadModule rewrite_module modules/mod_rewrite.so
The following example illustrates a typical portion of the httpd.conf file after you have implemented the steps described in this step:
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteRule ^/(.*) /pkmslogout [noescape,L,R]
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
<IfModule mod_ibm_ssl.c>
Listen 0.0.0.0:443
<VirtualHost *:443>
ServerName connections.example.com
SSLEnable
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteRule ^/(.*) /pkmslogout [noescape,L,R]
</VirtualHost>
</IfModule>
SSLDisable
- Add an ErrorDocument 500 statement to the httpd.conf file. This statement appears in the user's browser if an IBM Connections application becomes unavailable.
- Save and close the httpd.conf file.
- Restart IBM HTTP Server.
- (Do not complete this step for Tivoli Access Manager with SPNEGO) Add a Tivoli Access Manager authenticator property by editing LotusConnections-config.xml.
- Use the following command to check out the configuration file:
execfile("app_server_root/profiles/DMGR/bin/connectionsConfig.py")
If you are prompted to specify which server to connect to, enter 1.
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
- app_server_root is the WebSphere Application Server installation directory
- DMGR is the name of the Deployment Manager profile. For example: Dmgr01
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied while you edit them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case sensitive. If you do not know the cell name, execute the following command in the wsadmin client to determine it:
print AdminControl.getCell()
For example:
LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Configure the custom authenticator to support server-to-server authentication for Tivoli Access Manager:
LCConfigService.updateConfig("customAuthenticator.name",
"TAMAuthenticator")
- Keep the file open until you have completed the next step.
- (Do not complete this step for Tivoli Access Manager with SPNEGO) Configure the cookie timeout value for IBM Connections:
- Locate the CookieTimeout attribute in LotusConnections-config.xml. If the attribute is not present, add it to the <customAuthenticator name="TAMAuthenticator"> element.
- Set the value, in minutes, of the CookieTimeout attribute to be equal to or less than the maximum timeout and idle timeout values that you configured in Tivoli Access Manager.
When your production environment is ready, set the AllowSelfSignedCerts parameter to false.
If the parameter does not already exist in LotusConnections-config.xml, create it. Open the file in a text editor and add the parameter to the customAuthenticator element.
- Save your changes.
- Check LotusConnections-config.xml back in by running the following command:
LCConfigService.checkInConfig()
- The value of the cookie timeout attribute in LotusConnections-config.xml must be smaller than the values of the timeout and inactive-timeout attributes in the webseald-server-name.conf file. Check these values in the [session] stanza of the webseald-server-name.conf file and edit them if necessary.
The values of the timeout parameters in the Tivoli Access Manager configuration file are given in seconds but the CookieTimeout value in LotusConnections-config.xml is given in minutes.
Use the following example as a guide:
# Maximum lifetime (in seconds) for an entry in the credential cache
# Set this to zero allows entries in the cache to fill without expiry until the
# cache contains the number of entries specified by max-entries. After that
# point, entries are expired according to a least recently used algorithm.
timeout = 3600
# Lifetime (in seconds) of inactive entries in the credential cache.
# To disable, set to 0.
inactive-timeout = 600
- Import the Tivoli Access Manager certificate into the WebSphere Application Server trust store. For more information, see the Add certificates to the WebSphere trust store topic.
- Restart your cluster: Stop all application servers and all nodes, and then restart the deployment manager, all the nodes, and all the application servers.
Enable single sign-on for SiteMinder
Configure IBM Connections to use Computer Associates' SiteMinder to implement user authentication and single sign-on (SSO).
Complete the following prerequisite conditions:
- Ensure that you can access IBM Connections applications from a web browser.
- Complete the installation and configuration of TAI/ASA. The instructions are included with SiteMinder.
- Verify that TAI/ASA is registered with WebSphere Application Server.
Each href attribute in LotusConnections-config.xml is case-sensitive and must specify a fully-qualified domain name.
- The connectionsAdmin J2C alias specified during installation must correspond to a valid account that can authenticate with SiteMinder. It may map to a back-end administrative user account. This account must be capable of authenticating for single sign-on against SiteMinder. If you need to update the user ID or credentials for this alias, see the Changing references to administrative credentials topic.
- WebSphere Application Server 7 Fix Pack 21 does not provide the key Java libraries required to install and configure SiteMinder Application Server Agents (ASA) for WebSphere with WebSphere Application Server. The procedure to update your files is described in Step 1 of this task.
- For more information about the SiteMinder Policy Server and Web Agent configuration, go to the CA SiteMinder BookShelf.
- For more information about the SiteMinder Agent for WebSphere, see the CA SiteMinder Agent for WebSphere guide (PDF) and the CA eTrust SiteMinder Agent for IBM WebSphere Release Notes® (PDF).
You need to create SiteMinder Agent and Domain objects with realms, rules, and a policy related to IBM HTTP Server and WebSphere Application Server.
When a user requests a page that is protected by SiteMinder, the Web Agent on the HTTP server intercepts the request and prompts the user for authentication. If the user provides valid credentials, the user is authenticated and an SMSESSION cookie is added to the request which is then passed on to the WebSphere Application Server. The SiteMinder Trust Association Interceptor (TAI) on the server verifies the information in the cookie and sets the User Principal that IBM Connections requires to identify the user.
This task describes a configuration that uses SiteMinder Policy Server 6.0 SP5, SiteMinder ASA 6.0 Agent for WebSphere Application Server (with CR00010 hotfix), and SiteMinder Web Agent v6qmr5-cr035.
To set up SSO using SiteMinder:
- Download and apply the Unrestricted JCE policy files:
- Go to the J2SE 5 SDK Security information web page.
- Authenticate with your universal IBM user ID and password.
- Download the Unrestricted JCE Policy files for SDK for all newer versions package.
- Extract the files from the downloaded package.
- Back up your existing copies (if any) of the US_export_policy.jar and local_policy.jar files, located in the app_server_root/java/jre/lib/security directory.
- Copy the new jar files from the extracted package to the same directory, overwriting any existing files.
- Create agents on the SiteMinder Policy Server, including a Web Agent for IBM HTTP Server and an Application Server Agent for WebSphere Application Server.
- Open the SiteMinder Administration console.
- Right-click Agents and select Create Agent.
- Enter details of the Name and Description of the Web Agent for IBM HTTP Server.
- Repeat these steps for the Application Server Agent.
- Create Agent Configuration Objects on the SiteMinder Policy Server. In the SiteMinder Administration Console, open the Agent Conf Objects pane and complete the following steps:
- Configure the Web Agent for IBM HTTP Server:
- Right-click Apache Default Sets Agent and select Duplicate Configuration Object.
- Enter the Name and description of the Agent Configuration Object.
- Update the following parameters to match your environment:
- DefaultAgentName
- Name of the Apache Agent created earlier
- CookieDomain
- your_domain
where your_domain is your IBM Connections domain. If, for example, the URL is http://activities.example.com/activities, your host name is activities.example.com and your domain is example.com. In this example, you would set CookieDomain=example.com. .
- RequireCookies
- NO
This parameter configures the Web Agent to support basic authentication but without requiring all API client programs to support cookies.
- BadCSSChars
- <,>
This parameter enables the Invite colleagues functionality in Profiles.
- LogOffUri
- URI
Configure SiteMinder to recognize only one web address as the logout web address. Uncomment one of the following URIs by removing the number sign (#) character:
#LogOffUri="/activities/service/html/ibm_security_logout"
#LogOffUri="/blogs/ibm_security_logout"
#LogOffUri="/communities/communities/ibm_security_logout"
#LogOffUri="/dogear/ibm_security_logout"
#LogOffUri="/files/ibm_security_logout"
#LogOffUri="/forums/ibm_security_logout"
#LogOffUri="/homepage/web/ibm_security_logout"
#LogOffUri="/moderation/ibm_security_logout"
#LogOffUri="/news/ibm_security_logout"
#LogOffUri="/profiles/ibm_security_logout"
#LogOffUri="/search/ibm_security_logout"
#LogOffUri="/wikis/ibm_security_logout"
- Under the System tab, update the Agent Configuration Object with the following value: FCCCompatMode - NO
- Configure the Application Server Agent:
- Right-click Apache Default Sets Agent and select Duplicate Configuration Object.
- Enter the Name and description of the Agent Configuration Object.
- Update the following parameters to match your environment:
- DefaultAgentName
- Name of the Apache Agent created earlier
- CookieDomain
- your_domain
where your_domain is your IBM Connections domain. If, for example, the URL is http://activities.example.com/activities, your host name is activities.example.com and your domain is example.com. In this example, you would set CookieDomain=example.com.
- AssertionAuthResource
- /siteminderassertion
- AssertbyUserID
- True
Notes:
- When activated, the LogOffUri parameter clears the SMSESSION cookie and ensures that the user is logged out of all IBM Connections browser sessions.
- To add parameters, edit the Agent Configuration Object on the SiteMinder Policy Server. Alternatively, you can edit the LocalConfig.conf file on the HTTP server if the Web Agent is configured to use it.
- If you are editing the SiteMinder configuration file directly, you must surround the values of SiteMinder configuration parameters with quotation marks ("); for example: BadCSSChars="<,>". If you are changing these parameters within the SiteMinder Policy Server, do not use quotation marks.
- Specify your SiteMinder Authentication Scheme configuration:
- Open the SiteMinder Administration Console and navigate to the Authentication Scheme Properties dialog box.
- From the Authentication Scheme type list, select HTML Form template.
- Clear the Use Relative Target check box.
- Enter the URL of your IBM Connections HTTP server in the web Server Name field.
- On the SiteMinder Policy Server, create a domain for the IBM HTTP Server web agent.
- Create protected realms under the IBM HTTP Server Web Agent domain:
- Use the Agent Object and Forms Authentication Scheme that you created in Step 3.a and Step 4, create SiteMinder realms that are protected by forms authentication.
See the Realms that require forms authentication table for a list of URLs that are protected by forms authentication.
Table 77. Realms that require forms authentication
Application Protected URL resource ConnectionsDefaultRealm / Activities /activities/follow/atomfba /activities/service/atom2/forms /activities/service/atom2/communityEvent /activities/service/download/forms /activities/service/getnonce/forms Blogs /blogs/api_form /blogs/atom_form /blogs/follow/atomfba /blogs/roller-ui/blog /blogs/roller-ui/feed_form /blogs/roller-ui/rendering/api_form /blogs/roller-ui/rendering/feed_form /blogs/services/atom_form Bookmarks /dogear/atom_fba Common resources /connections/opensocial/rest Communities /communities/calendar/atom_form /communities/follow/atomfba /communities/forum/service/atom/forms /communities/recomm/ajax /communities/recomm/atom_form /communities/service/atom/forms Files /files/follow/atomfba /files/form/cmis/repository Forums /forums/atom/forms /forums/follow/atomfba Metrics /metrics /cognos Profiles /profiles/atom/forms /profiles/atom2/forms /profiles/follow/atomfba Wikis /wikis/follow/atomfba
- Use the Agent Object and Forms Authentication Scheme that you created in Step 3.a and Step 4, create SiteMinder realms that are protected by basic authentication.
See the Realms that require basic authentication table for a list of URLs that are protected by basic authentication.
Table 78. Realms that require basic authentication
Application Protected URL resource Activities /activities/follow/atom /activities/service/download /activities/service/html/autocompleteactivityname /activities/service/html/autocompleteentryname /activities/service/html/autocompletemembers /activities/service/atom /activities/service/getnonce Blogs /blogs/api /blogs/atom /blogs/follow/atom /blogs/issuecategories /blogs/roller-ui/BlogsWidgetEventHandler.do /blogs/roller-ui/feed /blogs/roller-ui/rendering/api /blogs/roller-ui/rendering/feed /blogs/services/atom Bookmarks /dogear/api/app /dogear/api/deleted /dogear/api/notify /dogear/atom Common resources /connections/opensocial/basic/rest Communities /communities/calendar/atom /communities/calendar/handleEvent /communities/calendar/ical /communities/follow/atom /communities/forum/service/atom /communities/recomm/atom /communities/recomm/handleEvent /communities/service/atom /communities/service/json Files /files/basic/api /files/basic/cmis /files/basic/opensocial /files/follow/atom Forums /forums/atom /forums/follow/atom Home page /homepage/atom/search /homepage/atom/mysearch News /news/atom/service /news/atom/stories/newsfeed /news/atom/stories/public /news/atom/stories/saved /news/atom/stories/statusupdates /news/atom/stories/top /news/atom/watchlist /news/atomfba/stories/public Profiles /profiles/atom /profiles/atom2 /profiles/audio.do /profiles/follow/atom /profiles/json /profiles/photo.do /profiles/vcard Wikis /wikis/basic/api /wikis/follow/atom
- Optional: Protect login credentials with encryption: Using the Basic over SSL Template scheme, create a SiteMinder Authentication Scheme and apply the new Authentication Scheme to all the SiteMinder realms that require basic authentication.
- Create Delete and Head actions for the Web Agent. By default, the Web Agent has only the Get, Post, and Put actions available. To add the Delete and Head actions:
- In the SiteMinder Administration Console, click View and select Agent Types.
- Select Agent Types in the Systems pane.
- Double-click Web Agent in the Agent Type list.
- In the Agent Type Properties dialog box, click Create.
- Enter Delete in the New Agent Action dialog box and click OK.
- Enter Head in the New Agent Action dialog box and click OK.
- Click OK again to save the new action.
- Create the following rules for each realm:
Table 79. Rules for the IBM HTTP Server realms
GetPostPutDelHead rule OnAuthAccept rule Realm: CurrentRealm Realm: CurrentRealm Resource: * (not /*) Resource: * (not /*) Action: Web Agent actions -> Get,Post,Put,Delete,Head Action: Authentication events -> OnAuthAccept When this Rule fires: Allow Access When this Rule fires: Allow Access Enable or Disable this Rule: Enabled Enable or Disable this Rule: Enabled
- Create a policy and add the users who will be able to access the server to the policy. You can allow all users in the LDAP directory or a subset of users; for example: an LDAP branch, individual users, or groups of users.
- Add the new rules to the new policy.
- Specify realms that are not protected by SiteMinder.
You must configure notification templates and some Atom feeds as unprotected URLs. The Blogs footer page must also be unprotected because Blogs uses the Velocity template to extract footer pages.
Table 80. Realms that do not require authentication
Application Unprotected URL resource Activities /activities/auth /activities/images /activities/oauth /activities/service/html/images /activities/service/html/mainpage /activities/service/html/styles /activities/service/html/themes /activities/service/html/servermetrics /activities/service/html/serverstats /activities/serviceconfigs /activities/static/ Blogs /blogs/oauth /blogs/serviceconfigs /blogs/static/ Bookmarks /dogear/oauth /dogear/peoplelike /dogear/serviceconfigs /dogear/static/ Common resources /connections/bookmarklet/tools/blet.js /connections/bookmarklet/tools/discussThis.js /connections/bookmarklet/tools/rlet.js /connections/core/oauth /connections/oauth /connections/resources/ic /connections/resources/socmail-client /connections/resources/socpim /connections/resources/web /nav/common Communities /communities/calendar/Calendar.xml /communities/calendar/oauth /communities/comm.widget /communities/images /communities/nav /communities/recomm/oauth /communities/resourceStrings.do /communities/service/atom/oauth /communities/service/html/communityview /communities/service/html/community/autoCompleteMembers.do /communities/service/html/singleas /communities/service/opensocial/oauth /communities/serviceconfigs /communities/static/ /communities/stylesheet /communities/tools/embedAS.html /communities/widgets Files /files/app /files/basic/anonymous/api /files/basic/anonymous/cmis /files/basic/anonymous/opensocial /files/form/anonymous/api /files/form/anonymous/cmis /files/form/anonymous/opensocial /files/oauth /files/static/ Forums /forums/oauth /forums/serviceconfigs /forums/static/ Home page /homepage/oauth /homepage/search /homepage/serviceconfigs /homepage/static/ /homepage/web/updates/ Metrics /metrics/service/eventTracker /metrics/service/oauth /cognos/servlet Moderation /moderation/app /moderation/oauth /moderation/static News /help /news/microblogging/isPermitted.action /news/follow/oauth /news/oauth /news/serviceconfigs /news/sharebox/config.action /news/static/ OAuth Provider /oauth2 Profiles /profiles/atom/forms/connections.do /profiles/images /profiles/oauth /profiles/serviceconfigs /profiles/static/ Search /search/atom/search /search/oauth /search/static/ Widget container /connections/opensocial/anonymous/rest /connections/opensocial/common /connections/opensocial/gadgets /connections/opensocial/ic /connections/opensocial/oauth /connections/opensocial/rpc /connections/opensocial/social /connections/opensocial/xrds /connections/opensocial/xpc Wikis /wikis/basic/anonymous/api /wikis/form/anonymous/api /wikis/home /wikis/js /wikis/oauth /wikis/static/
- Map the Reader role in the Activities and Wikis applications All Authenticated in Application's Realm. See Roles.
- On the SiteMinder Policy Server, create a domain for the Application Server Agent.
- Add the following realm to the new WebSphere Application Server domain:
Table 81. SiteMinder realms for WebSphere Application Server
Realm name Protected resource SM TAI Validation /siteminderasssertion You must configure the Protected Resource of this realm to match the AssertionAuthResource parameter that you configured earlier for the Application Server Agent.
- Set the timeout value of the session for each realm.
- In the SiteMinder Policy Server, open the Realm Dialog and click Session.
- In the Session Timeouts Group Box, enter timeouts for each realm. Enter the following values, if they are not already present:
- Maximum Timeout Enabled
- 2 Hours 0 Minutes
- Idle Timeout Enabled
- 1 Hours 0 Minutes
The maximum timeout and the idle timeout must be longer than the LTPA token timeout, which is defined in WebSphere Application Server. The LTPA token timeout is set to 120 minutes by default.
- Install the Web Agent on IBM HTTP Server:
- Download the latest version of the Web Agent from the CA website.
- Install the Web Agent. For instructions, go to the SiteMinder BookShelf.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
- Install the Application Server Agent on your WebSphere nodes:
- Download the latest version of the Application Server Agent from the CA website.
- Install the Application Server Agent on each node in your IBM Connections deployment. For instructions, see the SiteMinder Agent for WebSphere Agent Guide.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
- Copy the smagent.properties file from the ASA installation conf folder to the WebSphere Application Server profile properties folder; for example: C:\program files\IBM\websphere\appserver\appsvr01\properties.
If Cognos is enabled, also copy the smagent.properties file to the properties folder of the WebSphere Application Server profile that hosts Cognos.
- Configure Trust Association Interceptor on WebSphere Application Server.
- From the administrative console for WebSphere Application Server, click Security > Global security.
- Under Web and SIP security, click Trust association.
- Click Enable Trust Association and then click Save.
- Click Interceptors.
- Delete any unused interceptors.
Do not delete the OAuth interceptor.
- Click New and enter the following name for the new interceptor:
com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor
- Click OK and then click Save.
- Restart WebSphere Application Server.
- Create rewrite rules to remap Atom API requests. Open the IBM HTTP Server httpd.conf configuration file. The file is stored in the ibm_http_server_root/conf directory. Add the following rules to the file:
You must add these rules to both the HTTP and HTTPS sections of the file.
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]
Do not close the httpd.conf file until after the next step.
- Create rewrite rules that redirect URLs when users log out of IBM Connections. Add the following rules to the httpd.conf file:
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteCond %{QUERY_STRING} !=logoutExitPage=your_logout_url
RewriteRule /(.*)/ibm_security_logout(.*)
LogOffUri?logoutExitPage=your_logout_url [noescape,L,R]
where LogOffUri is the URL that you uncommented earlier. After logging out of IBM Connections, the user's browser is directed to your_logout_url. This URL could be your corporate home page or the SiteMinder login page.
You must add these rules to both the HTTP and HTTPS entries.
The following example illustrates a typical portion of the httpd.conf file after you have implemented this step:
RewriteEngine on RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*) RewriteCond %{QUERY_STRING} !=logoutExitPage=http://corphome.example.com RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://corphome.example.com [noescape,L,R] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L] #Connections Config for SSL LoadModule ibm_ssl_module modules/mod_ibm_ssl.so <IfModule mod_ibm_ssl.c> Listen 0.0.0.0:443 <VirtualHost *:443> ServerName connections.example.com SSLEnable RewriteEngine on RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*) RewriteCond %{QUERY_STRING} !=logoutExitPage=http://corphome.example.com RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://corphome.example.com [noescape,L,R] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L] </VirtualHost> </IfModule> SSLDisableUncomment the LoadModule rewrite_module modules/mod_rewrite.so line in the httpd.conf file. This line is commented out by default. When the line is commented out, the web server will not start.
- Save and close the httpd.conf file, restart the http server, and then make sure the SiteMinder page displays when users access the http server.
- Add a SiteMinder authenticator property to the IBM Connections configuration by editing LotusConnections-config.xml.
- Use the following command to check out the configuration file:
execfile("app_server_root/profiles/DMGR/bin/connectionsConfig.py")
If you are prompted to specify which server to connect to, enter 1.
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
- app_server_root is the WebSphere Application Server installation directory
- DMGR is the name of the Deployment Manager profile. For example: Dmgr01
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied while you edit them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case sensitive. If you do not know the cell name, execute the following command in the wsadmin client to determine it:
print AdminControl.getCell()
For example:
LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Update the custom authenticator values by running the following commands:
- Configure the custom authenticator to support server-to-server authentication for SiteMinder:
LCConfigService.updateConfig("customAuthenticator.name",
"SiteMinderAuthenticator")
Set the value of the custom.authenticator.cookieTimeout parameter to be equal to or less than the maximum timeout and idle timeout values that you configured earlier.
If the parameter does not already exist in LotusConnections-config.xml, create it. Open the file in a text editor and add the parameter to the customAuthenticator element. Set the timeout value in minutes.
LCConfigService.updateConfig("customAuthenticator.CookieTimeout","timeout"
where timeout is a value in minutes that is less than or equal to the SiteMinder timeout values.
When your production environment is ready, set the AllowSelfSignedCerts parameter to false.If the parameter does not already exist in LotusConnections-config.xml, create it. Open the file in a text editor and add the parameter to the customAuthenticator element.
- Check LotusConnections-config.xml back in by running the following command:
LCConfigService.checkInConfig()
- Restart your IBM Connections deployment.
- Stop IBM Connections servers, node agents, and deployment manager.
- Start the deployment manager and nodes.
- Allow time for the nodes to synchronize, and for the updated LotusConnections-config.xml file to be copied to each node.
- Start IBM Connections.
What to do next
Advise your users to close all browser windows when they log out of Activities. This precaution avoids potential security problems that could arise because the SiteMinder session cookie in a browser window might still be updating while a user is logging out from a different browser window.
Enable single sign-on for Lotus Quickr
Before installing the IBM Connections Connector for IBM Lotus Quickr, enable single sign-on (SSO) between IBM Connections and Lotus Quickr.
- This is an optional task.
- This task applies to Quickr J. For information about enabling single sign-on (SSO) for Quickr D, see the Enabling single sign-on for Domino topic.
- If you are enabling SSO between IBM Connections and a product that is deployed on a pre-6.1 version of WebSphere Application Server, you must first complete the steps described in the Enabling single sign-on for stand-alone LDAP topic.
When your IBM Connections applications are deployed on servers in the same WebSphere Application Server cell, SSO is enabled by default. However, when they applications are hosted in different cells, they use different LTPA certificates and you must manually enable SSO between IBM Connections and Lotus Quickr. To do this, you must exchange LTPA certificates between the cells.
If all the cells use Federated Repositories, set the realm name in each cell to the same value. For example, ensure that all cells use defaultWIMFileBasedRealm or a custom realm name such as exampleRealmName. Set the realm names before you export the LTPA token.
If any cell uses a stand-alone LDAP instead of Federated Repositories, set the realm names of all cells to the name of the LDAP server. For example, if you connect to an LDAP server at ldapserver.example.com over port 389, set all the realm names to ldapserver.example.com:389. Set the realm names before you export the LTPA token.
In either scenario, all cells must use the same realm name to facilitate SSO between the cells.
To allow SSO between IBM Connections and Lotus Quickr, complete the following steps:
- On the server where IBM Connections is installed, enable SSO:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator, expand Security > Global security.
- Expand Web and SIP security and then click Single sign-on (SSO).
- Enter the domain name .
Ensure that the domain name you enter is valid: On the node where Lotus Quickr is installed, log into the WebSphere Application Server Integrated Solutions Console as an administrator, click Security > Global security > Web and SIP security > Single sign-on (SSO) and verify that the domain name is present.
- On the node where Lotus Quickr is installed, complete the following steps:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator, and click Security > Secure administration, applications, and infrastructure.
- Click LTPA and provide values for the following fields:
- Password . Type a secure password that you will remember. You will need to provide this password later, when you configure to the keys you are exporting.
Confirm the password.
- Fully qualified key file name . Specify a valid path and name for the file that will hold the exported keys.
- Click Export keys
- On each node where IBM Connections is installed:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator, and click Security > Global security > LTPA
- In the Cross-cell single sign-on section, provide values for the following fields:
- Password . Set the password that you used for the Lotus Quickr key file that you exported.
Confirm the password.
- Fully qualified key file name . Set the path and name of the Lotus Quickr key file that you exported.
- Click Import keys.
- On each node where IBM Connections is installed:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator.
- Click Security > Global security > LTPA, and then in the Cross-cell single sign-on section, provide values for the following fields:
- Password . Type a secure password that you will remember. You will need to provide this password later, when you export the key file.
Confirm the password.
- Fully qualified key file name . Specify a valid path and a name for the file that will hold the exported keys.
- Click Export keys.
- On the node where Lotus Quickr is installed, complete the following steps:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator and click Security > Secure administration, applications, and infrastructure > LTPA.
- In the General properties section, provide values for the following fields:
- Password . Set the password that you used for the IBM Connections key file that you exported.
Confirm the password.
- Fully qualified key file name . Set the name of the IBM Connections key file that you exported.
- Click Import keys.
- Restart all the nodes.
Related tasks
Enable users to publish file attachments to Lotus Quickr
Enable single sign-on for Domino
If your organization uses IBM Connections in a Domino environment, you can enable single sign-on (SSO) for easier user authentication.
Before you can enable SSO, verify that you can access the installed IBM Connections applications from a web browser.
Start your Domino server.
Ensure that you have a user ID with administrative access to the Domino server.
Configure an LDAP server as the user directory.
Notes:
- This is an optional configuration.
- This task applies to Quickr D. For information about enabling single sign-on (SSO) for Quickr J, see the Enabling single sign-on for Lotus Quickr topic.
- If you are using a reverse proxy, you must specify the reverse proxy address in the LotusConnections-Config.xml file.
- If you are enabling SSO between IBM Connections and a product that is deployed on a pre-6.1 version of WebSphere Application Server, you must first complete the steps described in the Enabling single sign-on for stand-alone LDAP topic.
Single sign-on enables users to log into one IBM Connections application and switch to other applications without needing to authenticate again.
By default, applications deployed within the same WebSphere Application Server cell are enabled for single-sign-on. To support this, the application servers share the same set of LTPA keys and the same LDAP directory configuration. Use these instructions if you want to set up SSO between applications that use different LDAP directory configurations.
The Configure user name mapping in the SSO LTPA token topic in the IBM Lotus Domino information center can help you choose the correct configuration parameters for your environment.
To enable SSO for Domino:
- Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.
- Click Security > Global security.
- Select Federated Repositories from the Available realm definitions field and then click Configure.
- Enter the realm name of the LDAP server in the Realm name field. For example: enterprise.example.com:389.
- Click Apply and then click Save.
- Synchronize the nodes.
- Restart the servers in your IBM Connections deployment.
- Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.
- Click Security > Global security.
- In the Authentication mechanisms and expiration area, expand Web and SIP security and click LTPA.
- Enter your IBM Connections domain name in the Domain name field, ensuring that you add a dot (.) before the domain name.
- Select the check boxes for Interoperability Mode and Web inbound security attribute propagation.
- Restart your IBM Connections applications.
- Verify that you can switch between the applications without needing to authenticate more than once.
- Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.
- Click Security > Global security.
- In the Authenticaion area, click LTPA.
- In the Password and Confirm password fields, enter the password that protects the exported key.
- Enter the file name of the key file to generate in the Fully qualified key file name field.
- Click Export keys.
- Click Apply and then click Save.
- Set up the SSO configuration document on the Domino server by completing the steps in the Create a Web SSO configuration document topic in the Domino information center.
- Verify the Domino server maps correctly between the user IDs stored in the LDAP that is used by IBM Connections and the Domino address book.
- If user names are present in both the LDAP directory and the Domino Directory:
- In the user Person document, click Administration.
- Under Client Information, enter the user name DN that is expected by WebSphere Application Server in the LTPA user name field.
Typically, this name is the user's LDAP distinguished name (DN). Separate the name components with slashes. For example, if the DN is uid=jdoe,cn=sales,dc=example, dc=com, enter the following value: uid=jdoe/cn=sales/dc=example/dc=com.
- If user names are present in the LDAP directory only:
- Open the Directory Assistance document for the LDAP directory. Alternatively, create a directory assistance database and configure the Domino server to use this database.
- In the SSO Configuration section, enter an LDAP attribute for the name in an SSO token.
This attribute is used in the LTPA token when the LTPA_UserNm field is requested. Ensure that the selected field contains the user name that WebSphere Application Server expects. Options for this field include:
- To use the LDAP distinguished name, enter a value of $DN. This is the most common configuration; it indicates that the user's LDAP DN is the name expected by WebSphere Application Server, rather than a name in an arbitrary LDAP field.
- Use any appropriate LDAP attribute, provided it uniquely identifies the user.
- Leave the field blank to default to the Domino distinguished name, if known. Otherwise, the default is the LDAP distinguished name.
- Configure Domino Server to use the new Web SSO Configuration Document:
- In Domino Administrator, click Files and then open the server.s Address Book (the names.nsf file).
- Select the Servers view and open the server to configure.
- Navigate to Internet Protocols > Domino Web Engine.
- Change to Edit mode.
- Select the new Web SSO Document in the Web SSO Configuration box.
- Save your changes.
- Use the Domino console, stop and start the HTTP task by issuing the following commands:
tell http quit
load http
The tell http restart and restart task http commands cannot read the updated SSO configuration
Enable single sign-on for standalone LDAP
IBM Connections requires a federated repositories configuration, but you can enable IBM Connections applications to perform Single sign-on for a standalone LDAP directory.
This procedure is required if you want to enable Single sign-on (SSO) between IBM Connections and an application hosted by a version of WebSphere Application Server that is earlier than 6.1, which is the version in which federated repositories were introduced. Before you perform this procedure, configure federated repositories on IBM Connections.
By default, applications deployed on servers within the same WebSphere Application Server cell are enabled for single-sign-on. To support this, the servers share the same set of LTPA keys and the same LDAP directory configuration. Use this configuration if you want to set up SSO between applications that use different LDAP directory configurations. To enable SSO between IBM Connections and a WebSphere Application Server configured for standalone LDAP:
- Log in to the WebSphere Application Server Integrated Solutions Console by going to the following web address in a browser:
http://<web.server.host.name>:9060/ibm/console
- Log in to the Welcome page.
- Click Security > Global security.
- Select Federated Repositories from the Available realm definitions field, and then click Configure.
- On the Federated repositories page, add the <host_name>:<port> of the standalone LDAP server to the Realm name field.
For example:
ldap.example.com:389
- Click Apply and then click Save to save this setting.
- After changing the realm name, you must update the administrative user roles because the previous realm name is still appended to the administrative users. Until you remove and re-add the administrative users, the users are unable to access the Integrated Solutions Console.
- Navigate to Users and Groups > Administrative User Roles.
- Select all user roles and click Remove.
- Click Add.
- In the Roles field, click Administrator.
- In the User field, enter the user name to which you want to grant administrative privileges.
- In the Search string field, enter a user name to set as an administrator and then click Search. Select the user name in the Available list and click the right arrow button to move it to the Mapped to role field.
- To map other users, repeat the previous step.
- Click OK and then click Save.
If there is only one user, you might not be allowed to remove the user. In that case, add the new user first and then remove the original user.
- Synchronize the nodes and then restart the servers:
- Log into the Integrated Solutions Console for the Deployment Manager.
- Expand System administration > Nodes. Select the name of the node that you updated and click Full Resynchronize.
- Select Servers > Clusters. Select the check box for the cluster you want to restart and click Stop.
- Select System administration > Node agents. Select the check boxes for the nodes to restart and click Restart.
- Stop and restart the Deployment Manager.
- Log into the Integrated Solutions Console again.
- Select Servers > Clusters. Select the check box the cluster you want to restart and click Start.
Enable single sign-on for the Windows desktop
Configure IBM Connections to use SPNEGO for single sign-on (SSO). This configuration permits users to sign in to the Windows desktop and automatically authenticate with IBM Connections.
Verify that IBM Connections works correctly without the SPNEGO authentication protocol.
Create a user account in the LDAP directory and add it to the WebSphere Application Server administrators group.
Complete the steps in the Creating a service principal name and keytab file topic.
If you are using on-ramp plug-ins or mobile services, your data traffic is not authenticated by Kerberos tickets or SPNEGO tokens. It is instead authenticated through J2EE form-based authentication.
The Kerberos authentication protocol uses strong cryptography which enables a client to prove its identity to a server across an insecure network connection. After the client and server have proven their identity, the authentication protocol encrypts all data that the client and server exchange. The SPNEGO tokens, which wrap valid Kerberos tickets, can be used to negotiate the security for SSO.
To configure IBM Connections to use SPNEGO, complete the following tasks:
Map an Active Directory account to administrative roles
Map an account from Active Directory to administrative roles in IBM WebSphere Application Server.
This task is not required if you do not use Microsoft Active Directory.
Ensure that you have configured IBM Connections to use Active Directory as the user directory. For more information, see the Set up federated repositories topic.
Ensure that you have configured WebSphere Application Server to use the Kerberos and LTPA authentication option. For more information, see the Configuring SPNEGO on WebSphere Application Server topic.
Select an Active Directory account to map to administrative roles in IBM WebSphere Application Server.
After enabling Kerberos and LTPA authentication in WebSphere Application Server, the default file-based repository no longer works and you can no longer log in to the WebSphere Application Server Integrated Solution Console using the wasadmin account. Any services that require authentication and that use the wasadmin ID no longer work. Consequently, some functions in IBM Connections fail, including search indexing, notifications, and adding widgets.
To prevent such problems, you must map an account in Active Directory to the IBM Connections administrative roles in IBM WebSphere Application Server.
To map the Active Directory account:
- Map an Active Directory account to administrative roles:
- Log in to the WebSphere Application Server Integrated Solution Console on the Deployment Manager.
- Click Users and groups > Administrative user roles > Add and select Admin Security Manager.
- Enter the Active Directory account name in the Search string field and click Search.
- Select the account name in the Available column and click the right arrow button to add the account name to the Mapped to role column.
- Click OK.
- Click Add and select Administrator
- Enter the Active Directory account name in the Search string field and click Search.
- Select the account name in the Available column and click the right arrow button to add the account name to the Mapped to role column.
- Click OK.
- Click Save.
- Change J2C authentication:
- Click Security > Bus security > ConnectionsBus.
- Under Additional Properties, click Security > Users and groups in the bus connector role > New.
- In the SIB Security Resource Wizard window, click Users, enter the Active Directory account in the Search pattern field, and click Next.
- Select the check box for the account name and click Next.
- If you are satisfied with the summary information, click Finish.
- Click Save.
If you subsequently change the password for the Active Directory account that you map in this step, you must also change the password for the ConnectionsAdmin J2C alias.
- Update the messaging bus configuration. Complete the steps in the Updating the messaging bus configuration when the connectionsAdmin user ID changes topic.
- For each application, update the mapping for the dsx-admin, search-admin, and widget-admin J2EE roles, replacing the currently-mapped user with the Activity Directory account. Go to the Switching to unique administrator IDs for system level communication topic and complete Step 3.
- Modify the runtime user for the Search application:
- Click Applications > Application Types > WebSphere enterprise applications > Search.
- Under Details Properties, click User RunAs Roles.
- Select the Admin check box.
- Enter the new user name and password.
- Click Apply.
- Click OK.
If you subsequently change the password for the Active Directory account that you map in this step, you must also change the password for the ConnectionsAdmin J2C alias.
- (Only required if you use Windows services for starting or stopping IBM Connections) Edit your Windows services to use your Active Directory account instead of wasadmin to start and stop IBM Connections.
Create a service principal name and keytab file
Create a service account in Microsoft Active Directory to support a service principal name (SPN) for IBM Connections, and then create a keytab file that the Kerberos authentication service can use to establish trust with the web browser.
Configure IBM Connections to use Active Directory as the user directory. For more information, see the Set up federated repositories topic.
Do not perform this procedure until after you have populated the Profiles database. For more information, see the Populating the Profiles database topic.
Active Directory and the domain controller must be hosted on Windows systems but IBM Connections may be installed on AIX, Linux, or Windows systems.
A service principal name (SPN) account uniquely identifies an instance of a service. Before the Kerberos authentication service can use an SPN to authenticate a service, you must register the SPN on the account object that the service instance uses to log on. You must then create a keytab file. When a web browser tries to access the service, it must get a ticket from the Active Directory key distribution center to send with the access request. Active Directory uses the keytab file to decrypt the ticket sent from the web browser to establish that the application server can trust the browser.
In a network deployment of IBM Connections, each node is granted a key inside a key table file. This task shows you how to merge the keys for all the nodes in your deployment into a single key table.
An SPN consists of the following information:
- Service type
- Specifies the protocol to use, such as HTTP.
- Instance
- Specifies the name of the server hosting the application. For example: finance1.us.example.com. Use the IBM HTTP Server name or the virtual host name through which users access IBM Connections applications. You do not need to specify a port number.
- Realm
- Specifies the domain name of the server hosting the application. For example: US.EXAMPLE.COM.
Specify an SPN using the following syntax: service_type/instance@realm
For example: HTTP/finance1.us.example.com@US.EXAMPLE.COM
To create a service principal name and keytab file, complete the following steps:
- Synchronize the clocks of the systems hosting IBM Connections. If the host clocks are not synchronized with the Kerberos server clock, authentication will fail.
- AIX or Linux:
For information about synchronizing the system clocks in an AIX or Linux environment, refer to your operating system documentation. For examples of the ntpdate command, go to the ntpdate Command topic in the AIX information center.
- Windows:
Use the domain controller as the time server, run the TimeSyn.bat file on each IBM WebSphere Application Server system hosting IBM Connections. Use the Windows Task Scheduler to run the batch file.
For example, when finance.us.example.com is both the domain controller and the NTP time server, the TimeSyn.bat file contains the following commands:
w32tm /config /manualpeerlist:financès.example.com,0x8 /syncfromflags:MANUAL net stop w32time net start w32time w32tm /resyncFor more information about how to use the domain controller as the time server, go to the How to configure an authoritative time server in Windows Server topic on the Microsoft Support website. For more information about running the Windows schedule task, go to this Time synchronization topic on the Microsoft Support website.
- Install Windows Support Tools on the systems hosting Active Directory. You must have access to these tools to run the ktpass command later in this procedure. For more information, go to the Install Windows Support Tools webpage on the Microsoft Technet website.
- Log in to the Windows Domain Controller. You must know which server is the domain controller and you must have an administrative level user name and password.
- Create a new account for IBM Connections by accessing the Active Directory Users and Computers settings.
- In the New Object - User window, enter a user name in the User logon name field and specify the domain in the corresponding field. For example, enter lcserver01 in the User logon name field, and enter @us.example.com in the domain field.
- Click Next.
- Type a password for the logon name in the Password field.
- On the Account page, select the User cannot change password and Password never expires check boxes. By preventing the password from expiring, you avoid having to recreate the keytab file after the password has changed. Click OK to save the new user information.
- Map the service principal name to the IBM Connections user account that you created and generate a keytab file. Generate the keytab file using the IBM HTTP Server name or the virtual host as the instance in the service principal name. Run the following ktpass command on the domain controller:
ktpass -out path_to_keytab .princ SPN
-mapuser account_name -mapOp set .pass account_password
using the following variables:
- path_to_keytab
- File path where you want to store the generated keytab file.
- SPN
- The Kerberos service principal name.
- account_name
- The service account name.
- account_password
- Password associated with the service account.
For example:
ktpass -out c:\finance1.keytab -princ HTTP/finance1.us.example.com@US.EXAMPLE.COM -mapuser icserver01 -mapOp set -pass Passw0rd1For extra security, you should consider creating a keytab file for each system, where each system has its own user account. If you use the same user account to generate the keytab file, use the -mapOp add parameter instead of the -mapOp set parameter.
This example shows how to create unique keytab files for different systems:
ktpass -out c:\finance1.keytab -princ HTTP/finance1.us.example.com@US.EXAMPLE.COM -mapuser icserver01 -mapOp set -pass Passw0rd1 ktpass -out c:\finance2.keytab -princ HTTP/finance2.us.example.com@US.EXAMPLE.COM -mapuser icserver02 -mapOp set -pass Passw0rd2 ktpass -out c:\finance3.keytab -princ HTTP/finance3.us.example.com@US.EXAMPLE.COM -mapuser icserver03 -mapOp set -pass Passw0rd3
- Merge all the keytab files to make the Deployment Manager aware of the SPNs for each node.
The following example demonstrates the procedure for merging keytab files.
Assuming that you have created the following keytab files:
- krb5.keytab on the Deployment Manager
- krb5NodeA.keytab on Node A
- krb5NodeB.keytab on Node B
Run the ktab command with the following switch:
-m source_keytab_name destination_keytab_name
where source_keytab_name is the name of the keytab file on the source system and destination_keytab_name is the name of the keytab file on the destination system.
Step 1: merge the keytab file on Node A into the keytab file on the Deployment Manager:
# ./ktab -m /etc/krb5NodeA.keytab /etc/krb5.keytab Merging keytab files: source=krb5NodeA.keytab destination=krb5.keytab Done!Step 2: merge the keytab file on Node B into the keytab file on the Deployment Manager:
# ./ktab -m /etc/krb5NodeB.keytab /etc/krb5.keytab Merging keytab files: source=krb5NodeB.keytab destination=krb5.keytab Done!For more information, go to the Use the ktab command to manage the Kerberos keytab file topic in the IBM WebSphere Application Server 7 information center.
- Create a Kerberos configuration file named krb5.conf for each node. You do not need to create a configuration file for the deployment manager. To create a Kerberos configuration file, complete the following steps:
- If IBM Connections is not installed on the system that hosts the domain controller, copy the keytab file to the system where IBM Connections is installed.
- Open a command prompt on the system hosting the Deployment Manager and start the wsadmin client with the following parameters:
- AIX or Linux:
./wsadmin.sh -lang jacl -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
Windows:
wsadmin -lang jacl -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user account for the Administrator role for IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server Deployment Manager. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter.
- Enter the following command as one line in the wsadmin client:
$AdminTask createKrbConfigFile
{
-krbPath appserver\java\jre\lib\security\krb5.conf
-realm REALM
-kdcHost kdc_hostname
-dns dns_hostname
-keytabPath path_to_keytab
}
using the following variables:
- appserver
- The path to the WebSphere Application Server root directory. Do not specify the path to the IBM Connections application. The krbPath parameter defines where the resulting krb5.conf configuration file is stored.
- REALM
- The Kerberos realm. Enter the name of the realm in uppercase letters.
- kdc_hostname
- The name of the Active Directory key distribution center host. This name is typically the domain controller server.
- dns_hostname
- The DNS server name of the domain controller server.
- path_to_keytab
- The file path to the directory in which the keytab file is stored.
Use the following sample configuration file to format your entry:
C:\IBM\WebSphere\AppServer\java\jre\lib\security\krb5.conf [libdefaults] default_realm = EXAMPLE.COM default_keytab_name = FILE:C:\finance1.keytab default_tkt_enctypes = des-cbc-md5 rc4-hmac default_tgs_enctypes = des-cbc-md5 rc4-hmac kdc_default_options = 0x54800000 # forwardable = true # proxiable = true # noaddresses = true [realms] EXAMPLE.COM = { kdc = finance1.us.example.com:88 default_domain = finance1.us.example.com } [domain_realm] .finance1.us.example.com = EXAMPLE.COM
- Copy the merged keytab file and the new krb5.conf file to the same location on each node.
For more information, go to the Creating a Kerberos configuration file topic in the IBM WebSphere Application Server 7 information center.
Create a redirect page for users without SPNEGO support
Create an HTML page to redirect users whose web browsers do not support SPNEGO. If users navigate to a SPNEGO-protected webpage but their browsers do not support SPNEGO, redirect them to an HTML page that is not protected by SPNEGO.
To create an HTML page to redirect users :
- Create an HTML page with HTML such as that shown in the following example:
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN"> <META HTTP-EQUIV="Content-Type" CONTENT="text/html"> <!-- Notes: - This file should be served from an unprotected website. Alternatively, it can be loaded from the WebSphere Application Server file system. - Any imbedded graphics/javascript/css must be loaded from an unprotected website. - This file is loaded after WebSphere Application Server is initialized. If changes to this file are necessary, restart WebSphere Application Server. - This file is returned whenever the SPNEGO TAI receives an NTLM token for any application in the cell. In other words, this file is generic for all applications. However, by using the document.location Javascipt , we can get the original URL, and redirect to that original URL with the "?noSPNEGO" text added - thus forcing the standard application userid/password challenge. --> <html> <script language="javascript"> var origUrl=""+document.location; if (origUrl.indexOf("noSPNEGO")<0) { if (origUrl.indexOf('?')>=0) origUrl+="&noSPNEGO"; else origUrl+="?noSPNEGO"; } function redirTimer() { self.setTimeout("self.location.href=origUrl;",0); } </script> <META HTTP-EQUIV = "Pragma" CONTENT="no-cache"> <script language="javascript"> document.write("<title> Redirect to "+origUrl+ " </title>"); </script> <head> </head> <body onLoad="redirTimer()"/> </html>
- Save the file as, for example, NoSpnegoRedirect.html on a publicly-accessible directory on your webserver. For example, IHS_server/htdocs/NoSpnegoRedirect.html.
Configure SPNEGO on WebSphere Application Server
Configure SPNEGO on IBM WebSphere Application Server V7.0.
The connectionsAdmin J2C alias specified during installation must correspond to a valid account that can authenticate with Active Directory. The alias must map to an administrative user account that can authenticate for single sign-on with Active Directory. If you update the user ID or credentials for this alias, complete the steps in the Changing references to administrative credentials topic.
Your WebSphere Application Server administrative account must be a valid account that can authenticate with Active Directory. User accounts that are specified only in the WebSphere Internal File Repository cannot check out configuration documents. Nor can such accounts connect to any of the LC MBeans to run commands.
Tip:For information about best practices for Service Principal Names and SPNEGO configuration, go to Tips on using Kerberos service principal names. The topic also provides tips for multitier environments. For more information about setting up SPNEGO web authentication for WebSphere Application Server, go to WebSphere with a side of SPNEGO. To configure SPNEGO on WebSphere Application Server:
- Log on to the WebSphere Application Server Integrated Solutions Console on the Deployment Manager and select Security > Global Security.
- In the Authentication area, click Kerberos configuration and then enter the following details
- Kerberos service name
- HTTP
- Kerberos configuration file
- Full path to your Kerberos configuration file
- Kerberos keytab file name
- Full path to your keytab file
- Kerberos realm name
- Name of your Kerberos realm
- Select Trim Kerberos realm from principal name if it is not already selected.
- Select Enable delegation of Kerberos credentials if it is not already selected.
- Click OK and then click Save.
- Click Kerberos configuration and in the Related Configuration area, click SPNEGO Web authentication.
SPNEGO Web authentication and Kerberos authentication use the same Kerberos client configuration and keytab files.
- Set the SPNEGO filter:
- In the SPNEGO Filters area, click New and enter the following details:
- Host name
- Enter the host name of the deployment manager
- Kerberos realm name
- Enter your Kerberos realm name
- Filter criteria
- request-url!=noSPNEGO;request-url!=/mobile;request-url!=/nav;request-url!=/bundles/js;request-url!=/static;request-url!=/activities/oauth;request-url!=/blogs/oauth;request-url!=/dogear/oauth;request-url!=/communities/calendar/oauth;request-url!=/communities/service/atom/oauth;request-url!=/communities/service/opensocial/oauth/;request-url!=/communities/recomm/oauth;request-url!=/connections/opensocial/oauth;request-url!=/connections/opensocial/anonymous/rest;request-url!=/connections/opensocial/common;request-url!=/connections/opensocial/gadgets;request-url!=/connections/opensocial/ic;request-url!=/connections/opensocial/rpc;request-url!=/connections/opensocial/social;request-url!=/connections/opensocial/xrds;request-url!=/connections/opensocial/xpc;request-url!=/connections/resources/web;request-url!=/connections/resources/ic;request-url!=/files/oauth;request-url!=/forums/oauth;request-url!=/homepage/oauth;request-url!=/metrics/service/oauth;request-url!=/moderation/oauth;request-url!=/news/oauth;request-url!=/news/follow/oauth;request-url!=/profiles/oauth;request-url!=/wikis/oauth;request-url!=/search/oauth;request-url!=/connections/core/oauth/;request-url!=/resources;request-url!=/oauth2/endpoint/
Ensure that you separate each filter with a semicolon (;). No other character is allowed as a separator.
- Filter class
- Leave this field blank to allow the system to use the default filter class (com.ibm.ws.security.spnego.HTTPHeaderFilter).
- SPNEGO not supported error page URL
- Enter the URL to the redirect page that you created. For example: http://webserver/NoSpnegoRedirect.html.
where webserver is the name of your IBM HTTP Server instance and NoSpnegoRedirect.html is the name of the redirect page.
- NTLM token received error page URL
- Enter the URL to the redirect page that you created. For example: http://webserver/NoSpnegoRedirect.html.
- Select Trim Kerberos realm from principal name.
- Select Enable delegation of Kerberos credentials.
- Click OK and then click Save.
- On the SPNEGO Web authentication page, complete the following steps:
- Select Dynamically update SPNEGO.
- Select Enable SPNEGO.
- Select Allow fall back to application authentication mechanism.
- Enter the path to the Kerberos configuration file in the Kerberos configuration file with full path field. You created this file in the Creating a service principal name and keytab file topic.
- Enter the path to the Kerberos keytab file in the Kerberos keytab file name with full path field. You created this file in the Creating a service principal name and keytab file topic.
- Click Apply.
- Set the level of authentication that users must go through to access your IBM Connections deployment. In the following choices, you can force users to always authenticate or allow users to access Blogs, Bookmarks, Communities, Files, Profiles, and Wikis anonymously. These anonymous users must log in only if they try to access a private area. For more information about forcing authentication, see the Forcing users to log in before they can access an application topic.
- (default) Allow anonymous access to IBM Connections:
- Select Applications > Application Types > WebSphere enterprise applications.
- Click the link to the first IBM Connections application in the Enterprise Applications table.
- In the Detail Properties area, click Security role to user/group mapping.
- Select the reader Role, click Map Special Subjects, and select Everyone.
- Click OK and then click Save.
- Repeat steps b-e for the remaining IBM Connections applications in the Enterprise Applications table.
- Force users to log in to access IBM Connections:
- Select Applications > Application Types > WebSphere enterprise applications.
- Click the link to the first IBM Connections application in the Enterprise Applications table.
- In the Detail Properties area, click Security role to user/group mapping.
- Select the reader Role, then click Map Special Subjects and select All Authenticated in Application's Realm.
- Click OK and then click Save.
- Repeat steps b-e for the remaining IBM Connections applications in the Enterprise Applications table.
- Remove interceptor classes:
- Select Security > Global Security.
- Expand Web and SIP security and click Trust association > Interceptors.
- Select the check boxes for the following two classes:
- com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl
- com.ibm.ws.security.TAMTrustAssociationInterceptorPlus
- Click Delete and then click Save.
- Disable TAI authentication:
If you are configuring Tivoli Access Manager with SPNEGO, or SiteMinder with SPNEGO. Those configurations require the default value of true for this parameter.
- Select Security > Global Security > Custom properties > New.
- Enter the following name and value pair:
- Name
- com.ibm.websphere.security.performTAIForUnprotectedURI
- Value
- false
- Click OK and then click Save.
- Click Global Security. In the Authentication area, click LTPA if it is not already selected. Click Save.
- Synchronize all the nodes in your deployment.
- Stop and restart WebSphere Application Server:
- Stop all instances of WebSphere Application Server that host your IBM Connections applications.
- Stop all node agents.
- Restart the Deployment Manager.
- Restart all the node agents.
- Restart all instances of WebSphere Application Server.
Configure web browsers to support SPNEGO
Configure your web browser to support SPNEGO authentication. Add IBM Connections and IBM HTTP Server to the list of sites that are permitted to engage in SPNEGO authentication with the browser.
To edit your web browser preferences, complete the following steps:
Do one of the following:
- Microsoft Internet Explorer:
- From the Internet Explorer menu, select Tools > Internet Options and then click the Security tab.
- Click the Local intranet icon and then click Sites.
- Click Advanced and then add the web address of the host name of your IBM Connections server into the Add this website to the zone field. For example: *.enterprise.example.com. Click Add.
- Enter the host name of your IBM HTTP Server into the Add this website to the zone field and click Add. For example: http://<IHS_host> or https://IHS_host>".
- Click OK to save the change and return to the main Security page.
- Click Custom level, scroll to find User Authentication > Logon, and select Automatic logon only in Intranet zone. Click OK to save the change and return to the main Security page.
- Click the Advanced tab, scroll to find Security, and then select the Enable Integrated Windows Authentication check box. Click OK to save the change.
- Restart the web browser to apply the configuration changes.
- Mozilla Firefox:
- Open Firefox and type about:config into the location bar.
- Type network.n into the Filter field and double-click network.negotiate-auth.trusted-uris.
- Enter the address of the server that hosts IBM Connections. For example: http://enterprise.example.com or https://enterprise.example.com if you want to use HTTPS. Enter a comma and then enter the address of your IBM HTTP Server .
- Click OK to save the change.
- If the deployed SPNEGO solution is using the advanced Kerberos application of Credential Delegation, double-click network.negotiate-auth.delegation-uris. This preference defines the sites for which the browser can delegate user authorization to the server. Enter a comma-delimited list of trusted domains or URLs.
- Restart Firefox to apply the configuration change.
Enable single sign-on for Tivoli Access Manager with SPNEGO
Configure IBM Connections to use single sign-on with IBM Tivoli Access Manager and SPNEGO.
- Complete the task described in the Configuring web browsers to support SPNEGO topic.
- Ensure that IBM Tivoli Access Manager for e-business, version 6.1 Fix Pack 4, is installed.
- This task describes how to enable single sign-on (SSO) for Tivoli Access Manager on the Windows operating system. For information about other operating systems, go to the Configure Windows desktop single signon (UNIX) page in the Tivoli Access Manager 6.1 information center.
- IBM Connections supports the WebSphere cookie-based lightweight third-party authentication (LTPA) mechanism as an SSO solution for Tivoli Access Manager. IBM Connections does not support other SSO solutions that WebSEAL supports such as WebSphere Trust Association Interceptor (TAI), Forms SSO, Cross-domain SSO, or E-community SSO.
- IBM Connections supports the use of SSL Transparent Path junctions with Tivoli Access Manager. IBM Connections does not support TCP type junctions or Tivoli Access Manager Standard junctions.
- Verify that you can access IBM Connections applications from a web browser.
- Set the IBM WebSphere Application Server single sign-on domain to the same value as the domain of the Tivoli Access Manager server.
Single sign-on (SSO) enables users to log in to an IBM Connections application and switch to other applications within the product without having to authenticate again.
There are several different ways to configure SSO. The IBM Connections DefaultAuthenticator protocol allows your users and Tivoli Access Manager to prove their identities to one another in a secure manner. After users sign in to their Active Directory Windows client systems, they are automatically signed into both Tivoli Access Manager and IBM Connections.
To set up SSO using Tivoli Access Manager with SPNEGO, complete the following steps:
- Create a user account for WebSEAL in your Active Directory domain. When creating the user account, ensure that you specify the following options:
- The user cannot change the password
- The password never expires
For example, if you create an account for A User, where the Active Directory domain is tamspnego.example.com, the user identity is auser@tamspnego.example.com.
- Map a Kerberos principal to an Active Directory user. Map the service principal name to the account that you created in Step 1 by running the ktpass command on the domain controller. Use the Tivoli Access Manager server through which users access IBM Connections as the instance in the service principal name.
- Run the following ktpass command:
ktpass .princ SPN -mapuser account_name -mapOp set .pass account_password
where
- SPN is the Kerberos service principal name. The host name specified in the SPN should match the host name of the WebSEAL server. For example, if users contact the WebSEAL server at diamond.subnet2.example.com and the WebSEAL server is part of the EXAMPLE.COM Active Directory domain, the Kerberos principal name is HTTP/diamond.subnet2.example.com@EXAMPLE.COM.
- account_name is the account name specified in Step 1.
- account_password is the password associated with the account specified in Step 1.
- Modify the Windows service for the WebSEAL instance so that it starts using the new user account that you just created. On the WebSEAL server, complete the following steps:
- Click Start > Programs > Administrative Tools > Services.
- Right-click on Access Manager WebSEAL-default and select Properties.
- Click Log On and then click This account.
- Enter the details of the user account and password that you created in Step 1.
- Click OK to save your changes.
- Grant administrator privileges for the local system to the account that you created in step 1.
- Enable SPNEGO for WebSEAL:
- Stop the WebSEAL server.
- Enable SPNEGO over SSL by adding the following lines to the WebSEAL configuration file:
[spnego]
spnego-auth = https
[authentication-mechanisms]
kerberosv5 = fully_qualified_path to the authentication library
For example: kerberosv5 = TDI_root\bin\stliauthn.dll
where TDI_root is the installation directory of Tivoli Access Manager.
- Restart WebSEAL from the Services Control Panel. On Windows, WebSEAL must be running as a service for SPNEGO authentication to work properly. Otherwise, it runs using the credentials of the logged in user.
- Configure form-based authentication with transparent junctions. Complete all the steps in the Enabling single sign-on for Tivoli Access Manager topic except the steps about updating interService URLs , adding a Tivoli Allow access to the Embedded Experience gadget, and adding a Tivoli Access Manager authenticator property. You need to use the IBM HTTP Server URLs and the DefaultAuthenticator property in this configuration.
This procedure enables a fallback authentication method for user systems that do not support SPNEGO. This alternative is important for users of Lotus Notes, mobile devices, and other extensions for IBM Connections.
Results
After users sign in to the Windows desktop, they are automatically signed into IBM Connections.
If you are using on-ramp plug-ins or mobile services, your data traffic is not authenticated by Kerberos tickets or SPNEGO tokens. It is instead authenticated through J2EE form-based authentication.
What to do next
For more information about Kerberos and SPNEGO, go to the SPNEGO protocol and Kerberos authentication page in the Tivoli Access Manager 6.1 information center.
Enable single sign-on for SiteMinder with SPNEGO
Configure IBM Connections to use single sign-on with Computer Associates' SiteMinder and SPNEGO.
Before you can enable SSO, you must first install IBM Connections and ensure that you can access the installed applications from a web browser. You must also have completed the TAI/ASA installation and configuration instructions that are included with SiteMinder, including registering the TAI/ASA with WebSphere Application Server.
- Complete the task described in the Configuring web browsers to support SPNEGO topic.
- Verify that you can access IBM Connections applications from a web browser.
Notes:
Each href attribute in LotusConnections-config.xml is case-sensitive and must specify a fully-qualified domain name.
- The connectionsAdmin J2C alias specified during installation must correspond to a valid account that can authenticate with SiteMinder. It may map to a back-end administrative user account. This account must be capable of authenticating for single sign-on against SiteMinder. If you need to update the user ID or credentials for this alias, see the Changing references to administrative credentials topic.
- WebSphere Application Server 7 does not provide the key Java libraries required to install and configure SiteMinder Application Server Agents (ASA) for WebSphere with WebSphere Application Server. The procedure to update your files is described in Step 1 of this task.
- For more information about the SiteMinder Policy Server and Web Agent configuration, go to the CA SiteMinder BookShelf.
- For more information about the SiteMinder Agent for WebSphere, see the CA SiteMinder Agent for WebSphere guide (PDF) and the CA eTrust SiteMinder Agent for IBM WebSphere Release Notes (PDF).
This task describes how to create SiteMinder Agent and Domain objects with realms, rules, and a policy related to IBM HTTP Server, Microsoft Internet Information Services (IIS), and WebSphere Application Server.
When a user requests a page that is protected by SiteMinder, the Web Agent on the HTTP server intercepts the request and prompts the user for authentication. The user is redirected to a Microsoft IIS server which is configured for SPNEGO authentication. If the user provides valid credentials, the user is authenticated by SPNEGO and a SiteMinder agent on the IIS server generates an SMSESSION cookie. This cookie is added to the request which is passed on to WebSphere Application Server. The SiteMinder Trust Association Interceptor (TAI) on the application server verifies the information in the cookie and sets the User Principal that IBM Connections requires to identify the user.
This task refers to a configuration that uses SiteMinder Policy Server 6.0 SP5, SiteMinder ASA 6.0 Agent for WebSphere Application Server (with CR00010 hotfix), and SiteMinder Web Agent v6qmr5-cr035.
To set up SSO using SiteMinder with SPNEGO:
- Download and apply the Unrestricted JCE policy files:
- Go to the J2SE 5 SDK Security information web page.
- Authenticate with your universal IBM user ID and password.
- Download the Unrestricted JCE Policy files for SDK for all newer versions package.
- Extract the files from the downloaded package.
- Back up your existing copies (if any) of the US_export_policy.jar and local_policy.jar files, located in the app_server_root/java/jre/lib/security directory.
- Copy the new jar files from the extracted package to the same directory, overwriting any existing files.
- Create agents on the SiteMinder Policy Server, including Web Agents for IBM HTTP Server and Microsoft IIS, and an Application Server Agent for WebSphere Application Server.
- Open the SiteMinder Administration console.
- Right-click Agents and select Create Agent.
- Enter details of the Name and Description of the Web Agent for IBM HTTP Server.
- Repeat these steps for the Web Agent for IIS.
- Repeat these steps for the Application Server Agent.
- Create Agent Configuration Objects on the SiteMinder Policy Server. In the SiteMinder Administration Console, open the Agent Conf Objects pane and complete the following steps:
- Configure the Web Agent for IBM HTTP Server:
- Right-click Apache Default Sets Agent and select Duplicate Configuration Object.
- Enter the Name and description of the Agent Configuration Object.
- Update the following parameters to match your environment:
- DefaultAgentName
- Name of the Apache Agent created earlier
- CookieDomain
- your_domain
where your_domain is your IBM Connections domain. If, for example, the URL is http://activities.example.com/activities, your host name is activities.example.com and your domain is example.com. In this example, you would set CookieDomain=example.com. .
- RequireCookies
- NO
This parameter configures the Web Agent to support basic authentication but without requiring all API client programs to support cookies.
- BadCSSChars
- <,>
This parameter enables the Invite colleagues functionality in Profiles.
- LogOffUri
- URI
Configure SiteMinder to recognize only one web address as the logout web address. Uncomment one of the following URIs by removing the number sign (#) character:
#LogOffUri="/activities/service/html/ibm_security_logout"
#LogOffUri="/blogs/ibm_security_logout"
#LogOffUri="/communities/communities/ibm_security_logout"
#LogOffUri="/dogear/ibm_security_logout"
#LogOffUri="/files/ibm_security_logout"
#LogOffUri="/forums/ibm_security_logout"
#LogOffUri="/homepage/web/ibm_security_logout"
#LogOffUri="/moderation/ibm_security_logout"
#LogOffUri="/news/ibm_security_logout"
#LogOffUri="/profiles/ibm_security_logout"
#LogOffUri="/search/ibm_security_logout"
#LogOffUri="/wikis/ibm_security_logout"
- Under the System tab, update the Agent Configuration Object with the following value: FCCCompatMode - NO
- Configure the Web Agent for IIS:
- Right-click IIS Default Sets Agent and select Duplicate Configuration Object.
- Enter the Name and description of the Agent Configuration Object.
- Update the following parameters to match your environment:
- DefaultAgentName
- Name of the Apache Agent created earlier
- CookieDomain
- your_domain
where your_domain is your IBM Connections domain. If, for example, the URL is http://activities.example.com/activities, your host name is activities.example.com and your domain is example.com. In this example, you would set CookieDomain=example.com. .
- RequireCookies
- NO
This parameter configures the Web Agent to support basic authentication but without requiring all API client programs to support cookies.
- BadCSSChars
- <,>
This parameter enables the Invite colleagues functionality in Profiles.
- Configure the Application Server Agent:
- Right-click Apache Default Sets Agent and select Duplicate Configuration Object.
- Enter the Name and description of the Agent Configuration Object.
- Update the following parameters to match your environment:
- DefaultAgentName
- Name of the Apache Agent created earlier
- CookieDomain
- your_domain
where your_domain is your IBM Connections domain. If, for example, the URL is http://activities.example.com/activities, your host name is activities.example.com and your domain is example.com. In this example, you would set CookieDomain=example.com.
- AssertionAuthResource
- /siteminderassertion
- AssertbyUserID
- True
Notes:
- When activated, the LogOffUri parameter clears the SMSESSION cookie and ensures that the user is logged out of all IBM Connections browser sessions.
- To add parameters, edit the Agent Configuration Object on the SiteMinder Policy Server. Alternatively, you can edit the LocalConfig.conf file on the HTTP server if the Web Agent is configured to use it.
- If you are editing the SiteMinder configuration file directly, you must surround the values of SiteMinder configuration parameters with quotation marks ("); for example: BadCSSChars="<,>". If you are changing these parameters within the SiteMinder Policy Server, do not use quotation marks.
- Specify your SiteMinder Authentication Scheme configuration:
- Open the SiteMinder Administration Console and navigate to the Authentication Scheme Properties dialog box.
- From the Authentication Scheme type list, select Windows Authentication template.
- Clear the Use Relative Target check box.
- Enter the URL of your IIS server in the web Server Name field.
- Complete the User DN Lookup field with the appropriate information for your domain. For example, (sAMAccountName=%{UID}).
- On the SiteMinder Policy Server, create a domain for the IBM HTTP Server web agent.
- Create protected realms under the IBM HTTP Server Web Agent domain:
- Use the IBM HTTP Server Agent Object and Windows Authentication Scheme that you created earlier, create SiteMinder realms that are protected by Windows forms authentication.
Table 82. Realms that require forms authentication
Application Protected URL resource ConnectionsDefaultRealm / Activities /activities/follow/atomfba /activities/service/atom2/forms /activities/service/atom2/communityEvent /activities/service/download/forms /activities/service/getnonce/forms Blogs /blogs/api_form /blogs/atom_form /blogs/follow/atomfba /blogs/roller-ui/blog /blogs/roller-ui/feed_form /blogs/roller-ui/rendering/api_form /blogs/roller-ui/rendering/feed_form /blogs/services/atom_form Bookmarks /dogear/atom_fba Common resources /connections/opensocial/rest Communities /communities/calendar/atom_form /communities/follow/atomfba /communities/forum/service/atom/forms /communities/recomm/ajax /communities/recomm/atom_form /communities/service/atom/forms Files /files/follow/atomfba /files/form/cmis/repository Forums /forums/atom/forms /forums/follow/atomfba Metrics /metrics /cognos Profiles /profiles/atom/forms /profiles/atom2/forms /profiles/follow/atomfba Wikis /wikis/follow/atomfba
- Use the IBM HTTP Server Agent Object that you created earlier, create SiteMinder realms that are protected by basic authentication.
Table 83. Realms that require basic authentication
Application Protected URL resource Activities /activities/follow/atom /activities/service/download /activities/service/html/autocompleteactivityname /activities/service/html/autocompleteentryname /activities/service/html/autocompletemembers /activities/service/atom /activities/service/getnonce Blogs /blogs/api /blogs/atom /blogs/follow/atom /blogs/issuecategories /blogs/roller-ui/BlogsWidgetEventHandler.do /blogs/roller-ui/feed /blogs/roller-ui/rendering/api /blogs/roller-ui/rendering/feed /blogs/services/atom Bookmarks /dogear/api/app /dogear/api/deleted /dogear/api/notify /dogear/atom Common resources /connections/opensocial/basic/rest Communities /communities/calendar/atom /communities/calendar/handleEvent /communities/calendar/ical /communities/follow/atom /communities/forum/service/atom /communities/recomm/atom /communities/recomm/handleEvent /communities/service/atom /communities/service/json Files /files/basic/api /files/basic/cmis /files/basic/opensocial /files/follow/atom Forums /forums/atom /forums/follow/atom Home page /homepage/atom/search /homepage/atom/mysearch News /news/atom/service /news/atom/stories/newsfeed /news/atom/stories/public /news/atom/stories/saved /news/atom/stories/statusupdates /news/atom/stories/top /news/atom/watchlist /news/atomfba/stories/public Profiles /profiles/atom /profiles/atom2 /profiles/audio.do /profiles/follow/atom /profiles/json /profiles/photo.do /profiles/vcard Wikis /wikis/basic/api /wikis/follow/atom
- Optional: Protect login credentials with encryption: Using the Basic over SSL Template scheme, create a SiteMinder Authentication Scheme and apply the new Authentication Scheme to all the SiteMinder realms that require basic authentication.
- Create Delete and Head actions for the Web Agent. By default, the Web Agent has only the Get, Post, and Put actions available. To add the Delete and Head actions:
- In the SiteMinder Administration Console, click View and select Agent Types.
- Select Agent Types in the Systems pane.
- Double-click Web Agent in the Agent Type list.
- In the Agent Type Properties dialog box, click Create.
- Enter Delete in the New Agent Action dialog box and click OK.
- Enter Head in the New Agent Action dialog box and click OK.
- Click OK again to save the new action.
- Create the following rules for each realm:
Table 84. Rules for the IBM HTTP Server realms
GetPostPutDelHead rule OnAuthAccept rule Realm: CurrentRealm Realm: CurrentRealm Resource: * (not /*) Resource: * (not /*) Action: Web Agent actions -> Get,Post,Put,Delete,Head Action: Authentication events -> OnAuthAccept When this Rule fires: Allow Access When this Rule fires: Allow Access Enable or Disable this Rule: Enabled Enable or Disable this Rule: Enabled
- Create a policy and add the users who will be able to access the server to the policy. You can allow all users in the LDAP directory or a subset of users; for example: an LDAP branch, individual users, or groups of users.
- Add the new rules to the new policy.
- Specify realms that are not protected by SiteMinder.
You must configure notification templates and some Atom feeds as unprotected URLs. The Blogs footer page must also be unprotected because Blogs uses the Velocity template to extract footer pages.
Table 85. Realms that do not require authentication
Application Unprotected URL resource Activities /activities/auth /activities/images /activities/oauth /activities/service/html/images /activities/service/html/mainpage /activities/service/html/styles /activities/service/html/themes /activities/service/html/servermetrics /activities/service/html/serverstats /activities/serviceconfigs /activities/static/ Blogs /blogs/oauth /blogs/serviceconfigs /blogs/static/ Bookmarks /dogear/oauth /dogear/peoplelike /dogear/serviceconfigs /dogear/static/ Common resources /connections/bookmarklet/tools/blet.js /connections/bookmarklet/tools/discussThis.js /connections/bookmarklet/tools/rlet.js /connections/core/oauth /connections/oauth /connections/resources/ic /connections/resources/socmail-client /connections/resources/socpim /connections/resources/web /nav/common Communities /communities/calendar/Calendar.xml /communities/calendar/oauth /communities/comm.widget /communities/images /communities/nav /communities/recomm/oauth /communities/resourceStrings.do /communities/service/atom/oauth /communities/service/html/communityview /communities/service/html/community/autoCompleteMembers.do /communities/service/html/singleas /communities/service/opensocial/oauth /communities/serviceconfigs /communities/static/ /communities/stylesheet /communities/tools/embedAS.html /communities/widgets Files /files/app /files/basic/anonymous/api /files/basic/anonymous/cmis /files/basic/anonymous/opensocial /files/form/anonymous/api /files/form/anonymous/cmis /files/form/anonymous/opensocial /files/oauth /files/static/ Forums /forums/oauth /forums/serviceconfigs /forums/static/ Home page /homepage/oauth /homepage/search /homepage/serviceconfigs /homepage/static/ /homepage/web/updates/ Metrics /metrics/service/eventTracker /metrics/service/oauth /cognos/servlet Moderation /moderation/app /moderation/oauth /moderation/static News /help /news/microblogging/isPermitted.action /news/follow/oauth /news/oauth /news/serviceconfigs /news/sharebox/config.action /news/static/ OAuth Provider /oauth2 Profiles /profiles/atom/forms/connections.do /profiles/images /profiles/oauth /profiles/serviceconfigs /profiles/static/ Search /search/atom/search /search/oauth /search/static/ Widget container /connections/opensocial/anonymous/rest /connections/opensocial/common /connections/opensocial/gadgets /connections/opensocial/ic /connections/opensocial/oauth /connections/opensocial/rpc /connections/opensocial/social /connections/opensocial/xrds /connections/opensocial/xpc Wikis /wikis/basic/anonymous/api /wikis/form/anonymous/api /wikis/home /wikis/js /wikis/oauth /wikis/static/
- On the SiteMinder Policy Server, create a domain for the Application Server Agent.
- Add the following realm to the new WebSphere Application Server domain:
Table 86. SiteMinder realms for WebSphere Application Server
Realm name Protected resource SM TAI Validation /siteminderasssertion You must configure the Protected Resource of this realm to match the AssertionAuthResource parameter that you configured earlier for the Application Server Agent.
- On the SiteMinder Policy Server, create a domain for the IIS Server Agent.
- Use the IIS Agent Object and Windows Authentication Scheme that you created earlier, create a SiteMinder realm that is protected by Windows authentication.
Table 87. SiteMinder realms that require Windows authentication
Realm name Protected resource IIS_Realm /
- Create the following rules for this realm:
Table 88. Rules for the IIS realm
GetPostPutDelHead rule OnAuthAccept rule Realm: CurrentRealm Realm: CurrentRealm Resource: * (not /*) Resource: * (not /*) Action: Web Agent actions -> Get,Post,Put,Delete,Head Action: Authentication events -> OnAuthAccept When this Rule fires: Allow Access When this Rule fires: Allow Access Enable or Disable this Rule: Enabled Enable or Disable this Rule: Enabled
- Set the timeout value of the session for each realm.
- In the SiteMinder Policy Server, open the Realm Dialog and click Session.
- In the Session Timeouts Group Box, enter timeouts for each realm. Enter the following values, if they are not already present:
- Maximum Timeout Enabled
- 2 Hours 0 Minutes
- Idle Timeout Enabled
- 1 Hours 0 Minutes
The maximum timeout and the idle timeout must be longer than the LTPA token timeout, which is defined in WebSphere Application Server. The LTPA token timeout is set to 120 minutes by default.
- Install the Web Agent on IBM HTTP Server:
- Download the latest version of the Web Agent from the CA website.
- Install the Web Agent. For instructions, go to the SiteMinder BookShelf.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
- Install the Web Agent on IIS:
- Download the latest version of the Web Agent from the CA website.
- Install the Web Agent. For instructions, go to the SiteMinder BookShelf.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
- Install the Application Server Agent on your WebSphere nodes:
- Download the latest version of the Application Server Agent from the CA website.
- Install the Application Server Agent on each node in your IBM Connections deployment. For instructions, see the SiteMinder Agent for WebSphere Agent Guide.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
- Copy the smagent.properties file from the ASA installation conf folder to the WebSphere Application Server profile properties folder; for example: C:\program files\IBM\websphere\appserver\appsvr01\properties.
If Cognos is enabled, also copy the smagent.properties file to the properties folder of the WebSphere Application Server profile that hosts Cognos.
- Configure Trust Association Interceptor on WebSphere Application Server.
- From the administrative console for WebSphere Application Server, click Security > Global security.
- Under Web and SIP security, click Trust association.
- Click Enable Trust Association and then click Save.
- Click Interceptors.
- Delete any unused interceptors.
Do not delete the OAuth interceptor.
- Click New and enter the following name for the new interceptor:
com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor
- Click OK and then click Save.
- Restart WebSphere Application Server.
- Create rewrite rules to remap Atom API requests. Open the IBM HTTP Server httpd.conf configuration file. The file is stored in the ibm_http_server_root/conf directory. Add the following rules to the file:
You must add these rules to both the HTTP and HTTPS sections of the file.
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]
Do not close the httpd.conf file until after the next step.
- Create rewrite rules that redirect URLs when users log out of IBM Connections. Add the following rules to the httpd.conf file:
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteCond %{QUERY_STRING} !=logoutExitPage=your_logout_url
RewriteRule /(.*)/ibm_security_logout(.*)
LogOffUri?logoutExitPage=your_logout_url [noescape,L,R]
where LogOffUri is the URL that you uncommented earlier. After logging out of IBM Connections, the user's browser is directed to your_logout_url. This URL could be your corporate home page or the SiteMinder login page.
You must add these rules to both the HTTP and HTTPS entries.
The following example illustrates a typical portion of the httpd.conf file after you have implemented this step:
RewriteEngine on RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*) RewriteCond %{QUERY_STRING} !=logoutExitPage=http://corphome.example.com RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://corphome.example.com [noescape,L,R] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L] #Connections Config for SSL LoadModule ibm_ssl_module modules/mod_ibm_ssl.so <IfModule mod_ibm_ssl.c> Listen 0.0.0.0:443 <VirtualHost *:443> ServerName connections.example.com SSLEnable RewriteEngine on RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*) RewriteCond %{QUERY_STRING} !=logoutExitPage=http://corphome.example.com RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://corphome.example.com [noescape,L,R] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/$1/tags/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/feed/$1/entries/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*) RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L] </VirtualHost> </IfModule> SSLDisableUncomment the LoadModule rewrite_module modules/mod_rewrite.so line in the httpd.conf file. This line is commented out by default. When the line is commented out, the web server will not start.
- Configure SiteMinder to use HTTP or HTTPS communications:
- Add the following lines to the end of the httpd.conf file:
- HTTP:
Listen 8888 <VirtualHost *:8888> ServerName connections.example.com </VirtualHost>
- HTTPS:
Listen 444 <VirtualHost *:444> ServerName connections.example.com SSLEnable Keyfile "/opt/IBM/KeyFiles/webserver-key.kdb" SSLStashFile "/opt/IBM/KeyFiles/webserver-key.sth" </VirtualHost>Save and close the file.
- Open the WebAgent.conf file, usually located in the ibm_http_server_root/conf directory, and uncomment the LocalConfig.conf location: localconfigfile="/opt/IBM/HTTPServer/conf/LocalConfig.conf". Save and close the file.
- Open the LocalConfig.conf file, usually located in the ibm_http_server_root/conf directory, and configure the IgnoreHost setting to ensure that SiteMinder ignores any traffic that goes through this virtual host.
HTTPS: IgnoreHost="connections.example.com:444"
HTTP:IgnoreHost="connections.example.com:8888"
- Comment out every other line in the LocalConfig.conf file. Save and close the file.
- Add the virtual host to WebSphere Application Server:
- In the Integrated Solutions Console on the Deployment Manager, click Environment > Virtual Hosts > default_host > Host Aliases > New.
- Enter the host name and port of the alias. For example: enter * and 444 for HTTPS, or * and 8888 for HTTP.
Verify that IBM HTTP Server copied the updated plugin-cfg.xml file to the ibm_http_server_root/Plugins/config/webserver1 directory. The timestamp on the file indicates when it was updated.
- Add the interservice URL for the new virtual host to LotusConnections-config.xml:
- Check out LotusConnections-config.xml. For information about editing configuration files, see the Changing common configuration property values topic.
- Add 444 or 8888 to each instance of interService URL. For example, change <sloc:interService href="http://connections.example.com"/> to <sloc:interService href="https://connections.example.com:444"/>
- Save and check in the file.
- Restart IBM HTTP Server, the Deployment Manager, and the nodes.
What to do next
Verify the configuration is working correctly:
- Log in to your Windows client system.
- Open Firefox or Internet Explorer and navigate to https://IHS_host/homepage. If you can log in without entering your credentials, then you have successfully configured single sign-on for SiteMinder with SPNEGO.
The customAuthenticator element for back-end inter-service communication
The customAuthenticator element in LotusConnections-config.xml defines some key parameters in your single sign-on (SSO) solution.
The configuration settings that you can specify in this XML element only affect back-end inter-service communication in an SSO environment.
The attributes for the customAuthenticator element can differ, depending on the SSO solution that you have implemented. Most attributes are optional, but some might be mandatory in the context of your SSO solution. For more information, see the relevant topics for your authentication solution.
Default attributes
The following default attributes for the customAuthenticator element are available when the customAuthenticator attribute is set to DefaultAuthenticator, TAMAuthenticator, or SiteMinderAuthenticator.
- customAuthenticator
- The customAuthenticator primary element has two attributes, name and classname. Either or both attributes must be set to an authenticator such as Default, TAM, or SiteMinder. This attribute is mandatory.
- AllowSelfSignedCerts
- Optional. Should be set to false in the production environment. For security and legal reasons, self-signed certificates should only be used in test environments. The default value is true.
- CookieTimeout
- This value should match the value in your security proxy or WebSphere Application Server. When the TAM authenticator is in use, this value should also match the TAM inactive-timeout setting. The default value is 60 minutes.
- ConnectionTimeout
- This value determines the time period after which a connection is dropped. The default value is 30 seconds.
- SoTimeout
- This default socket value defines the length of time to wait for data. The default value is 60 seconds.
- MaxTotalConnections
- The value defines the maximum number of connections allowed overall. The default value is 256 connections.
- DefaultMaxConnectionsPerHost
- Defines the maximum number of connections allowed per host. The default value is 128 connections.
Additional attributes for Tivoli Access Manager and SiteMinder
There are additional attributes available when the customAuthenticator attribute is set to TAMAuthenticator or SiteMinderAuthenticator.
- CustomLoginUsernameField
- This attribute key should be implicitly set to user. If you customize the username field in the login form, this setting allows a new field name to be configured for entering the username.
- CustomLoginPasswordField
- This attribute key should be implicitly set to PASSWORD. If you customize the password field in the login form, this setting allows a new field name to be configured for entering the user password.
- CustomLoginFormField
- This attribute key should be implicitly set to Form. If you customize the login form field in the login form, this setting allows a new field name to be configured for posting login information to this customized form.
- CustomLoginFormValue
- This attribute key should be implicitly set to Login. If you customize the login value field in the login form, this setting allows a new value for login form to be configured for posting login information to this customized form.
- FormBasedAuthLoginURL
- This is a dedicated login URL for form based authentication.
This extract from LotusConnections-config.xml shows attributes with sample values:
<customAuthenticator name="TAMAuthenticator" > <attribute key="AllowSelfSignedCerts" value="true" /> <attribute key="CookieTimeout" value="60" /> <attribute key="ConnectionTimeout" value="30" /> <attribute key="SoTimeout" value="60" /> <attribute key="MaxTotalConnections" value="256" /> <attribute key="DefaultMaxConnectionsPerHost" value="128" /> <attribute key="CustomLoginUsernameField" value="username" /> <attribute key="CustomLoginPasswordField" value="PASSWORD" /> <attribute key="CustomLoginFormField" value="login-form-type" /> <attribute key="CustomLoginFormValue" value="pwd" /> <attribute key="FormBasedAuthLoginURL" value = "https://myHost.example.com:myPort/mypkmslogin.form/" /> </customAuthenticator>Configure the AJAX proxy
By default, the IBM Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the IBM Connections applications. If you want to change the traffic that is allowed from non-IBM Connections services, you must explicitly configure it.
This task is not required. Only perform it if you want to display information from an external service within IBM Connections.
When configuring the AJAX proxy to allow your users access to trusted third-party web sites, ensure that those sites implement appropriate security controls. Configuring the proxy to mirror content from third-party servers may cause the proxy to mirror malicious content from those servers, so be sure to allow access to trusted sites only.
The proxy-config.tpl template file defines rules about which HTTP requests, headers, and cookies are allowed to be redirected to the IBM Connections applications. When an IBM Connections server is started, it reads information about the applications from LotusConnections-config.xml, and, based on the rules defined in the proxy-config.tpl template file, configures the proxy to be used by any web browsers or other servers that send requests to IBM Connections.
For example, if you want to allow one application, such as Home page, to proxy a widget, but not allow any of the other applications to proxy it, create an application-specific version of the proxy-config.tpl file and edit that. See Configuring the AJAX proxy for a specific application for more details. To configure the AJAX proxy, complete the following steps:
- Access the common AJAX proxy configuration template file:
- Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on
Windows:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\binYou must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
- Enter the following command to start the wsadmin client:
- AIX or Linux:
./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
- Microsoft
Windows:
wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.
- In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
For example:
- AIX or Linux:
./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879
- Microsoft
Windows:
wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879
- Access the configuration file:
execfile("connectionsConfig.py")
- Use the following command to check out the configuration file:
LCConfigService.checkOutProxyConfig("temp_directory", "cell_name")...where temp_directory is a temporary directory of your choice, and cell_name is the name of the cell where the IBM Connections application that uses the global proxy template file is located.
- From the temporary directory to which you checked out the configuration files, open the proxy-config.tpl file in a text editor.
- Make your edits. For example, you can do the following things:
- To explicitly refuse all traffic from a specific site, add a policy as follows:
<proxy:policy url="malicious.site.com" acf="none"> <proxy:actions/> <proxy:headers/> <proxy:cookies/> </proxy:policy>
- To allow a particular service on your network to display a custom widget, you can add the following policy entry to the file:
<proxy:policy url="http://my.network.com/widget/*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept.*</proxy:header> <proxy:header>Content.*</proxy:header> <proxy:header>Authorization.*</proxy:header> <proxy:header>If-.*</proxy:header> <proxy:header>Pragma</proxy:header> <proxy:header>Cache-Control</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> </proxy:cookies> </proxy:policy>
- If a service requires authentication, you can configure it to also allow basic authentication requests by adding a basic-auth-support="true" attribute to the <proxy:policy> element. For example:
<proxy:policy url="http://my.network.com/service/*" acf="none" basic-auth-support="true"> ... </proxy:policy>If this attribute is not added, when an unauthenticated request is sent to a service that requires authentication, the service does not display the basic authentication dialog, but returns an HTTP 403 status code instead.
- To allow a particular service to run on your network and to pass cookies for LTPA tokens to the applications:
<proxy:policy url="http://my.network.com/service/*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept.*</proxy:header> <proxy:header>Content.*</proxy:header> <proxy:header>Authorization.*</proxy:header> <proxy:header>If-.*</proxy:header> <proxy:header>Pragma</proxy:header> <proxy:header>Cache-Control</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> </proxy:cookies> </proxy:policy>Set the headers using regular expressions. If no cookies are specified, the proxy will pass all of them. To prevent it from passing any cookies, specify <proxy:cookies/>.
- The following policy allows GET requests to be passed to any web address. If you want to allow your users to have access to all web sites, remove the comments from around this policy. For example, users who add a feed to a community will see a 403 error where the feed results should be displayed unless you perform this step. Be sure that the policy is listed as the last policy in the configuration file.
<!--proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers/> <proxy:cookies/> </proxy:policy-->Do not enable this policy on internet-facing deployments because it can allow unauthorized access to internal servers.
- You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.
For example:
- circular_redirects
- Specifies that circular redirects are allowed. This property accepts a Boolean value of true or false specified in lower-case letters. If set to true, it supports using a proxy for a site that redirects to the same URL but with different parameters. Such a change is not recognized as a new URL. The default value of this property is true.
- connection-timeout
- Amount of time before an attempt to connect to a host times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- max_circular_redirects
- Maximum number of times a circular redirect is allowed before the proxy rejects it. Specified as an integer, the default value of this property is 100.
- maxconnectionsperhost
- Maximum number of simultaneous connections between the proxy and a given host. Specified as an integer, the default value of this property is 20.
- maxtotalconnections
- Maximum number of simultaneous connections between the proxy and all of the hosts together. Specified as an integer, the default value of this property is 50.
- socket-timeout
- Amount of time before an attempt to use a socket times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- unsigned_ssl_certificate_support
- Specifies that self-signed SSL certificates are supported. This property accepts a Boolean value of true or false specified in lower-case letters. The default value of this property is true. Change it to false when the system is ready for production.
<proxy:meta-data> <proxy:name>maxconnectionsperhost</proxy:name> <proxy:value>20</proxy:value> </proxy:meta-data>
- Save and close the file.
- Check the proxy-config.tpl file in during the same session in which you checked it out. Use the following command to check the file in:
LCConfigService.checkInProxyConfig("temp_directory", "cell_name")...where temp_directory is the temporary directory to which you checked out the configuration files, and cell_name is the name of the cell
...where the application that uses the common proxy-config.tpl file is located.
- Restart the application server hosting IBM Connections.
Configure the AJAX proxy for a specific application
The AJAX proxy configuration for all of the IBM Connections applications is defined in the proxy-config.tpl file. If you want to specify different AJAX proxy settings for a specific application only, you can do so by creating a new, application-specific version of the proxy-config.tpl template file.
This task is not required. Only perform it if you want to display information from an external service within IBM Connections. You can define a custom proxy configuration for the Activities, Communities, Home page, Profiles, and Search applications, but not the other IBM Connections applications. By default, the IBM Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the IBM Connections applications. If you want to change the traffic that is allowed from non-IBM Connections services, you must explicitly configure it
To configure the AJAX proxy for a specific application:
- Go to the directory on the WebSphere Application Server in which the configuration files are stored.
For example: C:\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\<cell_name>\LotusConnections-configFind the proxy-config.tpl file, and then make a copy of the file, naming it using the following syntax:
proxy-application_name-config.tpl...where application_name is the name of the application for which you want to create a custom proxy configuration. Valid entries for application_name are: activities, communities, homepage, profiles, or search.
Save the copy in the same directory:
C:\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\<cell_name>\LotusConnections-config
- Check out the copied configuration file .
- Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on
Windows:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\binYou must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
- Enter the following command to start the wsadmin client:
- AIX or Linux:
./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
- Microsoft
Windows:
wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.
- In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
For example:
- AIX or Linux:
./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879
- Microsoft
Windows:
wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879
- Access the configuration service files for the application to which you want to apply special proxy configuration rules using the following command:
execfile("py_file_name")...where py_file_name is one of the following, depending on the application to which you are applying the proxy configuration settings:
- Activities: activitiesAdmin.py
- Communities: communitiesAdmin.py
- Home page: homepageAdmin.py
- Profiles: profilesAdmin.py
- Search: searchAdmin.py
- Check out the configuration service for the application using one of the following commands:
- Activities:
ActivitiesConfigService.checkOutProxyConfig("temp_directory", "cell_name")
- Communities:
CommunitiesConfigService.checkOutProxyConfig("temp_directory", "cell_name")
- Home page:
HomepageCellConfig.checkOutProxyConfig("temp_directory", "cell_name")
- Profiles:
ProfilesConfigService.checkOutProxyConfig("<temp_directory>", "<cell_name>")
- Search:
SearchCellConfig.checkOutProxyConfig("temp_directory", "cell_name")...where
- temp_directory is the temporary working directory to which the configuration TPL and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are not using the Microsoft Windows operating system.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is required. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()
- Navigate to the temporary directory specified in the previous step, and then open the custom template file in a text editor.
- Make your edits. For example, you can do the following things:
- To explicitly refuse all traffic from a specific site, add a policy as follows:
<proxy:policy url="malicious.site.com" acf="none"> <proxy:actions/> <proxy:headers/> <proxy:cookies/> </proxy:policy>
- To allow a particular service on your network to display a custom widget, you can add the following policy entry to the file:
<proxy:policy url="http://my.network.com/widget/*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept.*</proxy:header> <proxy:header>Content.*</proxy:header> <proxy:header>Authorization.*</proxy:header> <proxy:header>If-.*</proxy:header> <proxy:header>Pragma</proxy:header> <proxy:header>Cache-Control</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> </proxy:cookies> </proxy:policy>
- If a service requires authentication, you can configure it to also allow basic authentication requests by adding a basic-auth-support="true" attribute to the <proxy:policy> element. For example:
<proxy:policy url="http://my.network.com/service/*" acf="none" basic-auth-support="true"> ... </proxy:policy>If this attribute is not added, when an unauthenticated request is sent to a service that requires authentication, the service does not display the basic authentication dialog, but returns an HTTP 403 status code instead.
- To allow a particular service to run on your network and to pass cookies for LTPA tokens to the applications:
<proxy:policy url="http://my.network.com/service/*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept.*</proxy:header> <proxy:header>Content.*</proxy:header> <proxy:header>Authorization.*</proxy:header> <proxy:header>If-.*</proxy:header> <proxy:header>Pragma</proxy:header> <proxy:header>Cache-Control</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> </proxy:cookies> </proxy:policy>Set the headers using regular expressions. If no cookies are specified, the proxy will pass all of them. To prevent it from passing any cookies, specify <proxy:cookies/>.
- The following policy allows GET requests to be passed to any web address. If you want to allow your users to have access to all web sites, remove the comments from around this policy. For example, users who add a feed to a community will see a 403 error where the feed results should be displayed unless you perform this step. Be sure that the policy is listed as the last policy in the configuration file.
<!--proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers/> <proxy:cookies/> </proxy:policy-->Do not enable this policy on internet-facing deployments because it can allow unauthorized access to internal servers.
- You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.
For example:
- circular_redirects
- Specifies that circular redirects are allowed. This property accepts a Boolean value of true or false specified in lower-case letters. If set to true, it supports using a proxy for a site that redirects to the same URL but with different parameters. Such a change is not recognized as a new URL. The default value of this property is true.
- connection-timeout
- Amount of time before an attempt to connect to a host times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- max_circular_redirects
- Maximum number of times a circular redirect is allowed before the proxy rejects it. Specified as an integer, the default value of this property is 100.
- maxconnectionsperhost
- Maximum number of simultaneous connections between the proxy and a given host. Specified as an integer, the default value of this property is 20.
- maxtotalconnections
- Maximum number of simultaneous connections between the proxy and all of the hosts together. Specified as an integer, the default value of this property is 50.
- socket-timeout
- Amount of time before an attempt to use a socket times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- unsigned_ssl_certificate_support
- Specifies that self-signed SSL certificates are supported. This property accepts a Boolean value of true or false specified in lower-case letters. The default value of this property is true. Change it to false when the system is ready for production.
<proxy:meta-data> <proxy:name>maxconnectionsperhost</proxy:name> <proxy:value>20</proxy:value> </proxy:meta-data>
- Save and close the file.
- Check in the file that you updated to the appropriate configuration service using one of the following commands:
- Activities:
ActivitiesConfigService.checkInProxyConfig("temp_directory", "cell_name")
- Blogs or Communities:
CommunitiesConfigService.checkInProxyConfig("temp_directory", "cell_name")
- Home page:
HomepageCellConfig.checkInProxyConfig("temp_directory", "cell_name")
- Profiles:
ProfilesConfigService.checkInProxyConfig("temp_directory", "cell_name")
- Search:
SearchCellConfig.checkInProxyConfig("temp_directory", "cell_name")...where temp_directory is the temporary directory to which you checked out and updated the proxy-application_name-config.tpl file, and cell_name is the name of the cell where the application that uses the proxy template file is located.
- Restart the WebSphere Application Server hosting IBM Connections.
What to do next
To make subsequent changes to the application-specific proxy template file, repeat steps 2 through 9 to check out the file, make your updates, and check the file back in again.
Enable the AJAX proxy to forward user credentials
Edit the proxy configuration template file to instruct the IBM Connections server to accept LTPA tokens. This task is necessary if you want to configure single sign-on between IBM Connections and the servers defined in the proxy configuration file.
- Open a command line window, start the wsadmin tool, and then do one of the following things:
- If you want all of the applications to pass LTPA tokens, access the common AJAX proxy configuration template file.
- Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on
Windows:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\binYou must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
- Enter the following command to start the wsadmin client:
- AIX or Linux:
./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
- Microsoft
Windows:
wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.
- In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
For example:
- AIX or Linux:
./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879
- Microsoft
Windows:
wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879
- If you want only a single application to be able to pass LTPA tokens, access the custom proxy configuration template file that you created for that application. See Configuring the AJAX proxy for information about how to create this file. To access the custom configuration template file, use the following command:
execfile("<$WAS_HOME>/profiles/<DMGR>/bin/ application_nameConfig.py")...where application_name is the name of the application for which you created a custom proxy configuration template file. For example:
- Activities: activitiesAdmin.py
- Communities: communitiesAdmin.py
- Home page: homepageAdmin.py
- Profiles: profilesAdmin.py
If you are prompted to specify which server to connect to, type 1. This information is not used by the wsadmin client when you are making configuration changes.
- Check out the proxy configuration template file using one of the following commands:
- If you want all of the applications to be able to pass LTPA tokens, use the following command to check out the proxy-config.tpl file.
LCConfigService.checkOutProxyConfig("<temp_directory>","<cell_name>")
- If you want only a single application to be able to pass LTPA tokens, use the following command:
application_nameConfigService.checkOutProxyConfig( "<temp_directory>","<cell_name>")...where application_name is the name of the application for which you created a custom proxy configuration template file. For example:
- Activities:
ActivitiesConfigService.checkOutProxyConfig("temp_directory", "cell_name")
- Communities:
CommunitiesConfigService.checkOutProxyConfig("temp_directory", "cell_name")
- Home page:
HomepageCellConfig.checkOutProxyConfig("temp_directory", "cell_name")
- Profiles:
ProfilesConfigService.checkOutProxyConfig("temp_directory", "cell_name")
- From the temporary directory to which you checked out the files, open the proxy configuration template file in a text editor.
- Include the following declarations in the proxy:policy block of the service to allow cookies for LTPA tokens to be passed to the applications:
<proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> </proxy:cookies>
- Save and close the file.
- Check in the proxy configuration template file during the same session in which you checked it out. To do so, complete the following steps:
- If you edited the proxy-config.tpl file, use the following command to check it back in:
LCConfigService.checkInProxyConfig("temp_directory", "cell_name")...where temp_directory is the temporary directory to which you checked out the configuration files, and cell_name is the name of the cell
...where the application that uses the common proxy-config.tpl file is located.
- If you made configuration changes for a specific application, check that custom template file back in using one of the following commands:
- Activities:
ActivitiesConfigService.checkInProxyConfig("temp_directory", "cell_name")
- Communities:
CommunitiesConfigService.checkInProxyConfig("temp_directory", "cell_name")
- Home page:
HomepageCellConfig.checkInProxyConfig("temp_directory", "cell_name")
- Profiles:
ProfilesConfigService.checkInProxyConfig("temp_directory", "cell_name")where temp_directory is the temporary directory to which you checked out the configuration files, and cell_name is the name of the cell where the application that uses the proxy template file is located.
- Restart the application server hosting IBM Connections.
Configure the AJAX proxy to work with a pass-through proxy
If your organization has a pass-through proxy required for Internet access, configure the AJAX proxy to send requests to it. Otherwise, your connections to the Internet will not work. The AJAX proxy supports Basic authentication.
If the AJAX proxy needs to go through a border firewall before accessing the network, configure the AJAX proxy configuration file to connect to a pass-through proxy before accessing the network.
The AJAX proxy configuration file is stored in the LotusConnections-config directory. A common proxy configuration file, proxy-config.tpl, is shared by all the applications. To configure the AJAX proxy to work with a pass-through proxy:
- To access the common AJAX proxy configuration template file:
- Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on
Windows:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\binYou must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
- Enter the following command to start the wsadmin client:
- AIX or Linux:
./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port
- Microsoft
Windows:
wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Portwhere:
- admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
- admin_password is the password of the WebSphere Application Server administrator.
- SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.
- In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
For example:
- AIX or Linux:
./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879
- Microsoft
Windows:
wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879
- Access the configuration file:
execfile("connectionsConfig.py")
- Use the following command to check out the configuration file:
LCConfigService.checkOutProxyConfig("temp_directory", "cell_name")
...where temp_directory is a temporary directory of your choice, and cell_name is the name of the cell where the IBM Connections application that uses the global proxy template file is located.
- From the temporary directory to which you checked out the configuration files, open the proxy-config.tpl file in a text editor.
- Add a <proxy:meta-data> element containing each of the following parameters:
- passthru_host
- The address at which the proxy is listening. In most cases, accessing the host and port from a browser causes an authentication request popup to be displayed. Required.
- passthru_password
- Password that corresponds with the passthru_username value. Required. If you do not provide a user name and password, all other parameters are ignored.
- passthru_port
- The port at which the proxy is listening. If not specified, then a default value of port 80 is used. Required.
- passthru_realm
- User credential pairs are associated with realms, not URLs. This allows the same authorization information to be used for multiple URLs or whole URL trees. When a server sends back an unauthorized error, it includes the name of the realm that the requested URL belongs to. The client can then look and see whether it has stored a username and password for the realm, and if so, it supplies that information without having to prompt the user again. If a user name and password are needed for the proxy, you can specify the realm for the proxy so that the credentials do not get sent to any proxy. If you do not specify this parameter, then the credentials are sent for all authentication attempts. In the example that follows, Subversion User Authentication is specified as the passthru_realm. As a result, all authentication requests from this realm on the SVN server will be provided the given username and password. Optional. Set the passthru_realm parameter in a production environment to prevent the user name and password information from being presented for all authentication requests.
- passthru_username
- User name for authenticating with the pass-through proxy. In the that follows, any username which has read access to the subversion server will be sufficient when a GET request is sent to get authorization. Required. If you do not provide a user name and password, all other parameters are ignored.
The following example shows the configuration for a fictitious proxy firewall.
<proxy:meta-data> <proxy:name>passthru_host</proxy:name> <proxy:value>9.17.237.132</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_port</proxy:name> <proxy:value>3128</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_realm</proxy:name> <proxy:value>Subversion User Authentication</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_username</proxy:name> <proxy:value>adamsmith</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_password</proxy:name> <proxy:value>password123</proxy:value> </proxy:meta-data>
- Save and close the file.
- Use the following command to check in the proxy-config.tpl file during the same session in which you checked it out:
LCConfigService.checkInProxyConfig("temp_directory", "cell_name")
...where temp_directory is the temporary directory to which you checked out the configuration files, and cell_name is the name of the cell where the application that uses the common proxy-config.tpl file is located.
- Restart the application server hosting IBM Connections.
Configure the library widget proxy
Add a proxy policy to the proxy-ecm-config.tpl file to enable communication between IBM Connections and ECM servers.
To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client. See Starting the wsadmin client for details.
When configuring the proxy to allow your users access to trusted third-party web sites, ensure that those sites implement appropriate security controls. Configuring the proxy to mirror content from third-party servers may cause the proxy to mirror malicious content from those servers, so be sure to allow access to trusted sites only.
To configure the proxy-ecm-config.tpl file for library widgets.
- Start the wsadmin client.
- Access and check out the proxy-ecm-config.tpl file:
- Enter the following command to access theproxy-ecm-config.tpl file: execfile("connectionsConfig.py")
If you are prompted to specify which server to connect to, type 1.
- Enter the following command to check out the proxy-ecm-config.tpl file:
LCConfigService.checkOutProxyEcmConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the file is copied and are stored while you make changes. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutProxyEcmConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutProxyEcmConfig("c:/temp","foo01Cell01")
- Navigate to the working directory and open the proxy-ecm-config.tpl file in a text editor. In the policy element, replace the URL attribute with the server address of the ECM server:
<proxy:policy url="http://www.myECMServer.com:8080/*" acf="none" basic-auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> <proxy:method>HEAD</proxy:method> <proxy:method>POST</proxy:method> <proxy:method>PUT</proxy:method> <proxy:method>DELETE</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept*</proxy:header> <proxy:header>Content*</proxy:header> <proxy:header>Authorization*</proxy:header> <proxy:header>X-Method-Override</proxy:header> <proxy:header>Set-Cookie</proxy:header> <proxy:header>If-*</proxy:header> <proxy:header>Pragma</proxy:header> <proxy:header>Cache-Control</proxy:header> <proxy:header>X-Server</proxy:header> <proxy:header>X-Update-Nonce</proxy:header> <proxy:header>X-Passthrough-Basic</proxy:header> <proxy:header>X-Requested-With</proxy:header> <proxy:header>If-Modified-Since</proxy:header> <proxy:header>If-None-Match</proxy:header> <proxy:header>com.ibm.lotus.openajax.virtualhost</proxy:header> <proxy:header>com.ibm.lotus.openajax.virtualport</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> <proxy:cookie>JSESSIONID</proxy:cookie> </proxy:cookies> </proxy:policy>
- You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.
For example:
- circular_redirects
- Specifies that circular redirects are allowed. This property accepts a Boolean value of true or false specified in lower-case letters. If set to true, it supports using a proxy for a site that redirects to the same URL but with different parameters. Such a change is not recognized as a new URL. The default value of this property is true.
- connection-timeout
- Amount of time before an attempt to connect to a host times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- max_circular_redirects
- Maximum number of times a circular redirect is allowed before the proxy rejects it. Specified as an integer, the default value of this property is 100.
- maxconnectionsperhost
- Maximum number of simultaneous connections between the proxy and a given host. Specified as an integer, the default value of this property is 20.
- maxtotalconnections
- Maximum number of simultaneous connections between the proxy and all of the hosts together. Specified as an integer, the default value of this property is 50.
- socket-timeout
- Amount of time before an attempt to use a socket times out. Specified in milliseconds, the default value of this property is 60,000, which is 1 minute.
- unsigned_ssl_certificate_support
- Specifies that self-signed SSL certificates are supported. This property accepts a Boolean value of true or false specified in lower-case letters. The default value of this property is true. Change it to false when the system is ready for production.
<proxy:meta-data> <proxy:name>maxconnectionsperhost</proxy:name> <proxy:value>20</proxy:value> </proxy:meta-data>
- If your environment uses a pass-through proxy, add a <proxy:meta-data> element containing each of the following parameters:
- passthru_host
- The address at which the proxy is listening. In most cases, accessing the host and port from a browser causes an authentication request popup to be displayed. Required.
- passthru_password
- Password that corresponds with the passthru_username value. Required. If you do not provide a user name and password, all other parameters are ignored.
- passthru_port
- The port at which the proxy is listening. If not specified, then a default value of port 80 is used. Required.
- passthru_realm
- User credential pairs are associated with realms, not URLs. This allows the same authorization information to be used for multiple URLs or whole URL trees. When a server sends back an unauthorized error, it includes the name of the realm that the requested URL belongs to. The client can then look and see whether it has stored a username and password for the realm, and if so, it supplies that information without having to prompt the user again. If a user name and password are needed for the proxy, you can specify the realm for the proxy so that the credentials do not get sent to any proxy. If you do not specify this parameter, then the credentials are sent for all authentication attempts. In the example that follows, Subversion User Authentication is specified as the passthru_realm. As a result, all authentication requests from this realm on the SVN server will be provided the given username and password. Optional. Set the passthru_realm parameter in a production environment to prevent the user name and password information from being presented for all authentication requests.
- passthru_username
- User name for authenticating with the pass-through proxy. In the example that follows, any username which has read access to the subversion server will be sufficient when a GET request is sent to get authorization. Required. If you do not provide a user name and password, all other parameters are ignored.
The following example shows the configuration for a fictitious proxy firewall.
<proxy:meta-data> <proxy:name>passthru_host</proxy:name> <proxy:value>9.17.237.132</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_port</proxy:name> <proxy:value>3128</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_realm</proxy:name> <proxy:value>Subversion User Authentication</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_username</proxy:name> <proxy:value>adamsmith</proxy:value> </proxy:meta-data> <proxy:meta-data> <proxy:name>passthru_password</proxy:name> <proxy:value>password123</proxy:value> </proxy:meta-data>
- Enter the following command to check in your changes: LCConfigService.checkInProxyEcmConfig("working_directory","cell_name")
- Restart the IBM Connections server.
What to do next
To enable communication with more ECM servers, add a new copy of the current policy for each ECM server. In each new policy change the server name in the URL attribute.
Securing applications from malicious attack
IBM Connections provides security measures, such as an active content filter and content upload limits, that you can use to mitigate the risk of malicious attacks. Because these security measures can also limit the flexibility of the applications, you, as the system administrator, must evaluate the security of your network and determine whether or not you need to implement them.
Any software that displays user authored content can be vulnerable to cross-site scripting (XSS) attacks. Attackers can introduce JavaScript into their content that can, among other things, steal a user's session. Session stealing in a single sign-on (SSO) environment poses particular challenges because any vulnerability to XSS attacks can render the entire single sign-on domain vulnerable.
One of the ways that IBM Connections provides a defense against this type of attack is by implementing an active content filter. The active content filter removes potentially harmful text content, such as JavaScript, from user input added to a post or entry before saving the post or entry to an application; it does not filter file attachments. You can turn off the active content filter altogether if you determine that your network is safe from the threat of malicious attacks. You can also change the content that is filtered per application by editing the configuration properties.
Considerations
While securing IBM Connections against malicious attacks mitigates the vulnerability to XSS attacks, it also limits what trusted users can do. For example, it removes the ability to add dynamic JavaScript content to a blog. Some areas to consider when deciding which security measures to implement are:
- Text-based fields
- When active content filtering is enabled, users cannot add certain types of content to text-based fields. The product ships with a set of active content filter configuration files which specify which types of content are allowed and which are not. The configuration files used by the product by default allow users to edit styles and add forms to entries in each of the applications. They also allow users of the Blogs and Wikis applications to add flash content to entries. You can use the default filter settings or you can choose to apply other settings. See Configuring the active content filter for more details.
- File uploads
- Activities, Blogs, Files, Forums, and Wikis enable users to upload files, including Javascript and HTML. There is no way to guarantee that these files will not contain malicious code for cross-site scripting attacks, and the Active Content Filter is not used when downloading this content. To mitigate the effects of malicious code, you should configure IBM Connections to download files using a separate domain. This forces the downloaded content to be executed in isolation, and prevents it from accessing data associated with an authenticated session. For more details, see Specifying a separate file download domain.
- Custom templates
- Blogs supports the use of custom templates, which provide the ability for the blog owner to change the look of the blog. A custom template page is not filtered by the active content filter. Allowing custom template use introduces a XSS attack vulnerability.
Related tasks
Protect against malicious active content
Communities configuration properties Activities configuration properties
Configure the active content filter for Blogs, Wikis, and Forums
IBM Connections provides a set of active content filter (ACF) configuration files that you can apply to the Blogs, Wikis, or Forums applications to limit or widen the types of content that users can add to their blog posts, wiki pages, or forum posts.
This is not a required procedure. Only perform this if you want to change the level of filtering performed by the active content filter.
By default, Blogs, Wikis, and Forums filter active content in the following ways:
- Javascript is stripped from all posts and pages.
- You can change the formatting of content within rich text fields and styles can be added using HTML.
- Flash animations are permitted.
The following configuration files are shipped with IBM Connections and stored in the LotusConnections-config\extern directory. To change the level of filtering that is performed by the active content filter, you can replace the default configuration file with one of these files.
- acf-config.xml
- Allows style changes, allows forms, but strips flash. Flash is a format used for videos and animated content.
- acf-config-nf.xml
- Allows style changes, but strips forms and flash. The types of forms that are not allowed are form HTML elements. Form HTML elements are used to add things like buttons or fields to a web page.
- acf-config-ns.xml
- Allows forms, but strips style changes and flash. Preventing style changes affects rich text fields. If you configure the active content filter to prevent style changes, then users will not be able to perform the common tasks associated with changing the style of rich text content, such as changing the font color, margins, and so on.
- acf-config-nf-ns.xml
- Prevents style changes and strips forms and flash.
- acf-config-flash.xml
- Allows style changes, allows forms, and allows flash.
- acf-config-nf-flash.xml
- Allows style changes and flash, but strips forms. This file is the default file used by Blogs, Wikis, and Forums.
- acf-config-ns-flash.xml
- Allows forms and flash, but strips style changes.
- acf-config-nf-ns-flash.xml
- Allows flash, but strips style changes and forms.
- acf-config-nm.xml
- Prevents users from changing the margins on images and strips flash.
- acf-config-nm-flash.xml
- Allows flash, but prevents users from changing the margins on images.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for details.
- Edit LotusConnections-config.xml.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Open LotusConnections-config.xml in a text editor.
- Find the <sloc:serviceReference> element for the application to which you want to change filtering levels. The application name is specified in the serviceName attribute.
Change the active content filter configuration for the applications with the following serviceName attributes:
- Blogs
- Wikis
- Forums
- Add the following attribute to the <sloc:serviceReference> element for the application you want to change:
For example:
acf_config_file="file_name"...where file_name is one of the configuration files described earlier.
For example, to configure the Blogs application to allow style changes, but strip forms and flash, you would add the acf_config_file element:
<sloc:serviceReference bootstrapHost="myServer.example.com" bootstrapPort="2817" clusterName="" enabled="true" serviceName="blogs" ssl_enabled="true" acf_config_file="acf-config-nf.xml"> <sloc:href> <sloc:hrefPathPrefix>/blogs</sloc:hrefPathPrefix> <sloc:static href="http://enterprise.example.com:9082" ssl_href="https://enterprise.example.com:9447"/> <sloc:interService href="https://enterprise.example.com:9447"/> </sloc:href> </sloc:serviceReference>
- Repeat Steps d and e to apply different filtering levels to different applications, and then save and close the configuration file.
- After making changes, check the configuration file back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
- Synchronize the nodes using the Integrated Solutions Console for the network deployment system.
- Restart the WebSphere Application Server.
Configure the active content filter for Activities, Communities, and Bookmarks
IBM Connections provides a set of active content filter (ACF) configuration files that you can apply to the Activities, Communities, or Bookmarks applications to limit or widen the types of content that users can add to their entries.
This is not a required procedure. Only perform this if you want to change the level of filtering performed by the active content filter.
All of the applications, except Blogs, Wikis, and Forums, use the default acf-config.xml file, which filters active content in the following ways:
- You can change the formatting of content within rich text fields, but styles cannot be added to entries using HTML.
- Javascript is stripped from all entries.
- Flash animations are not permitted.
The following configuration files are shipped with IBM Connections and stored in the LotusConnections-config\extern directory. To change the level of filtering that is performed by the active content filter, you can replace the default configuration file with one of these files:
- acf-config-nf.xml
- Allows style changes, but strips forms and flash. The types of forms that are not allowed are form HTML elements. Form HTML elements are used to add things like buttons or fields to a web page.
- acf-config-nf-ns.xml
- Prevents style changes and strips forms and flash.
- acf-config-nm.xml
- Prevents users from changing the margins on images. By default, these applications permit image margin changes.
- acf-config-ns.xml
- Allows forms, but strips style changes and flash. Preventing style changes affects rich text fields. If you configure the active content filter to prevent style changes, then users will not be able to perform the common tasks associated with changing the style of rich text content, such as changing the font color, margins, and so on.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for details.
- Edit LotusConnections-config.xml.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Open LotusConnections-config.xml in a text editor.
- Find the <sloc:serviceReference> element for the application to which you want to change filtering levels. The application name is specified in the serviceName attribute.
Change the active content filter configuration for the applications with the following serviceName attributes:
- Activities
- Communities
- Bookmarks
- Add the following attribute to the <sloc:serviceReference> element for the application you want to change:
For example:
acf_config_file="file_name"...where file_name is one of the configuration files (acf-config-nf.xml, acf-config-nf-ns.xml, acf-config-nm.xml, or acf-config-ns.xml).
For example, to configure the Activities application to prevent image margin changes, you could add the following acf_config_file element:
<sloc:serviceReference bootstrapHost="myServer.example.com" bootstrapPort="2817" clusterName="" enabled="true" serviceName="activities" ssl_enabled="true" acf_config_file="acf-config-nm.xml"> <sloc:href> <sloc:hrefPathPrefix>/blogs</sloc:hrefPathPrefix> <sloc:static href="http://enterprise.example.com:9082" ssl_href="https://enterprise.example.com:9447"/> <sloc:interService href="https://enterprise.example.com:9447"/> </sloc:href> </sloc:serviceReference>
- Repeat Steps d and e to apply different filtering levels to different applications, and then save and close the configuration file.
- After making changes, check the configuration file back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
- Synchronize the nodes using the Integrated Solutions Console for the network deployment system.
- Restart the WebSphere Application Server.
Mitigating a cross site scripting attack
If you deem that your network is secure enough to turn off the active content filter, consider using one of the configuration options described in this topic to mitigate an attack should one occur. If you decide to disable active content filtering in favor of providing maximum flexibility, you must take steps to contain a cross site scripting (XSS) attack. For example, your organization might believe that as long as the XSS exposure is limited only to your blog site, the risk is acceptable. If that is the case, consider adopting the following best practices to contain an attack:
- Use isolated domains
- Ensure that the component at risk of attack is installed in a completely separate domain. For example, if the Blogs application will allow posting of active content, install it in a separate domain such as: blogs.acme.org. If the Activities application will allow active content, install it in a separate domain such as: activities.acme.org. Also consider using multiple domains for a single application, using a separate domain for the file downloads of the application.
- Do not use single sign-on
- To contain any attack, ensure that single-sign-on (SSO) authentication is not used to authenticate a user in an application that allows active content. When single sign-on is enabled, a user's cookie can be stored and used to access data in another domain. While it is not recommended that single sign-on be used when a component has turned off active content filtering, it is possible to use single sign-on with HTTP Only Cookies. WebSphere Application Server version 6.1.0.11 introduced the ability to produce "HTTP Only" cookies for the single sign-on cookies. If this application is used in conjunction with an HTTP-only browser, then the XSS vulnerability can be contained.
- Configure files to be downloaded from a separate domain
- Add rewrite rules to the IBM HTTP Server configuration file to force any downloaded files to be recognized by the web browser as content that is independent from the application it was downloaded from, and treat it accordingly. Without downloading in a subdomain with non-shared authentication, there is a vulnerability because other content types can allow execution of content with the hosting domain's credentials. An example of another content type that can get executed in the hosted domain is Adobe Flash. If Flash Player 9 is used, all hosted Flash will be allowed to call the hosting domain's services and execute XSS attacks. With Flash Player 10, if Content-Disposition: inline is used this vulnerability still exists. Blogs uses this Content-Disposition mode, so for maximum security on Blogs, a separate download domain must be used or Flash must be disabled.
If you choose to set up a subdomain for file downloads, determine whether or not to enable single sign-on between the subdomain and the domain of the core application:
See Specifying a separate file download domain for information about how to create the subdomain.
- If you choose to enable single sign-on, configure HTTP-only cookies. To do so:
- Open the WebSphere Application Server Integrated Solution Console.
- Expand Security, and then select Global security.
- Click Custom properties.
- Click New to add a property, and then add the following values to the fields:
- Name
- com.ibm.ws.security.addHttpOnlyAttributeToCookies
- Value
- true
- Click Apply, and then OK.
- If you choose not to enable single sign-on, users will be asked to re-authenticate when they download a file.
Specify a separate file download domain
Files added to the Activities, Blogs, or Files applications could potentially contain malicious code that can exploit the cross-site scripting vulnerabilities of some browsers. You can add rewrite rules to the IBM HTTP Server configuration file to force any downloaded files to be recognized by the web browser as content that is independent from the application from which it was downloaded, and treat it accordingly.
Most web browsers have security applications that prevent scripts which originate from one domain from accessing information in a browser session in another domain. This security application is loosely called the same origin policy. A domain is made up of a protocol (such as HTTP) and the domain (host name) that the page is loaded from. You can implement the following procedure to force files downloaded from Activities, Blogs, Files, or Forums to be identified as coming from a different domain than the application's web browser session.
When Siteminder is configured, the cookie domain is determined by the Siteminder CookieDomain configuration, which defines a single, fixed domain in IBM HTTP Server. This means without additional effort, downloads must share single sign-on with the application if Siteminder is used. See Mitigating a cross site scripting attack for more information about this risk.
- Register a new DNS domain alias for downloads from the Activities, Blogs, or Files sites, which points to the Activities, Blogs, Files, or Forums domain respectively. For example, if your server domain name for Activities is activities.example.com, you could name the alias activities-downloads.example.com and have it point to the same IP address as activities.example.com does.
- You might need a secondary certificate for the download domain. If so, get the certificate and configure it for use through the virtual host options. See the IBM HTTP Server documentation for more information.
- Open the httpd.conf file, which is the configuration file for IBM HTTP Server, in a text editor. By default, the file is stored in the following directory:
- AIX: /usr/IBM/HTTPServer/conf
- Linux: /opt/IBM/HTTPServer/conf
- Microsoft
Windows: C:\IBM\HTTPServer\conf
- Enable the rewrite module. If the following line of text is commented out, uncomment it. If the statement is not present, add it.
LoadModule rewrite_module modules/mod_rewrite.so
- Edit the configuration to indicate that the download domain allows download and login actions only and forbids all other actions. To do so, add the following block of text to the non-SSL virtual host section of the configuration file:
- Activities:
RewriteEngine On RewriteCond %{SERVER_NAME} !activities-downloads.example.com$ [NC] RewriteCond $1 !.*activitiesExtendedDescription.*$ [NC] RewriteRule ^/activities/service/download/(.+)$ http://activities-downloads.example.com/
activities/service/download/$1 [L] RewriteCond %{SERVER_NAME} ^activities-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} !^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/activities/auth/j_security_check$ RewriteRule .* - [F] RewriteCond %{SERVER_NAME} ^activities-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/activities/auth/login.jsp$ RewriteCond %{REQUEST_URI} !^/activities/auth/j_security_check$ RewriteCond %{REQUEST_URI} !^/activities/nav/.+$ RewriteCond %{REQUEST_URI} !^/activities/bundles/.+$ RewriteCond %{REQUEST_URI} !^/activities/styles/.+$ RewriteCond %{REQUEST_URI} !^/activities/javascript/.+$ RewriteRule !^/activities/service/download/(.+)$ - [F]
- Blogs:
RewriteEngine On RewriteCond %{SERVER_NAME} !^blogs-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteRule ^/blogs/(.+)/resource(/.+)?$ http://blogs-downloads.example.com/ blogs/$1/resource$2 [L] RewriteCond %{SERVER_NAME} ^blogs-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} !^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/blogs/j_security_check$ RewriteRule .* - [F] RewriteCond %{SERVER_NAME} ^blogs-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/login.do$ RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/login-redirect.jsp$ RewriteCond %{REQUEST_URI} !^/blogs/j_security_check$ RewriteCond %{REQUEST_URI} !^/blogs/bundles/css/.+$ RewriteCond %{REQUEST_URI} !^/blogs/nav/.+$ RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/images/.+$ RewriteCond %{REQUEST_URI} !^/blogs/.+/resource(/.+)?$ RewriteRule .* - [F]
- Files:
For Files: RewriteEngine On RewriteCond %{SERVER_NAME} !^files-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteRule ^/files(/.*)?/(document|draft|attachment|version)/([^/]*)/
media(/[^/]*/*)?$ http://files-downloads.example.com/files$1/$2/$3/media$4 [L] # If SSL is enabled for the component, remove the commenting from the two # lines below to redirect the login. # RewriteCond %{SERVER_NAME} ^files-downloads.example.com$ [NC] # RewriteRule ^/files/login$ https://files-downloads.example.com/files/login [L] RewriteCond %{SERVER_NAME} ^files-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} !^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/files/j_security_check$ RewriteRule .* - [F] RewriteCond %{SERVER_NAME} ^files-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/files/login$ RewriteCond %{REQUEST_URI} !^/files/j_security_check$ RewriteCond %{REQUEST_URI} !^/files/images/.+$ RewriteCond %{REQUEST_URI} !^/files/nav/.+$ RewriteCond %{REQUEST_URI} !^/files/js/.+$ RewriteCond %{REQUEST_URI} !^/files(/.*)?/(document|draft|attachment|version)/
([^/]*)/media(/[^/]*/*)?$ # If the IHS fast file serving module (mod_ibm_local_redirect.so) is enabled, # then you need to add access on the download domain for the alias you added # when configuring the module by replacing <FILES_CONTENT_DIR> with this value # and uncommenting the rule below. # See Configuring Files and Wikis downloading for production deployments # RewriteCond %{REQUEST_URI} !^/<FILES_CONTENT_DIR>/.+$ RewriteRule .* - [F]
- Forums:
RewriteEngine On RewriteCond %{SERVER_NAME} !forums-downloads.example.com$ [NC] RewriteCond $1 !.*forumsExtendedDescription.*$ [NC] RewriteRule ^/forums/service/download/(.+)$ http://forums-downloads.example.com/
forums/service/download/$1 [L] RewriteCond %{SERVER_NAME} ^forums-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} !^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/forums/auth/j_security_check$ RewriteRule .* - [F] RewriteCond %{SERVER_NAME} ^forums-downloads.example.com$ [NC] RewriteCond %{REQUEST_METHOD} ^(GET|HEAD)$ [NC] RewriteCond %{REQUEST_URI} !^/forums/auth/login.jsp$ RewriteCond %{REQUEST_URI} !^/forums/auth/j_security_check$ RewriteCond %{REQUEST_URI} !^/forums/nav/.+$ RewriteCond %{REQUEST_URI} !^/forums/bundles/.+$ RewriteCond %{REQUEST_URI} !^/forums/styles/.+$ RewriteCond %{REQUEST_URI} !^/forums/javascript/.+$ RewriteRule !^/forums/service/download/(.+)$ - [F]If you are cutting and pasting these statements into the configuration file, be advised that we have added hard returns to long statements to enable them to be displayed on the web page. Be sure to remove the hard-coded returns from long statements, such as URLs, after you paste them into the configuration file.
Replace references to .example.com with the alias that you created for the download domain for files downloaded from the application.
- If you are sending traffic over SSL, add the same set of statements to the SSL virtual host section of the configuration file, but update all web address references to indicate HTTPS instead of HTTP.
There are a few statements in the snippets for Files that must be either included or commented out depending on whether or not SSL is enabled.
- Add the rule in the previous step to any virtual host sections of the configuration file.
- Save and close the configuration file.
Turning off active content filtering
Only turn off active content filtering if you have secured your network against cross-site scripting attacks by other means.
The active content filter removes potentially harmful text content, such as JavaScript, from user input added to a post or entry before saving the post or entry to an application; it does not filter file attachments. Before you disable active content filtering, be sure you have considered the security implications of this decision. See Securing applications from malicious attack for more information.
- Start the wsadmin client. See Starting the wsadmin client for details.
- Find out what the current setting is for the active content filter property. See Editing configuration files for details and to find out which commands to use to check out the configuration files.
- Change the active content filtering property for the application using one of the following commands:
- Activities:
ActivitiesConfigService.updateConfig("activeContentFilter.enabled", "false")
- Blogs:
BlogsConfigService.updateConfig("ACFEnabled", "false")
- Bookmarks:
DogearCellConfig.updateConfig("activeContentFilter.enabled", "false")
- Communities:
CommunitiesConfigService.updateConfig("activeContentFilter.enabled", "false")
- Files:
FilesConfigService.updateConfig("activeContentFilter.enabled","false")
- Forums:
ForumsConfigService.updateConfig("activeContentFilter.enabled","false")
- Profiles:
ProfilesConfigService.updateConfig("activeContentFilter.enabled","false")
- Wikis:
WikisConfigService.updateConfig("activeContentFilter.enabled","false")
- Apply your changes. See Applying property changes for details.
Related tasks
Start the wsadmin client Change common configuration property values Edit configuration files Forcing traffic to be sent over SSL
You can configure IBM Connections to force all traffic that passes between an IBM Connections server and a user's web browser to be sent over the Secure Socket Layer (SSL).
Be sure that SSL is enabled in your environment before you perform this procedure. See Configuring the IBM HTTP Server for SSL in the Installing section of the IBM Connections product documentation for more information.
To edit configuration files, you must use the wsadmin client. See Start the wsadmin client for details.
- Use the wsadmin client to access and check out the IBM Connections configuration files.
- Enter the following command to access the IBM Connections configuration file: execfile("connectionsConfig.py")
If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.
- Enter the following command to check out the IBM Connections configuration files:
LCConfigService.checkOutConfig("working_directory","cell_name")
where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
AIX and Linux only: The directory must grant write permissions or the command does not run successfully.
- cell_name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:print AdminControl.getCell()
- AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")
- Microsoft
Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")
- Enter the following command:
LCConfigService.updateConfig("force.conf.comm.enabled", "true")
- After making changes, check the configuration files back in and you must do so during the same wsadmin session in which you checked them out for the changes to take effect. See Applying common configuration property changes for information about how to save and apply your changes.
- Optional: To secure session cookies, complete the following steps:
- Log in to the WebSphere Application Server Integrated Solutions Console of the server hosting your IBM Connections applications as the administrator.
- Expand Servers > Server Types, and then select WebSphere application servers.
- Click the server hosting IBM Connections from the list of server names.
- Click Session Management, and then click Enable cookies.
- Select the Restrict cookies to HTTPS sessions check box.
- Click Apply, and then click OK.
- Optional: To secure LTPA tokens, complete the following steps:
- From the WebSphere Application Server Integrated Solutions Console, expand Security, and then click Global security.
- Expand Web and SIP security, and then click single sign-on (SSO).
- Select the Requires SSL check box.
- Click Apply, and then click OK.
Related tasks
Change common configuration property values Start the wsadmin client Apply common configuration property changes Enable users to publish file attachments to Lotus Quickr Performance
Get information about how to configure IBM Connections for optimal performance.
About this task
Refer to the IBM Connections wiki for information about how to improve the performance of IBM Connections.IBM Connections wiki > Tuning for performance
Integrate with other products
You can integrate IBM Connections applications with other products.
Extend IBM Connections to work with the following products:
- IBM Connections Plug-in for IBM Sametime®
- Use the IBM Connections Plug-in for Sametime to bring powerful capabilities of the Activities and Profiles applications to your Sametime client.
- IBM Connections Plug-in for IBM Lotus Notes
- The Activities sidebar has been expanded to provide additional applications within the Notes client. Just choose the Connections component during the Notes client installation.
- IBM Connections Status Updates Plug-in for Lotus Notes
- Keep up-to-date with your Connections network from your Notes client. Use this sidebar application to post your status and view status for your colleagues.
- IBM Connections Files Plug-in for Lotus Notes
- Upload and access Connections files from your Lotus Notes sidebar.
- IBM Connections Portlets for IBM WebSphere Portal
- Use the Connections portlets to bring the collaborative power of Blogs, Activities, Bookmarks, Profiles, Wikis and Tags to your WebSphere Portal environment.
- IBM Connections Business Card
- Replace the standard Sametime business card with a business card that displays content from the person's IBM Connections profile and includes links to Connections content they own.
- IBM Connections Plug-in for Microsoft Office and Microsoft Windows
- Use the IBM Connections Plug-in for Microsoft Office and Microsoft Windows to integrate your collaboration tools. You can post mail messages to activities or get the benefit of Profiles in your Outlook client. Bring the powerful capabilities of the Activities, Blogs, and Profiles applications to your office applications, such as Microsoft Word, and add files from Windows Explorer to an activity in seconds. Use the Microsoft Outlook Social Connector to interact with your Connections network.
- IBM Connections Plug-in for Microsoft SharePoint
- Use the IBM Connections Plug-in for Microsoft SharePoint to integrate IBM Connections collaboration services with Microsoft SharePoint.
Use these other products from within IBM Connections:
- IBM Connections Widget for Microsoft SharePoint
- Use the IBM Connections Widget for Microsoft SharePoint to access Microsoft SharePoint documents from a community.
- IBM Lotus Quickr
- Use the IBM Connections Connector for Quickr to integrate Lotus Quickr places with communities. Community members can use different types of Lotus Quickr places to organize and share project files, post comments to a blog, and work collaboratively on team documents.
Notes:
- Install IBM Connections before attempting to install and use the plug-ins. The plug-ins rely on the functionality of the applications provided in the IBM Connections application.
- Do not configure IBM Connections to prevent email addresses from being displayed. If you hide email addresses, the extensions will not function, with the exception of the IBM Connections Portlets for IBM WebSphere Portal and the connectors for Communities. IBM Connections Connector for Quickr can be installed and will function in an IBM Connections deployment that is configured to prevent email addresses from being displayed:
Related tasks
Hide email addresses Install plug-ins to use IBM Connections in other applications
Enhance the other products that you use every day by making IBM Connections applications available from them.
You can access your IBM Connections data from within other products by adding plug-ins to those other products.
IBM Connections Plug-in for IBM Sametime
Bring a set of the powerful social networking applications of IBM Connections into the Sametime client.
The IBM Connections Plug-in for Sametime is available in two forms:
The plug-in provides the following features:
- The plug-in for Sametime embedded in the Notes client is available as an option during the Notes client installation.
- The plugin for the stand-alone Sametime client is provided as an update site, available as a download from the IBM Connection plug-in catalog.
- Activities . Use this application to save chats to activities, open activities from your Sametime window, or find activities that you share with a contact.
- Connections Business Card . Use this application to find out more about the people in your Sametime Contact list by viewing their business cards.
- Communities . Save chats to a community forum. This feature is only available in the standalone version of Sametime, not in the embedded version.
Install the IBM Connections Plug-in for Sametime
As the administrator, you can download the IBM Connections Plug-in for Sametime and host it in a location from which your users can access it to upgrade their own Sametime clients.
The IBM Connections Plug-in for Sametime requires Sametime version 8.0 or later. The following instructions are for downloading and installing the plug-in for the stand-alone Sametime client. The plug-in for use with the embedded Sametime client is available as a Notes installation option.
In order for the plug-in to be available for users to install from their Sametime clients, Sametime must be configured to allow plug-ins, as described in the Plug-in Management section of this topic: http://publib.boulder.ibm.com/infocenter/sametime/v8r5/index.jsp?topic=/com.ibm.help.sametime.v85.doc/admin/admin_ssc_policies_comm_list.html if the setting "Allow user to install plug-in" is not enabled, users will be unable to access the plug-in. The IBM Connections plug-in for Sametime allows users to save chats to activities, open related activities from a Sametime chat window, or save chats to a community forum. In addition, users can display contact information that is pulled directly from the Profiles server. To install the plug-in:
- Download the plug-in from the IBM Connections catalog web site:
https://greenhouse.lotus.com/catalog
- Save the update site files (site.xml file, plugins directory, and applications directory) to a location on your server. The location must be one that can be addressed by a web browser. Consult the IBM HTTP Server documentation for information on setting up addressable directories. The ht_docs directory is the default root directory of the HTML document repository.
- Let your users know the address from which the site is available so that they can specify it as the "New Remote Site" when they upgrade their clients to use the applications. For example, if you copied the update site files to an IBM HTTP Server directory called /opt/IBM/IHS61/htdocs/en_US/plugins, your users could use the following web address as the Remote Site:
http://myserver/plugins
- On the Sametime 8.0 or later server, enable your users to save chat transcripts. Otherwise, they will not be able to save chat transcripts to activities.
- Instruct your users to follow the steps described in the topic, Add the IBM Connections Plug-in for Sametime to your client, to complete the installation.
Add the IBM Connections Plug-in for IBM Sametime to your client
Use the built-in upgrade facility of the Sametime client to install the features provided by the IBM Connections Plug-in for Sametime that your administrator has made available to you. If you do not have access to the plug-in, contact your site administrator.
Your Sametime client must be version 8.0 or later. To add the IBM Connections features to your Sametime client, complete the following steps:
- From the Sametime client on which you want to implement the features, select Tools > Plug-Ins > Install Plug-ins from the menu.
- On the Install/Updates page, choose Search for new features to install, and then click Next.
- Select New Remote Site.
- Type a name, such as IBM Connections Plugin, in the Name field, and then type the web address provided by your administrator in the URL field.
- Click OK.
- In the Updates window, expand the site you selected, and then expand the IBM Connections folder.
- Select the check box next to IBM Connections if you want to install all plug-in features. If you want to only install certain features, select the check boxes for the components individually:
Click Next.
- Activities Sametime Feature . Use this feature to save chats to activities, open activities from your Sametime window, or find activities that you share with a contact.
To display the Save chat to activities icon, enable the Allow user to save chat log option on the Sametime server.
- Connections Business Card . Use this feature to find out more about the people in your Sametime Contact list by viewing their business cards.
- Communities Sametime Feature - Use this feature to save chats to communities forums.
- Click each feature to read its license agreement, select I accept the terms in the license agreement, and then click Next to open the installation page.
- Review the features to be installed, and then click Finish.
- After the client restarts, select File > Preferences, and then click Connections.
- Fill out the fields in the Preferences page:
Click Apply, and then click OK.
- User name . Set the user name you use to log into IBM Connections.
- Password . Set the password associated with the user name you use to log into IBM Connections.
- Server URL . Server URL - Set the web address for the Connections server provided by your administrator. For example: http://enterprise.acme.com .
IBM Connections Communities and Sametime Advanced Server Integration
The IBM Sametime Advanced Server can be configured to load Broadcast Communities from your IBM Connections Community server.
This application lets users save a broadcast chat to a community on the IBM Connections Communities server using the IBM Connections plug-ins for Sametime with Sametime clients configured to access the Sametime Advanced server. Refer to the Sametime Advanced documentation in the Sametime wiki for instructions.
Configure the Sametime Advanced server
After installing the Communities server and the required Sametime software, the next step is to configure the Sametime Advanced server to download communities from the Communities server.
To integrate Connections with Sametime Advanced, you must give the Sametime Advanced administrator permissions to view all of the communities in Connections. Sametime Advanced then uses that administrator.s account to download the list of communities from Connections and display it in the Broadcast Communities panel in Sametime Advanced.
Integration between IBM Sametime and IBM Connections products is one of the features of the IBM Connections Suite.
- 1.Create a dedicated Communities administrator. For more information, see Administering community content.
You will use this account when synchronizing Connections with Sametime Advanced in a later step.
- Determine the name of the LDAP realm used by the Connections deployment:
- On the Connections deployment manager, log in to the WebSphere Integrated Solutions Console as the WebSphere administrator.
- In the navigation list, click Security > Secure Administration, applications and infrastructure > Federated Repositories.
- Click Configure.
- On the main Federated repositories page, note the value for the realm name used for the Connections deployment.
- Close the Federated repositories page by clicking Cancel.
- Move to the computer hosting the Communities application for Connections, and start the wsadmin client :
- Open a command prompt, and then change to the following directory:
WAS_install_root\profiles\DM_profile\bin...where WAS_install_root is the WebSphere Application Server installation directory and DM_profile is the Deployment Manager profile directory, typicallydmgr01. For example, on Microsoft
Windows:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\binYou must start the wsadmin client from this directory because the Jython files for the product are stored here. If you try to start the client from a different directory, the execfile() command that you subsequently call to initialize the administration environment for a Connections component does not work correctly.
- Start the wsadmin client with the following command:
IBM AIX, Linux
./wsadmin.sh -lang jython -user was_admin_user_id -password was_admin_password -port SOAP_CONNECTOR_ADDRESS_portWindows
wsadmin -lang jython -user was_admin_user_id -password was_admin_password -port SOAP_CONNECTOR_ADDRESS_portwhere:
For example:
- was_admin_user_id is the user name of the WebSphere administrator account on the deployment manager.
- was_admin_password is the password of the WebSphere administrator account.
- SOAP_CONNECTOR_ADDRESS_port is the SOAP port for WebSphere Application Server. The default value of the SOAP port is 8879; if you are using the default port value, you do not need to specify this parameter.
If you are not using the default port and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
- Open the Integrated Solution Console for the deployment manager, and select System Administration > Deployment Manager.
- Under "Additional properties" expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
AIX, Linux
./wsadmin.sh -lang jython -user primaryAdmin -password p@assword -port 8879Windows
wsadmin -lang jython -user primaryAdmin -password p@assword -port 8879
- Now access and check out the Communities configuration file:
- Access the Communities configuration files with the following command:
execfile("communitiesAdmin.py")If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Check out the Communities configuration files :
CommunitiesConfigService.checkOutPolicyConfig("working_directory", "Cell_name")...where:
For example:
- working_directory is the temporary working directory to which the configuration XML and XSD files are copied. The files are kept in this working directory while you make changes to them.
AIX and Linux only: The directory must grant write permissions or the command will not run successfully.
- Cell_name is the name of the WebSphere Application Server cell hosting the Connections application. This argument is required. If you do not know the cell name, you can determine it by typing the following command in the wsadmin command processor:
print AdminControl.getCell()CommunitiesConfigService.checkOutPolicyConfig("/opt/my_temp_dir", "CommServerNode01Cell")
- Change to the working_directory where you stored the checked out files and open the communities-policy.xml file in a text editor.
- Make sure the file contains the following grant statement; if not, copy the code below and paste it into the section containing grant statements, and fill in the realm and Sametime Advanced administrator.s user name.
Even if the file already contains the grant statement, you will need to add the first line, which specifies the user who is receiving permissions.
<comm:grant> <comm:principal class="com.ibm.ws.security.common.auth.WSPrincipalImpl" name=" Connections_Realm/ST_Advanced_admin_user_name " /> <comm:principal class="com.ibm.tango.auth.principal.Role" name="admin" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityManagementPermission" communityType="*" action="*" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityMembershipPermission" communityType="*" action="*" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityAccessPermission" communityType="*" action="*" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityReferencePermission" communityType="*" action="*" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityBroadcastPermission" communityType="*" action="*" /> <comm:permission class="com.ibm.tango.auth.permission.CommunityInvitePermission" communityType="*" action="*" /> </comm:grant>where:
- Connections_Realm is the Connections LDAP repository realm name that you identified in step 1.
- ST_Advanced_admin_user_name is the user name of the Sametime Advanced administrator who will have permissions to view Connections communities.
- Save and close the file.
- Check in the updated file using the following wsadmin client command:
CommunitiesConfigService.checkInPolicyConfig("working_directory", "Cell_name")
- Exit the wsadmin client with the following command: exit.
- Stop and restart the server.
- Synchronize Connections and Sametime Advanced:
- Move to the Sametime System Console and log in as the Sametime administrator.
- Click Sametime Servers > Sametime Advanced Server.
- Click the name of the Sametime Advanced server.
- On the Administrative Sets tab, location "Connection settings".
- Select https protocol.
- Set the fully qualified host name in the Host name field.
- Set the port number in the Port field.
- Set the user name and password for the Communities administrative user created in step 1.
- Select the Enable Daily Community Synchronization check box.
The servers will synchronize daily at 2 AM in the time zone of the Sametime Advanced server.
- Click Save.
- Click Synchronize Now to synchronize immediately rather than waiting for the scheduled synchronization.
Sametime Advanced cannot access the list of broadcast communities until synchronization is complete.
Enable SSL access to the Communities Server
To secure access between the Communities server and the Sametime Advanced server, perform the following steps.
- From the Sametime Advanced server, select Security > SSL Certificate and key management > Key store and certificates > NodeDefaultTrustStore > Signer Certificates.
- Select Retrieve from Port.
- Enter the host and port details for the Communities server to connect to.
- Click OK.
- Save the results and reboot the server if needed.
Remove the IBM Connections Plug-in for Sametime
Remove the plug-in using the standard Sametime feature removal tools. To remove the IBM Connections Plug-in for Sametime, complete the following steps:
- From the Sametime client, select Tools > Plug-Ins > Manage Plug-ins.
- Click the Show Nested Features icon to display a list of the installed features.
You may need to expand sections to find the features.
- Find Activities Sametime Feature in the list. Right-click the feature name, and then select Uninstall.
- When asked to confirm, click OK. When asked to restart, click No.
- Find Communities Sametime Feature in the list. Right-click the feature name, and then select Uninstall.
- When asked to confirm, click OK. When asked to restart the client, click No.
- Find Connections Business Card in the list. Right-click the feature name, and then select Uninstall.
- When asked to confirm, click OK. When asked to restart the client, click Yes.
IBM Connections Portlets for WebSphere Portal
Bring the power of IBM Connections to your portal applications.
This section describes the 3.0.1.1 version of the IBM Connections Portlets for WebSphere Portal. The portlets do not currently support the IBM Connections 4 servers. This section will be updated when support for Connections 4 is certified.
Install the 3.0.1.1 version makes the following portlets available to your portal users:
- Activities . Collaboration tool for collecting, organizing, sharing, and reusing work related to a project goal.
- Blogs . Online journals you can use to deliver timely information with a personal touch.
- Bookmarks . Social bookmarking tool that you can use to save, organize, and share Internet and intranet bookmarks.
- Tags . Meaningful keywords you can use to find associated content.
- Profiles . Directory of colleagues you can use to build a network and locate expertise.
- Wikis . Repository for sharing and collaborating on pages of interest to your group.
- Forums . View and contribute to discussion topics.
- Community Overview . View basic community information like the description, tags, and community owners. Perform basic community actions from the portlet.
- Blogs Summary . Choose a view to see a snapshot of recent, latest, or featured blog activity
- Profiles Summary . View a summary of information about your colleagues.
- Forums Summary . View a list of forums that you can access.
- Bookmarks Summary . View a list of bookmarks you can access.
With the 3.0.1.1 version, you can also deploy community pages, which are portal pages associated with communities from IBM Connections communities. Portlets on community pages are automatically scoped to the community membership and display content from the community in the portlets. For example, if your community contains a forum, adding the forum portlet to a community page lets portal users view and interact with the forum content from a Portal application.
If you are installing the 3.0.1.1 version of IBM Connections Portlets for IBMWebSphere Portal, you must uninstall any previous versions of the portlets before you install. Upgrading from previous versions is not supported.
What's New in the IBM Connections Portlets for WebSphere Portal
IBM Connections Portlets for WebSphere Portal includes some new and updated features.
The IBM Connections Portlets for WebSphere Portal do not yet support the IBM Connections 4 servers. This section is a placeholder until support is enabled.
Deploying the IBM Connections portlets
Deploy the IBM Connections to bring social business to your portal applications.
Follow these instructions to install, configure, and deploy the IBM Connections portlets for IBM WebSphere Portal.
If you plan to deploy IBM Connections portlets on anonymous pages that do not require authentication, find out more in this article from the IBM Web Experiences wiki. Follow the steps for setting up anonymous access in the "Enabling session IDs for anonymous users" article from the IBM WebSphere Portal wiki.
Restriction: In order to use common directory services, Portal must be configured to use a federated LDAP. Use of a stand-alone LDAP is not supported.
Configure the resource environment provider
You must add IBM Connections server URLs to the WebSphere Resource Environment provider as part of the configuration.
Follow these steps to configure the environment variable to set the IBM Connections server URLs for the portlets.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resources > Resource Environment > Resource Environment Providers.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- Click New and specify as name WP ConnectionsIntegrationService.
- Click Apply.
- Click Custom Properties.
- Click New and create the following attributes:
These fields are mandatory:
Name Description Type blogsHomepageHandle Set to the blogs Home page handle for your IBM Connections deployment. The default is Home.
The homepage handle can be found under Apps > Blogs > Administration in the field Handle of blog to serve as Blogs Homepage when logged into the Connections server as a blogs administrative user.
java.lang.String connVersion 3.0.1.1 java.lang.String tagSearchType Set to search or mysearch depending on whether you want the tag cloud to display tags only for public content or tags for public content as well as content the logged-in user has contributed. java.lang.String emailSet Set to email-exposed or email-hidden depending on whether or not the IBM Connections server is configured to expose user email addresses or to hide them. java.lang.String If you are using the same hostname for all Connections services and the default context roots for every service then you only need to set the following additional parameter and ignore the optional parameters for setting the individual service URLs and context roots:
Name Description Type globalBaseURL Base URL to the Connections server. For example, https://connections.ibm.com java.lang.String All URL parameters should be set using the SSL (https) protocol and port.
Optional: If you use a different hostname for each of your Connection services set the following parameters instead of globalBaseURL:
Name Description Type activitiesURL Base URL to the Activities service. For example, https://connections-activities.ibm.com.. java.lang.String profilesURL Base URL to the Profiles service. For example, https://connections-profiles.ibm.com . java.lang.String communitiesURL Base URL to the Communities service. For example, https://connections-communities.ibm.com . java.lang.String blogsURL Base URL to the Blogs service. For example, https://connections-blogs.ibm.com . java.lang.String bookmarksURL Base URL to the Bookmarks service. For example, https://connections-dogear.ibm.com java.lang.String forumsURL Base URL to the Forums service. For example, https://connections-forums.ibm.com java.lang.String wikisURL Base URL to the Wikis service. For example, https://connections-wikis.ibm.com java.lang.String searchBaseURL Base URL to the SearchBaseURL service. For example, https://connections-search.ibm.com java.lang.String Optional: If you are not using the default context root to address each Connections service, set the following parameters to define the context roots used for your Connections deployment:
Name Description Type activitiesContextRoot The context root for the Activities service. For example, /mycontext/activities. If this parameter isn't defined, the default context root will be used: /activities java.lang.String profilesContextRoot The context root for the Profiles service. For example, /mycontext/profiles. If this parameter isn't defined, the default context root will be used: /profiles. java.lang.String communitiesContextRoot The context root for the Communities service. For example, /mycontext/communities. If this parameter isn't defined, the default context root will be used: /communities. java.lang.String blogsContextRoot The context root for the Blogs service. For example, /mycontext/blogs. If this parameter isn't defined, the default context root will be used: /blogs. java.lang.String bookmarksContextRoot The context root for the Bookmarks service. For example, /mycontext/dogear. If this parameter isn't defined, the default context root will be used: /dogear. java.lang.String forumsContextRoot The context root for the Forums service. For example, /mycontext/forums. If this parameter isn't defined, the default context root will be used: /forums. java.lang.String wikisContextRoot The context root for the Wikis service. For example, /mycontext/wikis. If this parameter isn't defined, the default context root will be used: /wikis. java.lang.String searchContextRoot The context root for the Search service. For example, /mycontext/search. If this parameter isn't defined, the default context root will be used: /search. java.lang.String If you are configuring the portlets with a single sign on solutions, for example, Tivoli Access Manager, use the URL you use to access the IBM Connections server for single sign-on.
(Optional) These variables control display features for the Connections portlets.
Name Description Type showContentTitleInPortlet This is used to show/hide the Content title within the portlet. The default value is True, because by default the theme for Portal 7.0.0.2 and Portal 8 portlets deploys portlets without a skin. In those cases, it is important to display the content title in the portlet.
java.lang.String showForumSummaryFiltersInCommunity This is used to show or hide options, for example, Open questions or Answered question for the Forums summary portlet, because there is no API support to filter topics in a community scope. The default value is False. java.lang.String (Optional) Some of the Connections portlets (Blogs, Bookmarks and Activities) use Dojo dialogs for creating and editing content. Theme resources are not available inside Dojo dialogs. To optimize the Dojo loading while working with Dojo dialogs, configure the following property. It contains the comma-separated list of Dojo layers to be loaded for optimizing the Dojo loading inside the dialogs. The defaults correspond to the Portal server.
Name Description Type dojoLayers Default value for Portal 7: _dom_layer.js,dojo.js,_app_layer.js,dijit.js,_data_layer.js,_dijit_menu_layer.js,_fmt_layer.js,_fx_layer.js,_dijit_layout_basic_layer.js,_dojox_layout_basic_layer.js,_dnd_ext_layer.js
Default value for Portal 8: _dom.js,_app.js,dijit.js,_data.js,_dijit_menu.js,_fmt.js,_fx.js,_dijit_layout_basic.js,_dojox_layout_basic.js,_dnd_ext.js,_dnd_basic.js
java.lang.String
- Save the new settings.
Configure the DynaCache
Configure DynaCache to store community feeds in order to reduce server requests.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 to use this feature. The IBM Connections portlets use a DynaCache to store the initial service configuration URLs for the portlets and then to store the Community feed URLs and other information to optimize the page load performance for community pages. Storing the community feed URLs in the DynaCache reduces the number of server requests to the IBM Connections server to render the content in each of the portlets.
To set up the Connections Portlets DynaCache instance for each node in you portal cluster, do the following:
- Open the WebSphere Application Server Admin Console and expand Cache Instances in the Resources section.
- Select Object Cache Instances.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- Click New to create a new cache instance.
- Set the JNDI Name to services/cache/LCPortletsObjectCache and set Name to something meaningful.
- Click OK to save your changes.
What to do next
The default value of 2000 is designed to handle the number of community feeds for an average deployment. You can edit this value. For example, you might set this value to 20 times the number of active communities that would be accessed in ten minute period.
Set up an authentication alias for the portlets
Set up an authentication alias with user credentials from the common LDAP shared between IBM Connections and Portal to manage VMM services. To set up an authentication alias with user credentials from the common LDAP between IBM Connections and Portal, follow these steps:
In a network environment, you must create the alias in the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- In the WebSphere Application Server Integrated Solutions Console, expand Security, and then select Global Security.
- Expand Java Authentication and Authorization Service.
- Select J2C authentication data.
- Click New and specify the alias name and the user credentials for a user from the common LDAP between IBM Connections and Portal. If you are deploying on Portal 7.0.0.2, make sure Prefix new alias names with the node name of the cell is checked before creating the alias. If you are deploying on Portal 8, Prefix new alias names with the node name of the cell can be de-selected. However, if it is de-selected, you must make sure that the alias name in the directory.services.xml does not have the prefix. For more information on configuring the directory.services.xml file, see the topic Configuring portlets to use common directory services.
This user must be assigned the dsx-admin role in Connections for the Communities application. For more information, see the topic Roles.
- Click OK and Save.
Results
After you have created the authentication alias, you will see the alias prefixed with the WebSphere cell name. For example:
<cellname>/dsxAdmin connectionsAdmin on a Portal 8 server, the alias is prefixed with the node name. for example, <nodename>/dsxAdmin.
Configure portlets to use common directory services
Configure the IBM Connections portlets to use the common directory services to enable directory lookup from IBM Connections in the IBM WebSphere Portal environment. This enables typeahead for finding names.
For general information on enabling common directory services for IBM Connections applications, refer to the topic Using the Profiles database as the user directory. If you have not already done so, create an authentication alias, described in the topic Set up an authentication alias for the IBM Connections portlets.
Restriction: In order to use common directory services, Portal must be configured to use a federated LDAP. Use of a stand-alone LDAP is not supported. Follow these steps to configure common directory services for the IBM Connections portlets.
- Stop WebSphere Portal Server. For a clustered deployment, stop all Portal servers.
- On the server hosting IBM Connections, open LotusConnections-config.xml for editing. This file is located in the {install.root}/config/cells/{local.cell}/LotusConnections-Config directory.
- Make sure the Profiles database is set up to be the user directory for IBM Connections by looking for the following setting:
profiles_directory_service_extension_enabled="true"If this setting is not enabled, see Using the Profiles database as the user directory to find the steps you can follow to enable it.Make sure that the Profiles user directory includes the user dsxAdmin, which is used in Portal for creating the J2C authentication alias.
- Locate the <serviceReference> elements with the serviceName="communities" and serviceName="profiles" attributes and take note of the values of the <interService> and <hrefPathPrefix> elements.
<sloc:serviceReference serviceName="profiles" <sloc:hrefPathPrefix>/profiles</sloc:hrefPathPrefix> <sloc:interService href="https://enterprise.example.com:9080"/> </sloc:serviceReference> <sloc:serviceReference serviceName="communities" <sloc:hrefPathPrefix>/communities</sloc:hrefPathPrefix> <sloc:interService href="https://enterprise.example.com:9081"/> </sloc:serviceReference>
- Do the following to copy the configuration files:
- For a single server: On the IBM WebSphere Portal server, copy the following files:
from the DirectoryServices directory from the IC Portlets 3.0.1.1 download package, <IC3011_portlets>\DirectoryServices, to: <portalInstallRoot>\wp_profile\config\cells\<cell>\ .
- directory.services.xml
- directory.services.xsd
- sonata.services.xml
- sonata.services.xsd
- For a clustered deployment: On the primary IBM WebSphere Portal server, copy the files from the DirectoryServices directory from the IC Portlets 3.0.1.1 download package, <IC3011_portlets>\DirectoryServices, to the DMGR directory located at: <DMGR install root>\profiles\<dmgr profile name>\config\cells\<cell>\ .
- Edit directory.services.xml and set:
Option Value com.ibm.connections.directory.services.waltz.profiles.integration.service.url [interService href] + [hrefPathPrefix] + /dsx/ com.ibm.connections.directory.services.waltz.profiles.integration.service.auth.alias [cell name]/dsxAdmin com.ibm.connections.directory.services.waltz.communities.integration.service.url [interService href] + [hrefPathPrefix] + /dsx/ com.ibm.connections.directory.services.waltz.communities.integration.service.auth.alias [cell name]/dsxAdmin The value for com.ibm.connections.directory.services.waltz.profiles.integration.service.auth.alias and com.ibm.connections.directory.services.waltz.communities.integration.service.auth.alias is the J2C authentication alias created in the Set up an authentication alias topic.
The values for [interService href] and [hrefPathPrefix] for the Profiles and Communities integration service URL properties are the properties that were identified in the LotusConnections-config.xml configuration file in Step 4.
For example, this is a sample code block from directory.services.xml after setting the parameters:
<config version="3.0" id="directory.services" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="directory.services.xsd"> <profileProvider class="com.ibm.connections.directory.services.provider.WaltzServiceProvider"> <property name="com.ibm.connections.directory.services.waltz.profiles.integration.service.enabled">true</property> <property name="com.ibm.connections.directory.services.waltz.profiles.integration.service.url">https://profiles.ibm.com/profiles/dsx/</property> <property name="com.ibm.connections.directory.services.waltz.profiles.integration.service.auth.alias">portalcell/dsxAdmin</property> <property name="com.ibm.connections.directory.services.waltz.communities.integration.service.enabled">true</property> <property name="com.ibm.connections.directory.services.waltz.communities.integration.service.url">https://communities.ibm.com/communities/dsx/</property> <property name="com.ibm.connections.directory.services.waltz.communities.integration.service.auth.alias">portalcell/dsxAdmin</property> <profileProvider/> </config>
- If you are using LTPA SSO, skip this step because no change is require. For other types of authentication, edit sonata.services.xml and change the sonataServices tag, <sonataServices name="DefaultAuthenticator">, to the appropriate value for the name attribute.
- SPNEGO: <sonataServices name="KerberosAuthenticator">
- TAM: <sonataServices name="TAMAuthenticator">
- SiteMinder: <sonataServices name="SiteMinderAuthenticator">
- TAM and SPNEGO: <sonataServices name="KerberosAuthenticator">
On a Portal 8 server, use <sonataServices name="TAMAuthenticator">
- SiteMinder and SPNEGO: <sonataServices name="KerberosAuthenticator+">
- (Clustered deployment only) Login to DMGR admin console and navigate to the System Administration - Nodes. Select both WebSphere Portal nodes and click Full Resynchronize.
- Restart the Portal server after updating directory.services.xml or restart all of the servers for a clustered deployment.
Import a certificate to support SSL
Import a certificate so that IBM Connections and WebSphere Portal can communicate over Secure Socket Layer (SSL). In order for WebSphere Portal to communication with IBM Connections over Secure Sockets Layer (SSL), the WebSphere Portal server must trust the signer of the SSL certificate for IBM Connections. This might be set up by default in your WebSphere infrastructure if you use SSL certificates issued by a commonly recognized authority. If you use self-signed certificates, the default certificate or a signer that is not recognized by your WebSphere Portal server, you will need to import the SSL certificate from IBM Connections to your WebSphere Portal server.
Import the SSL keys into the Portal server as follows:
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Security > SSL certificate and key management > Key stores and certificates.
- Add the certificates to the appropriate trust store as configured in SSL Configurations. To view the SSL configuration and determine the appropriate trust store, navigate to :Security > SSL certificate and key management > SSL configurations > NodeDefaultSSLSets > ['Trust Store Name'] For example, in a standalone deployment you navigate to NodeDefaultTrustStore > Signer certificates for adding certificates. If NodeDefaultSSL Sets points to 'CellDefaultTrustStore', you add a certificate to 'CellDefaultTrustStore'.
- Click Retrieve from port.
- Enter the host and SSL port used by your Connections server. The default SSL port is 443. Give the alias a name, for example, Connections. For example:
Host: connections.example.com Port: 443 Alias: connections
- Click Retrieve signer information.
- Click OK.
- Click Save.
Configure authentication for the portlets
Set up single sign-on integration between IBM Connections and WebSphere Portal using third-party security products, or configure basic authentication to enable access to the portlets.
IBM Connections uses single sign-on (SSO) to secure the transfer of user ID and password information that is used to authenticate with the system. With SSO, users can switch to different applications without needing to authenticate again. SSO is automatically enabled when IBM Connections is installed on a single WebSphere Application Server profile or when different profiles are federated into the same cell.
Configure basic authentication allows the manual entry of user credentials in the personalize mode of the portlets. Basic authentication for the portlets can only be supported if single sign-on is not already enabled between WebSphere Portal and IBM Connections. If single sign-on is enabled (through LTPA, Kerberos or another mechanism), it will take precedence. If single sign-on is enabled, the basic authentication credentials entered in the personalize mode of the portlets will be ignored.
Configure single sign-on for end users is recommended over using basic authentication for end user interactions. When using basic authentication for the portlets, every user must type in their personal credentials manually in the personalize mode of the portlets or shared credentials can be supplied from the Credential Vault. Basic authentication can be especially useful for trials of the portlets before you have a chance to configure some form of single sign-on, but is not recommended for production use.
Enable single sign-on for the portlets using a stand-alone LDAP server
Before installing the IBM Connections Portlets for IBM WebSphere portal, enable single sign-on (SSO) between IBM Connections and WebSphere Portal..
This task describes the steps required to enable SSO between IBM Connections and WebSphere Portal when they are on different WebSphere Application Server cells. Applications deployed on servers within the same WebSphere Application Server cell are enabled by default for SSO.
You should set the realm name in the LTPA token to that of the LDAP server before you export the LTPA token. For example, if you connect to an LDAP server at ldapserver.example.com over port 389, then you must set the realm name to ldapserver.example.com:389. If you need to change the realm name, see the topic Changing the realm name.
To allow SSO between IBM Connections and WebSphere Portal, complete the following steps:
- On the server where IBM Connections is installed, enable SSO:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator, expand Security > Global security.
- Expand Web and SIP security and then click Single sign-on (SSO).
- Enter the domain name .
Ensure that the domain name you enter is valid: on the node where WebSphere Portal is installed, log into the WebSphere Application Server Integrated Solutions Console as an administrator, click Security > Global security > Web and SIP security > Single sign-on (SSO) and verify that the domain name is present.
- On IBM Connections deployment manager node:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator.
- Click Security > Global security > LTPA, and then in the Cross-cell single sign-on section, provide values for the following fields:
- Password . Type a secure password that you will remember. You will need to provide this password later, when you export the key file
Confirm the password.
- Fully qualified key file name . Specify a valid path and a name for the file that will hold the exported keys
- Click Export keys.
- On the node where WebSphere Portal is installed:
- Log into the WebSphere Application Server Integrated Solutions Console as an administrator and click Security > Global security > LTPA.
- In the General properties section, provide values for the following fields:
- Password . Set the password that you used for the IBM Connections key file that you exported
Confirm the password.
- Fully qualified key file name . Set the name of the IBM Connections key file that you exported
- Click Import keys
- Restart all the nodes.
Configure single sign-on for portlets with TAM and SPNEGO
Configure IBM Connections portlets to use single sign-on with IBM Tivoli Access Manager and SPNEGO.
Single sign-on (SSO) enables users to log in to an IBM Connections application and switch to other applications within the product without having to authenticate again.
There are several different ways to configure SSO. This procedure describes an approach that uses the Kerberos authentication protocol. This authentication method allows Tivoli Access Manager and users web browsers to prove their identities to one another in a secure manner. After users sign in to their Active Directory Windows client systems, they are automatically signed into both Tivoli Access Manager and IBM Connections.
Configuring IBM Connections and WebSphere Portal to share a single Deployment Manager saves on administration time by combining administration tasks for the two applications. Establishing a single-sign on environment benefits the users by creating a more seamless environment between the two applications.
Follow these steps to configure single sign-on.
- Before federating Portal as a managed node of the Deployment Manager of IBM Connections, make sure the realms match between Connections Deployment Manager and Portal. If change the realm names so they match, follow the steps in Changing the realm name.
- Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:
- From the <wp_profile_root>/ConfigEngine directory of the primary node, run this task: ConfigEngine.bat collect-files-for-dmgr -DWasPassword=password . This creates a zip file containing all the files which need to be copied to the Deployment Manager. The zip file, named filesForDmgr.zip, will be placed in the <wp_profile_root>/filesForDmgr directory.
- Stop the Deployment Manager.
- Expand each of the files in the filesForDmgr.zip file into the proper location on the Deployment Manager based on the directory names within the zip file. The directory names in the zip file are based on the typical default directory names. The directory called AppServer/profiles/Dmgr01 is used to identify the Deployment Manager profile root, and the AppServer directory is used to identify the Deployment Manager installation root directory. If the Deployment Manager was installed into the default directory (AppServer) and the profile was created in the default directory (AppServer/profiles/Dmgr01), then the zip file can be expanded directly into the directory above the AppServer directory; for example /IBM/WebSphere.
- Start the Deployment Manager.
- To augment a Deployment Manager profile, run the following command from the <AppServer_root>/bin directory:
manageprofiles.bat -augment -templatePath c:/IBM/WebSphere/AppServer/profileTemplates/management.portal.augment -profileName Dmgr01
- Restart the Deployment Manager.
- Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.
- Run the following command from the <wp_profile_root>/bin directory to federate the primary node:
addNode.bat dmgr_hostname dmgr_port -includeapps -includebuses -username was_admin_user -password was_admin_passwordFor example:addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd
- On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.
- To configure the IBM HTTP Server with Single Sign-On, delete and re-add the webserver on the WebSphere Application Server Integrated Solutions Console in order to re-map all applications including Portal, and import the Portal certificate into IBM HTTP Server.
- Skip this step if you are deploying on Portal 8. To Configure the same SPNEGO single sign-on for Portal and Connections:
- Create user for Portal host server on AD
- Create keytab file for Portal server on AD.
ktpass -out path_to_keytab .princ SPN -mapuser account_name -mapOp set .pass account_passwordWhere:For example:
- path_to_keytab is the file path where you want to store the generated keytab file.
- SPN is the Kerberos service principal name.
- account_name is the service account name.
- account_password is the password associated with the service account.
ktpass -princ HTTP/portal.cn.ibm.com@cn.ibm.com -out c:\portal.keytab -mapuser portaluser -mapOp set -pass Passw0rd
- Merge the portal keytab into the merged Connections keytab by running the ktab command with the following switch:
-m source_keytab_name destination_keytab_nameWhere:For example:
- source_keytab_name is the name of the keytab file on the source system.
- destination_keytab_name is the name of the keytab file on the destination system.
c:\IBM\WebSphere\AppServer\java\jre\bin>ktab.exe -m y:\SPNEGO\portal.keytab y:\SPNEGO\merged.keytab
- Recreate the krb5.conf file using the new merged keytab file:
$AdminTask createKrbConfigFile { -krbPath appserver\java\jre\lib\security\krb5.conf -realm REALM -kdcHost kdc_hostname -dns dns_hostname -keytabPath path_to_keytab }For example:wsadmin.bat -user adminuser -password adminpwd $AdminTask createKrbConfigFile {-krbPath y:\SPNEGO\krb5.conf -realm CN.IBM.COM -kdcHost AD.cn.ibm.com -dns cn.ibm.com -keytabPath y:\SPNEGO\merged.keytab}
- Enable SPNEGO single sign-on by configuring Kerberos in the WebSphere Application Server Integrated Solutions Console, following the steps in the Enabling single sign-on for Tivoli Access Manager with SPNEGO topic.
- Synchronize the node and restart the Deployment Manager node. If you can not manage the Portal node on the WebSphere Application Server Integrated Solutions Console , manually synchronize the node and restart the Deployment Manager node.
- Configure Tivoli Access Manager on the Portal server, following the directions in the topic Configure Tivoli Access Manager in the IBM WebSphere Portal product wiki. For example:
server task default-webseald-TAMhost.cn.ibm.com create -t ssl -b filter -A -F C:\WASLTPA.key -Z password -h DMhost.cn.ibm.com -c all -f -k -j -J trailer /wpsv70 ConfigEngine.bat run-svrssl-config -Dwp.ac.impl.PDAdminPwd=password ConfigEngine.bat validate-pdadmin-connection -DWasPassword=password -Dwp.ac.impl.PDAdminPwd=password ConfigEngine.bat enable-tam-all -DWasPassword=password
Configure single sign-on with TAM
Configure IBM Connections portlets to use single sign-on with IBM Tivoli Access Manager.
Single sign-on (SSO) enables users to log in to an IBM Connections application and switch to other applications within the product without having to authenticate again.
There are several different ways to configure SSO. This authentication method allows Tivoli Access Manager and users web browsers to prove their identities to one another in a secure manner.
Configuring IBM Connections and WebSphere Portal to share a single Deployment Manager saves on administration time by combining administration tasks for the two applications. Establishing a single-sign on environment benefits the users by creating a more seamless environment between the two applications.
Follow these steps to configure single sign-on.
- Before federating Portal as a managed node of the Deployment Manager of IBM Connections, make sure the realms match between Connections Deployment Manager and Portal. If change the realm names so they match, follow the steps in Changing the realm name.
- Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:
- From the <wp_profile_root>/ConfigEngine directory of the primary node, run this task: ConfigEngine.bat collect-files-for-dmgr -DWasPassword=password . This creates a zip file containing all the files which need to be copied to the Deployment Manager. The zip file, named filesForDmgr.zip, will be placed in the <wp_profile_root>/filesForDmgr directory.
- Stop the Deployment Manager.
- Expand each of the files in the filesForDmgr.zip file into the proper location on the Deployment Manager based on the directory names within the zip file. The directory names in the zip file are based on the typical default directory names. The directory called AppServer/profiles/Dmgr01 is used to identify the Deployment Manager profile root, and the AppServer directory is used to identify the Deployment Manager installation root directory. If the Deployment Manager was installed into the default directory (AppServer) and the profile was created in the default directory (AppServer/profiles/Dmgr01), then the zip file can be expanded directly into the directory above the AppServer directory; for example /IBM/WebSphere.
- Start the Deployment Manager.
- To augment a Deployment Manager profile, run the following command from the <AppServer_root>/bin directory:
manageprofiles.bat -augment -templatePath c:/IBM/WebSphere/AppServer/profileTemplates/management.portal.augment -profileName Dmgr01
- Restart the Deployment Manager.
- Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.
- Run the following command from the <wp_profile_root>/bin directory to federate the primary node:
addNode.bat dmgr_hostname dmgr_port -includeapps -includebuses -username was_admin_user -password was_admin_passwordFor example:addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd
- On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.
- To configure the IBM HTTP Server with Single Sign-On, delete and re-add the webserver on the WebSphere Application Server Integrated Solutions Console in order to re-map all applications including Portal, and import the Portal certificate into IBM HTTP Server.
- Configure Tivoli Access Manager on the Portal server, following the directions in the topic Configure Tivoli Access Manager in the IBM WebSphere Portal product wiki. For example:
server task default-webseald-TAMhost.cn.ibm.com create -t ssl -b filter -A -F C:\WASLTPA.key -Z password -h DMhost.cn.ibm.com -c all -f -k -j -J trailer /wpsv70 ConfigEngine.bat run-svrssl-config -Dwp.ac.impl.PDAdminPwd=password ConfigEngine.bat validate-pdadmin-connection -DWasPassword=password -Dwp.ac.impl.PDAdminPwd=password ConfigEngine.bat enable-tam-all -DWasPassword=password
Configure single sign-on for portlets with Siteminder and SPNEGO
Configure IBM Connections portlets to use single sign-on with Computer Associates' SiteMinder and SPNEGO.
- Enable Siteminder and SPNEGO for IBM Connections, following the steps in Enabling Siteminder and SPNEGO.
- Enable and configuring single sign-on for HTTP requests using SPNEGO following the steps in this topic.
- Configure SiteMinder following the steps in this topic.
- Merge all the keytab files to make the Deployment Manager aware of the SPNs for each node.
The following example demonstrates the procedure for merging keytab files.
Assuming that you have created the following keytab files:
- krb5.keytab on the Deployment Manager
- krb5NodeA.keytab on Node A
- krb5NodeB.keytab on Node B
Run the ktab command with the following switch:
-m source_keytab_name> destination_keytab_name
where source_keytab_name is the name of the keytab file on the source system and destination_keytab_name> is the name of the keytab file on the destination system.
Step 1: merge the keytab file on Node A into the keytab file on the Deployment Manager:
# ./ktab -m /etc/krb5NodeA.keytab /etc/krb5.keytab Merging keytab files: source=krb5NodeA.keytab destination=krb5.keytab Done!Step 2: merge the keytab file on Node B into the keytab file on the Deployment Manager:
# ./ktab -m /etc/krb5NodeB.keytab /etc/krb5.keytab Merging keytab files: source=krb5NodeB.keytab destination=krb5.keytab Done!For more information, go to the Use the ktab command to manage the Kerberos keytab file topic in the IBM WebSphere Application Server 7 information center.
- Configure the Virtual Member Manager (VMM).
For example:
- If you haven.t already done so, follow the instructions in Configuring portlets to use common directory services, to copy sonata.services.xml to <wp_root>\config\cells\<cell name>\
- Edit sonata.services.xml to use KerberosAuthenticator+ instead of DefaultAuthenticator.
- Add all IIS, Portal and Connections servers SPN as attributes.
<sonataServices name="KerberosAuthenticator+"> <attribute key="IISKerberosSPN" value="HTTP/wti-iis.spnego1.mul.ie.ibm.com@SPNEGO1.MUL.IE.IBM.COM"/> <attribute key="WebKerberosSPN" value="HTTP/dslvm326.spnego1.mul.ie.ibm.com@SPNEGO1.MUL.IE.IBM.COM"/> <attribute key="WebKerberosSPN" value="HTTP/dslvm442.spnego1.mul.ie.ibm.com@SPNEGO1.MUL.IE.IBM.COM"/> <attribute key="WASKerberosSPN" value="HTTP/dslvm443.spnego1.mul.ie.ibm.com@SPNEGO1.MUL.IE.IBM.COM"/> <attribute key="CookieTimeout" value="60"/> </sonataServices>
Configure single sign-on for portlets with SPNEGO
Configure IBM Connections portlets to use single sign-on with SPNEGO.
Single sign-on (SSO) enables users to log in to an IBM Connections application and switch to other applications within the product without having to authenticate again.
There are several different ways to configure SSO. This procedure describes an approach that uses the Kerberos authentication protocol. This authentication method allows users web browsers to prove their identities to one another in a secure manner. After users sign in to their Active Directory Windows client systems, they are automatically signed into IBM Connections.
Configure IBM Connections and WebSphere Portal to share a single Deployment Manager saves on administration time by combining administration tasks for the two applications. Establishing a single-sign on environment benefits the users by creating a more seamless environment between the two applications.
Follow these steps to configure single sign-on.
- Before federating Portal as a managed node of the Deployment Manager of IBM Connections, make sure the realms match between Connections Deployment Manager and Portal. If change the realm names so they match, follow the steps in Changing the realm name.
- Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:
- From the <wp_profile_root>/ConfigEngine directory of the primary node, run this task: ConfigEngine.bat collect-files-for-dmgr -DWasPassword=password . This creates a zip file containing all the files which need to be copied to the Deployment Manager. The zip file, named filesForDmgr.zip, will be placed in the <wp_profile_root>/filesForDmgr directory.
- Stop the Deployment Manager.
- Expand each of the files in the filesForDmgr.zip file into the proper location on the Deployment Manager based on the directory names within the zip file. The directory names in the zip file are based on the typical default directory names. The directory called AppServer/profiles/Dmgr01 is used to identify the Deployment Manager profile root, and the AppServer directory is used to identify the Deployment Manager installation root directory. If the Deployment Manager was installed into the default directory (AppServer) and the profile was created in the default directory (AppServer/profiles/Dmgr01), then the zip file can be expanded directly into the directory above the AppServer directory; for example /IBM/WebSphere.
- Start the Deployment Manager.
- To augment a Deployment Manager profile, run the following command from the <AppServer_root>/bin directory:
manageprofiles.bat -augment -templatePath c:/IBM/WebSphere/AppServer/profileTemplates/management.portal.augment -profileName Dmgr01
- Restart the Deployment Manager.
- Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.
- Run the following command from the wp_profile_root>/bin directory to federate the primary node:
addNode.bat dmgr_hostname dmgr_port -includeapps -includebuses -username was_admin_user -password was_admin_passwordFor example:addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd
- On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.
- To configure the IBM HTTP Server with Single Sign-On, delete and re-add the webserver on the WebSphere Application Server Integrated Solutions Console in order to re-map all applications including Portal, and import the Portal certificate into IBM HTTP Server.
- To Configure the same SPNEGO single sign-on for Portal and Connections.
- Create user for Portal host server on AD.
- Create keytab file for Portal server on AD:
ktpass -out path_to_keytab .princ SPN -mapuser account_name -mapOp set .pass account_passwordWhere:
For example:
- path_to_keytab is the file path where you want to store the generated keytab file.
- SPN is the Kerberos service principal name.
- account_name is the service account name.
- account_password is the password associated with the service account.
ktpass -princ HTTP/portal.cn.ibm.com@cn.ibm.com -out c:\portal.keytab -mapuser portaluser -mapOp set -pass Passw0rd
- Merge the portal keytab into the merged Connections keytab by running the ktab command with the following switch:
-m source_keytab_name destination_keytab_nameWhere:
For example:
- source_keytab_name is the name of the keytab file on the source system.
- destination_keytab_name is the name of the keytab file on the destination system.
c:\IBM\WebSphere\AppServer\java\jre\bin>ktab.exe -m y:\SPNEGO\portal.keytab y:\SPNEGO\merged.keytab
- Recreate the krb5.conf file using the new merged keytab file:
$AdminTask createKrbConfigFile { -krbPath appserver\java\jre\lib\security\krb5.conf -realm REALM -kdcHost kdc_hostname -dns dns_hostname -keytabPath path_to_keytab }For example:wsadmin.bat -user adminuser -password adminpwd $AdminTask createKrbConfigFile {-krbPath y:\SPNEGO\krb5.conf -realm CN.IBM.COM -kdcHost AD.cn.ibm.com -dns cn.ibm.com -keytabPath y:\SPNEGO\merged.keytab}
- Enable SPNEGO single sign-on by configuring Kerberos in the WebSphere Application Server Integrated Solutions Console, following the steps in the Enabling single sign-on for the Windows desktop topic.
- Synchronize the node and restart the Deployment Manager node. If you can not manage the Portal node on the WebSphere Application Server Integrated Solutions Console , manually synchronize the node and restart the Deployment Manager node.
Change the realm name
When you configure IBM Connections portlets to use single sign-on, you may need to change the Portal realm name to match the one used in IBM Connections.
- In the WebSphere Application Server Integrated Solutions Console, change the realm name. For example, from defaultWIMFileBasedRealm to AD.cn.ibm.com:389.
- Configure Portal to use the new realm name as the default realm:
- Use a text editor to open the wkplc.properties file, located in the <wp_profile_root>/ConfigEngine/properties directory.
- For defaultRealmName, type the realmName property value you want to use as the default realm.
- Save your changes to the wkplc.properties file.
- Run the following task from the <wp_profile_root>/ConfigEngine directory, to set this realm as the default realm:
./ConfigEngine.sh wp-default-realm -DWasPassword=password
- Stop and restart all necessary servers to propagate your changes.
- The default Portal administrator user ID is a file-based user ID which is unlikely to exist in your IBM Connections realm. Follow these steps to change the WAS/Portal administrator user ID to an available user ID in the IBM Connections realm.
- Run the following command from the <wp_profile_root>/ConfigEngine directory, to replace the existing WebSphere Application Server administrative user ID and group ID with the new user and group.
./ConfigEngine.sh wp-change-was-admin-user -DWasPassword=password -DnewAdminId=newadminid -DnewAdminPw=newpassword -DnewAdminGroupId=newadmingroupidYou must provide the full distinguished name (DN) for the newAdminId and newAdminGroupId parameters.
The task is intended to run against a running server. If the server is stopped, add the -Dskip.ldap.validation=true parameter to the task to skip the validation.
- Verify the task completed successfully. In a clustered environment, restart the deployment manager, the node agent(s), and WebSphere Portal servers. In a standalone environment, restart the server and WebSphere Portal servers.
- Run this task to replace the old WebSphere Portal administrative user ID and group ID with the new user and group:
./ConfigEngine.sh wp-change-portal-admin-user -DWasPassword=password -DnewAdminId=newadminid -DnewAdminPw=newpassword -DnewAdminGroupId=newadmingroupidYou must provide the full distinguished name (DN) for the newAdminId and newAdminGroupId parameters.
The task is intended to run against a running server. If the server is stopped, add the -Dskip.ldap.validation=true parameter to the task to skip the validation.
Enable basic authentication
Configure basic authentication for the IBM Connections portlets. Use basic authentication if you are not using single sign-on for authentication.
Configure basic authentication allows the manual entry of user credentials in the personalize mode of the portlets. Basic authentication for the portlets is only supported if single sign-on is not already enabled between WebSphere Portal and IBM Connections. If single sign-on is enabled, the basic authentication credentials entered in the personalize mode of the portlets will be ignored.
When using basic authentication for the portlets, every user must type in their personal credentials manually in the personalize mode of the portlets or shared credentials can be supplied from the Credential Vault.
If a user changes a valid user ID and password, the user must log out of Portal and log in again to refresh the credentials. If a user enters credential incorrectly, or updates an expired password, logging out and logging back in is not required.
- Set the authenticationMethod property to basicAuth in the file \WEB-INF\lcaccelerator\properties\lcaccelerator.properties in the deployed portlets war.
- Make sure your changes are applied to all cluster members. Apply changes in the WAR file, redeploy the WAR and synchronize the changes to all cluster members from the WebSphere deployment manager.
- If making changes directly to deployed applications, after saving the file, restart the portlets application or the application server(s).
What to do next
After you configure basic authentication, you can enable the portlets in one of the following ways:
- End users can log into portlets using the Personalize mode.
- The Portal administrator can configure the portlets using the credential slot
To configure the portlets through a system slot:
- In Portal Server Administration choose Administration > Access > Credential Vault.
- Click Add a vault slot.
- Choose a vault and vault segment from select dropdown.
- Choose a vault resource to associate with the system slot. If no vault resource is associated with the vault slot, create a new vault resource.
- Enter a vault slot name. This is the name that is seen in the configuration mode of the portlets.
- Check Vault Slot is shared.
- Enter a shared user ID and password to be stored in the system slot.
- (Optional) For Portal 8, the ADMIN_SLOTS virtual resource requires access permissions. Assign ADMIN_SLOTS "All Authenticated users" permissions. The ADMIN_SLOTS can be found under the virtual resource in the Resources Permissions Portlet
The settings on the personalize mode of the portlets will override the settings in configuration mode. To enable the personalize mode in the portlets, the Portal administrator must perform step 1 and enable basic authentication.
Update the portlet theme
Update the theme profile for the Connections portlets to functions properly.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 refresh to use this feature. If you are deploying on WebSphere Portal 7.0.0.2, this assumes you have deployed the fast theme, as described in this wiki article.
By design. the default themes for Portal 7.0.0.2 and Portal 8.0 do not load Dojo in view mode. This helps to render the theme faster. Because the Connections portlets use Dojo capabilities, you must update the default theme profile for the server you are using. If you do not, the Connections portlets will not work.
If you do not deploy these modules, you can still deploy and configure the Connections portlets on a Portal 7 server, but some features will not work as expected. You will not be able to deploy and configure the Connections portlets on a Portal 8 server. An error will warn you that the modules are missing.
- Follow the steps in this article to add the following modules to the default theme profile (profile_deferred.json): Portal 7.0.0.2:
Portal 8.0:
- wp_liveobject_framework
- dijit_form_16
- dijit_theme_tundra_16
- wp_liveobject_framework
- dijit_form_17
if you are using a custom profile, add the modules to that profile.
- Stop and restart the Portal server.
- To specify a theme profile at the page level you can override the default theme. For example, if the theme is using the profile_deferred.json profile, you can specify a custom profile for specific portal pages. Follow the steps for Set a profile override on a page.
Install the IBM Connections Portlets for IBM WebSphere Portal
Install the IBM Connections Portlets for IBM WebSphere Portal.
Use the portlets, you can access only those IBM Connections offerings that you have already installed and configured.
If you are installing the 3.0.1.1 version of IBM Connections Portlets for IBMWebSphere Portal, you must uninstall any previous versions of the portlets before you install. Upgrading from previous versions is not supported.
If you want to enable LTPA single sign-on between an IBM Connections feature and a WebSphere Application Server configured for stand-alone LDAP, complete the steps to enable single-sign on before beginning this procedure in the topic Configuring single sign-on.
When Single Sign-On is enabled between Portal and Connections, the Portal administrator who installs and configures the IBM Connections portlets should be a valid Connections user. For example the user you assign to manage the Virtual Member Manager, as described in the topic Set up an authentication alias for the IBM Connections portlets, can be made a Portal administrator following the steps in this topic. You can also create a Connections profile for the default Portal administrator in the IBM Connections profiles database by following the steps in the topic Add LDAP data to the Profiles database.
Anonymous Portal users can access the IBM Connections portlets and are treated as anonymous Connections users. However, authenticated Portal users must also be valid Connections users or they will get an error when trying to access a Connections portlet.
- Download the plug-in from the IBM Connections catalog at the following web site:
https://greenhouse.lotus.com/catalog.
- From your browser, log into IBM WebSphere Portal as an administrator. If the Portal server is part of a cluster, perform the installation on the primary node. If the server is stand-alone, use the Portal URL for the server. For example, http://HOST:10039/wps/portal.
- Click Administration > Portlet Management > Web Modules.
- Click Install.
- Extract the files from the snor.pf.portlets.zip file that you downloaded from the plug-in catalog.
- Browse to snor.pf.portlets.war.
- Click Next.
- Click Finish.
Under certain conditions, completing the installation results in the error message Lost track of the selected WAR file from the Browse button. Make sure it is on the disk and try again. If you encounter this error, see this solution on the IBM Support Portal for instructions on how to resolve the problem.
- Verify the portlets are successfully installed.
What to do next
After installing the portlets, do the following:
- Copy the Piece of Content (PoC) handler jar file ( com.ibm.lconn.lcaccelerator.poc.jar ) from <portlet install zip>/POCResolver to <PortalServer>/shared/app. You will need this file to establish communication between the portlets.
- Copy the jar file in the REP folder (com.ibm.lconn.lcaccelerator.rep.jar) from <portlet install zip>/REP to the <PortalServer>/shared/app directory.
- If your Portal server is deployed on a cluster, copy each jar to the Portal nodes.
Configure the portlets on a page
Configure the IBM Connections portlets on a WebSphere Portal page.
Restriction: Do not place multiple instances of the same portlet on a page. For example, putting two blog portlets on a page might result in unexpected behavior and is not supported.IBM Connections portlets may be configured on multiple pages with different filtering and display options. Community Pages (see Community Pages) affect portlets configured on those pages. By default, IBM Connections portlets placed on a community page filter the user's view to display content from that community. A link to a piece of content from a community resolves to a community page if there is an appropriate portlet to display the content on a matching community page. For example, if the Blogs portlet is configured on a "New Employees" community page, the page renders a link in WebSphere Portal to blog entries from that community (see Addressing IBM Connections content). If an appropriate community page is not found, links to the content in WebSphere Portal use a set of default pages to display IBM Connections content.
You can organize these pages any way you like and can even hide them from your Portal site's main navigation so that users can not directly navigate to them. The following procedure creates one page for each service under a label named "IBM Connections" under the pre-defined "Home" page in WebSphere Portal. You can move the Connections pages or create them elsewhere in your WebSphere Portal site structure. It is only important that the unique names for these pages remain the same.
- Define a label to contain the default pages.
- Define a label to contain the default pages.
- Click Administration > Portal User Interface > Manage Pages.
- Navigate to the page where you want to add a portlet. For example, navigate to Home.
- Click New Label. A label is a container for WebSphere Portal pages that does not itself contain content. Alternatively, create a page if you want to place portlets or content on this page.
- Enter IBM Connections for the title.
- Click OK.
- Define page unique names that indicate the portal page users are directed to in order to view content from the Connections services. These unique names are used in the Content resolver component that handles the Portal page look up The lookup retrieves the appropriate page when a user selects Connections search results from the WebSphere Portal Search Center, selects items from the Connections summary portlets, or uses the URLs described in the Addressing IBM Connections content section. For each of the rows in the table, do the following:
- Define a page for each service to serve as a default page for content of that type.
- Click on the IBM Connections label you created in the prior step.
- Click New Page, enter the title and unique name and create the page by clicking OK. The are suggested names, but you can modify them for your deployment.
Table 89. Suggested page and portlet titles
Page Title Unique Name Portlet Title Profiles ibm.conn.profiles Profiles Activities ibm.conn.activities Activities Blogs ibm.conn.blogs Blogs Bookmarks ibm.conn.bookmarks Bookmarks Forums ibm.conn.forums Forums Wikis ibm.conn.wikis Wikis Do not deploy an Activities portlet or a Forums summary portlet on an anonymous page. The portlet page must require users to authenticate.
- Optional: You may need to use different unique names than the ones specified. Using different unique names might be useful if you want to deploy multiple detail portlets to the same page, or if you have existing unique names assigned to pages for other reasons. If you do, copy com.ibm.lconn.lcaccelerator.poc.properties from the /POCResolver folder from the location where you extracted the Connections Portlets download package and place the file in <wp_profile>/properties. To override the unique name expected for a specific portlet, edit the property that corresponds to the detail portlet on the page. For example, blogs=blogs.example.page indicates that users should be navigated to this page to view content from Blogs
- Optional: Using the com.ibm.lconn.lcaccelerator.poc.properties file from step d, you can also specify an error page. The error page is used if the portlets cannot find an appropriate Portal page to display a piece of content. Use the key error.page in the properties file to indicate the unique name for your error page. The default value of the unique name of the error page is ibm.conn.navigation.error.
This error page is used when a page cannot be found to display a piece of content or community, such as when no community page exists for some community but a link to that community is clicked. This might happen from search results if community pages do not exist for all communities.
- Optional: Using the com.ibm.lconn.lcaccelerator.poc.properties file from step d, you can also specify a different application ID for the portlet application using the key ibm.conn.portlets.app.id. If not specified, the default value is com.bowstreet.portlet.WebAppRunner2_snor.pf.portlets.
- Add portlets to corresponding pages:
- Click on the pencil icon (Edit Page Layout) next to a page.
- Click Add Portlets.
- Set the portlet title in the Search box and click Search.
- Select the check box next to the appropriate portlet, then click OK.
- Click Done.
- Follow these steps to give users access to the page.
- Navigate to Administration > Access > Resource Permission > Pages > Content Root. Navigate to the first page that contains an IBM Connections Portlet.
- Click the Assign Access button for the entry. For example, to allow non-admin users to access the portlets, set the role "Privileged User" to "All authenticated users." To allow anonymous access, set the role "User" to "Anonymous Portal User."
- Click on Apply and then Done.
- Repeat Steps a-d for each page that contains an IBM Connections Portlet.
Page access may be inherited. If page access is not inherited in your site structure, click on the key icon (Edit access) next to each page and add at least user access for each user or group that will need to view Connections content in WebSphere Portal.
- Follow these steps to give users access to the portlets.
- Navigate to Administration > Access > Resource Permission > Portlet Applications.
- Search for com.bowstreet.portlet.WebAppRunner2_snor.pf.portlets or the name of the portlet application if you have customized.
- Click Assign Access for the entry and assign users, groups or virtual groups to the portlet application. For example, to allow non-admin users to access the portlets, set the role Privileged User to All authenticated users.
You may use groups other than all authenticated users if you want only a subset of site users to access the Connections portlets. Even if a user cannot access the portlets directly, the user may be able to access Connections content through service APIs from IBM Connections and WebSphere Portal and via other interfaces including but not limited to search and mobile clients. If you do not want a user to use Connections or see certain Connections content, set up Connections security on the Connections server to exclude that user.
- To allow anonymous access, set the role User to Anonymous Portal User.
- Click on Apply and then Done.
Set public render parameter-sharing for the IBM Connections portlets
If you are using the 3.0.1.1. Version of the IBM Connections portlets, you can set public render parameter sharing for the IBM Connections Portlets. These parameters communicate what content to render when navigating between portlets and from IBM Connections content accessed from the search center portlet.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 to use this feature.
The IBM Connections detail portlets use public render parameters to communicate what content to render when navigating between the portlets and from IBM Connections content accessed from the Search Center portlet. The default sharing scope for all public render parameters is the global scope. To prevent sharing of public render parameters between pages and to avoid undesirable behavior in rendering content in the portlets, define a unique scope for each page that contains an IBM Connections detail portlet.
For information on defining scopes for public render parameters, see this article on Public Render parameters in the IBM WebSphere Portal wiki.
Configure the application-specific AJAX proxy to support authentication
Configure the application-specific AJAX proxy to manage authentication for the IBM Connections portlets.
IBM Connections portlets now use an application-specific AJAX proxy as the mechanism for forwarding security headers and cookies with each REST service call to authenticate the request with the Connections server. You can configure the AJAX Proxy to forward LTPA token and the appropriate headers for an environment configured to use a Tivoli Access Manager or SiteMinder security proxy.
This task presents the steps to enable the default setting to forward the LTPA. For more information on configuring a proxy, see the following articles in the IBM WebSphere Portal product documentation:
If you use customized cookie names for single sign-on (this is not common), refer to the WebSphere Portal documentation for altering AJAX proxy policies to include additional cookies.
You must list the IBM Connections server to be accessed as an allowed request target in the AJAX proxy configuration. The recommended way of enabling this access is to map the URL pattern for the IBM Connections server to ibm_connections_policy dynamic policy using the WP ConfigService configuration service.
- List the IBM Connections server you plan to access as an allowed request target in the AJAX proxy configuration. The recommended way of enabling this access is to map the URL pattern for the Lotus Connections server to ibm_connections_policy dynamic policy using the WP ConfigService configuration service.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resources > Resource Environment > Resource Environment Providers.
- Click WP ConfigService.
- Under Additional Properties, click Custom Properties.
- Click New, and enter the property name wp.proxy.config.urlreplacement.ibm_connections_policy.default.connections.server.http, and set the string value to the HTTP URL pattern of the IBM Connections server. For example:
http://connections_hostname:http_port_number/*
- Click New, and enter the property name wp.proxy.config.urlreplacement.ibm_connections_policy.default.connections.server.https and set the string value to the HTTPS URL pattern of the IBM Connections server.
https://connections_hostname:https_port_number/*
- Save the property changes.
- Map the security roles for everyone and all authenticated users on the proxy servlet.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Applications > Application Types > WebSphere enterprise applications.
- Click PA_WPF or the name of your portlet Web application if you changed the name.
- Click Security role to user/group mapping.
- Check Everyone Role and click Map Special Subjects > Everyone.
- Check All Role and click Map Special Subjects > All Authenticated in Application.s Realms.
- Click OK.
- Save the changes.
- Restart the WebSphere Portal Server.
The URL patterns used in this step must match those used in the topic Configuring WebSphere environment variables.
What to do next
Use the following test URLs to verify that the application-specific proxy configuration is working.
If you are in an SSO environment you must first open a new browser window and log into Portal as a Connections user.
If you have a web server configured for Portal as well as Connections, use: http://<WP_Server>/wps/<CONNECTIONS_PORTLETS_CONTEXT_ROOT>/proxy/https/<CONNECTIONS_SERVER_BASE_URL>/profiles/atom/profileService.do
For example http://myportalwebserver/wps/PA_WPF/proxy/https/myconnectionswebserver/profiles/atom/profileService.do
If you have a web server configured for Connections but not for Portal, use: http://<WP_Server:Port>/wps/<CONNECTIONS_PORTLETS_CONTEXT_ROOT>/proxy/https/<CONNECTIONS_SERVER_BASE_URL>/profiles/atom/profileService.do
For example http://myportalserver:10039/wps/PA_WPF/proxy/https/myconnectionswebserver/profiles/atom/profileService.do
If you do not have web servers configured for either Portal or Connections, use: http://<WP_Server:Port>/wps/<CONNECTIONS_PORTLETS_CONTEXT_ROOT>/proxy/https/<CONNECTIONS_SERVER_BASE_URL:port>/profiles/atom/profileService.do
For example http://myportalserver:10039/wps/PA_WPF/proxy/https/myconnectionsserver:9444/profiles/atom/profileService.do
In an SSO environment:
- If you are prompted to save or open a document or a feed renders in the browser, then the proxy has been properly configured.
- If you are prompted to enter a user name and password, then the proxy has been properly configured but SSO is not enabled.
- If you receive a 403 error in response then the proxy is not properly configured.
- If you receive a 500 or any other response code, this means the proxy was properly configured but something else is not working.
In a non-SSO environment:
- Enter the user name and password of a Connections user.
- If you are prompted to save or open a document or a feed renders in the browser, then the proxy has been properly configured
- If you receive a 403 error in response then the proxy is not properly configured.
- If you receive a 500 or any other response code, this means the proxy was properly configured but something else is not working.
If you receive a 404 or Page Not Found error, check the context root of the Connections portlets. If you have other Web Experience Factory portlets installed, you might need to change from PA_WPF to PA_WPF_1 or PA_WPF_X where X is some number.
Uninstall the IBM Connections portlets
OPTIONAL: If you no longer want the Portlets installed, you can remove them from IBM WebSphere Portal. For information on uninstalling portlets, see the following topic in the IBM WebSphere Portal information center: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/index.jsp?topic=/com.ibm.wp.ent.doc_v6101/admin/adpltadmwork.html.
If you are removing all of the IBM Connections portlets, you will remove the snor.pf.portlets.war file installed as part of the deployment.
Optional and recommended configuration
Depending on your deployment, follow these steps to optimize the IBM Connections portlets.
The following are some optional configuration steps you can take to enhance the deployment of IBM Connections portlets for IBM WebSphere Portal.
Community Pages
In 3.0.1.1, you can integrate Connections Communities into your Portal site to enhance your portal's social collaboration capabilities.
You integrate Communities by associating a set of portal pages with a community. These types of portal pages are called Community Pages. By associating a set of portal pages with a community in Connections, all of the Connections portlets on those pages will automatically render their content within the context of that Community. One or more communities can be integrated into your portal site. You can associate different sets of pages in your portal site with the appropriate community. The community can be public, moderated or private.
Before you add portlets to a community page, make sure that the corresponding widget exists in the community. For example, before you add a Blogs portlet to a community page, make sure the IBM Connections community contains a blog. If not, add the Blogs widget to the IBM Connections community using the browser interface.
Restriction: Ideation blogs are not supported for community pages. If your IBM Connections community contains an Ideation blog widget, it will not display if the Blogs portlet is deployed on a community page.Some of the ways the portlets on a Portal community page interact with an IBM Connections community include:
- Clicking on a profile user name or photo in a Profiles summary portlet displays profile detail in the target portlet.
- Clicking on a View all link in a Profiles summary portlet displays a list of community members in the target portlet. Note that this link only works if there is a Profiles detail portlet on the page.
- Clicking the View all link in a Blogs summary portlet displays all entries in a community blog in the Blogs detail portlet on a community page.
- Clicking on the entry in a Blogs summary portlet displays the detail of that entry in the Blogs detail portlet on a community page.
- When a user hovers over an entry in a Blogs summary portlet, a pop-up displays, with a link allowing a user to read the entry.
- Clicking Read for an entry in the Blogs summary portlet shows the selected entry details in the Blogs detail portlet.
Follow the steps for configuring and mapping community pages for your version of IBM WebSphere Portal.
Map a community page to a community
Map a community page to an IBM Connections community so the portlets can interact with community content.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 to use this feature.
Follow the steps to map the community pages to a community based on what WebSphere Portal Server you are using.
- To map community pages to a community on a WebSphere Portal 7 server:
- Log into Portal as an administrator.
- Navigate to the page to map to a community.
- Click Actions > Edit Page Properties.
- Expand the Advanced options section and click I want to set parameters.
- Add the following new parameters:
Parameter Key Parameter Value ibm.community.id The ID of the connections community. To get this value, open the Connections community in a browser and copy the ID following communityUid= in the community URL. ibm.community.home Set to TRUE if the page is identified as the home page for the community. There can be only one home page. In the case where there are multiple homepages set, the first page is selected. ibm.community.page Set to FALSE if this is the home page; otherwise, set to TRUE. If you are creating a page which has a parent page that is mapped to a community, follow steps c and d , but you must explicitly set the parameters set in step e. To do this, click the Edit icon for each parameter, click OK, then explicitly set the parameters.
- To map community pages to a community on a WebSphere Portal 8 server, create a community association using the XML configuration interface (xmlaccess command). When defining the association in the XML import file, use the <content-mapping-info> element, and specify a content mapping scope of ibm.connections for an individual nested <content-mapping> element. For details and an example, refer to the topic on Manage community associations in the WebSphere Portal product wiki.
- Assign access to the page. If the community has restricted membership, you can secure the page so that only members of the community can see the page in the Portal navigation. You can also access assign on community pages mapped to public or moderated communities, but doing so does not restrict access to the content in the community. There are other mechanisms, including APIs, mobile clients, connectors and search and portlets on other pages which may expose the content outside the community page. Membership lists in Connections communities should have the correct level of access to community content and Portal pages should reflect that level . Before you use communities for access control on pages, follow the steps in Integrating community membership with Portal security.
- Navigate to Administration > Manage Pages and find the community page for which you want to set access.
- Click Set Page Permission (lock icon).
- Uncheck Allow Inheritance for all rows and click Apply.
- Click on the Edit Role button in the Privileged User and User columns and make sure no users or groups are added that you do not want to access this page.
- Click on the Edit Role button in the Privileged User or User column, depending on what level of access you want to grant to community members. See the Roles topic for a description of roles in WebSphere Portal.
- Click Add.
- Change Search by to displayName.
- Enter the name of the community in the search box and click Search.
- Check the box next to the group representing the community and click OK. If successful, the group appears in the list of members in the role and a message indicates that the members were successfully added to the role.
- Before adding portlets to your community page, make sure that the corresponding widget exists in the community. For example, before you add a Blogs portlet to the community page, make sure the IBM Connections community contains a blog. If not, add the Blogs widget to the IBM Connections community using the browser interface.
What to do next
If the portal administrator configures a portlet with a new connections server URL for a community page, then the changes will take effect only after the community page is configured with a valid community ID for the new connections server, by editing the portal page parameters settings to include the new community ID.
Integrate community membership with Portal security
Configure the Virtual Member Manager to integrate information from IBM Connections communities with your WebSphere Portal environment.
Starting with version 6.1, IBM WebSphere Application Server uses a component called Virtual Member Manager (VMM) to manage information about community membership. VMM provides an interface that enables communication between WebSphere Portal and any repository, whether federated repositories, a stand-alone repository, or your own custom user registry. You can configure VMM to recognize IBM Connections as a repository so that Portal can access community user and group information from IBM Connections communities. For example, once this is configured, users will be able to select IBM Connections private or public communities as groups when assigning security roles or access rights.
For more information about the architecture of VMM, see this article from the IBM WebSphere Portal wiki.
For more information about configuring a user repository for VMM, see this white paper from IBM Developer Works.
After configuring IBM Connections to work with VMM, user can:
- Search for IBM Connections public and private communities by name (represented as groups in WebSphere)
- Resolve public and private community membership for particular users (represented as group membership in WebSphere)
- Display the WebSphere users that are members of a particular IBM Connections public or private community
The following are some known limitations:
- When using the VMM get operation to get a single identifier and querying by name, instead of using the unique externalID, nothing will be returned if more than one community name matches the query.
- The operation to display WebSphere users that are members of a particular IBM Connections community can have a perfromance impact for large groups.
- Tivoli Directory Integrator is recommended for populating user data into Connections. When using the profile data population wizard, a user's email may not be populated into the Communities database. Consequently, a user may not appear in the proper communities until they have logged into Communities, used a feature from the Communities service, or their profile has been synchronized with Tivoli Directory Integrator.
Prerequisites
In order to configure the VMM to recognize an IBM Connections repository, the following must be true:
- IBM WebSphere Portal must be completely installed and verified
- IBM Connections must be completely installed and Search has to be verified to work
- IBM Connections must have email enabled if you are using IBM Connections Portlets for Portal 3.0.1.1. If you have upgrade to the 3.0.1.1 refresh, you do not need to have email enabled. Hidden email is supported.
- Single sign-on should be configured between Connections and Portal. Follow the steps in Configuring single sign-on.
- IBM Connections and WebSphere Portal must share a common LDAP.
- Import the SSL certificate from WebSphere Portal server to IBM Connections. Follow the steps in Importing a certificate to support SSL with the following differences:
- Log into the WebSphere Application Server Integrated Solutions Console for the Connections server, rather than the Portal server.
- Enter the host, port and alias for the Portal server. For example:
Host : portal.example.com Port : 10025 (SOAP default port on Portal. Please specify appropriate port if non default is used) Alias : Portal Certificate (Admin can choose any appropriate alias)
- If you are deploying on WebSphere Portal 7.0.0.2, install Fixpack PM51981 to avoid problems with private community pages. You can download the Fixpack from Fix Central.
- Update the VMM schema so that PersonAccount includes ibm-entryUuid <personCorrelationAttribute>. To open the scripting interface , refer to "Opening a console window for interactive scripting" in this article. In the scripting interface , enter the following commands
$AdminTask addIdMgrPropertyToEntityTypes {-name ibm-entryUuid -dataType string -entityTypeNames PersonAccount} $AdminConfig savePortal must be running while you execute this command. Restart the server to apply the changes.
Configure the IBM Connections repository to work with VMM
Complete these tasks to configure the IBM Connections User Repository Adapter. When configuration is complete, you can verify that it is working by logging in to WebSphere Portal as an administrator. Open the Users and Groups portlet from the Administration tab. Search for groups that should be present as communities in your IBM Connections deployment. If you find the correct groups and the members of the groups are listed, the deployment is successful.
Deploying libraries for the IBM Connections portlets
Deploy libraries required to integrate information from IBM Connections profiles and communities with your WebSphere Portal environment.
Follow these steps for deploying libraries.
In a cluster environment, copy libraries on the Deployment Manager and on every node.
- For Portal 7.0.0.2 with a separate Deployment Manager:
- Copy jars from CommunitiesVMM/vmmAdapterMain to AppServer/lib/ext directory
- Copy jars from CommunitiesVMM/vmmAdapterFilter to PortalServer/shared/app
- For Portal server 6.1.5.3 with a separate Deployment Manager:
- Copy jars from CommunitiesVMM/vmmAdapterMain to AppServer/lib/ext directory
- Copy jars from CommunitiesVMM//vmmAdapterPortal6AdditionalLibs to AppServer/lib/ext directory
- Copy jars from CommunitiesVMM/vmmAdapterFilter to PortalServer/shared/app
For Portal nodes, follow the steps for separate Deployment Manager, even if a common Deployment Manager is configured.
- For Portal server 7.0.0.2 with a common Deployment Manager, copy jars as follows on the Connections and Deployment Manager nodes:
- AppServer/lib/ext:
- com.ibm.ws.wim.adapter.base.jar [location: CommunitiesVMM/vmmAdapterMain]
- com.ibm.ws.wim.adapter.connections-forwarding.jar [location: CommunitiesVMM/vmmAdapterForwarding]
- AppServer/lib/ext/vmm:
You must manually create the vmm directory.
- Jars from CommunitiesVMM/vmmAdapterMain [exclude: com.ibm.ws.wim.adapter.base.jar ]
- PortalServer/shared/app
- Jars from CommunitiesVMM/vmmAdapterFilter to PortalServer/shared/app
- For Portal server 6.1.5.3 with a common Deployment Manager, copy jars as follows on the Connections and Deployment Manager nodes:
- AppServer/lib/ext:
- com.ibm.ws.wim.adapter.base.jar [location: CommunitiesVMM/vmmAdapterMain]
- com.ibm.ws.wim.adapter.connections-forwarding.jar [location: CommunitiesVMM/vmmAdapterForwarding]
- AppServer/lib/ext/vmm:
You must manually create the vmm directory.
- Jars from CommunitiesVMM/vmmAdapterMain [exclude: com.ibm.ws.wim.adapter.base.jar ] -
- Jars from CommunitiesVMM//vmmAdapterPortal6AdditionalLibs
- PortalServer/shared/app
- Jars from CommunitiesVMM/vmmAdapterFilter
Configure a Resource Environment Provider for IBM Connections portlets
You must add IBM Connections server URLs to the WebSphere Resource Environment provider before you can add an IBM Connections repository to the Virtual Member Manager.
Copy the com.ibm.ws.wim.adapter.connections.filter.jar file to the \\Portalserver\shared\app folder.
Ensure you have followed the previous steps in Deploying libraries for the IBM Connections portlets before performing this configuration or your server may fail to start after setting these parameters.
Add any allowed IBM Connections server URLs. For example, if the server allows http and https URLs, add both.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resources > Resource Environment > Resource Environment Providers.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- If the WP ConnectionsIntegrationService already exists, click on it. If not, click New, specify WP ConnectionsIntegrationService, and click Apply.
- Click Custom Properties.
- Click New and configure the following attributes:
Name Description Type personCorrelationAttribute (formerly personRdnAttribute) Set the corresponding person relative distinguished name attribute. In case the personCorrelationAttribute is of type uniqueId, its value should be the ldap attribute which is mapped to the Profile Database field that represents the unique id. For example, if the unique id is represented by the guid profile database field, and this field is mapped to the ibm-entryUuid LDAP attribute, then use ibm-entryUuid as the value for the personCorrelationAttribute. java.lang.String personCorrelationAttributeType Assign a value of mail or uniqueId to specify whether the correlation attribute represents an email address or unique identifier. java.lang.String communityRdnAttribute Set the corresponding community relative distinguished name attribute. For example, cn. java.lang.String maxSearchResults A maximum of results the connections repository will return on a single query. For example, 120. java.lang.String J2CAuthAlias The auth alias name as noted in Step Authentication Alias Configuration. For example, cell/dsxAdmin java.lang.String ldapTypeTDS Specify True if you are using TDS as your LDAP, or specify False if you are using a different LDAP, for example, Microsoft ADS or Novell DS java.lang.String mailProperties (No longer needed. Maintained for backward compatibility.) Specify all possible mail properties. For example, mail,ibm-primaryEmail java.lang.String
- Optional: Optionally alter the default cache settings and add these to the configuration of the environment variable you configured in the topic Configuring the resource environment provider as part of the installation process. If a user is added to a community through the IBM Connections user interface, the user may need to wait for caches to time out before seeing private community pages or other effects of joining the community in WebSphere Portal. IBM Connections uses three different caches:
The possible configuration options are:
- Communities: caches communities from IBM Connections based on the unique ID
- Members: caches members of a community from IBM Connections based on the unique ID
- Entities: caches repository entities (either group or person) based on their unique ID
Name Type Default communitiesCache.size java.lang.String 1024 communitiesCache.lifetime java.lang.String 600 membersCache.size java.lang.String 1024 membersCache.lifetime java.lang.String 600 entitiesCache.size java.lang.String 1024 entitiesCache.lifetime java.lang.String 86400 All lifetime values are specified in seconds. The cache size indicates number of elements.
- Save the new settings.
What to do next
Stop the server so that you can deploy the libraries and make changes to the XML configuration files.
Configure for impersonation: protecting user access
The impersonation feature lets you access another user's system as though you are that user so that you can test user access. .
If you haven.t already done so, copy the com.ibm.ws.wim.adapter.connections.filter.jar file to the \\Portalserver\shared\app folder.
Ensure you have followed the steps in Deploying libraries for the IBM Connections portlets before performing this configuration or your server may fail to start after setting these parameters. The impersonation feature lets you access another user's system as though you are that user.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resources > Resource Environment > Resource Environment Providers.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- If the WP ConnectionsIntegrationService already exists, click on it. If not, click New, specify WP ConnectionsIntegrationService, and click Apply.
- Click Custom Properties.
- Configure the following attributes:
Name Description Comment runAsAdmin false Values are true or false. The default is false. This attribute determines if adapter runs in admin mode or non admin In admin mode, whenever any (admin/non admin) logged-in user looks up a community, the user sees all communities from the Connections server. In non-admin mode, logged-in users will see only those communities which they have explicitly joined.
- Navigate to Resource Environment > Resource Environment Providers.
- Select All as the scope.
- Click WP PumaStoreService. You might need to page through results or apply a filter.
- Click Custom Properties.
- Click New and configure the following attributes:
Name Description Type store.puma_default.filter.principalFilter.classname com.ibm.connections.vmm.adapter.filter.VMMPrincipalFilter . Make sure you specify the class name or you will get errors when starting up Portal.
java.lang.String store.puma_default.filter.principalFilter.position 120 java.lang.String
- Restart the IBM Connections portlets application from the WebSphere Application Server console or restart the Portal server.
What to do next
To verify that impersonation is configured correctly:
- Login as any non-admin user
- Create a page, for example, JonesxxPage.
- Click Actions > Share page.
- Select Group search from drop down
- Enter a search string and verify that the results come from communities the user belongs to rather than from all communities.
- Perform a similar test for each node.
Configure the IBM Connections repository for VMM
This task is done when the server is stopped. In a cluster, you can change the configuration files directly on the deployment manager and then synchronize the changes to all cluster nodes. The wimconfig.xml file governs a single ID attribute for all supported objects such as users, groups, and organizations in WebSphere Application Server. You can use LotusConnections-config.xml to override the ID attribute in the wimconfig.xml file. For example, you could use the wimconfig.xml file to specify the ibm-entryUUID attribute as the ID Key attribute for users and groups in all applications running on WebSphere Application Server, and then modify LotusConnections-config.xml to specify the employeeID as the ID Key attribute for IBM Connections applications.
- Add the repository configuration to the wimconfig.xml in the<profile_directory>/config/cells/local.cell/wim/config directory. Insert the following lines below the config:configurationProvider level:
<!-- Connections Repositories --> <config:repositories adapterClassName="com.ibm.ws.wim.adapter.connections.ConnectionsAdapter" id="connections" isExtIdUnique="true" supportExternalName="false" supportPaging="false" supportSorting="false" supportTransactions="false"> <config:baseEntries name="o=connections" nameInRepository="o=connections"/> </config:repositories> <!-- Connections Repositories End -->
- The same base entry must also be added to the default realm, and optionally, to all the user realms that contain softgroups: The base entry specification defines the base distinguished name/suffix for the connections communities inside VMM and may be set to a different value. The name and the nameInRepository should be the same. The same base entry must also be added to all the user realms that should contain softgroups, at least the default realm:
<config:realmConfiguration defaultRealm="defaultWIMFileBasedRealm"> <config:realms delimiter="/" name="defaultWIMFileBasedRealm" securityUse="active"> <config:participatingBaseEntries name="o=defaultWIMFileBasedRealm"/> <config:participatingBaseEntries name="o=connections"/> <config:uniqueUserIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/> <config:userSecurityNameMapping propertyForInput="principalName" propertyForOutput="principalName"/> <config:userDisplayNameMapping propertyForInput="principalName" propertyForOutput="principalName"/> <config:uniqueGroupIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/> <config:groupSecurityNameMapping propertyForInput="cn" propertyForOutput="cn"/> <config:groupDisplayNameMapping propertyForInput="cn" propertyForOutput="cn"/> </config:realms> </config:realmConfiguration>
- For the other configured repositories such as the main LDAP repository, add the Connections repository as a group repository with the following line:
... <config:repositoriesForGroups>connections</config:repositoriesForGroups> ...
What to do next
To verify that the adapters started correctly, do the following:
- Look for the following type of informational message in the SystemOut.log:
ConnectionsLo I CLVPA0006I: Successfully initialized Connections Lookaside Adapter for IBM Connections Profiles (implementation version = 1.0.0, build date = 2011/02/02 23:44:24) ConnectionsAd I CLVCG0005I: Successfully initialized Connections Adapter for IBM Connections Communities (implementation version = 1.0.0, build date = 2011/02/02 23:44:24)If there are warning messages, such as:ConnectionsLo W CLVPA0005W: Could not access IBM Connections Communities server with the given URL https://connections-server:9449/communities! Reason = ...verify that the IBM Connections server is started and available from the Application Server with the given URL and credentials.
- Log in to WebSphere Portal as administrator and open the Users and Groups portlet from the Administration tab. Search for groups that should be present as communities in the IBM Connections installation. The adapter is working if you can confirm that the correct groups are listed and the members of the groups are also listed. If there are groups or members missing, verify the SystemOut.log for error messages. Usually this is a configuration issue (for example, a problem with the name attribute) or the user repository of WebSphere does not contain all the users registered in Profiles.
Configure search integration
IBM Connections search integration in IBM Websphere Portal allows users to perform search queries and view query results for IBM Connections content within the context of their portal environment.
This feature requires the 3.0.1.1 version of IBM Connections Portlets for IBM Websphere Portal.
This integration point is enabled by configuring the portal search center component to include IBM Connections content as part of the related search results. You also need to configure a component to allow the navigation from the portal search center to the portlets so that users can view the Connections related search results.
Understand the search architecture
Portal currently provides the following two search frameworks. The one you use depends on whether you value performance or ease of maintenance.
- Search Service
- Search Service is a live search and leverages REST (along with other technologies ) to search on a target information source and fetch the matching results. Connections/Portal integration uses the "Remote Content Server Search Service Type" (referred to as RCSS type), leveraging the ATOM/REST APIs exposed by Connections. This approach would tag relevance score of connections content, in isolation, to the portal relevance score. It is a federated approach in which the search is federated between Portal and Connections instances.
- Search Collections
- Search Collections uses a seedlist framework to crawl and index all of the Connections data locally on a Portal server. The advantage of this approach is that it removes extra network traffic to the Connections server during the search process, making information retrieval fast. One disadvantage is that the crawler needs to run frequently to synchronize local content with all the latest content on the Connections server. It can do a better relevance ranking of search results, as search results (including Portal and Connections) are served by the Portal engine only.
When you are configuring Search, note the following repositories
...where files are stored:
- Icons ( DisplayProvider/icons ) must be copied to <wp_profile>/installedApps/NODE_NAME/wps.ear/wps.war/images/icons
- Display provider plug-in (DPP) jar file ( com.ibm.lconn.lcaccelerator.dpp.jar ) from <portlet install zip>/DisplayProvider must be placed in <PortalServer>/shared/app
- Piece of Content (PoC) handler jar file ( com.ibm.lconn.lcaccelerator.poc.jar ) from <portlet install zip>/POCResolver must be placed in <PortalServer>/shared/app .
Excluding Connections Portlets from Portal default search indexing
Exclude the Connections portlets from the default Portal search indexing.
If you are integrating with WebSphere Portal 8.0, portlets are excluded from portal search by default and you do not need to specifically exclude them.
By default, on WebSphere Portal 7.0 servers, the Portal search crawler crawls all the portal pages and active portlets lying on them. Since IBM Connections uses its own seedlists for search, you can exclude the Connections portlets from the default portal indexing. The default crawler user is the default Portal admin user. This user might not be a Connections user, so in order to exclude the IBM Connections Portlets from the Portal indexing; this user should not have access to Connections portlets. To achieve this, create a separate group which lists all Connections users who should have access to IBM Connections portlets. Make sure that the crawler user is not part of this group. IBM Connections portlets should be assigned access permission to this group instead of to the 'All Authenticated Portal users group'. This way when the crawler runs, the default portal indexing will exclude IBM Connections portlets.
Configure search using Remote Content Server Search Service Type (RCSS)
Use the Remote Content Server Search Service Type (RCSS) to implement live search for IBM Connections content from an IBM WebSphere Portal application.
Consider these issues before you configure RCSS:
Search Service is a live search and leverages REST to search on a target information source and fetch the matching results. IBM Connections and WebSphere Portal integration uses RCSS to leverage the ATOM/REST APIs exposed by IBM Connections. This approach correlates a relevance score for IBM Connections content with the Portal relevance score. It is a federated approach where the search is federated between Portal and IBM Connections instances.
- RCSS search is not supported when your deployment is configured to use Tivoli Access Manager and SPNEGO or Computer Associates' SiteMinder and SPNEGO.
- Users who are registered in an LDAP that is common between IBM Connections and WebSphere Portal should be granted administration rights in Portal to configure RCSS using scopes API over http.
- Click the Administration link in the header of the portal page.
- In the Manage Search section, click New Search Service.
- Name the service appropriately so that it is easily identifiable, provide this value in the Service Name field.
- Configure the search service using the following parameters. Possible values for the parameters are provided in the Parameter Value column.
Parameter Key Parameter Value SearchRequestUrl /atom/search/results RestServiceUnSecureUrl /search ContentType RemoteContent QueryParam includeportalcustomizations=true&query IgnoreAllSourcesSearch false RestServiceSecureUrl /search StartParam start AllSourcesParam scope QueryLangParam queryLang DisplayProviderId ConnRCSS RequestLocaleParam locale LocationParam scope RequestLocationType /atom/scopes
- Log out and log in again before creating scopes for the RCSS service you configured.
What to do next
Troubleshoot: The RCSS component doesn't use the key store managed by WebSphere Application Server. If you try to set the RestServiceSecureProtocol property to https and the RestServiceSecurePort property to the SSL port for the Connections server when configuring the RCSS search service, you will not be able to retrieve the search scopes from Connections and thus will not be able to complete the search configuration. You will see SSL handshake errors in the WebSphere Portal SystemOut logs even though you imported the Connections SSL certificate into the WebSphere Application Server SSL certificate trust store. If you encounter this problem, follow the additional configuration steps documented in this tech note.
Configure a search collection
Search Collections uses a seedlist framework to crawl and index all of the IBM Connections data locally on a WebSphere Portal server.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 to use this feature.
Ensure these IBM Connections seedlists are available with basic authentication. Depending on your security configuration, this may be the default or may be accomplished with an additional virtual host in your HTTP server, by addressing a WebSphere node directly, or by altering Tivoli Access Manager or SiteMinder configuration to open a basic authentication protected endpoint. To configure a search collection, you specify one content source for each Connections seed list. Each Connections service (for example, Profiles, Communities, or Blogs) exposes its own seed list so there is one content source per Connections service.
- Click the Administration link in the header of the portal page.
- In the Manage Search section, click Search Collection.
- Click New Collection.
- Define the location of the collection on the portal file system and name it with an easily identifiable value.
- Click OK to create the collection and create the associated folders and files on the file system.
The path should not point to an existing directory.
- Click Collection to view the metadata of the collection created.
- Select Seedlist Provider as the Content source type.
- Provide the name and the seedlist URL of the Connections service. A Seedlist URL has the form: https://<connection_server_name>:port/<service_name>/seedlist/myserver For example: https://connections.ibm.com:9444/activities/seedlist/myserver.
If IBM Connections is configured to use Tivoli Access Manager and SPNEGO security, or just SPNEGO, configure the seedlist URL and host without TAM, using IHS host only.
- Click the Security tab and enter your Connections administrator credentials, so that you can access the specific service seedlist URL.
- Click Create to create the corresponding Content Source to enable crawling over the service defined.
- Create other Connections services Activities, Blogs by repeating steps 1 - 10.
You can either select to run the crawler on the complete set or on individual service
- Ensure these seedlists are available with basic authentication. Depending on your security configuration, this may be the default or may be accomplished with an additional virtual host in your HTTP server, by addressing a WebSphere node directly, or by altering Tivoli Access Manager or SiteMinder configuration to open a basic authentication protected endpoint.
Set the Search Scope
Define search scopes for the content from IBM Connections that is returned from a search in IBM WebSphere Portal applications. Once the service/collection is defined, search scopes can be optionally defined. This search scope is available to the end user, after the setup and primarily facilitate defining different level of granularity at which the search is executed from the Portal user interface.
- Click the Administration link in the header of the portal page.
- In the Manage Search section, click on Search Scope.
- Click New Scope.
- Specify a name for the scope and click Select Location, to select the services and collections to include. This view allows you to mix and match various services and content sources and to define the granularity of the search scope being defined.
Display action buttons and links for anonymous users
Edit style sheets to display action buttons and links for anonymous users.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 refresh to use this feature. By default, some action buttons or links in anonymous view, such as Login to Start a Wiki, Login to Start a Forum or Login to Flag as Inappropriate do not display for anonymous users. If you want anonymous users to see these buttons and links, you must edit the style sheets to display the action buttons. After changing the styles in the style sheet, the following actions display in portlets for users who access the portlets anonymously:
- Wikis . Login to Start a Wiki
- Forums . Login to Start a Forum
- Forums . Login to Start a Topic
- Blogs . Login to Flag as Inappropriate
- Open the stylesheet connectionsportlet.css or connectionsportletRTL.css from the lcaccelerator\css folder where the Connections portlets are installed.
- For any component to display action buttons for anonymous users, change the attribute display from none to inline. The choices are:
.activitiesAnonymous{ display:none; } .wikisAnonymous{ display:none; } .blogsAnonymous{ display:none; } .dogearAnonymous{ display:none; } .forumsAnonymous{ display:none; } .profilesAnonymous{ display:none; } .copAnonymous{ display:none;
Conditional Loading of the Lotus CSS bundle
If you are using 3.0.1.1, load the IBM Connections portlets CSS bundle to properly render the user interfaces for the IBM Connections portlets.
If you are using the 3.0.1.1 refresh version, disregard this topic. The portlets display correctly using the Portal style sheets. The IBM Connections portlets bundle their own Lotus CSS package containing all of the style definitions and images required to properly render the UI. This CSS package is based on the same CSS package contained in the WebSphere Portal 6.1.5 Page Builder theme. Because of this, the portlet application contains logic to determine whether or not to load the CSS package bundled with the portlets depending on whether or not the theme used by the portal environment has already loaded the Lotus CSS as part of the theme. This is done to avoid loading of duplicate style definitions during page load. Follow these steps to specify a loading option.
- Depending on your server configuration, open the lcaccelerator.properties file in an editor as follows:
- For a Windows-based non-clustered Portal server, open: [portalInstallRoot]\wp_profile\installedApps\[cell]\PA_WPF.ear\snor.pf.portlets.war\WEB-INF\lcaccelerator\properties\lcaccelerator.properties
- For a Linux/AIX-based non-clustered Portal server, open: [portalInstallRoot]/wp_profile/installedApps/[cell]/PA_WPF.ear/snor.pf.portlets.war/WEB-INF/lcaccelerator/properties/lcaccelerator.properties
- For a Windows-based clustered portal Server, open the file on each application server node: [portalInstallRoot]\wp_profile\installedApps\[cell]\PA_WPF.ear\snor.pf.portlets.war\WEB-INF\lcaccelerator\properties\lcaccelerator.properties
- For a Linux/AIX-based clustered portal server, open the file on each application server node: [portalInstallRoot]/wp_profile/installedApps/[cell]/PA_WPF.ear/snor.pf.portlets.war/WEB-INF/lcaccelerator/properties/lcaccelerator.properties
- Specify one of the following options for the oneui_css_loadrule configuration setting:
- oneui_css_loadrule=portal This is the default setting. This setting causes the portlets to not load the bundled Lotus CSS but rely on the portal theme to provide the style definitions.
- oneui_css_loadrule=portlet This setting causes the portlets to always load the Lotus CSS bundled with the portlets regardless of whether its already available in portal environment or not. This is the suggested option if the portal theme has been heavily customized where a lot of style definitions that the portlets would depend on in the portal theme have been changed. This will ensure that the integrity of the Connections Portlet UI is preserved. This setting also may be used in the scenario where the portlets are deployed in an advanced or back level version of Portal that's not officially supported. In this situation, the newer Portal theme may contain an updated version of the Lotus CSS that's not supported by the Connections Portlets.
- Save your changes to the file.
Configure the Connections business card
Enable the IBM Connections Business Card so that your users can access Connections data such as a person's profile information. Follow the steps in the
The IBM Connections business card used by the portlets now supports the configuration where the email address is hidden in IBM Connections. Follow the steps in the IBM WebSphere Portal product documentation for enabling the business card:
- WebSphere Portal 7: http://www-10.lotus.com/ldd/portalwiki.nsf/dx/Integrating_Lotus_Connections_wp7
- WebSphere Portal 6.1.5: http://publib.boulder.ibm.com/infocenter/wpdoc/v6r1/topic/com.ibm.wp.exp.doc_v615/collab/i_coll_t_enable_lcprofile.html
To verify that the IBM Connections Business Card is enabled:
- Open one of the Lotus Connections portlets on WebSphere Portal and search for a person.
- Hover on the user's name to make sure the business card displays for this user. If not, the Connections business card is not configured properly.
What to do next
When the Connections business card is integrated in Portal, it affects the styles of the skin of the portlets. For example, the width of the area where the portlet title is shown is decreased. To resolve this issue, install iFix PM24072 on the Portal server. You can download the Fixpack from Fix Central.
Configure links to open Connections in the same browser window
You can configure the portlets so that when a user clicks a Connections link it opens Lotus Connection in the same browser window rather than the default, which is to open in a new window. When you configure the portlets you can enable an option that allows users to access the full IBM Connections application from a portlet. Follow these steps to configure the option to open Connections in the same browser rather than opening a new window.
- Open the lcaccelerator.properties file, located at: <portal-profile-home>\installedApps\<node>\PA_WPF.ear\snor.pf.portlets.war\WEB-INF\lcaccelerator\properties.
- Set the openExternalLinksInNewWindow property to false.
- Save your change and restart WebSphere Portal.
Enable logging for the portlets
In order to diagnose and resolve errors that occur with the IBM Connections Portlets, you must enable logging.
When you configure WebSphere Portal to write the trace and message logging for the Connections portlets, the messages are logged in the trace.log. The file is updated when an error occurs or if trace logs are created. The file is created in the following directory: <portal_server_root>\log. You can enable tracing for each portlet separately. The log classes used for the portlets are as follows:
Activities portlet:
- com.ibm.lconn.activities.detail
- com.ibm.lconn.activities.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Blogs portlet:
- com.ibm.lconn.blog.detail
- com.ibm.lconn.blog.summary
- com.ibm.lconn.blog.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Bookmarks portlet:
- com.ibm.lconn.dogear.detail
- com.ibm.lconn.dogear.summary
- com.ibm.lconn.dogear.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Profiles portlet:
- com.ibm.lconn.profiles
- com.ibm.lconn.profiles.summary
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Tags portlet:
- com.ibm.lconn.tagsi.service
- com.ibm.lconn.common
Wikis portlet:
- com.ibm.lconn.wiki
- com.ibm.lconn.wiki.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Forums portlet:
- com.ibm.lconn.forum.detail
- com.ibm.lconn.forum.summary
- com.ibm.lconn.forum.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
Community Overview portlet:
- com.ibm.lconn.communityOverview
- com.ibm.lconn.communityOverview.service
- com.ibm.lconn.profiles.service
- com.ibm.lconn.common
VMM adapter:
- com.ibm.ws.wim.adapter.connections.network.*
- com.ibm.ws.wim.adapter.*
- com.ibm.connections.vmm.adapter.filter.*
The recommended logging level is all.
For additional information on debugging issues with the Virtual Member Manager adapter, see this tech note.
VMM adapter - Sonata Trace specification for sonata/authentication :
Connections Server:
- com.ibm.connections.httpClient.*
- com.ibm.connections.directory.services.*
- com.ibm.ws.security.*
- org.apache.commons.httpclient.*
- SonataHttpHeader
- SonataHttpBody
Portal Server:
- com.ibm.connections.httpClient.*
- org.apache.commons.httpclient.*
- SonataHttpHeader
- SonataHttpBody
The recommended logging level is all.
Inter-portlet Navigation (Piece of Content handler)
- com.ibm.lconn.lcaccelerator.search.resolver.*
The recommended logging level is all.
Search center portlet (display provider):
- com.ibm.lconn.lcaccelerator.search.display.*
The recommended logging level is all.
Configuration Properties Helper:
The Configuration Properties Helper retrieves all of the configuration settings from the Resource Environment Provider and makes them available to the portlets.
com.ibm.lconn.lcaccelerator.profiles.rep.*
Type-ahead:
The type-ahead builder is used to manage the members/owners. This uses the directory services to function.
- com.ibm.connections.directory.services.*
- com.ibm.connections.httpClient.*
- com.ibm.websphere.wim.*
- com.ibm.ws.wim.*
The recommended logging level is all.
REST Call logging:
This will enable logging of details of the REST service calls to a separate log file
These logs will get generated at <installed war>/WEB-INF/logs/RESTCallLogs.log.
- Open the file <installed war>\WEB-INF\lcaccelerator\properties\loggerServiceMapping.properties
- Set the property TPA_REST_LOG_FLAG to true.
- Restart the Application war from the WAS admin console.
You can specify the following log levels: info, fine, finer, finest, and all. To enable logging for one or more of the Connections portlets, do the following:
- Log into WebSphere Portal as the Administrator
- Navigate to Administration > Portal Analysis > Enable Tracing .
- In the Append these trace settings field, specify the log level for the desired log class and click the add button (+): For example, com.ibm.lconn.activities.summary=fine
- Repeat step 3 for each log class to log.
- Log out of portal and log back in.
Example
For example, if you wanted to enable the finest log level for the Activities Detail portlet, you would add these three logging settings:If you wanted to enable the fine log level for the Bookmarks Summary portlets, you would add these logging settings:
- com.ibm.lconn.activities.detail=finest
- com.ibm.lconn.activities.service=finest
- com.ibm.lconn.profiles.service=finest
- com.ibm.lconn.dogear.summary=fine
- com.ibm.lconn.dogear.service=fine
Pinning portlet content to a tag
Specify a tag to pin for an IBM Connections portlet to show content associated with that tag.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 to use this feature. If you want the content of a portlet scoped to a specific tag, you can set a page parameter to the tag.
Each portlet can be pinned only to a single tag.
- Edit the portal page containing the IBM Connections portlets. For details on editing page parameters, see this Portal wiki article.
- Set the page parameter for each portlet to pin to a tag.
Table 90. Tag pin parameters
Portlet Parameter Activities Detail ibm.tag.pin.activities.detail Blogs Detail ibm.tag.pin.blogs.detail Blogs Summary ibm.tag.pin.blogs.summary Bookmarks Detail ibm.tag.pin.bookmarks.detail Bookmarks Summary ibm.tag.pin.bookmarks.summary Forums Detail ibm.tag.pin.forum.detail Forums Summary There is no page parameter for this portlet. You can set a pin option from the Edit Shared Sets panel. Wikis Detail ibm.tag.pin.wikis.detail Global Page Pin ibm.tag.pin.all Use the global tag pin to specify a common tag to use as a filter for all IBM Connections portlets on the page. Tags you specify for individual portlets override this global tag pin.
- Save the page changes.
- Log out of WebSphere Portal and then log back in to refresh the portlets so that you can see content pinned to the specified tag.
Configure and wiring the Tags portlet
After installing and deploying the IBM Connections portlets, configure and wire the Tags portlet so it works in concert with other portlets in an IBM WebSphere Portal application.
When you are deploying the Tags portlet, note that if you are also deploying a Bookmarks portlet there is a difference in how tags display. The Bookmarks portlet by default returns active tags for the last 30 days. If this does not match what displays in the Tags portlet you can change the configuration settings for Bookmarks. For example, you can increase the setting from 30 days to 180 days to display more tags. For information on changing the Bookmarks configuration, follow the steps in the topic Changing view and link thresholds and change the value of the sinceWhen.activeTags.
Follow these steps to configure and wire the IBM Connections Tags portlet.
Wiring the Tags portlet
The Tags portlet allows users to view content tagged with the tag selected from the portlet to aid in the discovery of content.
You should already have added the IBM Connections portlets to a Portal page before you proceed with wiring. The Tags portlet must be deployed on the same page with at least one other IBM Connections portlet. Read How the Tags portlet interacts with the other IBM Connections portlets for information on how the Tags portlet communicates with the other IBM Connections portlets. Follow these steps to wire the Tags portlet to other IBM Connections portlets so that the Tags portlet can filter IBM Connections content displayed in the other IBM Connections portlets.
Only the detail portlets can be wired to the Tags portlet. The summary portlets cannot be wired to the Tags portlet.
- From the Edit Layout page of the page containing the Tags portlet and at least one other IBM Connections detail portlet, click the Wires tab.
- Set the following wire(s) from the Tags portlet to the corresponding IBM Connections portlets on the page:
Source Portlet Send Target Page Target Portlet Receive Wire Type Tags Selected Tag {current page} {Blogs|Profiles|Wikis|Bookmarks|Forums|Activities} Selected Tag Public
- Click Add.
- If you have the Tags portlet deployed on a page with one IBM Connections detail portlet and want the Tags portlet to show tags associated with the view in the details portlet, set the following wire:
Source Portlet Send Target Page Target Portlet Receive Wire Type {Blogs|Profiles|Wikis|Bookmarks|Forums|Activities} Tags Payload {current page} Tags Tags Payload Public
- Click Add.
- Click Done.
How the Tags portlet interacts with the other IBM Connections portlets
This topic describes how the Tags portlet interacts with the other IBM Connections portlets.
The IBM Connections Tags portlet allows users to locate content in the other IBM Connections portlets (Activities, Blogs, Bookmarks, Wikis and Profiles). Selecting a tag from the Tags portlet causes the Connections portlets to reload to display the content from the Connections applications tagged with the selected tag. This interaction between the Tags portlet and other Connections portlets is enabled through portlet wiring to send the information that the Connections portlets need to request the proper feeds filtered by the selected tag.
There are two modes of operation with regards to the interaction between the tags and the other Connections portlets: one-way and two-way communication mode. In one-way communication mode, the Tags portlet sends a wire to the other Connections portlets to update their view according to a selected tag. In two-way communication mode, the other Connections portlets can also send a wire to the Tags portlet to update its view as well according to the view being displayed.
Tags are not supported for Forums or Profiles deployed on a community page.
One-way Communication Mode
One-way communication mode is enabled when the Tags portlet is set to communicate with multiple instances of the Connections application portlets. This is enabled when more than one application is selected in the Shared Sets panel of the Tags portlet. In this mode, the Tags portlet uses the IBM Connections Homepage Search API to obtain an aggregated tag feed of the selected applications using the search URL set in the Tags portlet configure panel. To properly configure one-way communication mode for tag filtering, the following items are required:
- The search URL is properly configured in the Tags portlet configuration panel.
- At least two applications that you want represented in the Tags must be selected in the Tags portlet shared settings panel.
- The wiring must be configured to send a wire from the Tags portlet to the applications selected in step 2. See Wiring the IBM Connections portlets for instructions on how to set up portlet wiring.
Two-way Communication Mode
Two-way communication mode is enabled when the Tags portlet is set to communicate with a single Connections application portlet. This is enabled when only one application is selected in the Shared Sets panel of the Tags portlet. In this mode, the Tags portlet uses the corresponding application api to obtain an the tag feed of the selected application using the application URL set in the Tags portlet configure panel. Like the one-way communication mode, the Tags portlet sends a wire to the Connections application portlet when a tag is selected. In addition, the Connections application portlet sends a wire to the Tags portlet to refresh the tags to show the tags relevant for the view selected. An example of this is when you drill down into an activity from the .My Activities. view in the Activities portlet, a wire is sent to the tags with information to show the tags specific to the activity selected. To properly configure two-way communication mode for tag filtering, the following items are required:
- The application URL of the Connections application you want to represent in the tags must be set in the Tags portlet configuration panel.
- The single application that you want represented in the tags must be selected in the Tags portlet shared settings panel.
- The wiring must be configured to send a wire from the Tags portlet to the Connections application selected in step 2 and the wiring from the Connections application portlet must be configured to send a wire to the Tags portlet to render tags for the view selected in the application portlet. See Wiring the IBM Connections portlets for instructions on how to set up portlet wiring.
Optimizing the page layout for the Tags portlet
On WebSphere Portal 6.1.5.x, optimize the page layout to use a smaller column width for the Tags portlet.
WebSphere Portal 6.1.5.x allows administrators and page editors to control the page layout for every page in the Portal environment. If the page layout includes a multi-column format, the size of each column can be set to optimize the layout to best accommodate the portlets on the page. The best layout of a page containing the IBM Connections tags portlet uses a smaller column width for the tags portlet leaving more screen real estate for the main content portlets with which it interacts.
- Enable the Edit Layout portlet to display the option to control the column size.
- Log in to WebSphere Portal as the administrator
- In the Administration section, go to Portlet Management > Portlets.
- Locate the Edit Layout portlet. Search by title using "edit layout" as the search text.
- Click the "Configure Portlet" icon.
- Set the "showAdvancedOption" to yes.
- Click OK to save the changes.
- Set the column size:
- Log in to WebSphere Portal as the administrator
- In the Administration section, go to Portlet Management > Manage Pages.
- Open a page containing the Tags portlet.
- Browse to the page containing the portlets and click on the "Edit Page Layout" option for the page.
- Click the "Show layout tools" link.
- In the header of the column containing the Tags portlet, click the two-sided arrow with the label "Not Set."
- Enter the pixel size for the width of the portlet. We recommend 180 pixels. This provides the optimal width.
- Click OK to save your settings.
Addressing IBM Connections content from a portlet
Use custom URIs to identify, access, and display IBM Connections in a portlet.
You must be running the 3.0.1.1 version of the IBM Connections Portlets of IBM WebSphere Portal to use this feature.
Beginning with version 6.0.1, IBM WebSphere Portal uses Piece of Content (POC) URIs to identify and address specific pieces of content in IBM Connections. Using a POC URI, you can precisely identify what content you want to display in a portlet. For example, when a user clicks a link in a blogs summary portlet, the POC URI identifies the blog content and displays it in the Blogs detail portlet. In earlier versions of Portal, this connection would be made using a standard URL to identify the target page of the content. URLs were limited and did not allow access to precise information about the state of a piece of content. The evolution to POC URIs provides a greater precision for identifying, retrieving, and displaying content. The URI specifies the identity of the content, not the location of the view of the document. The location of the view to the document is called the portal URL, or simply URL and the information contained in this URL is the navigational state, or simply state.
For detailed information on the creating and using custom URIs to access content, see the article Leveraging WebSphere Portal V6 programming model: Part 5. Accessing portal content with custom URLs on IBM developerWorks®.
Configure 3.0.1.1 to address content
To configure 3.0.1.1 so you can address content between portlets, edit the properties in the properties.poc file.
Use URIs to identify, access, and display IBM Connections content and profiles in a portlet. IBM WebSphere Portal uses Piece of Content (POC) URIs to identify and address specific pieces of content in IBM Connections independent of the page used to display the content. Using a POC URI, you can precisely identify what content you want to display without knowing where it should be displayed in your WebSphere Portal server at the time you generate a link. For example, when a user clicks a link in a blogs summary portlet, the POC URI identifies the blog content. Clicking on a link that uses a POC URI displays the blog entry in the Blogs detail portlet on the appropriate page. The evolution to POC URIs provides a greater precision for identifying, retrieving, and displaying content. The URI specifies the identity of the content, not the location of the view of the document. The location of the view to the document is called the portal URL, or simply URL and the information contained in this URL includes the navigational state, or simply state.
Configure navigation between portlets in the 3.0.1.1 release
Use URIs to identify, access, and display IBM Connections content and profiles in a portlet.
You must be running the 3.0.1.1 version of the IBM Connections Portlets of IBM WebSphere Portal to use this feature.
When working with a POC URI, you do not need to be aware of the page in Portal where a piece of content should be displayed, you only need to know some identifying data about the piece of content to create the URL. The correct WebSphere Portal page to display the content is retrieved after the user clicks on a link using a POC URI format.
The POC resolver handles navigation in following manner.
- If the piece of content is community content:
- Search the community page for a detail portlet to render the content.
- If no static community page is found , search for a stand-alone page.
- If no stand-alone page is found, navigate to an error page.
- If the piece of content is from a stand-alone page rather than from a community:
- Search the standalone page for a detail portlet to render the content.
- If no standalone page is found , navigate to an error page.
For detailed information on the creating and using custom URIs to access content, see the article Leveraging WebSphere Portal V6 programming model: Part 5. Accessing portal content with custom URLs on IBM developerWorks. The following steps are an example of how you can wire portlets in an application. You can apply these steps to wiring any of the IBM Connections portlets in an application.
- Ensure you have followed the install instructions completely. The JAR for the POC handler must be installed as described in Installing the IBM Connections Portlets for IBM WebSphere Portal.
- To configure navigation to community pages, ensure you have set the correct properties when defining the community page as described in Mapping a community page to a community.
- To configure navigation for content not inside a community, or for which a community page does not exist, ensure you have create default pages for each service as described in Configuring the portlets on a page.
What to do next
You can configure and customize certain aspects related to navigation by editing the default values in the configuration file com.ibm.lconn.lcaccelerator.poc.properties in the directory <portlet_build>/POCResolver. For example, you can customize:
- Portlet IDs
- Page names for stand-alone pages
- Default page to display when a target page is not available
After customizing the file, you must move it to the <wp_profile>/properties directory.
Configure 3.0.1.1 Refresh to address content
To configure 3.0.1.1R so you can address content between portlets, edit environment variables.
Use URIs to identify, access, and display IBM Connections content and profiles in a portlet. IBM WebSphere Portal uses Piece of Content (POC) URIs to identify and address specific pieces of content in IBM Connections independent of the page used to display the content. Using a POC URI, you can precisely identify what content you want to display without knowing where it should be displayed in your WebSphere Portal server at the time you generate a link. For example, when a user clicks a link in a blogs summary portlet, the POC URI identifies the blog content. Clicking on a link that uses a POC URI displays the blog entry in the Blogs detail portlet on the appropriate page. The evolution to POC URIs provides a greater precision for identifying, retrieving, and displaying content. The URI specifies the identity of the content, not the location of the view of the document. The location of the view to the document is called the portal URL, or simply URL and the information contained in this URL includes the navigational state, or simply state.
Configure a resource environment provider for POC
You must configure the WebSphere Resource Environment provider in order to address content in the portlets using POC.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 refresh to use this feature. Add any allowed IBM Connections server URLs. For example, if the server allows http and https URLs, add both.
- Log into the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resources > Resource Environment > Resource Environment Providers.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- If the WP ConnectionsIntegrationService already exists, click on it. If not, click New, specify WP ConnectionsIntegrationService, and click Apply.
- Click Custom Properties.
- Click New and configure the following attributes:
These attributes are optional. If you do not specify values, the default values are used.
Name Description Default Value Type pocRedirectToNativeUIOnError The default value of true enables redirection to the Connections native UI in case of error. The value of false redirects user to the configured portal error page. true java.lang.String portletsAppId Set the <portlet app id> for a customized portlet. . The default is com.bowstreet.portlet.WebAppRunner2_snor.pf.portlets java.lang.String pocErrorPageUN Specify an <error_page_UniqueName> as the error page. The default value is ibm.conn.navigation.error. java.lang.String <service name>StandalonePageUN This enables support for multiple detail portlets on a single standalone page. For example,
blogsStandalonePageUN=ibm.conn.common.standalone.page wikisStandalonePageUN=ibm.conn.common.standalone.page profilesStandalonePageUN=ibm.conn.common.standalone.pageindicates that blogs, wikis and profiles detail portlets are deployed on a page with the unique name ibm.conn.common.standalone.page.The default value is ibm.conn<service>.
For example:
- ibm.conn.profiles
- ibm.conn.blogs
- ibm.conn.activities
- ibm.conn.forums
- ibm.conn.bookmarks
- ibm.conn.wikis
java.lang.String
- Save the new settings.
What to do next
If you deployed an earlier version of the Connections portlets that used the poc.properties file to configure POC settings, the following properties from the poc.properties file correspond to the environment variables:
Property in the poc.properties file Environment variable name ibm.conn.portlets.app.id portletsAppId error.page pocErrorPageUN <service> <service>StandalonePageUN
Configure the cache for POC
Configure a cache to store a collections of web URLs to optimize the page load performance when resolving requests to address a piece of Connections content.
You must be using IBM Connections Portlets for IBM WebSphere Portal 3.0.1.1 refresh to use this feature. The IBM Connections portlets use a cache to store a collections of web URLs to optimize the page load performance when resolving requests to address a piece of Connections content.
To set up the Connections Portlets DynaCache instance for each node in you portal cluster, do the following:
- Open the WebSphere Application Server Admin Console and expand Cache Instances in the Resources section.
- Select Object Cache Instances.
- Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.
- Click New to create a new cache instance.
- Set the JNDI Name to services/cache/LCPocCache and set Name to something meaningful.
- Click OK to save your changes.
Results
The default value of 2000 is designed to handle the number of URLs for an average deployment. You can edit this value.
Configure a global proxy for POC
Configure a global proxy for POC to handle URL redirections.
This procedure only applies if you are deploying the IBM Connections portlets 3.0.1.1 refresh edition on Portal 7 servers. Skip these steps if you are using 3.0.1.1 or are deploying on Portal 8 servers.
You must configure a global proxy in order to address content in the Connections portlets.
To set up the global proxy, do the following:
- Follow the instructions in this article to configure a global proxy.
- When you configure the global proxy, add the following line to the proxy definition:
<proxy:policy url="{$ibm_connections_policy}" acf="none" basic-auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> <proxy:method>HEAD</proxy:method> <proxy:method>POST</proxy:method> <proxy:method>PUT</proxy:method> <proxy:method>DELETE</proxy:method> </proxy:actions> <proxy:cookies> <proxy:cookie>LTPA</proxy:cookie> <proxy:cookie>LTPA2</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>PD-H-SESSION-ID</proxy:cookie> <proxy:cookie>PD-S-SESSION-ID</proxy:cookie> <proxy:cookie>SMSESSION</proxy:cookie> </proxy:cookies> </proxy:policy>
Configure navigation between portlets
Use URIs to identify, access, and display IBM Connections content and profiles in a portlet.
You must be running the 3.0.1.1 version of the IBM Connections Portlets of IBM WebSphere Portal to use this feature.
Use URIs to identify, access, and display IBM Connections content and profiles in a portlet. IBM WebSphere Portal uses Piece of Content (POC) URIs to identify and address specific pieces of content in IBM Connections independent of the page used to display the content. Using a POC URI, you can precisely identify what content you want to display without knowing where it should be displayed in your WebSphere Portal server at the time you generate a link. For example, when a user clicks a link in a blogs summary portlet, the POC URI identifies the blog content. Clicking on a link that uses a POC URI displays the blog entry in the Blogs detail portlet on the appropriate page. The evolution to POC URIs provides a greater precision for identifying, retrieving, and displaying content. The URI specifies the identity of the content, not the location of the view of the document. The location of the view to the document is called the portal URL, or simply URL and the information contained in this URL includes the navigational state, or simply state. When working with a POC URI, you do not need to be aware of the page in Portal where a piece of content should be displayed, you only need to know some identifying data about the piece of content to create the URL. The correct WebSphere Portal page to display the content is retrieved after the user clicks on a link using a POC URI format.
The POC resolver handles navigation in following manner.
- If the piece of content is community content:
- Search the community page for a detail portlet to render the content.
- If no static community page is found , search for a stand-alone page.
- If no stand-alone page is found, navigate to an error page.
- If the piece of content is from a stand-alone page rather than from a community:
- Search the standalone page for a detail portlet to render the content.
- If no standalone page is found , navigate to an error page.
For detailed information on the creating and using custom URIs to access content, see the article Leveraging WebSphere Portal V6 programming model: Part 5. Accessing portal content with custom URLs on IBM developerWorks. The following steps are an example of how you can wire portlets in an application. You can apply these steps to wiring any of the IBM Connections portlets in an application.
- Ensure you have followed the install instructions completely. The JAR for the POC handler must be installed as described in Installing the IBM Connections Portlets for IBM WebSphere Portal.
- To configure navigation to community pages, ensure you have set the correct properties when defining the community page as described in Mapping a community page to a community.
- To configure navigation for content not inside a community, or for which a community page does not exist, ensure you have create default pages for each service as described in Configuring the portlets on a page.
Custom URI syntax
Understand the syntax for creating a custom URI to access a piece of content.
POC URI Syntax
Construct a POC URI to address Connections content. The syntax has this form:
connections:<atom_uri>&commID=<community_id>&service=<service_name>&type=<content_type>commID, service, and type must be specified as parameters. Parameter names are case sensitive.
Parameters
- connections
- connections is the scheme that identifies the type of content the URI is locating.
- atom_uri
- The path portion of the URI used to fetch the atom document for the content.
- commID
- (optional) Community ID. Needs to be specified if the content is community-based.
- service
- Identifies the Connections service.
- type
- Identifies the content type. For example, an activity or a wiki page.
Table 91. Connections services and types
Service Type Type specific parameters Description activities activity Opens a particular activity, showing the outline page in the appropriate activities detail portlet item Opens the activity outline page for the activity containing this item in the activities portlet. The atom_uri may refer to an activity todo, entry, section, comment, chat communication, or email communication. blogs blog Opens particular blog in the appropriate blog details portlet entry Opens a particular blog entry in the appropriate blog details portlet communities community Opens the community page for this community if one is available, otherwise directs to the configured error page. forums forum Opens a particular forum in the appropriate forum details portlet topic forumUuid (optional)
Opens a particular forum topic entry in the appropriate forums details portlet profiles profile Opens the profile detail in the profiles portlet wikis wiki Opens a particular wiki in the appropriate wiki details portlet page Opens a particular wiki page in the appropriate wiki details portlet file wikiLabel
pageLabel
Opens the attachments listing page for the parent wiki page in the wikis portlet. The atom_uri may be the URI of any attachment on the page, obtained from the attachment Atom entry. The portlet will list all attachments for that wiki page.
POC Servlet
The piece of content (POC) servlet checks for authentication. The /poc mapping does not require authentication but recognizes if valid authentication or single-signon information is present. If that case, the resolver framework will redirect to /myportal; otherwise, it redirects to /portal. In many usage scenarios it is appropriate to address the /poc mapping, because it detects potential authentication information automatically. In any case, access control to the actual page and portlets to which the POC URI resolves is enforced by the portal. The POC servlet default path is
http://<server>:<port>/wps/poc?uri=Use the POC Servlet with the POC URI to access content as follows:
POC URI:http://<server>:<port>/wps/poc?uri=connections:<atom_uri>&commID=<community_id>&service=<service_name>&type=<content_type>
Sample URI
POC URI to address a forum topic:http://<server>:<port>/wps/poc?uri=connections:forums/atom/topic?topicUuid=da99c49f-d2d0-47d9-9f18-1f32cf9e108c&type=topic&service=forums&commID=9425353dfea-484c-1234-1f2f7d51e517&forumUuid=6864a28b-dfea-484c-9fd8-1f2f7d51e517
IBM Connections Business Card
The IBM Connections Business Card integrates the applications of IBM Connections with Sametime.
The IBM Connections Business Card replaces the standard business card in products with Sametime enabled. In addition to a person's contact information, you can view their IBM Connections profile, and see other content such as what blogs they own.
Configure the IBM Connections Business Card
As the administrator, you can configure the IBM Connections Business Card plug-in to provide IBM Connections contact information in products with IBM Sametime awareness enabled. The IBM Connections business card plug-in allows users to display contact information that is pulled directly from the Profiles server combined with information from IBM Sametime. You can edit the plugin_customization.ini file as described in Use INI settings to configure the IBM Connections features that are available in the IBM Lotus Notes client to enable the Connections Business Card to work with Sametime awareness.
To understand how to integrate the IBM Connections Business Card with the IBM Lotus Notes Activities sidebar refer to this article on Notes Integration.
What to do next
To uninstall this plug-in:
- Uninstall the IBM Connections Business Card using the Add/Remove programs service from the Control Panel.
- Manually remove the Business Card related accounts from the Accounts Preferences panel. Delete all accounts that have the description .IBM Connections.. The account named .Connections. should be the final account deleted.
Only do this if you are NOT using the Activities sidebar. If this is the case leave all accounts in place.
IBM Connections Desktop Plug-ins for Microsoft Windows
Use the plug-ins to share files and information between Microsoft Windows applications and IBM Connections.
The IBM Connections Desktop Plug-ins Microsoft Windows supports:
- IBM Connections 4.0
- IBM Connections 3.0.1.1
- Microsoft Windows XP SP3 (32-bit)
- Windows Vista (32-bit)
- Windows 7 SP1 (32-bit, 64-bit)
- Microsoft Office 2007 Standard or higher (32-bit)2010 Standard or higher (32, 64-bit)
- Microsoft Outlook 2007 Standard or higher (32-bit), 2010 Standard or higher (32, 64-bit)
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features from Microsoft Windows Explorer:
- Upload local files to IBM Connections from Windows Explorer or from your desktop
- Share uploaded files with people, communities, or folders in IBM Connections
- Work on files locally and publish them to IBM Connections
- View people's contact details and get in touch with them
- Pin, follow, or like IBM Connections files and folders
- View or contribute comments for a file
- Lock a file when you are editing it to prevent file conflicts
- View and restore files from IBM Connections Trash
- Share folders with IBM Connections Communities
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features from Microsoft Office (Word, Excel, PowerPoint):
- Features added to Word:
- Add a document to IBM Connections Files or Communities
- Attach a document to an Activity or Wiki page
- Publish a document to a Blog entry
- Add someone's profile information from IBM Connections into a document
- Add a bookmark from IBM Connections into a document
- Add a URL from a document as a bookmark in IBM Connections
- Search for content in IBM Connections
- Features added to PowerPoint:
- Add a presentation to IBM Connections Files or Communities
- Attach a presentation to an Activity or Wiki page
- Search for content in IBM Connections
- Features added to Excel:
- Add a spreadsheet to IBM Connections Files or Communities
- Attach a spreadsheet to an Activity or Wiki page
- Search for content in IBM Connections
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features from Microsoft Outlook:
- Add an email to IBM Connections Files or Communities
- Attach an email to an activity or wiki page
- Search for content in IBM Connections
- View social activities for email recipients and people in your network
- Invite people to your IBM Connections network
- View IBM Connections business card for email senders and recipients in Outlook 2010
If you previously installed any version of the IBM Connections Plug-in for Microsoft Office and Microsoft Windows, installing this plug-in silently removes the Microsoft Explorer features from the older plug-ins.
You have two options for installing the plug-in. Individual users can install the plug-in, or you can perform a silent installation to install the plug-in for a group of users.
Performing a user installation
Users can install the IBM Desktops Plug-ins for Microsoft Windows following these steps.
- Download the plug-in from the IBM Connections catalog at the following web site:
https://greenhouse.lotus.com/catalog
- Unzip the file.
- Double-click IBMConnectionsDesktop.exe to launch the installation program.
- Optional: Choose not to install the Microsoft Office or Microsoft Outlook plug-ins. In the Custom Setup panel, click the icon next to Microsoft Office or Microsoft Outlook, and then click This feature will not be available to not install those plug-ins. The Microsoft Explorer plug-in is always installed.
- Click Finish to complete the installation.
- If prompted, reboot your computer.
Performing a silent installation
Administrators can silently upgrade or install the IBM Connections Desktop Plug-ins for Microsoft Windows from the command prompt. User notification is disabled during the silent installation, except in error cases such as notification of failed prerequisites. A silent installation uses the same installation program that the graphical user interface (GUI) version uses. However, instead of displaying a wizard interface, the silent installation reads all of your responses from parameters that you pass to the command line. In order for the installation to work successfully, you must run the silent installation from the directory where you unzipped the plug-in files.
- Download the plug-in from the IBM Connections catalog at the following web site:
https://greenhouse.lotus.com/catalog
- Unzip the file.
- cd directory where you saved IBMConnectionsDesktop.exe.
- Type IBMConnectionsDesktop.exe /Options(s) [PROPERTY=Value] The optional parameters and public property settings are listed in the following tables:
Table 92. Optional parameters
Optional parameters Description /install Installs the plug-in. /uninstall Uninstalls the plug-in. /quiet Establishes Silent mode requiring no user interaction. /norestart Prevents restart after the installation is complete. /promptrestart Prompts the user for restart if necessary. /forcerestart Always restarts the computer after installation. Table 93. Public properties
Public property Description INSTALLDIR Directory that plug-ins will be installed in. For example, INSTALLDIR=C:\Progra~1\IBM\Connections Desktop PluginsADDLOCAL Optionally install components. If this is not specified, all components are installed. The Windows Explorer feature is required and is always installed. Examples:
- To silently install just the Microsoft Windows Explorer feature:
IBMConnectionsDeskTop.exe /install /quiet ADDLOCAL=WindowsExplorer
- To silently install the Microsoft Office feature:
IBMConnectionsDeskTop.exe /install /quiet ADDLOCAL=WindowsExplorer,MicrosoftOffice
- To silently install the Microsoft Outlook feature:
IBMConnectionsDeskTop.exe /install /quiet ADDLOCAL=WindowsExplorer,MicrosoftOutlook
- To disable Connections 3.0 or 3.01 features on Microsoft Window Explorers desktop:
IBMConnectionsDeskTop.exe /install /quiet DSB_MS30X_EXPLORER
- To disable Connections 3.0 or 3.01 features on Microsoft Window Explorers and install the Connections 4.0 plug-ins features for Windows Explorer:
IBMConnectionsDeskTop.exe /install /quiet ADDLOCAL=WindowsExplorer DSB_MS30X_EXPLORERDSB_MS30X_EXPLORER If you previously installed an earlier version of the IBM Connections 3.0.1 Plug-in for Microsoft Office and Microsoft Windows, this option disables rather than uninstalls plug-in features. If this option is not specified, the earlier features will be uninstalled silently.
- To disable Windows Explorer features of the IBM Connections 3.0.1 Plug-in for Microsoft Office and Microsoft Windows and install all components of the Connections 4.0 plug-in:
IBMConnectionsDeskTop.exe /install /quiet DSB_MS30X_EXPLORER
- To disable Windows Explorer features of the IBM Connections 3.0 or 3.0.1 Plug-in and install the Windows Explorer feature of Connections 4.0 plug-in:
IBMConnectionsDeskTop.exe /install /quiet ADDLOCAL=WindowsExplorer DSB_MS30X_EXPLORERTable 94. Samples of silent install commands
description Example Silent install with restart and INSTALLDIR property IBMConnectionsDesktop.exe /install /quiet /forcerestart INSTALLDIR=C:\Progra~1\IBM\SampleSilent uninstall with no restart IBMConnectionsDesktop.exe /uninstall /quiet /norestart
- Reboot the machine.
Repairing or removing the IBM Connections Desktop plug-ins
Users experiencing problems with the plug-in can use the Repair function to correct it or use the Remove feature to uninstall the plug-in.
- Navigate to the Add/Remove Programs panel from your Microsoft Windows control panel.
- Select IBM Connections Desktop Plug-ins for Microsoft Windows and choose one of the following:
- Select Change , then Next, and finally Repair to correct an installation.
- Select Remove to remove the plug-in from your system.
- Confirm your choice and complete the operation.
- Reboot your computer.
Preferences and policies for the IBM Connections Desktop Plug-ins for Microsoft Windows
Set preferences and policies to control how users interact with the IBM Connections Desktop Plug-in for Microsoft Windows.
The following table shows preference and policy settings that control the behavior of the IBM Connections Desktop Plug-in for Microsoft Windows. These registry values are not created during install. You must create these keys/values as needed. If a key/value does not exist the appropriate default is assumed. Set values to anything other than the values listed below will produce unpredictable results.
For 64-bit machines, the registry settings are stored in HKLM/SOFTWARE/Wow6432Node/IBM instead of in HKLM/SOFTWARE/IBM (used for 32-bit machines).
Table 95. Registry keys for IBM Connections Desktop Plug-in for Microsoft Windows.
Enter registry keys with no line breaks. They are formatted for readability in the tables below.
Key/SubKey (HKLM/SOFTWARE/IBM) or (HKLM/SOFTWARE/Wow6432Node/IBM on 64-bit) Name (Type = String) Values Description Social Connectors/Sets
Hide ShellExt
0 . Display Context Menu (Default)
1 . Do not display Context Menu
Controls the default visibility preference of the Windows Explorer context menu extension.
Set this value will override a user preference if the policy is also set to Disable (value=1)
Social Connectors/Sets
Hide ShellExt Policy
0 . Enable Preference (Default)
1 . Disable Preference
Controls whether users can modify the preferences value.
HKCU/SOFTWARE/Microsoft/Windows/CurrentVersion/
Explorer/HideDesktopIcons/ClassicStartMenu
32-bit OS
{A0D85EDF-50B5-4B12-9D74-0D69E6729A11}
64-bit OS
{21034BDC-B57E-400b-A5D5-2B1E98502805}
Type = DWORD
0 . Show (Default)
1 . Hide
Controls hiding of the Desktop Icon when using the classic Start Menu. This must be set per user (HKCU).
HKCU/SOFTWARE/Microsoft/Windows/CurrentVersion/
Explorer/HideDesktopIcons/NewStartPanel32-bit OS
{A0D85EDF-50B5-4B12-9D74-0D69E6729A11}
64-bit OS
{21034BDC-B57E-400b-A5D5-2B1E98502805}
Type = DWORD
0 . Show (Default)
1 . Hide
Controls hiding of the Desktop Icon when using the default Start Menu. This must be set per user (HKCU).
Social Connectors/Sets
Hide Desktop Icon Policy
0 . Enable Preference (Default)
1 . Disable Preference
Controls whether users can modify the value via the General Tab of the preferences dialog.
Social Connectors/Sets
SendLink MailApp
mailto . Use mailto: protocol (Default)
<MAPI program> - Registered name of email program
Example: Lotus Notes
Sets the default email application in the General tab of the preferences dialog.
If set to mailto:, the mailto: protocol will be used instead of MAPI.
Social Connectors/Sets
SendLink MailApp Policy
0 . Enable Preference (Default)
1 . Disable Preference
Controls whether users can modify the E-mail Sets value via the General tab of the preferences dialog.
Social Connectors/Sets
UnpublishedPrompt
0 . Do not display prompt
1 . Display prompt (Default)
Controls the default setting of the unpublished draft warning.
Set this value will override the user's preference if the policy is also set to Disabled.
Social Connectors/Sets
UnpublishedPrompt Policy
0 . Allow Hide (Default)
1 . Disable Hide
Controls whether end users can elect to hide the unpublished draft warning.
Social Connectors/Sets
ShowInfoBubbles
0 . Do not show Alerts
1 . Show Alerts (Default)
Controls the default setting for alerting that local drafts need to be saved.
Social Connectors/Sets
ShowInfoBubbles Policy
0 . Enable Preference (Default)
1 . Disable Preference
Controls whether users can change the ShowInfoBubbles preference.
Social Connectors/Sets
MonitorWarnOnClose
0 . Do not warn on close
1 . Warn on close (Default)
Controls display of warning message when drafts monitor is closed:
Social Connectors/Sets
MonitorWarnOnClose Policy
0 . Enable Preference (Default)
1 . Disable Preference
Controls whether warning dialog can be suppressed by users.
Social Connectors/Sets
EnableCacheCleanup
0 . Disable Cache Cleanup (Default)
1 . Enable Cache Cleanup
Default setting for enabling/disabling cache cleanup.
Overrides user preference if policy is also set.
Social Connectors/Sets
EnableCacheCleanup Policy
0 . Enable Preferences (Default)
1 . Disable Preferences
Controls whether users can change any of the Cache settings.
Social Connectors/Sets
CacheAge
<days> - number of days
Min . 1
Max . 100
Default - 1 (Default)
Files not accessed within the specified number of days will be deleted.
Social Connectors/Sets
CacheFrequency
<minutes> - number of minutes
Min . 5
Max . 1,440
Default - 120 (Default)
Controls how often to run cache cleanup
Social Connectors/Sets
ScanIgnoreExtensions
<comma separated extensions>
List of extensions to ignore changes on. This list will be merged with any user preferences unless the policy is set to Disable.
Example: gif, jpeg, mpg
Modifying this setting requires you to reboot.
Social Connectors/Sets
ScanIgnoreExtensions Policy
0 . Enable Preference (Default)
1 . Disable Preference
Set the policy to disable will prevent users from adding file extensions to the ignore list.
Social Connectors/Servers
Password Save Policy
0 . Allow Saving (Default)
1 . Do not Allow Saving
Controls whether users can persist passwords locally.
Passwords are stored in the Windows Credential Store.
Social Connectors/Sets
Default Auth Type
0 . Basic Authentication (Default)
1 . Custom
Controls the default authentication type in the Add Site dialog.
Social Connectors/Sets
Default Auth Ext
{EA483EAD-9E-4ECC-BDDD-BF8B1D72A1C6} - SiteMinder Authentication
{4B9448AB-DF3D-4859-A3CA-3653890997} - Integrated Windows Authentication
{B5BAD66C-CF6F-4FA5-9BC7-EF36C76D331A} - TAM Authentication
{FB5CF435-95ED-4FE6-BB7D-95F82DB65C5C} - Integrated Windows Authentication (TAM)
{CCD9158D-BCD9-4DCD-81B2-48E21D670F5C} - Integrated Windows Authentication (SiteMinder)
When Default Auth Type is set to Custom this setting controls which custom authentication module will display by default. For example to use Tivoli Access Manger authentication set this to {B5BAD66C-CF6F-4FA5-9BC7-EF36C76D331A} and then set Default Auth Type to Custom.
Social Connectors
BasicAuthEncoding
(Type is DWORD)
28591 - (ISO8895-1) (Default)
65001 - (UTF8)
Select encoding type for credentials when using basic authentication.
Social Connectors
LFFilesRoot
<path to existing directory>
%HOMEPATH%\ LFFiles (Default)
Default root directory for downloaded files. This must be set to a non-shared local directory on the client system. Once set it will only affect newly added servers, communities, or people
Modifying this setting requires you to reboot.
Social Connectors/Sets
DefaultConnectURL
<server url>
Enter the URL to use as the default site URL in the "Connect to a Site" dialog.
Social Connectors/Sets
DefaultConnectName
<server display name>
This display name is the default server display name in the "Connect to a Site" dialog.
Social Connectors/Sets
Help URL
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Using_the_IBM_Connections_Desktop_Plugins_for_Microsoft_Windows_ic40 (Default)
.http://. or .https://. is required as part of the url
The url for help for the entire product.
Social Connectors/Sets
HelpConnectURL
http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Using_the_IBM_Connections_Desktop_Plugins_for_Microsoft_Windows_ic40 (Default)
.http://. or .https://. is required as part of the url
The URL for help on the Connect to Site dialog. This will override the setting for HelpURL
Table 96. Outlook Social Connector Sets Default settings
Key/SubKey (HKLM/SOFTWARE/IBM) or (HKLM/SOFTWARE/Wow6432Node/IBM on 64-bit) Name (Type = String) Values Description Social Connectors/Office/OSC
MaxFriends
<friends> - number of friends Min . 100 Max . 9999 Default - 500
Maximum number of friends that can be downloaded from the users network. These will create outlook contacts. Values entered will be rounded up to the next hundred (e.g. 111 would be treated as 200)
Social Connectors/Office/OSC
MaxNews
<items> - number of news items Min . 100 Max . 9999 Default - 500
Maximum number of activities that will be downloaded from the news feed. These will be stored in the outlook cache via OSC framework. Values entered will be rounded up to the next hundred (e.g. 111 would be treated as 200)
Social Connectors/Office/OSC
DaysSince
Min . 1 Max . 14599 (year 1970) Default - 14
When getting news activities, this is how many days to go back in time from the current day.
Social Connectors/Office/OSC
HashedSearchParm
hashEmail
The name of the property in a users profile to compare with the HashEmail. Can be used to test hash email lookup is working when server cannot be configured Social Connectors/Office/OSC
HashFunction
Default . SHA1 Other values are MD5 or CRC32MD5
The hash algorithm used to compare the email addresses. This is passed to Outlook and it will return a hashed value of the email address using this type. Social Connectors/Office/OSC
EnableDynamicActivities
0 . Disable DynActivities (Default)
1 . Enable DynActivities
Enable getting dynamic news items for users. This requires the server be configured to handle the Hashed SearchParam Social Connectors/Office/OSC
EnableDynamicContacts
0 . Disable DynContacts (Default)
1 . Enable DynContacts
Enable getting dynamic contacts. This requires the server be configured to handle the Hashed SearchParam Social Connectors/Office/OSC
EnableContacts
0 . Disable Contacts (Default)
1 . Enable Contacts
Get contacts for Profiles Network and create Outlook contacts Table 97. Outlook Social Connector Sets per hostname (Provider) overrides of Default values. This allows per server settings.
Key/SubKey (HKLM/SOFTWARE/IBM) or (HKLM/SOFTWARE/Wow6432Node/IBM on 64-bit) Name (Type = String) Values Description Social Connectors/Office/OSC
MaxFriends
<friends> - number of friends Min . 100 Max . 9999
Default - 500
Maximum number of friends that can be downloaded from the users network. These will create outlook contacts. Values entered will be rounded up to the next hundred (e.g. 111 would be treated as 200)
Social Connectors/Office/OSC
MaxNews
<items> - number of news items Min . 100 Max . 9999
Default - 500
Maximum number of activities that will be downloaded from the news feed. These will be stored in the outlook cache via OSC framework. Values entered will be rounded up to the next hundred (e.g. 111 would be treated as 200)
Social Connectors/Office/OSC
DaysSince
Min . 1 Max . 14599 (year 1970)
Default - 14
When getting news activities, this is how many days to go back in time from the current day.
Social Connectors/Office/OSC
HashedSearchParm
Default - hashEmail
The name of the property in a users profile to compare with the HashEmail. Can be used to test hash email lookup is working when server cannot be configured.
Social Connectors/Office/OSC
HashFunction
Default . SHA1 Other values are MD5 or CRC32MD5
The hash algorithm used to compare the email addresses. This is passed to Outlook and it will return a hashed value of the email address using this type.
Social Connectors/Office/OSC
EnableDynamicActivities
0 . Disable DynActivities (Default)
1 . Enable DynActivities
Enable getting dynamic news items for users. This requires the server be configured to handle the Hashed SearchParam.
Social Connectors/Office/OSC
EnableDynamicContacts
0 . Disable DynContacts (Default)
1 . Enable DynContacts
Enable getting dynamic contacts. This requires the server be configured to handle the Hashed SearchParam.
Social Connectors/Office/OSC
EnableContacts
0 . Disable Contacts
1 . Enable Contacts (Default)
Get contacts for Profiles Network and create Outlook contacts.
Table 98. Registry settings to enable the dynamic features of the IBM Connections OSC provider
Key/SubKey (HKLM/SOFTWARE/IBM) or (HKLM/SOFTWARE/Wow6432Node/IBM on 64-bit) Name (Type = String) Values Description HKLM\Software\IBM\Social Connectors\Office\OSC\EnableDynamicContacts
REG_STRING
0 . Disable lookup
1 . Enable lookup (Default)
Dynamic Contact Lookup . This dynamic feature will allow the authenticated user to lookup the picture, name, and job title for the OSC user.
HKLM\Software\IBM\Social Connectors\Office\OSC\EnableDynamicActivities
REG_STRING
0 . Disable
1 . Enable (Default)
Dynamic Contact Activites . This dynamic feature will allow the authenticated user to retrieve the activities for the OSC user.
HKLM\Software\IBM\Social Connectors\Office\OSC\ HashFunction
REG_STRING
SH1
MD5
CRC32MD5
Email address hash for the dynamic lookup. This hash is configurable incase the desired type of hash on the server is not the default value of MD5. This is a function provided by the OSC framework, not the OSC provider. This tells the OSC provider to request the particular hash type.
Manage policies and preferences with a group policy
Use a group policy administrative template to manage preferences and policies across an enterprise. If you want to set policies and preferences for a group of users, use the Group Policy Administrative Template. This console provides a single user interface through which to manage Group Policy across an enterprise. To use the template, load it into the Group Policy Management Console snap-in.
- To start the Group Policy Management Console, open a command line window and enter gpedit.msc .
- Select Computer Configuration > Administrative Templates.
- Right-click on the Administrative Templates node and select Add/Remove Templates.
- Select Add.
- Navigate to the installation directory for the plug-ins. For example, C:\Program Files (x86)\IBM\Connections Desktop Plugins.
- Select the appropriate template for your Windows version (For example, IBMConnections.adm or IBMConnections64.adm).
Results
There will be two newly created nodes with the following new entries:
- Computer Configuration > Administrative Templates > Classic Administrative Templates (ADM) > IBM Connections Desktop Plug-ins for Microsoft Windows
- Temporary File Cleanup - Enable/Disable Cleanup
- Temporary File Cleanup - Policy
- Temporary File Cleanup - Minimum File Access Time
- Temporary File Cleanup - Cleanup Frequency
- Hide Shell Extension
- Hide Shell Extension - Policy
- Hide Desktop Icon - Policy
- Hide Desktop Icon - New Start Panel
- Hide Desktop Icon - Classic Start Menu
- SendLink MailApp
- SendLink MailApp - Policy
- Unpublished Prompt
- Unpublished Prompt - Policy
- Show Information Bubbles
- Show Information Bubbles - Policy
- Monitor Warn On Close
- Monitor Warn On Close - Policy
- Scan Ignore Extensions
- Scan Ignore Extensions - Policy
- Password Save - Policy
- Default Authentication Type
- Default Authentication Extension
- Basic Authentication Encoding Type
- Cache Directory Root
- Help URL
- Connect to Site Help URL
- Connect to Site Server URL
- Connect to Site Server Name
- OSC - Maximum Number of Friends
- OSC - Maximum Number of News Items
- OSC - Period of Time for News Feed
- OSC - Hash Search Parameter
- OSC - Hashed Email Function
- OSC - Enable Dynamic Activities
- OSC - Enable Dynamic Contacts
- OSC - Enable Contacts
- User Configuration > Administrative Templates > Classic Administrative Templates (ADM) > IBM Connections Desktop Plug-ins for Microsoft Windows
- Hide Desktop Icon - New Start Panel
- Hide Desktop Icon - Classic Start Menu
Configure dynamic feeds for the Outlook Social Connector
Configure the IBM Connections Profiles server and the IBM Connections Outlook Social Connector provider to support dynamic feeds to bring data from Connections to the outlook client via the Microsoft Outlook Social Connector.
By default, the IBM Connections OSC provider does not have the dynamic contacts capabilities enabled. This is because the IBM Connections server must be configured to support this feature. Dynamic contacts capability can potentially make many server requests and so server load is reduced by disabling the capability until the server supports the required information.
Dynamic contacts are those members not in the authenticated user.s network. As Microsoft Outlook switches emails, the sender.s email address is sent to the OSC providers to check whether that email address exists on the server. The IBM Connections server must do an additional step to populate its repository with a hash of the Profiles members email address. For security purposes, the OSC does not provide the email address in plain text. Instead, it is hashed according to your specified function, either as MD5 or SHA1. To improve efficiency, the IBM Connections OSC provider designates any hashed email address as not available when the server returns no information for that address. This hashed email address is kept in memory for the life of the Microsoft Outlook process and is not requested again until Microsoft Outlook restarts.
To enable the dynamic features for the IBM Connections OSC provider create the following registry settings described in detail in the topic IBM Connections 4 IBM Preferences and policies for the IBM Connections Desktop Plug-ins for Microsoft Windows.
- Dynamic Contact Lookup . This dynamic feature will allow the authenticated user to lookup the picture, name, and job title for the OSC user.
- Dynamic Contact Activites . This dynamic feature will allow the authenticated user to retrieve the activities for the OSC user.
Configure the Profiles server to support feeds
Configure the IBM Connections Profiles server to support dynamic feeds in Microsoft Outlook Social Connector.
To configure support for dynamic feeds for an IBM Connections 4 server, you must edit properties in the profiles-types.xml and profiles-config.xml files.
- Navigate to the configuration files in the following location: WebSphere/AppServer/profiles/<AppSrv>/config/cells/<serverNodeCell>/LotusConnections-config.
- Edit the file profiles-types.xml in a text editor and add a <property> for the attribute hashEmail:
<property> <ref>hashEmail</ref> <updatability>readwrite</updatability> <hidden>false</hidden> <fullTextIndexed>true</fullTextIndexed> </property>
- Edit the file profiles-config.xml file in a text editor and Add a <simpleAttribute> to the <profileExtensionAttributes> element.
<simpleAttribute extensionId="hashEmail" length="40"/>
- Save your changes and close the configuration files.
- Restart the connections server so the changes will take effect.
- Populate the new attribute. This is a sample of how to produce the hash with a simple Java method:
String hash = hashString(email,"MD5"); // SHA-1 public static String hashString(String text, String alg) throws NoSuchAlgorithmException, UnsupportedEncodingException { MessageDigest md = MessageDigest.getInstance(alg); md.update(text.getBytes("iso-8859-1"), 0, text.length()); // convert the byte-array into a hex-string byte[] hash = md.digest(); StringBuffer buf = new StringBuffer(); for( int i=0; i < hash.length; i++ ) { int b = hash[i]; if( b < 0 ) b = 256 + b; if( b < 16 ) buf.append("0"); buf.append(Integer.toHexString(b)); } return buf.toString(); }The result should be a web page with only the hashed email returned.
IBM Connections Plug-in for Microsoft SharePoint
The IBM Connections Plug-in for Microsoft SharePoint brings IBM Connections applications such as searching by tag, searching by profile, and viewing business cards, into the SharePoint environment. Install the IBM Connections Widget for Microsoft SharePoint so that Connections users can access documents from a SharePoint server.
The IBM Connections Plug-in for Microsoft SharePoint provides the following applications:
- Profiles search for finding people in your organization. If colleagues you find with a Profiles search are in your SharePoint directory, you can add them to your SharePoint group or site.
- Business card for getting contact and social networking information about users in your organization. From the business card, you can create a mail message to this colleague or open their blog, bookmarks or full profile.
- Tag cloud for finding content stored on IBM Connections servers. Clicking a tag launches a search that matches against all Connections services. For example, clicking a new-hire tag could return a community and a blog posting.
- The IBM Connections Widget for Microsoft SharePoint is a widget you install separately on an IBM Connections server so that community members can upload, view and share documents stored on a Microsoft SharePoint server.
To get started, download the plug-in from the IBM Connections catalog web site: https://greenhouse.lotus.com/catalog.
Install the IBM Connections plug-in for Microsoft SharePoint 3.0.1.1
The IBM Connections plug-in for Microsoft SharePoint brings IBM Connections features such as searching by tag, searching by profile, and viewing business cards, into the SharePoint environment.
The IBM Connections plug-in for Microsoft SharePoint release 3.0.1.1 requires Microsoft SharePoint 2010.
Install language packs for Microsoft SharePoint to the server farm before you install this plug-in. This allows the plug-in to automatically install language pack solutions for all the supported languages installed in the server farm. If you install additional language packs to the server farm after installing the plug-in run the configuration wizard again to make the additional languages available to the plug-in. Follow these steps to install the plug-in.
- On your SharePoint server, unzip the plug-in contents to a location you will remember.
For example, C:\Program Files\IBM\Lotus\Connections.
- Run the Install.bat program to launch the plug-in installation and configuration wizard
- Review the URLs for accessing the IBM Connections Profiles and Search servers. The URLs are automatically filled in based on the Profiles Server URL, but you can change them if necessary.
- Optional: Modify the settings for the Profiles search.
- Click OK to complete the installation. Information from the installation is logged to plugin directory\logs\install-<timestamp>.log.
If you need to modify your configuration after installing, navigate to where you unzipped the plug-in files for installation. Then run ModifyPluginConfig.bat This launches the plug-in configuration wizard and allows you to change your settings or install additional language packs. Update information is logged to plugin directory\logs\update-timestamp.log.
What to do next
If anonymous authentication is enabled in the Internet information Services (IIS) Manager, then the API used by the SharePoint widget will not work as expected. To check if anonymous authentication is enabled in IIS:
- Go to Start > Administrative Tools > Internet Information Services (IIS) Manager.
- In the Connections section, expand the server, and then expand Sites.
- Select the SharePoint site. The default is SharePoint - 80.
- Double click the icon for Authentication.
- Check to see if there is an entry for Anonymous Authentication.
If anonymous authentication is not actually needed on this SharePoint server, you can disable it in IIS. However, if anonymous authentication is required then you must disable anonymous authentication for only the URL pattern used by the plugin API, as follows:
- Create a supplemental web configuration file called webconfig.IBMConnections.xml For instructions on creating the configuration file, see this article. Add this code.
<?xml version="1.0" encoding="utf-8"?> <actions> <remove path="configuration/location[@path='_layouts/lcphandler.ashx']" /> <add path="configuration"> <location path="_layouts/lcphandler.ashx" allowOverride="false"> <system.web> <authorization> <deny users="?" /> </authorization> </system.web> </location> </add> </actions>
- Place this file in the \CONFIG folder of the SharePoint server. The default location for SharePoint 2010 is C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG and the default location for SharePoint 2007 is C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\CONFIG.
- Open the SharePoint 2010 Management Shell
- Run the command stsadm -o copyappbincontent
- Repeat steps 2-4 on all front-end web servers.
Deploying the IBM Connections plug-in for Microsoft SharePoint 3.0.1.1
After installing the plug-in, you activate the IBM Connections features to make them available from Microsoft SharePoint. To enable the IBM Connections plug-in, deploy the features to the Microsoft SharePoint server farm. You can complete the deployment from the Central Administration site or from the Management Shell. See the Microsoft documentation for further details.
- Follow the instructions provided by Microsoft to deploy the following solutions:
- ConnectionsPluginCore.wsp - Required for business card integration, the profile search and tag cloud web parts, and the IBM Connections SharePoint widget.
- ConnectionsPluginCore_LCID.wsp where LCID is a Microsoft locale ID. Required for any languages that are in use in the server farm. See http://technet.microsoft.com/en-us/library/ff463597.aspx for the list of SharePoint supported languages and their LCID. If deploying solutions using Management Shell please refer to the Microsoft documentation for deploying language pack solutions. Deploy the ConnectionsPluginCore.wsp solution before you deploy any language pack solutions. The IBM Connections plug-in only supports languages supported by IBM Connections 3.0.
- ConnectionsProfileSearch.wsp - Optional, provides the profile search web part.
- - ConnectionsTagCloud.wsp - Optional, provides the tag cloud web part.
- Activate the IBM Connections features. The IBM Connections Tag Cloud and Search IBM Connections Profiles features are installed when their solutions are deployed. However, they must be activated before the web parts display in the Web Part Gallery. These features are scoped to the Site Collection level, so for a particular site collection, you can activate the web parts from Site Sets > Site Collection Administration > Site Collection Features. The features can also be activated using the Management Shell using the Enable-SPFeature command. For more information about the Management Shell command, refer to the Microsoft documentation.
- To enable the IBM Connections Profiles business card on your SharePoint site, make the following changes to your master page:
For more information about customizing master pages, refer to the Microsoft documentation:
- Near the beginning of the page, register a tag for the IBM Connections profile user control:
<%@ Register TagPrefix="Connections" tagname="ProfileScript" src="~/_controltemplates/ConnectionsProfileScript.ascx" %>
- At the end of the master page body, include the IBM Connections profile user control:
<Connections:ProfileScript ID="ConnProfileScript" runat="server"/>
Uninstall the IBM Connections plug-in for Microsoft Sharepoint 3.0.1.1
Deactivate the IBM Connections features and uninstall the plug-in to remove it from Microsoft SharePoint. Follow these steps to uninstall the plug-in.
- To disable business card integration, remove the tags you added to your master page:
- Remove the tag for the IBM Connections profile user control from the header of the page:
<%@ Register TagPrefix="Connections" tagname="ProfileScript" src="~/_controltemplates/ConnectionsProfileScript.ascx" %>
- Remove the IBM Connections profile user control tag from the footer of the body of the master page:
<Connections:ProfileScript ID="ConnProfileScript" runat="server"/>
- Deactivate the IBM Connections features. Deactivate the IBM Connections Tag Cloud and Search IBM Connections Profiles features from all Site Collections. For a particular site, you can deactivate the features from Site Sets > Site Collection Administration > Site Collection Features. You can also deactivate features with the Disable-SPFeature command from the Management Shell. For more information, see the Microsoft documentation.
- Retract all IBM Connections solutions from the Microsoft SharePoint server farm. You must retract all IBM Connections plug-in solutions from the server farm. You can do this from the Central Administration site or from the Management Shell. Retract all ConnectionsPluginCore(<LCID>).wsp language pack solutions before removing ConnectionsPluginCore.wsp. Refer to the Microsoft documentation for retracting solutions and for retracting language pack solutions.
- Navigate to the folder where you unzipped the plug-in files for installation and run Uninstall.bat. The uninstallation program removes all plug-in solutions and plug-in properties from the server farm. Uninstall information is logged to plugin directory\logs\uninstall-timestamp.log.
Install the IBM Connections Plug-in for Microsoft SharePoint
The IBM Connections Plug-in for Microsoft SharePoint brings IBM Connections features such as searching by tag, searching by profile, and viewing business cards, into the SharePoint environment.
For information on supported versions of Microsoft SharePoint, see the system requirements on the download page for the plug-in: https://greenhouse.lotus.com/catalog.
- Download the plug-in from the IBM Connections catalog web site:
https://greenhouse.lotus.com/catalog
- Log on to the Windows Server with the SharePoint administrator ID. The plug-in installer requires full access to the SharePoint directories. Usually, the SharePoint administrator ID also has system administration rights on the server.
- Run the installation program, lotus-connections-sharepoint-plugin.exe or lotus-connections-sharepoint-plugin-64.exe for 64-bit servers.
- After the installation program completes, the plug-in configuration program launches automatically. On the URL Sets tab of the configuration program, specify the Profiles Server URL, for example, http://connections.mycompany.com/profiles.
- Tab to the Federated Search URL field. It will be automatically filled in based on the Profiles Server URL, but you can change it if necessary.
- If you are installing on MOSS 2007, there will be two additional fields:
The default installation of MOSS automatically creates one tabbed Search Center at http://<server>/SearchCenter/Pages.
- In the Shared Service Provider (SSP) field, enter the names of the SSPs that are active on the server (in a default installation of MOSS there is one SSP called SharedServices1). Separate multiple names by pressing Enter.
- In the Search Center URLs field, enter the root URLs of any search centers to enable for Profiles search. These search centers must be sites based on the "Enterprise Search Center with Tabs" template. Set the root URL in the format http://<server>/<sitename>/Pages. For example, http://sp.mycompany.com/MySearch/Pages.
- After you have completed the URL Sets fields, click Apply. The configuration program may take several minutes to execute. When it has completed, click OK to exit the program.
- If you are installing on MOSS 2007, you need to perform additional steps to enable the search centers for Profiles Search:
- Log on to the SharePoint site as the administrator and navigate to the first search center.
- Click Site Actions > View All Site Content.
- Under the Lists category, click Tabs in Search Pages.
- Click New. Set the Tab Name field to any text you want, for example, Profiles Search. Set the Page field to lcpsearch.aspx. Click OK to save the new tab.
- Go back to the Lists category and click Tabs in Search Results.
- Click New. Set the Tab Name field to any text you want, for example, Profiles Results. Set the Page field to lcpsearchresults.aspx. Click OK to save the new tab.
- Go back to the search center and click the new Profiles Search tab. This will cause the aspx page to compile.
- Click Publish to make the page available to all users.
- Enter a search query. This will cause the results page to compile.
- Click Publish to make the page available to all users.
- Repeat these steps for the other search centers.
The plug-in automatically adds a Profiles by Name search scope to the generic SharePoint search bar that is usually found in the header of every page. Profiles results from search bar queries display in the first Search Center specified.
- After you install the plug-in, if you get a Page Not Found error when you use Profiles search from SharePoint, it is because the lcpsearch and lcpsearchresults pages are not checked in. To correct this:
- Login as administrator.
- Click Search Tab.
- Select Site Actions > View All Site Content.
- Click the Pages link.
- Find lcpsearch and lcpsearchresults from the drop-down menu and click Check In for each one.
- Click OK and Save.
- Your SharePoint users can now use the IBM Connections features integrated with SharePoint. For example, SharePoint site owners can add the tag cloud web part to their sites.
- If you cannot see the IBM Connections business card on Internet Explorer, follow these additional steps:
- Start Internet Explorer.
- Click Tools > Internet Options.
- On the Security tab, click Custom Level for Internet settings.
- In the Security Sets list, change Access data sources across domains in the Miscellaneous section to Enable.
- Click OK.
- Click Yes when you receive the following message: Are you sure you want to change the security settings for this zone?
- Click OK.
What to do next
The Tag Cloud web part is installed during the plug-in configuration, but the SharePoint administrator must activate it for the site. For example,
C:\Program Files\IBM\Lotus\Connections\Plug-in for Microsoft SharePoint\Features\TagCloud\deploy>tagcloudsetup /activate /weburl http://testsite.test.comIf you create a new site collection after installing the plug-in, the profiles search and business card features are available automatically, but the tag cloud is not. To make the tag cloud available, launch the plug-in configuration program, go to the Plug-in Applications tab, deactivate the tag cloud, and activate it again. This will add the tag cloud to the web part catalog of all new site collections.
Let your user community know that the integration features are available for use. The Profiles Search bar is available in the header of the SharePoint site. Users can enter a name to search the Lotus Connection profile directory, or click a name to open the associated profile. The business card feature is also globally available, so users can hover over a person's name and see the person's associated business card. Site owners can add the IBM Connections tag cloud web part so that users can search IBM Connections content by tag.
The Profiles business card is available for person names that appear in tables and lists and other locations throughout the SharePoint user interface. The card looks up names in the Profiles directory by email address. In order for the card to work for a particular name, that person must have the same email address in both the SharePoint directory and in the Profiles directory. If SharePoint and Connections are using the same LDAP directory, this will not be a problem, but different directories can be used as long as the email addresses match.
To remove this plug-in, follow this procedure:
- Log on to the Windows Server with the SharePoint administrator ID.
- Windows Server 2003: choose Start -> Control Panel -> Add or Remove Programs, select IBM Connections 3.0 Plug-in for Microsoft SharePoint, and click Remove.
- Windows Server 2008: choose Start -> Control Panel -> Programs and Applications, select IBM Connections 3.0 Plug-in for Microsoft SharePoint, and click Uninstall.
Configure the SharePoint plug-in
After you install the IBM Connections plug-in for Microsoft SharePoint, you can make some configuration changes.
The default plug-in configuration is usually sufficient for most installations. If you want to change any settings, follow this procedure:
- Log on to the Windows Server with the SharePoint administrator ID.
- From the Windows Start menu, choose IBM Connections 3.0 Plug-in for Microsoft SharePoint > IBM Connections 3.0 Plug-in for Microsoft SharePoint Configuration. You can then perform any of these configuration tasks:
- On the URL Sets tab, you can change any of the IBM Connections URLs specified during the installation. On MOSS, you can add or delete shared service providers or search centers.
- On the Plug-in features tab, you can deactivate or activate features.
Deactivating the tag cloud removes the tag cloud web part from the Web Part catalog, but does not remove the web part itself from any pages. The option to add a tag cloud to a site page remains an option in the Add a Web Part list. If you do not want it to appear on that list, you must remove it manually.
- If you add new SharePoint language packs after you install the plug-in, go to the Languages tab and click the Add New button. The configuration program will automatically scan the SharePoint installation and install new plug-in language packs.
- On the Profiles tab, choose whether to display the IBM Connections profile or the SharePoint profile when a user clicks a name in the SharePoint user interface. You can also specify the number of results to display from a profile search.
Configure single-sign on with IBM Tivoli Access Manager
(Optional) If IBM Connections is configured to use single sign-on with IBM Tivoli® Access Manager you can extend single-sign on to include the IBM Connections plug-in for Microsoft SharePoint.
If IBM Connections is configured to use single sign-on with IBM Tivoli® Access Manager, you can add the following resources to the unprotected access control list so that Tivoli Access Manager passes HTTP requests for these resources through to WebSphere Application Server for authentication. For details, see the topic Enabling single sign-on for Tivoli Access Manager.
acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/dojolite_1.4/dojo/nls lc3-bypass-acl acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/nav/common/styles/base/semanticTagStyles.css lc3-bypass-acl acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/nav/common/styles/base/standaloneVcard.css lc3-bypass-acl acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/resourceStrings.do lc3-bypass-acl acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/resources/js-resources.js lc3-bypass-acl acl attach /WebSEAL/<tam_server>-<WebSEAL_instance>/profiles/nav/blankIE.html lc3-bypass-acl
IBM Connections Status Updates Plug-in for Lotus Notes
This sidebar plug-in allows you to update status and view the status for colleagues in your network from your Lotus Notes client.
Use the sidebar plug-in, you can:
- Post status letting your colleagues know what you are doing
- View status for people in your network
- Comment on status updates
- Delete your status or associated comments
- Forward an update by email
- View or post updates from the icon in the system tray when you are not working in the Notes client
- Keep up with updates for people you follow
If you plan to install both the IBM Connections Status Updates plug-in and the IBM Connections Files plug-in for your Lotus Notes client, make sure they are both the same version. For example, if you install the 3.0.1 version of the Status Updates plug-in, make sure you install the 3.0.1 version of the Files plug-in. Running different versions of the plug-ins can cause problems.
Install the IBM Connections Status Updates Plug-in for Lotus Notes
Use this plug-in to post your own status and view the status for colleagues in your network from your Lotus Notes client.
This plug-in is supported on Lotus Notes clients, starting with release 8.5.1. For the details on supported configurations, see the download page for this plug-in on the IBM Connections catalog: https://greenhouse.lotus.com/catalog.
When you install this plug-in on the Lotus Notes client, you must configure Notes to recognize the IBM Connections servers before deploying the Status Updates plug-in. For details on configuring the servers, see the Configuration section of the Notes Integration article in the IBM Connections wiki.
After completing the configuration changes, follow these instructions to install or uninstall the IBM Connections Status Updates plug-in as a sidebar application.
- Download the plug-in from the IBM Connections catalog web site:
https://greenhouse.lotus.com/catalog
- Extract the compressed file. The compressed file contains both an Add-on installer and an Update Site package (updatesite.zip). The Add-on installer is supported on the Windows platform only. The Update Site is supported for all supported platforms (Windows, Linux, and Mac).
- To install the Status Updates plug-in using the Add-on installer for Windows, click the setup.exe file from the extracted package. Follow the instructions provided by the installation wizard to install the plug-in.
- To install the IBM Connections Status Updates plug-in using the Update Site package:
- Log in as the administrator.
- Click File > Application > Install
If you do not see this menu option, contact your Lotus Notes administrator.
- Select Search for new features to install.
- Select Add Zip/Jar Location and browse for the updatesite.zip file within the StatusUpdatesAddonInstaller folder.
- Expand the components in the package and select the Business Card 3.0.1_<timestamp> and Status Updates 3.0.1_<timestamp> entries from the list of options and install the plug-ins. You are presented with a series of dialog boxes asking you to confirm to install the plug-ins. For each one, select Install this plug-in and continue with the installation.
- After the installation process is finished, restart the Lotus Notes client.
What to do next
You can configure the interval for refreshing the content of status updates by changing the value of com.ibm.lconn.statusupdates/refresh.rate.in.minutes in the plugin_customization.ini file. For example:
com.ibm.lconn.statusupdates/refresh.rate.in.minutes=10The default refresh interval is 15 minutes. You can increase the interval by specifying a higher interval in minutes. You can also decrease the refresh interval, but if you set a value of 1 - 4 minutes, the refresh interval will remain at 5 minutes. To turn off the refresh interval, set the value to 0.
If the IBM Connections server either resides in the Siteminder SSO environment, or the IBM Connections server has forceConfidentialCommunication enabled in the LotusConnections-config.xml file, the user will see broken profile photos in the Status Updates list view. Test for this before you deploy Status Updates. To correct it, add the following line to the plugin_customization.ini file:
com.ibm.lconn.statusupdates/download.image.enabled=true
Uninstall the Status Updates plug-in
Uninstall the Status Updates plug-in to remove it from your Lotus Notes client.
- To uninstall the IBM Connections Status Updates plug-in if you installed using the Add-on installer, click the setup.exe file from the extracted package and follow the instructions for removing the plug-in.
- To uninstall the IBM Connections Status Updates plug-in if you installed using the Update Site, follow these steps:
- Select File > Application > Application Management
- In the applications\eclipse section, find and select the entries for the Business Card and Status Updates plug-ins.
- Select the Uninstall link.
- Restart the Lotus Notes client after the uninstallation process is finished.
IBM Connections Files Plug-in for Lotus Notes
Use the IBM Connections Files plug-in for Lotus Notes to have easy access to your files or community files from the Notes sidebar.
The Connections Files plug-in lets you upload and access files from the sidebar of your Notes client. After installing the sidebar application you can:
- Upload files for your own use or to share with others
- Drag and drop an attached file or a file from your desktop to Files
- Drag and drop or copy and paste a file from Files to your desktop
- Send an HTML link to a file
- Search for people or communities
- Sort files for easier browsing
- Detach the Files window from the Notes sidebar
- Open Connections Files in a browser
If you plan to install both the IBM Connections Status Updates plug-in and the IBM Connections Files plug-in for your Lotus Notes client, make sure they are both the same version. For example, if you install the 3.0.1 version of the Status Updates plug-in, make sure you install the 3.0.1 version of the Files plug-in. Running different versions of the plug-ins can cause problems.
Install the IBM Connections Files plug-in for Lotus Notes
Install the IBM Connections Files plug-in for Lotus Notes to access IBM Connections Files from your Lotus Notes client.
There are two ways to install the IBM Connections Files Plug-in for Lotus Notes. A user can install the plug-in for a Notes client using the InstallShield wizard, or an administrator can perform a silent installation for all plug-in users.
Install the Files plug-in on a Windows client
Install the plug-in so that it is integrated with the Lotus Notes client.
- Download the IBM Connections Files plug-in for Lotus Notes from the IBM Connections catalog at the following web site:
https://greenhouse.lotus.com/catalog
- Unzip ICS301_Files_20110713.zip.
- Click Setup.exe in the output folder.
- Make sure your Lotus Notes client is closed before beginning the installation.
- Accept installation prompts for installing the plug-in.
- Click Finish to complete the installation.
Silently installing the IBM Connections Files plug-in (Windows)
Administrators can silently install the Connections Files plug-in from the command prompt. A silent installation uses the same installation program that the graphical user interface (GUI) version users. However, instead of displaying a wizard interface, the silent installation reads all your responses from parameters that you pass to the command line. In order for the installation to work successfully, you must run the silent installation from the directory where you unzipped the plug-in files.
- Make sure your Lotus Notes client is closed before beginning the installation.
- Open a command window. For example, choose Run from the Microsoft Windows Start menu and type cmd, then click OK.
- Set the path for the downloaded and unzipped installation file for the plug-in. For example, c:\<download_folder>.
- Enter setup.exe /s /v" /qn" to begin the installation.
Install the Files plug-in on a Mac client
Install the Mac version of the IBM Connections Files plug-in for Lotus Notes so that it is integrated with the Lotus Notes client.
If you have an existing version of this plug-in installed, uninstall it before installing a new version.
- Download the IBM Connections Files plug-in for Lotus Notes from the IBM Connections catalog at the following web site:
https://greenhouse.lotus.com/catalog
- Unzip ICS301_Files_20110713.zip.
- Open the output.mac folder, and double-click FilesPlugin.zip to unzip the package.
- Make sure your Lotus Notes client is closed before beginning the installation.
- Double-click xpd.mac-addon.pkg to launch the installation program.
- Accept installation prompts for installing the plug-in.
- Click Finish to complete the installation.
Silently installing the IBM Connections Files plug-in (Mac)
Administrators can silently install the Connections Files plug-in from the command prompt. A silent installation uses the same installation program that the graphical user interface (GUI) version users. However, instead of displaying a wizard interface, the silent installation reads all your responses from parameters that you pass to the command line. In order for the installation to work successfully, you must run the silent installation from the directory where you unzipped the plug-in files.
- Make sure your Lotus Notes client is closed before beginning the installation.
- Open a terminal window.
- Set the path for the downloaded and unzipped installation file for the plug-in. For example, /output.mac/FilesPlugin.
- Enter sudo Installer -pkg package name -target destination volume to begin the installation. Where:
- package name is the name of the installer "xpd.addon.mac.pkg".
- destination volume is the disk where Lotus Notes was installed.
For example: sudo Installer -pkg xpd.addon.mac.pkg -target Macintosh_HD
- Enter your password at the prompt to begin the installation. When the installation completes, a terminal message displays The install was successful.
Viewing the log files
If you encounter any errors during the installation or configuration process, review the log files for troubleshooting information. On Windows, the logs for the plug-in are stored in the default temp directory for users. For example, on Windows XP, the directory is: C:\documents and settings\<username>\Local Sets\temp\rcp_addon_install.txt\.
To view the logs on a Mac, follow these steps.
- If the Notes version is lower than 8.5.2.
- Open the Terminal windows.
- Enter cd /tmp to navigate to the temp folder.
- Enter sudo cat rcp_FilesPlugin_install.log to view the installation log for the Files plug-in.
- Enter sudo cat rcp_FilesPlugin_uninstall.log to view the uninstall log for the Files plug-in.
- Enter your password at the prompt to view the log.
The rcp_FilesPlugin_install.log and rcp_FilesPlugin_uninstall.log files are deleted automatically when the system is restarted.
- If the Notes version is 8.5.2 or higher.
- Navigate to the directory where Notes is installed.
- Navigate to /Contents/MacOS/rcp/deploy/instalHistory.
- Find the zip file. It's name will be similar to this: Notes_8.5.2FP3_ADDON_INSTALL_1311563867253.zip or Notes_8.5.2FP3_ADDON_UNINSTALL_1311572948964.zip.
- Unzip the file and navigate to /colutil/tmp to access the log
What to do next
There is a configuration which can prevent users from uploading, downloading, or sharing files. Users will be able to view files, but, when trying to upload, download, or share a file will see this error message: "A problem with the server was encountered". This is most likely because an SSL setting called "Forced confidential" is enabled in LotusConnections-config.xml on the IBM Connections server and it creates a conflict on the Notes client. To correct this problem, set the following Files configuration setting in the plugin_customization.ini file. This setting applies to all versions of Notes.
- Open the plugin_customization.ini file for the Notes client in a text editor. The file is stored in the following directory: <Notes Install>/framework/rcp/plugin_customization.ini
On Mac, your path might be different depending on where you installed Notes. For example, your path might be: /Applications/Notes.app/Contents/MacOS/rcp/eclipse/features/plugin_customization.ini
- Add this line:
com.ibm.documents.connector.service/ENABLE_SSL=true
Uninstall the IBM Connections Files plug-in
Uninstall the Files plug-in to remove it from your Lotus Notes client. You can remove the plug-in from a single client or run a command to remove it from all plug-in users.
- To remove the plug-in from a single Windows client:
- From the Microsoft Windows Control Panel, select Add or Remove Programs (on Vista, it is called Programs and Features), then select IBM Connections 3.0.1 Files Plug-in for Lotus Notes.
- Click Remove (on Microsoft Windows 7 and Vista, it is called Uninstall), and then click Yes to confirm your choice.
- To silently remove the plug-in from Windows clients:
- Make sure your Lotus Notes client is not running.
- Open a command prompt window. For example, choose Run from the Microsoft Windows Start menu and type cmd, then click OK.
- Set the path for the downloaded and unzipped installation file for the plug-in. For example, c:\<download folder>.
- Enter setup.exe -s -x -v"/qn" to remove the plug-in.
- To remove the plug-in from a single Mac client:.
- Open the folder where you unzipped the FilesPlugin.zip and navigate to the uninstaller folder.
- Click unistaller.app , and then click Yes to confirm your choice.
- To silently remove the plug-in from Mac clients:
- Make sure your Lotus Notes client is not running.
- Open a terminal window.
- Set the path for the downloaded and unzipped installation file for the plug-in. For example, /output.mac/FilesPlugin/uninstaller.
- Enter ./addonUninstall -rcphome /Applications/Notes.app/Contents/MacOS -addonID FilesPlugin to remove the plug-in.
IBM Lotus Notes Activities sidebar
Access the IBM Connections applications from within the Notes client. This capability is not provided as a plugin, but can be configured as part of the client. Just select the Connections component during the Notes client installation.
You can use the Connections component to perform the following tasks:
- Collaborate on a project using the Activities sidebar.
- Display Activities to-do items in the Notes calendar.
- Bookmark a Notes document and add it to your bookmark collection in IBM Connections.
- Find out more about the people you work with by expanding a person's business card. Click one of the IBM Connections application links in the business card to read a person's blog, download files authored by the person, browse the person's bookmark collection, or find content contributed by the person to the wikis and communities that she participates in.
- Search across the IBM Connections applications.
For more information about the IBM Connections applications available from the IBM Lotus Notes client, refer to the Notes Help.
Install plug-ins to use other applications in IBM Connections
Enhance IBM Connections by installing plug-ins so that you can use other applications from within IBM Connections.
You can use other products from IBM Connections by adding these plug-ins.
IBM Lotus Quickr Library widgets for IBM Connections
IBM Connections communities can interact with IBM Lotus Quickr libraries using two new widgets.
- The "Linked Quickr Library" widget links to an existing Lotus Quickr Library.
- The "Quickr Library" widget creates a new Lotus Quickr Library.
A "Linked Quickr Library" widget surfaces an existing Lotus Quickr library. Members of the community can read and manage library documents based on their roles in the Lotus Quickr place that contains the library. An administrator or user with a Manager role in the place must add community members as place members before the members can access the library. Membership changes are not synchronized between the community and place, an administrator must update both.
A "Quickr Library" widget creates a new Lotus Quickr place with a library, and surfaces that library in the community. When the place is created, community members are synchronized to Lotus Quickr and made place members. Any membership changes in the community are synchronized to the place. But membership changes in the place are not synchronized to the community. For example, if you add a member to the community, that change is synchronized and they are added to the place. But adding a user to the place will not add them to the community. When the community is deleted, the place and library are deleted.
A community can only have one of each widget.
Download the widgets from the IBM Lotus and WebSphere Portal Business Solutions Catalog.
See the following topics for help adding the widgets to a community:
See the following topics for steps required to configure your environment, steps for installing and configuring the widgets, and steps for uninstalling the widgets:
Configure single sign-on between the Connections and Lotus Quickr servers
You must configure single sign-on between the IBM Connections and Lotus Quickr servers before you can add Lotus Quickr Library widgets to IBM Connections communities.
Both servers must be configured to use the same LDAP.
- On the IBM Connections server, open the WebSphere Application Server Integrated Solutions Console.
- Navigate to Security > Global Security > Web and SIP Security > Single sign-on.
- Make sure single sign-on is enabled.
- Set the domain name to the common domain name suffix of the two servers. For example, if the two servers are connections.my.enterprise.com and quickr.my.enterprise.com, the domain name for SSO could be .my.enterprise.com.
- Navigate to Security > Global Security > LTPA.
- Under cross-cell single sign-on type a password that you will use later, and the location and name of a key file name to export to, for example C:\my.keys
- On the Lotus Quickr server, open the WebSphere Application Server Integrated Solutions Console.
- Navigate to Security > Secure administration, applications, and infrastructure > Web Security > Single sign-on.
- Make sure single sign-on is enabled.
- Set the domain name to the same one set for the IBM Connections server.
- Copy the key file that you exported from IBM Connections in Step 6 to the Lotus Quickr server. For example, copy the C:\my.keys file from the IBM Connections server to a directory on the Lotus Quickr server.
- In the console, navigate to Security > Secure administration, applications, and infrastructure > Authentication mechanisms and expiration.
- Under cross-cell single sign-on enter the password you used in Step 6 to export the keys.
- Enter the path and file name of the key file on the Lotus Quickr server and click Import keys.
- Restart Lotus Quickr server.
Add Connections URLs to the Lotus Quickr Resource Environment provider
You must add IBM Connections server URLs to the Lotus Quickr Resource Environment provider before you can add Lotus Quickr Library widgets to IBM Connections communities.
Add any allowed IBM Connections server URLs. For example, if the server allows http and https URLs, add both.
- On the Lotus Quickr server, open the WebSphere Application Server Integrated Solutions Console.
- Navigate to Resource Environment > Resource Environment Providers.
- Open QuickrDocumentLibraryConfig.
- Select Custom Properties.
- If your Connections server allows http, add new entry with name "pdmConfig.connIntg.host" and server URL value, such as "http://yourserver.com:9080" In deployments with web servers, the URL value should use the web server port, such as "http://yourserver.com:80". If you have TAM enabled on the IBM Connections server, replace yourserver.com with the TAM sever hostname.
- If your Connections server allows https, add new entry with name "pdmConfig.connIntg.secure.host" and server URL value, such as "https://yourserver.com:9443" In deployments with web servers, the URL value should use the web server ssl port, such as "https://yourserver.com:443". If you have TAM enabled on the IBM Connections server, replace yourserver.com with the TAM sever hostname.
- Save settings and restart the Lotus Quickr server.
Install and configuring the Lotus Quickr library widgets
Download the Lotus Quickr library widgets and then install and configure them.
Before you can use the widgets:
- You must configure single sign-on between the IBM Connections and Lotus Quickr servers. See the topic Configuring single sign-on between the Connections and Lotus Quickr servers.
- You must add IBM Connections server URLs to the Lotus Quickr Resource Environment provider. See the topic Add Connections URLs to the Lotus Quickr Resource Environment provider.
- To use the Linked Lotus Quickr library widget there must be an existing Lotus Quickr place with a library in the Lotus Quickr deployment.
- You must install all prerequisites. See the Lotus Quickr Library widget page on the IBM Lotus and WebSphere Portal Business Solutions Catalog web site.
- In SiteMinder environments only, perform the follow tasks on the IBM connections server:
- Copy the US_export_policy.jar and local_policy.jar files from wherever you unpackaged the unrestricted.zip file when configuring SiteMinder. Paste it in the following directory, overwriting the existing versions of those files:
<websphere_application_server>/java/jre/Lib/Security
- Copy the sm_jsafe.jar and sm_jsafeJCE.jar files from the Siteminder ASA crypto-libraries installation directory. Paste it in the following directory, overwriting the existing versions of those files:
<websphere_application_server>/java/jre/lib/ext
- Download the Lotus Quickr Library widget war file from the IBM Lotus and WebSphere Portal Business Solutions Catalog web site.
- Install the widget war file.
- Log in to the WebSphere Administrative Console on the IBM Connections server.
- Navigate to Applications > Application Types > WebSphere enterprise applications.
- Click Install.
- Browse and select the comm.communitylibrary.war file, click Next, and then click Next again.
- In Step 1 of the installation wizard, click Next without changing anything.
- In Step 2, select the cluster and web server (if there is one), and then click Next.
- In Step 3 of the installation wizard, in the Target Resource JNDI Name column, click Browse and select communities. Then click Apply. The field is populated with the value jdbc/sncomm. Then check the box and click Next.
- In Step 4, check the box and then click Next without changing anything.
- In Step 5, type /quickr/connector in the Context Root field, and then click Next.
- In Step 6, click Finish.
- Click Save to save all changes. In clusters you must wait for synchronization to complete before continuing. Check the systemout.log in the /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/nodeagent directory (on Linux servers) to check for the synchronization completed successfully message.
- In the list of applications, select the Lotus Quickr Library widgets application and then click Start to start it.
- Create a J2C authentication alias for the Lotus Quickr administrator.
The server generates a J2C alias with a cell name and the alias name you provided, for example: cell01\quickradmin. You must use this generated alias, including the cell name.
- On the IBM Connections server, log into the WebSphere Application Server Integrated Solutions Console, expand Security, and then select Global Security.
- Expand Java Authentication and Authorization Service.
- Select J2C authentication data.
- Click New.
- Type an alias name (for example quickradmin), and specify the user ID and password credentials of a Lotus Quickr administrator.
If the Lotus Quickr administrative user is not available to IBM Connections (meaning not in the LDAP or defaultFileBasedRepository), then you must add them to the defaultFileBasedRepository. Navigate to Users and Groups > Manage Users, and then create a user with the Lotus Quickr administrator ID and password.
- Copy the widget configuration files to the IBM Connections configuration directory.
- Navigate to the widget \resources_config directory:
\IBM\WebSphere\AppServer\profiles\AppSrv01\installedApps\cell_name\comm_communitylibrary_war.ear\comm.communitylibrary.war\resources_config
- Copy the communities-quickr-library-config.xml and communities-quickr-library-config.xsd files to the \LotusConnections-Config directory:
\IBM\WebSphere\AppServer\profiles\<profile_name>\config\cells\<cell_name>\LotusConnections-configIn clustered deployments, copy the files to the \LotusConnections-Config directory on the deployment manager node.
- Add the widget resource bundle to the LotusConnections-config.xml file.
- Navigate to the widget \resources directory:
\IBM\WebSphere\AppServer\profiles\AppSrv01\installedApps\<cell_name>\comm_communitylibrary_war.ear\comm.communitylibrary.war\resourcesIn clusters, navigate to the directory on any node.
- Copy the contents of the \resources directory to the IBM\LotusConnections\data\shared\customization\strings directory (in clusters, copy to the deployment manager computer).
- Check out and open LotusConnections-config.xml. See Editing configuration files.
- Add the following line of code into the <resources> element block to register the resource bundle for the Quickr Library widget:
<widgetBundle name="com.ibm.quickr.communitylibrary.resources" prefix="quickrCommunityLibrary_res" />
- Add the following widget xml definitions to the widgets-config.xml file, editing values to reflect your environment. In clustered deployments, edit the widgets-config.xml file on the deployment manager node. See steps and most attribute descriptions in the topic Enabling custom widgets for Communities:
<widgetDef bundleRefId="quickrCommunityLibrary_res" defId="LinkedQuickrCommunityLib" description="LinkedQuickrCommunityLibDesc" primaryWidget="false" url="/quickr/connector/com.ibm.quickr.communitylibrary.xml" modes="view edit fullpage" iconUrl="{contextRoot}/nav/common/images/iconFiles16.png" uniqueInstance="true" displayLoginRequired="true" helpLink="http://www.lotus.com/ldd/lcwiki.nsf/dx/Using_the_Linked_Lotus_Quickr_library_widget_ic301"> <itemSet> <item name="iframeLoadTimeout" value="30000" /> </itemSet> </widgetDef> <widgetDef bundleRefId="quickrCommunityLibrary_res" defId="QuickrCommunityLib" description="QuickrCommunityLibDesc" primaryWidget="false" url="/quickr/connector/com.ibm.quickr.communitylibrary.xml" modes="view fullpage" iconUrl="{contextRoot}/nav/common/images/iconFiles16.png" uniqueInstance="true" displayLoginRequired="true" helpLink="http://www.lotus.com/ldd/lcwiki.nsf/dx/Using_the_Lotus_Quickr_library_widget_ic301"> <itemSet> <item name="iframeLoadTimeout" value="30000" /> </itemSet> <lifecycle remoteHandlerURL="remoteHandlerURL/quickr/connector/lifecycle" remoteHandlerAuthenticationAlias="remoteHandlerAuthenticationAlias"> <event>widget.added</event> <event>widget.removed</event> <event>community.members.added</event> <event>community.members.removed</event> <event>community.updated</event> <event>community.visibility.changed</event> <event>community.prepare.delete</event> <event>community.members.modified</event> </lifecycle> </widgetDef>Where:
- In IBM Tivoli Access Manager environments the widgetDef url value must explicitly specify the Quickr server Tivoli Access Manager junction URL. For example, this sample assumes a URL such as https://yourserver.com:port/lotus and only the /quickr/connector/com.ibm.quickr.communitylibrary.xml part is specified. In Tivoli Access Manager environments you must specify the entire URL, for example https://tam.hostname.com:port/lotus/quickr/connector/com.ibm.quickr.communitylibrary.xml.
- The itemSet.item.value attribute is the number of milliseconds Internet Explorer browsers wait to determine if the Lotus Quickr library loaded successfully before showing an error. If Internet Explorer users are seeing only the error page, you can try increasing this value to resolve the issue, particularly if they can see the library in the Firefox browser.
- {contextRoot} is a variable automatically populated with the Connections directory.
- remoteHandlerURL is the URL of the Connections server on which the widget is installed, for example: https://yourserver.com:9443. If you have IBM Tivoli Access Manager enabled on IBM Connections server, replace yourserver.com with the IBM Tivoli Access Manager sever hostname.
- remoteHandlerAuthenticationAlias is the Connections J2C authentication alias used to talk to the servlet. The alias connectionsAdmin is the default for all widgets.
- On the IBM Connections server, open communities-quickr-library-config.xml and update the Lotus Quickr information for your environment, for example:
<host>quickr.example.com</host> <port>10040</port> <sslPort>10035</sslPort> <useSSL>false</useSSL> <authentry>cell01/quickradmin</authentry> <ownersRole>Managers</ownersRole> <membersRole>Editors</membersRole> <publicRole>Readers</publicRole>Where:
- <host> is the Lotus Quickr server hostname. If you have IBM Tivoli Access Manager enabled on Lotus Quickr server, replace yourserver.com with the IBM Tivoli Access Manager sever hostname.
- <port> is the http port number of the Lotus Quickr server. Or if a web server is configured, <port> is the http port number of the web server.
- <sslPort> is the https port number of the Lotus Quickr server. Or if a web server is configured, <port> is the http port number of the web server.
- <useSSL> is whether or not to use http or https in communicating with the Lotus Quickr server. If this is set to "true", the Lotus Quickr server must have a certificate that is trusted by the IBM Connections server. See Secure communications using Secure Sockets Layer in the WebSphere Application Server 6.1 documentation for more information.
- <authentry> is the full name of the J2C authentication alias for the Lotus Quickr administrator that you created in Step 3.
- For <ownersRole>, <membersRole>, and <publicRole> the role names can be either the role title in English or the id field returned for the roles feed. If anonymous access is not allowed, the publicRole element should be omitted or empty. The publicRole is applied in both public and moderated communities, but is not in restricted communities
- In clustered environments, perform a full synchronization of the IBM Connections cluster.
- Restart IBM Connections.
- If you had IBM HTTP Server installed before you installed the Lotus Quickr widget, follow instructions in Mapping applications to IBM HTTP Server to map the Lotus Quickr widget application to the IBM HTTP Server.
Uninstall the Lotus Quickr Library widgets
Uninstall the widget war file, and remove the definitions and resources.
- Uninstall the widget war file.
- Log into the WebSphere Application Server Integrated Solutions Console on the IBM Connections server.
- Navigate to Applications > Application Types > WebSphere enterprise applications and search for "comm.communitylibrary.war".
- Uninstall comm.communitylibrary.war.
- Remove the widget definition added to widgets-config.xml during widget configuration.
- Remove the resources added during widget configuration.
- Remove the resources files added during install to the Connections Data\shared\customization\strings directory.
- Remove the communities-quickr-library-config.xml and xsd files from the LotusConnections-Config directory.
- Check out LotusConnections-config.xml.
- Remove the following line of code in the <resources> element block:
<widgetBundle prefix="quickrCommunityLibrary_res" name="com.ibm.quickr.communitylibrary.resources" />
- Remove J2C alias for Lotus Quickr administrative user, if not still in use for something else.
- Navigate to Security > Global Security > Java Authentication and Authorization Service > J2C Authentication Data.
- Select the J2C alias for Lotus Quickr administrator and click Delete.
- Restart the Communities application. In network deployments, make sure the node synchronizes before restarting Commnunities.
IBM Connections Widget for Microsoft SharePoint
Install the IBM Connections Widget for Microsoft SharePoint to share documents from a SharePoint server with community members.
You must install IBM Connections Plug-in for Microsoft SharePoint in order to use this widget.
Install the SharePoint widget and make it available to community owners. A community owner can then add the widget to a community so that community members can view and edit files uploaded from a SharePoint server.
Install the SharePoint widget for Communities
Install the Microsoft SharePoint widget so that Community owners can make it available for members to use.
These instructions are for installing the IBM Connections Widget for Microsoft SharePoint for an English-language deployment. If you want to make the widget available in other languages, follow the installation instructions in the topic Installing the non-English version of the SharePoint widget for Communities.
This widget requires that IBM Connections Plug-in for Microsoft SharePoint be installed before you use the widget. Before you begin, familiarize yourself with how to install widgets for the Communities application. For details, see this topic: Add custom widgets to Communities Install the SharePoint widget so that community owners can make the widget available in a community. Community members can then upload and share documents from a SharePoint server.
- Follow the steps for checking out the widgets-config.xml, documented here: Enable custom widgets for Communities.
- Add the xml definition for the SharePoint widget to the Communities section of the widgets-config.xml:
<widgetDef defId="SharePoint Documents" description="SharePointFiles" modes="edit view fullpage" uniqueInstance="true" url="/SPWidgets/SPFiles/SPFiles.xml?version={version}" helpLink="http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Using_the_SharePoint_widget_lc3" iconUrl="/SPWidgets/SPFiles/images/spSite.png"> </widgetDef>
- Check in the widgets-config.xml file as documented in the custom widgets topic.
- Install the SharePoint widget ear file on the same server as the Communities application, as follows:
- Log into the Websphere Application Server console.
- Select Install New Application and browse for the name of the SharePoint ear file you downloaded from the IBM Connections catalog web site: https://greenhouse.lotus.com/catalog.
- Accept the installation defaults, but select the cluster
...where the Communities application is installed. If you are using an IHS server, select that as well or you will not be able to access the SharePoint widget after you install it.
- Save the configuration changes. A confirmation screen will confirm that the application SharePointContent is installed.
- Select Applications -> Enterprise Applications and start the application SharePointContent.
If starting the SharePointContent application produces errors in the WAS console, wait and try again. The installation might not be distributed to each application server.Does
- To see the widget on the Customize palette for Communities, restart the Deployment Manager, restart the server cluster, and restart the Communities application.
If your SharePoint Server and IBM Connections hosting the Communities application are not in the same domain, add the domain of the SharePoint server to the DNS settings of the IBM Connections server. Otherwise, your users will get an error when trying to create a new community on a server with the SharePoint widget deployed.
- If IBM Connections is configured to use single sign-on with IBM Tivoli® Access Manager, configure a transparent path junction for the Sharepoint widget if you want to get Sharepoint documents in Connections communities under TAM. Follow the steps for configuring a transparent path junction in the topic Enabling single sign-on for Tivoli Access Manager. Run this server task to enable the TAM junction:
'server task <WebSEAL-instance-name> create -t ssl -h <backend-server-name> -x -p <backend-server-port> -i -b ignore -f -A -2 -F <ltpa-token> -Z <ltpa-password> /SPWidgets'
- If IBM Connections is configured to use a reverse proxy that directs all IBM Connections traffic to a single server, you must add some mapping rules so that the widget will be accessible.
- Refer to the topic Configuring a reverse caching proxy for instructions on adding mapping rules.
- In the Mapping Rules section, add the following reverse pass rules for the SharePoint widget:
ReversePass http://<httpserver>/SPWidgets* http://<proxyserver>/SPWidgets* ReversePass https://<httpserver>/SPWidgets* https://<proxyserver>/SPWidgets*...where <httpserver> is the host name of the HTTP server. The HTTP server is usually IBM HTTP Server, but could be a load balancer or another proxy, depending on your deployment. <proxyserver> is the host name of the proxy server.
What to do next
Once the SharePoint widget is available for the Communities application, a community owner can click the Community Actions button for the community and add the SharePoint widget to the community from the widget panel.
You can configure the widget to change how users interact with the widget. To make configuration changes:
- Copy the sharepoint-library-config.xml and sharepoint-library-config.xsd files from the configuration folder where the SharePoint widget is installed into the LotusConnections-Config directory on the IBM Connections server.
- Edit any of the variables in the sharepoint-library-config.xml file.
Variable Description maxUploadSize The maximum size in MB of a file that can be uploaded through the SharePoint widget to the SharePoint server. This does not apply to SPNEGO and TAM configurations.
uploadTimeout Number of seconds before an upload will timeout. For an infinite timeout, specify 0 seconds. authenticationType Specified the default authentication type that will be selected during widget editing, allowed values are: Windows, SPNEGO, SiteMinder, TAM, Forms, Web single sign on. hideAuthenticationOptions Prevents the community owner from changing the default authentication type by hiding the authentication.
- Save the changes and synchronize the nodes.
- Stop and restart the SharePointContent application.
If you want to support file uploads from SharePoint to Connections that exceed 50MB, you must edit a supplemental web configuration file. Perform these steps on all front end web servers.
- Copy the webconfig.IBMConnections.xml file from the configuration folder where the SharePoint widget is installed to the SharePoint CONFIG directory. For example: C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\CONFIG.
- Open webconfig.IBMConnections.xml in an editor and change the value of the MaxRequestSize variable. Note that the value is defined in KB, not MB.
- Save the changes and apply the changes to the web server.
- Open a command window and navigate to a BIN directory. For example:
c:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\BIN
- Enter stsadm -o copyappbincontent
- Click Run.
Install the non-English version of the SharePoint widget for Communities
Install the Microsoft SharePoint widget so that Community owners can make it available for members to use in languages other than English.
This widget requires that you install the IBM Connections plug-in for Microsoft SharePoint before you use the widget. Before you begin, familiarize yourself with how to install widgets for the Communities application. For details, see this topic: Enable custom widgets for Communities. To enable the widget for languages other than English, you should also be familiar with enabling custom strings for widgets, described in this topic: Add custom strings for widgets and other specified scenarios. Enable the language strings so that the widget can display in languages other than English, then install the SharePoint widget so that community owners can make the widget available in a community. Community members can then upload and share documents from a SharePoint server.
- Follow the steps for adding a resource bundle to the LotusConnections-config.xml file, documented in the topic Add custom strings for widgets and other specified scenarios.
- Extract spwidgets.files_res.zip and copy the spwidgets_res file to a resources directory.
- Check out LotusConnections-config.xml.
- Add the following line of code into the <resources> element block to register the resource bundle for the SharePoint widget:
<resources> <widgetBundle prefix="spwidgets_res" name="com.ibm.connections.sp.files.resources"/> </resources>
- Check in LotusConnections-config.xml.
- Follow the steps for checking out the widgets-config.xml, described in the topic Enabling custom widgets for Communities.
- Add the xml definition for the SharePoint widget to the Communities section of the widgets-config.xml:
<widgetDef defId="SharePointFiles" description="SharePointFilesDesc" bundleRefId="spwidgets_res" modes="edit view fullpage" uniqueInstance="true" url="/SPWidgets/SPFiles/SPFiles.xml?version={version}" helpLink="http://www-10.lotus.com/ldd/lcwiki.nsf/dx/Using_the_SharePoint_widget_lc3" iconUrl="/SPWidgets/SPFiles/images/spSite.png"> </widgetDef>
- Check in the widgets-config.xml file as documented in the custom widgets topic.
- Install the SharePoint widget ear file on the same server as the Communities application, as follows:
- Log in to the WebSphere Application Server console.
- Select Install New Application and browse for the name of the SharePoint ear file you downloaded from the IBM Connections catalog web site: https://greenhouse.lotus.com/catalog.
- Accept the installation defaults, but select the cluster
...where the Communities application is installed. Accept the installation defaults, but select the server or servers where the Communities application is installed. If you are using an IHS server, select that as well or you will not be able to access the SharePoint widget after you install it.
- Save the configuration changes. A confirmation screen confirms that the application SharePointContent is installed.
- Select Applications -> Enterprise Applications and start the application SharePointContent.
If starting the SharePointContent application results in errors in the WAS console, wait and try again. The application might not be distributed to all application servers.
- To see the widget on the Customize palette for Communities, restart the Deployment Manager, restart the server cluster, and restart the Communities application.
If your SharePoint Server and IBM Connections hosting the Communities application are not in the same domain, add the domain of the SharePoint server to the DNS settings of the IBM Connections server. Otherwise, your users are presented with an error when trying to create a new community on a server with the SharePoint widget deployed.
- If IBM Connections is configured to use single sign-on with IBM Tivoli® Access Manager, configure a transparent path junction for the Sharepoint widget if you want to get Sharepoint documents in Connections communities under TAM. Follow the steps for configuring a transparent path junction in the topic Enabling single sign-on for Tivoli Access Manager. Run this server task to enable the TAM junction:
'server task <WebSEAL-instance-name> create -t ssl -h <backend-server-name> -x -p <backend-server-port> -i -b ignore -f -A -2 -F <ltpa-token> -Z <ltpa-password> /SPWidgets'
- If IBM Connections is configured to use a reverse proxy that directs all IBM Connections traffic to a single server, you must add some mapping rules so that the widget will be accessible.
- Refer to the topic Configuring a reverse caching proxy for instructions on adding mapping rules.
- In the Mapping Rules section, add the following reverse pass rules for the SharePoint widget:
ReversePass http://<httpserver>/SPWidgets* http://<proxyserver>/SPWidgets* ReversePass https://<httpserver>/SPWidgets* https://<proxyserver>/SPWidgets*...where <httpserver> is the host name of the HTTP server. The HTTP server is usually IBM HTTP Server, but could be a load balancer or another proxy, depending on your deployment. <proxyserver> is the host name of the proxy server.
What to do next
Once the SharePoint widget is available for the Communities application, a community owner can click the Community Actions button for the community and add the SharePoint widget to the community from the widget panel.
For information on enabling languages, see the topic Enabling users to set a language preference.
IBM Connections Connector for Lotus Quickr
As administrator, you can enable IBM Lotus Quickr integration with the Communities application, allowing community members to organize and share files, and collaborate on documents from a central location.
Integration with Lotus Quickr gives the communities in your organization a place to store and manage files. Communities associated with a team place in Lotus Quickr can aggregate updates in the community overview page, making it easier to stay current with projects and work collaboratively.
The Activities application can also be integrated with Lotus Quickr, allowing users to publish documents from an activity to a Lotus Quickr space. For more information, see Integrating Activities with IBM Lotus Quickr.
The following prerequisites currently apply to Lotus Quickr integration with Communities:
- The Lotus Quickr server and the IBM Connections server must be using the same LDAP server.
- The Lotus Quickr server and the IBM Connections server must be in the same domain.
- Single sign-on (SSO) must be enabled between WebSphere Application Server and Lotus Quickr. In addition, the realm name specified in the SSO configuration for both systems must match. For more information, see Enabling single sign-on for Lotus Quickr.
- When using the REST API interface to create Lotus Quickr places, the user must be registered as an administrator on the Lotus Quickr server.
Integration between Communities and Lotus Quickr is currently supported for Lotus Quickr services for WebSphere Portal and Lotus Quickr services for Lotus Domino. To find out what versions of Lotus Quickr are supported for this release of IBM Connections, see Detailed system requirements for IBM Connections.
CAUTION:After you have installed the IBM Connections Connector for Lotus Quickr, it is important that the owner of a Lotus Quickr place does not delete the place or change the membership of the place using the Lotus Quickr APIs. In addition, the Lotus Quickr administrator must not use administrative commands to delete a place or change the membership of a place. These actions might disrupt the synchronization that is carried out by the connector.
Related
Associated applications Administer Communities
Publishing attachments to Lotus Quickr
Install the IBM Connections Connector for Lotus Quickr
Install the IBM Connections Connector for Lotus Quickr by doing one of the following:
Use the Lotus Quickr connector installation wizard
Install the IBM Connections connector for Lotus Quickr to bring file-sharing capabilities and collaboration functionality to your communities.
- You only need to install the Lotus Quickr connector on the Deployment Manager server. The Deployment Manager will then synchronize the changes to the remaining nodes.
- When planning your integration, ensure that Lotus Quickr and IBM Connections use the same protocol . http or https.
- Download the connector from the IBM Connections catalog on the following web site to the IBM Connections Deployment Manager machine:
https://greenhouse.lotus.com/catalog
- From the Connector Install Directory, open the quickr directory and run the executable file to launch the installation wizard for your deployment using one of the following commands.
- AIX, Linux, and Linux on System z®:
install.sh
- Microsoft
Windows:
install.bat
- Select the packages to install and click Next.
- Review and accept the license agreement by selecting I accept the terms in the license agreements. Then click Next to continue.
- Set the location where you want to install the connector in the Installation Directory field, and then click Next.
- Select the features to install, and then click Next.
- Specify which Lotus Quickr deployment type you want to use.
- Select the Quickr Integration Selection options to enable for your deployment.
- Under Configuration Sets, enter the host name of the Lotus Quickr server in the Quickr server host name field.
For example: quickr.example.comIf your Lotus Quickr solution is integrated with IBM Tivoli Access Manager or if it uses a proxy server, then you need to specify the Tivoli Access Manager or proxy server address instead of a direct remote HTTP or Lotus Quickr server address.
- Enter the Lotus Quickr server port number in the Quickr server port field.
For example: 80
- Enter the number of the port to connect to the Lotus Quickr application over SSL in the Quickr server ssl port field.
For example: 9443Do not leave this field blank. If SSL is not configured, enter 443 as the SSL port.
- Enter the authentication alias created by the installer for the superuser to use for managing Lotus Quickr in the J2C authentication user name field. This user name is required to authenticate.
For example: adminNotes:
- If you are installing the connector in a Lotus Quickr for Lotus Domino deployment, the user provided here must have permission to create places on the Lotus Quickr server. If the Lotus Quickr server is configured to allow anyone with server access to create places, then permission does not need to be explicitly set for the user.
For information about granting access to create places on the Lotus Quickr server, go to the following web page:
http://publib.boulder.ibm.com/infocenter/lqkrhelp/v8r0/topic/com.ibm.lotus.quickr.admin.dom.doc/admin/qp_adm_sec_places_t.html
- In a Lotus Quickr for Lotus Domino deployment, the superuser must also be listed as an administrator on the Lotus Quickr server. For information about giving administrator access to additional users, go to the following web page:
http://publib.boulder.ibm.com/infocenter/lqkrhelp/v8r0/index.jsp?topic=/com.ibm.lotus.quickr.admin.dom.doc/admin/qp_adm_sec_serveradmin_t.html
- Enter the password associated with the authentication alias that you provided in the previous step in the J2C authentication password field, and then click Next to continue.
- On the Install Locations panel, specify the location of the IBM Connections installation home directory in the IBM Connections install home directory field and click Validate.
For example: C:\IBM\Connections
The Connector libraries install location and Connector configuration install location fields are automatically populated when you specify the directory where IBM Connections is installed.
- Click Next to continue.
- Review the summary of the information that you have entered. To make changes, click Back. To start the installation, click Next.
- Review the results of the installation and click Finish to complete the installation process.
What to do next
After running the installation wizard, there are a number of steps required to perform to complete the networked installation. See the topic Completing the installation of the LotusQuickr connector for more information.By default, IBM Connections won't pass cookies and authorization-related headers to or from external servers for feeds. To enable trusted feeds from the Lotus Quickr server for Communities, you need to configure the Ajax proxy with the settings that you want. For more information, see Supporting Lotus Quickr authenticated feeds.
Complete the installation of the Lotus Quickr connector
When installing the IBM Connections connector for Lotus Quickr in a network environment, you need to perform a number of steps on the Deployment Manager server to complete the installation.
Install the Lotus Quickr connector on the Deployment Manager server. For information on how to install the connector, see Installing the IBM Connections Connector for Lotus Quickr.
After you have installed the Lotus Quickr connector on the Deployment Manager server, perform the following steps to complete the network installation.
- Log in to the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- Select System administration > Nodes, select All nodes, and then click Full Resynchronize.
- Select System administration > Node agents.
- Select the nodes that have been updated, and then click Stop.
- Start the nodes on each node machine.l
What to do next
The Lotus Quickr Delayed Synchronizer propagates community membership changes to associated Lotus Quickr places if the Lotus Quickr server is down when a community change occurs. In a networked environment, you need to edit the communities-quickr-config.xml file to ensure that the Lotus Quickr Delayed Synchronizer is only enabled on one server. For more information, see Configuring delayed synchronization.
Install the Lotus Quickr connector in silent mode
Install the IBM Lotus Quickr connector for Communities in silent mode when you want to use a response file to automate installation. In addition to modifying the default response files, you also can generate a silent response files with Installation Manager. See: http://pic.dhe.ibm.com/infocenter/install/v1r4/topic/com.ibm.silentinstall12.doc/topics/t_silent_create_response_files_IM.html .
To install the Lotus Quickr connector in silent mode, complete the following steps.
- Open a command prompt and change to one of the following directories.
- AIX, Linux, or Linux on System z:
LC_Connector_Install_IM\IM\linux
- Microsoft
Windows:
LC_Connector_Install_IM\IM\windows
- Enter one of the following commands to install the connector:
- AIX, Linux, or Linux on System z:
install.silent.sh
- Microsoft
Windows:
install.silent.bat
Supporting Lotus Quickr authenticated feeds
By default, the IBM Connections proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the IBM Connections applications. It also prevents HTTP GET requests from non-IBM Connections services and prevents all cookies or headers from being directed to the applications.
To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client. See Starting the wsadmin client for details. If you want to make changes to the traffic that is allowed from other services, for example, to enable trusted feeds from the IBM Lotus Quickr server for Communities, you must explicitly configure it. Feeds for private communities in Lotus Quickr Domino and all feeds in Lotus Quickr Portal require authentication. By default, IBM Connections won't pass cookies and authorization-related headers to and from external servers for feeds.
The following policy allows GET requests to be passed to any web address. If you want to allow your users to have access to all web sites, remove the comments from around this policy. For example, users who add a feed to a community will see a 403 error
...where the feed results should be displayed unless you perform this step. Be sure that the policy is listed as the last policy in the configuration file.
<!--proxy:policy url="*" acf="none"> <proxy:actions> <proxy:method>GET</proxy:method> <proxy:headers/> <proxy:cookies/> </proxy:policy-->When uncommented, this policy specifies that feeds can exchange GET methods with non-IBM Connections hosts. The empty <proxy:cookies/> and <proxy:headers/> elements mean that cookies and headers are not allowed. If you want to allow a host to exchange cookies or headers, or to perform PUT, POST, or DELETE methods, add a new policy that supports this.To create a policy that provides support for Lotus Quickr authenticated feeds:
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Open a command-line window, start the wsadmin tool, and then use the following commands to access the IBM Connections configuration files:
execfile("<$WAS_HOME>/profiles/<DMGR>/bin/connectionsConfig.py")execfile("<$WAS_HOME>/profiles/<DMGR>/bin/communitiesAdmin.py")
- Check out the proxy configuration file :
LCConfigService.checkOutProxyConfig("working-directory", "cell-name")...where:
- working-directory is the temporary working directory to which the configuration TPL and XSD files are copied. The files are kept in this working directory while you make changes to them.
AIX and Linux only: The directory must grant write permissions or the command will not run successfully.
- cell-name is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is required. It is also case-sensitive, so type it with care.
- Open the proxy-config.tpl file in a text editor.
- Add the following <proxy:policy> entry before the default policy, replacing quickrserver.example.com with the host name of your Lotus Quickr server. Be sure to insert the custom policy earlier in the code than the default policy, if one exists.
If a web server is not used with Lotus Quickr then a port number is required in the URL. The default ports in a non-clustered environment are 10040 for http and 10035 for https.
<proxy:policy url="http://quickrserver.example.com/*" acf="none" basic-auth-support="true" auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept*</proxy:header> <proxy:header>Content*</proxy:header> <proxy:header>Authorization*</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> </proxy:cookies> </proxy:policy>You should also include an HTTPS policy to allow for users who choose to use or are forced to use an SSL connection.For example:
<proxy:policy url="https://quickrserver.example.com/*" acf="none" basic-auth-support="true" auth-support="true"> <proxy:actions> <proxy:method>GET</proxy:method> </proxy:actions> <proxy:headers> <proxy:header>User-Agent</proxy:header> <proxy:header>Accept*</proxy:header> <proxy:header>Content*</proxy:header> <proxy:header>Authorization*</proxy:header> </proxy:headers> <proxy:cookies> <proxy:cookie>JSESSIONID</proxy:cookie> <proxy:cookie>LtpaToken</proxy:cookie> <proxy:cookie>LtpaToken2</proxy:cookie> </proxy:cookies> </proxy:policy>Depending on your configuration, the <proxy:policy> section might require more or less detail. The following table lists some common cookies and headers that might be required under different configurations.Table 99. Common cookies or headers
Cookie/Header Description SMSESSION SiteMinder session cookie that passes SiteMinder credentials to Lotus Quickr. PD-H-SESSION-ID Non-secure Tivoli Access Manager session cookie that passes Tivoli Access Manager credentials to Lotus Quickr. PD-S-SESSION-ID Secure Tivoli Access Manager session cookie that passes the secure version of the Tivoli Access Manager cookie to Lotus Quickr. WWW-AUTHENTICATE Secure socket layer (SSL) header that passes SSL authentication when connecting to a secure Lotus Quickr deployment.
- After making your changes, save and close the proxy-config.tpl file.
- To check in the proxy-config.tpl file, use the following command:
LCConfigService.checkInProxyConfig("working-directory", "cell-name")
- To exit the wsadmin client, type exit at the prompt.
- Stop and restart the application servers hosting IBM Connections.
Edit the Lotus Quickr configuration file
You can edit settings in the IBM Lotus Quickr configuration XML file to change the values that you entered at install time or to add a custom place type.
The Quickr Connector cannot use the string customization mechanism that the core product uses. When you install the IBM Connections connector for Lotus Quickr, you can specify whether to enable support for Lotus Quickr wiki and team place templates. You can also specify the host, ports, user ID, and passwords to use. The installer then updates the configuration file with this information.
Each enabled place type shows up as a separate associated application in the Communities user interface. A maximum of five associated applications can be shown. If you need to change the information you supplied at install time, for example, if you want to disable a template that you enabled during installation, or add custom place types, you can do so by editing the communities-quickr-config.xml file. You can also edit the configuration file to change the roles associated with a Lotus Quickr place type. For more information, see Configuring roles for Lotus Quickr places.
When editing the communities-quickr-config.xml file, note that for each <comm:QuickrPlaceType> element, the name attribute must be unique. The <comm:managedApplicationTypeID> must also be unique and it cannot be changed. It must be 24 bytes or less.
You use the <comm:placeTemplate> template to create a place. The <comm:server> element must match the name of a <comm:QuickrServer> element. The <comm:resourceBundleName> entry is the name of a property file on the Communities application classpath for strings presented in the user interface. The property file must have the following keys:
For <comm:ownersRole>, <comm:membersRole>, and <comm:publicRole> the role names can be either the role title in English or the ID field returned for the roles feed. If anonymous access is not allowed, the <comm:publicRole> element should be omitted or left empty.
- label.applicationName
- label.applicationShortName
- str.place.title - The value may contain a {0} placeholder for the name of the community.
The <comm:contentFeedLink> element is the name of the link field in a place entry to be used for the place's feed. This is an optional field. For IBM Lotus Domino server, always use content as the value. For WebSphere Portal wikis, wikis and blogs are valid values. For WebSphere Portal team places, valid values are "wikis", "blogs", and "documentLibraries".
To edit the configuration information for Lotus Quickr integration, complete the following steps:
- Use a text editor to open the communities-quickr-config.xml file from the following location on the file system of the Deployment Manager:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\<cell_name>\LotusConnections-config
- Make the required changes in the file.
For example:
<comm:QuickrPlaceType name="DominoWiki" enabled="true"> <comm:managedApplicationTypeID>QuickrDominoWiki</comm:managedApplicationTypeID> <comm:placeTemplate>Wiki</comm:placeTemplate> <comm:server>Domino</comm:server> <comm:resourceBundleName>com.example.lconn.comm.quickr.resources.QuickrWikiResources </comm:resourceBundleName> <comm:ownersRole>Manager</comm:ownersRole> <comm:membersRole>Editor</comm:membersRole> <comm:publicRole>Reader</comm:publicRole> <comm:contentFeedLink>content</comm:contentFeedLink> </comm:QuickrPlaceType> <comm:QuickrPlaceType name="PortalTeamPlace" enabled="true"> <comm:managedApplicationTypeID>QuickrPortalTeamspace</comm:managedApplicationTypeID> <comm:placeTemplate>Team Place</comm:placeTemplate> <comm:server>Portal</comm:server> <comm:resourceBundleName>com.example.lconn.comm.quickr.resources.QuickrTeamspaceResources </comm:resourceBundleName> <comm:ownersRole>Managers</comm:ownersRole> <comm:membersRole>Editors</comm:membersRole> <comm:publicRole>Readers</comm:publicRole> <comm:contentFeedLink>documentLibraries</comm:contentFeedLink> </comm:QuickrPlaceType> <!-- **************************************************************************************************** Multiple QuickServer entries are allowed. For each comm:QuickrServer, the name attribute must be unique. comm:host is the server hostname. comm:port is the http port number. comm:sslPort is the https port number. comm:authentry is the name of the authentication alias resource created within the WAS Admin console comm:serverType must match the name of a QuickrServerType **************************************************************************************************** --> <comm:QuickrServer name="Domino"> <comm:host>commdev01.example.com</comm:host> <comm:port>80</comm:port> <comm:sslPort>443</comm:sslPort> <comm:authentry>MyCell/DominoAlias</comm:authentry> <comm:serverType>Domino</comm:serverType> </comm:QuickrServer> <comm:QuickrServer name="Portal"> <comm:host>commdev01.example.com</comm:host> <comm:port>10038</comm:port> <comm:authentry>MyCell/PortalAlias</comm:authentry> <comm:serverType>Portal</comm:serverType> </comm:QuickrServer>
- Save your changes and then apply them by doing the following:
- Log in to the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- Select System administration > Nodes, select all the nodes, and then click Full Resynchronize.
- From the main Integrated Solutions Console page, select Servers > Clusters.
- Select the check box for the cluster containing the nodes that have been updated, and then click Stop.
- Select the cluster and click Start.
- Optional: Place the properties file in the Communities classpath.
\profiles\AppSrv0xxx\installedApps\xxxCell\Communities.ear\comm.web.war\WEB-INF\classes\
Where AppSrv0xxx and xxxCell must match the profile name and cell name for your deployment.
For example, if your communities-quickr-config.xml file contains <comm:resourceBundleName>com.ibm.lconn.comm.quickr.resources.QuickrTeamspace2Resources</comm:resourceBundleName>, then create the folder structure com\ibm\lconn\comm\quickr\resources within \installedApps\<cellname>\Communities.ear\comm.web.war\WEB-INF\classes\. Place QuickrTeamspace2Resources.properties in this directory, for example \profiles\AppSrv01\installedApps\localCell01\Communities.ear\comm.web.war\WEB-INF\classes\com\ibm\lconn\comm\quickr\resources\QuickrTeamspace2Resources.properties. Make sure that QuickrTeamspace2Resources.properties file contains the three keys. For example:
- label.applicationName=Europe Teamspace Wiki
- label.applicationShortName=Teamspace Wiki
- str.place.title=Europe Wiki for {0}
- Once the properties files are in place for all nodes, restart Communities.
Configure roles for Lotus Quickr places
Edit settings in the IBM Lotus Quickr configuration XML file to change the roles associated with Lotus Quickr place types. When you install the IBM Connections connector for Lotus Quickr, you can specify whether to enable support for Lotus Quickr wiki and team place templates. The installer then updates the communities-quickr-config.xml configuration file with this information. If you want to change the roles associated with a Lotus Quickr place type, you can do so by editing the configuration file. For example, you might want to configure settings so that when your users create a Lotus Quickr place that is associated with a community, the owners of the community are also owners of the Lotus Quickr place.
For more information about editing settings in the communities-quickr-config.xml file, see Editing the Lotus Quickr configuration file.
To edit the roles associated with Lotus Quickr place types:
- Use a text editor to open the communities-quickr-config.xml file from the following location on the file system of the Deployment Manager:
C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\<cell_name>\LotusConnections-config
- Look for the section of the file that lists the <comm:QuickrPlaceType> entries and update the values of the <comm:ownersRole>, <comm:membersRole>, and <comm:publicRole> elements for each entry as required.
The following code is just one example of a <comm:QuickrPlaceType> entry.<comm:QuickrPlaceType name="DominoTeamspace" enabled="true"> <comm:managedApplicationTypeID>QuickrDominoTeamspace</comm:managedApplicationTypeID> <comm:placeTemplate>h_StdPlaceType</comm:placeTemplate> <comm:server>DefaultServer</comm:server> <comm:resourceBundleName>com.ibm.lconn.comm.quickr.resources.QuickrTeamspaceResources</comm:resourceBundleName> <comm:ownersRole>Superuser</comm:ownersRole> <comm:membersRole>Editor</comm:membersRole> <comm:publicRole>Reader</comm:publicRole> <comm:contentFeedLink>content</comm:contentFeedLink> </comm:QuickrPlaceType>The following roles are supported.
- Lotus Quickr services for Lotus Domino:
- Author
- Editor
- Manager
- Reader
- Superuser
- Lotus Quickr services for WebSphere Portal:
- Contributors
- Editors
- Managers
- Readers
If anonymous access is not allowed, the <comm:publicRole> element should be omitted or left empty.
- Save your changes and then apply them by doing the following:
- Log in to the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- Select System administration > Nodes, select all the nodes, and then click Full Resynchronize.
- From the main Integrated Solutions Console page, select Servers > Clusters.
- Select the check box for the cluster containing the nodes that have been updated, and then click Stop.
- Select the cluster and click Start.
Enable SSL access to the Lotus Quickr server
To enable the use of Secure Sockets Layer (SSL), you need to manually edit the communities-quickr-config.xml configuration file.
To secure access between the Communities server and the IBM Lotus Quickr server, perform the following steps.
- On the file system of the Deployment Manager, use a text editor to open the communities-quickr-config.xml file from the following subdirectory:
<WAS_HOME>/profiles/<profile_name>/config/cells/<cell_name>/LotusConnections-config/communities-quickr-config.xml
- Set the <comm:useSSL> element to true as follows:
<comm:useSSL>true</comm:useSSL>
- Save your changes and then apply them .
- Log in to the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- Select System administration > Nodes, select all the nodes, and then click Full Resynchronize.
- From the main Integrated Solutions Console page, select Servers > Clusters.
- Select the check box for the cluster containing the nodes that have been updated, and then click Stop.
- Select the cluster and click Start.
Integrate with SiteMinder and Tivoli Access Manager
If you have enabled IBM Connections to use Computer Associates' SiteMinder or IBM Tivoli Access Manager for user authentication and single sign-on (SSO), and you have configured your deployment for integration with Lotus Quickr, you need to manually edit the communities-quickr-config.xml configuration file to disable the use of SSO. SSO must also be disabled when using SPNEGO; otherwise the Lotus connectors will not function properly.
When integrating Lotus Quickr with IBM Connections, note that you must perform additional steps to secure Lotus Quickr when Tivoli Access Manager is enabled. For more information, go to the following web page:
http://www-10.lotus.com/ldd/lqwiki.nsf/dx/Configure_TAM_and_WebSEAL_with_Lotus_Quickr_qp85
To disable SSO for Lotus Quickr, complete the following steps:
- Use a text editor to open the communities-quickr-config.xml file from the following subdirectory on the file system of the Deployment Manager.
<WAS_HOME>/profiles/<profile_name>/config/cells/<cell_name>/LotusConnections-config/communities-quickr-config.xml
- Set the <comm:useSSO> element to false as follows:
<comm:useSSO>false</comm:useSSO>
- For a Tivoli Access Manager environment only, add a junction in contextPath as follows:
<comm:QuickrServerType name="Domino"> <comm:contextPath>QuickrD_Junction/dm/atom/</comm:contextPath> <comm:publicEntry id="oid:null"><member type="user" dn="Anonymous"/></comm:publicEntry> <comm:publicEntry id="oid:null"><member type="user" dn="Default"/></comm:publicEntry> </comm:QuickrServerType>
- Save your changes and then apply them by doing the following:
- Log in to the WebSphere Application Server Integrated Solutions Console for the Deployment Manager.
- Select System administration > Nodes, select All nodes, and then click Full Resynchronize.
- From the main Integrated Solutions Console page, select Servers > Clusters.
- Select the check box for the cluster containing the nodes that have been updated, and then click Stop.
- Select the cluster and click Start.
Use the Lotus Quickr Delayed Synchronizer
The IBM Lotus Quickr Delayed Synchronizer propagates community membership changes to Lotus Quickr places if the Lotus Quickr server is down when changes in community membership are made.
You can edit configuration property settings to control the delayed synchronization task, and use administrative commands to mark the communities containing links to Lotus Quickr Wikis or Teamspaces for full membership synchronization. Marking a community in this way forces a full membership and visibility (public or private access) synchronization to the Lotus Quickr Teamspace or Lotus Quickr Wiki server the next time that the synchronization task runs.
Configure delayed synchronization
When you install the IBM Lotus Quickr connector, the delayed synchronization task is automatically configured with default settings. If you want to change those settings to values that better suit your deployment, you need to edit the <QuickrDelayedSync> settings in the communities-quickr-config.xml file. The Lotus Quickr Delayed Synchronizer reconciles inconsistencies in membership synchronization between a Lotus Quickr place and its associated community. A community's membership might go out of synchronization from time to time, for example, if the Lotus Quickr server is down when new members are being added to or deleted from a community. The Delayed Synchronizer looks at all the communities that have been modified in the past 14 days to check if the membership between the communities and the associated Lotus Quickr places has fallen out of synchronization. The synchronizer then propagates any changes to the Lotus Quickr place at a later time.
To configure delayed synchronization between Lotus Quickr places and their associated communities, complete the following steps on the file system of the Deployment Manager:
- Navigate to the following subdirectory to locate the communities-quickr-config.xml file:
<WAS_HOME>/profiles/<profile_name>/config/cells/<cell_name>/LotusConnections-config/ communities-quickr-config.xml
- Open the file with a text editor and navigate to the bottom of the file to locate the QuickrDelayedSync settings. The QuickrDelayedSync task information looks similar to the following:
<comm:QuickrDelayedSync enabled="true"> <comm:startDelay value="60"/> <!-- minutes --> <comm:taskInterval value="60"/> <!-- minutes --> <comm:daysBackToScan>14</comm:daysBackToScan> </comm:QuickrDelayedSync>
- Update the settings as required. The following table displays information regarding the QuickrDelayedSync properties and the type of data that you can enter for them:
Table 100. QuickrDelayedSync properties
Property Description QuickrDelayedSync.enabled Enables synchronization to occur. This property takes a Boolean value: true or false. QuickrDelayedSync.startDelay The delay in minutes before the task starts. This property takes an integer value. QuickrDelayedSync.taskInterval The delay in minutes between consecutive tasks. This property takes an integer value. QuickrDelayedSync.daysBackToScan Limits the search for community changes. The default value of 14 indicates that only communities that have been modified in the past two weeks will be checked for missed propagations. This property takes an integer value.
- Save your changes to the communities-quickr-config.xml file.
- To apply your changes, stop and restart the Communities server.
What to do next
When you have multiple WebSphere Application Servers running the Communities application, you must ensure that the Lotus Quickr Delayed Synchronizer is only enabled on one server by doing the following:
- On the file system of the Deployment Manager, open the communities-quickr-config.xml file in a text editor. Edit the file so that the <comm:serverToRunOn> element contains a string in the following format:
cellname\nodename\servername
For example:
<comm:serverToRunOn>acmeNode01Cell\acmeNode01\server1</comm:serverToRunOn>
- Save your changes and then apply them by doing the following:
- Select System administration > Nodes, select all the nodes, and then click Full Resynchronize.
- From the main Integrated Solutions Console page, select Servers > Clusters.
- Select the check box beside the cluster containing the nodes that have been updated, and then click Stop.
- Select the cluster and click Start.
Marking a community for synchronization
The IBM Lotus Quickr Delayed Synchronizer should automatically propagate changes after a Lotus Quickr server outage; however, in unusual circumstances, such as restoring a Lotus Quickr place from backup, you might want to force a full synchronization to occur. You can mark an IBM Connections community that contains links to a Lotus Quickr Wiki or Teamspace so that the synchronizer performs a full synchronization between the membership of the place and the membership of its associated community when the synchronization task next runs.
To use administrative commands, you must use the wsadmin client. See Start the wsadmin client for details. The Lotus Quickr Delayed Synchronizer propagates community membership changes to associated Lotus Quickr places if the Lotus Quickr server is down when a community change occurs. The synchronizer also grants or removes public access to match the associated community's visibility. The synchronizer runs hourly by default.
You need to ensure that the delayed synchronization task is only enabled on one server in the cluster. For more information, see What to do next in the topic Configuring delayed synchronization.
To mark a community for synchronization, complete the following steps.
- Start the wsadmin client from the following directory of the system on which you installed the Deployment Manager:
app_server_root\profiles\dm_profile_root\bin...where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01.
You must start the client from this directory or subsequent commands that you enter do not execute correctly.
- Start the Communities Jython script interpreter :
execfile("communitiesAdmin.py")If prompted to specify a service to connect to, type 1 to pick the first node in the list. Most commands can run on any node. If the command writes or reads information to or from a file using a local file path, you must pick the node where the file is stored.
- Use the ManagedAppService.addLinkProperty command to update the association between a community and a remote application by adding the NEEDS-TO-BE-SYNCED key property and setting it to true.
When fetching a link for a community application, to fetch a Lotus Quickr Portal Wiki, use QuickrPortalWiki, and to fetch a Lotus Quickr Portal team place, use QuickrPortalTeamspace.
For example:
wsadmin>bycommname=CommunitiesService.fetchCommByName("<community name>") wsadmin>link=ManagedAppService.fetchLinkByCommApp(bycommname,"QuickrPortalWiki") wsadmin>link2=link.get(0) wsadmin>ManagedAppService.addLinkProperty(link2,"NEEDS-TO-BE-SYNCED","true")
Results
The Lotus Quickr Delayed Synchronizer performs a full membership synchronization between the Lotus Quickr place and the associated community when the synchronization task is next run.
Uninstall the Lotus Quickr connector
Use the uninstaller to remove the IBM Connections Connector for Lotus Quickr from your system. To uninstall the Lotus Quickr connector:
- Run the uninstaller by doing one of the following:
Alternatively, double-click the launcher.exe file in the eclipse directory.
- AIX, Linux, or Linux on System z:
- Open a command prompt and change to this directory:
InstallationManager_directory/eclipse/
- Enter the following command:
chmod +x launcher
- Then enter the following command:
./launcher
- Microsoft
Windows:
- Open a command prompt and change to this directory:
InstallationManager_directory/eclipse/
- Enter the following command:
launcher.exe
- Select the language to use for the uninstallation process and click Next.
- Review the summary panel to verify that the applications to remove are present. If you want to make any changes, click Back to edit the values that you input. Click Next to begin the uninstallation process.
- Review the results of the uninstallation and click Finish to close the wizard.
Uninstall the Lotus Quickr connector in silent mode
Uninstall the IBM Lotus Quickr connector for Communities in silent mode when you want to use a response file to automate the procedure for removing the connector from your system.
Before starting the following procedure, you need to install the Installation Manager. For more information, see Installing the Lotus Quickr connector in silent mode.
To uninstall the Lotus Quickr connector in silent mode, complete the following steps.
- Open a command prompt and enter one of the following commands.
- AIX, Linux, or Linux on System z:
generate_other_responsefile.sh
- Microsoft
Windows:
generate_other_responsefile.bat
- Click Uninstall in the first panel and complete the uninstall process. After you do this, a response file named LC.rsp is generated in the following directory:
\LC_Connectors_Install_IM\ConnectorsQuickr
- Change to one of the following directories.
- AIX, Linux, or Linux on System z:
LC_Connector_Install_IM\IM\linux
- Microsoft
Windows:
LC_Connector_Install_IM\IM\windows
- Start the silent uninstall.
- Change to one of the following directories.
- AIX, Linux, or Linux on System z:
.\InstallationMananger\eclipse
- Microsoft
Windows:
C:\Program Files\IBM\Installation Manager\eclipse
- Enter one of the following commands to uninstall the connector.
- AIX, Linux, or Linux on System z:
./IBMIM --launcher.ini silent-install.ini -input <LC_HOME>/silentResponseFile/LC_uninstall.rsp -log ./uninstall.log
- Microsoft
Windows:
.\IBMIMc.exe --launcher.ini silent-install.ini -input <LC_HOME>\silentResponseFile\LC_uninstall.rsp -log .\uninstall.log
Upgrading the Lotus Quickr connector
To upgrade to a newer version of the IBM Connections Connector for Lotus Quickr, uninstall the existing connector before installing the new connector. When you upgrade to a new version of the Lotus Quickr connector, the existing connector data is preserved. However, if you customized the configuration files for the previous version of the connector, you need to make those configuration changes again after installing the new version of the connector.
- Uninstall the existing Lotus Quickr connector. For more information, see Uninstalling the Lotus Quickr connector.
- Install the new version of the Lotus Quickr connector. For more information, see Installing the IBM Connections Connector for Lotus Quickr.
What to do next
Repeat any customization changes that you made to the previous configuration if required.
Optional: defining a list of supported Lotus Quickr servers for Communities
You can provide a list of the supported IBM Lotus Quickr servers to the proxy server to ensure that it honors any requests made for access to one of the supported Lotus Quickr servers. This is an optional task.
You must have Lotus Quickr deployed in your enterprise before you can perform this procedure. You must also have administrative access to the IBM WebSphere Application Server where the Communities application is installed.
- Go to the WebSphere Application Server Integrated Solutions Console for the server hosting the Deployment Manager.
- Expand Resources > Resource Environment, and then click Resource Environment Providers.
- Click QuickrWhitelistProvider from the list, and then click Custom properties.
- Create one custom property for each Lotus Quickr server to enable users to access. To create a custom property, enter values in the following fields:
If you upgraded a stand-alone deployment which was already configured to integrate with Lotus Quickr to a network deployment, you must recreate these custom properties for the provider on the cluster's cell. The custom properties must be redefined because they are lost when you federate the node into a cluster.
- name
- Create a property name that begins with the term allow. For example:
allowQuickrPrimary.example.com
- value
- Set the fully qualified domain name of the Lotus Quickr server or its IP address. Do not specify the protocol, nor any port numbers.
To enable users to access several servers within a specific domain, specify the parent domain in this field. You must start the string with a period (.). For example, if you were to specify .example.com, the proxy would allow the file to be published to all the servers that are available from subdomains of example.com.
The provider does not convert IP addresses to domain names nor the other way around. If the server is requested using both identifiers, create two properties: one property that specifies the domain name in the value field and one that specifies the IP address in the value field.
- Repeat the previous step for every Lotus Quickr server to add to the list of supported servers.
Use plug-ins from IBM Connections in other products
Get help using the plug-ins that bring the capabilities of IBM Connections to other products.
Use the IBM Connections Plug-in for IBM Sametime
Use the IBM Connections Plug-in for IBM Sametime to access Connections content from Sametime.
What is the IBM Connections Plug-in for IBM Sametime?
Use the IBM Connections Plug-in for IBM Sametime to bring powerful capabilities of the IBM Connections to the Sametime window.
When you install the IBM Connections Plug-in for IBM Sametime, you can enable any of the following features:
- Activities Sametime Feature. Use this feature to save chats to activities, open activities from your Sametime window, or find activities that you share with a contact. This feature provides a bridge between the real-time communication of Sametime and the project management power of Activities, a component of IBM Connections.
- Profiles Business Card Sametime Feature . Use this feature to find out more about the people in your Sametime Contact list. When you hover over a name in the contact list, the Profiles business card associated with that person is displayed. The Profiles business card provides the person's job title, location, and telephone number. It also provides links to other IBM Connections features.
- Communities Sametime Feature - Use this feature to save chats to a community. If you have also installed Sametime Advanced you can save Broadcast chats into their corresponding community.
Set the IBM Connections servers in Sametime
Before you can interact with IBM Connections from the Sametime window, you must specify the IBM Connections servers.
To establish a connection with the IBM Connections servers, you must know the Web addresses of the servers, and the user name and password you use to access IBM Connections. If you do not have this information, contact your administrator. Follow these steps to enter or edit preference settings for connecting to the servers.
- From the chat window, choose File > Preferences.
- Click Connections.
- Enter the user name and password you use to access IBM Connections. If you do not know them, see your site administrator.
- Enter URLs for the servers you plan to use.
If you do not know the server URLs, contact your site administrator. Use the following syntax to specify the server Web address:
https://<server.domain>/<feature>For example:https://enterprise.acme.com/activities
- Set the authentication type and URL you are using from the following choices:
- Java Form
You do not need to specify an authentication URL for this option.
- Tivoli Access Manager
- Site Minder Form
- Click Apply, and then click OK.
What to do next
For more information about integrating Sametime with the Notes servers, see the article on Notes Integration in the IBM Connections product wiki. For information on customizing settings for the plug-in, see the article on Use Notes INI settings to configure Connections integration in the IBM Connections product wiki.
Activities Sametime Feature
Use the Activities Sametime Feature to save chats to activities and open related activities from your Sametime window.
An activity is a space for storing and viewing a collection of files and documents relating to a particular topic. For example, an activity that organizes work on a project might include links to specifications, response documents that team members create to discuss issues, To Dos assigned to team members and a group calendar.
Add a chat to an existing activity
Save a chat as a text file that gets stored in an existing activity.
Your Sametime client must be enabled to save chats or the Add Chat Transcript to Activities icon will not be displayed in the action bar of the chat window. If you do not see the icon, contact your administrator. If you are engaged in a chat that you would like to preserve and make available to others, you can save it to an activity.
- From the chat window, click the Add Chat Transcript to Activities icon.
- Optional: Edit the title of the chat entry by editing the Name field. The entry is named "Chat: " followed by the names of the chat participants by default.
- Type tags for the chat file in the Tags field. Type a comma between tags. Tags are keywords that you use to classify information to make it easier to search. Tags must be entered as single words. For example: human_resources, payroll, event-planning.
- Optional: Select the Private check box if you do not want the chat to be viewable by other activity members.
- Choose one of the activities listed, and then click OK. The message, "Chat added to activity: <activity_name>," is displayed. If you and your chat partner are both members of the chosen activity and you did not mark the chat private, the message is displayed in the chat window for both participants to see. You and your chat partner can click the activity name to open the activity. If a person participating in the chat is not a member of the chosen activity or you marked the chat private, the message is displayed in the message bar of your chat window. It is not displayed in the message bar of the chat windows of the other participants.
What to do next
You can open the activity from your Activities dashboard to view the chat file.
Add a chat to a new activity
Save a chat as a text file that gets stored in a new activity.
Your Sametime client must be enabled to save chats or the Add Chat Transcript to Activities icon will not be displayed in the action bar of the chat window. If you do not see the icon, contact your administrator. If you are engaged in a chat that you would like to preserve and make available to others, you can save it to a new activity.
- From the chat window, click the Add Chat Transcript to Activities icon.
- Optional: Edit the title of the chat entry by editing the Name field. The entry is named "Chat: " followed by the names of the chat participants by default.
- Type tags for the chat file in the Tags field. Type a comma between tags. Tags are keywords that you use to classify information to make it easier to search. Tags must be entered as single words. For example: human_resources, payroll, event-planning.
- Optional: Select the Private check box if you do not want the chat to be viewable by other activity members.
- Click New to create a new activity.
- Type a name for the activity in the Activity field.
- In the Authors field, type a comma after your chat partner's name, and then add the names of people you want to add as authors to the activity. You can also remove your chat partner's name if you do not want the person to be a member of the new activity. If you want to add readers, click Add Readers, and then type the names into the Readers field. If you want to add owners, click Add Owners, and then type the names into the Owners field.
- Authors can add content to an activity.
- Owners can add and delete content and manage the activity.
- Readers can read activity content but cannot post new content.
- Optional: Type a description of the purpose of the activity in the Activity goal field.
- Optional: Enter tags that classify the activity.
- Optional: Click Add Due Date to specify a date by which this activity should be completed.
- Click OK. The message, "Chat added to activity: <activity_name>," is displayed. If you did not remove your chat partner's name from the Authors field when creating the new activity, nor mark the chat private, the message is displayed in the chat window for both participants to see. You and your partner can click the activity name to open the activity. If you did remove your chat partner's name from the Authors field of the new activity or marked the chat private, the message is displayed in the message bar of your chat window. It is not displayed in the message bar of the window of other chat participants.
What to do next
You can open the activity from your Activity dashboard to view the chat file.
Find related activities
You can find activities you share in common with a person in your Contacts list or a current chat partner. To display a list of activities to which you and a chat partner or you and a person in the Contacts list both belong as members, you can search for a related activity.
- Do one of the following:
- If you are chatting with someone and want to open an activity to which you both belong, from the chat window click the Find Related Activities icon.
A list displays the first five shared activities and provides the total number of activities that you have in common.
- If you want to find out if you and a person in your Contacts list are both members of any of the same activities, from the Contacts list, right-click the person's name, and then select Find Related Activities.
A list displays the first five shared activities.
- Do one of the following:
- Click an activity name to open the activity in a Web browser.
- Click Show in Browser to open Activities in a Web browser and display the full list of related activities.
Profiles Business Card Sametime Feature
Use this feature to learn more about the people in your Sametime Contact list.
Profiles is a directory of the people in your organization and information about them required to form and encourage effective networks. In addition to basic information captured in a business card format, Profiles catalogs skills such as technical expertise, past work experience, familiarity with foreign languages, and areas of interest.
Learning more about your contacts
Use the Profiles business card to find out more about the people in your Sametime Contacts list. The Profiles business card provides the basic information you would expect to find on a business card. It also includes links to any of the IBM Connections features that are implemented for your organization. One of the links is a Profiles link, which you can click to open the person's profile in IBM Connections. The profile provides more information, including details about current and past work projects and organizational chart information.
To view a person's business card:
- Open the Sametime Contacts list.
- Hover over a person's name in the list to see their business card. If business card does not display or if the IBM Connections links do not display on the business card, make sure you have properly specified the Connections server in the IBM Connections Preferences page and that the person has created a profile in IBM Connections.
Add a chat to a community
Save a chat as a text file that gets posted to an existing community. This feature is only available for the stand-alone Sametime client; it is not available in the Sametime client embedded in Notes.
Your Sametime client must be enabled to save chats or the Add Chat to Community Forum icon will not be displayed in the action bar of the chat window. If you do not see the icon, contact your administrator. If you are engaged in a chat that you would like to preserve and make available to others, you can save it to a community.
- From the chat window, click the Add Chat to Community Forum icon.
- Optional: Edit the title of the chat entry by editing the Name field. The entry is named "Chat: " followed by the names of the chat participants by default.
- Choose one of the communities listed, and then click OK.
What to do next
You can open the community to view the chat file.
Add a broadcast chat to a community
Broadcast a chat in a corresponding community.
Your Sametime client must be at least Sametime Advanced 8.0 and be enabled to use Broadcast tools or you cannot use this feature. If you are not sure whether you have this capability, check with your administrator. You can broadcast a chat to a corresponding community to post a message for the community members.
- In your Sametime Contacts list, expand the Broadcast Communities section.
- Click the name of a broadcast community to open a broadcast chat window.
- Enter your message.
- Click the Add chat to community forum icon to past the chat to the community discussion forum. You must be a member of the community to post a broadcast chat. if you are not, you will see a message box with that information and given the opportunity to save the chat to a different community.
What to do next
You can open the community to view the chat file.
Use the IBM Connections Portlets for WebSphere Portal
Use the IBM Connections 3.0.1.1 Portlets for WebSphere Portal to interact with Connections from a Portal application.
This section describes the 3.0.1.1 version of the IBM Connections Portlets for WebSphere Portal. The portlets do not currently support the IBM Connections 4 servers. This section will be updated when support for Connections 4 is available.
Personalizing a portlet
Specify or edit the login name and password you use to access IBM Connections.
Personalize options are available when basic authentication is in use. The personalize options are not available if the deployment is configured to use single-sign on.
If you do not know the user name and password for accessing an IBM Connections service, consult with your IBM Connections administrator. To personalize a portlet, do the following:
- Select Personalize from the portlet menu.
- Enter a User Name and Password or update this information if it has changed.
- Click OK to save your changes or Cancel to return to the view without saving your changes.
The Activities portlet
The IBM Connections Activities portlet lets you view and create activities, and work with to do items.
Use the Activities portlet
The Activities portlet lets you interact with the IBM Connections Activities features so you can use activities to organize your collaborative work without leaving your IBM WebSphere Portal environment.
The Activities Detail portlet has two views, My Activities and To Dos List.
The My Activities view displays activities that you created or that you belong to. From the My Activities view you can:
- Click Start an Activity to create a new activity. Assign it a title and optionally enter a description, goal, or tags. Add members for your activity and save it to add it to your list.
- Click Completed to view completed activities.
- Click High priority to view activities that are flagged as needing your immediate attention.
- Click Medium priority to view activities that are not as pressing.
- Sort the view by clicking the column header for Last Updated or by Due Date.
Click an activity name to open it. From the activity you can do the following:
- Click Add to do item to create a to do. You can assign it to yourself or to another user. You can also optionally assign a priority, due date, tags, and a description.
- Click Add Entry to add an entry to the activity.
- Click Add Section to create a section to keep your activity organized.
- Respond to a to do item by marking it complete, or click More to add a comment, edit, or delete the to do.
- If you are the activity owner, click Members to add members to the activity. You can assign a member owner, author, or reader access.
- View emails and chat transcripts saved to the activity. Comment on this content or create associated to do items.
Edit the shared settings for the Activities portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet:
Configure the Activities portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Display icon to open IBM Connections in a browser window Display an icon that opens IBM Connections in a browser so users can fully access the application. Display link to open IBM Connections in a browser window Activity title links to open the recent updates page for that activity in a browser window. Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Blogs portlet
The IBM Connections Blogs detail portlet gives you access to your blogs from within IBM WebSphere Portal.
Purpose
Use the Blogs portlets to interact with the IBM Connections Blogs feature so you can read or contribute to blogs without leaving the IBM WebSphere Portal environment. You can also view and contribute to Ideation Blogs you can access. Ideation blogs, unlike standard blogs, are used to generate and promote ideas in a community.
- If the Blogs portlet is deployed on a community page, Ideation blogs will not display in the portlet.
- If the Blogs portlet is deployed on a stand-alone page, a logged in user can click on a community blog to see the entries but will be unable to click on entries created by other users. To enter comments, vote for or recommend an idea, open Blogs in the web application.
- Pin options in the Blogs Edit Shared Sets mode are not available from the My Blogs view of the portlet. You can only pin the Blogs portlet from the public views (Latest Entries and All Blogs.)
The Blogs Detail portlet has three views, Latest Entries, All Blogs, and My Blogs.
The Latest Entries view displays recent entries and comments posted to blogs. From this view, you can:
- Click an entry to read it. If comments are enabled you can add a comment.
- Click an idea to read it. You can vote on an idea. If you are the blog owner you can also graduate ideas that have community support.
- Click the name of a contributor to view the associated business card.
- Sort the view by Date, Title, Most Recommendations, Most Comments, or Most Visits.
The All Blogs view lists all blogs for your organization. From this view, you can:
- Click the name of a blog to open it and view the entries.
- Click the name of an Ideation Blog to open it so that you can view the ideas and view voting activity.
- Click More to view details for the blog, such as a description or tags.
- Click the name of a blog owner to view the associated business card.
The My Blogs view lists blogs for which you are an owner or member. From this view, you can:
- Click the name of a blog to open it. You can view the entries and comments or create an entry.
- Click the name of an Ideation Blog to open it so that you can view the ideas and view voting activity.
- Click Sets to edit the basics for a blog, including the title, description, and tags. You can also add blog owners, authors, or draft users.
- Click Start a Blog to start a new blog.
You cannot create an Ideation Blog from the Blogs portlet because it must be created within a community.
Edit the shared settings for the Blogs portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information about access levels, see the WebSphere Portal Information Center. Sets you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet:
Configure the Blogs portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Profile photos for Latest Entries Displays author pictures next to blog entries. Display icon to open IBM Connections in a browser window Display an icon that opens IBM Connections in a browser so users can fully access the application. Display link to open IBM Connections in a browser window Opens IBM Connections in a browser window so that users can interact with the full application. Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Blogs Summary portlet
The IBM Connections Blogs Summary portlet gives you a targeted view of your blogs activity from within IBM WebSphere Portal.
Purpose
Use the Blogs Summary portlet to display a targeted view of blogs, such as most popular blogs.
The Blogs Summary portlet has two views:
- Recommends displays the most recommended blogs.
- Date displays blogs with the newest first.
Edit the shared settings for the Blogs Summary portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet:
Configure the Blogs Summary portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Homepage Handle Enter the Homepage Handle for your Blogs deployment. Display link to open IBM Connections in a browser window Opens IBM Connections in a browser window so that users can interact with the full application.
The Bookmarks portlet
The IBM Connections Bookmarks portlet gives you access to your bookmarks from within IBM WebSphere Portal.
Use the Bookmarks portlet
The Bookmarks portlet lets you interact with the IBM Connections Bookmarks feature so you can access your bookmarks without leaving the IBM Websphere Portal environment. The portlet has two views, All Bookmarks and My Bookmarks.
The All Bookmarks view displays bookmarks you created as well as bookmarks shared with you by others in your organization. The My Bookmarks view only displays the bookmarks you created. You can click the More option for a bookmark to edit or delete it.
From the All Bookmarks or the My Bookmarks view you can:
- Click a bookmark to visit the Web page.
- Click More to view details about the bookmark.
- Click the name of a bookmark owner to view the associated business card.
- Sort the view by clicking the column header for Date or by Popularity.
The My Blogs view lists blogs for which you are an owner or member. From this view you can:
- Click the name of a blog to open it. You can view the entries and comments or create a new entry.
- Click the name of an Ideation Blog to open it so that you can view the ideas and view voting activity.
- Click Sets to edit the basics for a blog, including the title, description, and tags. You can also add blog owners, authors or draft users.
- Click Start a Blog to start a new blog.
You cannot create an Ideation Blog from the Blogs portlet because it must be created within a community.
Edit the shared settings for the Bookmarks portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. You can choose either My Bookmarks, All Bookmarks, or both.
Configure the Bookmarks portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Bookmarks Summary portlet
The IBM Connections Bookmarks Summary portlet gives you a targeted view of your bookmarks from within IBM WebSphere Portal.
Use the Bookmarks Summary portlet
Use the Bookmarks Summary portlet to integrate a specific view of Bookmarks into a Portal application. The portlet has three views:
- Public Bookmarks lists all public bookmarks. This is the only view that allows you to filter the bookmarks by pinning a tag.
- Most Popular Bookmarks lists the web pages most frequently bookmarked.
- Most Visited Bookmarks lists the bookmarks that receive the most clicks.
Edit the shared settings for the Bookmarks portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Sets you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet.
The Profiles Portlet
The IBM Connections Profiles portlet gives you access to your profile and network information from within IBM WebSphere Portal.
Use the Profiles portlet
The Profiles portlet lets you interact with the IBM Connections Profiles feature so you can access your profile and network information without leaving the IBM Websphere Portal environment. The portlet has two views, Status Updates and My Profile.
From the Status Updates view, you can:
From the My Profile view, you can:
- Post your status
- View your status history
- View the status for other people in your network
- Comment on other people's status
- Delete comments or status you posted
- Search Profiles by name, tag, or keyword
- View and update your profile information (This feature takes you to IBM Connections Profiles)
- View report-to chain for yourself or your colleagues
- View network information for yourself or your colleagues
- Search Profiles by name, tag, or keyword
- Invite people to join your network
- View, accept or decline invitations to join other networks
- Send e-mail to colleagues or display their business card
Edit the shared settings for the Profiles portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. Choose which views to display in the portlet. You can choose Status Updates or My Profile.
Configure the Profiles portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Enable this will provide link to the External Connections UI for editing profile Displays an Edit Profile link so that users can update their profiles in the IBM Connections web application. Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Profiles Summary portlet
Use the IBM Connections Profiles summary portlet to add a targeted view of profile and network information to an IBM WebSphere Portal application.
Use the Profiles portlet
Use the IBM Connections Profiles summary portlet to add a targeted view of profile and network information to an IBMWebSphere Portal application.The portlet has two views, Status Updates and My Profile.
From the Status Updates view, you can:
From the My Profile view, you can:
- Post your status
- View your status history
- View the status for other people in your network
- Comment on other people's status
- Delete comments or status you posted
- Search Profiles by name, tag, or keyword
- View and update your profile information (This feature takes you to IBM Connections Profiles)
- View report-to chain for yourself or your colleagues
- View network information for yourself or your colleagues
- Search Profiles by name, tag, or keyword
- Invite people to join your network
- View, accept or decline invitations to join other networks
- Send e-mail to colleagues or display their business card
Edit the shared settings for the Profiles portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. Choose which views to display in the portlet. You can choose Status Updates or My Profile.
Configure the Profiles portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Enable this will provide link to the External Connections UI for editing profile Displays an Edit Profile link so that users can update their profiles in the IBM Connections web application. Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Tags portlet
The IBM Connections Tags portlet gives you access to your profile and network information from within IBM WebSphere Portal.
Use the Tags portlet
The Tags portlet lets you access IBM Connections content by user-defined tags, or keywords. You can see tags for all IBM Connections content or associate tags with a narrower content source, such as a blog or community.
Edit the shared settings for the Tags portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Choose Edit Shared Sets from the portlet menu and choose the Connections applications for which you want to display tags.
Configure the Tags portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description
- Include tags for public content only
- Include tags for public content and private content
Specify whether to display tags for public content only or for public as well as your private content.
The Wikis portlet
The IBM Connections Wikis portlet brings the collaborative power of an IBM Connections wiki to IBM WebSphere Portal.
Use the Wikis portlet
The Wikis portlet lets you interact with the IBM Connections Wikis feature so you can access content without leaving the IBM Websphere Portal environment.
Edit the shared settings for the Wikis portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. You can choose to display:
- All wikis
- A list of all wiki pages for this community (default)
- The currently selected wiki page
- The most recent wiki page for this community
Configure the Wikis portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Display icon to open IBM Connections in a browser window Display an icon so users can open Connections in a browser window to access the full application. Display link to open IBM Connections in a browser window Allow links from the wiki to open Connections in a browser window. Display page controls only in bottom bar Hides the page controls at the top of the window. Clear the checkbox to display paging controls in the header and footer of the page.
The Community Overview portlet
A Community Overview portlet lets you display information from an IBM Connections community in an IBM WebSphere Portal application.
Use the Community Overview portlet
The Community Overview portlet lets you display any of the following information from an IBM Community:
- Community icon
- Community name
- Community owners
- Tags
- Community description
- Community Type
A portlet page containing a community overview portlet has membership that is scoped to the community membership. If you leave the community, you will no longer have access to the portal page and will be taken to the home page for the portal application.
Edit the shared settings for the Community Overview portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which information from the community you want to display in the portlet.
The Forums portlet
The IBM Connections Forums portlet brings the collaborative power of an IBM Connections forum to IBM WebSphere Portal.
Use the Forums portlet
The Forum portlet lets you interact with the IBM Connections Forums feature so you can access content without leaving the IBM Websphere Portal environment. You can read topics, create new topics, or comment on topics.
Edit the shared settings for the Forums portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. You can choose to display:
- All forum topics for this community (default)
- The most recent forum topic for this community
- The currently selected forum topic for this community
Configure the Forums portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Display icon to open IBM Connections in a browser window Display an icon so users can open Connections in a browser window to access the full application. Display page controls only in bottom bar Hides the page controls in the header of the window. Clear the checkbox to display paging controls in the header as well as the footer of the page.
The Forums Summary portlet
The IBM Connections Forums summary portlet displays a targeted view of Forums in your WebSphere Portal application.
Use the Forums summary portlet
Use the Forums Summary portlet to insert a targeted view of Forums content in a WebSphere Portal application. Choose one of the following views:
- All Topics lists all of the forums topics for the logged-in user. It does not list public forum topics.
- Open Questions lists the questions awaiting answers in the forum.
- Answered Questions lists the answered questions in the forum.
- Topics Followed by User lists the topics the logged-in users asked to follow.
The Forums Summary portlet only displays forum entries for the logged-in user and does not display public forum entries not associated with the user.
Edit the shared settings for the Forums Summary portlet
You must have at least editor access for the page and for the portlet to be able to edit shared settings for Connections features. For more information on access levels, see the WebSphere Portal Information Center. Note that settings you enter on this page can be overridden by settings on the Personalize page for a portlet. Choose Edit Shared Sets from the portlet menu and choose which view to display in the portlet. You can also choose to display topics filtered by a tag you specify, turn on or off the display of replies in the portlet, and specify the number of topics to display.
Configure the Forums portlet
You must have administrative access to the portlet to be able to configure it. Choose Configure from the portlet menu and configure these options:
Option Description Display link to open IBM Connections in a browser window Display a link so users can open Connections in a browser window to access the full application.
Use the IBM Connections Desktop Plug-ins for Microsoft Windows
Use the plug-ins to share files and information between Microsoft Windows applications and IBM Connections.
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features for Microsoft Windows Explorer:
- Upload local files to IBM Connections from Windows Explorer or from your desktop
- Share uploaded files with people, communities, or folders in IBM Connections
- Work on files locally and publish them to IBM Connections
- View people's contact details and get in touch with them
- Pin, follow, or like IBM Connections files and folders
- View or contribute comments for a file
- Add files directly to IBM Connections Communities, specific Wiki pages, and Activities
- Lock a file when you are editing it to prevent file conflicts
- View and restore files from IBM Connections Trash
- Share folders with IBM Connections Communities
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features for Microsoft Office (Word, Excel, PowerPoint):
- Features added to Word:
- Add a document to IBM Connections Files or Communities
- Attach a document to an Activity or Wiki page
- Publish a document to a Blog entry
- Add someone's profile information from IBM Connections into a document
- Add a bookmark from IBM Connections into a document
- Add a URL from a document as a bookmark in IBM Connections
- Search for content in IBM Connections
- Features added to PowerPoint:
- Add a presentation to IBM Connections Files or Communities
- Attach a presentation to an Activity or Wiki page
- Search for content in IBM Connections
- Features added to Excel:
- Add a spreadsheet to IBM Connections Files or Communities
- Attach a spreadsheet to an Activity or Wiki page
- Search for content in IBM Connections
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features for Microsoft Outlook:
- Add an email to IBM Connections Files or Communities
- Attach an email to an activity or wiki page Search for content in IBM Connections
- View social activities for email recipients and people in your network
- Invite people to your IBM Connections network
- View IBM Connections business card for email senders and recipients in Outlook 2010
Connecting to an IBM Connections site
You must provide information about IBM Connections servers before you can share files and information between Microsoft Windows and IBM Connections. After you connect to an IBM Connections site, you can interact with that site from Microsoft Office, Microsoft Outlook, and Windows Explorer.
- Do one of the following:
- Open a document in a Microsoft Office application or Microsoft Outlook.
- Click the IBM Connections tab.
- Click Connect to a site.
- Open Microsoft Windows Explorer.
- Right-click IBM Connections in the navigation pane.
- Select Connect to a site.
- In the Site URL field type the URL you use to connect to IBM Connections. For example, https://connections.server.com or https://connections.server.com:port.
- In the Display name field, type the name you want to display for this site in Microsoft Windows applications.
- Enter the user name and password you use to log into that IBM Connections site. Select Remember this password if you do not want to enter it each time you log in or restart your operating system.
- Select an authentication type if there is a reason to change it from the default. By default, the plug-in authenticates with the IBM Connections server using basic authentication. If your enterprise uses a different authentication type, you might be instructed to edit the authentication setting.
Use the IBM Connections Plug-in for Microsoft Office
Use this plug-in to share files and information between IBM Connections and Microsoft Word, Excel, and PowerPoint.
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features for Microsoft Office (Word, Excel, PowerPoint):
- Features added to Word:
- Add a document to IBM Connections Files or Communities
- Attach a document to an Activity or Wiki page
- Publish a document to a Blog entry
- Add someone's profile information from IBM Connections into a document
- Add a bookmark from IBM Connections into a document
- Add a URL from a document as a bookmark in IBM Connections
- Search for content in IBM Connections
- Features added to PowerPoint:
- Add a presentation to IBM Connections Files or Communities
- Attach a presentation to an Activity or Wiki page
- Search for content in IBM Connections
- Features added to Excel:
- Add a spreadsheet to IBM Connections Files or Communities
- Attach a spreadsheet to an Activity or Wiki page
- Search for content in IBM Connections
Add documents to Files
Add Word, Excel, and PowerPoint documents to the IBM Connections Files application.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site. This topic provides one way to add Microsoft Office documents to IBM Connections. You can also add documents from the File tab in Office applications by clicking Save & Send and then Send to IBM Connections.
- Open the document.
- Click the IBM Connections tab.
- Click Files.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Optional: Type tags which you can use to find the document in Connections.
- Choose to share the file with no one, or with specific people or communities, or with everyone.
- Optional: Choose whether to allow other people who can see the document to share it with other people. This option is not available if you choose to share with everyone.
- Click Upload.
Add documents to Communities
Add Word, Excel, and PowerPoint documents to IBM Connections communities.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site. This topic provides one way to add Microsoft Office documents to IBM Connections. In Microsoft Office 2010, you can also add documents from the File tab in Office applications by clicking Save & Send and then Send to IBM Connections.
- Open the document.
- Click the IBM Connections tab.
- Click Communities.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Set the community name or select one using the dropdown.
- Choose whether to upload the document directly to the community, or upload it to My Files in the Files application and share it with the community from there.
- Click OK.
Add documents to Activities
Add Word, Excel, and PowerPoint documents to the IBM Connections activities.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site. This topic provides one way to add Microsoft Office documents to IBM Connections. You can also add documents from the File tab in Office applications by clicking Save & Send and then Send to IBM Connections.
- Open the document.
- Click the IBM Connections tab.
- Click Activities.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Do one of the following:
- Click Browse to find an existing activity, then do one of the following:
- Select My activities and choose from the list of activities you own or are a member of. The list includes community activities.
- Select Search, then type characters to use to search for activities. The results include community activities.
- Click OK.
- Click Create new activity, then:
- Type a name, tags and a goal for the activity.
- Optionally add a due date.
- Add people or communities as members with specified access.
- Click Create.
- If you are adding the document as a To Do item, by default, the task is assigned to Anyone (shared), meaning any member of the activity can perform the task, and then check it off after it has been completed. To assign the to-do item to a specific member, click Choose a person, and then perform one of the following actions:
- Standard activity:
- To assign the to-do entry to a specific person, select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
- If the activity has been shared with a community, then you can assign the to-do item to a community member by selecting Community: community_name where community_name is the name of the community, and then selecting the persons name from the list.
- If a person is a member of a group that belongs to the activity, then add the person as an individual activity member before you can add them.
- Community activity to which all community members were added:
- Select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
- Community activity to which only a subset of community members were added:
- Select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
- To assign the to-do entry to a community owner, select community_name (community owners) where community_name is the name of the community, and then select the owners name from the list.
- Optional: Add a due date.
- Optional: Change the title, and add tags, a description, and new section. Typeahead for the Tags and Section fields returns matches as you type if you want to keep tags and section names consistent.
- Optional: Mark the to do as private if you do not want other members to see it.
- Click Upload.
Add documents to Wikis
Add Word, Excel, and PowerPoint documents to the IBM Connections wikis. The document is added to a wiki page as an attachment.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site. This topic provides one way to add Microsoft Office documents to IBM Connections. You can also add documents from the File tab in Office applications by clicking Save & Send and then Send to IBM Connections.
- Open the document.
- Click the IBM Connections tab.
- Click Wikis.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Do one of the following:
- Select My wikis, and then expand the wiki you want and select a page.
- Select Search, and type characters to use to search for a wiki.
- Select an existing wiki page attachment.
- Optional: Change the file name.
- Click Upload. If you selected an attachment, it will be replaced by the uploaded document.
Add Word documents to Blogs
Add Word documents to IBM Connections blogs. The document is added as a new blog post.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
Word documents must use a blog template before you can upload them as an IBM Connections blog post. Use the blog post template when you create a new document by selecting it from the list of templates. If you want to convert an existing document to a blog post, create a new document with the blog post template, and then copy the content into that new document.
Follow these steps to post a Word document as a blog post in IBM Connections.
- Open the document in Word.
- Click the IBM Connections tab.
- Click Blogs.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Click Browse.
- Select a blog and click OK.
- Optional: Edit the entry title and add tags.
- Optional: Select Post as draft to post the document as a draft only.
- Click Upload.
The conversion process may remove or change some of the formatting present in the Word document.
What to do next
You can also convert an existing document to the blog template within Word. Click File > Save & Send > Publish as Blog Post. This Microsoft feature reopens the document using the Microsoft blog template.
Add IBM Connections profiles to Word documents
Add people's IBM Connections profiles to Word documents.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open the document.
- Click the IBM Connections tab.
- Click in the document where you want to place the profile information, and then click Profile Information.
- If you connect to more than one IBM Connections site, select a site from which to insert the profile information.
- Do one of the following:
- Start typing a name and then select the best match.
- Click the arrow icon and select from people you've recently interacted with, people you're following, or people in your network.
- Select the name of a person and view their business card using by clicking the button to the right of the edit field.
- Click OK.
Add IBM Connections bookmarks to Word documents
Add IBM Connections bookmarks to Word documents.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open the document.
- Click the IBM Connections tab.
- Click in the document where you want to place the bookmark information, and then click Bookmarks.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Show bookmarks from the My Bookmarks, My Watchlist, or Popular Bookmarks lists in IBM Connections.
- Start typing the name of a bookmark to narrow the list.
- Click Insert.
Add bookmarks to IBM Connections from Word documents
Add bookmarks to IBM Connections from URLs in Word documents.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open the document.
- Click the IBM Connections tab.
- If there is a URL in the document you want to create the bookmark for, highlight it. If you don.t highlight a URL you will have to type it in when you create a bookmark.
- Click Bookmark URL in, and then select one of the following:
Option Description Bookmarks To add a bookmark in Bookmarks, select an IBM Connections site, then fill out the fields for the bookmark. Select Make Bookmark Public to create a bookmark that everyone can access. Leave it deselected to create a bookmark that only you can access. A Community To add a bookmark to a community, select an IBM Connections site. Then start typing a community name and select or search on it. Or use the arrow icon to select from lists. Fill out the fields for the bookmark. Select Add to important bookmarks to add the bookmark to the important bookmarks list in the community. An Activity Do one of the following:
- Click Browse to find an existing activity. Then either select My activities and choose from the list of activities you own or are a member of. The list includes community activities. Or select Search, then type characters to use to search for activities. The results include community activities. Then click OK.
- Click Create new activity, then:
- Type a name, tags and a goal for the activity.
- Optionally add a due date.
- Add people or communities as members with specified access.
- Click Create.
Search from Office for IBM Connections content
Search for IBM Connections content without leaving your Microsoft Office applications. Find content in IBM Connections using the Search feature.
- Enter a search term in the search bar on the Connections ribbon. The default is to search all of Connections and return matching results. If you connect to more than one site, you can select a different server to search.
- To refine a search, click Advanced Search. The Advanced Search opens in a browser window. Use the Advanced Search filters to refine your search.
Use the IBM Connections Plug-in for Microsoft Outlook
Use this plug-in to share files and information between IBM Connections and Microsoft Outlook.
The IBM Connections Desktop Plug-ins for Microsoft Windows provides the following features for Microsoft Outlook:
- Add an email to IBM Connections Files or Communities
- Attach an email to an activity or wiki page
- Search for content in IBM Connections
- View social activities for email recipients and people in your network
- Invite people to your IBM Connections network
- View IBM Connections business card for email senders and recipients in Outlook 2010
Viewing IBM Connections user business cards
From Microsoft Outlook email, you can view people's business cards from IBM Connections Profiles. Business cards list people's contact information as well as links to content and IBM Connections.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open an Outlook message.
- Right-click an email address and select IBM Connections > View Business Card. If you are connected to multiple sites, select the site to retrieve the card from. You can also right-click an unopened email and click View Business Card.
Add Outlook emails to Files
Add Microsoft Outlook emails to the IBM Connections Files application.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open Microsoft Outlook.
- Select the email from a view, such as Inbox.
- Click the IBM Connections tab.
- Click Files.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Optional: Type tags which you can use to find the document in Connections.
- Choose to share the file with no one, or with specific people or communities, or with everyone.
- Optional: Choose whether to allow other people who can see the document to share it with other people.
- Click Upload. This adds the complete email file, including any attachments, as one document.
Add Outlook emails to Communities
Add Microsoft Outlook emails to the IBM Connections Communities application.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open Microsoft Outlook.
- Select the email from a view, such as Inbox.
- Click the IBM Connections tab.
- Click Communities.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Set the community name or select one using the dropdown.
- Choose whether to upload the document directly to the community, or upload it to My Files in the Files application and share it with the community from there.
- Click OK. This adds the complete email file, including any attachments, as one document.
Add Outlook emails to Activities
Add Microsoft Outlook emails to the IBM Connections Activities application.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open Microsoft Outlook.
- Select the email from a view, such as Inbox.
- Click the IBM Connections tab.
- Click Activities.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Do one of the following:
- Click Browse to find an existing activity, then do one of the following:
- Select My activities and choose from the list of activities you own or are a member of. The list includes community activities.
- Select Search, then type characters to use to search for activities. The results include community activities.
- Click OK.
- Click Create new activity, then:
- Type a name, tags and a goal for the activity.
- Optionally add a due date.
- Add people or communities as members with specified access.
- Click Create.
- If you are adding the email as a To Do item, by default, the task is assigned to Anyone (shared), meaning any member of the activity can perform the task, and then check it off after it has been completed. To assign the to-do item to a specific member, click Choose a person, and then perform one of the following actions:
- Standard activity:
- To assign the to-do entry to a specific person, select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
- If the activity has been shared with a community, then you can assign the to-do item to a community member by selecting Community: community_name where community_name is the name of the community, and then selecting the persons name from the list.
- If a person is a member of a group that belongs to the activity, then add the person as an individual activity member before you can add them.
- Community activity to which all community members were added:
- Select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
If the activity has more than 500 members, you can click Next to see additional names.
The filter searches the names on the current page only. If there are multiple pages, click Next until you get to a page with names in the same alphabetic range as the name you are looking for, and then type the name into the filter box.
- Community activity to which only a subset of community members were added:
- Select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
If the activity has more than 500 members, you can click Next to see additional names.
The filter searches the names on the current page only. If there are multiple pages, click Next until you get to a page with names in the same alphabetic range as the name you are looking for, and then type the name into the filter box.
- To assign the to-do entry to a community owner, select community_name (community owners) where community_name is the name of the community, and then select the owners name from the list.
- Optional: Add a due date.
- Optional: Change the title, and add tags, a description, and new section.
- Optional: Mark the to do as private if you do not want other members to see it.
- Click Upload. This adds the complete email file, including any attachments, as one document.
Add Outlook emails to Wikis
Add Microsoft Outlook emails to the IBM Connections Wikis application.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open Microsoft Outlook.
- Select the email from a view, such as Inbox.
- Click the IBM Connections tab.
- Click Wikis.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Do one of the following:
- Select My wikis, and then expand the wiki you want and select a page.
- Select Search, and type characters to use to search for a wiki. In the results, expand the wiki you want and select a page.
- Optional: Change the file name.
- Click Upload. This adds the complete email file, including any attachments, as one document.
Add IBM Connections users to Outlook emails
When you compose a Microsoft Outlook message, you can search Profiles for a name and insert it into one of the address fields in your message.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Create a message.
- Click IBM Connections > Insert Profile Email.
- If you connect to more than one IBM Connections site, select a site to look for the person.
- Enter a name or email and then select the user. Or click the arrow icon and select from people you've recently interacted with, people you're following, or people in your network.
- Select an action:
You can also view their business card by clicking the button to the right of the name field.
- Add to TO
- Add to CC
- Add to BCC
- Message (to add the address to the body of the message)
- Check the Add to Outlook Contacts option if you want to add this user to Outlook contacts.
Results
The email address is inserted in the field that you selected.
Search from Outlook for IBM Connections content
Search for IBM Connections content without leaving your Microsoft Outlook client. Find content in IBM Connections using the Search feature.
- Enter a search term in the search bar on the Connections ribbon. The default is to search all of Connections and return matching results. If you connect to more than one site, you can select a different server to search.
- To refine a search, click Advanced Search. The Advanced Search opens in a browser window. Use the Advanced Search filters to refine your search.
Use IBM Connections with the Outlook Social Connector
Use the Microsoft Outlook Social Connector to stay in contact with your IBM Connections network.
Connect with your network
Use the Outlook Social Connector with IBM Connections, you can do the following:
- Add people to your network
- View your network from your Outlook client
- View all interaction you share with a colleague in your network, including email, attachments, meetings, and feeds
This plug-in requires Outlook Social Connector version 1.1 or higher. If you have not already done so, you must upgrade the default version of OSC for your Microsoft Office application, or install it for the first time. For information on Outlook Social Connector and instructions on how to download the correct software, see this OSC article on the Microsoft web site.
The IBM Connections OSC provider
One of the different features of the IBM Connections OSC provider and other OSC providers is that it supports multiple servers where most providers connect to only one server. You can connect to up to four servers, which is helpful if your organization maintains Connections servers for internal and external use.
Once the IBM Connections Desktop Plug-ins are configured to connect to at least one Connections server you can enable those servers in Account Sets for Microsoft Outlook so that you can integrate contacts from those servers in your social networks available from your Outlook client.
Enable the OSC provider
After configuring Microsoft Office to connect to an IBM Connections server, you can then enable the Outlook Social Connector to bring network contacts into Microsoft Outlook. Once the IBM Connections Desktop Plug-ins are configured to connect to at least one Connections server, launch the Preferences for the Connections plug-ins to ensure that server will be available for the OSC configuration in Microsoft Outlook.
- Click Preferences on the IBM Connections ribbon and click Outlook Social Connector. This section lists the servers that have been configured for the IBM Connections Desktop Plug-ins.
- Check up to four the servers that you would like to have available for the OSC.
- Open Microsoft Outlook and view Account Sets. One way to do that is to click the View tab and click People Pane > Account Sets in Microsoft Outlook 2010.
- The Account Set dialog contains all of the OSC providers installed for the system. The OSC Providers that are already checked have been previously configured. Check up to four providers to configure and click Connect to begin receiving the social information for those networks.
If Microsoft Outlook was already running when you selected servers for OSC from the Preferences panel, you will need to restart Microsoft Outlook to connect to the changes.
Add IBM Connections to Outlook as a social network
Add IBM Connections to Microsoft Outlook as a social network.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open Outlook.
- Choose one of the following: .
- Office 2007: Tools > Social Network Account Set .
- Office 2010: View > People Pane > Account Sets.
- Select an IBM Connections site.
- Click Connect.
- Click Finish.
Results
You can now view information about contacts in your network in the People Pane. You can also open the IBM Connections folder in your Contacts list to view and manage your network.
Inviting people to join your IBM Connections network from Outlook
Invite people to your IBM Connections network from your Outlook client. As you are working in Outlook, you may interact with people you would like to include in your IBM Connections network.
- Invite people to your network in the following ways:
Option Description From the business card If you view the business card of a contact who is a colleague in your IBM Connections deployment, click the Invite to Network button to send them a request to join your network. From an Outlook view Right-click the sender's name and choose IBM Connections > Invite to My Network, and then select a site. A request to join your network is sent to the person. From a profile photo, or from a name in To, Cc, or Bcc fields of a mail message Right-click the photo or name and choose IBM Connections > Invite to My Network, and then select a site. A request to join your network is sent to the person.. If a person is not a Connections member, a notification will inform you that you cannot add or remove them from your network.
- Add an optional message with your invitation.
- Click Also Follow (Receive Updates) if you want updates from this person to display in your update list on your IBM Connections home page.
- If the person is already in your Connections network, Remove from My Network will display instead of an invitation. Click to remove the person from your network.
Viewing your IBM Connections network contacts in Outlook
In Microsoft Outlook, view your entire IBM Connections network, or see your interaction with one colleague. From your Microsoft Outlook client you can view your entire network or select a contact and view interaction with a colleague.
- Select Contacts to change to that view.
- Click an IBM Connections site in the My Contacts list to view your Connections network.
- Select a colleague to view interaction with that person. The Person Pane displays all of the activities you share with this colleague.
- The All Items view displays email, attachments and meetings you have in common, as well as recent status updates for this person.
Use the IBM Connections Plug-in for Microsoft Windows Explorer
Use this plug-in to upload and work with IBM Connections files in IBM Connections in Microsoft Explorer.
Features added to Windows Explorer:
- Upload local files to IBM Connections from Windows Explorer or from your desktop
- Share uploaded files with people, communities, or folders in IBM Connections
- Work on files locally and publish them to IBM Connections
- View people's contact details and get in touch with them
- Pin, follow, or like IBM Connections files and folders
- View or contribute comments for a file
- Add files directly to IBM Connections Communities, specific Wiki pages, and Activities
- Lock a file when you are editing it to prevent file conflicts
- View and restore files from IBM Connections Trash
- Share folders with IBM Connections Communities
To perform any of these tasks you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
Manage IBM Connections files from Windows Explorer
Manage your IBM Connections files from Windows Explorer.
After installing IBM Connections Desktop Plug-ins for Microsoft Windows you will see an IBM Connections folder in the navigation pane of Windows Explorer. From this folder you can view and access all of your IBM Connections files from your desktop. For any file you can:
- Double-click a file to open a local copy of the file.
- Right-click a file and select Open in browser to launch IBM Connections in a browser window so that you can access the file details and download link.
To work with plug-in features you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
Table 101. Folders for managing Connections files
Folder Description My Files A list of all the files you have published to IBM Connections Files. Pinned Files Files you have pinned for easy retrieval. Shared with Me Files that have been shared with you. Shared by Me Files you have shared with people or communities. My Folders Folders you have created. You can drag and drop files into folders. To remove a file from a folder, right-click the file name and click Remove from folder. Pinned Folders Folders you have pinned for easy retrieval. Folders Shared with Me Folders others have shared with you. Communities Communities you belong to and public communities. This folder does not automatically display all of the communities you can access. Add the communities to access from your desktop. Click the icon for a community to view associated files. To add a new community, right-click Community in the navigation pane, choose Add, then type the name of a community to add. People This folder lists files that have been shared with you organized by the person who shared them. The folder does not automatically display all of the people who have shared files with you. Add the people who have shared files to track from the desktop. Click a profile picture to see the associated files. To add a new person to their folder, right-click People in the navigation pane, choose Add, then type the name of a person. Trash Move a file to the trash hides it from all folders and it no longer appears in searches. When you move a file to trash, all of the file's versions, recommendations, and comments move to trash, and the file is hidden from people with whom you have shared it. If a file is restored from the trash, it is added back to the folders it was previously in, and all data is restored. When you restore a file from trash, all versions, recommendations, and comments are restored, and people with whom you have shared the file can see it again. The Trash folder contains subfolders for trash from My Files, each community, and each person. Only subfolders containing deleted files are displayed
Uploading files
Add files to IBM Connections Files so that you can store them or share them with others.
Upload files from your desktop and add them to IBM Connections. You can upload them to the Files application, where you can make them public, keep them private or share them with people or communities you specify. You can upload a file to a community so that all members of the community can access the file. You can also upload to an activity to make it available to activity members or to a wiki to make it available to wiki members.
If you get an error when uploading PDF files, check with your administrator. If Connections is running in a TAM or TAM and SPNEGO security environment, the administrator should make sure that the parameter suppress-dynurl-parsing-of-posts is set to yes on TAM server to allow for the proper uploading of PDF documents.
Uploading a file to the Files application
Add files to IBM Connections Files so that you can store them or share them with others.
You must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site. You must also have at least Contributor access to add files to IBM Connections.
- Right-click a file name from Windows Explorer and select IBM Connections > Add to Files. Alternatively, you can drag a desktop file to My Files in the IBM Connections section of your Windows Explorer navigation pane or paste a file into the same section.
- If you connect to more than one IBM® Connections site, select a site to upload the document to.
- Optional: Add tags to help you more easily find the document in IBM Connections.
- Select any of the following choices:
Option Description No one (visible only to me)
Make the file private. Only the owner can see and edit it.
People or Communities
Share the file with specific people or a community. Perform these steps:
- Select a Person or a Community.
To share with a public community you must be using Connections 3 or higher.
- Select the as Reader or as Editor access level:
- Readers can read or download a file. They can add files to folders to which they have Contributor access, be notified of changes to the file, and share the file with other people.
- Editors can read, edit, download, upload a new version, and set properties on the file. They can add files to folders to which they have Contributor access, be notified of changes to the file, and share it with other people.
- Perform one of the following tasks:
- To share with people, click in the field to display the names of people you have recently shared files with. If the person you are looking for is displayed, select them. If they are not displayed, type a name or email address, and then select the person.
- To share with a community, start typing the name of the community, and then select the community when it displays.
When you share a file with a public community the file becomes public.
When you share a file with people or a community, the option Allow others to share this file is enabled by default. You can disable this if you do not want others to share the file. This option is not available if you make a file public.
Public (visible to everyone)
Make the file visible to everyone, even people who have not logged in.
An administrator can configure the system so that everyone must log in, or only a certain group of people can log in. In this case public files are only available to users who are able to log in.
- Click Upload.
Uploading a file to a community
Add a file to a community to share it with community members.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Right-click a file name from Windows Explorer and select IBM Connections > Add to Communities. Alternatively, you can drag a file from Windows Explorer or from the desktop and drop it into the File folder for the target community, or paste a file to the same destination.
Dragging a file or pasting a file into a community directly uploads the file into the community instead of sharing it with the community.
- If you connect to more than one IBM® Connections site, select a site to which you want to upload the file.
- Set the name of the community, and then select it. Or click the arrow icon next to the Community field and select a community that you are a member of.
- Choose one of the following:
- Upload to community to upload to a selected community. Choose this option if you intend to only share a file with members of the community.
- Upload to My Files and share with community. Choose this option if you want to share with colleagues who are not members of the community as well as sharing with community members.
- Click OK to upload the file. When you open the activity in IBM Connections, your file is in the community.
A file shared with or uploaded to a community inherits the visibility of that community. For example, if the community is public all files within the community are also automatically public.
Results
If you want to add a file to a community that already displays in your IBM Connections navigation pane, expand the community list so you can see the Files folder for the target community and drag in a file to upload it to the community.
Uploading a file to an activity
Add a file to an activity to share it with other activity users.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Right-click a file name from Windows Explorer and select IBM Connections > Add to Activities.
- If you connect to more than one IBM Connections site, select a site to upload the file to.
- Do one of the following:
- Click Browse to find an existing activity, then do one of the following:
- Select My activities and choose from the list of activities you own or are a member of. The list includes community activities.
- Select Search, then type characters to use to search for activities. The results include community activities.
- Click OK.
- Click Create new activity, then:
- Type a name, tags and a goal for the activity.
- Optionally add a due date.
- Add people or communities as members with specified access.
- Click Create.
- If you are adding the file as a To Do item, by default, the task is assigned to Anyone (shared), meaning any member of the activity can perform the task, and then check it off after it has been completed. To assign the to-do item to a specific member perform one of the following actions:
- Standard activity:
- To assign the to-do entry to a specific person, select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
- If the activity has been shared with a community, then you can assign the to-do item to a community member by selecting Community: community_name where community_name is the name of the community, and then selecting the persons name from the list.
- If a person is a member of a group that belongs to the activity, then add the person as an individual activity member before you can add them.
- Community activity to which all community members were added:
- Select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
If the activity has more than 500 members, you can click Next to see additional names.
The filter searches the names on the current page only. If there are multiple pages, click Next until you get to a page with names in the same alphabetic range as the name you are looking for, and then type the name into the filter box.
- Community activity to which only a subset of community members were added:
- Select Individual activity members, and then select the persons name from the list. To find people, scroll through the alphabetic list of names or type a person's name into the Type to filter this list field.
If the activity has more than 500 members, you can click Next to see additional names.
The filter searches the names on the current page only. If there are multiple pages, click Next until you get to a page with names in the same alphabetic range as the name you are looking for, and then type the name into the filter box.
- To assign the to-do entry to a community owner, select community_name (community owners) where community_name is the name of the community, and then select the owners name from the list.
- Optional: Add a due date.
- Optional: Change the title, and add tags, a description, and new section. Typeahead for the Tags and Section fields returns matches as you type if you want to keep tags and section names consistent.
- Optional: Mark the to do as private if you do not want other members to see it.
- Click Upload.
Uploading a file to a wiki
Add a file to a wiki to share it with other wiki users.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Right-click a file name from Windows Explorer or the desktop and select IBM Connections > Add to Wikis.
- If you connect to more than one IBM Connections site, select a site to upload the document to.
- Do one of the following:
- Select My wikis, and then expand the wiki you want and select a page.
- Select Search, and type characters to use to search for a wiki.
- Select an existing wiki page attachment.
- Optional: Change the file name.
- Click Upload. If you selected an attachment, it will be replaced by the uploaded document.
Sharing a file with additional people or communities
If you have uploaded a file to the Files application, you can share it with other people and communities from Explorer.
When you share files, roles determine how others can interact with the file. Owners can share their files with people or communities. People can have Reader or Editor access to the file. Communities have Reader access. If you are connecting to an IBM Connections 4.0 server, communities can also have Editor access.
- Readers can read, comment on, download, and recommend a file, be notified of changes to the file, and share the file. They can add a file to one of their folders, or to a folder to which they have Contributor access.
- Editors can read, edit, comment on, download, recommend, upload a new version of, and set properties on the file. They can be notified of changes to the file, and share it. Editors can also add a file to a folder of theirs, or to a folder to which they have Contributor access.
- Right-click the file in the IBM Connections section of Explorer and select Share.
- To share the file with everyone, select Public.
- To share with people or communities, select People or Communities and specify the people or communities you want to share the file with.
- Add an optional message to describe the file. This message will be shared with the people or communities you specified.
- Click Share to share the file. An email notification is sent to the people listed in the dialog.
Viewing file details in a browser
If you have uploaded a file to the Files application, you can launch IBM Connections in a browser and view your file.
- Navigate to a file you have already uploaded to the Files application, for example, a file in the My Files node of IBM Connections.
- Right click the file and select Open in browser.
- If prompted to log in, enter your IBM Connections user name and password.
- View your file in the My Files application.
What to do next
From the IBM Connections Files application you can perform all available actions on the file. For example, you can download the file for viewing or editing, upload a new version, or share the file with others. Refer to the IBM Connections help for descriptions of all actions available from the Files application.
Publishing local drafts
Publish updates to your files from Explorer or from the Drafts monitor.
If you change a local version of a file you have posted to IBM Connections, you can publish your changes as a new version of the file. Publish a new version from Explorer, or use the Files monitor to view all drafts and publish changes.
Publishing drafts from the Drafts monitor
Publish updates to your files from the Drafts monitor. When you download a file from IBM Connections and edit the file, a notification message in the system tray informs you that a new draft has been created. You can view all of your files in the draft state from the Drafts monitor. From the monitor, you can open a draft, publish your changes to IBM Connections, or delete a draft.
- Click the IBM Connections icon in the system tray to open the Drafts monitor. The Drafts monitor lists all of the files you have with unpublished changes.
- Right click a draft and select one of the following to work with a draft:
- Open draft to open a local copy of the file for editing.
- Publish to publish your changes as a new version of the file. You are prompted to add an optional change summary. People with whom you have shared the file will be notified that the file has changed. The notification is enabled by default, but you can disable it..
- Delete draft to permanently remove the local draft. Deleting a draft does not affect the version of the file published to IBM Connections.
Publishing drafts from Explorer
If you revise a local copy of a file, you can publish the changes or upload a new file. If you change the local copy of a file that you have downloaded from IBM Connections, you can publish the changes so they appear as a new version of the file or you can upload a new copy of the file.
- If you have editor access, you can publish your local draft as a new version. Right click the file and choose Publish local draft. You are prompted to add an optional message and choose whether to notify others by email.
- To discard the changes you have made to this file, right-click the file and choose Delete local draft. You are notified that the changes you made to the draft will be discarded.
- To upload a new version, right-click a file and choose Upload New Version. Browse for a file to upload as a new version.
Connecting to others using the business card
Use the business card to view peoples' contact details and get in touch with them. The business card provides a useful snapshot of a user's IBM Connections profile information.
The business card provides links to the IBM Connections applications that are used by the person and allows you to perform a number of actions. For example, if your administrator has configured email addresses to display, you can send an email.
- To access a person's business card, right-click their name in any IBM Connections dialog, or for example the People section, and select View business card.
- Use the business card to perform the following tasks:
- Click the name of a person to open their IBM Connections profile.
- Add the person as a colleague by selecting the Invite to My Network icon, typing an invitation message, and clicking Send invitation.
- Follow a person by selecting the Follow icon. You will receive notifications about this person.s activities.
- Send the person an email by clicking Send E-mail icon.
This option is not available if your administrator has configured IBM Connections to prevent email addresses from being displayed.
- Download a person.s vCard by choosing More Actions > Download vCard and specify a path where you want to save the vCard.
- Access the applications associated with a person by clicking More Actions and selecting an application. For example, you can view a person.s full profile by clicking Profiles.
Following files and folders
You can receive notification when changes are made to a file or folder.
When you follow a file or folder, notifications are sent to your IBM Connections home page when the file or folder is updated.
To track file and folder changes:
Option Description To be notified when a file is added to a folder
Right-click a folder and select Properties. Check Follow this folder.
By default this is selected for folders that you own and public folders.
To be notified when a file is edited or commented on
Right-click a file and select Properties. Check Follow this file.
By default this is selected for files that you own and public files.
- To stop following:
- Right-click a folder and select Properties. Uncheck Follow this folder.
Right-click a file and select Properties. Uncheck Follow this file.
Viewing properties for a file or folder
You can pin, follow, or recommend a file or folder from the properties panel.
When you view the properties for a file or folder, you can view information about version and sharing. You can also pin, follow, or recommend the file or folder.
Right-click a file and choose Properties. The following options are available from the Properties panel:
Option Description File name, description and tags If you have permission, you can edit these fields to rename the file, add or edit a description, or add or edit tags. Sharing details Click Sharing details to see who the file is shared with.
If you own the file or have sharing rights, you can add people or communities to share with.
Likes Click Like this file to like a file. You can also view the number of likes.
Pin Click Pin this file to add a file to Pinned Files in the navigation pane.
Follow Click Follow this file if you want notifications about changes to a file or folder added to your Notifications list in the IBM Connections browser application.
Comments Click the Details link to view information about comments.
Depending on your access, you can add a comment, follow or stop following a comment, or open a comment in a browser.
Versions Click the Details link to view information about versions.
From the versions panel you can double-click a version to open it. Depending on your access you can delete a version or restore a previous version.
Downloads Click the Details link to view information about downloads.
Right-click a person.s name to see available actions such as viewing a business card or sending a link to the file or folder.
Lock Lock a file to prevent others from editing it. Unlock the file to make it available for editing. Right-click a folder and choose Properties. The following options are available from the Properties panel:
Option Description Folder name and description If you have permission, you can rename the folder or edit the description. Sharing details Click Sharing details to see who the folder is shared with.
If you own the folder or have sharing rights, you can add people or communities to share with.
Pin Click Pin this folder to add a folder to the Pinned Folders folder in the navigation pane.
Follow Click Follow this folder if you want notifications about changes to a folder added to your Notifications list in the IBM Connections browser application.
Search IBM Connections from Microsoft Office and Outlook
Search for IBM Connections content from Word, Excel, PowerPoint, and Outlook.
To perform these steps you must be connected to an IBM Connections site. For more information, see Connecting to an IBM Connections site.
- Open a document or email.
- Click the IBM Connections tab.
- In the Search section, select an IBM Connections site to search if you connect to more than one.
- Type characters in the search field and click the magnifying glass icon to search those characters.
- Optional: Click Open Advanced Search to open IBM Connections and search from there.
Set preferences for IBM Connections Plug-ins for Microsoft Windows
Set preferences for the IBM Connections Plug-ins for Microsoft Office, Microsoft Outlook, and Microsoft Windows Explorer.
Open a document in any Microsoft Office application or from Microsoft Outlook, click the IBM Connections tab, and then click Preferences. Or from Microsoft Windows Explorer, right-click IBM Connections, and then click Preferences.
Table 102. General preferences
Preference Description Email settings Select Use Mail application and specify an email provider, such as Lotus Notes. This is the email the plug-in will use for notifications. Select Use mailto: protocol to use the default email. Show Desktop icon Places an icon for the plug-in on your desktop. Show Windows Explorer Context Menu Extension This controls whether the IBM Connections context menu displays when you right-click a desktop file. Table 103. Connections site preferences
Preference Description Site URL The URL for the IBM Connections server you are connecting to. Display name The name of the IBM Connections server. User name The user name you use to log into IBM Connections. Password The password you use to log into IBM Connections. Authentication type By default, the plug-in authenticates with the IBM Connections server using basic authentication. If your administrator has implemented an alternate authentication mechanism in the environment in which the IBM Connections server is running, you might be instructed to edit the authentication settings. Table 104. Outlook Social Connector preferences
Preference Description Outlook Social Connector Provider Select up to four servers to add to the Outlook Social Connectors (OSC). Add Connections servers to OSC will make Connections profiles available in Outlook contacts and in the People Pane. Once a server is added to OSC it cannot be removed by un-checking the server name here. If Outlook is open, restart it to see the changes. Table 105. Downloaded files preferences
Preference Description Alert me when I save a draft When this option is enabled, a popup message notifies you when you save a draft. Enable automatic deletion of drafts When this option is enabled, unpublished drafts are deleting on the schedule you specify. Ignore local changes made to files with these extensions Specify extensions for types of files you do not want to save as drafts.
Use the IBM Connections Status Updates Plug-in for Lotus Notes
Status Updates let you keep up with your Connections network from the Notes client.
The Status Updates application lets you:
- Post your status so that colleagues can see what you are working on
- View status updates for your colleagues and comment on them
- Clear your status
- Forward a post via email
- View your board or someone else's board
- Work with updates from the system tray, even when you are not working in Notes
What.s new in this release? Using new features, you can:
- Attach a local file to your status update so you can easily share it with colleagues
- Search for people or communities using a new search bar with typeahead support
- Post status updates to a community you can access
- View all updates from your activity stream
- Recommend posts using the Like button
Work with Status Updates
Keep up-to-date with what is happening in your network with the Status Updates sidebar application.
Purpose
Do the following to work with your status updates:Table 106. Working with Status Updates
Task Steps Manage your status Do any of the following:
- Enter a status message and click Post to publish it.
- Click Reset to clear your current update.
- Right-click an update you posted and choose Delete to remove it.
Share a photo or a file with others To share a photo or file, enter the text for an update, then click Attach a File. Browse for a local file. The file is appended to your post so that others can view or download it. Interact with other people in your network Do any of the following:
- To comment on an update, click Add comment, enter your comment and click Post Comment.
- To view all of the status updates for one person, click the name of the person to view their board. You can also change the search scope to People and begin to type the name or email of a colleague. The type-ahead feature returns matches. Choose the matching name to view all updates from that person.
- Click a file attachment that a colleague has posted to open the file in an appropriate application.
Recommend posts and comments To recommend a post, open the entry or comment and click Like to recommend it. Click Undo if you no longer want to recommend it. Interact with communities you can access Do any of the following:
- To post an update to a community you can access, use the search bar to find the community. You can change the scope to search all communities, public communities, or communities for which you are a member. Status updates you post to a community display in the Recent Updates view of the community.
- Choose the I.m Following > Communities view from the application menu to view all recent updates to these communities.
Change the view in the application window To change views, click the menu icon for the application and choose from one of these views:
- I.m Following displays all updates for people and content you are following. You can also choose to filter what displays so you can view a more targeted list of updates.
- Status Updates displays status updates but no other notifications from colleagues.
- Discover displays updates and other activities from your colleagues, whether they are in your network or not.
- Recent Communities lets you pick a community you accessed recently to view recent updates posted to that community.
- Connections Preferences opens the preference page where you set the server URL and log-in credentials for connecting to an IBM Connections server.
View a colleague.s profile in IBM Connections To view a profile in IBM Connections, right-click an update and select Open in Browser. Connections opens in the default Web browser so you can view and interact with the profile for the person you selected. Forward a status update To forward a status message using Lotus Notes, right-click an entry and choose Forward this Entry. The comment is inserted into an email form. Work with updates from the system tray Do any of the following:
- To update your status when you are not working in Notes, right-click the Status Updates icon in your system icon tray and select Update Status. Enter your status and click Update.
- To view status updates when you are not working in Notes, right-click the Status Updates icon in your system icon tray and select View Status Updates. This opens your Notes client with the Status Updates application open.
Use the IBM Connections Files plug-in for Lotus Notes
Use the IBM Connections Files plug-in for Lotus Notes to have easy access to your files or community files from the Notes sidebar.
The Connections Files plug-in lets you upload and access files from the sidebar of your Notes client. After installing the sidebar application you can:
- Upload files for your own use or to share with others.
- Drag and drop an attached file or a file from your desktop to Files.
- Drag and drop or copy and paste a file from Files to your desktop.
- Send an HTML link to a file.
- Search for people or communities.
- Sort files for easier browsing.
- Detach the Files window from the Notes sidebar.
- Open Connections Files in a browser.
What.s new in this release?
- Lock files to prevent others form editing them.
- Use enhanced search to search the full directory for people.
Uploading a file in Connections
Add files to Connections Files so that you can store them or share them with others.
- To browse for a file to upload, do the following:
- Click Upload to My Files from the panel menu or click the File Upload icon on the toolbar of the Files panel.
- In the File field type the file path or browse for the file.
- In the Name field type a file name if browsing does not add one. Or change the name of the file.
- To drag and drop a file to upload, do the following:
- Drag a file from your desktop or drag a file attachment to the Files sidebar application.
- Drop the file.
- Select any of the following choices:
Option Description No one (private)
Make the file private. Only the owner can see and edit it.
People/Communities (give specific file permissions to others)
Share the file with specific people or a community. Perform these steps:
- Select a Person or a Community.
To share with a public community you must be using Connections 3.
- Select the as Reader or as Editor access level:
- Readers can read or download a file. They can add files to folders to which they have Contributor access, be notified of changes to the file, and share the file with other people.
- Editors can read, edit, download, upload a new version, and set properties on the file. They can add files to folders to which they have Contributor access, be notified of changes to the file, and share it with other people.
- Perform one of the following tasks:
- To share with people, click in the field to display the names of people you have recently shared files with. If the person you are looking for is displayed, select them. If they are not displayed, type a name or email address, and then select the person.
- To share with a community, start typing the name of the community, and then select the community when it displays.
When you share a file with a public community the file becomes public.
Public (visible to everyone)
Make the file visible to everyone, even people who have not logged in.
An administrator can configure the system so that everyone must log in, or only a certain group of people can log in. In this case public files are only available to users who are able to log in.
- Click OK.
What to do next
To replace a file you have uploaded with a newer version, do the following:
- Right click the file and select Upload New Version.
- Browse for a new version of the file.
- Add an optional change summary.
- Click OK to replace the existing file with a newer version.
Sharing a file
Share a file with others using the IBM Connections Files plug-in for Lotus Notes.
When you share a file, you can give people Reader or Editor access. You can give communities Reader access.
You can also share files that have been shared with you if the owner allows it, but you cannot make them public. Only owners can make a file public.
To see who has access to your files, right-click a file and click Sharing details.
Do any of the following to share a file:
Option Description To share a file when you upload it
- Click Upload to My Files.
- Set the file path or browse for the file.
- Type a file name.
- Select No one to keep the file private, select People if you want to specify people to share with or select Public to share with everyone.
- Click OK.
To share a file after you upload it
The type of notification a share recipient receives depends on what you have configured for notifications in Lotus Connections.
- Right-click a file name and select Share File.
- Select People if you want to specify people to share with or select Public to share with everyone.
- Click Share to share the file.
To email a link to a file
- Right-click a file name and select Copy Link.
- Paste the link into an email.
- Send the mail to one or more people.
To copy a file so you can include it in an email
- Right-click a file name and select Copy.
- Create an email.
- Right-click in the body of the email message and select Paste. .
- Add any additional text to the mail and send it.
Locking files in Connections
Lock files to prevent people from editing them.
The Owners and Editors of files can lock and unlock those files. For example, if you upload a file you are the owner and can lock and unlock that file. If you give a person Editor access to the file, they can also lock and unlock it. When you lock a file, people can still download and read it, but only you can upload new versions of it.
When a file is locked it cannot be edited, but it can still be deleted.
- Right-click a file in the sidebar application and choose Lock File.
- To unlock the file, click More Actions > Unlock File
Search for files
Use search criteria to find files by keyword, or associated with people or communities of interest to you. You can also sort the files to make browsing for a file easier.
- Do any one of the following to find files:
Option Description To find files you uploaded
Click My Files > My Files to browse your uploaded files.
To find files people shared with you
Click My Files > Shared With Me to view files shared by other people specifically with you. Files shared with you might also be public.
To find files you shared with people
Click My Files > Shared By Me to view files you shared with specific people. Files shared by you might also be public.
To find files associated with a person or community
Search for the name of the person or community to see files associated with them or click the view menu, choose Other Files, and choose the name of the person or community.
To search for public communities you must be using Connections 3 or higher.
To search for files
Select one of the search scopes: People, My Communities, Communities or Files in this View Type characters into the search field. Connections returns files associated with the person or community you specify, or with those characters in the title, description, or file contents. If you do not see a match for a person, click Search directory to search the complete directory in an attempt to find the person.
To search for public communities you must be using Connections 3 or higher.
- Do any of the following to sort the list of files, to make it easier to browse:
Option Description To show files by name
Click My Files > Sort by > Name to view an alphabetical list of files. Select this menu item again to reverse the sort order.
To show most recent files
Click My Files > Sort by > Most Recent to view a list of files with the most recently updated file first on the list. Select this menu item again to toggle the sort order so that the most recently updated file is last on the list.
Opening Files in a new window or in a browser
Access the full Files capabilities by opening Connections Files in a browser window or display the Files plug-in in a window that is independent from the Notes sidebar. The Connections Files plug-in for Lotus Notes provides a subset of the full Files capabilities. If you require features that are not available in the sidebar application, you can launch Connections Files from the sidebar application. You can also choose to display the Files plug-in in a window that is separate from the Notes client sidebar so you can resize it or move it to a different location.
- To open Connections Files in a browser window, click Open in Browser from the panel menu. Connections Files opens in the web browser specified in your Lotus Notes preferences. If you have set the Lotus Notes preference for Web browser to open web pages as a tab within Notes, you will not be required to log into Files. If your preferences are set to open web pages in an external browser, you may need to log into Connections.
- To open the Files plug-in in a new window, click Open in New Window from the panel. To return the Files plug-in to the Notes sidebar, choose Dock from the panel menu.
Set IBM Connections server preferences for Files
You can provide your IBM Connections password or specify the address of the server in the Connections preferences page. If you are already using the Connections Activities sidebar application, the preferences should already be set for you to access Connections Files. If you need to modify the settings, the Connections Server Sets section of the preference page contains the information required to log in to the Files panel of the sidebar. To set the server preferences, complete the following actions:
- From the panel menu, select Preferences.
- Fill in the following fields in the Connections Server Sets section:
Field Description Server URL Set the Web address of the Connections activities server, beginning with either https:// or http:// For example: https://enterprise.example.com
If you know that the server requires a secure, encrypted connection, begin the address with https://
Some administrators change the context roots that are used to access Connections features. If the Web address that you normally use to access the Activities feature has a value other than <server_name>/activities, specify the server URL using a syntax similar to this: http://enterprise.example.com/activities
Your administrator might have already provided a value for this field using an administrative policy. If so, do not change the value.
User name Type your user name for logging into the Connections server. User password Set the associated password.
- Click Apply to save your changes, and then click OK to close the Preferences window.
Results
The next time that you use Notes, the new settings are used to log you in to Connections automatically.
Use the IBM Lotus Notes Activities sidebar
Access the IBM Connections applications from within the Notes client.
You can access your IBM Connections data from within the Notes client by choosing to install the IBM Connections feature while installing the Notes client. The product documentation for the Activities sidebar is included in the Notes client help system.
Use plug-ins from other products with IBM Connections
Get help using the plug-ins that bring the capabilities of other products into IBM Connections.
Use the IBM Connections Connector for Lotus Quickr
Access the IBM Connections applications from within Lotus Quickr.
You can create, view, and manage access to a Lotus Quickr place from within an IBM Connections community by installing the Lotus Quickr connector. The product documentation for the connector is included in the Lotus Quickr connector help.
Use the IBM Connections Plug-in for Microsoft SharePoint
Use the IBM Connections plug-in for Microsoft SharePoint to bring IBM Connections features such as searching by tag, searching by profile, and viewing business cards, into the SharePoint environment.
After an administrator installs and deploys the IBM Connections Plug-in for Microsoft SharePoint, users will be able to:
- Search IBM Connections Profiles to find people in your organization. If colleagues you find with a Profiles search are in your SharePoint directory, you can add them to your SharePoint group or site.
- View a colleagues IBM Connections business card to get contact and social networking information about users in your organization. From the business card, you can create a mail message to this colleague or open their blog, bookmarks or full profile.
If the IBM Connections uses hidden email, the business card will not display. Also, if you are using the SharePoint plug-in with Siteminder single-sign-on and you see an error for loading data for the business card, check the security settings for your browser and make sure the setting to access data sources across domains is enabled.
- Use the tag cloud to find content stored on IBM Connections servers. Clicking a tag launches a search that matches against all Connections services. For example, clicking a new-hire tag could return a community and a blog posting.
If your administrator has also deployed the IBM Connections Widget for Microsoft SharePoint, you can access SharePoint files from an IBM Connections community.
Use the SharePoint widget
Access Microsoft SharePoint documents from within an IBM Connections community. Documents you upload to the widget from SharePoint are available to all members of the community. The SharePoint widget lets you include SharePoint documents in your community. To access the widget you must have the user name and password you use to access your SharePoint server. if you don't have this information, consult your SharePoint administrator.
- After adding the SharePoint widget to your community, log in to the SharePoint server with your Sharepoint user name and password.
- To add a document, click Upload a Document and specify a file to upload and a destination folder.
- To create a new folder, click New Folder and enter a folder name and description.
- To open the SharePoint server click Go to SharePoint.
- Click the folder menu to do any of the following:
- Click Open to expand the folder and view subfolders and documents.
- Click Upload document to and browse for a document to add to the folder.
- Click Edit Properties to change the folder name.
- Click Delete to permanently remove the folder and all of its contents.
- Click a document name and perform any of these operations:
- Click Download this document to open a document for viewing or editing. The document will open in it's native application. For example, if the document is a Microsoft Word document, it will open in Microsoft Word.
- Click Upload new version and browse for the file to replace the document with a newer version.
- To change the properties of a document, such as the name, click Edit properties. Edit the properties and save the changes.
- Click Delete to permanently remove the file from the SharePoint widget.
- To create a feed of the SharePoint documents list, click Feed for SharePoints Documents List, copy the feed data, and paste it into your feed reader.
Use the Linked Lotus Quickr library widget
The Linked Quickr Library widget lets you work with documents in an existing Lotus Quickr Library from an IBM Connections community.
Perform the following tasks to add a Linked Lotus Quickr Library widget to a community.
- Open the community.
- Click Community Actions > Customize.
- In the Add Content section, click Linked Quickr Library and then close the section. A Linked Quickr Library widget is added to the community.
- In the widget menu, select Edit.
- Type a title for the library as it displays in the community.
- Type or paste the direct URL of the library. To copy the URL, open the library in Lotus Quickr and click Show links.
- Click Save.
- Click the library title in the widget to open the library as in full application mode.
- For help using the library, click the Help link.
Use the Lotus Quickr library widget
The Quickr Library widget lets you create a new Lotus Quickr Library and work with it in an IBM Connections community.
Perform the following tasks to add a Lotus Quickr Library widget to a community.
- Open the community.
- Click Community Actions > Customize.
- In the Add Content section, click Quickr Library and then close the section. A Quickr Library widget is added to the community.
- Click the link in the widget. It is the name of the community.