Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
CAP (Common Alerting Protocol) API for Ruby
branch: master

This branch is 9 commits ahead, 335 commits behind farrel:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib/generators/rcap
spec
.gitignore
CHANGELOG.rdoc
Gemfile
Gemfile.lock
README.rdoc
Rakefile
rcap-rails-generators.gemspec

README.rdoc

rcap-rails-generators - Generators for the Common Alerting Protocol for Ruby on Rails

Overview

The Common Alerting Protocol is a lightweight standard to facilitate the distribution of alerting data. RCAP is an implementation of the CAP in Ruby. It allows for the creation of RCAP messages from Ruby applications and the parsing of external messages.

RCAP currently supports only CAP Version 1.1 and rcap-rails-generators only supports Rails 3.X.

This gem is a set of generators for creating RCAP ActiveRecord models and migrations.

Version

1.3

Dependencies

rcap-rails-generators depends on the following gems

rcap-rails-generators uses the REXML API, included in Ruby, to parse and generate XML.

Installation

rcap-rails-generators is distributed as a Ruby gem and is available from Gemcutter. If you have Gemcutter set as a source of your gems then rcap-rails-generators can be installed from the command line

gem install rcap-rails-generators

or via Bundler

gem 'rcap-rails-generators'

The gem is also available for download and manual installtion at www.aimred.com/gems .

Once installed you can run:

rails generate rcap:models

and

rails generate rcap:migrations

to create the respective files.

rcap:models also installs a couple of necessary modules in your Rails.root/lib directory. You will need to make sure they are required:

# config/initializers/load_extensions.rb require 'rcap' require 'validations'

Web resources

Usage

To include RCAP into your application add the following require

require 'rcap'

All RCAP classes reside in the RCAP namespace but including the RCAP module makes the classes available at the top level without the RCAP prefix.

