Connections 4.5 CR14: Customize, Secure, Tune, and Integrate

+

Search Tips   |   Advanced Search

Connections 4.5 CR14: Customize, Secure, Tune, and Integrate

  1. Customize
  2. Security
  3. Performance
  4. Integrate with other products


Customize

If you customized an earlier version of Connections, there is no migration path provided for importing your changes into Connections 4.5 or later. Before upgrading, review and make a note of your existing customizations so that you can verify them post-migration and rework if necessary. In addition, customization work might no longer be valid if a customized file is updated with a subsequent fix pack or interim fix.

Additional information about the CSS and HTML markup structure used in Connections is available in the IBM Collaboration Solutions (ICS) UI Developer Guide.


Customization best practices

Most of the changes made 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

Best practice is to make changes within the customization directory only. Changes not made in customization directory are known as product modifications.

The type of changes that you can make using the customization directory include:

  • Changes to static files, such as images, CSS, HTML, and text files.

  • Changes to real files, that is, files that are not generated at runtime and which get served directly to the browser.

  • Changes to JSP files using a standard include request, for example...

      <jsp:include page="myjspfragment.jspf" .../>

    ...and...

      <c:import url= myjspfragment.jspf/>

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

  • Changes to JSP files using the JSP include directive. For example...

      <%@ include file="myjspfragment.jspf"%>

  • Changes to files within a JAR file. For example, adding custom strings to the ui.properties file in the lc.profiles.web.app-3.0.jar archive to customize error messages for field validation.

  • Changes to Java classes (Java class files).

  • Changes to TAG files. These files are used in the Communities and Forums applications.

  • Changes to TLD files.

  • Changes to most XML configuration files in the WEB-INF directory. This includes web.xml.

Keep your customization directory under source control to allow you to maintain it and track your changes over time. Use a web inspector to help you to locate the CSS rules to change. For example, Firebug on Mozilla Firefox, Webkit Inspector on Google Chrome or Apple Safari, or Weinre for Mobile. Use documented, public APIs where possible. Do not modify JSP files inside web modules or JAR files. Instead, use supported extension points where available, for example, for login pages or error pages, and so on.

Back up the customization directory before a product upgrade:

  1. Rename the customization directory to a temporary name.
  2. Apply the Connections interim fix or fix pack.
  3. Verify the functionality.
  4. Compare the updated files to the customized copy and then merge the changes.
  5. Change the name of the customization directory back to the original name.
  6. Test your customizations.


Customize the user interface

The procedure to customize Connections is the same for each application:

  1. Find the file that serves as the source of the interface elements to customize.

  2. Enable the customization debugging capability.

  3. Copy the file to customize and past it into the appropriate customization directory.

    You can find the sources for style sheets in the following JAR files:

    • WAS_HOME/profiles/profile_name/installedApps/cell_name/appname.ear/appname.war/WEB-INF/eclipse/plugins/com.ibm.oneui3.styles_version.jar

      Contains IBM Collaboration Solutions OneUI 3.0.x toolkit that includes image resources and sprites. This JAR file contains the CSS files for all Connections applications.

    • WAS_HOME/profiles/profile_name/installedApps/cell_name/appname.ear/appname.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.styles_version.jar

      Contains CSS style sheets that extend or override default styles from the OneUI 3.0.x toolkit.

    Popular customization areas...

    Feature File location
    Cascading style sheets /nav/common/styles/defaultTheme/custom.css
    /nav/common/styles/defaultTheme/custom_rtl.css (Hebrew, Arabic)
    /nav/common/styles/defaultTheme/defaultTheme.css
    Error page /nav/templates/error.jsp
    Footer /nav/templates/footer.jsp
    Login page /nav/templates/login.jsp
    Navigation bar /nav/templates/header.jsp
    Menus available from the navigation bar /nav/templates/menu/people.jsp
    /nav/templates/menu/communities.jsp
    /nav/templates/menu/apps.jsp

    For example, to edit the footer and have the same footer be displayed in all of the applications, store the updated footer file...

      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 in the customizationDir directory to make your changes.

  5. Test your changes by refreshing the web browser.

    You might have to clear your browser cache to see the changes.

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

  7. Use WAS admin 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.


Determine where to save your customizations

When you are customizing Connections, save your customized files to the appropriate directory to ensure that your customizations override the default settings.

The base directory where you must 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.

  1. Log in to the dmgr console and go to...

      Environment | WebSphere variables.

  2. Look for CONNECTIONS_CUSTOMIZATION_PATH in the list of variable names and make a note of the value. For example:

      /local/IBM/Connections/data/shared/customization

  3. Save your customized files in the appropriate subdirectory...

    Directory path Stores files to be applied to...
    customizationDir/common All of the applications.
    customizationDir/activities Activities user interface only.
    customizationDir/blogs Blogs user interface only.
    customizationDir/bookmarks Bookmarks user interface only.
    customizationDir/communities Communities user interface only.
    customizationDir/files Files user interface only.
    customizationDir/forums Forums user interface only.
    customizationDir/homepage Home page user interface only.
    customizationDir/metrics Metrics page user interface only.
    customizationDir/moderation Moderation page user interface only.
    customizationDir/news News user interface only.
    customizationDir/profiles Profiles user interface only.
    customizationDir/search Advanced Search user interface only.
    customizationDir/wikis Wikis user interface only.

    Where to store customized versions of files when the customizations apply to all the applications.

    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

    Where to store application-specific versions of customized CSS files:

    Directory path Description
    customizationDir/themes/applications/activities.css Customized styles for Activities.
    customizationDir/themes/applications/blogs.css Customized styles for Blogs.
    customizationDir/themes/applications/dogear.css Customized styles for Bookmarks.
    customizationDir/themes/applications/bookmarklet.css Customized styles for the Bookmarklet.
    customizationDir/themes/applications/communities.css Customized styles for Communities.
    customizationDir/themes/applications/files.css Customized styles for Files.
    customizationDir/themes/applications/forums.css Customized styles for Forums.
    customizationDir/themes/applications/homepage.css Customized styles for the Home page.
    customizationDir/themes/applications/metrics.css Customized styles for Metrics.
    customizationDir/themes/applications/moderation.css Customized styles for Moderation.
    customizationDir/themes/applications/news.css Customized styles for News.
    customizationDir/themes/applications/profiles.css Customized styles for Profiles.
    customizationDir/themes/applications/wikis.css Customized styles for Wikis.


Application WAR files

The default location for the web application directory for each application is:

    WAS_HOME/profiles/profile_name/installedApps/cell_name/appname.ear/appname.war

Application war files include...

    File WAR file for...
    oawebui.war Activities application
    blogs.war Blogs application
    dogear.webui.war Bookmarks application
    comm.web.war Communities application
    files.web.war Files application
    forum.web.war Forums application
    homepage.war Home page application
    lc.metrics.ui.war Metrics application
    sn.moderation.ui.war Moderation application
    news.web.war News application
    lc.profiles.app.war Profiles application
    search.war Search application
    wikis.web.war Wikis application


OSGi bundles

The following OSGi bundles are packaged as part of Connections, where ver is a version stamp that may change depending on the interim fix:

OSGi bundle Contains
com.ibm.dwa.web.resources_ver.jar JavaScript code specific to the Communities Events application. Contains many of the "calendar view" related user interface handling code for the Communities Events widget.
com.ibm.lconn.activities.web.resources_ver.jar JavaScript and resource strings for the Activities application user interface.
com.ibm.lconn.activitystreams.search.admin.web.resources_ver.jar HTML, JavaScript, and CSS files used by the activity stream search administration user interface.
com.ibm.lconn.blogs.web.resources_ver.jar JavaScript code specific to the Blogs application. Contains user interface handling code for the Blogs application.
com.ibm.lconn.calendar.web.resources_ver.jar JavaScript code specific to the Communities Events application. 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_ver.jar JavaScript and resource strings for the Communities Places catalog user interface.
com.ibm.lconn.communities.web.resources_ver.jar 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_ver.jar JavaScript code specific to the community Blog widget and Ideation Blog widget. 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_ver.jar JavaScript and resource strings for the Files widget user interface in Communities application.
com.ibm.lconn.core0.web.resources_ver.jar Core JavaScript widgets, which are mostly a hard copy of the com.ibm.lconn.core.web.resources_ver.jar source. Will be deprecated in a future release.
com.ibm.lconn.dogear.web.resources_ver.jar Containing JavaScript code specific to the Bookmarks application. Contains user interface handling code for the Bookmarks application.
com.ibm.lconn.ecmpicker.web.resources_ver.jar JavaScript code for the document picker used connect to ECM repositories.
com.ibm.lconn.files.web.resources_ver.jar JavaScript and resource strings for the Files application user interface.
com.ibm.lconn.forums.web.resources_ver.jar JavaScript code specific to the Forums application. Contains the user interface handling code for Forums, and also code for the Forums widgets in Communities.
com.ibm.lconn.homepage.web.resources_ver.jar JavaScript code 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_ver.jar User interface code for the Linked Library widget.
com.ibm.lconn.metrics.plugins.web.resources_ver.jar JavaScript code that is needed to bind to other Connections applications for Metrics requirements: track read events in Files and Activities.
com.ibm.lconn.metrics.reports.web.resources_ver.jar JavaScript code specific to the Cognos report page.
com.ibm.lconn.metrics.web.resources_ver.jar JavaScript code 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_ver.jar JavaScript code specific to the Moderation application.
com.ibm.lconn.news.digest.web.resources_ver.jar JavaScript and strings for the user interface elements that are specific to the News application, including the language selector that is used on the Settings page in News.
com.ibm.lconn.news.microblogging.sharebox.form_ver.jar 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_ver.jar JavaScript resources for the OAuth administration application.
com.ibm.lconn.profiles.web.resources_ver.jar 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_ver.jar Strings and JavaScript resources for the Related Communities widget.
com.ibm.lconn.share0.web.resources_ver.jar Base classes (dialogs, widgets, and utils) for the com.ibm.lconn.wikis.web.resources__ver.jar file.
com.ibm.lconn.wikis.web.resources_ver.jar JavaScript code 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. 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.

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
zh-TW Traditional 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.


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

Add a WAS environment variable named CONNECTIONS_CUSTOMIZATION_DEBUG and set it to true.

    Open the dmgr console and go to...

      Environment | WebSphere variables.

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

  2. Type the following values into the fields:

      Name CONNECTIONS_CUSTOMIZATION_DEBUG
      Value true

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

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

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

  1. Open the Integrated Solutions Console, expand...

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


Customize the navigation bar

You can edit the files that control the content of the 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. Turn on the customization debugging capability.

  2. To add a link to the list of links in the navigation bar, for example, a link called "IBM software"...

    1. Make a copy of header.jsp, which defines the content of the main navigation bar. You can access the file from the following directory:

      The header.jsp file is the same for each application so you only need to make a copy of one of header.jsps.

      You might want to copy your header changes to the login.jsp and error.jsp files for consistency across your deployment.

    2. Paste the copy of header.jsp into the appropriate subdirectory in the customization directory, most likely the common directory.

      For example, to change the look of the navigation bar in all the applications, copy the file into:

        customizationDir/common/nav/templates

    3. Open the copy of header.jsp 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 header.jsp. You do not need to restart the applications to see the links display.

  3. 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. cp appname.war/nav/templates/menu/user.jsp 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. cp appname.war/nav/templates/menu/user.jsp customizationDir/common/nav/templates/menu/user.jsp

    2. Copy one of the existing menu sections and change the "src" attribute to point to a servlet, JSP, or static HTML page containing the markup to use. 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 appname.war/nav/templates/menu/people.jsp
        Communities menu appname.war/nav/templates/menu/communities.jsp
        Apps menu appname.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 header.jsp: 

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

  7. Update the product version stamp and ensure that users see the changes the next time that they log in to Connections.


