Desk.com Widget for Dashing

README.md

Desk.com Dashing Widget

Dashing widget to display the number of cases in your Desk.com account. This widget uses Desk.com’s API and some code from the beautiful Hotness Widget by rowanu.

Preview

Dependencies

This widget requires oauth to authenticate with the Desk.com API, so you’ll probably have to add the following to your gemfile:

gem 'oauth'

Then run bundle install to make everything work perfectly!

Installation

To install this widget, run this command form your Dashing directory:

dashing install 8927307

Usage

To include this widget in your dashboard, add the following snippet of code to the dashboard layout file:

<li data-row="1" data-col="1" data-sizex="1" data-sizey="1">
  <div data-id="desk_cases" data-view="Desk" data-low="10" data-high="70" data-title="Unsolved cases"></div>
</li>

You may want to change the title of the widget, as well as the low and high values (more on this a bit further down).

Configuration

Obviously, you must add your Desk.com API credentials and the URI of your site to desk.rb for this widget to work. There are a few additional settings you may want to configure.

Cases will by default be fetched from Desk.com every 5 minutes, but this may also be changed.

Search Parameters

Personally, I only need to see the number of new and open cases not currently assigned to an agent. To change this, edit search_params. Read more about the search possibilities on this site: API:Cases:Fields

Color Scale

Depending on your usage, you may want to change what is defined as a low and high number of cases. To do this, change the values of data-low and data-high in the snippet above.

Colors

The default color scheme is advantage scale? by turtlejoy.

You may of course change the colors as you wish by editing desk.scss.

The future

I hope to some day extend this widget to fetch more than just the total count of cases. Contributions are welcome!

desk.coffee

class Dashing.Desk extends Dashing.Widget
  @accessor 'count', Dashing.AnimatedValue

  constructor: ->
    super

  onData: (data) ->
    node = $(@node)

    count = parseInt data.count # Count of cases.
    low = parseInt node.data 'low' # Count below this is good.
    high = parseInt node.data 'high' # Count above this is bad.

    level = switch
      when count <= low then 0
      when count >= high then 4
      else
        size = (high - low) / 3 # Number of colors in between low and high.
        num = Math.ceil (count - low) / size

    backgroundClass = "hotness#{level}"
    lastClass = @get "lastClass"
    node.toggleClass "#{lastClass} #{backgroundClass}"
    @set "lastClass", backgroundClass

desk.html

<h1 class="title" data-bind="title"></h1>

<h2 class="cases" data-bind="count"></h2>

<p class="updated-at" data-bind="updatedAtMessage"></p>

desk.rb

#!/usr/bin/env ruby
require 'oauth'

# All of the following configuration variables must be filled out!
configuration = {
  # Desk.com API Credentials.
  api_consumer_key: '',
  api_consumer_secret: '',
  access_token: '',
  access_token_secret: '',

  # General config.
  site_uri: '',
  search_params: 'status=new,open&assigned_user=none'
}

# Authorize to the Desk.com API.
consumer = OAuth::Consumer.new(
  configuration[:api_consumer_key],
  configuration[:api_consumer_secret],
  site: configuration[:site_uri],
  scheme: :header
)
access_token = OAuth::AccessToken.from_hash(
  consumer,
  :oauth_token => configuration[:access_token],
  :oauth_token_secret => configuration[:access_token_secret]
)

SCHEDULER.every '5m', first_in: 0 do |job|
  # Construct the full API URI.
  uri = configuration[:site_uri] + '/api/v2/cases/search?page=1&per_page=1&' + configuration[:search_params]

  # Connect to the API and get me some cases!
  response = access_token.get(uri)

  # Parse the JSON response.
  json = JSON.parse(response.body)

  # Send the total number of cases to the dashboard.
  send_event(:desk_cases, count: json['total_entries'])
end

desk.scss

// ----------------------------------------------------------------------------
// Sass declarations
// ----------------------------------------------------------------------------
$background-color:  #444;
$value-color:       #fff;

$title-color:       rgba(255, 255, 255, .7);

// ----------------------------------------------------------------------------
// Widget-desk styles
// ----------------------------------------------------------------------------
.widget-desk {

  background-color: $background-color;

  .title {
    color: $title-color;
  }

  .cases {
    color: $value-color;
  }

  .updated-at {
    color: rgba(0, 0, 0, 0.3);
  }

}

.hotness0 { background-color: #3b985f; }
.hotness1 { background-color: #daf493; }
.hotness2 { background-color: #fce691; }
.hotness3 { background-color: #f17f5b; }
.hotness4 { background-color: #9a2039; }