# ONEAccess for Ruby
This is a ruby gem that wraps the ONEAccess API in an easy to use ruby library, so the API can be accesses transparently by invoking methods.

The full documentation about the ONEAccess API can be found at:
http://apidocs.oneaccess.io/docs

Currently, only the version `v1.1` is supported by this gem.

## Installation & Setup
Install the gem directly:
```
gem install oneaccess
```

or add it to your `Gemfile`:
```
gem 'oneaccess'
```

The gem must be initialized with the API keys. If it's being used in a Rails project, then the file `/config/initializers/oneaccess.rb` should be created:
```ruby
ONEAccess.configure do |config|
  config.api_key = 'API_KEY_HERE'
  config.master_api_key = 'MASTER_API_KEY_HERE'
end
```

## Tests
The tests are written in RSpec. Run the `rspec` in the root directory of the project.
A coverage report is automatically generated and stored under `/coverage`.

## Documentation
The API and data model has been converted into ruby modules and classes following the same organization as defined in the OA documentation, but adapted to the ruby convetions (underscored instead of camelCase). Therefore, by reading the official documentation you can easily infer what the ruby API will look like.

Not all the methods in the API are currently supported, here's a list of all suported calls:

- User by Email: _/user/getByEmail_
- Research Document: _/research/document_
- Research Document by User ID: _/research/documentByUserId_
- Organization's Product Groups: _/entitlement/organization/productgroup/getList_
- Organization: _/organizations/id_
- User's Product Groups: _/entitlement/user/productgroup/getList_

### User by Email _(/user/getByEmail)_
Official Documentation: http://apidocs.oneaccess.io/docs/usergetorcreate

This method returns a `User` object if it matches the first name, last name, and email. If there's not a match, then a new user is created and returned.

#### How to use:
```ruby
resp = ONEAccess::API::User.getByEmail(first_name: 'Alex', last_name: 'Santos', email: 'alex@ae.com')

resp.data #=> instance of ONEAcess::DataObject::User
resp.data.id #=> 305 (id of the user)
resp.data.organization.id #=> 805 (id of the company)
resp.data.email #=> alex@ae.com
```

### Research Document _(/research/document)_
Official Documentation: http://apidocs.oneaccess.io/docs/researchdocument

This method retrieves a research document by providing the research ID and the first name, last name, and email of the user requesting access. If the user does not have access to the research, a `ONEAccess::Error:APIError` exception will be raisen.

#### How to use:
```ruby
begin
  resp = ONEAccess::API::Research.document(document_id: 2341, first_name: 'Alex', last_name: 'Santos', email: 'alex@ae.com')

  resp.data #=> instance of ONEAcess::DataObject::ResearchDocumentInfo
  resp.data.url #=> url of the document
  resp.data.title #=> document's title
  resp.data.saml #=> instance of ONEAccess::DataObject::SAMLInfo

  puts "requires SAML" unless resp.data.saml.nil?

rescue ONEAccess::Error::APIError => e
  if e.api_status_code == ONEAccess::APIStatusCode::OBJECT_NOT_FOUND
    puts "Not entitled or does not exist"
  end
end
```

### Research Document by User ID _(/research/documentByUserId)_
Official Documentation: http://apidocs.oneaccess.io/docs/researchdocumentbyuserid

Similar to the previous method, this method retrieves a research document by providing the research ID, but together with the user's ID instead. If the user does not have access to the research, a `ONEAccess::Error:APIError` exception will be raisen.

#### How to use:
```ruby
begin
  resp = ONEAccess::API::Research.document_by_user_id(document_id: 2341, user_id: 805)

  resp.data #=> instance of ONEAcess::DataObject::ResearchDocumentInfo
  resp.data.url #=> url of the document
  resp.data.title #=> document's title
  resp.data.saml #=> instance of ONEAccess::DataObject::SAMLInfo

  puts "requires SAML" unless resp.data.saml.nil?

rescue ONEAccess::Error::APIError => e
  if e.api_status_code == ONEAccess::APIStatusCode::OBJECT_NOT_FOUND
    puts "Not entitled or does not exist"
  end
end
```

### Symbology Companies _(/symbology/companies)_
Official Documentation: http://apidocs.oneaccess.io/docs/symbologycompanies

This method retrieves a list of symbology companies by providing a `IsPrivate`, `PageNumber` and `PageSize`.

#### How to use:
```ruby
resp = ONEAccess::API::Symbology.companies(is_private: false, page_number: 0, page_size: 20)

resp #=> instance of ONEAcess::Response::CompaniesResponse
resp.data #=> instance of Array containing ONEAcess::DataObject::CompanyLight

end
```

### Symbology Company _(/symbology/company/:id)_
Official Documentation: http://apidocs.oneaccess.io/docs/referencescountriesid

This method retrieves a company by providing an `Id`.

#### How to use:
```ruby
resp = ONEAccess::API::Symbology.company(id: 1)

resp #=> instance of ONEAcess::Response::CompanyResponse
resp.data #=> instance of Array containing ONEAcess::DataObject::Company

end
```

### Get Organization by ID _(/organizations/id)_
Official Documentation: http://apidocs.oneaccess.io/docs/organization-2

This method returns an Organization by providing the Organization ID.

#### How to use:
```ruby
resp = ONEAccess::API::Organizations.get_organization(id: 123)

resp.data #=> instance of ONEAcess::DataObject::Organization
resp.data.id #=> id of the Organization
resp.data.name #=> name of the Organization
resp.data.short_name #=> Short Name of the Organization
resp.data.active #=> Boolean meaning if the Organization is Active or not
resp.data.type #=> type of the Organization (Unspecified = 0, Buyside = 1, Sellside = 2, Advisory = 3, Other = 4, Vendor = 5, Internal = 6)
resp.data.main_address #=> instance of ONEAccess::DataObject::Address
resp.data.addresses #=> Array of instances of ONEAccess::DataObject::Address
```

### Research Entitlement

### Create an Research Entitlement request

Official documentation: http://apidocs.oneaccess.io/docs/entitlmentresearchuserrequestscreate

Creates a new Research Entitlement Request for the given User.

#### How to use
```ruby
begin
  resp = ONEAccess::API::Entitlement::Research::UserRequests.create(user_id:'123', sell_side_org_id:'456',
         sales_contact_first_name:'John', sales_contact_last_name:'Doe', sales_contact_email:'john.doe@example.com')

  resp.data #=> ID of the new Request
rescue ONEAccess::Error::APIError => e
  puts "Error creating the Research Entitlement Request: #{e}"
end
```