G5 Updatable

Gem Version Build Status

G5 Updatable provides a solution for automatic updates of client and location data when modified or created in the G5 Hub.

Requirements

G5 Updatable makes use of PostgrSQL's json field type, and so only supports implementing apps that also use PostgreSQL.

Installation

  1. Add this line to your application's Gemfile:
   gem 'g5_updatable'
  1. And then execute:
   bundle
  1. Run the generator.
   rails g g5_updatable:install

This mounts the engine at /g5_updatable.

  1. And copy the engine's migrations to your application:
    rake g5_updatable:install:migrations
  1. Optional: load all of G5-Hub's data into your database
    rake g5_updatable:load_all

Note, all of the G5_AUTH env variables need to be set for this to work.

Usage

G5 Updatable exposes a POST route at /g5_updatable/update that accepts a client_uid parameter (the URL for the client's detail page within the G5 Hub). When the route is hit, it will update/create Location and Client.

See the G5-Hub webhook logic for further info.

G5 Updatable also exposes two GET endpoints which return JSON:

  • '/g5_updatable/locations/:urn' returns information about a location
  • '/g5_updatable/syncs' returns updated_at timetamp of the most recent location sync

Hooks

To execute code every time a location is updated:

G5Updatable::LocationsUpdader.on_update do |g5_updatable_location|
  puts "G5Updatable::Location##{g5_updatable_location.id} was just updated"
end

Associations

You will likely have models in your own application that are associated with a Client or Location. A module is available to include in your related models to support this association. Assuming your model has a client_uid or location_uid string field respectively, you can do the following:

class Foo < ActiveRecord::Base
  include G5Updatable::BelongsToClient # if Foo belongs to a client
  include G5Updatable::BelongsToLocation # if Foo belongs to a location
end

It provides a #location method that will fetch the correct location.

Spec Helpers

The engine provides a helper files that can be included in your project to bring in some testing support. Currently this is limited to (some factory definitions)[https://github.com/G5/g5_updatable/blob/active-record-up-in-here/lib/g5_updatable/rspec/factories.rb]. In rspec you can add the following line to your spec/spec_helper.rb:

require 'g5_updatable/rspec'

FactoryGirl Factories

For easier testing, if your app uses FactoryGirl, you can get access to factories by require "g5_updatable/factories".

Authors

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Write your code and specs
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request

If you find bugs, have feature requests or questions, please file an issue.

Specs

The database.yml for the dummy app must be created and modified to match your PostgreSQL configuration. If you are using the G5 Orion Vagrant image, the sample file should just work. You can copy it into place with:

$ cp spec/dummy/config/database.sample.yml spec/dummy/config/database.yml

Run specs via rspec with:

$ rspec spec

License

Copyright (c) 2014 G5

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.