IBM Connections 4: Customize, Security, Performance, and Integration


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.

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:

The following types of change cannot be made using the customization directory:


Customization guidelines


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.

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

  2. Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

  3. 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.war

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

    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.

      • /nav/common/styles/defaultTheme/custom.css

      • /nav/common/styles/defaultTheme/custom_rtl.css
      For more information, see Add styles to the IBM Connections stylesheet.

    • To make extensive changes to the colors used in the product, edit the following file:
      /nav/common/styles/defaultTheme/defaultTheme.css

      For 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.jsp
    For 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

  4. Edit the file stored in the customizationDir directory to make your changes.

  5. Test your changes by refreshing the web browser. You might also need to clear your browser cache to see the changes.

  6. When you are ready to publish your changes, turn off the customization debugging capability.

  7. Use the WebSphere Application Server Integrated Solutions Console, stop and restart each application EAR file.

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

  1. Log in to the IBM WebSphere Application Server Integrated Solutions Console.

  2. Expand Environment and select WebSphere variables.

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

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

  1. To turn on the customization debugging capability, add a WebSphere Application Server environment variable named CONNECTIONS_CUSTOMIZATION_DEBUG and set it to true.

    1. Open the IBM WebSphere Application Server Integrated Solutions Console, expand Environment, and then click WebSphere variables.

    2. In the Scope section, select cell 1 from the list, and then click New.

    3. Set the following values into the fields:

      Name

      CONNECTIONS_CUSTOMIZATION_DEBUG

      Value

      true

    4. Click Apply, and then OK to return to the previous page.

    5. Restart the server for your changes to take place.

  2. To disable customization debugging, set the CONNECTIONS_CUSTOMIZATION_DEBUG variable to false.

    1. Open the Integrated Solutions Console, expand Environment, and then click WebSphere variables.

    2. In the Scope section, select cell 1 from the list.

    3. Select CONNECTIONS_CUSTOMIZATION_DEBUG and enter false in the Value field.

    4. Click Apply, and then click OK.

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

where:


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.

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

    1. 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/templates

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

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

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

    4. Add the following HTML code before the closing </ul> tag:

      <li><a href="http://www.ibm.com" >IBM website/a></li>

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

  3. 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:

    1. Copy the user.jsp file from application_name.war/nav/templates/menu/ to the following location:

      customizationDir/common/nav/templates/menu/user.jsp

    2. Modify the following line in the copied file to add a lotusHidden style:

      --%><td class="lotusNowrap lotusHidden" id="logoutContainer"</><%--

    3. Save and close the customized user.jsp file.

  4. To add a new drop-down menu:

    1. Copy the user.jsp file from application_name.war/nav/templates/menu/ to the following location:

      customizationDir/common/nav/templates/menu/user.jsp

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

    3. Save and close the customized user.jsp file.

  5. To make changes to Communities, Profiles, and Apps menus, copy or remove code sections to render links in the respective JSP files:

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

    2. Paste the copied file into the following directory:
      customizationDir/common/nav/templates/menu/

    3. Open the copied file in a text editor and make your changes.

    4. 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">&#9660;</span><%--
                    
                 --%></a><%-- 
             --%>
    </li>

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

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

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

  2. Open the copied image file and update it as needed.

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

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

  5. Stop and restart the Common.ear file in order to pick up the CSS changes.

  6. Test whether your custom image is being displayed successfully by refreshing the web browser and opening the page where the image is displayed.

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

  2. Create a CSS file named custom.css and store it in the following subdirectory of the customization directory:
    customizationDir/themes/defaultTheme

    For information about how to find out where your customizationDir directory is located, see Determining where to save your customizations.

  3. Save your company logo in the following directory:
    customizationDir/themes/defaultTheme/images

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

  5. Save and close the custom.css file.

  6. Stop and restart the Common.ear file in order to pick up the CSS changes.

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

  2. Add the new icon files to the following directory:
    customizationDir/themes/images

    where customizationDir is the base directory where your customizations should go. For more information, see Determining where to save your customizations.

  3. 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/base

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

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

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

      1. 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;}

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

      3. 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; }

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

  2. Download the following file:

    Spriting.zip

  3. Extract the contents of Spriting.zip to a local working directory.

  4. Modify the sprited images as needed using an image editor of your choice. The images are located in the resources/imageLibrary folder.

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

  6. From the working directory, run the following command to compile the final CSS for the sprited images:

    ./spriteCat.sh

  7. A css folder is created inside the resources directory. Copy all of the contents of this directory to the following location:
    customizationDir/themes/

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

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

  3. 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.css

    Alternatively, you can copy it from any of the application WAR directories:
    application_war/nav/common/styles/defaultTheme/defaultTheme.css

    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

  4. Add new style definitions or edit the style specified for the class definition that you copied from the defaultTheme.css file.

  5. Save and close the custom.css file.

  6. Stop and restart the Common.ear file in order to pick up the CSS changes.

  7. To test your style changes, reference your new style from a user interface element, and then refresh your web browser.

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

  2. Create a defaultTheme directory in the customizationDir directory.
    For example: customizationDir/themes/defaultTheme

    For information about how to find out where your customizationDir directory is located, see Determining where to save your customizations.

  3. Navigate to the web application defaultTheme directory:
    WAS_HOME/profiles/profile_name/installedApps/cell_name/application_name.ear/application_name.war/nav/common/styles/defaultTheme

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

  4. 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.css

    Notes:

    • 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.css

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

  5. Open the copy of the defaultTheme.css file in a text editor.

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

  7. Save and close the CSS file.

  8. To test your style changes refresh the web browser.

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

    The login.jsp file is the same for each application. You only need to make a copy of one instance of the file.

  3. Paste the login.jsp file into the appropriate subdirectory of the customizationDir 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
    See Determining where to save your customizations for more information about locating your base customization directory.

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

  5. Save and close the login page.

  6. To test your changes, log out of the product. Refresh the web browser, and then go to a login page.

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

    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.

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

  4. 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}"&gt;<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.

  5. Save and close the footer.jsp file.

  6. Restart the applications, and then refresh your web browser to see your changes.

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

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

    The error.jsp file is the same for each application. You only need to make a copy of one instance of the file.

  3. 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/templates

    If you want to create an application-specific error page, copy the file into the following directory:

    customizationDir/application_name/nav/templates

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

  5. Save and close the error.jsp file.

  6. To test your changes, refresh the web browser, and then perform an action that will generate an error message.

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

  8. 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:

  1. Welcome

  2. Share

  3. Explore
