Skip to main content

Best Practice: How Code42 Integrates MindTouch with Zendesk

code42_square.png
Written by Renee Schaefer
Documentation Team Lead at Code42
This page applies to:MindTouch Responsive


Unsupported! Content on this page is not supported by MindTouch. Please search our Success Center for supported content.


The flexibility of both MindTouch and Zendesk provides customers of both platforms numerous integration options. This article explains how to automatically search the content of a MindTouch site directly from the Zendesk ticket submission form.
 

How it Works

When Code42 customers choose "Submit a Ticket" from our MindTouch site, or when they choose "Create a Request" from the Code42 Zendesk, they are taken to our Zendesk ticket submission form.

User Experience

From a user perspective, this is how the form works.

  1. In the ticket submission form, enter your account email address.
  2. In the Subject field, begin typing an email subject.
  3. Shortly after you begin typing your subject, a search of the Code42 MindTouch site for matching articles is executed and the page presents you with up to five suggested help articles. 
  4. The search results display article title, Overview text, and article URL. 


 

  1. At that point, you can either choose an article or you can continue completing the ticket submission form to request help from our Customer Champion team.

Behind the Scenes

To make this work, we created our own Zendesk extensions: a Global CSS widget and a Global JavaScript widget. We are currently using Zendesk Classic. If you are using Zendesk Help Center, then your process will be slightly different.

Coding the JavaScript Widget

The Global JavaScript widget performs searches by making a MindTouch API call. Then it creates a <div>, where search results are inserted and presented to the customer. The code is below. Search results are filtered to include pages and exclude attachments. The "notrack" parameter is set to "false" so the searches are logged in the MindTouch Search Report.


$j(document).ready(function() {  
    (function($) {
        var checkForTopicsElement = function() {
            if ($('#suggestions_for_new_topic').length === 0) {
                $('#ticket_subject').closest('div').append($('<div id="suggestions_for_new_topic"><div class="related-topics-header"><h3 class="ticket-suggestion-header">Related articles</h3><p><strong>The following articles may help resolve the issue that you are experiencing.</strong></p></div><div class="frame ticket-form-frame"><div id="topic_suggestions"></div><a href="#" target="_blank" class="icon-padded" id="moreResults">More articles</a></div></div>').hide().fadeIn(800));
            }
        };
        var moreResults = function(search) {
            $('#moreResults').attr('href', 'http://mysite.mindtouch.us/Special:Search?search=' + search);
        };
        var buildResult = function(result) { //
            var builtResult = '';
            builtResult += '<li class="suggestions articles ticket-subject-result"><a href="';
            builtResult += result.uri;  
            builtResult += '" tabindex="-1" target="_blank">';
            builtResult += result.title; 
            builtResult += '</a>';
            builtResult += '</li>';
            builtResult += '<p class="icon-padded">';
            builtResult += result.content;
            builtResult += '</p><p class="icon-padded" style="font-size: 9px"><a href="';
            builtResult += result.uri;
            builtResult += '">';
            builtResult += result.uri;
            builtResult += '</a></p>';
            return builtResult;
        };
        var delay = (function() {
            var timer = 0;
            return function(callback, ms) {
                clearTimeout(timer);
                timer = setTimeout(callback, ms);
            };
        }());
        Zendesk.displayResults = function(data) {
            if (data.search["@count"] !== "0") {
                checkForTopicsElement();
                var results = '';
                if (data.search["@count"] === "1") {
                    var result = data.search.result;
                    if (result.hasOwnProperty('page')) {
                        results += buildResult(result);
                    }
                } else {
                    $.each(data.search.result, function(i, val) {
                        if (val.hasOwnProperty('page')) {
                            results += buildResult(val);
                        }
                    });
                }
                var lastSuccessfulSearch = $('#ticket_subject').val();
                moreResults(encodeURIComponent(lastSuccessfulSearch));
                $('#topic_suggestions').html(results);
            }
        };
        Zendesk.bindRelatedTopics = function() {
            $('#ticket_subject').keyup(function() {
                var searchInput = this;
                delay(function() {
                    if (searchInput.value.length === 0) {
                        return;
                    }
                    var currentSearch = searchInput.value;  //Current search input value
                    $.ajax({  //Begin jQUery ajax call
                        url: 'https://mysite.mindtouch.us/@api/deki/site/query',  //URL to query
                        data: {  //Query data to send to MindTouch
                            'dream.out.format': 'jsonp',  //Allow cross-domain requests from Zendesk to MindTouch
                            'dream.out.pre': 'dataWork',  
                            q: currentSearch,  //Use currentSearch variable defined above
                            limit: 5,  //Limit search results to 5
                            constraint: 'namespace:main AND type:wiki',  //Apply same default search constraints as Special:Search
                            notrack: false  //Track results in MindTouch Search Report
                        },
                        dataType: 'jsonp',  //jQuery data type to enable jsonp / cross-domain requests
                        jsonp: 'callback',
                        jsonpCallback: 'dataWork',  //On success, process data
                        success: function dataWork(data) {  //Process data
                            Zendesk.displayResults(data);
                        }
                    });  //End jQuery ajax call
                }, 300);  //Wait 300 ms before searching
            });
        };
        Zendesk.bindRelatedTopics();
        if ($('#ticket_subject').length > 0) {
            $('#ticket_subject').trigger('keyup');
        }
    }(jQuery));
});

Coding the CSS Widget

The Global CSS widget controls how the search results appear to your users. The below image shows the IDs and classes used on our form.


Our CSS:

.ticket-subject-result {
  display: block;
  padding-top: 2px;
  padding-bottom: 2px;
  background: url(imagepathandname.png) no-repeat !important;
}
#suggestions_for_new_topic {
  display: block;
  width: 98%;
}
.ticket-suggestion-header {
  text-transform: uppercase;
  font-size: 16px;
  color: #FE5000;
  font-weight: normal;
}
div.frame.ticket-form-frame {
  width: 98% !important;
  border: 0 none;
  padding: 3px 0 0 0;
  background: none;
}
.icon-padded {
  padding-left: 17px;
}

Steps to Install in Zendesk

To install this integration in Zendesk Classic, follow the steps below.  Zendesk's official documentation on installing widgets is available at support.zendesk.com. If you are using Zendesk's new interface, you must create Zendesk apps, instead.

If you have the Zendesk Plus or Enterprise plan, we recommend first creating the widgets in your Zendesk sandobx to test functionality before releasing to your production Zendesk.

Create the Widgets

To install this integration into your Zendesk Helpdesk, you must create two widgets, a Global JavaScript widget and a Global CSS widget. To create the widgets:

  1. Sign into your Zendesk Helpdesk as an administrator.
  2. Go to Settings > Extensions.
  3. On the Widgets tab, select add widget.
  4. Under Select Widget to Add, choose Global JavaScript or Global CSS.
    It does not matter whether you create the JavaScript widget or the CSS widget first.
  5. Enter a Title.
  6. Next to Available for, choose who you'd like to access the widget.
    Code42's Zendesk is 100% public and anyone can submit a help request. We've chosen "People who are not agents" for both widgets. This means that the MindTouch search is available to anyone (excluding agents) who visits our Submit a Request form - even people who are not signed into our Zendesk.
  7. In the Content box, enter your JavaScript or CSS code.
  8. Below Content, make sure Create widget is selected and then Submit.

Repeat the above steps for your other widget.

Once the widgets have been created, they should be active in your Zendesk "Submit a Request" form and ready to use.