SupportBee's App Platform

Getting Started Guide

Introduction

SupportBee Apps can extend or customize the functionality of SupportBee. These apps are hosted on SupportBee's servers and available to everyone using SupportBee. Learn More

Setup

Prerequisite: You should have Ruby version 1.9.3 installed

Checkout the App platform from Github
git clone git://github.com/SupportBee/SupportBee-Apps.git

copy the omniauth example file
cp config/omniauth.platform.example.yml config/omniauth.platform.yml

Create a new branch with app_name as its name
git branch campfire
(choose an app_name which does not end with 's')

Checkout the new branch
git checkout campfire

Bundle install
bundle install

Create a new app using the generator
bin/sbapp new campfire
This generates an app boilerplate in the apps directory. The boilerplate generates the following directoy structure

dummy
|--assets
|  |
|  |--images
|  |  |
|  |  |-- icon.png
|  |  |-- screenshot.png
|  |    
|  |--views
|     |
|
|--dummy.rb
|--config.yml

Run the server locally using rackup
rackup

Right now, server requires a restart every time you change the app.

Configure Your App

Each app has a config.yml where all the configurations of the app are defined.

name: Dummy
slug: dummy
access: public
description: This is to test and a boilerplate app.
developer: 
  name: SupportBee
  email: SupportBee
  twitter: @supportbee
  github: SupportBee
action:
  button:
    screens: 
    - all
    - unassigned
    listing: 
    - all
    label: Send To Dummy

The slug should be unique across the platform.

Form for Settings

An app can specify the settings required by it in the Base class. These settings are accepted when the app is added to a SupportBee helpdesk.

module Dummy
  class Base < SupportBeeApp::Base
    string :name, :required => true
    password :key, :required => true, :label => 'Token'
    boolean :active, :default => true

    white_list :name
  end
end

An app can define a string, password or a boolean type of setting. Each setting accepts a name of the settings and a set of options

  • :label if not defined, the name is humanized and rendered as the label
  • :required
  • :default
  • :hint this will appear right below the input field

A setting can also be of type oauth. This triggers an oauth authentication of the service specified as name when the app is added to a help desk.
Right now we support the following services

  • github
  • trello

Example:
oauth :github

If you need integrations with any other service, please contact us.

An app can also white list the attributes for logging. If a white list is not speicifed, no attribute will be logged.

The Setting

Writing Some Logic

{slug}.rb

The app logic is defined in this file. The whole app can be defined in this single file or can be spread across multiple files which are required here. The basic structure is as follows:

module Dummy
  module EventHandler
    def ticket_created; end
  end

  module ActionHandler
    def action_button
     # Handle Action here
     [200, "Success"]
    end
  end

  class Base < SupportBeeApp::Base
    string :name, :required => true
    password :key, :required => true, :label => 'Token'
    boolean :active, :default => true

    # Custom public/private methods can be defined here
    # These methods can be called from the Handler modules
  end
end

Also, a few helper methods are available in the Base and Handler methods. See here for more on this.

Handling Events

An App can consume events by defining methods in EventHandler module.

module Dummy
  module EventHandler
    def ticket_created; end
    def agent_reply_created; end
    def customer_reply_created; end
    def ticket_archived; end
    def ticket_unarchived; end
    def ticket_spammed; end
    def ticket_unspammed; end
    def ticket_trashed; end
    def ticket_untrashed; end
  end
end

The event ticket.created triggers the method ticket_created and so on.

All the methods have access to the following information:

  • auth: This is required to get SupportBee API access for the helpdesk which triggered the App.
  • settings: This contains the values of the settings defined by the app for the helpdesk which triggered the App.
  • payload: This contains the event/action relavent data. This changes depending on the type of event or action.

Methods might also have access to payload.agent for certain actions like ticket_archived that can be triggered by agents. The Audit Trail App has some examples.

Here is an example of a Campfire App posting to campfire on ticket creation.

def ticket_created
  campfire = Tinder::Campfire.new settings.subdomain, 
                                  :token => settings.token
  room = campfire.find_room_by_name(settings.room)
  room.speak "New Ticket: #{payload.ticket.subject}"
end

Create an Action Button

An App can respond to actions by defining methods in ActionHandler. Currently only one action is allowed; button.

module Pivotal
  module ActionHandler
    def button
      # Handle Action here
      [200, "Success"]
    end

    def all_actions
    end
  end
end

Button Action

For a button action to work; you need to configure it in config.yml

action:
  button:
    screens:
    - all
    - unassigned
    label: Send To Dummy

This renders a Send To Dummy action in the SupportBee UI for Unassigned and All. When this action is triggered in the UI the method button is triggered.All actions must return a status and a optional message.
[200, "Successfully sent to Dummy"]

The Button

All action methods have access to the same information as events. In addition to these a list of ticket ids selected in the listing at the time of the trigger is also provided.

Overlay Form in the UI

A button action can also define an overlay which can be used to accept more information. Handlebars templating language is used to specify the overlay. The template is defined in APP_ROOT/assets/views/button/overlay.hbs. When the button action is triggered this overlay will receive the list of ticket ids selected. A boilerplate of the handlebars code is as follows:

  Iterate over tickets
  {{#each tickets}}
    {{subject}}
  {{/each}}

This overlay can accept form inputs. The form inputs will be serialized to a JSON object. A boilerplate of the form is as follows:

Name<br/>
First name: <input name="person[name][first_name]" value="John"><br/>
Last name: <input name="person[name][last_name]" value="Doe"><br/>
  
Age: <input name="person[age]" value=36><br/>

Sex:<br/>
<input type="radio" name="person[sex]" value="Male" checked="checked">Male
<input type="radio" name="person[sex]" value="Female">Female

And the serialized JSON object is as follows:

{
  person: {
    name: {
      first_name: 'John',
      last_name: 'Doe'
    },
    age: '36',
    sex: 'Male'
  }
}

Testing your App

Developer Console

We have created a simple console to easily trigger your Apps with sample payload. Right now it only supports Events. Soon you will be able to trigger button actions as well. To access the console for your app go to /{app_slug}/console when running the platform locally. For Campfire app, that would be /campfire/console.

The Console

Helpers

HTTP Helpers

A set of HTTP helpers are available to the apps to make external calls. You can find these helper methods here

https://github.com/SupportBee/SupportBee-Apps/blob/master/lib/helpers/http.rb

SupportBee Objects

All the payload data like ticket, reply or comment are available in the form of SupportBee Objects. These objects can be used to communicate with the SupportBee servers. For example, an app can post a comment on a ticket.

You can go through in detail here