s2_netbox 0.0.1.pre → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 55443e3415036a124d1b1501115d3e3b7535e58f
-  data.tar.gz: 24205f66709d5862b25c92dc26e21cfb4c4a3eb4
+  metadata.gz: b70e6ef03b4e2e70b559e99aed3d310be1a9937f
+  data.tar.gz: fca51277062f1225a2362ffdc851439bc37622c6
 SHA512:
-  metadata.gz: 689d3c3d2d1cd1f8dff87625d3fa26c1e2ff52d72dbf962e3485a5e3bcc70a6a3c7fec6db4ace1bca66015b8299cb96ab4a94ae8e323c08d008773d371c4d3d9
-  data.tar.gz: e0eb5a19555ec1278f667908aef345246de75faa8f630af6df56045daf51d5182a00869e255720026d523272e7b62b8fb6d6d4a06420c5bdeb5b0c4340190795
+  metadata.gz: d4e62ff92d0d570d6f18f714732da57118e1c0f75ddd06dae914d7ef8eec1a0499cd209bb2eb12371e36e19855591eefc1d2d113cb5cf9d40865f2ab02490e28
+  data.tar.gz: 1d6fc17fe9d3188e5488b7ac665186d4de36ee2f9a92a542ffeb5b88462814a6f646f756a6a5305c8d78bb13d5c8d54497653a91ffa1d2d88ebf8398caa5f178

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /.idea
+s2_netbox-*.gem

data/README.md