Replace images

Customize the product by replacing images specific to Connections with your own company images.

The procedure described here applies to non-sprited images only.

  1. Copy the image to replace and paste it to a new location.

    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.

  4. 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. Update the product version stamp and ensure that users see the changes the next time that they log in to Connections.


Change the Connections logo

To customize Connections so that it has the look and feel of your organization, you can specify a CSS override that replaces the Connections logo with your company logo.

Two IBM logos display in the product by default. The first logo contains the text Connections and second logo is the graphical IBM logo. You can replace both logos with your company logo.

  1. Turn on the customization debugging capability.

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

  3. Save your company logo in...

      customizationDir/themes/defaultTheme/images

  4. Open the CSS file in a text editor and add the following lines:

    • To replace the 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, 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.

  8. Update the product version stamp and ensure that users see the changes the next time that they log in to 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. Turn on the customization debugging capability.

  2. Add the new icon files to the following directory:

    customizationDir/themes/images

  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/appname.ear/appname.war/nav/common/styles/base

    where:

    • WAS_HOME is the directory where IBM WebSphere Application Server is installed.
    • profile_name is the profile where you installed Connections.

    • cell_name is the cell where you installed the application.
    • appname.ear is the name of the application EAR file. To customize interface styles that are common to all applications, use the Common.ear file.
    • appname.war is the name of the application WAR file.
    • version is the version number of the Connections release plus the date and build number of the JAR file.

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

  7. Update the product version stamp and ensure that users see the changes the next time that they log in to Connections.


File type icons

These icons are provided by Connections for displaying files.

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 Connections by modifying the images and copying them to the appropriate customization directory.

  1. Turn on the customization debugging capability.

  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:

    ...where target is the name of the image to sprite.

    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.

  9. Update the version stamp and restart the application.


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 Connections. You can also specify any of the specifically labeled components, such as iconsOther48, as a target for the ws_ant.sh command.

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

You can change the look of the 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 Connections stylesheet, you need to create a CSS file containing your customized styles and store it in the customizationDir/themes/defaultTheme folder.

  1. Turn on the customization debugging capability.

  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:

    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

  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. If you enabled customization debugging in step 1, turn it off when you are ready to publish your changes.

  9. See Required post-customization step for information about how to apply your changes permanently.


Make extensive color and style changes

Edit the defaultTheme.css file to change the look of the user interface, such as changing the font style or background color.

The default styles and colors for Connections applications are specified in the defaultTheme.css file. Extra application-specific styles are defined in files that are named after the applications such as the activities.css file. These extra styles override the styles in the defaultTheme.css file.

