Out with the old

In the past, when a customer wanted to check on the status of any of their open cases they would log into their secure space overview page and use the Community Open Cases widget. This widget was designed with a very simple goal in mind, just display the open cases with a bit of extra information and an emphasis on Severity 1 issues. This proved useful for quite some time and gave customers a good overview of what was going on with their community from a support perspective.

However, there was one major flaw. Customers had no way of interacting with this information and often found it very difficult to organize this data in a manner that they could use quickly and efficiently. Welcome, open cases widget 2.0!

The new and improved open cases widget

Along with our upgrade of the Supportal to SBS 3.0, I took on the job of updating this widget to provide customers with better control over their open cases. There are two major upgrades that I gave this widget which have enhanced the way people use it:

1. Cases broken down by Severity

Instead of displaying all the open cases in a potentially enormous group, I've broken down the display into 3 distinctive parts. This is especially helpful for customers with more than 10+ open support cases at a time and allows customers to quickly see if they have any Level 1 issues that they need to attend to quickly.

2. New case option available: Priority

To the right of every case status is a set of up and down buttons which control the individual priority of every issue (within their respective severity).

Okay great, so how do I use it?

Step 1: Log in

Log into the Supportal and visit your Company's secure space "Overview" tab

Step 2: Organize open cases

Browse through any open cases and use the "move up/move down" buttons to re-order them. All the moving on the screen will be done in real-time thanks to our good old friend Javascript. You may recognize these buttons from SBS, as they are used to control the location of profile fields on the admin console registration settings page.

Step 3: Don't forget to Save!

As of right now, your cases will be in the order you want on the overview page, but there is one final step. You will need to click the Save Settings button at the bottom right hand corner of the widget. This will take the current ordering of your widget and persist the case priorities to the database.

You will receive a friendly notification at the top of the widget that your Priority changes have been successfully saved, and you are done!

Well that's easy enough, how does it all work?

I'm glad you asked--it's really quite simple.

Displaying the widget

First off, the widget loads up all the non-closed cases within a secure space and puts them into three different Collections (one for each severity):

for (String caseID : caseIDs) {
    try {
        SupportCase supportCase = supportCaseManager.getSupportCase(Long.parseLong(caseID));
        String status = supportCase.getStatus();
        if (status != null && !caseStatusManager.isClosedStatus(status)) {
            String severity = supportCase.getSeverity();
            String priority = supportCase.getPriority();
            supportCase.setPriority(priority != null ? priority : "0");
 
            if(severity.equals("Level 1")) {
                openSev1Cases.add(supportCase);
                Collections.sort(openSev1Cases, new CaseComparator());
            }
            else if(severity.equals("Level 2")) {
                openSev2Cases.add(supportCase);
                Collections.sort(openSev2Cases, new CaseComparator());
            }
            else {
                openSev3Cases.add(supportCase);
                Collections.sort(openSev3Cases, new CaseComparator());
            }
        }
    }
    catch (NotFoundException e) {
        log.error("Could not retreive support case in OpenCasesWidget: " + e.getMessage());
    }
}

(Ideally this will get refactored soon to allow for more or less than 3 severities instead of being hard-coded. But it will work for now.)

The CaseComparator() orders all the currently open cases by their priority in the database. If nothing has yet been set, it will be put in the order that the cases were created.

The fancy effects

The cases are now sent to the template, where they are displayed in their respective severity grouping and automatically hooked into the Javascript functions that allow the up/down buttons to work. When you click on one of the buttons the following Javascript magic happens:

1. References to the required objects on the screen are loaded up using Javascript:

var moveUp = function(e, type) {
    Event.stop(e);
    var ansc = this.up(".case-field");
    if(ansc != undefined) {
        ansc.previous().insert({before: ansc});
        updateHiddenField(ansc, ansc.next());
    }
    updateOrderingAnchors(type);
}

2. A hidden priority field for each case is updated with the new ordering value:

var updateHiddenField = function(element, newElement) {
    var temp = element.select(".case-priority")[0].value;
    element.select(".case-priority")[0].value = newElement.select(".case-priority")[0].value;
    newElement.select(".case-priority")[0].value = temp;
}

3. The ordering of the case above (or below if the down arrow was pressed) will be swapped on screen and the list rebuilt:

var updateOrderingAnchors = function(type) {
    if(type == "1") {
        var elms = $("sev1-case-list-body").select("tr");
    }else if(type == "2") {
        var elms = $("sev2-case-list-body").select("tr");
    }else{
        var elms = $("sev3-case-list-body").select("tr");
    }
    elms.each(function(tr, i) {
        var anchors = tr.select(".field-moveup")[0];
        if (i <= 0) {
            anchors.update("<span class='move-up-disabled'>move up</span>");
        }
        else {
            anchors.update(new Element("a", {"class": "anchor-move-up", href: "#"}).update("move up"));
        }
        anchors = tr.select(".field-movedown")[0];
        if (i == elms.length - 1) {
            anchors.update("<span class='move-down-disabled'>move down</span>");
        }
        else {
            anchors.update(new Element("a", {"class": "anchor-move-down", href: "#"}).update("move down"));
        }
    });
    bindAnchors();
}

