Codebase Notification Server
The Codebase notification server exists to dispatch notification requests from the Codebase
application. The server consists of a number of 'protocols' which are defined in the
folder and represent each of the various services which can be invoked when actions are carried
out within Codebase.
A protocol consists of a number of options which should be defined by the user developing the specific protocol. You can look at existing protocols to get an example of how things work.
Each time an action is carried out within Codebase - the system will automatically attempt to call the appropriate protocol within the notification server. This request will include the full payload containing information about the action which has been carried out in addition to the configuration options the user has specified for your application.
Creating a protocol
Creating a new protocol is quite easy. Simply create a new file in the
with a name which is representative of the service you are implementing. For example, if you
wanted to create a Basecamp protocol, simply call it
Within the file there are a number of options, firstly, you need to specify a description of the protocol which defines exactly what it does. This is displayed to users within the Codebase interface when configuring your service with their account.
desc 'My awesome service which posts messages to Campfire each time somebody carries out' desc 'an activity within my Codebase account'.
desc method can be called multiple times to define a multiline description. It will be
joined into one sentence when displayed to the user
Defining Fields required for your protocol
Define which fields are required for your protocol to function.
field :username, :required => true, :description => "Your username" field :password, :required => true, :description => "Your password" field :url, :description => "Your URL"
If a field is required, simply set the
:required key to true. The description is displayed
to users when configuring the protocol within the interface.
Defining additional validation rules
If you need to validate the user provided options, you can do so by defining a validation block as displayed below.
validation do |options, errors| errors << "You must eat carrots" unless options['foods'].include?('carrots') errors << "ID must be a number" unless options['id'] =~ /\A\d+\z/ end
Simply add text into the
errors array. If the errors array is not empty, the protocol will
not be invoked and will be cancelled.
Defining the protocol itself
So, the real hard work itself,
protocol :basecamp do |type, options, payload| ## do your thing end
Inside the protocol block, you have access to the
type which is a symbol representing which
type of activity was carried out (e.g. new_ticket, push, deployment etc...).
the user-configuration options for the notification.
payload contains the full data for the request.
You can view the example payloads in
test/examples/*.json. All data is presented to the payload
block as a hash with keys as strings.
The protocol block should return either true or false to represent whether the protocol action was carried out successfully or not.
If you encounter an error, simply raise it.
raise Error, "Something terrible happened!"
Raised errors are not reported back to the user but are logged for investigation by the Codebase team.
If you require any additional libraries for your protocol to function, firstly, ensure you require
them at the top of your protocol file (e.g.
require net/ssh) and, if it's a Gem, ensure you add
it to the libraries
When you're finished...
When you're happy with your protocol, submit your data back to the Codebase team who will review it and push it into our systems.
Your protocol should include a logo. Logos should be placed in
logos/*.gif. The image file itself
should be 48x48.
If you have any questions or comments, feel free to drop an email to firstname.lastname@example.org