To customize a UI control in an application, you might have to edit the application-specific CSS file instead of the defaultTheme.css file. You can overwrite the application-specific CSS file by storing your edited version in the customization directory for that application.

  1. Turn on the customization debugging capability.

  2. Create a defaultTheme directory in the customizationDir directory.

    For example:

  3. Navigate to the themes directory:

      WAS_HOME/profiles/profile_name/installedApps/cell_name/appname.ear/appname.war/WEB-INF/eclipse/plugins/com.ibm.lconn.core.styles_version.jar!/resources/base/applications

    The com.ibm.lconn.core.styles_version.jar file contains CSS style sheets that extend or override default styles from the OneUI 3.0.x toolkit.

    where:

    • WAS_HOME is the directory where IBM WebSphere Application Server is installed.
    • profile_name is the profile where you installed Connections.

    • cell_name is the cell where you installed the application.
    • appname.ear is the name of the application EAR file. To customize interface styles that are common to all applications, use the Common.ear file.
    • appname.war is the name of the application WAR file.
    • version is the version number of the Connections release plus the date and build number of the JAR file.

  4. Copy the defaultTheme.css file and any other files to change and 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...

    • 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 for the class definition to change. For example, suppose to update the following lines: 
    body.lotusui30 {color:#222;background:none;background-color:#cee1fc}
.lotusContent{background-color:#fff;}

    • To change the color of body text, change the default value from #222, which is the code for black, to a color of your choosing.

      The font color that you define for body text is applied only 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.

    • To change the background color, change the default value from #fff, which is the code for white, to a color of your choosing.

  7. Save and close the CSS file.

  8. To test your style changes, refresh the application in your web browser.

  9. If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes.

For information about how to apply your changes permanently, see Required post-customization step.


Customize the login page

You can change the appearance of the Connections login page to meet your organization's needs. For example, you can replace the IBM logo displayed on the login page. Or you might want to include a link that enables users to have their user IDs or passwords sent to them through email.

  1. Turn on the customization debugging capability.

  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/appname.ear/appname.war/nav/templates

    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:

  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 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. If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes.

  8. Apply your changes permanently.


Customize the footer

You can edit the files that control the content of the Connections footer to improve the footer's functionality.

The footer.jsp file defines the content of the footer in Connections. The style used by the footer is defined in the defaultTheme.css file. In addition to defining the style of Connections, this file also sets the font color and background color of the navigation bar and footer.

  1. Turn on the customization debugging capability.

  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/ appname.ear/appname.war/nav/templates

    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.

    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 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 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. If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes.

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

You can change the text that is displayed on the 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. Turn on the 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/appname.ear/appname.war/nav/templates

    where:

    • WAS_HOME is the directory where IBM WebSphere Application Server is installed.
    • profile_name is the profile where you installed Connections.

    • cell_name is the cell where you installed the application.
    • appname.ear is the name of the application EAR file. To customize interface styles that are common to all applications, use the Common.ear file.
    • appname.war is the name of the application WAR file.
    • version is the version number of the Connections release plus the date and build number of the JAR file.

    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.

    For example, to use the same error page in all the applications, copy the file into the following directory:

    To create an application-specific error page, copy the file into the following directory:

      customizationDir/appname/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. If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes.

  8. See Required post-customization step for information about how to apply your changes permanently.


Customize the Getting Started view

Help users get started with your implementation of Connections by customizing the Getting Started view that is displayed in the Home page.

The Getting Started view is only available from the Home page. If you do not install the Home Page application, then the Getting Started view is not available in the product.

To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client.

See Start wsadmin

The gettingstarted-config.xml file defines the content of the Getting 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 Getting Started view configuration:

      HomepageCellConfig.checkOutGettingstartedConfig("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. The directory must grant write permissions or the command will not run successfully.

    • cell_name is the name of the WAS cell hosting the Connections application. This argument is case-sensitive, so type it with care. To determine cell name, run wsadmin command: 
      print AdminControl.getCell()

    For example:

      HomepageCellConfig.checkOutGettingstartedConfig("/opt/act/temp","Cell01")

  4. Find the gettingstarted-config.xml file in the following directory, and open it in a text editor.

      /opt/IBM/WebSphere/AppServer/profiles/<AppSrv>/config/cells/<nodeName>/LotusConnections-config

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

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

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

  8. Run the following command to check the configuration files back in. You must check the files back in in the same wsadmin session in which you checked them out for the changes to take effect. 
    HomepageCellConfig.checkInGettingstartedConfig("working_directory",
 "cell_name")

    working directory and cell_name match values specified during checkout.

  9. Update the version stamp property to force a refresh of users' web browsers, so that they will see the changes you made to the Getting Started view the next time they access the product.


Customize product strings

You can replace a word or phrase in the product user interface with terminology that better suits your environment.

You cannot use this method to customize the default notification messages in emails that are sent from Connections applications. See Customizing 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 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 used 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 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. To change the term "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 Connections, see Language codes.

  3. Save the properties file that you created in... 
    customizationDir/strings
    where customizationDir is the root directory for customization files.

    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 dmgr 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. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp". The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

    3. Enter the following command to increment the value of the versionStamp property:

      LCConfigService.updateConfig("versionStamp","gmt_timestamp")

        yyyyMMdd.HHmmss

      LCConfigService.updateConfig("versionStamp","").

    4. After making changes, check the configuration files back in and you must do so in 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 Connections applications.
      For example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/standaloneCell01/
    • webresources refers to the web resources provisioning directory for Connections created during installation. By default, it is created in...

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

Description Source location Save customizations in
Common widget strings In installedApps/appname.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 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

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

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 Connections has a Bookmarking Tools link in the page footer that allows users to install this toolbar button.

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

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

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

customizationDir/strings/com.ibm.lconn.widgets.resources.ui_widgets.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
Strings that display in the Communities catalog user interface, including Communities table and community entries, menu items, and the Catalog administration 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


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

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

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

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

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

Description Source location Save customizations in
Template resource strings for use in activity stream event titles

Customized strings must have the same placeholders (string of characters delimited by curly braces) as the placeholders in the source string.

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

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

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

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

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
Welcome page content In installedApps/Wikis.ear/share.services.jar:/src/com/ibm/lconn/share/services/handlers/wiki/nls/WikiWelcomeMessages_locale.properties customizationDir/strings/com.ibm.lconn.share.services.handlers.wiki.nls.WikiWelcomeMessages_locale.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 Customizing 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 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 Connections.

  • To use the external resource bundle loader for adding and updating strings in the user interface, see Adding 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.

  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 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 WAS admin 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 Connections applications.
      For example: /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/standaloneCell01/

    • webresources refers to the web resources provisioning directory for Connections created during installation. By default, it is created in...

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

Description Source location Place customizations in
Like control (in embedded experience) installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.oneui.web.resources_version.jar/resources/recommend/nls/Recommender.js customizationDir/javascript/com/ibm/oneui/recommend/nls/Recommender.js
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

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

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

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 Connections has a Bookmarking Tools link in the page footer that allows users to install this toolbar button.

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

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
Strings that display in the Communities catalog user interface, including Communities table and community entries, menu items, and the Catalog administration user interface webresources/com.ibm.lconn.communities.catalog.web.resources_version.jar/resources/nls/placeCenter.js customizationDir/javascript/lconn/communities/catalog/nls/placeCenter.js


Embedded experience

Description Source location Place customizations in
Embedded experience content installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.social.ee.web.resources_version.jar/resources/nls/socialEEStrings.js customizationDir/javascript/com/ibm/social/ee/nls/socialEEStrings.js
Embedded experience window installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.oneui.web.resources_version.jar/resources/controls/nls/FlyoutDialog.js customizationDir/javascript/com/ibm/oneui/controls/nls/FlyoutDialog.js


Forums

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

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.

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


Share dialog

Description Source location Place customizations in
Share dialog installedApps/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins/com.ibm.social.ee.sharebox.resources_version.jar/resources/nls/socialShareboxStrings.js customizationDir/javascript/com/ibm/social/sharebox/nls/socialShareboxStrings.js
Share update form webresources/com.ibm.lconn.news.microblogging.sharebox.form_version.jar/resources/nls/InputForm.js customizationDir/javascript/lconn/news/microblogging/sharebox/nls/InputForm.js

The file upload form used by the Share feature uses Files strings.

For information about customizing Files strings, see Property file strings.


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.

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

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

When adding custom strings, use the wsadmin client.

See Start wsadmin for details.

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
  • Configuring 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 Customizing 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 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 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. Access the Connections configuration file:

      execfile("$WAS_HOME/profiles/dmgrGR/config/bin_lc_admin/connectionsConfig.py")

    3. Check out the 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 WAS cell hosting the Connections application. This argument is required. It is also case-sensitive, so type it with care.
      For example: 
      LCConfigService.checkOutConfig("/temp", "Cell01")

    4. From the temporary directory to which you just checked out the 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 Connections.  -->

  <widgetBundle prefix="example" name="com.example.resources"/>

</resources>

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

    7. To check in the updated file:

      LCConfigService.checkInConfig()

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

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 Connections users by the system.

You can customize the text used in the notification messages sent to users to include information specific to your organization. All of the strings used in notification templates are contained in...

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

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

      LotusConnections-config/notifications/appname/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 Connections

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 Connections in such a way that they do not disrupt existing code or prevent you from applying interim fixes.


Overriding JavaScript in Connections

You can override the JavaScript files used by 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 Connections deployment with the customization directory configured.

For information about locating the customization directory, see Customizing 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 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, you must copy that new change into your override file to maintain your customization.

To override JavaScript files....

  1. Identify the JavaScript file to override.

    Most of the JavaScript used by 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 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. It is recommended 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 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.

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.


Extend JavaScript in Connections

You can extend the JavaScript files used by Connections when you want to add new functionality, widgets, or scripts to the product.

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

The easiest way to extend the JavaScript used in Connections is to start with a sample bundle, add files to it, and deploy it in your Connections environment.

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 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 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 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 Connections JavaScript. To ensure that your module is loaded, 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 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 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 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 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, 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. 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 Connections by adding your own custom JSTL tags to meet your company's needs.

  1. Turn on 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/
appname.ear/appname.war/nav/templates

    where:

    • WAS_HOME is the directory where IBM WebSphere Application Server is installed.
    • profile_name is the profile where you installed Connections.

    • cell_name is the cell where you installed the application.
    • appname.ear is the name of the application EAR file. To customize interface styles that are common to all applications, use the Common.ear file.
    • appname.war is the name of the application WAR file.
    • version is the version number of the Connections release plus the date and build number of the JAR file.

  3. Paste the .jsp file into the appropriate subdirectory in the 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. If you enabled custom debugging, turn off the debugging capability when you are ready to publish your changes.

  8. See Required post-customization step for information about how to apply your changes permanently.


Customize the Application Access and Access Request interfaces

You can customize the header, footer, login, and error pages that prompt 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, 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.


Customize notifications

The content of the notifications sent by 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.

Before making any customizations, first back up your original notifications folder. In addition, ensure that any customized files are backed up before performing a product upgrade or applying a cumulative refresh or fix pack, as you might need to merge your changes again manually after making updates.


Customize standard notifications

You can customize the standard email messages that are sent by the applications in Connections, including the auto-generated notifications that are generated by the News application.

Before making any customizations, first back up your original notifications folder. In addition, ensure that any customized files are backed up before performing a product upgrade or applying a cumulative refresh or fix pack, as you might need to merge your changes again manually after making updates.

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 Connections, see Configure notifications.

      Notifications are stored in the following location: 

      WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/

      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: 
        WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/appname/resources/nls
      • Shared strings: 
        WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/resources/nls

      Where language_code is the locale of the language. For example, notification_fr.properties.

      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: 
        WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/appname/resources/images
      • Shared images: 
        WAS_HOME/profiles/Dmgr01/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.

Before making any customizations, first back up your original notifications folder. In addition, ensure that any customized files are backed up before performing a product upgrade or applying a cumulative refresh or fix pack, as you might need to merge your changes again manually after making updates.

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 that is 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: 
      WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/news

    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 dmgr 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... 
      WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/news
    3. Register the custom templates in notification-config.xml.

      1. Open a command prompt, and then change to the following directory on the system on which you installed the Deployment Manager:

          WAS_HOME/profiles/Dmgr01/bin

        For example, on Windows:

          C:/IBM/WebSphere/AppServer/profiles/Dmgr01/bin

        You must run the following command to Start wsadmin 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 Connections application does not work correctly.

      2. Start wsadmin:
          ./wsadmin.sh -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 WAS administrator.

        • SOAP_CONNECTOR_ADDRESS Port is the SOAP port for WAS. 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 WAS Integrated Solution Console. To look up the SOAP port number, perform the following steps:

          1. Open WAS Integrated Solution Console for the deployment manager, and then select...

              System Administration | Deployment Manager | Additional properties | Ports | SOAP_CONNECTOR_ADDRESS

        For example:

          ./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879

      3. Access the Connections configuration files:

          execfile("connectionsConfig.py")

      4. Check out notification-config.xml

          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.

          temporary directory must grant write permissions or the command will not run successfully.

        • cell_name is the WAS 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 notification-config.xml 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 notification-config.xml.

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

          WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/news/resources/nls
      • Shared strings:

          WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/resources/nls

      Where language_code is the locale of the language. For example, notification_fr.properties.

      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 Connections logo image and individual application icons.

    1. Locate the images in...

        WAS_HOME/profiles/Dmgr01/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 Connections.

Before making any customizations, first back up your original notifications folder. In addition, ensure that any customized files are backed up before performing a product upgrade or applying a cumulative refresh or fix pack, as you might need to merge your changes again manually after making updates.

The notifications used in 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 Customizing email digests.

You can customize notifications in Connections by updating the shared resources stored at this location:

    WAS_HOME/profiles/Dmgr01/config/cells/cell-name/LotusConnections-config/notifications/resources

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:

    WAS_HOME/profiles/Dmgr01/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 dmgr 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:

        WAS_HOME/profiles/Dmgr01/config/cells/cell_name/LotusConnections-config/notifications/resources/nls

      where language_code is the locale of the language. For example, notification_fr.properties.

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

        WAS_HOME/profiles/Dmgr01/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 WAS_HOME/profiles/Dmgr01/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 users can choose.

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 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 Connections, there is no migration path provided for importing your changes into Connections 4. Before upgrading to 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:

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 Defines the look of the Blogs Listing view.
mynotificationreceived Defines the look of the Notifications Received list on the My Updates page.
mynotificationsent Defines the look of the Notifications Sent list on the My Updates page.
myupdates Defines the 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 Settings 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. 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, you must choose to customize the theme. Customizing theme templates involves editing the source HTML for the template files. You should only do this if you are comfortable editing HTML files. 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 Settings 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 Settings 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: Adding 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 Settings 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.


Make a custom theme available to users

You can create custom themes and make them available to your blog users. Customizing themes requires experience editing HTML and CSS files.

Follow these steps to make a custom theme available to 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 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 in 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 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 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 an earlier version of Connections, there is no migration path provided for importing your changes into Connections 4 or later. Before upgrading to Connections 4 or later, 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.


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

  1. Create a copy of the existing default theme.

    1. Copy the com.ibm.oneui3.styles_build stamp.jar file from application_server\installedApps\cell_name\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:

      /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/cell01/Common.ear/connections.web.resources.war/WEB-INF/eclipse/plugins

      You must copy the JAR file in order to access the defaultTheme folder. Do not copy the folder from the nav/common/styles directory because this directory contains older themes.

    2. Unzip the JAR file and locate the resources/css folder.

    3. Copy the defaultTheme directory from the css folder to the customizationDir/themes directory, where customizationDir is the base directory where you store your customizations. If the themes subdirectory does not already exist, create it now.

      The customizationDir directory is located in the shared content store directory that is defined during installation, when it is saved as an IBM WebSphere Application Server variable named CONNECTIONS_CUSTOMIZATION_PATH.

    4. Rename the customizationDir/themes/defaultTheme directory to customizationDir/themes/corporateTheme. Rename the defaultTheme.css stylesheet inside the customizationDir/themes/corporateTheme directory to corporateTheme.css. Rename the defaultThemeRTL.css stylesheet 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 customizationDir directory so they can be used from all the applications.

  2. Update the corporateTheme.css file and other CSS files in the customizationDir/themes/corporateTheme 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:

    customizationDir/communities/images/ This image will be displayed in the Theme Palette.

After defining a new theme, you need to add it to the Communities configuration file, communities-config.xml.

For more information, see Adding 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 wsadmin

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, you must 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....

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. Check out the Communities configuration :

      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, Linux, and IBM i only: The directory must grant write permissions or the command will not run successfully.

      • cell_name is the name of the WAS cell hosting the Connections application. This argument is required. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example: 
      CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommCell01")

  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/

    Ensure the value specified for themeUuid is in lowercase. Also uuid and cssUrl are dependent on each other.

  5. Save the communities-config.xml file.

  6. After making changes, check the configuration files back in, and you must do so in 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.

  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 Customizing the user interface for information about how to publish your changes and make them permanent.


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

To specify the name of a custom community theme....

  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, Adding 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, Customizing product strings.

  5. Restart the Communities server.


Remove community themes

To make a specific community theme unavailable to 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 wsadmin

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

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. Check out the Communities configuration :

      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, Linux, and IBM i only: The directory must grant write permissions or the command will not run successfully.

      • cell_name is the name of the WAS cell hosting the Connections application. This argument is required. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example: 
      CommunitiesConfigService.checkOutConfig("/opt/my_temp_dir", "CommCell01")

  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 in 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 Connections, you must use an Ajax proxy.

IBM WebSphere Application Server Application Pack for Web 2.0 includes an Ajax proxy.

For more information, see the WebSphere Application Server information center.

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


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 Connections, you must use an Ajax proxy.

For information about how to configure the Communities business card on a Lotus Domino server, see Configure 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. To use an Ajax proxy, add the following code to the web page before the </body> tag: 
    <script type="text/javascript">  var SemTagSvcConfig = {baseUrl: "community_service_URL", proxyURL: "Ajax_proxy_URL"};
</script>
    The following properties are available for the SemTagSvcConfig variable:

    Property Description
    baseUrl Used to download resource strings and CSS files for the business card from the Communities application.

    The baseUrl parameter must be provided for the CSS to load. For example: http://myserver.com/communities

    This property is required.

    proxyURL Used to channel the HTTP request using an Ajax proxy. This proxy URL is required to avoid cross-domain issues. It is used to channel data from the IBM Lotus Connections server to your web site.

    The value of the proxyURL parameter must be a link to your own Ajax proxy. The Ajax proxy must reside in the same domain as the application that includes the business card. For example, if your application resides at http://myserver.com/myCustomApp, the value of the proxyURL might be http://myserver.com/myCustomAppProxy.

    This property is required.

    isBidiRTL Used to provide support for bidirectional languages. This property takes a Boolean value.

    This property is optional.

    loadCssFiles Used to download a CSS file for the business cards. This property takes a Boolean value.

    This property is optional. By default, it is set to true.

    For example: 

    <script type="text/javascript">     var SemTagSvcConfig =     {        baseUrl: "http://myConnectionsServer.mycompany.com",        proxyURL: "http://myDominoServer.mycompany.com/xsp/proxy/BasicProxy",        loadCssFiles: true     };  </script>

  2. To configure the semantic tag service, include the following 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, you must 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 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>

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

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

  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 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
  • LDAP distinguished name, using the DN parameter

    The lookup by distinguished name requires that Profiles include the DN as an attribute of the profile. Specifically, the DN parameter must be mapped to the Profile database column EMPLOYEE.PROF_SOURCE_UID.

    See Mapping fields manually and Attribute mapping for Profiles for related information.

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 Connections. Hiding email is a way to protect user privacy. 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...

  1. Include the following reference to the semanticTagService.js file in your code: 
    <script type="text/javascript"  src="src="protocol://conn_server/profiles/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, you must 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://conn_server/profiles/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 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://conn_server/profiles/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://conn_server/profiles/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. 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. 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...

        • service-location.xsd
        • LotusConnections-config.xsd
        • LotusConnections-config.xml

        ...are in...

          WAS_HOME\profiles\WAS_Profile\config\cells\Host_name\LotusConnections-config

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

    When displaying in Internet Explorer Quirks mode, a user's integrated business card may display their name in a different location than when using the browser’s Standards mode. To work around this display issue, enter the following statement in the html file to force a Standards mode rendering: 

    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> (http://www.w3.org/TR/html4/strict.dtd%27%3E)


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


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, use the wsadmin client.

See Start wsadmin

You can specify links to services acquired from another vendor in...

    WAS_HOME/profiles/WAS_Profile/config/cells/Host_name/LotusConnections-config/LotusConnections-config.xml

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:

      WAS_HOME/profiles/Dmgr01/bin

    where app_server_root is the IBM WebSphere Application Server installation directory and Dmgr01 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 Connections configuration files.

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes: When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp". The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

  3. Open LotusConnections-config.xml, and modify it to include the following 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 Adding 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 in 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.


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 Connections Connector for Lotus Quickr and the following Lotus Quickr product documentation topics:

For the Connections business card to appear in Lotus Quickr, you must complete the steps in the following topics 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 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 Quickr Entry Place feature.

  • To find out what versions of Lotus Quickr are supported, see Detailed system requirements for Connections.

  • For Lotus Quickr for Lotus Domino, 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.

    See create Lotus Quickr entry places

    Quickr Domino 8.5 and later no longer supports the Quickr Entry Place feature.

    When adding a Quickr link to the business card, if you have enabled SSL in 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 Connections using HTTPS.

  • To edit configuration files, use the wsadmin client.

    See Start wsadmin 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 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: 

    WAS_HOME/profiles/Dmgr01/bin

    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 Connections configuration files.

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp". The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

  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 in 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, use the wsadmin client.

See Start wsadmin 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: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  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. 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 in 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 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 that are defined by default, or you can add extension properties defined by you to meet your organization's needs.

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


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

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, assistant email, country, and department title are resolved from the associated value.

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

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:

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.

You can also add a new extension field. In the following example a new extension field (preferredFrenchName) is defined that can be used as an additional given name or surname during directory search from within the Profiles application. The additional searchable name would be the value of the preferredFrenchName field.

  1. Stop the server.

  2. Modify the profiles-config.xml file and the tdi-profiles-config.xml to add the new extension field as follows: 
    <simpleAttribute extensionId="preferredFrenchName" length="64" sourceKey="LDAP-attribute-name"/>

  3. Modify the profiles-types.xml file to add preferredFirstName and the extension field to the default profile-type as in the following example:

    If you are using TDI, make this update to the profiles-types.xml file in your TDI solution directory. 

            <property>
            <ref>preferredFirstName</ref>
            <updatability>readwrite</updatability>
            <hidden>false</hidden>
            <mapToNameTable>givenName</mapToNameTable>
        </property>
        <property>
            <ref>preferredFrenchName</ref>
            <updatability>readwrite</updatability>
            <hidden>false</hidden>
            <mapToNameTable>surname</mapToNameTable>
        </property>

  4. Modify LotusConnections-config\profiles\templates\resources\nls\template_en.properties to add a new field label for preferredFrenchName as follows: 
    label.preferredFrenchName=Preferred French name

  5. Add the two new fields to the profileEdit.ftl as follows: 
        <@util.renderFormControl ref="preferredFirstName" singleColumnLayout=false nlsKey="label.preferredFirstName"/>
    <@util.renderFormControl ref="preferredFrenchName" singleColumnLayout=false nlsKey="label.preferredFrenchName"/>

  6. Restart the server.

  7. To test, edit a user profile and set values for the person’s preferredFirstName and preferredFrenchName. In Profiles, click the Directory tab and perform a search on the person’s preferredFirstName and preferredFrenchName name.


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

    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:

    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:

      • AIX or Linux: 

        ./sync_all_dns.sh

        Windows: 

        sync_all_dns.bat

      • IBM i: 
        Run QSH command cd /DB_Wizard_directory/TDIPopulation/IBMi/TDI
sync_all_dns.sh

      • AIX or Linux: 

        ./populate_from_dn_file.sh

        Windows: 

        populate_from_dn_file.bat

      • IBM i: 
        Run QSH command cd /DB_Wizard_directory/TDIPopulation/IBMi/TDI
populate_from_dn_file.sh


Enable custom extension attributes for Profiles

Extend the Profiles application by adding custom extension attributes.

To edit configuration files, use the wsadmin client.

See Start wsadmin

In addition to different attribute layouts, Profiles supports extension attributes for every profile type. Because all profiles share one schema, an extension attribute, such as customers, has the same semantic meaning for all profile types. However, you can choose to associate a particular attribute with a profile based on profile type. The attributes are declared in the profiles-config.xml file located in the was_profile_root/config/cells/cell_name/nodes/node-name/LotusConnections-config directory. Although changes to profiles-config.xml should generally be made using wsadmin client scripting, there are no wsadmin commands to modify the profilesDataModel, so you can make changes to the profilesDataModel using a text editor.

To add a custom extension attribute to the My Profile page, perform the following steps.

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  3. Save a copy of the profiles-config.xml file.

  4. Open the file in a text editor.

  5. To define the extension attribute, add it to the <profileExtensionAttributes> element under <profileDataModels> as shown in the following sample: 
    <profileDataModels>    
  <profileExtensionAttributes>
    <simpleAttribute extensionId="property1" length="64"/>
    <simpleAttribute extensionId="property2" length="64"/>
    <simpleAttribute extensionId="property3" length="64"/>
  </profileExtensionAttributes>

  <profileDataModel>
...
  </profileDataModel>
...
</profileDataModels>
    For example: 
    <profileDataModels>
  <profileExtensionAttributes>
   ...
    <simpleAttribute extensionId="spokenLang" length="64" />
    <simpleAttribute extensionId="TechExperience" length="64" />
    <simpleAttribute extensionId="officeAddress" length="64" />
    <simpleAttribute extensionId="homeAddress" length="64" />

  </profileExtensionAttributes>
</profileDataModels>

  6. Check the configuration files back in in the same wsadmin session in which you checked them out for the changes to take effect.


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 the profiles-types.xml file.

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.

Sample – Profile-type declaration with hierarchy and inheritance Description 

<config>
  <type>
    <parentId>snx:person</parentId>
    <id>customer</id>
    ...
  </type>
</config>
 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:

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.

mapToNameTable Enum

Indicates if this property value is intended as an additional given name or surname for use in a directory search from within the Profiles application.

  • surname – Specifies that the value of this property is added as a surname to the Profiles database for use in a simple directory search.
  • givenName – Specifies that the value of this property is added as a given name to the Profiles database for use in a simple directory search.
  • none – Specifies that this value is not mapped to a name field in the Profiles database and not used in a simple directory search.

The default value for this property is none for all fields except the following:

  • preferredFirstName - givenName
  • preferredLastName - surname

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.

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, use the wsadmin client.

See Start wsadmin

To add a new profile type for widget layout, perform the following steps.

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

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

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 the profiles-types.xml file, 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 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 Saving your customizations and Post-migration tasks topics.

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.

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

Use the information in this section to customize your user interface templates.


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 wsadmin

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: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

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

Use the profileDetails.ftl template to render multiple sections of the main profile page.

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

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

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

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

Use the businessCardInfo.ftl template to control how profile fields are presented in the business card.

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

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

    If your desired customization requires profile record data for resolved codes, extension fields, secretary information, manager information, or connection information, also update your profiles-config.xml file. Use the following procedure to specify the additional required data needed for input to the FreeMarker template processor:

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

    2. Locate the <template/> element whose attribute name is equal to businessCardInfo.

    3. Modify the <templateDataModel/> section, using the following example, to include the <templateData/> element for the required data.

    4. Save your changes.

    5. Check in the updated profiles-config.xml file.

    6. Restart the server.

    Example: 

    <template name="businessCardInfo">
 <templateDataModel>
  <!--  include if you render workLocation, organization, department information -->
  <templateData>codes</templateData>
  <!--  include if and only if you render profile extension fields in the template -->
  <templateData>extensions</templateData>
  <!--  include if you render secretary name or email in the template -->
  <templateData>secretary</templateData>
  <!--  include if you render manager name or email in the template -->
  <templateData>manager</templateData>
  <!--  include if you render information dependent upon two users being connected -->
  <templateData>connection</templateData>
 </templateDataModel>
</template>


Customize search results information

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

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  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.

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

    If your desired customization requires profile record data for resolved codes, extension fields, secretary information, or manager information, also update your profiles-config.xml file. Use the following procedure to specify the additional required data needed for input to the FreeMarker template processor:

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

    2. Locate the <template/> element whose attribute name is equal to searchResults.

    3. Modify the <templateDataModel/> section, using the following example, to include the <templateData/> element for the required data.

    4. Save your changes.

    5. Check in the updated profiles-config.xml file.

    6. Restart the server.

    Example: 

    <template name="searchResults">
 <templateDataModel>
  <!--  include if you render workLocation, organization, department information -->
  <templateData>codes</templateData>
  <!--  include if and only if you render profile extension fields in the template -->
  <templateData>extensions</templateData>
  <!--  include if you render secretary name or email in the template -->
  <templateData>secretary</templateData>
  <!--  include if you render manager name or email in the template -->
  <templateData>manager</templateData>
 </templateDataModel>
</template>


Customize edit display fields

Edit the profileEdit.ftl file to customize edit display fields.

To edit configuration files, use the wsadmin client.

See Start wsadmin

Use the profileEdit.ftl template to customize the profile field display on the profile edit page.

  1. Start the wsadmin client: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

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

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

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

Field Type Description
config.sametime.enabled boolean Set to TRUE if Sametime awareness is enabled.
config.sametime.href string Specify the HREF value if Sametime awareness is enabled.
config.sametime.sslHref string Specify the SSL HREF value if Sametime awareness is enabled.
config.sametime.inputType string 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.

Field Type Description
nls.template.<nlsKey> string Defines the look-up string from the default templates resource bundle using the specified nlsKey value.
nls.<nlsBundleId>.<nlsKey> string Defines the 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.

Field Type Description
request.contextPath String Application context path.
request.path String Application context path.
request.query.<queryParameter> Map Specifies the map containing all query parameters and their values from the incoming request.
request.lang String 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.

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:

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:

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:

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:

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:

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:

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:

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.

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.

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.

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.

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 searching in Profiles.

Specify which properties the Profiles application exposes in its search index.

For information about the underlying Profiles search logic, see the How does search work in Connections Profiles wiki article.


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, use the wsadmin client.

See Start wsadmin

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: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  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.

    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 specific search requirements.

To edit configuration files, use the wsadmin client.

See Start wsadmin

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 the profiles-types.xml file.

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: 

        app_server_root\profiles\Dmgr01\bin

    where app_server_root is WAS installation directory and Dmgr01 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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required and is case-sensitive. To determine cell name, run wsadmin command:  
        print AdminControl.getCell()
      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i: 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  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 the profiles-types.xml file.

    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 the profiles-types.xml file 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, use the wsadmin client.

See Start wsadmin

Default mappings for uid and mail are provided. To use a mapping for loginId, replace AdmgrIN_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: 

    WAS_HOME/profiles/Dmgr01/bin

    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. 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, pick the node where the file is stored.

    2. 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, Linux, and IBM i only: The directory must grant write permissions or the command does not complete successfully.

      • cell_name is the name of the WAS cell hosting the Profiles application. This argument is required. It is also case-sensitive. To determine cell name, run wsadmin command:

        print AdminControl.getCell()

      For example:

      • AIX or Linux: 
        ProfilesConfigService.checkOutConfig("/opt/prof/temp","Cell01")

        Windows: 

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

      • IBM i 
        ProfilesConfigService.checkOutConfig("/temp","Cell01")

  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 Customizing 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 Customizing 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 Configure 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 Configure 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 Customizing edit display fields.

  7. Edit the widgets-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 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

Connections provides a quick way to share content with others. From anywhere in 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". 
    <To confirm changes made  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>
         </To confirm changes made >
    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 .

  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 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. For example, if you are using a widget that displays bookmarks for a specific tag, you can 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.


To confirm changes made 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.

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

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. 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 so users will see your changes the next time they log in, without having to clear their web browser cache.

Only perform this procedure if you made customization changes to the product user interface.

To edit configuration files, use the wsadmin client.

See Start wsadmin for details.

Each product web page downloads static script and stylesheets that do not change often. To optimize performance, these pages are cached for extended periods of time so that 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 Connections configuration files.

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        • When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp".

        • AIX, IBM i, and Linux only: The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

  2. Enter the following command to increment the value of the versionStamp property:

    LCConfigService.updateConfig("versionStamp","gmt_timestamp")

      yyyyMMdd.HHmmss

    LCConfigService.updateConfig("versionStamp","").

  3. After making changes, check the configuration files back in and you must do so in 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

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

    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: opt\IBM\Connections\data\shared\customization\strings\com.ibm.connections.metrics.ui.strings.ui.properties. Refer to Customize product strings for more information about strings customization.


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

    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, which isbased on a predefined layout, for the Metrics application to display.

The instructions that follow demonstrate the procedure for creating a simple report by using Cognos Report Studio. Follow the steps in the example to create a column chart that shows the total number of times that items were updated for each Connections applications. The report uses three basic sets of data:

  • The Measure is the quantity; the example report shows the total number of times that an event occurred (EVENT_COUNT).

  • The Dimensions are the qualifiers that describe what is being counted, for example, the applications where events occurred.

    The Categories are subsets of a dimension; for example, the SOURCE dimension contains categories for all applications.

  • The Data Series is the measure that is being tracked; the example report tracks "update events" across multiple applications so that you can compare the totals.

For more information about dimensions in the Metrics PowerCube, see PowerCube dimensions.

For more information about working with Cognos Report Studio, see the Report Studio User Guide.

  1. Choose a unique name for the report:

    A unique name 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 that your new report has a unique name.

    1. Open a browser and go to the Cognos dashboard by 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 jobtemplate job and click Set properties .

    5. Click the Job tab.
    6. Review the list of reports. If you see a name that matches 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 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 that the report generates.

      For this example, select Column; this type displays the available formats for a column chart.

    2. In the Insert chart window, select a specific format from the display that corresponds to the type of chart that you selected in the previous step.

      For this example, select any column chart format. Because the example tracks a limited data series, there is no data to stack and all of the column formats 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 your report:

    Begin with all categories and exclude the categories that 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 Edit 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 Add to copy it to the excluded Members list.

    9. Select DEFAULT in the Available members list and click Add to copy it to the excluded Members list.

      DEFAULT represents a special calculation that is not needed for this simple report, so you can 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 use the UPDATE type of the EVENT measure as the data series. Because this report tracks the total number of updates for each application, the data series contains only 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 includes each month or year that is 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 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. Go to the location where you saved the report, and select the new report.

    3. Click Set properties .

    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, copy the entire URL from the Default action url field.

    7. Click Close.

    8. Leave the Cognos dashboard open so that 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 ( from ?b_action= to 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 is not available to users until you add 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 is refreshed whenever Update is clicked, you must 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 jobtemplate job and click Set properties .

    4. Click the Job tab.

    5. Click Add.

    6. Locate the new report in the Available entries list and click Add to add the report to the Selected entries list.

    7. Click OK.

    8. Repeat substeps c-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, copy the entire URL from the Default action url field.

    7. 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. (To confirm changes made ) 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 2012.

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

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

    ..\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 – Specify 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. 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... 

    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 are displayed with a text label that does not link to any additional report. 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... 

    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 – Specify 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 in the "Seasonal products" category. 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 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.


Customize the Wikis welcome page

Customize the welcome page of the Wikis application.

You can change the default content of the welcome page to suit your needs. There are different versions of the content for the standard Wikis application, the Communities version of Wikis, and the SmartCloud version of Wikis.

For detailed information about editing property files, see the Property file strings topic.

  1. Open the following file for editing:

    com.ibm.lconn.share.services.handlers.wiki.nls.WikiWelcomeMessages_locale.properties

    where locale is the two-letter code that indicates the language that is used in the file; for example, en indicates the English language. The file is in the installedApps/Wikis.ear/share.services.jar:/src/com/ibm/lconn/share/services/handlers/wiki/nls directory.

  2. Edit any of the following attributes:

      WELCOME_PAGE.TITLE
      Name of the wiki.

      WELCOME_MESSAGE_HTML
      Welcome message in a standard wiki.

      WELCOME_MESSAGE_COMMUNITY_HTML
      Welcome message in a community wiki.

      WELCOME_CLOUD_MESSAGE_COMMUNITY_HTML
      Welcome message in a SmartCloud wiki.

  3. Save the file.

  4. Copy the file to the customizationDir/strings directory. If necessary, confirm to overwrite an existing file with the same name.


Security

Connections provides a flexible security infrastructure that supports an open, easily shareable data model.

Find out what security applications are provided by default in 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 Connections users for access to their data.

Connections now supports the OAuth 2.0 standard authorization protocol. Third-party applications ("consumer" applications) can use a combination of OAuth and the Connections API to access Connections data.

Before a consumer application can access a user's Connections data, an 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. "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 Connections activity stream and status updates.

As an 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 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 Settings > Application Access. This authorization management interface is customizable.

For general information on OAuth, see the OAuth web site at http://oauth.net/.

To add gadgets deployed externally, such as iGoogle gadgets, configure locked domains, which isolate semi-trusted gadgets, and prevents them from accessing SSO tokens, or using DOM access to the parent page of the gadget iFrame to forward sensitive data to external sites.

For more information on locked domains, refer to Enable locked domains.

To connect an OAuth 2 client with Connections using Connections APIs with the Open Authentication 2 protocol the supported flow is as follows:

Authorization code grant flow.

Authorization endpoint URL:

https://www.connections.example.com/oauth2/endpoint/connectionsProvider/authorize

Token endpoint URL:

https://www.connections.example.com/oauth2/endpoint/connectionsProvider/token

The /oauth2 context root is configurable as is any other Connections application via the IBM console. The change should be applied to the LotusConnections-config.xml in the "oauthprovider" service as follows: 

<sloc:serviceReference serviceName="oauthprovider"
enabled="true"  ssl_enabled="true"  bootstrapHost="admin_replace"
bootstrapPort="admin_replace"
clusterName="">
<sloc:href>
<sloc:hrefPathPrefix>/oauth2</sloc:hrefPathPrefix>
<sloc:static href="http://www.connections.example.com" ssl_href="https://www.connections.example.com"/>
<sloc:interService href="https://www.connections.example.com"/>
</sloc:href>
</sloc:serviceReference>


Manage the client application list

Use commands to manage the list of client applications that are allowed to prompt users for access to their Connections data, using the OAuth authentication protocol.

See the topic Running administrative commands for steps on executing oauthAdmin.py before running OAuth commands in 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 transmit authorization credential responses to the OAuth client.

    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 transmit authorization credential responses to the OAuth client.

    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()
    Return a count of known client applications. There are no parameters.

    Example: 

    wsadmin>OAuthApplicationRegistrationService.getApplicationCount()

2


Delete a client application

    OAuthApplicationRegistrationService.deleteApplication(String appId)
    Delete 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.


Install and enabling OAuth TAI

You need to install and enable the OAuth TAI in Connections.

  1. Before installing Connections 4.5 be sure to install the IBM WebSphere Application Server release 8.0.0.5 or higher.

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

    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 a maximum limit to the 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.
    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. 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 WAS admin 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: ==, !=, %=, ^=, <, >.

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

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

    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, 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')
      In order to see the secret, run the following command: 
      wsadmin>clientSecret = OAuthApplicationRegistrationService.getApplicationById('conn-ee').get('client_secret')  wsadmin>print clientSecret
      For example: 
      CdVFsLUyTGa9p8BaHZcNSir4i7sLcuk31XZMkhtXSHUcXGKI7HDeCONm89lf

  2. To enable auto-authorization for this gadget, the provider has to be configured to make it a privileged client. Modify the connectionsProvider.xml (for example, located in \IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\nameCell01\oauth20\) used 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 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 specifically designed to solve gadget use cases. 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 Connections 4.5 release supports an OAuth 2.0 consumer proxy that allows the Homepage component to surface gadgets in an OpenSocial container that interacts 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 Connections.

Perform any of the following tasks using the appropriate command:


Counting providers

    NewsOAuth2ConsumerService.countProvider()
    Return 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)
    Return 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)
    Return 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)
    Register or update 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)
    Delete 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)
    Return 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)
    Return 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)
    Return 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)
    Register or update 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".

      grantType
      The authorization grant type. Supported values are "code" or "client_credentials".

      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)
    Delete 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)
    Delete 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)
    Return 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)
    Return 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)
    Return 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.findGadgetBindingByUri("http://www.acme.com/mygadget", "connections_service")