4. Now that the ordering is complete, you click the Save Settings button which makes a call to this Javascript to call a DWR method and display the nice notification at the top of the widget:

CasePriorityAction.setPriorities( values, {
    callback:function() {
        $('save-button').enable();
        $('jive-success-box').style.display = "block";
        Effect.Fade($('jive-success-box'),{delay: 3, duration: 5});
    }
});

Saving the data

The final step involves saving this to the database, which is done by the call to the setPriorities DWR method as noted above. This loops through all the cases on the screen and sets the priorities in the database accordingly:

public void setPriorities(List<String> values) {
    try {
        for(String value : values){
            String[] vars = value.split("-");
            SupportCase supportCase = supportCaseManager.getSupportCase(Long.parseLong(vars[1]));
            supportCase.setPriority(vars[2]);
            
            supportCaseManager.updateSupportCase(supportCase);
        }
    }
    catch (NotFoundException e) {
        log.error("Could not retreive case in CasePriorityAction: " + e.getMessage());
    }
}

I hope this information provides you with interesting insight into how our custom development allows us to work smarter and more efficiently with all our customers.  We want these new features to enrich your Jive experience!

As always, Jive welcomes any and all feedback about this feature and the Supportal in general.  Please comment on this post or start a discussion in our Supportal Feedback space.

Below is a small filter that I co-authored recently to integrate with Oracle Access Manager (formerly called Oblix). With the release of CS 2.0 we have totally revamped the authentication process and it is now built on spring-security (formerly acegi). Doing this makes it super easy for most of the typical SSO use-cases to be implemented in a reasonable amount of time.

Here was the use case:

1. User Makes initiial request and is not authenticated yet.

2. Webgate routes user to the corporate login page

3. User supplies auth credentials

4. Webgate authenticates the user

5. Webgate sets an Authentication Cookie that identifies this user to Webgate

6. Webgate adds custom HTTP Headers to a new request to the originally requested resource, in this case clearspace.

7. Clearspace ACEGI Filter chain executes for /*** path, this is where I inserted the OblixSSOFilter right before the form authentication.

8. The Filter executes, grabs the HTTP Header "jwt-dn" and extracts the users DN (the user name).

9. The Filter retrieves the User and creates an Authentication and allows the rest of the filters to execute.

The User is now authenticated. The Default authoprovider ultimatly loads the Users permission etc downstream using the default AuthProvider.

Here is the code for the filter. The filter is pretty straight forward. It looks at the incoming HttpServletRequest and attempts to retrieve a HTTP Header that was sent along from the webgate authentication form previously visited by the user, as stated above, in this particular scenario I was able to assume authentication would always be done prior to accessing clearspace.

 package com.jivesoftware.clearspace.sso.oblix;
 
 
import com.jivesoftware.community.aaa.AnonymousAuthentication;
import com.jivesoftware.community.aaa.JiveUserAuthentication;
import com.jivesoftware.base.*;
 
 
import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.FilterChain;
import java.io.IOException;
 
import org.acegisecurity.context.SecurityContextHolder;
import org.acegisecurity.Authentication;
import org.apache.commons.lang.StringUtils;
 
/**
 * Created by IntelliJ IDEA.
 * User: fred
 * Date: Jun 11, 2008
 * Time: 12:36:14 PM
 */
public class OblixSSOFilter implements Filter {
 
 
    private static String OAMHEADER = "jwt-unique";
    private static String HEADER_NAME = "jwt-dn";
    private UserManager userManager;
    //possible to use system properties to enable and change the header, for
    //now just keep it simple.
    private String oamHeaderName = HEADER_NAME;
    private boolean enabled = true;
 
    public OblixSSOFilter(){
        super();
    }
 
  
 
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
        Authentication authentication;
 
        if(!enabled){
            filterChain.doFilter(servletRequest,servletResponse);
        }else{
            try {
                Log.debug("executing oblix filter");
                HttpServletRequest request = (HttpServletRequest)servletRequest;
                String oamHeader = request.getHeader(getOamHeaderName());
                if(oamHeader != null){
                    Log.debug("got OAM header: " + oamHeader);
                    String userDN = extractUserDN(oamHeader);
 
                    User authenticationTarget = null;
                    try{
                        authenticationTarget = userManager.getUser(StringUtils.chomp(userDN));
                    }catch(UserNotFoundException e){
                        Log.error("no user found with username: " + userDN);
                    }
                    //Found an a
                    authentication = new JiveUserAuthentication(authenticationTarget);
                    authentication.setAuthenticated(true);
                }else{
                    Log.debug("no OAM Header");
                    authentication = new AnonymousAuthentication();
                }
                    SecurityContextHolder.getContext().setAuthentication(authentication);
               }catch (Exception e) {
                    Log.error("Exception occured while trying to authenticate OAM response: " + e.getMessage());
               }
           
               
          filterChain.doFilter(servletRequest,servletResponse);
       }
    }
 
 
    private String extractUserDN(String header){
        String userName = null;
        String[] elements = StringUtils.split(header,',');
        for(String element: elements){
            Log.debug("processing header: " + element);
            if(element.startsWith(OAMHEADER)){
                String[] uniqueID = StringUtils.split(element,'=');
                userName = uniqueID[1];
            }
        }
        return(userName);
    }
 
    public void destroy(){
    }
 
    public void setUserManager(UserManager userManager) {
        this.userManager = userManager;
    }
 
    public AuthenticationProvider getAuthenticationProvider() {
        return authenticationProvider;
    }
 
    public void setAuthenticationProvider(AuthenticationProvider authenticationProvider) {
        this.authenticationProvider = authenticationProvider;
    }
 
    public String getOamHeaderName() {
        return oamHeaderName;
    }
 
    public void setOamHeaderName(String oamHeaderName) {
        this.oamHeaderName = oamHeaderName;
    }
 
    public boolean isEnabled() {
        return enabled;
    }
 
    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }
}