@@ -1,16 +1,20 @@
-[![CircleCI](https://circleci.com/gh/teamsquare/s2_netbox/tree/develop.svg?style=svg)](https://circleci.com/gh/teamsquare/s2_netbox/tree/develop)
-[![Code Climate](https://codeclimate.com/github/teamsquare/s2_netbox/badges/gpa.svg)](https://codeclimate.com/github/teamsquare/s2_netbox)
-[![Test Coverage](https://codeclimate.com/github/teamsquare/s2_netbox/badges/coverage.svg)](https://codeclimate.com/github/teamsquare/s2_netbox/coverage)
-[![Issue Count](https://codeclimate.com/github/teamsquare/s2_netbox/badges/issue_count.svg)](https://codeclimate.com/github/teamsquare/s2_netbox)
+[![CircleCI](https://circleci.com/gh/Teamsquare/s2_netbox/tree/develop.svg?style=svg)](https://circleci.com/gh/teamsquare/s2_netbox/tree/develop)
+[![Code Climate](https://codeclimate.com/github/Teamsquare/s2_netbox/badges/gpa.svg)](https://codeclimate.com/github/teamsquare/s2_netbox)
+[![Test Coverage](https://codeclimate.com/github/Teamsquare/s2_netbox/badges/coverage.svg)](https://codeclimate.com/github/teamsquare/s2_netbox/coverage)
+[![Issue Count](https://codeclimate.com/github/Teamsquare/s2_netbox/badges/issue_count.svg)](https://codeclimate.com/github/teamsquare/s2_netbox)
 
 This gem provides Ruby bindings to the [S2 NetBox](http://s2sys.com/products/access-control-systems/netbox/) API for [S2 Security Systems](http://s2sys.com/) products.
+
 # Currently Supported API methods
+
 This Gem has been written pretty specifically for the needs of Teamsquare's internal management systems.
-Although every method **should** work if you follow the right conventions, only the specific ones we're using have been built out and tested.
+
+Through `S2Netbox::ApiRequest` class you **should** be able to invoke any API command on the S2 controller by hand, however only the specific ones we're using have been built out and tested.
 
 The specific methods we're using have been documented under the Usage section.  See the section "Other Commands" for details on how to invoke any arbitrary command in addition to the list of "supported" commands below.
 
 # Installation
+
 Add this line to your application's Gemfile:
 
     gem 's2_netbox'
@@ -24,18 +28,23 @@ Or install it yourself as:
     $ gem install s2_netbox
 
 # Configuration
+
 A call to `S2Netbox.configure` must be made before API requests can be made.  This sets up the controller's base URL as well as the username and password used when logging in.
 
 ```ruby
 S2Netbox.configure do |config|
-    config.controller_url = 'https://controller-host'	
+    config.controller_url = 'https://controller-host'
     config.username = 'api'
     config.password  = '[W2tnwoUdE+/97o8nmi#P77t'
 end
-```    
+```
+
 If you're using the S2Netbox gem in a Rails app, this could be placed in an initializer.
+
 # Usage
+
 All requests are bundled up into the required XML parcel with the required `COMMAND` and `PARAMS`.
+
 Once sent to the configured S2 controller, the response is wrapped up in an instance of `S2Netbox::Response` which includes the following accessors:
 
 * `code`
@@ -46,62 +55,85 @@ Once sent to the configured S2 controller, the response is wrapped up in an inst
 * `raw_response`
 * `session_id`
 
-`code` returns the raw code response which is typcially either `SUCCESS` or `FAIL`, but sometimes has weird other alternatives, such as `DUPLICATE` or `NOT FOUND` just to keep things interesting.
+`code` returns the raw code response which is typically either `SUCCESS` or `FAIL`, but sometimes has weird other alternatives, such as `DUPLICATE` or `NOT FOUND` just to keep things interesting.
 
 `success` is a boolean indicating if the `code` was `SUCCESS`.  Any other value for `code` results in `success` being `false`.
 
-`details` is a hash of the returned details. For example, when getting a Person object, this will contain the person's attributes, such as `FIRSTNAME` and `LASTNAME` as well as a hash of `ACCESSLEVELS`.  The details hash is keyed off the raw names of the XML attributes in the response (uppercase names, as a string, not symbole) so access them like:
+`details` is a hash of the returned details. For example, when getting a Person object, this will contain the person's attributes, such as `FIRSTNAME` and `LASTNAME` as well as a hash of `ACCESSLEVELS`.  The details hash is keyed off the raw names of the XML attributes in the response (uppercase names, as a string, not symbol) so access them like:
 
-    @result.details['FIRSTNAME']
-    
-not
+```ruby
+@result.details['FIRSTNAME']
+```
 
-    @result.details[:first_name]
+not
 
-`error_message` is populated with the error mesage returned from the system assuming `code` is not `SUCCESS`.
+```ruby
+@result.details[:first_name]
+```
+`error_message` is populated with the error message returned from the system assuming `code` is not `SUCCESS`.
 
 The `raw_request` and `raw_response` store the contents of the HTTP Post request and response respectively, so you can troubleshoot exactly what XML was sent and received by the systems.
 
 `session_id` contains the value of the `session_id` attribute if it exists on the root `<NETBOX>` element in the `raw_response`.  This is only populated in response to the `Login` command.  Use this when parsing the result of a `Login` attempt and store the `session_id` for future requests.
 
 # Authentication
-The gem supports authentication by username and password only. Although you can configure it to use the `sha_password` method of authentication, at pesent the MAC signature is not generated or included with any request.
+
+The gem supports authentication by username and password only. Although you can configure it to use the `sha_password` method of authentication, at present the MAC signature is not generated or included with any request.
 
 If your S2 system requires authentication via the `sha_password` and MAC signing, feel free to open a pull request :) Our systems are partitioned and don't use this form of authentication, but we'd love to accept a pull request to add this fucntionaltiy for other users.
+
 ## Login
+
 Login is used to establish a session and obtain a `session_id` which is used in subsequent requests:
 
+```ruby
       @result = S2Netbox::Commands::Authentication.login
+```
 
-To get an instance of `S2Netbox::Response` which (assuming log in is succesful) will include the `session_id` which can be used in subsequent requests:
+To get an instance of `S2Netbox::Response` which (assuming log in is successful) will include the `session_id` which can be used in subsequent requests:
 
+```ruby
     @result.session_id
+```
 
 ## Logout
+
 All sessions must be logged out. According to the S2 documentation:
 
 > WARNING: Failure to match every call to ‘Login’ with a call to ‘Logout’ will result in the accumulation of session files, consuming potentially large amounts of disk space.
 
 To log out, issue the `logout` command:
 
-    @result = S2Netbox::Commands::Authentication.logout('session_id_from_login')
+```ruby
+@result = S2Netbox::Commands::Authentication.logout('session_id_from_login')
+```
 
 # Version
+
 The `Version` module allows you to query the current API version.  This is really just an easy way to validate you're successfully connected to the S2 Controller and have a valid session.
 ## GetVersion
-    @result = S2Netbox::Commands::ApiVersion.get_version('session_id_from_login')
+
+```ruby
+@result = S2Netbox::Commands::ApiVersion.get_version('session_id_from_login')
+```
+
 The result object will contain the version (assuming you've successfully logged in):
 
-    :001 > puts @result.details['APIVERSION']
-    4.1
+```ruby
+:001 > puts @result.details['APIVERSION']
+4.1
+```
 
 # Person
-The `Person` module allows you to add and modfy Pereson records.
+
+The `Person` module allows you to add and modify Person records.
+
 ## AddPerson
+
 The `add_person` method accepts 3 arguments:
 
 1. Hash of person attributes
-1. List of access levels 
+1. List of access levels
 1. List of User Defined Fields
 1. (Optional) session_id
 
@@ -115,13 +147,16 @@ The `add_person` method accepts 3 arguments:
     }, %w(AccessLevel1 AccessLevel2), 'UDF1'
 )
 ```
+
 Both access levels and user defined fields can be specified either as a single string or as an array of strings.
+
 ## ModifyPerson
+
 The `modify_person` method allows you to modify an existing person, and is similar to the `add_person` method, but has an additional argument:
 
 1. Person ID
 1. Hash of person attributes
-1. List of access levels 
+1. List of access levels
 1. List of User Defined Fields
 1. (Optional) session_id
 
@@ -133,9 +168,80 @@ The `modify_person` method allows you to modify an existing person, and is simil
     :act_date => '10/10/2016'
 }, %w(AccessLevel1 AccessLevel2), 'UDF1')
 ```
+
 Access levels and user defined fields are replaced with those values specified in this call, and aren't additive to existing access levels or user defined fields.
-# Credentials
 
+# Credential
+
+## Add
+
+The `add` method accepts 2 arguments:
+
+1. Hash of credential attributes
+1. (Optional) session_id
+
+```ruby
+@result = S2Netbox::Commands::Credential.add({
+    :person_id => '8a806ed6-0246-49d0-b7a7-ab6402da01e3',
+    :encoded_num => '3113',
+    :card_format => '26 bit Wiegand'
+})
+```
+
+This will add a 26 bit Wiegand encoded card with card number 3113 to the Person record identified by ID `8a806ed6-0246-49d0-b7a7-ab6402da01e3` in the S2 controller.
+
+
+## Modify
+
+The `modify` method accepts 2 arguments:
+
+1. Hash of credential attributes
+1. (Optional) session_id
+
+```ruby
+@result = S2Netbox::Commands::Credential.add({
+    :encoded_num => '3113',
+    :disabled => 1
+})
+```
+
+This example will set `disabled` to `1` (a truthy value) for the credential identified with the `ENCODEDNUM` of `3113` in the S2 Controller.
+
+# Other Commands
+
+By using the `S2Netbox::ApiRequest` class directly, you can send any command to the S2 Controller.
+
+The `send_request` method allows commands to be sent to the S2 Controller and accepts the following arguments:
+
+1. The command name
+1. A hash of the command attributes
+1. (Optional) session_id
+
+For instance, although untested, you should be able to set a lockdown level by sending the command:
+
+```ruby
+S2Netbox::ApiRequest.send_request('SetThreatLevel', {:level_group_name => 'Elevated'})
+```
+
+Will set the current threat level to the threat level with a name of `Elevated` in the S2 Controller.
+
+## Sending commands to other endpoints
+
+The `S2Netbox::ApiRequest.send_request` method sends requests to the `/goforms/nbapi` endpoint.
+
+For finer grained control and advanced requests, including the ability to change this path, you can call the lower level `S2Netbox.request` method.
+
+The `S2Netbox::request` method takes three arguments:
+
+1. Url
+1. Command
+1. (Optional) session_id
+
+The `url` argument is the path to the API endpoint, such as `/goforms/nbapi`.
+
+The `command` argument is the raw XML command that will be placed within the `<NETBOX-API>` element.
+
+Pass in the optional `session_id` if you’re using username and password based authentication.
 
 # Development
 
@@ -153,5 +259,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 # License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/s2_netbox/api_request.rb

@@ -16,7 +16,16 @@ class S2Netbox::ApiRequest
   def self.method_missing(method_name, *arguments, &block)
     return super unless supported_operations.include?(method_name)
 
-    send_request(command_for_method(method_name), map_attributes(arguments[0]), arguments[1])
+    attributes = arguments[0]
+    session_id = arguments[1]
+
+    if arguments.length == 1 && !arguments[0].is_a?(Hash)
+      # there is only a single argument, and it isn't a hash - assume it is session_id
+      attributes = nil
+      session_id = arguments[0]
+    end
+
+    send_request(command_for_method(method_name), map_attributes(attributes), session_id)
   end
 
   def self.respond_to_missing?(method_name, include_private = false)
@@ -37,7 +46,7 @@ class S2Netbox::ApiRequest
     if command_map && command_map[method_name]
       return command_map[method_name]
     else
-      return "#{method_name.to_s.gsub('_', ' ').titlecase.gsub(' ', '')}#{name.split('::').last}"
+      return "#{method_name.to_s.tr('_', ' ').titlecase.delete(' ')}#{name.split('::').last}"
     end
   end
 
@@ -46,7 +55,7 @@ class S2Netbox::ApiRequest
 
     params.each do |k, v|
       if v.is_a?(Hash)
-        res << "<#{k.to_s}>"
+        res << "<#{k}>"
 
         singular = v[:singular_node_name]
 
@@ -54,9 +63,9 @@ class S2Netbox::ApiRequest
           res << "<#{singular}>#{inner_value}</#{singular}>"
         end
 
-        res << "</#{k.to_s}>"
+        res << "</#{k}>"
       else
-        res << "<#{k.to_s}>#{v}</#{k.to_s}>"
+        res << "<#{k}>#{v}</#{k}>"
       end
     end
 
@@ -70,6 +79,6 @@ class S2Netbox::ApiRequest
   def self.map_attributes(attributes)
     return unless attributes
 
-    attributes.reject { |_,v| blank?(v) }.map { |k, v| [k.to_s.gsub('_', '').upcase, v] }.to_h
+    attributes.reject { |_,v| blank?(v) }.map { |k, v| [k.to_s.delete('_').upcase, v] }.to_h
   end
 end

data/lib/s2_netbox/commands/person.rb

@@ -12,8 +12,6 @@ class S2Netbox::Commands::Person < S2Netbox::ApiRequest
     send_request('ModifyPerson', person_attributes, session_id)
   end
 
-  protected
-
   def self.build_attributes(attributes, access_levels, user_defined_fields)
     hash = map_attributes(attributes)
     hash = build_user_defined_fields(hash, user_defined_fields)
@@ -24,7 +22,7 @@ class S2Netbox::Commands::Person < S2Netbox::ApiRequest
 
   def self.build_access_level(hash, access_levels)
     unless access_levels.empty?
-      hash['ACCESSLEVELS'] = {:singular_node_name => 'ACCESSLEVEL', :values => access_levels}
+      hash['ACCESSLEVELS'] = {:singular_node_name => 'ACCESSLEVEL', :values => Array.wrap(access_levels)}
     end
 
     hash

data/lib/s2_netbox/version.rb

@@ -1,3 +1,3 @@
 module S2Netbox
-  VERSION = '0.0.1.pre'
+  VERSION = '0.0.1'
 end

data/s2_netbox.gemspec

@@ -19,15 +19,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'httparty'
-  spec.add_runtime_dependency 'activesupport'
-  spec.add_runtime_dependency 'facets'
+  spec.add_runtime_dependency 'httparty', '~> 0.14'
+  spec.add_runtime_dependency 'activesupport', '~> 4.0'
+  spec.add_runtime_dependency 'facets', '~> 3.1'
 
   spec.add_development_dependency 'bundler', '~> 1.12'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec_junit_formatter', '0.2.2'
   spec.add_development_dependency 'simplecov', '~> 0.7.1'
-  spec.add_development_dependency 'webmock'
-  spec.add_development_dependency 'factory_girl'
+  spec.add_development_dependency 'webmock', '~> 2.1'
+  spec.add_development_dependency 'factory_girl', '~> 4.7'
 end

metadata

@@ -1,57 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: s2_netbox
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre
+  version: 0.0.1
 platform: ruby
 authors:
 - Teamsquare
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-10 00:00:00.000000000 Z
+date: 2016-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: facets
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -126,30 +126,30 @@ dependencies:
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: factory_girl
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.7'
 description: S2 is an enterprise class, feature-rich web-based access control and
   event monitoring system. This Ruby wrapper makes integrating with the API on NetBox
   controllers easy. See http://s2sys.com/ for more information.
@@ -197,9 +197,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.8