[![CircleCI](https://circleci.com/gh/apartmentlist/yardi.svg?style=svg&circle-token=f257321b5c0e4a15a49eda74aa869a09d6db2f19)](https://circleci.com/gh/apartmentlist/yardi) # yardi A Ruby client for v4 of Yardi's Guestcard (and soon ILS) API ## Installation Add this line to your application's Gemfile: ```ruby gem 'yardi' ``` And then re-install your application's bundle: $ bundle install Or install it yourself as: $ gem install yardi ## Usage ### Configuration Configure the gem with your Yardi license, entity and platform: ```ruby Yardi.configure do |config| # Use your web service URL below config.license_key = ENV['LICENSE_KEY'] config.entity = 'Apartment List' config.platform = 'SQL Server' end ``` ### Useful classes #### Yardi::Credential Yardi SOAP actions require authentication so the SOAP action classes (see below) require a `:credential` parameter in the initializer. ```ruby credential = Yardi::Credential.new( username: 'my-username', password: 'my-password', database: 'test_db_live', server: '0SQL_DBtest' ) params = { agent: Agent.new(first_name: 'Test', last_name: 'Agent'), credential: credential, ... # any other required params } response = Yardi::Request::SomeSoapAction.new(params).perform ``` ### SOAP Actions To request an action, instantiate the appropriate class (see below) and invoke `#perform` on it. The API response will be parsed and returned as a ruby object. #### Yardi::Action::ImportYardiGuest_Login Insert a guest card into Yardi's system. ##### Initialization parameters * `agent [Yardi::Parameter::Agent]` * `credential [Yardi::Parameter::Credential]` information needed to authenticate with Yardi * `lead_source [String]` what Yardi calls TransactionSource * `reason [String]` what Yardi calls Event Reasons. This is the reason for the event, e.g. price inquiry, tour, etc. * `property [Yardi::Parameter::Property]` the property to associate the guest card with * `user [Yardi::Parameter::User]` the user to associate the guest card with #### Yardi::Request::GetResidents Get all the residents for a given property ID. ##### Initialization parameters * `credential [Yardi::Parameter::Credential]` information needed to authenticate with Yardi * `property_id [String]` the remote `YardiPropertyId` ##### Response An array of `Yardi::Model::Resident`s ###### Example ```ruby Yardi::Request::GetResidents.new( credential: credential, params: { property_id: 'p263656'} ).perform => [ # "home", "PhoneDescription" => "Home", "PhoneNumber" => "(123) 456-7890" } ], @status="Current", @unit_name="A2" >, # "cell", "PhoneDescription" => "Mobile", "PhoneNumber" => "8507742326" } ], @status="Current", @unit_name="A3" > ] ``` #### Yardi::Request::GetYardiGuestActivity Get a list of `Yardi::Model::Prospect`s for a given Prospect at the specified property ID. ##### Initialization parameters * `credential [Yardi::Parameter::Credential]` information needed to authenticate with Yardi * `params [Hash]` * `property_id [String]` * `prospect [Yardi::Parameter::Prospect]` ##### Response An array of `Yardi::Model::Prospect`s ###### Example ```ruby Yardi::Request::GetYardiGuestActivity.new( credential: credential, params: { property_id: 'p263656', prospect: prospect } ).perform # => [#, #] ``` #### Yardi::Model::Prospect ##### Attributes * `first_name` The `Prospect`'s first name according to Yardi's database * `last_name` The `Prospect`'s last name according to Yardi's database * `email` The `Prospect`'s email address according to Yardi's database * `phones` An Array of the `Prospect`'s phone numbers, or `nil` if there are none * `events` An Array of `Yardi::Model::Event` objects * `prospect_id` The `Prospect` id from Yardi's database e.g. `"p00003693"` * `tenant_id` The tenant id from Yardi's database e.g. `"t000456"` ## Development 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing If you are interested in contributing to this project, please review the [contribution guidelines](docs/contributing.md). ## Versions - 4.0.0 Add handling for 404 errors and move ConnectionError to be a subclass of Yardi::Error::Base - 3.1.2 Fix Prospect parsing to properly handle missing `Event` nodes - 3.1.1 Fix roommate parsing to properly extract roommate data from GetResidents response - 3.1.0 Add roommates to Resident Model and Parser - 3.0.6 Handle Yardi connection errors - 3.0.5 Handle missing event ids - 3.0.4 Add GuestsNotFound Error - 3.0.3 Handle roommates in prospect search results - 3.0.2 Raise an error when GetResidents call returns no Residents - 3.0.1 Handle parsing resident response when there is only one result - 3.0.0 GetYardiGuestActivity returns an Array of Prospects - 2.0.0 GetYardiGuestActivity uses a Prospect parameter - 1.0.3 Fix when GetResidents call returns nil dates - 1.0.2 Fix when GetResidents call returns a single phone number - 1.0.1 Fix when GetResidents call returns nil phone numbers - 1.0.0 Change response for GetYardiGuestActivity to be an array of Events instead of Tours. Also add lease dates GetResidents response. - 0.3.0 Add GetResidents request - 0.2.1 Handle when Yardi's response is completely empty - 0.2.0 Insert FirstContact events as Email instead of Other - 0.1.5 Handle missing bed/price preferences - 0.1.4 Fix Prospect search, which requires a property ID - 0.1.3 Fetch existing tours from Yardi - 0.1.2 Support custom connections for use with a proxy - 0.1.1 Handle multiple errors in the response - 0.1.0 Initial release with guestcard insertion and response handling