alert = RCAP::Alert.new(...

include RCAP # Include RCAP module into namespace
alert = Alert.new(...

Creating an Alert

alert = Alert.new( :sender   => 'cape_town_disaster_relief@capetown.municipal.za',
                   :status   => Alert::STATUS_ACTUAL,
                   :msg_type => Alert::MSG_TYPE_ALERT,
                   :scope    => Alert::SCOPE_PUBLIC,
                   :infos    => Info.new( :event       => 'Liquid Petroleoum Tanker Fire',
                                          :language    => 'en-ZA',
                                          :categories  => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
                                          :urgency     => Info::URGENCY_IMMEDIATE,
                                          :severity    => Info::SEVERITY_SEVERE,
                                          :certainty   => Info::CERTAINTY_OBSERVED,
                                          :headline    => 'LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY',
                                          :description => 'A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
                                                          after the R300 interchange.  Municipal fire fighting crews have been dispatched.
                                                          Traffic control officers are on the scene and have diverted traffic onto
                                                          alternate routes.' ))

# Accessing attributes
puts alert.status                          # Print out "Actual"
puts alert.infos[0].language               # Print out "en-ZA"
puts alert.infos[0].categories.join( ' ' ) # Print out "Transport Fire"

Exporting an Alert

To XML

Using the alert message created above

puts alert.to_xml # Print out CAP XML message

Will print the following CAP XML

<?xml version='1.0'?>
<alert xmlns='urn:oasis:names:tc:emergency:cap:1.1'>
  <identifier>494207a7-f86b-4060-8318-a4b2a3ce565e</identifier>
  <sender>cape_town_disaster_relief@capetown.municipal.za</sender>
  <sent>2009-10-26T21:04:51+02:00</sent>
  <status>Actual</status>
  <msgType>Alert</msgType>
  <scope>Public</scope>
  <info>
    <language>en-ZA</language>
    <category>Transport</category>
    <category>Fire</category>
    <event>Liquid Petroleoum Tanker Fire</event>
    <urgency>Immediate</urgency>
    <severity>Severe</severity>
    <certainty>Observed</certainty>
    <headline>LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY</headline>
    <description>
      A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
      after the R300 interchange. Municipal fire fighting crews have been
      dispatched. Traffic control officers are on the scene and have diverted
      traffic onto alternate routes.
    </description>
  </info>
</alert>

To YAML

YAML is a plain text serialization format designed to be easily readable and editable by both human and machine. RCAP has custom YAML generation and parsing methods to produce a YAML document that is as human friednly as possible. The following code

alert.to_yaml

will produce the following YAML document

---
Identifier: 2a1ba96d-16e4-4f52-85ea-0258c1440bd5
Sender: cape_town_disaster_relief@capetown.municipal.za
Sent: 2009-11-19T02:41:29+02:00
Status: Actual
Message Type: Alert
Scope: Public
Information:
- Language: en-ZA
  Categories: [Transport, Fire]
  Event: Liquid Petroleoum Tanker Fire
  Urgency: Immediate
  Severity: Severe
  Certainty: Observed
  Headline: LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY
  Description: |-
    A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
    after the R300 interchange.  Municipal fire fighting crews have been dispatched.
    Traffic control officers are on the scene and have diverted traffic onto
    alternate routes.

Note: If you use Ruby 1.8 the order of the attributes is jumbled due to hashes being unorderd (Ruby 1.9 implements ordered hashes). This does not affect the ability to parse documents generated from RCAP::Alert#to_yaml, it just makes things the output slightly messy.

To JSON

JSON(JavaScript Object Notation) is a text serialization format that can be easily loaded in a JavaScript environment.

alert.to_json

will produce the following JSON string

{"identifier":"0eb97e40-195b-437b-9a01-55fe89691def",
 "sender":"cape_town_disaster_relief@capetown.municipal.za",
 "sent":"2011-03-04T15:58:01+02:00",
 "status":"Actual",
 "msg_type":"Alert",
 "scope":"Public",
 "infos":[
   {"language":"en-ZA",
    "categories":["Transport","Fire"],
    "event":"Liquid Petroleoum Tanker Fire",
    "urgency":"Immediate",
    "severity":"Severe",
    "certainty":"Observed",
    "headline":"LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY",
    "description":"A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
                   after the R300 interchange. Municipal fire fighting crews have been dispatched.
                   Traffic control officers are on the scene and have diverted traffic onto \nalternate routes."}]}

Parsing an Alert From An External Source

From XML

RCAP allows for the parsing of a CAP XML string

alert = RCAP::Alert.from_xml( xml_string )

Currently RCAP only supports version 1.1 of the CAP standard and the parser is as strict as possible when parsing data.

From YAML

Alert messgaes can be read in from text files containing data formatted in YAML as generated by Alert#to_yaml.

alert = RCAP::Alert.from_yaml( yaml_string )

From JSON

An Alert can also be initialised from a JSON string produced by Alert#to_json

alert = RCAP::Alert.from_json( json_string )

Validating an alert

The RCAP API aims to codify as many of the rules of the CAP XML format into validation rules that can be checked using the Assistance API. The following Info object has two attributes ('severity' and 'certainty') set to incorrect values.

info = Info.new( :event      => 'Liquid Petroleoum Tanker Fire',
                 :language   => 'en-ZA',
                 :categories => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
                 :urgency    => Info::URGENCY_IMMEDIATE,
                 :severity   => nil,                   # Severity is not assigned
                 :certainty  => 'Unknown Certainty' )  # Certainty is assigned in incorrect value

puts "Is info valid: #{ info.valid? }"
info.errors.full_messages.each{ |message| puts "Error: #{ message }" }

Will produce the folling output:

Is info valid: false
Error: severity is not present
Error: certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown

All RCAP classes include the Validation module.

A full spec suite using RSpec was used to test the validations and currently numbers over 250 tests.

DateTime and Time

It is highly recommended that when dealing with date and time fields (onset, expires etc) that the DateTime class is used to ensure the correct formatting of dates. The Time class can be used when generating a CAP alert XML message however any CAP alert that is parsed from an external XML source will use DateTime by default.

Authors

Farrel Lifson - farrel.lifson@aimred.com

License

RCAP is released under the BSD License.

Copyright

2009-2011 Aimred CC

Something went wrong with that request. Please try again.