Skip to content

HCL Connections Widget Setup

Add Huddo widgets into HCL Connections on-premise environments.

There are two ways to surface Ideas and Wikis inside a Community:

Community Highlights is preferred

Community Highlights needs no wsadmin access and no Communities restart, and community owners add the widgets themselves per page. Use the Community Widgets below only if you are not running HCEC.

Either way, Huddo Wikis also needs the Connections Wiki widget disabled, which does need wsadmin.


Community Highlights (HCEC)

Huddo Ideas and Wikis integrate with HCL Connections Engagement Center (HCEC, formerly XCC), so they can be added as widgets to a Highlights page.

Each app serves its own widget registration script:

Widget Script
Huddo Ideas https://[HUDDO_URL]/ideas/widgets/connections/xcc-onprem.js
Huddo Wikis https://[HUDDO_URL]/wikis/widgets/connections/xcc-onprem.js

Where [HUDDO_URL] is your Huddo URL including the /huddo prefix — e.g. connections.example.com/huddo.

HCEC loads a single custom.js

HCEC accepts one custom.js per environment, so these are fragments to merge, not files to upload as-is. Each one chains any existing XCC.X.init, so concatenation order does not matter and they coexist with an existing Huddo Boards registration.

  1. Download both scripts from your running deployment, e.g.

    curl -O https://[HUDDO_URL]/ideas/widgets/connections/xcc-onprem.js
    curl -O https://[HUDDO_URL]/wikis/widgets/connections/xcc-onprem.js
    
  2. Set the base path in each file to match your deployment.

    Near the top of each script is a single constant, shipped with the app's own base path:

    const IDEAS_BASE = "/ideas";     // ideas/xcc-onprem.js
    const WIKIS_BASE = "/wikis";     // wikis/xcc-onprem.js
    

    On Component Pack the apps are served under the /huddo prefix, so change them to:

    const IDEAS_BASE = "/huddo/ideas";
    const WIKIS_BASE = "/huddo/wikis";
    

    Danger

    Skipping this step is the usual cause of an empty widget — the iframe requests /ideas/community/connections, which does not exist on a prefixed install.

  3. Build custom.js by concatenating the fragments.

    cat ideas-xcc-onprem.js wikis-xcc-onprem.js > custom.js
    

    If you already run Huddo Boards, append them to the existing Boards custom.js instead of replacing it — see the Boards CEC setup.

  4. Open the HCEC admin page

    https://[CONNECTIONS_HOST]/xcc/main
    
  5. Click Customize, Engagement Center Settings, expand Customization Files and click Upload File, then select your custom.js.

    Note: you must have the admin role for the Customize button to appear. The file must be named custom.js.

  6. To validate:

    1. Open the Highlights application in a Community
    2. Click Customize, Widgets, then Huddo Ideas or Huddo Wikis
    3. The widget should render the community's Ideas or Wikis content

Each widget exposes a Title and Height setting in its HCEC editor. Height defaults to 600px.


Community Widgets

The original Communities widget mechanism. It requires wsadmin access to the Deployment Manager and a restart of the Communities application, and the widgets are then available to every community.