You can edit the content that is displayed in each tab and you can add or remove tabs.

  1. Open a command window, and then start the wsadmin command line tool.

  2. Access the configuration files for the Home page application:

    execfile("homepageAdmin.py")

  3. Check out the Get Started view configuration files :

    HomepageCellConfig.checkOutGetstartedConfig("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 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()
    For example:

    • AIX/Linux:

      HomepageCellConfig.checkOutGetstartedConfig("/opt/act/temp","foo01Cell01")

    • Microsoft

      Windows:

      HomepageCellConfig.checkOutGetstartedConfig("c:/act/temp","foo01Cell01")

  4. From the temporary directory to which you checked out the gettingstarted-config.xml file, open it in a text editor.

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

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

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

      3. To change what is displayed in a tab, edit the title and content of the page. See the previous bullet for details.

  6. Save and close the gettingstarted-config.xml file.

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

  8. 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:

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

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

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

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

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

  4. Use the IBM WebSphere Application Server Integrated Solutions Console, stop and restart each application EAR file.

  5. Test your changes by clearing your browser cache, and then refreshing the browser.

  6. To force all user web browsers to refresh all cached content and display your changes, run the command that updates the product version stamp.

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

    2. Enter the following command to check out the IBM Connections configuration files:

      LCConfigService.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 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()
      For example:

      • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

      • Microsoft

        Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    3. 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","").

    4. 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/webresources

      For 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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
com.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.jar

If 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.properties

See Customize strings sourced in JavaScript for more information.

customizationDir/strings/com.ibm.openactivities.web.coreui.resources.
resources.properties
Activities 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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/strings/com.ibm.lconn.homepage.resources.nls.activitystream.
activitystream_resources.properties
Activity Stream filters In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/activitystream/config/activitystreamconfig_resources.properties
customizationDir/strings/com.ibm.lconn.homepage.resources.nls.activitystream.
config.activitystreamconfig_resources.properties
Notification strings In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
com/ibm/lconn/homepage/resources/nls/ui/ui_resources.properties
customizationDir/strings/com.ibm.lconn.homepage.resources.
nls.ui.ui_resources.properties
Strings 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.properties
customizationDir/strings/com.ibm.lconn.homepage.resources.nls.catalog.service.
ui.CatalogServiceUIMessages.properties
Widget resources In installedApps/Homepage.ear/homepage.war/WEB-INF/lib/homepage.utils.jar:
/com/ibm/lconn/homepage/resources/nls/widgets/widgets_resources.properties
customizationDir/strings/com.ibm.lconn.homepage.resources.nls.widgets.
widgets_resources.properties
Core 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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/strings/com.ibm.lconn.profiles.api.actions.
resources.properties
Main 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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/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.properties
customizationDir/strings/com.ibm.lconn.wikis.strings.ui.properties
Help tooltips In installedApps/Wikis.ear/wikis.web.jar:
com/ibm/lconn/wikis/strings/uihelp.properties
customizationDir/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.properties
customizationDir/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.

  1. Locate the JavaScript source file for the application to customize, based on the information in the topic, JavaScript resource strings.

  2. Determine the base directory where your customizations should go. For more information, see Determining

    ...where to save your customizations.

  3. 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.js

    For 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.js

    For a full list of the language codes supported by IBM Connections, see Language codes.

  4. Open the copied JavaScript file for editing. Find the key and value pair to overwrite, and replace the value with your custom text.

  5. Repeat the previous step until you have replaced all of the strings to change.

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

  7. Save and close the JavaScript file.

  8. Use the WebSphere Application Server Integrated Solutions Console, restart the application associated with the file that you have changed.

  9. Test your changes by clearing your browser cache, and then refreshing the browser.

  10. 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/webresources

      For 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.js
customizationDir/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.js
customizationDir/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.js
customizationDir/javascript/quickr/picker/nls/
language_code/picker.js
Calendar 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:

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

For a complete example, see Creating a simple profile data model and template customization.

  1. 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_name

    For 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.properties

    And to include a Slovakian version of the strings, you might include the following file:
    customization_dir/strings/com.example.resources_sk.properties

    The following sample string is contained in the properties file.

    label.vcard.encoding.cp943c=Japanese Encoding

  2. Register the resource bundle in LotusConnections-config.xml:

    1. Open a command window and start the wsadmin command-line tool as described in the topic, Starting the wsadmin client.

    2. Enter the following command to access the IBM Connections configuration file:
      execfile("<$WAS_HOME>/profiles/<DMGR>/config/bin_lc_admin/connectionsConfig.py")

    3. Enter the following command to check out the IBM Connections configuration file:
      LCConfigService.checkOutConfig(working_directory, cell_name)
      where:

      • 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.
      For example:

      LCConfigService.checkOutConfig("/temp", "foo01Cell01")

    4. From the temporary directory to which you just checked out the IBM Connections configuration files, open LotusConnections-config.xml in a text editor.

    5. Add the following line of code into the <resources> element block to register the resource bundle:

      <widgetBundle prefix=bundle_prefix name=bundle_name />

      ...where

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

      The following sample code is used to register the com.example.resources bundle:

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

    6. Save your changes to LotusConnections-config.xml.

    7. To check in the updated file, use the following command:
      LCConfigService.checkInConfig()

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

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

  2. Open the file and edit the string directly to make the required changes.

  3. Save your changes and close the file.

  4. 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/javascript

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

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

    1. Find com.ibm.lconn.core.web.resources_*.jar inside the deployed Common.ear file.

    2. Open the JAR file with a zip program.

    3. Extract the resources/SearchBar.js file to a location on your hard drive.

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

    1. Use a text editor, open the SearchBar.js file from the example in step 1.

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

    3. Copy SearchBar.js to the following directory:
      customizationDir/javascript/lconn/core/

      Ensure that you use the correct case in case-sensitive file systems.

  3. 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:

    1. Edit SearchBar.js to put an alert statement at the start of the file:

      alert("This file has been customized.");

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

  1. Download the following sample bundle:
    com.mycompany.example_1.0.0.jar

  2. Deploy the sample bundle.

    1. Locate your web resources provisioning directory for IBM Connections. The installer creates this directory at the following location:
      CONNECTIONS_HOME/data/shared/provision/webresources

      This directory contains many different JAR files, including at least one for each application, and utility bundles.

    2. Copy the sample bundle into the webresources directory.

    3. Restart the Common.ear file.

    4. Enter the following URL in your web browser:

      http://server/connections/resources/web/com.mycompany.example/readme.txt
      You should see the readme.txt file from the JAR in the resources/ folder display in the browser window.

  3. 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/

    1. Stop Common.ear.

    2. Add your new JavaScript, HTML, image, or CSS files into the JAR file in the resources/ directory.

    3. Restart Common.ear.

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

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

  5. Restart Common.ear to pick up the changes in the plugin.xml file.

  6. Change the name of the bundle.

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

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

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

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

    5. Restart Common.ear.

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

  1. Optional: Turn on the customization debugging capability. For more information, see Enabling and disabling customization debugging.

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

    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.

    • 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.
    For a list of the web application source directories that are packaged with IBM Connections, see Application WAR files and OSGi bundles.

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

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

  5. Save and close the .jsp file.

  6. To test your changes, refresh the web browser, and then access the page from the product.

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

  8. 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:

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

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

    3. Save your changes and then close the file.

    4. Synchronize all the nodes using the Integrated Solutions Console.

    5. Stop and restart the News application.

  • To edit the text strings used in the notification:

    1. 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/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 application-specific resources folder before moving to the shared strings in the shared resources folder.

    2. Save your changes and then close the files.

    3. Synchronize all the nodes using the Integrated Solutions Console.

    4. Stop and restart the News application.

  • To customize the images used in the notification:

    1. Locate the images in one of the following directories:

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

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

    3. Synchronize all the nodes using the Integrated Solutions Console.

    4. 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:

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

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

    3. Save your changes and then close the files.

    4. Synchronize all the nodes using the IBM WebSphere Application Server Integrated Solutions Console.

    5. Stop and restart the News application.

  • To use your own custom templates instead of the default templates:

    1. Create the templates by following the instructions provided in the FreeMarker documentation on this web page:
      http://freemarker.sourceforge.net/docs/index.html

      The Freemarker version currently used is 2.3.15.

    2. Save the templates in the following directory:

      app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/notifications/news

    3. Register the custom templates in the notification-config.xml file.

      1. 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/bin

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

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

        where:

        • 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:

          1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.

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

      3. Access the IBM Connections configuration files:

        execfile("connectionsConfig.py")

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

      5. Use a text editor, open the notification-config.xml file from the temporary directory to which you checked it out.

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

      7. Save your changes and close the notification-config.xml file.

      8. Check the configuration files back in :

        LCConfigService.checkInNotificationConfig("temp_dir","cell_name")

      9. To exit the wsadmin client, type exit at the prompt.

      10. Synchronize all the nodes using the Integrated Solutions Console.

      11. Stop and restart all the IBM Connections application servers.

  • To edit the text strings used in the email digest:

    1. Use a text editor, open the notification_language_code.properties files from one of the following directories and make your changes:

      • 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/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 application-specific resources folder before moving to the shared strings in the shared resources folder.

    2. Save your changes and then close the files.

    3. Synchronize all the nodes using the Integrated Solutions Console.

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

    1. Locate the images in the following directory:

      app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/resources/images

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

    3. Synchronize all the nodes using the Integrated Solutions Console.

    4. 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/resources

Table 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/resources
Saving 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:

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

    2. Save your changes and then close the files.

    3. Synchronize all the nodes using the IBM WebSphere Application Server Integrated Solutions Console.

    4. Synchronize all the nodes using the Integrated Solutions Console.

  • To edit the text strings used in the notifications:

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

    2. Save your changes and then close the files.

    3. Synchronize all the nodes using the Integrated Solutions Console.

    4. Stop and restart the News application.

  • To customize the images used in notifications:

    1. Locate the images in the following directory:

      app_server_root/profiles/dm_profile_root/config/cells/cell_name/LotusConnections-config/resources/images

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

    3. Synchronize all the nodes using the Integrated Solutions Console.

    4. Stop and restart the News application.

  • To customize notifications for a specific application:

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

    2. Save your changes and then close the files.

    3. Synchronize all the nodes using the Integrated Solutions Console.

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

  1. From the My Blogs page, click Sets for the blog you want to customize.

  2. Click Theme.

  3. Select a different theme for the blog. A preview window shows you what your blog will look like with the new theme.

  4. Click Save to apply the new theme.

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

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

  2. Click Theme.

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

  4. Click Templates. The templates for the current blog display.

  5. Click Edit to modify a template. See the examples for guidelines about how to make common customization changes.

  6. Save changes you make to the template.

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

  1. From the My Blogs tab, click Sets for the blog to add a logo to.

  2. Click Theme.

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

  4. Click Templates. The templates for the current blog display.

  5. Click the Edit icon next to the weblog template to open the template file for editing.

  6. 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"> 
    ]
    

  7. 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" />
