Dash-fu sources need to get their data somehow: enter Marios. Marios are the brave workers that go out and collect data from vaious data sources and report them back in the form of activities and metrics.

Setup

A Mario is setup in four steps. First, the display method returns an HTML form which will be displayed to the user. In fact, this method returns two values:

  • inputs – HTML input controls for setting up a new controller.

  • notes – Additional setup notes, e.g. other steps that need to be followed, what values to supply, etc.

Wrap input controls within the label and use the source notation for the name attribute. For example, for Twitter:

<label>Screen name <input type="text" name="source[screen_name]" size="30"></label>

When the form is filled, the setup method is called with a context and values from the form fields. Since the Mario needs to store state information, it uses the context for that. The context is a Hash that can store basic Ruby values (nil, String, boolean, Numeric, Array and Hash).

At the very least, it should name the source by setting “source.name”, typically using other values (e.g. a Twitter source could be named “Twitter mentions for @dash_fu”).

Some sources collect metrics. These sources must specify two additional values during setup:

  • metric.columns – Specifies the columns (at least one) that make up this metric. The value if an array where each item describes a single column, see below for more details.

  • metric.totals – True if this metric collects totals (life-time values, e.g. downloads, user accounts), false if it only collects daily values (e.g. average response time, number of instances in cluster).

For metric.columns, each item can use the following keys:

  • id – Column identifier (if missing, derived from column name)

  • name – Column name (required)

Note: any state information you want to store can only use field names with alphanumeric charactercs and underscore. Periods and all other special characters are reserved for special field names that are not stored as part of the state.

Shortly after setup, the validate method is called with the same context. If it raises any exception, the error is displayed to the user and the source is discarded. Otherwise, register is called with a Webhook URL. Some Marios use that to register the Webhook with another service.

Updates

Periodically, the Mario will be asked to update the source by calling the update method. This method is called with the same context and callbacks. If data comes from a webhook, then the second argument to update is a Rack::Request object.

The callback object passed to update can be used to update the source by calling one of its many methods. A single update may call any combination of methods, e.g. increasing a metric and recording an activity.

The callback methods exposed by the callback object are:

  • set! – Columns to set (metric). Records the most recent value for this metric. The single argument is a hash where the keys are column ids (or indexes), the values are integers or floats.

  • inc! – Columns to increment (metric). Records a change in value which may be positive or negative. The single argument is a hash where the keys are column ids (or indexes), the values are integers or floats.

  • activity! – Records a single activity. The single argument is a hash with various values described below.

  • error! – Records a processing error. The single agrument is an error message.

An activity is specified using the following fields:

  • uid – Unique identifier (within the scope of this source). For example, if activity is a release, this could be the version number.

  • html – HTML contents of the activity.

  • text – Text contents of the activity (can be used instead of html).

  • url – URL for original resource (e.g. blog post, tweet).

  • tags – Any number of tags for filtering activities like this (e.g. twitter, mention). Tags are lowercased and can contain alphanumeric, dashes and underscore.

  • person – Person who performed this activity. A hash with the (all optional) values :name, :email, :url and :photo.

  • timestamp – Timestamp activity occurred.

HTML can contain links (HTTP/S and email), images, bold, italics, paragraphs, block quotes, lists, tables, pre-formatted text, video and a few other elements. Scripts, objects, styles are obviously not allowed.

Occasionally, the meta method is called. This method is used to display meta-data from the most recent state (i.e. last update). It returns an array of fields, each being a hash with the following values:

  • title – Title for this field (not required)

  • text – Text to show as value of the field

  • url – Link (not required)

Teardown

Eventually the source is destroyed and the Webhook is unregistered by calling unregister.