See HCL's Using the widgets-config.xml file for Communities for the full check out, edit and check in procedure.

  1. SSH to the WAS Deployment Manager

  2. Start wsadmin

    cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
    ./wsadmin.sh -lang jython -user wasadmin -password <password-here>
    
  3. Check out the widgets-config.xml file.

    execfile("communitiesAdmin.py")
    CommunitiesConfigService.checkOutWidgetsConfig("/LCCheckedOut", AdminControl.getCell())
    
  4. Edit the widgets-config.xml file.

    Find the resource element with the type of community, e.g. <resource ... type="community" ... >, then under <widgets>, then within <definitions> add the following, replacing [HUDDO_URL] with your Huddo URL including the /huddo prefix — e.g. connections.example.com/huddo:

    Ideas

    <!-- Huddo Ideas -->
    <widgetDef defId="HuddoIdeas" modes="view fullpage" url="{webresourcesSvcRef}/web/com.ibm.social.urliWidget.web.resources/widget/urlWidget.xml" themes="wpthemeNarrow wpthemeWide wpthemeBanner" uniqueInstance="true">
        <itemSet>
            <item name="resourceId" value="{resourceId}"/>
            <item name="width" value="100%"/>
            <item name="height" value="500px"/>
            <item name="url" value="https://[HUDDO_URL]/ideas/community/connections"/>
        </itemSet>
    </widgetDef>
    <!-- END Huddo Ideas -->
    

    Wikis

    <!-- Huddo Wikis -->
    <widgetDef defId="HuddoWikis" modes="view fullpage" themes="wpthemeNarrow wpthemeWide wpthemeBanner" uniqueInstance="true" url="{webresourcesSvcRef}/web/com.ibm.social.urliWidget.web.resources/widget/urlWidget.xml">
        <itemSet>
            <item name="resourceId" value="{resourceId}"/>
            <item name="width" value="100%"/>
            <item name="height" value="500px"/>
            <item name="url" value="https://[HUDDO_URL]/wikis/community/connections"/>
        </itemSet>
    </widgetDef>
    <!-- END Huddo Wikis -->
    

    Also disable the Connections Wiki widget

    While the file is checked out, make the edits in Disable the Connections Wiki Widget too. Then check in and restart once.

  5. Check in the widgets-config.xml file.

    CommunitiesConfigService.checkInWidgetsConfig("/LCCheckedOut", AdminControl.getCell())
    
  6. Restart the Communities application via the ISC

    Tip

    If widgets no longer load in Communities and you see errors in the browser console like:

    The following error occurs when retrieving widgetProcess production.
    com.ibm.jsse2.util.h: PKIX path building failed: com.ibm.security.cert.IBMCertPathBuilderException: unable to find valid certification path to requested target
    

    then please ensure the Connections domain root certificate is trusted in the WebSphere ISC. This can be added using Retrieve from port under SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates

  7. Optional. Install the extensions for Connections Customizer. This includes a fix for the Community Widget that enables attachments to be downloaded as well as multiple new integrations for Connections.


Disable the Connections Wiki Widget

Required for Huddo Wikis, whichever way you add the Wikis widget — Community Highlights or Community Widgets.

Every new community creates its own Connections wiki, which then has to be migrated. Disabling the Connections Wiki widget stops these being created and avoids confusion between the old and new wikis.

If you are adding the Community Widgets, make these edits in the same check out. Otherwise:

  1. SSH to the WAS Deployment Manager and start wsadmin

    cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
    ./wsadmin.sh -lang jython -user wasadmin -password <password-here>
    
  2. Check out the widgets-config.xml file.

    execfile("communitiesAdmin.py")
    CommunitiesConfigService.checkOutWidgetsConfig("/LCCheckedOut", AdminControl.getCell())
    
  3. Edit the widgets-config.xml file.

    Find the Connections Wiki widget definition, <widgetDef defId="Wiki" ... >, in the <resource ... type="community" ... > element.

    1. Stop new communities getting a Connections wiki. At the end of the community resource, under <templates>, find <template id="default"> and remove (or comment out) the line that adds the Wiki widget:

      <!-- Connections Wiki replaced by Huddo Wikis
      <widgetInstance defIdRef="Wiki" instanceId="Wiki1" uiLocation="col1"/>
      -->
      

      Wiki widget in the default community template in widgets-config.xml

      Optional. If you added the Huddo Wikis Community Widget, add an instance of the Huddo Wikis widget in its place:

      <widgetInstance defIdRef="HuddoWikis" instanceId="HuddoWikis1" uiLocation="col1"/>
      
    2. Remove the Connections Wiki widget from the Add Apps menu. Add showInPalette="false" to the Wiki widgetDef, so community owners can no longer add it:

      <widgetDef defId="Wiki" showInPalette="false" ... >
      

    Warning

    Do not comment out the whole Wiki widgetDef (as is done for Activities) until all community wikis have been migrated. Communities that already have the widget would lose it and their wiki content would be hidden from members.

  4. Check in the widgets-config.xml file.

    CommunitiesConfigService.checkInWidgetsConfig("/LCCheckedOut", AdminControl.getCell())
    
  5. Restart the Communities application via the ISC