#end

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

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

  2. Modify or add template files to create the desired look, layout, and content for your theme.

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

  4. 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:

    1. Add the com.ibm.lconn.blogs.strings.ui_xx.properties file to customization_dir/strings.

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

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

    1. Create a copy of the existing default theme.

      For example, to create a new corporate theme:

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

      2. Rename the new directory to corporateTheme. This gives you a directory path that looks like this one: installDir/customizationDir/theme/corporateTheme.

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

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

    3. Save your changes.

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

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

    2. Start the Communities Jython script interpreter.

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

      2. Check out the Communities configuration files :

        CommunitiesConfigService.checkOutConfig("working_directory", "cell_name")

        where:

        • 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()

        For example:

        CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommServerNode01Cell")

    3. Open communities-config.xml in a text editor.

    4. 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/

    5. Save the communities-config.xml file.

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

    1. Test your changes by refreshing the web browser.

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

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

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

    3. Save your changes and close the properties file.

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

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

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

    2. Start the Communities Jython script interpreter.

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

      2. Check out the Communities configuration files :

        CommunitiesConfigService.checkOutConfig("working_directory", "cell_name")

        where:

        • 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()

        For example:

        CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommServerNode01Cell")

    3. Open communities-config.xml in a text editor.

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

    5. Save the communities-config.xml file.

    6. 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:

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

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

      • <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.
      For example:

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

    3. 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:

    1. Define the JavaScript configuration options for the business card by following the steps in the topic, Integrating the Communities business card.

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

    • 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.
    To integrate the Profiles business card with your web application, complete the following steps:

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

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

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

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

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

    2. Use and modify one of the following code examples to render the card with your personal details.

      To add the inline 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>
      To add the pop-up card:

      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>

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

    4. 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:

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

        2. 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}&amp;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:

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

    2. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    3. Open LotusConnections-config.xml, and modify it to include the following attributes:

      Table 39. Third-party service reference attributes

      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.

      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&amp;q={email}&amp;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}&amp;searchBy=email"
        person_card_service_name_js_eval="generalrs.label_personcard_profilelink"/>

    4. 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:..>

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

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

    2. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    3. Open LotusConnections-config.xml in a text editor.

    4. 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&amp;q={email}&amp;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}&amp;searchBy=email"
        person_card_service_name_js_eval="generalrs.label_personcard_profilelink"/>

    5. Open the service-location.xsd file and delete the relevant service name.

    6. 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:

    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.

    • 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.html

      Quickr 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.
    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 enable a Lotus Quickr link on the business card, complete the following steps.

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

    2. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    3. 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:

      1. Change enabled="false" to enabled="true".

      2. Change ssl_enabled="false"> to ssl_enabled="true">.

      3. Change <sloc:static href="admin_replace" to <sloc:static href="http://quickrServer.mycompany.com:port".

      4. Change ssl_href="admin_replace"/> to ssl_href="https://quickrServer.mycompany.com:port"/>.

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

        1. Change person_card_service_url_pattern="/allfiles/people/{email}" to person_card_service_url_pattern="/search?#owner={userid}|{displayName}".

    4. 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:

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

    2. Use the wsadmin client to access and check out the Profiles configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Open the profiles-config.xml file using a text editor.

    4. Locate the <businessCardLayout> element, and specify the actions to include in the <actions> element. Each <action> element must contain the following attributes:

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

      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>

    5. Save your changes.

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

    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:

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

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

      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.

      For example, to add an attribute called spokenLangs, the configuration would look similar to the following configuration in the profiles-config.xml file:

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

    3. Save your changes to tdi-profiles-config.xml and then close the file.

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

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

    2. Use the wsadmin client to access and check out the Profiles configuration files.

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

    3. Use the following command to check out the widget configuration file:

      ProfilesConfigService.checkOutWidgetConfig("<working_directory>", "<cell_name>")

      ...where:

      • 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.
      For example:

      ProfilesConfigService.checkOutWidgetConfig("/wsadminoutput", "jdoe30Node02Cell")

    4. Save a copy of the widgets-config.xml file.

    5. Open the file in a text editor.

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

    7. Save your changes and check the widgets-config.xml file back in :

      ProfilesConfigService.checkInWidgetConfig()

    8. To exit the wsadmin client, type exit at the prompt.

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

    1. Save a copy of the was_profile_root\installedApps\cell_name\profiles.ear\lc.profiles.app.war\WEB-INF\validation.xml file.

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

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

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

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

    2. Use the wsadmin client to access and check out the Profiles configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

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

    4. Modify the file contents to include any custom HTML or fields.

    5. Save your changes.

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

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

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

    2. Use the wsadmin client to access and check out the Profiles business card configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Open the LotusConnections-config/profiles/templates/profileDetails.ftl file.

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

    5. Save your changes.

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

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

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

    2. Use the wsadmin client to access and check out the Profiles configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Open the LotusConnections-config/profiles/templates/businessCardInfo.ftl file.

    4. Modify the file contents to include any custom HTML or fields.

    5. Save your changes.

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

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

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

    2. Use the wsadmin client to access and check out the Profiles business card configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Open the LotusConnections-config/profiles/templates/searchResults.ftl file.

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

    5. Save your changes.

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

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

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

    2. Use the wsadmin client to access and check out the Profiles business card configuration files.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Open the LotusConnections-config/profiles/templates/profileEdit.ftl file.

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

    5. Save your changes.

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

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

    1. Open the profiles-config.xml file using a text editor.

    2. Locate the <template/> element for businessCardInfo.

    3. Modify the <templateDataModel/> to include the following: statement:

      <templateData>connection</templateData>

    4. Save your changes.

    5. Check in your configuration file update.

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

    1. Open the profiles-config.xml file using a text editor.

    2. Locate the <templateReloading/> element

    3. Edit the value to define how frequently (in seconds) the template processor should look for updates to the templates on disk.

    4. Save your changes.

    5. Check in the configuration update.

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

    1. Open the profiles-config.xml file using a text editor.

    2. Locate the <templateNlsBundles/> element

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

    4. Save your changes.

    5. Check in the configuration update.

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

    1. Open the profiles-config.xml file using a text editor.

    2. Locate the <template/> element for the business card or search results.

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

    4. Save your changes.

    5. Check in the configuration update.

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

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

    2. Start the Profiles Jython script interpreter.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

    3. Navigate to the temporary working directory specified in the previous step, and then open the profiles-config.xml file in a text editor.

    4. 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:

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

    2. Start the Profiles Jython script interpreter.

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

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

    3. Navigate to the temporary working directory specified in the previous step, and then open the profiles-config.xml file in a text editor.

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

    5. Navigate to the temporary working directory specified in the previous step, and then open profiles-types.xml in a text editor.

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

    7. Check in the configuration files using the wsadmin command ProfilesConfigService.checkInConfig().

    8. Restart the application.

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

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

    2. Start the Profiles Jython script interpreter.

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

      2. 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. 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()
        For example:

        • AIX or Linux:

          ProfilesConfigService.checkOutConfig("/opt/prof/temp","foo01Cell01")

        • Microsoft

          Windows:

          ProfilesConfigService.checkOutConfig("c:/prof/temp","foo01Cell01")

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

    4. 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:

    • 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
    Profile owners can edit these fields using their Edit Profile page. The fields are searchable.

    For related information and information about using the wsadmin client to make these changes, see Customize display using templates.

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

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

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

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

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

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

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

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

    9. Restart the server. View your changes on the profile page and profile edit form.

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

    11. Save a copy of the was_profile_root\installedApps\cell_name\profiles.ear\lc.profiles.app.war\WEB-INF\validation.xml file.

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

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

    14. Edit the properties file for each locale, and add the following key/value pair for localization:

      label.editprofile.highSchool=High School

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

    1. 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" />

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

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

    4. 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:

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

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

    5. Design your gadget so that the contents will have a width that does not exceed 500px.

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

    1. Open the Administration view.

    2. Click Add another widget to display the Add new widget form.

    3. For the Share dialog

      1. Select that the widget is based on theOpen Social Gadget specification.

      2. Select Trusted as the security type because the gadget will need access to the ibm.connections.sharedialog container feature

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

    4. Enter a name for the widget in the Widget Title field.

    5. Enter a short description of the widget in the Description field.

    6. Enter the web address for the XML widget descriptor in the URL Address field. This address must be an absolute web address.

    7. Enter the widget location in the Secure URL Address field. This address must be an absolute web address.

    8. The Icon URL web address does not apply to adding gadgets to the Share dialog so you can ignore it.

    9. The Icon Secure URL address does not apply to adding gadgets to the Share dialog so you can ignore it.

    10. The IBM Connections specific tags option does not apply to adding gadgets to the Share dialog so you can ignore it.

    11. The Display in the My Page view does not apply to adding gadgets to the Share dialog so you can ignore it.

    12. The Display in the Updates view does not apply to adding gadgets to the Share dialog so you can ignore it.

    13. The option Opened by default does not apply to adding gadgets to the Share dialog so you can ignore it.

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

    15. Select opensocial as a required application in the Prerequisites area.

    16. Click Save.

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

    registerCloseListener(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.

    1. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    2. 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","").

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

    1. 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\metrics
      for example:

      IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics

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

    3. 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 ">

    4. Save and close the file.

    5. Refresh the browser before viewing the report to verify the new label.

      There is no need to restart the Cognos BI Server.

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

    1. 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\metrics
      for example:

      IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics

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

    3. 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]]&#62;
          </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>    

    4. Save and close the file.

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

    • 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.
    T

    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.

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

      1. Open a browser and navigate to the Cognos dashboard using the following address: http://cognosserver.example.com:9083/cognos/servlet/dispatch/ext

      2. Log in to Cognos as the Cognos administrator.

      3. Click Public Folders > IBMConnectionsMetrics > Metrics > static.

      4. In the Name column, locate the job called jobtemplate and click its Set properties icon.

      5. Click the Job tab.

      6. Review the list of reports; if you see a name matching the planned report, choose a different name for the new report.

      7. Click Cancel and exit the job.s properties page.

    2. Open Cognos Report Studio:

      1. Return to the Cognos dashboard.

      2. Click Launch > Report Studio.

      3. When prompted to select a data package, select IBMConnectionsMetrics > Metrics to create a report that queries the PowerCube containing Metrics data.

    3. In the Report Studio Welcome window, click Create a new report or template.

    4. Select a report type:

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

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

      3. Click OK.

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

      1. Click the Source tab.

      2. In the packages list, expand the METRICS_TRX_CUBE datasource.

      3. Select EVENT_COUNT and drag it to the Default measure (y-axis) area of the chart.

    6. 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:

      1. Return to the METRICS_TRX_CUBE datasource.

      2. Expand SOURCE and select the SOURCE hierarchy; drag it to the Categories (x-axis) area of the chart.

      3. Click All Members to begin by including the complete list of categories.

      4. On the Categories (x-axis) area of the chart, click <#SOURCE#> tag.

      5. In the Properties window, click the Edit button for the "Set Definition" property.

      6. In the Set Definition window, right-click the SOURCE hierarchy and select New > Exclude.

      7. In the Exclude window, expand the METRICS_TRX_CUBE datasource.

      8. Select SOURCE in the Available members list and click the right-arrow icon to copy it to the excluded Members list.

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

      10. Click OK.

      Begin with no categories and include only the categories you want in the report:

      1. Return to the METRICS_TRX_CUBE datasource.

      2. Expand SOURCE and select the SOURCE hierarchy.

      3. Expand Members and select SOURCE.

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

      5. Click OK.

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

      1. Expand the METRICS_TRX_CUBE > EVENT measure.

      2. Expand Members > EVENT.

      3. Select UPDATE and drag it to the Series area of the chart.

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

    9. Click Run > Run Report - HTML to test the report by viewing it in the Cognos Viewer; then close the viewer when ready to proceed.

    10. Determine the URL for the new report so you can add it to the Metrics user interface:

      1. Return to the Cognos dashboard.

      2. Navigate to the location where you saved the report, and select the new report.

      3. Click the Set properties icon .

      4. In the Set properties window, click the General tab.

      5. On the General tab, click View the search path, ID and URL.

      6. In the View the search path, ID and URL window,

      7. Copy the entire URL from the Default action url field.

      8. Click Close.

      9. Leave the Cognos dashboard open so you can return to it in step 11.

    11. Modify the report URL and add it to the Metrics user interface:

      1. Paste the copied URL into a text editor.

      2. 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=true 
        becomes:

         /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 

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

    12. (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.

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

      2. Click Public Folders > IBMConnectionsMetrics > Metrics > static.

      3. In the Name column, locate the job called jobtemplate and click its Set properties icon.

      4. Click the Job tab.

      5. Click Add.

      6. Locate the new report in the Available entries list and click the right-arrow icon to add the report to the Selected entries list.

      7. Click OK.

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

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

      1. Open a browser and navigate to the Cognos dashboard using the following address: http://cognosserver.example.com:9083/cognos/servlet/dispatch/ext

      2. Log in to Cognos as the Cognos administrator.

      3. Click Public Folders > IBMConnectionsMetrics > Metrics > static.

      4. In the Name column, locate the job called jobtemplate and click its Set properties icon.

      5. Click the Job tab.

      6. Review the list of reports; if you see a name matching the planned report, choose a different name for the new report.

      7. Click Cancel and exit the job.s properties page.

    2. Open Cognos Report Studio:

      1. Return to the Cognos dashboard.

      2. Click Launch > Report Studio.

    3. In the Report Studio Welcome window, click Create a new report or template.

    4. In the New window, select Blank report, and then click OK.

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

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

    7. When the report is complete, determine its URL so you can add the report to the Metrics user interface:

      1. Return to the Cognos dashboard.

      2. Navigate to the location where you saved the report, and select the new report.

      3. Click the Set properties icon .

      4. In the Set properties window, click the General tab.

      5. On the General tab, click View the search path, ID and URL.

      6. In the View the search path, ID and URL window,

      7. Copy the entire URL from the Default action url field.

      8. Click Close.

    8. Modify the report URL for use within the Metrics user interface:

      1. Paste the copied URL into a text editor.

      2. 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=true 
        becomes:

         /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 

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

    1. Create a blank report as described in Create a blank report from the PowerCube model.

    2. Click the Toolbox tab.

    3. In the Toolbox window, select the Table object and drag the it to the report.s layout.

    4. In the Insert Table dialog box, specify values in the Number of rows and Number of columns fields, and then click OK.

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

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

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

    1. Create a blank report as described in Create a blank report from the PowerCube model.

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

      1. Click the Toolbox tab.

      2. In the Toolbox window, select the Chart object and drag it to the design area.

      3. In the Insert Chart dialog box, select Line from the list of chart styles, select the Line with markers icon; then click OK.

    3. Select the Measure to display on the Y-axis:

      In this example, the measure is EVENT_COUNT.

      1. Click the Sources tab.

      2. In the packages list, expand the METRICS_TRX_CUBE datasource.

      3. In the Measures list, select EVENT_COUNT; drag it to the Default measure (y-axis) area of the chart.

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

      1. Return to the METRICS_TRX_CUBE datasource and expand the DATE dimension.

      2. Expand Members > DATE.

      3. Select 2010 and drag it to the Categories (x-axis) area of the chart.

      4. Select 2011 and drag it to the Categories (x-axis) area of the chart, placing it after 2010.

      5. Select 2012 and drag it to the Categories (x-axis) area of the chart, placing it after 2011.

    5. Select the data series:

      In this example, the data series is the type of event being counted: the CREATE.

      1. Return to the METRICS_TRX_CUBE datasource and expand the EVENT dimension.

      2. Expand Members > EVENT.

      3. Select CREATE and drag it to the Series area of the chart.

    6. Click Save to save the updated report.

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

    1. Create a blank report as described in Create a blank report from the PowerCube model.

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

      1. Click the Toolbox tab.

      2. In the Toolbox window, select the Crosstab object and drag it to the design area.

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

      1. Click the Sources tab.

      2. In the packages list, expand the METRICS_TRX_CUBE datasource, and then expand the DATE dimension.

      3. Expand Members > DATE.

      4. Select 2010 and drag it to the Rows area of the crosstab.

      5. Select 2011 and drag it to the Rows area of the crosstab, placing it after 2010.

      6. Select 2012 and drag it to the Rows area of the crosstab, placing it after 2011.

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

      1. Return to the METRICS_TRX_CUBE datasource.

      2. Expand Members > EVENT, and then expand the EVENT dimension.

      3. Select CREATE and drag it to the Columns area of the crosstab.

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

      1. Return to the METRICS_TRX_CUBE datasource.

      2. Expand Measures and select EVENT_COUNT; then drag it to the Measures area of the crosstab.

    6. Click Save to save the updated report.

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

    1. Create a blank report as described in Create a blank report from the PowerCube model.

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

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

      1. Click View > Queries to display the queries used in the report.

      2. Double-click Query1 to open the query definition window.

      3. In the Properties window, expand Data and locate the Query attribute.

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

      1. Click the Toolbox tab.

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

      3. In the Data Item Expression window, type tuple(...) in the Expression field.

      4. Click the Sources tab.

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

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

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

      8. Click OK to save the expression and close the Data Item Expression window.

    5. Rename the new data item so you can easily find and work with it later:

      1. Click the data item (the tuple) that you just created.

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

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

    6. Modify the trend chart to use the new NumOfNewFiles data item:

      1. Click View > Report Pages.

      2. Double-click Page1 to return to the base report.

      3. In the chart, delete the CREATE date item from the Series area.

      4. Click the Data Items tab.

        This tab appears now that you have a data item defined.

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

    7. Click Save to save the updated report.

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

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

    2. 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]]&#62;
              </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]]&#62;
             </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>  

    3. Save and close the file.

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

    1. 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\metrics
      for example:

      IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics

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

    3. 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]]&#62;
         </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]]&gt;
            </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]]&gt;
             </link>
          </entry>
      
      </entry>

    4. Save and close the file.

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

    1. 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\metrics
      for example:

      IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\cognos01\LotusConnections-config\metrics

    2. 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]]&#62;
         </link>
       </entry> 

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

    4. 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]]&gt;
            </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]]&gt;
             </link>
         </entry>
      
      </entry>

    5. Save and close the file.

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

    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.

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

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

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

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

        • 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.
        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:

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

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

      3. After updating the TAI properties provider_1.name and provider_1.filter, restart the WebSphere Application Server.

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

      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
      Refer to Configuring SPNEGO on WebSphere Application Server.


    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.

    1. To register an arbitrary client:

      1. Start wsadmin.

        ./wsadmin.sh -lang jython -user wasadmin -password passw0rd

      2. Load oauth admin commands

        execfile('oauthAdmin.py')

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

      4. 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')

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

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

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

    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

    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.

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

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

    1. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    2. From the temporary directory to which you just checked out the IBM Connections configuration files, open LotusConnections-config.xml in a text editor.

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

    4. 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:

      RESPMOD

      Represents McAfee virus scanning software

      AVSCAN

      Represents Symantec virus scanning software
      Or add the ICAP response modification service for the virus scanning software to support.

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

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

    7. Save your changes to LotusConnections-config.xml.

    8. 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:

    1. Open the Integrated Solutions Console of the WebSphere Application Server hosting the application for which you want to restrict access.

    2. Expand Applications > Application Types, and then select WebSphere enterprise applications.

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

    4. Click Security role to user/group mapping.

    5. Select the check box in the Select column next to the reader role.

    6. Click Map Special Subjects > All Authenticated in Application's Realm.

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

    8. Click OK. Click Apply, and then click OK.

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

    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.

    To set your SSO domain name, complete the following steps:

    1. Log in to the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.

    2. Select Security > Global security > Web and SIP security > Single sign-on (SSO).

    3. Enter a value for the SSO Domain name.

    4. Click Apply and then click Save.

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

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

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

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

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

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

    3. Import your IBM HTTP Server certificate into the Tivoli Access Manager keystore. To import the certificate, complete the following steps:

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

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

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

      4. Under Key database content, select Personal Certificates.

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

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

      7. Under Key database content, select Signer Certificates.

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

      9. Click Key Database File - Close to save your changes to the WebSEAL pdsrv.kdb certificate file and close the file.

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

    4. Use the exported LTPA key to configure the transparent path junctions in Tivoli Access Manager. To do so, complete the following steps:

      1. Copy the LTPA keys that you exported in Step 1 to the Tivoli Access Manager server.

        For example: C:\WAS7_ltpa.keys

      2. Open the pdadmin command line utility, which is installed as part of the Tivoli Access Manager runtime package.

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

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

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

    7. Attach default ACLs to resources that are protected by form-authentication.

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

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

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

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

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

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

    9. Specify a dynamic URL pattern to support the Blogs application and mail notification:

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

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

      3. To allow large Blogs posts, open the webseald.conf file and add the following parameter:

        dynurl-allow-large-posts = yes

      4. To enable the uploading of PDF files, add the following parameter to the webseald.conf file:

        suppress-dynurl-parsing-of-posts = yes

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

    11. (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

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

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

    14. Update the values for the dynamicHosts and interService URL attributes in the LotusConnections-config.xml configuration file:

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

        • 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()

        For example: LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

      2. Update the dynamicHosts values by running the following commands:

        1. Enable dynamicHosts:

          LCConfigService.updateConfig("dynamicHosts.enabled","true")

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

      3. (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

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

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

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

    17. Save and close the httpd.conf file.

    18. Restart IBM HTTP Server.

    19. (Do not complete this step for Tivoli Access Manager with SPNEGO) Add a Tivoli Access Manager authenticator property by editing LotusConnections-config.xml.

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

      2. Configure the custom authenticator to support server-to-server authentication for Tivoli Access Manager:

        LCConfigService.updateConfig("customAuthenticator.name",

        "TAMAuthenticator")

      3. Keep the file open until you have completed the next step.

    20. (Do not complete this step for Tivoli Access Manager with SPNEGO) Configure the cookie timeout value for IBM Connections:

      1. Locate the CookieTimeout attribute in LotusConnections-config.xml. If the attribute is not present, add it to the <customAuthenticator name="TAMAuthenticator"> element.

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

      3. Save your changes.

      4. Check LotusConnections-config.xml back in by running the following command:

        LCConfigService.checkInConfig()

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

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

    23. 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:

    1. Download and apply the Unrestricted JCE policy files:

      1. Go to the J2SE 5 SDK Security information web page.

      2. Authenticate with your universal IBM user ID and password.

      3. Download the Unrestricted JCE Policy files for SDK for all newer versions package.

      4. Extract the files from the downloaded package.

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

      6. Copy the new jar files from the extracted package to the same directory, overwriting any existing files.

    2. Create agents on the SiteMinder Policy Server, including a Web Agent for IBM HTTP Server and an Application Server Agent for WebSphere Application Server.

      1. Open the SiteMinder Administration console.

      2. Right-click Agents and select Create Agent.

      3. Enter details of the Name and Description of the Web Agent for IBM HTTP Server.

      4. Repeat these steps for the Application Server Agent.

    3. 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:

      1. Configure the Web Agent for IBM HTTP Server:

        1. Right-click Apache Default Sets Agent and select Duplicate Configuration Object.

        2. Enter the Name and description of the Agent Configuration Object.

        3. 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"

      2. Under the System tab, update the Agent Configuration Object with the following value: FCCCompatMode - NO

      3. Configure the Application Server Agent:

        1. Right-click Apache Default Sets Agent and select Duplicate Configuration Object.

        2. Enter the Name and description of the Agent Configuration Object.

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

    4. Specify your SiteMinder Authentication Scheme configuration:

      1. Open the SiteMinder Administration Console and navigate to the Authentication Scheme Properties dialog box.

      2. From the Authentication Scheme type list, select HTML Form template.

      3. Clear the Use Relative Target check box.

      4. Enter the URL of your IBM Connections HTTP server in the web Server Name field.

    5. On the SiteMinder Policy Server, create a domain for the IBM HTTP Server web agent.

    6. Create protected realms under the IBM HTTP Server Web Agent domain:

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

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

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

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

      1. In the SiteMinder Administration Console, click View and select Agent Types.

      2. Select Agent Types in the Systems pane.

      3. Double-click Web Agent in the Agent Type list.

      4. In the Agent Type Properties dialog box, click Create.

      5. Enter Delete in the New Agent Action dialog box and click OK.

      6. Enter Head in the New Agent Action dialog box and click OK.

      7. Click OK again to save the new action.

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

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

    10. Add the new rules to the new policy.

    11. 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/

    12. Map the Reader role in the Activities and Wikis applications All Authenticated in Application's Realm. See Roles.

    13. On the SiteMinder Policy Server, create a domain for the Application Server Agent.

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

    15. Set the timeout value of the session for each realm.

      1. In the SiteMinder Policy Server, open the Realm Dialog and click Session.

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

    16. Install the Web Agent on IBM HTTP Server:

      1. Download the latest version of the Web Agent from the CA website.

      2. Install the Web Agent. For instructions, go to the SiteMinder BookShelf.

      3. When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.

    17. Install the Application Server Agent on your WebSphere nodes:

      1. Download the latest version of the Application Server Agent from the CA website.

      2. Install the Application Server Agent on each node in your IBM Connections deployment. For instructions, see the SiteMinder Agent for WebSphere Agent Guide.

      3. When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.

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

    19. Configure Trust Association Interceptor on WebSphere Application Server.

      1. From the administrative console for WebSphere Application Server, click Security > Global security.

      2. Under Web and SIP security, click Trust association.

      3. Click Enable Trust Association and then click Save.

      4. Click Interceptors.

      5. Delete any unused interceptors.

        Do not delete the OAuth interceptor.

      6. Click New and enter the following name for the new interceptor:

        com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor

      7. Click OK and then click Save.

      8. Restart WebSphere Application Server.

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

    21. 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>
      SSLDisable

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

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

    23. Add a SiteMinder authenticator property to the IBM Connections configuration by editing LotusConnections-config.xml.

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

      2. Update the custom authenticator values by running the following commands:

        1. Configure the custom authenticator to support server-to-server authentication for SiteMinder:

          LCConfigService.updateConfig("customAuthenticator.name",

          "SiteMinderAuthenticator")

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

      3. Check LotusConnections-config.xml back in by running the following command:

        LCConfigService.checkInConfig()

    24. Restart your IBM Connections deployment.

      1. Stop IBM Connections servers, node agents, and deployment manager.

      2. Start the deployment manager and nodes.

      3. Allow time for the nodes to synchronize, and for the updated LotusConnections-config.xml file to be copied to each node.

      4. 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:

    1. On the server where IBM Connections is installed, enable SSO:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator, expand Security > Global security.

      2. Expand Web and SIP security and then click Single sign-on (SSO).

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

    2. On the node where Lotus Quickr is installed, complete the following steps:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator, and click Security > Secure administration, applications, and infrastructure.

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

      3. Click Export keys

    3. On each node where IBM Connections is installed:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator, and click Security > Global security > LTPA

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

      3. Click Import keys.

    4. On each node where IBM Connections is installed:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator.

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

      3. Click Export keys.

    5. On the node where Lotus Quickr is installed, complete the following steps:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator and click Security > Secure administration, applications, and infrastructure > LTPA.

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

      3. Click Import keys.

    6. 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:

    1. Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.

    2. Click Security > Global security.

    3. Select Federated Repositories from the Available realm definitions field and then click Configure.

    4. Enter the realm name of the LDAP server in the Realm name field. For example: enterprise.example.com:389.

    5. Click Apply and then click Save.

    6. Synchronize the nodes.

    7. Restart the servers in your IBM Connections deployment.

    8. Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.

    9. Click Security > Global security.

    10. In the Authentication mechanisms and expiration area, expand Web and SIP security and click LTPA.

    11. Enter your IBM Connections domain name in the Domain name field, ensuring that you add a dot (.) before the domain name.

    12. Select the check boxes for Interoperability Mode and Web inbound security attribute propagation.

    13. Restart your IBM Connections applications.

    14. Verify that you can switch between the applications without needing to authenticate more than once.

    15. Log into the WebSphere Application Server Integrated Solutions Console on the Deployment Manager.

    16. Click Security > Global security.

    17. In the Authenticaion area, click LTPA.

    18. In the Password and Confirm password fields, enter the password that protects the exported key.

    19. Enter the file name of the key file to generate in the Fully qualified key file name field.

    20. Click Export keys.

    21. Click Apply and then click Save.

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

    23. 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:

        1. In the user Person document, click Administration.

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

        1. Open the Directory Assistance document for the LDAP directory. Alternatively, create a directory assistance database and configure the Domino server to use this database.

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

    24. Configure Domino Server to use the new Web SSO Configuration Document:

      1. In Domino Administrator, click Files and then open the server.s Address Book (the names.nsf file).

      2. Select the Servers view and open the server to configure.

      3. Navigate to Internet Protocols > Domino Web Engine.

      4. Change to Edit mode.

      5. Select the new Web SSO Document in the Web SSO Configuration box.

      6. Save your changes.

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

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

    2. Log in to the Welcome page.

    3. Click Security > Global security.

    4. Select Federated Repositories from the Available realm definitions field, and then click Configure.

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

    6. Click Apply and then click Save to save this setting.

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

      1. Navigate to Users and Groups > Administrative User Roles.

      2. Select all user roles and click Remove.

      3. Click Add.

      4. In the Roles field, click Administrator.

      5. In the User field, enter the user name to which you want to grant administrative privileges.

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

      7. To map other users, repeat the previous step.

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

    8. Synchronize the nodes and then restart the servers:

      1. Log into the Integrated Solutions Console for the Deployment Manager.

      2. Expand System administration > Nodes. Select the name of the node that you updated and click Full Resynchronize.

      3. Select Servers > Clusters. Select the check box for the cluster you want to restart and click Stop.

      4. Select System administration > Node agents. Select the check boxes for the nodes to restart and click Restart.

      5. Stop and restart the Deployment Manager.

      6. Log into the Integrated Solutions Console again.

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

    1. Map an Active Directory account to administrative roles:

      1. Log in to the WebSphere Application Server Integrated Solution Console on the Deployment Manager.

      2. Click Users and groups > Administrative user roles > Add and select Admin Security Manager.

      3. Enter the Active Directory account name in the Search string field and click Search.

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

      5. Click OK.

      6. Click Add and select Administrator

      7. Enter the Active Directory account name in the Search string field and click Search.

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

      9. Click OK.

      10. Click Save.

    2. Change J2C authentication:

      1. Click Security > Bus security > ConnectionsBus.

      2. Under Additional Properties, click Security > Users and groups in the bus connector role > New.

      3. In the SIB Security Resource Wizard window, click Users, enter the Active Directory account in the Search pattern field, and click Next.

      4. Select the check box for the account name and click Next.

      5. If you are satisfied with the summary information, click Finish.

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

    3. Update the messaging bus configuration. Complete the steps in the Updating the messaging bus configuration when the connectionsAdmin user ID changes topic.

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

    5. Modify the runtime user for the Search application:

      1. Click Applications > Application Types > WebSphere enterprise applications > Search.

      2. Under Details Properties, click User RunAs Roles.

      3. Select the Admin check box.

      4. Enter the new user name and password.

      5. Click Apply.

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

    6. (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:

    1. 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 /resync

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

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

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

    4. Create a new account for IBM Connections by accessing the Active Directory Users and Computers settings.

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

    6. Click Next.

    7. Type a password for the logon name in the Password field.

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

    9. 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 Passw0rd1

      For 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

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

    11. 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:

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

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

        where:

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

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

      4. 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 :

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

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

    1. Log on to the WebSphere Application Server Integrated Solutions Console on the Deployment Manager and select Security > Global Security.

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

    3. Select Trim Kerberos realm from principal name if it is not already selected.

    4. Select Enable delegation of Kerberos credentials if it is not already selected.

    5. Click OK and then click Save.

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

    7. Set the SPNEGO filter:

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

      2. Select Trim Kerberos realm from principal name.

      3. Select Enable delegation of Kerberos credentials.

      4. Click OK and then click Save.

    8. On the SPNEGO Web authentication page, complete the following steps:

      1. Select Dynamically update SPNEGO.

      2. Select Enable SPNEGO.

      3. Select Allow fall back to application authentication mechanism.

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

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

      6. Click Apply.

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

        1. Select Applications > Application Types > WebSphere enterprise applications.

        2. Click the link to the first IBM Connections application in the Enterprise Applications table.

        3. In the Detail Properties area, click Security role to user/group mapping.

        4. Select the reader Role, click Map Special Subjects, and select Everyone.

        5. Click OK and then click Save.

        6. Repeat steps b-e for the remaining IBM Connections applications in the Enterprise Applications table.

      • Force users to log in to access IBM Connections:

        1. Select Applications > Application Types > WebSphere enterprise applications.

        2. Click the link to the first IBM Connections application in the Enterprise Applications table.

        3. In the Detail Properties area, click Security role to user/group mapping.

        4. Select the reader Role, then click Map Special Subjects and select All Authenticated in Application's Realm.

        5. Click OK and then click Save.

        6. Repeat steps b-e for the remaining IBM Connections applications in the Enterprise Applications table.

    10. Remove interceptor classes:

      1. Select Security > Global Security.

      2. Expand Web and SIP security and click Trust association > Interceptors.

      3. Select the check boxes for the following two classes:

        • com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl

        • com.ibm.ws.security.TAMTrustAssociationInterceptorPlus

      4. Click Delete and then click Save.

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

      1. Select Security > Global Security > Custom properties > New.

      2. Enter the following name and value pair:

        Name

        com.ibm.websphere.security.performTAIForUnprotectedURI

        Value

        false

      3. Click OK and then click Save.

    12. Click Global Security. In the Authentication area, click LTPA if it is not already selected. Click Save.

    13. Synchronize all the nodes in your deployment.

    14. Stop and restart WebSphere Application Server:

      1. Stop all instances of WebSphere Application Server that host your IBM Connections applications.

      2. Stop all node agents.

      3. Restart the Deployment Manager.

      4. Restart all the node agents.

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

      1. From the Internet Explorer menu, select Tools > Internet Options and then click the Security tab.

      2. Click the Local intranet icon and then click Sites.

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

      4. 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>".

      5. Click OK to save the change and return to the main Security page.

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

      7. Click the Advanced tab, scroll to find Security, and then select the Enable Integrated Windows Authentication check box. Click OK to save the change.

      8. Restart the web browser to apply the configuration changes.

    • Mozilla Firefox:

      1. Open Firefox and type about:config into the location bar.

      2. Type network.n into the Filter field and double-click network.negotiate-auth.trusted-uris.

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

      4. Click OK to save the change.

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

      6. 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:

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

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

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

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

        1. Click Start > Programs > Administrative Tools > Services.

        2. Right-click on Access Manager WebSEAL-default and select Properties.

        3. Click Log On and then click This account.

        4. Enter the details of the user account and password that you created in Step 1.

        5. Click OK to save your changes.

      3. Grant administrator privileges for the local system to the account that you created in step 1.

    3. Enable SPNEGO for WebSEAL:

      1. Stop the WebSEAL server.

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

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

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

    1. Download and apply the Unrestricted JCE policy files:

      1. Go to the J2SE 5 SDK Security information web page.

      2. Authenticate with your universal IBM user ID and password.

      3. Download the Unrestricted JCE Policy files for SDK for all newer versions package.

      4. Extract the files from the downloaded package.

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

      6. Copy the new jar files from the extracted package to the same directory, overwriting any existing files.

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

      1. Open the SiteMinder Administration console.

      2. Right-click Agents and select Create Agent.

      3. Enter details of the Name and Description of the Web Agent for IBM HTTP Server.

      4. Repeat these steps for the Web Agent for IIS.

      5. Repeat these steps for the Application Server Agent.

    3. 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:

      1. Configure the Web Agent for IBM HTTP Server:

        1. Right-click Apache Default Sets Agent and select Duplicate Configuration Object.

        2. Enter the Name and description of the Agent Configuration Object.

        3. 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"

      2. Under the System tab, update the Agent Configuration Object with the following value: FCCCompatMode - NO

      3. Configure the Web Agent for IIS:

        1. Right-click IIS Default Sets Agent and select Duplicate Configuration Object.

        2. Enter the Name and description of the Agent Configuration Object.

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

      4. Configure the Application Server Agent:

        1. Right-click Apache Default Sets Agent and select Duplicate Configuration Object.

        2. Enter the Name and description of the Agent Configuration Object.

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

    4. Specify your SiteMinder Authentication Scheme configuration:

      1. Open the SiteMinder Administration Console and navigate to the Authentication Scheme Properties dialog box.

      2. From the Authentication Scheme type list, select Windows Authentication template.

      3. Clear the Use Relative Target check box.

      4. Enter the URL of your IIS server in the web Server Name field.

      5. Complete the User DN Lookup field with the appropriate information for your domain. For example, (sAMAccountName=%{UID}).

    5. On the SiteMinder Policy Server, create a domain for the IBM HTTP Server web agent.

    6. Create protected realms under the IBM HTTP Server Web Agent domain:

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

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

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

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

      1. In the SiteMinder Administration Console, click View and select Agent Types.

      2. Select Agent Types in the Systems pane.

      3. Double-click Web Agent in the Agent Type list.

      4. In the Agent Type Properties dialog box, click Create.

      5. Enter Delete in the New Agent Action dialog box and click OK.

      6. Enter Head in the New Agent Action dialog box and click OK.

      7. Click OK again to save the new action.

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

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

    10. Add the new rules to the new policy.

    11. 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/

    12. On the SiteMinder Policy Server, create a domain for the Application Server Agent.

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

    14. On the SiteMinder Policy Server, create a domain for the IIS Server Agent.

    15. 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 /

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

    17. Set the timeout value of the session for each realm.

      1. In the SiteMinder Policy Server, open the Realm Dialog and click Session.

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

    18. Install the Web Agent on IBM HTTP Server:

      1. Download the latest version of the Web Agent from the CA website.

      2. Install the Web Agent. For instructions, go to the SiteMinder BookShelf.

      3. When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.

    19. Install the Web Agent on IIS:

      1. Download the latest version of the Web Agent from the CA website.

      2. Install the Web Agent. For instructions, go to the SiteMinder BookShelf.

      3. When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.

    20. Install the Application Server Agent on your WebSphere nodes:

      1. Download the latest version of the Application Server Agent from the CA website.

      2. Install the Application Server Agent on each node in your IBM Connections deployment. For instructions, see the SiteMinder Agent for WebSphere Agent Guide.

      3. When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.

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

    22. Configure Trust Association Interceptor on WebSphere Application Server.

      1. From the administrative console for WebSphere Application Server, click Security > Global security.

      2. Under Web and SIP security, click Trust association.

      3. Click Enable Trust Association and then click Save.

      4. Click Interceptors.

      5. Delete any unused interceptors.

        Do not delete the OAuth interceptor.

      6. Click New and enter the following name for the new interceptor:

        com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor

      7. Click OK and then click Save.

      8. Restart WebSphere Application Server.

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

    24. 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>
      SSLDisable

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

    25. Configure SiteMinder to use HTTP or HTTPS communications:

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

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

      3. 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"

      4. Comment out every other line in the LocalConfig.conf file. Save and close the file.

      5. Add the virtual host to WebSphere Application Server:

        1. In the Integrated Solutions Console on the Deployment Manager, click Environment > Virtual Hosts > default_host > Host Aliases > New.

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

      6. Add the interservice URL for the new virtual host to LotusConnections-config.xml:

        1. Check out LotusConnections-config.xml. For information about editing configuration files, see the Changing common configuration property values topic.

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

        3. Save and check in the file.

    26. Restart IBM HTTP Server, the Deployment Manager, and the nodes.


    What to do next

    Verify the configuration is working correctly:

    1. Log in to your Windows client system.

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

    1. Access the common AJAX proxy configuration template file:

      1. 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\bin

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

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

        where:

        • 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:

          1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.

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

      3. Access the configuration file:

        execfile("connectionsConfig.py")

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

    2. From the temporary directory to which you checked out the configuration files, open the proxy-config.tpl file in a text editor.

    3. 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/>.

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

    5. You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.

      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.
      For example:

      <proxy:meta-data>
        <proxy:name>maxconnectionsperhost</proxy:name>
        <proxy:value>20</proxy:value>
      </proxy:meta-data>  

    6. Save and close the file.

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

    8. 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:

    1. 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-config

      Find 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

    2. Check out the copied configuration file .

      1. 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\bin

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

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

        where:

        • 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:

          1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.

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

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

      4. 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()

    3. Navigate to the temporary directory specified in the previous step, and then open the custom template file in a text editor.

    4. 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/>.

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

    6. You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.

      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.
      For example:

      <proxy:meta-data>
        <proxy:name>maxconnectionsperhost</proxy:name>
        <proxy:value>20</proxy:value>
      </proxy:meta-data>  

    7. Save and close the file.

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

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

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

        1. 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\bin

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

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

          where:

          • 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:

            1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.

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

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

    3. From the temporary directory to which you checked out the files, open the proxy configuration template file in a text editor.

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

    5. Save and close the file.

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

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

    1. To access the common AJAX proxy configuration template file:

      1. 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\bin

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

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

        where:

        • 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:

          1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration > Deployment Manager.

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

      3. Access the configuration file:

        execfile("connectionsConfig.py")

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

    2. From the temporary directory to which you checked out the configuration files, open the proxy-config.tpl file in a text editor.

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

    4. Save and close the file.

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

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

    1. Start the wsadmin client.

    2. Access and check out the proxy-ecm-config.tpl file:

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

      2. Enter the following command to check out the proxy-ecm-config.tpl file:

        LCConfigService.checkOutProxyEcmConfig("working_directory","cell_name")

        where:

        • 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutProxyEcmConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutProxyEcmConfig("c:/temp","foo01Cell01")

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

    4. You can optionally specify values for the following proxy:meta-data properties. Add any custom configurations before these proxy:meta-data elements.

      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.
      For example:

      <proxy:meta-data>
        <proxy:name>maxconnectionsperhost</proxy:name>
        <proxy:value>20</proxy:value>
      </proxy:meta-data>  

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

    6. Enter the following command to check in your changes: LCConfigService.checkInProxyEcmConfig("working_directory","cell_name")

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

    1. Edit LotusConnections-config.xml.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

      3. Open LotusConnections-config.xml in a text editor.

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

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

      6. Repeat Steps d and e to apply different filtering levels to different applications, and then save and close the configuration file.

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

    2. Synchronize the nodes using the Integrated Solutions Console for the network deployment system.

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

    1. Edit LotusConnections-config.xml.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

      3. Open LotusConnections-config.xml in a text editor.

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

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

      6. Repeat Steps d and e to apply different filtering levels to different applications, and then save and close the configuration file.

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

    2. Synchronize the nodes using the Integrated Solutions Console for the network deployment system.

    3. 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:

    • If you choose to enable single sign-on, configure HTTP-only cookies. To do so:

      1. Open the WebSphere Application Server Integrated Solution Console.

      2. Expand Security, and then select Global security.

      3. Click Custom properties.

      4. Click New to add a property, and then add the following values to the fields:

        Name

        com.ibm.ws.security.addHttpOnlyAttributeToCookies

        Value

        true

      5. 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.
    See Specifying a separate file download domain for information about how to create the subdomain.


    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.

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

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

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

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

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

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

    7. Add the rule in the previous step to any virtual host sections of the configuration file.

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

    1. Start the wsadmin client. See Starting the wsadmin client for details.

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

    3. 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")

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

    1. Use the wsadmin client to access and check out the IBM Connections configuration files.

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

      2. Enter the following command to check out the IBM Connections configuration files:

        LCConfigService.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 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()
        For example:

        • AIX or Linux:LCConfigService.checkOutConfig("/opt/temp","foo01Cell01")

        • Microsoft

          Windows:LCConfigService.checkOutConfig("c:/temp","foo01Cell01")

    2. Enter the following command:

      LCConfigService.updateConfig("force.conf.comm.enabled", "true")

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

    4. Optional: To secure session cookies, complete the following steps:

      1. Log in to the WebSphere Application Server Integrated Solutions Console of the server hosting your IBM Connections applications as the administrator.

      2. Expand Servers > Server Types, and then select WebSphere application servers.

      3. Click the server hosting IBM Connections from the list of server names.

      4. Click Session Management, and then click Enable cookies.

      5. Select the Restrict cookies to HTTPS sessions check box.

      6. Click Apply, and then click OK.

    5. Optional: To secure LTPA tokens, complete the following steps:

      1. From the WebSphere Application Server Integrated Solutions Console, expand Security, and then click Global security.

      2. Expand Web and SIP security, and then click single sign-on (SSO).

      3. Select the Requires SSL check box.

      4. 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 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.
    The plug-in provides the following features:

    • 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:

    1. Download the plug-in from the IBM Connections catalog web site:

      https://greenhouse.lotus.com/catalog

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

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

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

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

    1. From the Sametime client on which you want to implement the features, select Tools > Plug-Ins > Install Plug-ins from the menu.

    2. On the Install/Updates page, choose Search for new features to install, and then click Next.

    3. Select New Remote Site.

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

    5. Click OK.

    6. In the Updates window, expand the site you selected, and then expand the IBM Connections folder.

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

      • 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 Next.

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

    9. Review the features to be installed, and then click Finish.

    10. After the client restarts, select File > Preferences, and then click Connections.

    11. Fill out the fields in the Preferences page:

      • 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 .
      Click Apply, and then click OK.


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

    2. Determine the name of the LDAP realm used by the Connections deployment:

      1. On the Connections deployment manager, log in to the WebSphere Integrated Solutions Console as the WebSphere administrator.

      2. In the navigation list, click Security > Secure Administration, applications and infrastructure > Federated Repositories.

      3. Click Configure.

      4. On the main Federated repositories page, note the value for the realm name used for the Connections deployment.

      5. Close the Federated repositories page by clicking Cancel.

    3. Move to the computer hosting the Communities application for Connections, and start the wsadmin client :

      1. 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\bin

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

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

        Windows

        wsadmin -lang jython -user was_admin_user_id -password was_admin_password -port SOAP_CONNECTOR_ADDRESS_port

        where:

        • 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:

          1. Open the Integrated Solution Console for the deployment manager, and select System Administration > Deployment Manager.

          2. Under "Additional properties" expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
        For example:

        AIX, Linux

        ./wsadmin.sh -lang jython -user primaryAdmin -password p@assword -port 8879

        Windows

        wsadmin -lang jython -user primaryAdmin -password p@assword -port 8879

    4. Now access and check out the Communities configuration file:

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

      2. Check out the Communities configuration files :

        CommunitiesConfigService.checkOutPolicyConfig("working_directory", "Cell_name")

        ...where:

        • 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()
        For example:

        CommunitiesConfigService.checkOutPolicyConfig("/opt/my_temp_dir", "CommServerNode01Cell")

      3. Change to the working_directory where you stored the checked out files and open the communities-policy.xml file in a text editor.

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

      5. Save and close the file.

      6. Check in the updated file using the following wsadmin client command:

        CommunitiesConfigService.checkInPolicyConfig("working_directory", "Cell_name")

    5. Exit the wsadmin client with the following command: exit.

    6. Stop and restart the server.

    7. Synchronize Connections and Sametime Advanced:

      1. Move to the Sametime System Console and log in as the Sametime administrator.

      2. Click Sametime Servers > Sametime Advanced Server.

      3. Click the name of the Sametime Advanced server.

      4. On the Administrative Sets tab, location "Connection settings".

      5. Select https protocol.

      6. Set the fully qualified host name in the Host name field.

      7. Set the port number in the Port field.

      8. Set the user name and password for the Communities administrative user created in step 1.

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

      10. Click Save.

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

    1. From the Sametime Advanced server, select Security > SSL Certificate and key management > Key store and certificates > NodeDefaultTrustStore > Signer Certificates.

    2. Select Retrieve from Port.

    3. Enter the host and port details for the Communities server to connect to.

    4. Click OK.

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

    1. From the Sametime client, select Tools > Plug-Ins > Manage Plug-ins.

    2. Click the Show Nested Features icon to display a list of the installed features.

      You may need to expand sections to find the features.

    3. Find Activities Sametime Feature in the list. Right-click the feature name, and then select Uninstall.

    4. When asked to confirm, click OK. When asked to restart, click No.

    5. Find Communities Sametime Feature in the list. Right-click the feature name, and then select Uninstall.

    6. When asked to confirm, click OK. When asked to restart the client, click No.

    7. Find Connections Business Card in the list. Right-click the feature name, and then select Uninstall.

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

    1. Log into the WebSphere Application Server Integrated Solutions Console.

    2. Navigate to Resources > Resource Environment > Resource Environment Providers.

    3. Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.

    4. Click New and specify as name WP ConnectionsIntegrationService.

    5. Click Apply.

    6. Click Custom Properties.

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

    8. 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:

    1. Open the WebSphere Application Server Admin Console and expand Cache Instances in the Resources section.

    2. Select Object Cache Instances.

    3. Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.

    4. Click New to create a new cache instance.

    5. Set the JNDI Name to services/cache/LCPortletsObjectCache and set Name to something meaningful.

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

    1. In the WebSphere Application Server Integrated Solutions Console, expand Security, and then select Global Security.

    2. Expand Java Authentication and Authorization Service.

    3. Select J2C authentication data.

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

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

    1. Stop WebSphere Portal Server. For a clustered deployment, stop all Portal servers.

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

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

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

    5. Do the following to copy the configuration files:

      • For a single server: On the IBM WebSphere Portal server, copy the following files:

        • directory.services.xml

        • directory.services.xsd

        • sonata.services.xml

        • sonata.services.xsd
        from the DirectoryServices directory from the IC Portlets 3.0.1.1 download package, <IC3011_portlets>\DirectoryServices, to: <portalInstallRoot>\wp_profile\config\cells\<cell>\ .

      • 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>\ .

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

    7. 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+">

    8. (Clustered deployment only) Login to DMGR admin console and navigate to the System Administration - Nodes. Select both WebSphere Portal nodes and click Full Resynchronize.

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

    1. Log into the WebSphere Application Server Integrated Solutions Console.

    2. Navigate to Security > SSL certificate and key management > Key stores and certificates.

    3. 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'.

    4. Click Retrieve from port.

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

    6. Click Retrieve signer information.

    7. Click OK.

    8. 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:

    1. On the server where IBM Connections is installed, enable SSO:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator, expand Security > Global security.

      2. Expand Web and SIP security and then click Single sign-on (SSO).

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

    2. On IBM Connections deployment manager node:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator.

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

      3. Click Export keys.

    3. On the node where WebSphere Portal is installed:

      1. Log into the WebSphere Application Server Integrated Solutions Console as an administrator and click Security > Global security > LTPA.

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

      3. Click Import keys

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

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

    2. Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:

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

      2. Stop the Deployment Manager.

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

      4. Start the Deployment Manager.

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

    4. Restart the Deployment Manager.

    5. Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.

    6. 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_password
      For example:

      addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd

    7. On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.

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

    9. Skip this step if you are deploying on Portal 8. To Configure the same SPNEGO single sign-on for Portal and Connections:

      1. Create user for Portal host server on AD

      2. Create keytab file for Portal server on AD.

        ktpass -out path_to_keytab .princ SPN
        
        -mapuser account_name -mapOp set .pass account_password
        Where:

        • 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.
        For example:

        ktpass -princ HTTP/portal.cn.ibm.com@cn.ibm.com -out c:\portal.keytab -mapuser portaluser -mapOp set -pass Passw0rd

      3. Merge the portal keytab into the merged Connections keytab by running 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.

        • destination_keytab_name is the name of the keytab file on the destination system.
        For example:

        c:\IBM\WebSphere\AppServer\java\jre\bin>ktab.exe -m y:\SPNEGO\portal.keytab y:\SPNEGO\merged.keytab

      4. 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}

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

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

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

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

    2. Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:

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

      2. Stop the Deployment Manager.

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

      4. Start the Deployment Manager.

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

    4. Restart the Deployment Manager.

    5. Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.

    6. 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_password
      For example:

      addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd

    7. On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.

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

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

    1. Enable Siteminder and SPNEGO for IBM Connections, following the steps in Enabling Siteminder and SPNEGO.

    2. Enable and configuring single sign-on for HTTP requests using SPNEGO following the steps in this topic.

    3. Configure SiteMinder following the steps in this topic.

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

    5. Configure the Virtual Member Manager (VMM).

      1. 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>\

      2. Edit sonata.services.xml to use KerberosAuthenticator+ instead of DefaultAuthenticator.

      3. Add all IIS, Portal and Connections servers SPN as attributes.
      For example:

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

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

    2. Perform the following steps to collect files from the primary node and copy them to the Deployment Manager:

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

      2. Stop the Deployment Manager.

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

      4. Start the Deployment Manager.

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

    4. Restart the Deployment Manager.

    5. Add the same Portal administration group as an administrators group on the IBM Connections Deployment Manager.

    6. 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_password
      For example:

      addNode.bat DMhost.cn.ibm.com 8879 -includeapps -includebuses -username adminuser -password adminpwd

    7. On the Portal server, run syncNode.bat and then restart the Deployment Manager and all node agents.

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

    9. To Configure the same SPNEGO single sign-on for Portal and Connections.

      1. Create user for Portal host server on AD.

      2. Create keytab file for Portal server on AD:

        ktpass -out path_to_keytab .princ SPN
        
        -mapuser account_name -mapOp set .pass account_password
        Where:

        • 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.
        For example:

        ktpass -princ HTTP/portal.cn.ibm.com@cn.ibm.com -out c:\portal.keytab -mapuser portaluser -mapOp set -pass Passw0rd

      3. Merge the portal keytab into the merged Connections keytab by running 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.

        • destination_keytab_name is the name of the keytab file on the destination system.
        For example:

        c:\IBM\WebSphere\AppServer\java\jre\bin>ktab.exe -m y:\SPNEGO\portal.keytab y:\SPNEGO\merged.keytab

      4. 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}

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

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

    1. In the WebSphere Application Server Integrated Solutions Console, change the realm name. For example, from defaultWIMFileBasedRealm to AD.cn.ibm.com:389.

    2. Configure Portal to use the new realm name as the default realm:

      1. Use a text editor to open the wkplc.properties file, located in the <wp_profile_root>/ConfigEngine/properties directory.

      2. For defaultRealmName, type the realmName property value you want to use as the default realm.

      3. Save your changes to the wkplc.properties file.

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

      5. Stop and restart all necessary servers to propagate your changes.

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

      1. 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=newadmingroupid

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

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

      3. 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=newadmingroupid

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

    1. Set the authenticationMethod property to basicAuth in the file \WEB-INF\lcaccelerator\properties\lcaccelerator.properties in the deployed portlets war.

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

    3. 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:

    1. In Portal Server Administration choose Administration > Access > Credential Vault.

    2. Click Add a vault slot.

    3. Choose a vault and vault segment from select dropdown.

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

    5. Enter a vault slot name. This is the name that is seen in the configuration mode of the portlets.

    6. Check Vault Slot is shared.

    7. Enter a shared user ID and password to be stored in the system slot.

    8. (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.

    1. Follow the steps in this article to add the following modules to the default theme profile (profile_deferred.json): Portal 7.0.0.2:

      • wp_liveobject_framework

      • dijit_form_16

      • dijit_theme_tundra_16
      Portal 8.0:

      • wp_liveobject_framework

      • dijit_form_17

      if you are using a custom profile, add the modules to that profile.

    2. Stop and restart the Portal server.

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

    1. Download the plug-in from the IBM Connections catalog at the following web site:

      https://greenhouse.lotus.com/catalog.

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

    3. Click Administration > Portlet Management > Web Modules.

    4. Click Install.

    5. Extract the files from the snor.pf.portlets.zip file that you downloaded from the plug-in catalog.

    6. Browse to snor.pf.portlets.war.

    7. Click Next.

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

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

    1. Define a label to contain the default pages.

      1. Define a label to contain the default pages.

      2. Click Administration > Portal User Interface > Manage Pages.

      3. Navigate to the page where you want to add a portlet. For example, navigate to Home.

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

      5.  Enter IBM Connections for the title.

      6. Click OK.

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

      1. Define a page for each service to serve as a default page for content of that type.

      2. Click on the IBM Connections label you created in the prior step.

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

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

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

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

    3. Add portlets to corresponding pages:

      1. Click on the pencil icon (Edit Page Layout) next to a page.

      2. Click Add Portlets.

      3. Set the portlet title in the Search box and click Search.

      4. Select the check box next to the appropriate portlet, then click OK.

      5. Click Done.

    4. Follow these steps to give users access to the page.

      1. Navigate to Administration > Access > Resource Permission > Pages > Content Root. Navigate to the first page that contains an IBM Connections Portlet.

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

      3. Click on Apply and then Done.

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

    5. Follow these steps to give users access to the portlets.

      1. Navigate to Administration > Access > Resource Permission > Portlet Applications.

      2. Search for com.bowstreet.portlet.WebAppRunner2_snor.pf.portlets or the name of the portlet application if you have customized.

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

      4. To allow anonymous access, set the role User to Anonymous Portal User.

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

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

      1. Log into the WebSphere Application Server Integrated Solutions Console.

      2. Navigate to Resources > Resource Environment > Resource Environment Providers.

      3. Click WP ConfigService.

      4. Under Additional Properties, click Custom Properties.

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

      6. 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/*

      7. Save the property changes.

    2. Map the security roles for everyone and all authenticated users on the proxy servlet.

      1. Log into the WebSphere Application Server Integrated Solutions Console.

      2. Navigate to Applications > Application Types > WebSphere enterprise applications.

      3. Click PA_WPF or the name of your portlet Web application if you changed the name.

      4. Click Security role to user/group mapping.

      5. Check Everyone Role and click Map Special Subjects > Everyone.

      6. Check All Role and click Map Special Subjects > All Authenticated in Application.s Realms.

      7. Click OK.

      8. Save the changes.

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

    1. To map community pages to a community on a WebSphere Portal 7 server:

      1. Log into Portal as an administrator.

      2. Navigate to the page to map to a community.

      3. Click Actions > Edit Page Properties.

      4. Expand the Advanced options section and click I want to set parameters.

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

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

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

      1. Navigate to Administration > Manage Pages and find the community page for which you want to set access.

      2. Click Set Page Permission (lock icon).

      3. Uncheck Allow Inheritance for all rows and click Apply.

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

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

      6. Click Add.

      7. Change Search by to displayName.

      8. Enter the name of the community in the search box and click Search.

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

    4. 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 save

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

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

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

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

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

          1. Jars from CommunitiesVMM/vmmAdapterMain [exclude: com.ibm.ws.wim.adapter.base.jar ] -

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

    1. Log into the WebSphere Application Server Integrated Solutions Console.

    2. Navigate to Resources > Resource Environment > Resource Environment Providers.

    3. Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.

    4. If the WP ConnectionsIntegrationService already exists, click on it. If not, click New, specify WP ConnectionsIntegrationService, and click Apply.

    5. Click Custom Properties.

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

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

      • 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
      The possible configuration options are:

      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.

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

    1. Log into the WebSphere Application Server Integrated Solutions Console.

    2. Navigate to Resources > Resource Environment > Resource Environment Providers.

    3. Select Server or Cluster as the scope, depending on whether you are deploying on a single server or on a cluster.

    4. If the WP ConnectionsIntegrationService already exists, click on it. If not, click New, specify WP ConnectionsIntegrationService, and click Apply.

    5. Click Custom Properties.

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

    7. Navigate to Resource Environment > Resource Environment Providers.

    8. Select All as the scope.

    9. Click WP PumaStoreService. You might need to page through results or apply a filter.

    10. Click Custom Properties.

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

    12. 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:

    1. Login as any non-admin user

    2. Create a page, for example, JonesxxPage.

    3. Click Actions > Share page.

    4. Select Group search from drop down

    5. Enter a search string and verify that the results come from communities the user belongs to rather than from all communities.

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

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

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

    3. 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:

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

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

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

    1. Click the Administration link in the header of the portal page.

    2. In the Manage Search section, click New Search Service.

    3. Name the service appropriately so that it is easily identifiable, provide this value in the Service Name field.

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

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

    1. Click the Administration link in the header of the portal page.

    2. In the Manage Search section, click Search Collection.

    3. Click New Collection.

    4. Define the location of the collection on the portal file system and name it with an easily identifiable value.

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

    6. Click Collection to view the metadata of the collection created.

    7. Select Seedlist Provider as the Content source type.

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

    9. Click the Security tab and enter your Connections administrator credentials, so that you can access the specific service seedlist URL.

    10. Click Create to create the corresponding Content Source to enable crawling over the service defined.

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

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

    1. Click the Administration link in the header of the portal page.

    2. In the Manage Search section, click on Search Scope.

    3. Click New Scope.

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

    1. Open the stylesheet connectionsportlet.css or connectionsportletRTL.css from the lcaccelerator\css folder where the Connections portlets are installed.

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

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

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

    3. 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:

    To verify that the IBM Connections Business Card is enabled:

    1. Open one of the Lotus Connections portlets on WebSphere Portal and search for a person.

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

    1. Open the lcaccelerator.properties file, located at: <portal-profile-home>\installedApps\<node>\PA_WPF.ear\snor.pf.portlets.war\WEB-INF\lcaccelerator\properties.

    2. Set the openExternalLinksInNewWindow property to false.

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

    1. Open the file <installed war>\WEB-INF\lcaccelerator\properties\loggerServiceMapping.properties

    2. Set the property TPA_REST_LOG_FLAG to true.

    3. Restart the Application war from the WAS admin console.
    These logs will get generated at <installed war>/WEB-INF/logs/RESTCallLogs.log.
     

    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:

    1. Log into WebSphere Portal as the Administrator

    2. Navigate to Administration > Portal Analysis > Enable Tracing .

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

    4. Repeat step 3 for each log class to log.

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

    • com.ibm.lconn.activities.detail=finest

    • com.ibm.lconn.activities.service=finest

    • com.ibm.lconn.profiles.service=finest
    If you wanted to enable the fine log level for the Bookmarks Summary portlets, you would add these logging settings:

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

    1. Edit the portal page containing the IBM Connections portlets. For details on editing page parameters, see this Portal wiki article.

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

    3. Save the page changes.

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

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

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

    3. Click Add.

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

    5. Click Add.

    6. 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:

    1. The search URL is properly configured in the Tags portlet configuration panel.

    2. At least two applications that you want represented in the Tags must be selected in the Tags portlet shared settings panel.

    3. 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:

    1. The application URL of the Connections application you want to represent in the tags must be set in the Tags portlet configuration panel.

    2. The single application that you want represented in the tags must be selected in the Tags portlet shared settings panel.

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

    1. Enable the Edit Layout portlet to display the option to control the column size.

      1. Log in to WebSphere Portal as the administrator

      2. In the Administration section, go to Portlet Management > Portlets.

      3. Locate the Edit Layout portlet. Search by title using "edit layout" as the search text.

      4. Click the "Configure Portlet" icon.

      5. Set the "showAdvancedOption" to yes.

      6. Click OK to save the changes.

    2. Set the column size:

      1. Log in to WebSphere Portal as the administrator

      2. In the Administration section, go to Portlet Management > Manage Pages.

      3. Open a page containing the Tags portlet.

      4. Browse to the page containing the portlets and click on the "Edit Page Layout" option for the page.

      5. Click the "Show layout tools" link.

      6. In the header of the column containing the Tags portlet, click the two-sided arrow with the label "Not Set."

      7. Enter the pixel size for the width of the portlet. We recommend 180 pixels. This provides the optimal width.

      8. Click OK to save yo