I simply created a jar containing this one class that I deployed to the WEB-INF\lib directory of a expanded clearspace war file. You can use any IDE or VI and Ant to create the jar, nothing special about it or clearspace specific.

After I had the jar. I needed to tell clearspace about the filter. Since 2.0 there is a back door that can be utilized to override the default implementation of clearspace managers,DAOs and other spring managed beans, this back door is your jiveHome\etc directoy. Within the jiveHome\etc directory you can copy and modify the various spring context files packaged in the clearspace.jar file found in \WEB\lib. This is done by extracting the appropriate spring context file from the clearspace.jar file found in WEB-INF\lib, make your edits to it and copy it into \jiveHome\etc. In my case the authentication filter stack is configured in spring-securityContext.xml so I extracted that and made the changes listed below:

<!-- NOTICE THE ADDITION OF oblixSS0Filter -->
<bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">
        <property name="filterInvocationDefinitionSource">
            <value>
                CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
                PATTERN_TYPE_APACHE_ANT
                /upgrade/**=httpSessionContextIntegrationFilter, upgradeAuthenticationFilter, upgradeExceptionTranslationFilter,jiveAuthenticationTranslationFilter
                /post-upgrade/**=httpSessionContextIntegrationFilter, postUpgradeAuthenticationFilter, postUpgradeExceptionTranslationFilter,jiveAuthenticationTranslationFilter
                /admin/**=httpSessionContextIntegrationFilter, adminAuthenticationFilter, adminExceptionTranslationFilter,jiveAuthenticationTranslationFilter
                /rpc/xmlrpc=wsRequireSSLFilter, httpSessionContextIntegrationFilter, basicAuthenticationFilter, wsExceptionTranslator, jiveAuthenticationTranslationFilter, wsAccessTypeCheckFilter
                /rpc/rest/**=wsRequireSSLFilter, httpSessionContextIntegrationFilter, basicAuthenticationFilter, wsExceptionTranslator, jiveAuthenticationTranslationFilter, wsAccessTypeCheckFilter
                /rpc/soap/**=wsRequireSSLFilter, httpSessionContextIntegrationFilter, jiveAuthenticationTranslationFilter 
                /**=httpSessionContextIntegrationFilter, oblixSSoFilter formAuthenticationFilter, rememberMeProcessingFilter, feedBasicAuthenticationFilter, jiveAuthenticationTranslationFilter
            </value>
        </property>
    </bean>

<!-- DECLARE THE NEW FILTER -->
<bean id="oblixSSoFilter" class="com.jivesoftware.clearspace.sso.oblix.OblixSSOFilter">
        <property name="userManager" ref="userManager" />
    </bean>

As you can see the stack is configured to protect various resources within clearspace, you can add to this stack as required for your particular case, in my case it was simply a matter of declaring my filter, this allows spring to handle the creation of the object and changing the filter stack for the root path of the application to ensure the oblixSSOFilter fired off prior to formAuthentication. If the oblix filter is able to vouch for the user making the request (via the headers) the filter sets the Authentication on the SecurityContext and life moves forward with an authenticated user, if not, I allow it to fall to the next filter in the stack and the process repeats, with this new framework in place it makes it easy to support multiple authentication sources while still staying on the peripheral edges of the product which will help when it comes time to upgrade.

After you have made the changes, restart your clearspace instance and you should be up and running with your new filter.

Enjoy!.  

As you know, we changed a few things in our underlying architecture for Clearspace 2.0, including some changes in the Freemarker templates as a result of moving from Webwork to Struts along with some other changes. In this video, Matt Walker, Professional Services Engineer at Jive Software, talks about the process of upgrading existing themes along with plenty of best practices to make your themes more easily upgradeable in the future.

Matt also did an earlier screencast as an Introduction to Skinning Clearspace, which you might also want to watch along with this video.

You can also download the Quicktime version (Caution: file is ~200MB), or you can watch a larger version online, which will improve readability of embedded screenshots (recommended).

The entire presentation is also attached below as a PDF file.

Learn the basics of customizing your Clearspace theme in this introduction to skinning Clearspace with Matt Walker, professional services engineer (and juggler!) at Jive Software.

Or you can download the Quicktime version (Caution! ~100MB file)

You can also learn more about customizing Clearspace by visiting our documentation space!