Returning a single binding by widgetId

    NewsOAuth2ConsumerService.findGadgetBindingByWidgetId(string widgetId, string serviceName)
    Return 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")


Purge all tokens

    NewsOAuth2ConsumerService.purgeAllTokens()
    Purge all tokens persisted in the repository. This operation should be executed if the underlying encryption method has been modified.

Example: 

wsadmin>NewsOAuth2ConsumerService.purgeAllTokens()


Configure single sign-on

Set up single sign-on integration between Connections and other IBM products and third-party security products.


How single sign-on works

Connections uses single sign-on (SSO) to secure the transfer of user ID and password information used authenticate with the system. With SSO, users can switch to different applications without needing to authenticate again.

SSO is automatically enabled when 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. 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 WAS 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...

  1. Log in to WAS admin 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.

Ensure that you have enabled Use available authentication data when an unprotected URI is accessed.

For more information, see the Setting up federated repositories topic.


Enable single sign-on for Tivoli Access Manager

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

  • Connections supports the WebSphere cookie-based lightweight third-party authentication (LTPA) mechanism as an SSO solution for Tivoli Access Manager. 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.

  • Connections supports the use of SSL Transparent Path junctions with Tivoli Access Manager. 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 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...

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

    1. Log into WAS admin 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. Recreating the LTPA token might introduce errors. Refer to Clearing all scheduled tasks if this occurs.

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

    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:\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 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:/Tivoli/PDWeb/www-default/certs/pdsrv.kdb

    For more information about importing certificates, see the Adding certificates to the WebSphere trust store topic.

  4. Use the exported LTPA key to configure the transparent path junctions in Tivoli Access Manager.:

    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 Connections server for which Tivoli Access Manager is managing authentication. For example, IBM HTTP Server configured for 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. This value 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
        • /mobileAdmin
        • /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 -k 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.

      • 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 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. Create a default 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

  6. 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 Connections; for example: default
      • app_root is the root path to the 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 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.

      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

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

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

      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
      /connections/serviceconfigs
      /nav/common
      Content Manager /wsi
      /acce
      /dm
      Communities /communities/calendar/Calendar.xml
      /communities/calendar/oauth
      /communities/images
      /communities/recomm/oauth
      /communities/service/atom/oauth
      /communities/service/html/communityview
      /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
      /files/serviceconfigs
      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
      /metrics/serviceconfigs
      /cognos/servlet
      Moderation /moderation/oauth
      News /help
      /news/common/sand/static/
      /news/follow/oauth
      /news/microblogging/isPermitted.action
      /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
      /search/serviceconfigs
      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/serviceconfigs
      /wikis/static

    3. The Atom feeds on Connections servers use basic authentication because most feed readers are unable to authenticate with form-authentication. WebSphere Application Server and Connections applications authenticate these Atom HTTP requests through basic authentication as required. To attach the unprotected ACL to resources that 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 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 .

      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

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

  9. To get the activity stream on the Homepage to display, you must import an SSL certificate from the TAM server to the nodes.

    1. Navigate to SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore> \ signer certs.

    2. Restart the Homepage application.

    To get the ECM events to appear, the TAM certs have to be imported to the NodeDefaultTrustStore. If the TAM server and the Web Seal server are different, you need to import the cert from the Web seal server.

  10. For Connections Content Manager configure an additional set of steps for the FileNet Collaboration Services:

    1. To add properties, the administrator needs to edit the <FNCS_HOME>\configmanager\profiles\fncs-sitePrefs.properties file, where FNCS_HOME is the FNCS installation directory, before running the configuration wizard.

    2. Add the following properties to the fncs-sitePrefs.properties file at the end of the file after the comments and save it: 
      urlBaseService <your http url for the TAM and WebSeal proxy>  fncsServerURL <your http url for the TAM and WebSeal proxy>  fncsServerURLSecure <your https url for the TAM and WebSeal proxy>

    3. After setting the properties, you must complete the steps in Configure FileNet Collaboration Services for the Connections Content Manager.

  11. Configure Tivoli Access Manager to use form-authentication over HTTPS by updating webseald-server-name.conf. 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.

  12. (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 webseald-server-name.conf:

    ba-auth = none

  13. Configure content filtering by adding the following lines to webseald-server-name.conf:

      [filter-content-types]
      type = text/xml
      type = application/atom+xml
      [script-filtering]
      script-filter = yes
      rewrite-absolute-with-absolute = yes

  14. Configure Tivoli Access Manager as the reverse proxy for Connections. Update webseald-server-name.conf:

    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.

  15. 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/dmgrGR/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 WAS cell hosting the Connections application. This argument is case sensitive. If you do not know the cell name in the wsadmin client to determine it:

        print AdminControl.getCell()

      For example:

      LCConfigService.checkOutConfig("c:/temp","Cell01")

    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.

  16. Determine how you want the system to behave when users log out of Connections. By default, when users click Log out in the SSO environment, they are not fully logged out of Connections. Edit the IBM HTTP Server httpd.conf configuration file to implement the post-log out behavior. By default, the file is located in...

    • 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

  17. Add an ErrorDocument 500 statement to the httpd.conf file. This statement appears in the user's browser if an Connections application becomes unavailable.

  18. Save and close the httpd.conf file.

  19. Restart IBM HTTP Server.
  20. (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/dmgrGR/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 WAS installation directory
      • dmgrGR 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 WAS cell hosting the 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","Cell01")

    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.
  21. (Do not complete this step for Tivoli Access Manager with SPNEGO) Configure the cookie timeout value for 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()

  22. 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 webseald-server-name.conf. Check these values in the [session] stanza of webseald-server-name.conf 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
      # Setting 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

  23. Import the Tivoli Access Manager certificate into WAS trust store.

    For more information, see the Adding certificates to the WebSphere trust store topic.

  24. 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 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 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 that you need 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 that is 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 WAS. The SiteMinder Trust Association Interceptor (TAI) on the server verifies the information in the cookie and sets the User Principal that 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 WAS_HOME/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 Settings 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 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 Settings 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 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

      4. Check whether the PrevalidateCookie property exists in the Configuration Values as follows:

        • If PrevalidateCookie does exist, click Edit and set it to YES.

        • If PrevalidateCookie does not exist, click Add, add a parameter named PrevalidateCookie, and set it to YES.

        • Click OK and then click OK again to save the parameters.
    Notes:

    • When activated, the LogOffUri parameter clears the SMSESSION cookie and ensures that the user is logged out of all 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 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.

      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.

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

    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.

    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
    Content Manager /wsi
    /acce
    /dm
    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/common/sand/static/
    /news/follow/oauth
    /news/microblogging/isPermitted.action
    /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:

    Realm name Protected resource
    SM TAI Validation /siteminderassertion

    You must configure the Protected Resource of this realm to match the AssertionAuthResource parameter that you configured earlier for the Application Server Agent.

    Make sure that SM TAI honors SM session-based cookies and the triggered LTPA cookies to be generated by WAS.

  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 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 WAS 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 WAS 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. Add the following custom property under Global Security > Custom properties: com.ibm.websphere.security.performTAIForUnprotectedURI=true.

    8. Click OK and then click Save.

      Connections servers should be protected by both SM TAI and OAuth TAI. This is important for supporting the EE and Activities Stream features.

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

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/api/(.*) /blogs/oauth/roller-ui/rendering/api/$1/api/$2 [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/tags/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/tags/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/entries/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/entries/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/comments/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/comments/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/blogs/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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 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 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 Connections configuration by editing LotusConnections-config.xml.

    1. Use the following command to check out the configuration file:

      • execfile("app_server_root/profiles/dmgrGR/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 WAS installation directory
      • dmgrGR 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 WAS cell hosting the 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","Cell01")

    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. Specify 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 Connections deployment.

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

Advise 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 Connections Connector for IBM Lotus Quickr, enable single sign-on (SSO) between 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 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 Connections applications are deployed on servers in the same WAS 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 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 Connections and Lotus Quickr...

  1. On the Connections Deployment Manager:

    1. Log into WAS admin console as an administrator and 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 that you enter is valid: On the node where Lotus Quickr is installed, log into WAS admin 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...

    1. Log into WAS admin 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. Complete the following steps on the system that hosts the Deployment Manager:

    1. Log into WAS admin 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 – Type the password that you used for the Lotus Quickr key file that you exported.

        Confirm the password.

      • Fully qualified key file name – Specify the path and name of the Lotus Quickr key file that you exported.

    3. Click Import keys.

  4. Restart the Deployment Manager.


Enable single sign-on for Domino

If your organization uses 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 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 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 Connections application and switch to other applications without needing to authenticate again.

By default, applications deployed within the same WAS 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 where Connections and Domino use different LDAP directory configurations or are hosted in different WAS cells.

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. Configure the LDAP for Connections:

    1. Log into WAS admin console on the Deployment Manager.

    1. Click Security > Global security.

    2. Select Federated Repositories from the Available realm definitions field and then click Configure.

    3. Enter the realm name of the LDAP server in the Realm name field. For example: enterprise.example.com:389.

    4. Click Apply and then click Save.

    5. Synchronize the nodes.

    6. Restart your Connections deployment.
  2. Configure the domain name:

    1. Log into WAS admin console on the Deployment Manager.

    2. Click Security > Global security.

    3. In the Authentication mechanisms and expiration area, expand Web and SIP security and click Single sign-on (SSO).

    4. Enter your Connections domain name in the Domain name field, ensuring that you add a dot (.) before the domain name.

    5. Select the check boxes for Interoperability Mode (optional) and Web inbound security attribute propagation. Make sure Set security to HTTP Only is not enabled.

    6. Restart your Connections deployment.
  3. Export the LTPA key file:

    1. Log into WAS admin console on the Deployment Manager.

    2. Click Security > Global security.

    3. In Authentication > Authentication mechanism and expiration click LTPA.

    4. In the Password and Confirm password fields, enter the password that protects the exported key.

    5. Enter the file name of the key file to generate in the Fully qualified key file name field.

    6. Click Export keys.

    7. Click Apply and then click Save.

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

  5. Verify that the Domino server maps correctly between the user IDs stored in the LDAP that is used by 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.
  6. 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. Click Edit Server to change to Edit mode.

    5. Select the new Web SSO Configuration 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

Verify that you can switch between Connections applications without needing to authenticate more than once.


Enable single sign-on for standalone LDAP

Connections requires a federated repositories configuration, but you can enable 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 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 Connections.

By default, applications deployed on servers within the same WAS 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 Connections and a WebSphere Application Server configured for standalone LDAP...

  1. Log in to WAS admin 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, 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 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 Connections to use SPNEGO for single sign-on (SSO). This configuration permits users to sign in to the Windows desktop and automatically authenticate with Connections.

Verify that Connections works correctly without the SPNEGO authentication protocol.

Create a user account in the LDAP directory and add it to WAS 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 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 Connections to use Active Directory as the user directory.

For more information, see the Setting 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 WAS 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 Connections fail, including search indexing, notifications, and adding widgets.

To prevent such problems, map an account in Active Directory to the 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 WAS 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 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 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.

      If you subsequently change the password for the Active Directory account that you map in this step, 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.

      If you subsequently change the password for the Active Directory account that you map in this step, also change the password for the ConnectionsAdmin J2C alias.

  6. (Only required if you use Windows services for starting or stopping Connections) Edit your Windows services to use your Active Directory account instead of wasadmin to start and stop 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 Connections, and then create a keytab file that the Kerberos authentication service can use to establish trust with the web browser.

Configure Connections to use Active Directory as the user directory.

For more information, see the Setting 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 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 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 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...

  1. Synchronize the clocks of the systems hosting 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 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è.us.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 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 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...

    1. If Connections is not installed on the system that hosts the domain controller, copy the keytab file to the system where Connections is installed.

    2. Open a command prompt on the system hosting the Deployment Manager and Start wsadmin 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 WAS administrator.
      • SOAP_CONNECTOR_ADDRESS Port is the SOAP port for WAS 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 WAS root directory. Do not specify the path to the 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 WAS 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 V8.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.

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 WAS admin 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. Specify the SPNEGO filter:

    1. In the SPNEGO Filters area, click New and enter the following details:

        Host name
        Enter the URI for how the Connections environment is accessed. Typically, it is the hostname/alias of the HTTP server.

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

    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. Level of authentication that users must go through to access your 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 Connections:

      1. Select Applications > Application Types > WebSphere enterprise applications.

      2. Click the link to the first 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 Connections applications in the Enterprise Applications table.

    • Force users to log in to access Connections:

      1. Select Applications > Application Types > WebSphere enterprise applications.

      2. Click the link to the first 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 Connections applications in the Enterprise Applications table.

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

  11. Click Global Security. In the Authentication area, click LTPA if it is not already selected. Click Save.

  12. Synchronize all the nodes in your deployment.

  13. Stop and restart WebSphere Application Server:

    1. Stop all instances of WebSphere Application Server that host your 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 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...

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

  • Connections supports the WebSphere cookie-based lightweight third-party authentication (LTPA) mechanism as an SSO solution for Tivoli Access Manager. 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.

  • Connections supports the use of SSL Transparent Path junctions with Tivoli Access Manager. Connections does not support TCP type junctions or Tivoli Access Manager Standard junctions.

  • Verify that you can access 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 Connections application and switch to other applications within the product without having to authenticate again.

There are several different ways to configure SSO. The Connections DefaultAuthenticator protocol allows 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 Connections.

To set up SSO using Tivoli Access Manager with SPNEGO...

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

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


Results

After users sign in to the Windows desktop, they are automatically signed into 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.

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 Connections to use single sign-on with Computer Associates' SiteMinder and SPNEGO.

Before you can enable SSO, you must first install 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 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 that you need 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 that is 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 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 WAS_HOME/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 Settings 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 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 Settings 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 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 Settings 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 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

      4. Check whether the PrevalidateCookie property exists in the Configuration Values as follows:

        • If PrevalidateCookie does exist, click Edit and set it to YES.

        • If PrevalidateCookie does not exist, click Add, add a parameter named PrevalidateCookie, and set it to YES.

        • Click OK and then click OK again to save the parameters.
    Notes:

    • When activated, the LogOffUri parameter clears the SMSESSION cookie and ensures that the user is logged out of all 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.

      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.

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

    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.

    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
    Content Manager /wsi
    /acce
    /dm
    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/common/sand/static/
    /news/follow/oauth
    /news/microblogging/isPermitted.action
    /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:

    Realm name Protected resource
    SM TAI Validation /siteminderassertion

    You must configure the Protected Resource of this realm to match the AssertionAuthResource parameter that you configured earlier for the Application Server Agent.

    Make sure that SM TAI honors SM session-based cookies and the triggered LTPA cookies to be generated by WAS.

  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.

    Realm name Protected resource
    IIS_Realm /

  16. Create the following rules for this 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 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 WAS 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 WAS 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. Add the following custom property under Global Security > Custom properties: com.ibm.websphere.security.performTAIForUnprotectedURI=true.

    8. Click OK and then click Save.

      Connections servers should be protected by both SM TAI and OAuth TAI. This is important for supporting the EE and Activities Stream features.

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

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/api/(.*) /blogs/oauth/roller-ui/rendering/api/$1/api/$2 [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/tags/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/tags/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/entries/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/entries/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/comments/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/comments/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/oauth/(.*)/feed/blogs/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)

    RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L]

    RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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/(.*)

    RewriteCond %{REQUEST_URI} !^/blogs/oauth/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 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 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.

Verify that 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
    To confirm changes made . 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
    This value 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 Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the Connections applications. To change the traffic that is allowed from non-Connections services, you must explicitly configure it.

This task is typically not required. Only perform it if you want to display information from an external service within Connections. The most common action that needs to be performed is step 4 if you wish to enable feeds from external sites.

When configuring the AJAX proxy to allow 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 Connections applications. When an 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 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 Configure the AJAX proxy for a specific application for more details. To configure the AJAX proxy...

  1. Access the common AJAX proxy configuration template file:

    1. Go to:

      WAS_HOME/profiles/Dmgr01/bin

      where Dmgr01 is the Deployment Manager profile directory; this directory is usually called dmgr01. For example, on Windows, the directory is C:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

      You must run the command to Start wsadmin from this specific directory because the Jython files for the product are stored there. If you start the client from a different directory, the execfile() command does not work correctly.

    2. Enter the following command to Start wsadmin:

      • AIX or Linux: ./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS_PORT

      • IBM i: wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS_PORT

        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 the Administrator role on IBM WebSphere Application Server. This administrator must be configured at the cell level, not at the cluster, node, or server level.
      • admin_password is the password of WAS administrator.
      • SOAP_CONNECTOR_ADDRESS_PORT is the SOAP port for WAS deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not have to specify this parameter. If you are not using the default value and you do not know the port number, you can look up its value in WAS Integrated Solution Console. To look up the SOAP port number, complete the following steps:

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

      • IBM i: wsadmin -lang jython -username primaryAdmin -password password -port 8879

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

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

    • To allow a particular service to run on your network configured with SSO, and to pass cookies for LTPA tokens and TAM or Siteminder to the service, use the following <proxy:cookies> pattern: 
      <proxy:policy url=" http://my.network.com/service/*"
        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>content-type</proxy:header>
            <proxy:header>accept-encoding</proxy:header>
            <proxy:header>uit</proxy:header>
            <proxy:header>pst</proxy:header>
            <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>If-.*</proxy:header>
            <proxy:header>Pragma</proxy:header>
            <proxy:header>Cache-Control</proxy:header>
            <proxy:header>X-Update-Nonce</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>iwaSSL</proxy:cookie>
            <proxy:cookie>iwaSSL2</proxy:cookie>
            <proxy:cookie>JSESSIONID</proxy:cookie>
            <proxy:cookie>has</proxy:cookie>
            <proxy:cookie>PD-H-SESSION-ID</proxy:cookie><!-- TAM -->
            <proxy:cookie>PD-S-SESSION-ID</proxy:cookie><!-- TAM -->
            <proxy:cookie>SMIDENTITY</proxy:cookie><!-- SiteMinder -->
            <proxy:cookie>SMSESSION</proxy:cookie><!-- SiteMinder -->
        </proxy:cookies>
    </proxy:policy>

  4. The following policy allows GET requests to be passed to any web address. To allow 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 Connections.


Configure the AJAX proxy for a specific application

The AJAX proxy configuration for all of the Connections applications is defined in the proxy-config.tpl file. 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 typically required. Only perform it if you want to display information from an external service within Connections. You can define a custom proxy configuration for the Activities, Communities, Home page, Profiles, and Search applications, but not the other Connections applications. The most common action that needs to be performed is step 5 if you wish to enable feeds from external sites.

By default, the Connections AJAX proxy is configured to allow cookies, headers or mime types, and all HTTP actions to be exchanged among the Connections applications. To change the traffic that is allowed from non-Connections services, you must explicitly configure it

To configure the AJAX proxy for a specific application...

  1. Go to the directory on WAS 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-appname-config.tpl
    where appname is the name of the application for which you want to create a custom proxy configuration. Valid entries for appname 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 by completing the following steps.

    1. Go to:

      WAS_HOME/profiles/Dmgr01/bin

      where Dmgr01 is the Deployment Manager profile directory; this directory is usually called dmgr01. For example, on Windows, the directory is C:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

      You must run the command to Start wsadmin from this specific directory because the Jython files for the product are stored there. If you start the client from a different directory, the execfile() command does not work correctly.

    2. Enter the following command to Start wsadmin:

      • AIX or Linux: ./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS_PORT

      • IBM i: wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS_PORT

        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 the Administrator role on IBM WebSphere Application Server. This administrator must be configured at the cell level, not at the cluster, node, or server level.
      • admin_password is the password of WAS administrator.
      • SOAP_CONNECTOR_ADDRESS_PORT is the SOAP port for WAS deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not have to specify this parameter. If you are not using the default value and you do not know the port number, you can look up its value in WAS Integrated Solution Console. To look up the SOAP port number, complete the following steps:

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

      • IBM i: wsadmin -lang jython -username primaryAdmin -password password -port 8879

        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 
      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 WAS cell hosting the Connections application. This argument is required. To determine cell name, run wsadmin command: 
        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>

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

    • To allow a particular service to run on your network configured with SSO, and to pass cookies for LTPA tokens and TAM or Siteminder to the service, use the following <proxy:cookies> pattern: 
      <proxy:policy url=" http://my.network.com/service/*"
        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>content-type</proxy:header>
            <proxy:header>accept-encoding</proxy:header>
            <proxy:header>uit</proxy:header>
            <proxy:header>pst</proxy:header>
            <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>If-.*</proxy:header>
            <proxy:header>Pragma</proxy:header>
            <proxy:header>Cache-Control</proxy:header>
            <proxy:header>X-Update-Nonce</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>iwaSSL</proxy:cookie>
            <proxy:cookie>iwaSSL2</proxy:cookie>
            <proxy:cookie>JSESSIONID</proxy:cookie>
            <proxy:cookie>has</proxy:cookie>
            <proxy:cookie>PD-H-SESSION-ID</proxy:cookie><!-- TAM -->
            <proxy:cookie>PD-S-SESSION-ID</proxy:cookie><!-- TAM -->
            <proxy:cookie>SMIDENTITY</proxy:cookie><!-- SiteMinder -->
            <proxy:cookie>SMSESSION</proxy:cookie><!-- SiteMinder -->
        </proxy:cookies>
    </proxy:policy>

  5. The following policy allows GET requests to be passed to any web address. To allow 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-appname-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 WAS hosting Connections.

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 Connections server to accept LTPA tokens or the TAM or SiteMinder cookies in an SSO environment. This task is necessary if you want to configure single sign-on between Connections and the servers defined in the proxy configuration file to forward a specific list of cookies.

  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:

        WAS_HOME/profiles/Dmgr01/bin
        For example, on Windows: 
        C:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

        You must run the following command to Start wsadmin 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 Connections component does not work correctly.

      2. Enter the following command to Start wsadmin:

        • AIX or Linux: 
          ./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port

          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 WAS administrator.
        • SOAP_CONNECTOR_ADDRESS Port is the SOAP port for WAS. 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 WAS Integrated Solution Console. To look up the SOAP port number, perform the following steps:

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

          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 Configure the AJAX proxy for information about how to create this file. To access the custom configuration template file: 

      execfile("$WAS_HOME/profiles/dmgrGR/bin/
 appnameConfig.py")
      where appname 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 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: 
      appnameConfigService.checkOutProxyConfig("temp_directory","cell_name")

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

    For a TAM or SiteMinder SSO environment, include the following declarations: 

    <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>iwaSSL</proxy:cookie>
    <proxy:cookie>iwaSSL2</proxy:cookie>
    <proxy:cookie>JSESSIONID</proxy:cookie>
    <proxy:cookie>has</proxy:cookie>
    <proxy:cookie>PD-H-SESSION-ID</proxy:cookie><!-- TAM -->
    <proxy:cookie>PD-S-SESSION-ID</proxy:cookie><!-- TAM -->
    <proxy:cookie>SMIDENTITY</proxy:cookie><!-- SiteMinder -->
    <proxy:cookie>SMSESSION</proxy:cookie><!-- SiteMinder -->
</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.:

    • If you edited the proxy-config.tpl file 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 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. Go to:

      WAS_HOME/profiles/Dmgr01/bin

      where Dmgr01 is the Deployment Manager profile directory; this directory is usually called dmgr01. For example, on Windows, the directory is C:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

      You must run the command to Start wsadmin from this specific directory because the Jython files for the product are stored there. If you start the client from a different directory, the execfile() command does not work correctly.

    2. Enter the following command to Start wsadmin:

      • 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 the Administrator role on IBM WebSphere Application Server. This administrator must be configured at the cell level, not at the cluster, node, or server level.
      • admin_password is the password of WAS administrator.
      • SOAP_CONNECTOR_ADDRESS_PORT is the SOAP port for the WebSphere(r) 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 have to specify this parameter. If you are not using the default value and you do not know the port number, you can look up its value in WAS Integrated Solution Console. To look up the SOAP port number, complete the following steps:

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

        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 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. To confirm changes made . Specify 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 Connections.


Configure the library widget proxy

Add a proxy policy to the proxy-ecm-config.tpl file to enable communication between Connections and ECM servers.

To edit configuration files, you must use the IBM WebSphere Application Server wsadmin client.

See Start wsadmin for details.

When configuring the proxy to allow 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")

    2. 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/Linux only: The directory must grant write permissions or the command does not run successfully.

      • cell_name is the name of the WAS cell hosting the Connections application. This argument is case-sensitive, so type it with care. To get cell name, from wsadmin:print AdminControl.getCell()
      For example:

      • AIX or Linux:LCConfigService.checkOutProxyEcmConfig("/opt/temp","Cell01")

        Windows:LCConfigService.checkOutProxyEcmConfig("c:/temp","Cell01")

  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.example.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:cookie>LTPA</proxy:cookie>
                            <proxy:cookie>LTPA2</proxy:cookie>
                            <proxy:cookie>PD-H-SESSION-ID</proxy:cookie>
                            <proxy:cookie>PD-S-SESSION-ID</proxy:cookie>
                            <proxy:cookie>SMSESSION</proxy:cookie>
            </proxy:cookies>
    </proxy:policy>

  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. To confirm changes made . Specify 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 Connections server.

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.


Enable locked domains

Assuming that you have completed the server setup previously described, to enable locked domains in Connections, specify an additional atrribute in the LotusConnections-config.xml to ensure that only ConnectionsOpensocial application is mapped to the locked domain host. For added security, only the ConnectionsCommon.ear should be mapped to the locked host. Although no SSO tokens will be flowing from the host, this extra precaution limits exposure of your Connections infrastructure to potentially malicious gadgets.

For more information about locked domains refer to Understanding and configuring locked domains on the IBM Social Business Toolkit wiki.

  1. Add the new attribute to LotusConnections-config.xml by completing the following steps:

    1. Start the wsadmin tool.

    2. Access the Connections configuration file: 
      execfile("<$WAS_HOME>/profiles/<dmgrGR>/config/bin_lc_admin/ connectionsConfig.py")
      If you are prompted to specify which server to connect to, enter 1. This information is not used by the wsadmin client when you are making configuration changes.

    3. Check out the Connections configuration : 
      LCConfigService.checkOutConfig("/working_directory", "cell_name")

      ...where...

      • working_directory is the temporary working directory where the configuration XML and XSD files are copied to. The files are kept in this working directory while you change them.

      • cell_name is the name of the WAS cell hosting the Connections application. This argument is case sensitive. If you do not know the cell name, you can determine it by entering the following command in the wsadmin command processor: print AdminControl.getCell(), for example: 
        LCConfigService.checkOutConfig("/temp","Cell01")

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

    5. Add this attribute to LotusConnections-config.xml. 
      <sloc:serviceReference bootstrapHost="{locked.host.name}" bootstrapPort="2809" clusterName="" enabled="true" serviceName="opensocialLocked" ssl_enabled="true">
        <sloc:href>
            <sloc:hrefPathPrefix>/connections/opensocial</sloc:hrefPathPrefix>
            <sloc:static href="http://{locked.host.name.authority/http}" ssl_href="https://{locked.host.name.authority/https}"/>
            <sloc:interService href="https://{locked.host.name.authority/https}"/>
        </sloc:href>
    </sloc:serviceReference>

    6. Save LotusConnections-config.xml.

    7. Check in the changed configuration property :

      LCConfigService.checkInConfig()

    8. After making updates to deploy the changes: synchAllNodes()

  2. Restart your Connections server.
For example, this configuration could look like the following sample: 
<sloc:serviceReference bootstrapHost="hern120w.dyn.webahead.renovations.com" bootstrapPort="2809" clusterName="" enabled="true" serviceName="opensocialLocked" ssl_enabled="true">
        <sloc:href>
            <sloc:hrefPathPrefix>/connections/opensocial</sloc:hrefPathPrefix>
            <sloc:static href="http://hern120w.locked.com:9080" ssl_href="https://hernw120.locked.com:9443"/>
            <sloc:interService href="https://hern120w.dyn.webahead.renovations.com:9443"/>
        </sloc:href>
    </sloc:serviceReference>


Enable virus scanning

Edit configuration property settings to force the applications that handle uploaded files to scan all files for viruses.

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.

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

See the documentation for the virus scanner to determine how to disable file cleaning.

To edit configuration files, use the wsadmin client.

See Start wsadmin for details.

The Bookmarks and Home page applications do not implement virus scanning because no files or images are uploaded to those application databases. To enable virus scanning for Activities, Blogs, Communities, Files, Forums, Profiles, and Wikis...

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

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files: 
      LCConfigService.checkOutConfig("working_directory","cell_name")

      ...where...

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them.

      • When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory.

        • For example: "C:/temp".

        • AIX , and Linux only: The directory must grant write permissions or the command fails.

      • cell_name is the name of WAS cell that hosts the Connections application. If you do not know the cell name, display it by typing the following command in the wsadmin client: print AdminControl.getCell()

        This input parameter is case-sensitive.

    The IBM i operating system does not support virus scanning.

  2. From the temporary directory to which you just checked out the 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 in 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.

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.


Force traffic to be sent over SSL

You can configure Connections to force all traffic that passes between an 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 Configure the IBM HTTP Server for SSL in the Installing section of the Connections product documentation for more information.

To edit configuration files, use the wsadmin client.

See Start wsadmin for details.

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

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        • When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp".

        • AIX, IBM i, and Linux only: The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

  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 in 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. To secure session cookies...

    1. Log in to WAS admin console of the server hosting your Connections applications as the administrator.

    2. Expand Servers > Server Types, and then select WebSphere application servers.

    3. Click the server hosting 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. To secure LTPA tokens...

    1. From WAS admin 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.


Force 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 Connections application.

Do not perform this task if you plan to use the Connections Multi-Service Portlet plug-in. This extension does not function as expected when 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, 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 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 WAS 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, 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 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 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):

    1. Enable (by uncommenting) the mod_rewrite.so module (#LoadModule rewrite_module modules/mod_rewrite.so) in the IBM HTTP Server's httpd.conf file; otherwise, the first RewriteRule in the next step will prevent the IHS Server from starting up. The httpd.conf file is stored in the following directory by default:

      • AIX: /usr/IBM/HTTPServer/conf

      • IBM i: /www/HTTPServer_name/conf
      • Linux: /opt/IBM/HTTPServer/conf

        Windows: C:\IBM\HTTPServer\conf

    2. 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. In the httpd.conf file, add the following rules: 
      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]
      If you have OAuth enabled, the modifications in the httpd.conf file should be as follows: 
      RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)  RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/feed/(.*)
RewriteCond %{REQUEST_URI} !(.*)/api/recommend/entries/(.*)
RewriteRule ^/blogs/oauth/(.*)/api/(.*) /blogs/oauth/roller-ui/rendering/api/$1/api/$2  [R,L]  RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)  RewriteRule ^/blogs/oauth/(.*)/feed/tags/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/tags/atom/  [R,L]  RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)  RewriteRule ^/blogs/oauth/(.*)/feed/entries/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/entries/atom/  [R,L]  RewriteCond %{REQUEST_URI} !^/blogs/oauth/roller-ui/rendering/(.*)  RewriteRule ^/blogs/oauth/(.*)/feed/comments/atom(.*) /blogs/oauth/roller-ui/rendering/feed/$1/comments/atom/  [R,L]


