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 and v3.0 are 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:

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 Entitlement Requests: /entitlement/research/userRequests/getListWithEntitlementsStatus
• Subscribe to Entitlements Updates: /entitlement/userSubscription/subscribeToUpdates
• Get User ids which entitlements have changed /entitlement/userSubscription/subscribeToUpdates/changedUsers/getList
• Create email inducement: /providers/inducements

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:

resp = ONEAccess::API::V1_1::User.get_by_email(first_name: 'Alex', last_name: 'Santos', email: 'alex@ae.com')

resp.data #=> instance of ONEAccess::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:

begin
  resp = ONEAccess::API::V1_1::Research.document(document_id: 2341, first_name: 'Alex', last_name: 'Santos', email: 'alex@ae.com')

  resp.data #=> instance of ONEAccess::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:

begin
  resp = ONEAccess::API::V1_1::Research.document_by_user_id(document_id: 2341, user_id: 805)

  resp.data #=> instance of ONEAccess::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:

resp = ONEAccess::API::V1_1::Symbology.companies(is_private: false, page_number: 0, page_size: 20)

resp #=> instance of ONEAccess::Response::CompaniesResponse
resp.data #=> instance of Array containing ONEAccess::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:

resp = ONEAccess::API::V1_1::Symbology.company(id: 1)

resp #=> instance of ONEAccess::Response::CompanyResponse
resp.data #=> instance of Array containing ONEAccess::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:

resp = ONEAccess::API::V1_1::Organizations.get_organization(id: 123)

resp.data #=> instance of ONEAccess::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 a Research Entitlement request

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

Creates a new Research Entitlement Request for the given User.

How to use

begin
  resp = ONEAccess::API::V1_1::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

User Entitlement Requests (/entitlement/research/userRequests/getListWithEntitlementsStatus)

Official Documentation: http://apidocs.oneaccess.io/docs/entitlementresearchuserrequests

This method returns a list of user entitlement requests based on the specified UserIds, PageNumber, PageSize, SortBy, IsAscending, CreateDateFrom, CreateDateTo, SellSideOrgIds and EntitlementStatus parameter values.

How to use:

begin
  resp = ONEAccess::API::V1_1::Entitlement::Research::UserRequests.get_list

  resp.data #=> Array of instances of ONEAccess::DataObject::UserEntitlementRequest
rescue ONEAccess::Error::APIError => e
  puts "Error listing the available user entitlement requests"
end

Subscribe to Entitlements Updates (/entitlement/userSubscription/subscribeToUpdates)

Official Documentation: http://apidocs.oneaccess.io/docs/entitlmentusersubscriptionsubscribetoupdates

This method allows to subscribe for user entitlement updates providing the list of users that one wishes to receive updates from. Returns the API Status Code as the result of the subscription operation.

How to use:

begin
  resp = ONEAccess::API::V1_1::Entitlement::UserSubscription.subscribe(user_ids: [<user_ids>])

  resp #=> instance of ONEAccess::Response::SubscribeToUpdatesResponse
rescue ONEAccess::Error::APIError => e
  puts "Error subscribing users for entitlements updates"
end

Get User ids which entitlements have changed (/entitlement/userSubscription/subscribeToUpdates/changedUsers/getList)

Official Documentation: http://apidocs.oneaccess.io/docs/entitlementusersubscriptionsubscribetoupdateschangedusersgetlist

This method allows to get the list of user ids which the entitlements have changed. Can be provided a date to get the users who have changed entitlements after the provided date. If the date is not provided then it returns the user ids in which the entitlements have changed after the last call to this method. For example:

First call at 08/22/2016 11:55:00. Next call at 08/22/2016 15:55:00. Returns the user ids who have changed entitlements after 08/22/2016 11:55:00.

Use UTC time zone for date parameter.

How to use:

begin
  resp = ONEAccess::API::V1_1::Entitlement::UserSubscription.changed_users(from_date: <utc_string_date>)

  resp #=> instance of ONEAccess::Response::ChangedUsersResponse
rescue ONEAccess::Error::APIError => e
  puts "Error getting the list of user ids which entitlements have changed"
end

Get Contributors (/references/contributors)

Official Documentation: http://apidocs.oneaccess.io/v2.0/docs/referencescontributors

Reference endpoint to help retrieve contributor IDs from names.

How to use:

begin
  resp = ONEAccess::API::V3_0::References.contributors(contributor_names: [<names>], limit: <limit>, offset: <offset>)

  resp #=> instance of ONEAccess::Response::ContributorsResponse
rescue ONEAccess::Error::APIError => e
  puts "Error getting the list of contributors"
end

Create Inducement (/providers/inducements)

Reference endpoint to create inducements for a given research.

How to use:

begin
  resp = ONEAccess::API::V3_0::Providers.inducements(recipient_user_id: 186, sender_email: "admin@admin.com", subject: "Inducement", email_body: "This email is an inducement.", receive_date: "2018-02-21 19:03:12" )
  resp #=> instance of ONEAccess::Response::InducementResponse
rescue ONEAccess::Error::APIError => e
  puts "Error creating the inducement"
end

Get Providers Users Details (/providers/GetProviderUserDetails)

Reference endpoint to get providers users details information.

How to use:

begin
  resp = ONEAccess::API::V3_0::Providers.users_details(buy_side_org_id: 1, provider_id: 1, contract_status_id: 1, user_id: 1, user_email: 'hello@example.com', user_reverse_entitlement_status: 1, vendor_id: 1, reverse_entitlement_status: 1)
  resp #=> instance of Array containing ONEAccess::DataObject::ProvidersUsersDetails
rescue ONEAccess::Error::APIError => e
  puts "Error getting providers users details"
end