g5_updatable

G5 Updatable

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 PostgreSQL's json field type, and so only supports apps that also use PostgreSQL.

Compatible with rails 4.x : Use version 0.x

Compatible with rails 5.x : Use version >= 1.0.0

Installation

1. Add this line to your application's Gemfile:

   gem 'g5_updatable'
   

2. And then execute:

   bundle
   

3. Run the generator.

   rails g g5_updatable:install
   

   This mounts the engine at /g5_updatable.

4. And copy the engine's migrations to your application:

    rake g5_updatable:install:migrations
   

5. Run the schema AND data migrations:

     rake db:migrate
     rake g5_updatable:data_migration
   

6. Optional: load all of G5-Hub's data into your database

Important: The entries.js and entries.json endpoint on the hub are deprecated. So, for all versions of g5_updatable before 0.17.0, this task will only load the newest 10 clients. If you would like to load all clients, please specify "~> 0.17.0" or higher in your Gemfile.

  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

Execute code each time a new client is created:

G5Updatable::ClientUpdater.on_create do |g5_updatable_client|
  puts "#{g5_updatable_client.name} was just created"
end

To execute code every time a location is updated:

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

Also optionally expect a secondary block argument, receiving the object previous to be updated ... you know.. For diff reasons.

G5Updatable::LocationsUpdater.on_update do |g5_updatable_location, before_update_location|
  puts "G5Updatable::Location##{before_update_location.properties} changed to "
  puts "G5Updatable::Location##{g5_updatable_location.properties} "
end

or, execute code only when a location is created:

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

The on_create callback is called right before the on_update callback when a new location is created.

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.

Dependencies

Versions >= 0.28.0 include Sidekiq as a dependency so that feed processing can be handled asynchronously instead of in the context of a web request. Note that we assume a queue of g5_updatable is present and that applications with custom queues should make sure to include one by that name, which can be prioritized per app as needed.

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'

FactoryBot Factories

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

Authors

• Brian Bauer / @bbauer
• Perry Hertler / @perryqh
• Chris Stringer / @jcstringer

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. You can copy it into place with:

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

Set up the test database for the first time:

bundle exec rake db:test:setup

Run specs:

bundle exec rspec spec

If you add a migration, make sure you apply it to the dummy app and commit the changes to spec/dummy/db/schema.rb:

bundle exec rake app:db:migrate RAILS_ENV=test

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.