plangrade API Gem

Ruby wrapper for the plangrade API.

Supports OAuth 2.0 authentication, including refresh_token. Read the plangrade docs for more details.

Additionally, this may be used in conjunction with omniauth-plangrade in order to facilitate authentication and obtaining a valid access_token and refresh_token pair for use with this gem to access plangrade API endpoints.

See the plangrade-ruby-client example for implementation of both omniauth-plangrade and plangrade-ruby.

This README provides only a basic overview of how to use this gem. For more information about the API endpoints, look at the plangrade docs.

Add this line to your application's Gemfile:

gem 'plangrade-ruby'

And then execute:

$ bundle install

The plangrade API requires authentication for access to certain endpoints. Below are the basic steps to get this done.

Setup a plangrade client application at the plangrade developer site.

You can use omniauth-plangrade to obtain a valid access token, as demonstrated below.

# In your redirect_uri after the user authorized access, just parse the omniauth response
auth = request.env["omniauth.auth"]
access_token = auth["credentials"]["token"]
refresh_token = auth["credentials"]["refresh_token"]

This gem comes bundled with an OAuth2 wrapper that provides convenience methods for getting through the OAuth2 flow.

# Be sure to require plangrade in any controller where you utilize plangrade-ruby
require 'plangrade'

# Begin by getting the authorization url
plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
auth_url = plangrade_client.webserver_authorization_url(:redirect_uri => 'your_redirect_uri')

After the user follows the link created above and authorizes your app, they will be redirected to your redirect_uri, with a code in the params that you can use to obtain an access token.

plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
response = plangrade_client.exchange_auth_code_for_token(:params => {:code => params[:code], :redirect_uri => 'your_redirect_uri'})
token = JSON.parse response.body
access_token = token["access_token"]
refresh_token = token["refresh_token"]

You may want to store the access_token since it is good for two hours. You may also want to store the refresh_token since it can be used to get a new access_token at any time, so long as the user does not revoke your app's authorization.

This gem also allows you to use a refresh_token to obtain a new access_token.

# Set up a plangrade OAuth2 client and retrieve your refresh_token
plangrade_client = Plangrade::OAuth2Client.new(ENV['PLANGRADE_CLIENT_ID'], ENV['PLANGRADE_CLIENT_SECRET'])
response = plangrade_client.refresh_access_token(:params => {:refresh_token => 'your_refresh_token', :redirect_uri => 'http://localhost:3000/callback'})
token = JSON.parse response.body
access_token = token["access_token"]
refresh_token = token["refresh_token"]

You can view the current state of the client using the Plangrade#options method.

require 'plangrade'

Plangrade.options
#> {:site_url=>"https://plangrade.com", :client_id=>your_client_id, :client_secret=>your_client_secret, :access_token=>current_access_token, :http_adapter=>Plangrade::Connection, :connection_options=>{:max_redirect=>5, :use_ssl=>true}}

To change the configuration parameters use the configure method. If you set your client_id and client_secret as ENV['PLANGRADE_CLIENT_ID'] and ENV['PLANGRADE_CLIENT_SECRET'] then this will automatically be set for you.

Plangrade.configure do |p|
  p.client_id = your_client_id
  p.client_secret = your_client_secret
end

At this point the access_token is nil. This will need to be set and, in the next section, we will see how to do this.

This gem offers three ways to interact with plangrade's API:

1. Calling methods on Plangrade module. (Returns an API response)
2. Calling methods on an instance of Plangrade::Client. (Returns an API response)
3. Calling methods on the custom object models. (Returns identity mapped objects)

In order for this to work, you will need to set up your access_token. This assumes that you already configured the client with your default options as was described above.

# Set up your access_token
Plangrade.configure do |p|
  p.access_token = your_access_token
end

# Get the current user
Plangrade.current_user

Note: Use this if you wish to create multiple client instances with different client_id, client_secret, and/or access_token. If your application uses a single pair of client_id and client_secret credentials, you ONLY need to specify the access_token.

# Create a client instance using the access_token
plangrade = Plangrade::Client.new(:access_token => your_access_token)

Call methods on the instance.

User

Current user info

user = plangrade.current_user
user_name = user[:name]

Create new user

new_user_id = plangrade.create_user(params)

Update user

updated_user = plangrade.update_user(id, params)

Delete user

plangrade.delete_user(id)

Companies

Create new company

new_company_id = plangrade.create_company(params)

Get company info

company = plangrade.get_company(id)

Get all of a user's companies

companies = plangrade.all_companies

Update company

updated_company = plangrade.update_company(id, params)

Delete company

plangrade.delete_company(id)

Participants

Create new participant

new_participant_id = plangrade.create_participant(params)

Get participant info

participant = plangrade.get_participant(id)

Get all of a company's participants

participants = plangrade.all_participants(:company_id => id, params)

Update participant info

updated_participant = plangrade.update_participant(id, params)

Archive participant

archived_participant_id = plangrade.archive_participant(id)

Delete participant

plangrade.delete_participant(id)

Activities

Get all of a company's activities

activities = plangrade.all_activities(:company_id => id, params)

Notices

Get all of a company's notices (documents)

notices = plangrade.all_notices(:company_id => id, params)

The object model is an abstraction that makes it easy to manipulate the JSON data return when accessing plangrade's API. Each model has accessor methods for all keys contained in the JSON response for a given model type.

Users

user_id = Plangrade::Resources::User.create(user_email_here, user_name_here)
user = Plangrade::Resouces::User.current_user
user.name
user.email
user.update!(:email => "compliance@plangrade.com")
user.delete!

Companies

company_id = Plangrade::Resources::Company.create(company_ein_here, company_name_here)
companies = Plangrade::Resources::Company.all
company = Plangrade::Resources::Company.get(company_id)
company.name
company.ein
company.grade
company.update!(:name => "plangrade, llc")
company.delete!

Patricipants

participants = Plangrade::Resources::Participant.all

# The last parameter in this is optional, this shows how to add it for an employee, a dependent would just omit the last
participant_id = Plangrade::Resources::Participant.create(company_id, first_name, last_name, 
														  street1, street2, city, state, zip, 
														  dob, email, phone, employee_id, {:ssn => employee_last_four_ssn})

participant = Plangrade::Resources::Participant.get(participant_id)
participant.first_name
participant.last_name
participant.company_id
...
participant.update!(:first_name => "Johnny")
participant.archive!
participant.delete!

Activities

activities = Plangrade::Resources::Activity.all

Notices

notices = Plangrade::Resources::Notice.all

This library aims to support and is tested against the following Ruby versions:

1. Ruby 1.9.3
2. Ruby 2.0.0
3. Ruby 2.1.0

This library may inadvertently work (or seem to work) on other Ruby implementations, however, support will only be provided for the versions listed above.

Copyright (c) 2015 Plangrade Inc

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.