Customize the user interface 

The steps that perform to customize IBM Connections are the same no matter what part of the product you are customizing.

Before you begin

Start IBM Connections and review the product user interface to determine which areas of the product you want to customize.
Attention: This documentation is provided to help you customize your deployment of IBM Connections. IBM Support can address questions about the customization process, but cannot address questions about the particulars of your customization. 

About this task

The IBM Connections 3.0.x user interface style was implemented according to the guidelines defined in the IBM Lotus User Interface Developer Documentation 2.1.   


  1. In the web application source directories for the applications, find the file that serves as the source of the area of the product that you want to edit.

      The default location for the web application directory for each application is: <WAS_home>/profiles/<profile_name>/installedApps/<cell_name>/<application_name.ear>/<application_name.war> where:

      • <WAS_home> is the directory to which you installed IBM WAS

      • <profile_name> is the profile to which you installed one of the IBM Connections applications

      • <cell_name> is the cell to which you installed the application

      • <application_name.ear> is the EAR file name for the application

      • <application_name.war> is one of the following file names:

          Table 1. Application WAR files
          Application File name
          Activities oawebui.war
          Blogs blogs.war
          Bookmarks dogear.webui.war
          Communities comm.web.war
          Files qkr.share.files.war
          Forums forum.web.war
          Home page homepage.war
          Search search.war

  2. Turn on the customization debugging capability by adding a WAS environment variable named CONNECTIONS_CUSTOMIZATION_DEBUG and setting it to true. To do so...

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

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

    3. Type the following values into the fields:





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

  3. Copy the file that you want to edit from one of the web application directories listed in Step 1.

      The following list identifies the files that serve as the source of the user interface areas that are popular targets for customization:

      • Colors and fonts: /nav/common/styles/defaultTheme/custom.css and /nav/common/styles/defaultTheme/defaultTheme.css.

          Note: If your users view the product in Arabic, Hebrew, or another right-to-left language, also copy the defaultTheme_rtl.css file.

      • Error page: /nav/templates/error.jsp

      • Footer: /nav/templates/footer.jsp

      • Login page: /nav/templates/login.jsp

      • Navigation bar: /nav/templates/header.jsp

      And then paste the file into the appropriate directory. For example:

      • To edit the footer and have the same footer be displayed in all of the applications, store the updated footer file in the following directory:


      • 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, you would store the login.jsp file in the files subdirectory instead of the common subdirectory:


      To determine the appropriate directory to paste the file to...

      1. Figure out the base directory where your customizations should go. The base directory is defined during the installation; it is saved as a WAS variable named CONNECTIONS_CUSTOMIZATION_PATH. By default, the variable is set to <installdir>\data\shared\customization.

          Do one of the following things:

          • To make changes to all of the applications, copy the file into the common subdirectory.

          • To make changes to a single application only, copy the file into the subdirectory for that application.

          The customization directory contains the following subdirectories:


            Stores files to be applied to all of the applications. You most often copy edited files to this directory.


            Stores files to be applied to the Activities user interface only.


            Stores files to be applied to the Blogs user interface only.


            Stores files to be applied to the Bookmarks user interface only.


            Stores files to be applied to the Communities user interface only.


            Stores files to be applied to the Files user interface only.


            Stores files to be applied to the Forums user interface only.


            Stores files to be applied to the Home page user interface only.


            Stores files to be applied to the News user interface only.



            Stores files to be applied to the Advanced Search user interface only.


            Stores files to be applied to the Wikis user interface only.

          where <customizationDir> is the customization directory specified in the CONNECTIONS_CUSTOMIZATION_PATH environment variable, which by default is set to <installdir>\data\shared\customization.

      2. Add your file to the appropriate subdirectory within the common directory or within a specific application directory.

          Cascading stylesheets

          • To add custom styles to the product, edit the custom.css or custom_rtl.css files.

              Note: You only need the custom_rtl.css if your users view the product in Arabic, Hebrew, or another right-to-left language.

          • To make extensive changes to the color of the product, edit the defaultTheme.css file.

            Both CSS files are stored in the following directory:

          Error page




          Login page


          Navigation bar


            For the menus available from the navigation bar:

            /nav/templates/menu/communities.jsp /nav/templates/menu/apps.jsp

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

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

  6. When you are ready to publish your changes, turn off the customization debugging capability by setting the CONNECTIONS_CUSTOMIZATION_DEBUG WAS environment variable to false.

      Important: Do not leave the product in debug mode when using it in a production environment. It has a major impact on product performance. Only use debug mode while you are making and testing changes to the user interface during the testing phase. If you forget to turn off debug mode, an error is written to the log to remind you.

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

    1. From the dmgr host, go to...:


        where <app_server_root> is the WAS installation directory and <dm_profile_root> is the dmgr profile directory, typically dmgr01. For example, on Windows:

        C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\bin

        Attention: You must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.

    2. Enter the following command to start the wsadmin client:

      • AIX or Linux:

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


        • <admin_user_id> is the user name of a person in the Administrator role on the IBM WAS.

        • <admin_password> is the password of the WAS administrator.

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

          1. Open the WAS Integrated Solution Console for the deployment manager, and then select System Administration -> dmgr.

          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:

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

        • Microsoft Windows:

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

    3. Enter the following command to access the IBM Connections configuration file: execfile("")

        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. This information is not used by the wsadmin client when you are making configuration changes.

    4. Check out the IBM Connections configuration files:



        • <working_directory> is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.

            AIX and Linux only: The directory must grant write permissions or the command does not run successfully.

        • <cell_name> is the name of the WAS cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. To obtain the cell name:print AdminControl.getCell()

        For example:

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

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

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

        LCConfigService.updateConfig("versionStamp","<gmt_timestamp>") where <gmt_timestamp> is the GMT time. You can specify an empty string for the time stamp or provide a GMT value string. When you specify an empty string, the client calculates the current GMT time and updates the version stamp with that value. If you choose to provide the time, specify it using the following format: yyyyMMdd.HHmmss and specify the time in GMT. It is best to provide an empty string and let the client format the time stamp. For example: LCConfigService.updateConfig("versionStamp","").

    6. After making changes, check the configuration files back in and do so during the same wsadmin session in which you checked them out for the changes to take effect. See Apply common configuration property changes for information about how to save and apply your changes.

What to do next

See the following topics for more information about customizing specific areas of the product.

Parent topic


Related tasks
Apply common configuration property changes

November 15, 2011


Nov 15, 2011 3:09:31 PM Reworded sentence around the link to the oneui doc. 5 Nov 15, 2011 9:17:35 AM Updated the name of the link to the oneui doc per Michael's request. 4 Nov 15, 2011 9:00:25 AM Changed forums.web.war to forum.web.war. 3 Oct 21, 2011 10:11:20 PM Added link to the OneUI toolkit 2.1 documentation. 2 Jun 30, 2011 4:56:11 PM Added the support statement in the Attention note in Before you begin ... 1