# Amsi

Ruby client of AMSI Evolution Suite API

## Versions

See the [changelog](CHANGELOG.txt)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'amsi'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install amsi

## Usage

### SOAP Actions

To request an action, instantiate the appropriate request class (see below) and invoke #perform
on it. The API response will be parsed and returned as a ruby object.

#### Amsi::Request::AddGuestCard
Add a new guest card for the prospect

##### Initialization parameters

Required initializer parameters:
* `contact_type` [String] See [Amsi::Parameter::ContactType](#amsiparametercontacttype)
* `password` [String] Amsi account password
* `portfolio_name` [String] the unique identifier for the property in AMSI
* `property_id` [String] AMSI property id
* `prospect` [Amsi::Parameter::Prospect](#amsiparameterprospect)
* `user_id` [String] Amsi account username
* `web_service_url` [String] Amsi Url to the leasing.asmx resource

Optional initializer parameters:
* `appointment_date` [Date] date the prospect is going to visit the property
* `comments` [String]
* `contact_datetime` [DateTime]
* `date_needed` [Date]
* `initial_source_id` [String]
* `lease_term_desired` [Integer]
* `leasing_agent_id` [String]
* `qualified` [Boolean]
* `unit_subtype` [String]
* `unit_type` [String]

##### Response

[Amsi::Model::GuestCardResult](#amsimodelguestcardresult)

#### Amsi::Request::GetMoveinsByFirstMarketingSource
Get all leases matching the specified marketing source and within the specified
time window.

##### Initialization parameters

Required initializer parameters:
* `from_date` [Date] Beginning of date interval within which to search
* `marketing_source_code` [String] Code corresponding to the marketing source
    for which to fetch move ins. Max of 3 characters according to their docs.
* `password` [String] Amsi account password
* `portfolio_name` [String] the unique identifier for the property in AMSI
* `property_id` [String] AMSI property id
* `through_date` [Date] End of date interval within which to search
* `user_id` [String] Amsi account username
* `web_service_url` [String] Amsi Url to the leasing.asmx resource

##### Response

Array<[Amsi::Model::Lease](#amsimodellease)>

#### Amsi::Request::GetPropertyList
Retrieve a list of properties and detailed information about each.

##### Initialization parameters

Required initializer parameters:
* `user_id` [String] Amsi account username
* `password` [String] Amsi account password
* `portfolio_name` [String] the unique identifier for the property in AMSI
* `web_service_url` [String] Amsi Url to the leasing.asmx resource

Optional initializer parameters and default values:
* `property_id` [String] Amsi property id (if this field is left blank, the response will
  include all properties in the portfolio)
* `include_leasing_agents` [Boolean] if true, response will include leasing agents for each property returned.
* `include_marketing_sources` [Boolean] if true, response will include marketing sources for each property returned.
* `include_unit_types` [Boolean] if true, response will include unit types for each property returned.


##### Response

Array<[Amsi::Model::Property](#amsimodelproperty)>


#### Amsi::Request::GetPropertyResidents
Retrieve resident leases for a given property. Returns current leases only by default.

##### Initialization parameters

Required initializer parameters:
* `user_id` [String] Amsi account username
* `password` [String] Amsi account password
* `portfolio_name` [String] the unique identifier for the property in Amsi
* `property_id` [String] Amsi property id
* `web_service_url` [String] Amsi Url to the leasing.asmx resource
* `params` [Hash] extra configuration fields: `:start_date` [String], `:end_date` [String], `:remote_id` [String], `:billing_config` [BillingConfiguration], `:import_id` [String] and `:pmc_id` [String]

Optional initializer parameters and default values:
* `lease_status` [String] Lease status filter; defaults to current leases ("C"). Valid values: (A)pplicant, (C)urrent, (I)ntent to Transfer, (L)eased, (N)otice, (P)revious, (T)ransfer, (V)approved, (X)cancelled
* `include_marketing_source` [Boolean] if true, response will include marketing sources on each lease returned.

##### Response

Array<[Amsi::Model::Lease](#amsimodelfloorplan)>


### Parameters

#### Amsi::Parameter::ContactType

Constants for the different channels prospects can use for contacting. Available constants are:

* `INTERNET`
* `PHONE`
* `RETURN_VISIT`
* `VISIT`

#### Amsi::Parameter::Prospect

A container for prospect details.

Required initializer parameters:
* `last_name` [String]

Optional initializer parameters:
* `daytime_phone` [String]
* `email` [String]
* `first_name` [String]


### Models

#### Amsi::Model::Address

A [Amsi::Model::Property](#amsimodelproperty) has an address and a remit_to_address

* `line_1` [String] 1st line in the street address
* `line_2` [String] 2nd line in the street address
* `line_3` [String] 3rd line in the street address
* `line_4` [String] 4th line in the street address
* `city` [String] the city
* `state` [String] the state
* `zip_code` [String] the zip code
* `country` [String] the country

#### Amsi::Model::GuestCardResult

The response from [AddGuestCard](#amsirequestaddguestcard), will have the following attributes:

* `contact_sequence_number` [Integer] (alias `contact_seq_no`)
* `guest_card_id` [String] the unique identifier for the newly created guest card
* `property_id` [String]
* `status` [String] either "SUCCESS" or "FAILURE" (also has convenience method `success?`)

#### Amsi::Model::GuestCard

The response from [GetMoveinsByFirstMarketingSource](#amsirequestsgetmoveinsbyfirstmarketingsource)
is an array of `Amsi::Model::Lease` instances. Leases have `guest_card` and
`matched_guest_cards`. `guest_card` is either an Amsi::Model::GuestCard or nil
 and `matched_guest_cards` is an array of Amsi::Model::GuestCards
 (can be empty). Amsi::Model::GuestCards have the following attributes:

* `email` [String]
* `create_date` [DateTime] The time the guest card was created according to AMSI
* `first_name` [String] The renter's first name
* `id` [String] The ID of the guest card in AMSI
* `initial_source_id` [String] the short code for the marketing source attributed to the lease
* `last_name` [String] The renter's last name
* `property_id` [String] The unique identifier of the property that the guest card belongs to

#### Amsi::Model::Lease

The response from [GetPropertyResidents](#amsirequestgetpropertyresidents) is an array of `Amsi::Model::Lease`
instances. Each instance will have the following attributes:

* `property_id` [String]
* `building_id` [String] Building ID
* `unit_id` [String] Unit name
* `resident_id` [String] Resident ID
* `external_reference_id` [String]
* `guest_card` [[Amsi::Model::GuestCard](#amsimodelguestcard)] or nil
* `matched_guest_cards` [Array<[Amsi::Model::GuestCard](#amsimodelguestcard)>], can be []
* `occupant_status_code` [String in Amsi::Model::Lease::Status]
* `occupant_status_code_description` [String]
* `begin_date` [Date]
* `end_date` [Date]
* `application_date` [Date]
* `sign_date` [Date]
* `move_in_date` [Date]
* `rent_amount` [Integer]
* `occupants` [Array<[Amsi::Model::Occupant](#amsimodeloccupant)>]
* `lead_id` [String] Guest Card No.
* `lead_date` [DateTime] Guest first contact date
* `lead_source_code` [String] Marketing source code

#### Amsi::Model::LeasingAgent

A [Amsi::Model::Property](#amsimodelproperty) has 0 or more leasing agents

* `agent_active_flag` [String] "Y" if the agent is active, otherwise "N" (also has convenience method `active?`)
* `code` [String] the unique identifier for the agent within the property (alias of `agent_code`)
* `agent_name` [String] the leasing agent's full name (alias of `agent_name`)
* `property_id` [String] the unique ID of the property the leasing agent works at

#### Amsi::Model::Manager

A [Amsi::Model::Property](#amsimodelproperty) has a manager

* `fax` [String] the property manager's fax number
* `first_name` [String] the property manager's first name
* `last_name` [String] the property manager's last name
* `middle_name` [String] the property manager's middle name
* `phone` [String] the property manager's phone number
* `salutation` [String] the property manager's salutation, e.g. "Mrs"

#### Amsi::Model::MarketingSource

A [Amsi::Model::Property](#amsimodelproperty) has 0 or more marketing sources

* `code` [String] unique identifier within the property (alias of `source_code`)
* `description` [String] a description of the marketing source (alias of `source_desc`)
* `source_active_flag` [String] "Y" if the marketing source is active, otherwise "N" (also has convenience method `active?`)
* `property_id` [String] the unique ID of the property the marketing source belongs to

#### Amsi::Model::Occupant

One occupant of a lease.  Each instance will have the following attributes:

* `property_id` [String]
* `building_id` [String] Building ID
* `unit_id` [String] Unit name
* `resident_id` [String] Resident ID
* `sequence_number` [String] Sequence number
* `first_name` [String]
* `last_name` [String]
* `phone_1` [String]
* `phone_2` [String]
* `responsible_flag` [String in ["Responsible" | "Non-Responsible"]]
* `email` [String]

#### Amsi::Model::Property

The response from [GetPropertyList](#amsirequestgetpropertylist) is an array of `Amsi::Model::Property`
instances. Each instance will have the following attributes:

* `address` [[Amsi::Model::Address](#amsimodeladdress)] the property's physical address
* `email` [String] the email address of the property (alias of `property_addr_email`)
* `id` [String] the property's unique identifier
* `leasing_agents` [Array<[Amsi::Model::LeasingAgent](#amsimodelleasingagent)>] the list of leasing agents for the property
* `live_date` [Date] the date the property went live
* `live_flag` [String] "Y" if the property is live, otherwise "N" (also has convenience method `live?`)
* `manager` [[Amsi::Model::Manager](#amsimodelmanager)] the property manager's contact info
* `marketing_sources` [Array<[Amsi::Model::MarketingSource](#amsimodelmarketingsource)>] the list of marketing sources for the property
* `name` [String] the name of the property (alias of `property_name_1`)
* `name_2` [String] an optional alternate name of the property (alias of `property_name_2`)
* `remit_to_address` [[Amsi::Model::Address](#amsimodeladdress)] the property's mailing address
* `unit_types` [Array<[Amsi::Model::UnitType](#amsimodelunittype)>] the list of unit types for the property

#### Amsi::Model::UnitType

A [Amsi::Model::Property](#amsimodelproperty) has 0 or more unit types

* `baths` [Decimal] the number of bathrooms in the unit
* `bedrooms` [Integer] the number of bedrooms in the unit
* `count` [Integer] Number of units in the property that are of this type
* `description` [String] a description of the unit type (alias of `unit_type_desc`)
* `market_rent` [Decimal] the rental price of the unit
* `minimum_security_deposit` [Decimal] the minimum security deposit needed for the unit (alias of `sec_min`)
* `month_to_month_renew` [Decimal] the month-to-month renewal amount (alias of `mtm_renew`)
* `other_renew` [Decimal] other renewal amount
* `property_id` [String] the unique ID of the property the unit is in
* `rooms` [Integer] the total number of rooms in the unit
* `sqft` [Integer] the total area of the unit (alias of `sqftg`)
* `standard_renew` [Decimal] the standard renewal amount
* `type` [String] the unique identifier within the property for this unit type (alias of `unit_type`)


## Compatibility

This gem sets global configurations on other dependent libraries, which makes it inherently *not*
thread-safe. Notably, it sets the following

* `MultiXml.parser = :ox`

If your client depends on any of these global settings, it is recommended that you do not run in
a multi-threaded environment.


## 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](https://rubygems.org).

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/apartmentlist/amsi.