Jivespace Community Blog

Support Design Introduction

communities@jivesoftware.com — Thu, 20 Nov 2008 21:47:06 GMT

Supportal

This is the first in a series of upcoming blog posts where we will delve into the details behind our Supportal. As most of our customers are already aware, the Supportal is Jive's Clearspace customization that transforms generic communities into personal communities where Jive collaborates directly with our customers via cases, documents, and projects.

This first post will provide the high-level overview, overriding design goals, business goals, and additional benefits to the Supportal. Future posts will delve into the business decision details, and the architecture.

The Name

People often ask how the name Supportal came to be. When it comes to overall creativity, I am horrible. In this project's infancy, I used Customer Portal, Customer Support Portal, Support Portal, and many other terms as names. Will French, Jive's Senior Support Engineer, and now the Supportal Development Lead, abbreviated Support Portal, to Supportal (likely making fun of me talking too fast), and the name stuck. It also gets rid of that stigma around the word "portal" as well!

Reasons for the Supportal

The Supportal was created to resolve's Support's own business pains. Prior to identifying the business pains however, we set 3 main overriding goals for the project:

Simplicity: The goal of the supportal is to solve business pain. Too many other support sites are tough to use and hard to navigate. Creating a case needs to be as simple and easy as possible. We continue this philosophy on upcoming features, ensuring that additional features add benefit without causing pain.
Accessibility: Customers weren't getting the information they needed, and people within Jive were not seeing the information they needed. The solution needed to include as many people as possible, while still being private so that only Jive and the customer can see the information.
Usability: Jive prides itself on this, and this is something that's always on our list. Making the Supportal as usable as possible is also a guiding factor we focused on during the first iteration and continue to improve upon.

With the overriding goals set, we identified the following business goals:

Create a solution where customers can go to create all their cases, regardless of severity
Replace email with an online system as the mode of communication
Recreate survey information. Associate the survey to the case.
Integrate Discussions (only community) with cases to provide customers with a single location to get their answer.
Provide customers the ability to create public cases, allowing others (outside Jive support) to read, contribute, and resolve, while ensuring that Jive Support will answer your issue.
Provide the same functionality (email) for customers who refuse to use the new system.
Remove manual customer and contract validation process

Solution

With the business goals identified, we realized that we had to integrate with our online community. Clearspace provided communities (security for each customer), email notification, reply by email, discussions, and a means to replace email as the primary mode of communication. 80% of the work was done for us. The missing parts were:

Auto-creation of customer communities via account, customer, and contract information in Salesforce
Validating customer ability to create cases upon user login
Adding meta data into customer community discussions, allowing them to become cases.
Customizing customer communities to show cases instead of discussions.
Synchronizing the cases (specifically the meta data) with Salesforce.
Paging for Severity 1 cases
Surveys
Creating cases via email

The following blog posts are going to delve into these sections providing more information behind each business goal, and how we customized Clearspace to solve the goal.

Additional Benefits

As with many solutions, we quickly realized that the Supportal can be used for more than just customer cases. The first additional use case for the Supportal was identified when our professional services team started using Clearspace's project functionality within the Secure Communities. This was exactly what Clearspace Projects were intended for, and the Supportal solved our PS department's communication requirements perfectily with no additional customizations.

We also have experienced a slight decrease in overall cases due to the increased visibility of the cases. Managers will frequently apply a community watch so that they receive emails whenever anyone creates a case in their community. We have had managers reply to a case telling us to disregard the case due to it being something they need to solve internally. We have also had managers follow up with their team directly when issues are stagnating, allowing us to resolve issues quicker.

Finally, the public case feature is being used for about 7% of all of our cases. Not a huge number, but definitely significant, and each additional case that is made public results in additional information in our community for others to see and use. This stat is without us pushing the feature at all.

Quick SSO on Clearspace 2.0

communities@jivesoftware.com — Tue, 01 Jul 2008 21:24:46 GMT

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" ></property>
    </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!.

Developing Plugins for Clearspace 2.0

communities@jivesoftware.com — Fri, 30 May 2008 22:59:05 GMT

Learn the basics of how to develop a plugin for Clearspace 2.0 from Jive engineer, Jon Garrison. Jon talks about spring, struts, and more in this video.

You can also download the Quicktime version (Caution: file is ~140MB), 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.

Theming in Clearspace 2.0

communities@jivesoftware.com — Mon, 12 May 2008 16:58:01 GMT

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.

Creating Dynamic Template Content in Clearspace

communities@jivesoftware.com — Fri, 08 Feb 2008 17:51:35 GMT

Jive's Rick Palmer, Professional Services Engineer, takes about 5 minutes to explain how to insert dynamic content into your Clearspace FreeMarker templates. The slide below provides more details.

Or you can download the Quicktime Movie (Caution! 122MB)

Introduction to Skinning Clearspace

communities@jivesoftware.com — Thu, 17 Jan 2008 19:28:35 GMT

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!