entrata

Entrata

Ruby client for Entrata API

Versions

• 0.1.0 Initial Release
• 0.1.1 Extend request timeout to 10 minutes for all requests
• 0.1.2 Request GetIlsPropertiesData via curl to avoid errors on large responses
• 0.2.0 Add buildingName to fixture file for getIlsPropertiesData success response
• 0.2.1 Make paths in StaticFileFetcher relative
• 0.2.2 Add buildingName to unit C606 in fixture file for successful getIlsPropertiesData
• 0.3.0 Raise a Request::Error when the response is not valid JSON and update Travis Ruby version
• 0.3.2 Expose lead request body for troubleshooting when sending leads
• 1.0.0 Allow us to pass renter min and max price range in
• 1.0.4 Make entrata gem compatible with Ruby 3 syntax updates
• 1.0.5 No functional changes. Updating build pipeline to publish to GitHub Packages.
• 1.1.0 Adding services to manage lea lite inactive and reactive guestcard requests.
• 1.2.0 Adding services to manage lea lite general guestcard requests.
• 1.2.1 Using mountain time in reactivate guestcard flow.
• 1.2.2 Byebug removed.

Installation

Add this line to your application's Gemfile:

gem 'entrata'

And then execute:

$ bundle

Or install it yourself as:

$ gem install entrata

Usage

Configuration

No gem configuration, but getting an access token (via Entrata::Client.get_access_token) requires client_id and client_secret in addition to auth_code provided by Entrata on property activation.

API Resources

All API access is performed via the Entrata::Client class.

There are two usage patterns:

1. Gathering client credential and PMC subdomain
2. Making authenticated requests to API resources using saved credential and PMC subdomain

Gathering client credential and PMC subdomain

Class methods are available for convenience of this one-time call sequence per PMC

auth_code = 'received from activation endpoint'
client_id = ENV['ENTRATA_CLIENT_ID'] # Apartmentlist assigned client_id
client_secret = ENV['ENTRATA_CLIENT_SECRET'] # Apartmentlist current client_secret

token_hash = Entrata::Client.get_access_token(auth_code: auth_code,
                                         client_id: client_id,
                                         client_secret: client_secret)

client_info = Entrata::Client.get_client_subdomain(token_hash['token'])
subdomain = client_info['subdomain']

# create or update Entrata credential with token and subdomain

Making authenticated requests to API resources

An instance of the Entrata::Client may be created per PMC to request authenticated resources available under its subdomain.

credential = #find by PMC or iterate all entrata credentials
token = credential.fields['access_token']
subdomain = credential.fields['subdomain']

client = Entrata::Client.new(subdomain: subdomain, token: token)

remote_property_id = #get from activation

client.process_property_activation(remote_property_id) #defaults to 'approve'-ing the activation
property_hash = client.get_property_info(remote_property_id)
multiple_property_hash = client.get_ils_properties_data([remote_property_id])

Testing

A test client is available for integration testing in your consuming application.

Entrata::TestClient behaves like Entrata::Client, but returns static responses or raises errors just like the real client would. It never makes any real HTTP requests.

Entrata::TestClient defaults to providing successful (static) responses collected from the real API.

You may force failure by providing specific ("fail") input values. See below for specific trigger parameters:

# Providing "fail" to specific parameters will raise `Entrata::Request::Error` just like the real client would.
Entrata::TestClient.get_access_token(auth_code: 'fail', client_id: 'anything', client_secret: 'anything') #BOOM!
Entrata::TestClient.get_client_info('fail') #BOOM!

test_client = Entrata::TestClient.new(subdomain: 'anything', token: 'anything')
test_client.get_property_info('fail') #BOOM!
test_client.process_property_activation('fail') #BOOM!
test_client.get_ils_properties_data(['at', 'least', 'one', 'fail']) #BOOM!

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.