Secure applications from malicious attack

Connections provides security measures, such as an active content filter and content upload limits, used 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 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 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 Configure 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 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.


Configure the active content filter for Blogs, Wikis, and Forums

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 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, use the wsadmin client.

See Start wsadmin for details.

  1. Edit LotusConnections-config.xml.

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        • When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp".

        • AIX, IBM i, and Linux only: The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

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


Configure the active content filter for Activities, Communities, and Bookmarks

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 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, use the wsadmin client.

See Start wsadmin for details.

  1. Edit LotusConnections-config.xml.

    1. Access the Connections configuration file: execfile("connectionsConfig.py")

      If you are prompted to specify a service to connect to, type 1 to select 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 by using a local file path, select the node where the file is stored. This information is not used by the wsadmin client when you are making configuration changes.

    2. Check out Connections configuration files:

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

      where:

      • working_directory is the temporary working directory to which configuration files are copied. The files are kept in this working directory while you edit them. Notes:

        • When you specify a path to the working directory on a system that is running Microsoft Windows, use a forward slash for the directory. For example: "C:/temp".

        • AIX, IBM i, and Linux only: The directory must grant write permissions or the command fails.

      • cell_name is the name of the WAS cell that hosts the Connections application. To get cell name: print AdminControl.getCell()

        This input parameter is case-sensitive.

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


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

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

    • /usr/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  # following lines 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 following rule.   # 
       See Configure 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.


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


Performance

Get recommendations from the IBM Collaboration Solutions Performance team on how to configure Connections for optimal performance.

Optimal tuning and the resulting system capacity can be affected by many factors, including the characteristics of the load on the system and the hardware used, including servers, disk subsystems, network topology, and more. Use the guidance provided in this wiki category as a recommended starting point for tuning an Connections deployment:

Connections wiki > Tuning for performance


Integrate with other products

Integrate Connections applications with other products, such as IBM Notes and IBM WebSphere Portal.

IBM provides a set of extensions, located on the IBM Collaboration Solutions Catalog Web site. These plug-ins enable the features and functions of Connections to be available in existing enterprise applications. To see what IBM plug-ins are available, see Integration Plug-ins Documentation for Connections 4.5.