approval_hub 0.0.3

data/README.md

@@ -0,0 +1,79 @@
+Approval Hub API
+================
+A simple library for talking to the Enterprise Approval Hub.
+See the rdoc for detailed usage instructions
+
+quick start
+-----------
+install the gem
+
+  gem install approval_hub
+  
+require and use
+
+  require 'approval_hub'
+  
+  # default uat instance
+  api = ApprovalHub::API.uat(username,password)
+ 
+  # default prod instance
+  api = ApprovalHub::API.prod(username,password)
+  
+  # register an approval
+  api.register do |r|
+     r.request_id        = "001"
+     r.requestor_id      = "neilcuk"
+     r.approver_id       = "kasperdulles[,others..]"
+     r.short_description = "A summary"
+     r.long_description  = "A lengthier expose"
+     r.url               = "http://url.to.source/system"
+  end
+  
+  # get details
+  api.details(request_id)
+  
+  # get approval status
+  api.status(request_id)
+  
+  # approve a request
+  api.approve(request_id, approver_id)
+  
+  # cancel a request
+  api.cancel(request_id, approver_id)
+  
+  # decline a request
+  api.decline(request_id, approver_id)
+  
+troubleshooting
+---------------
+All methods come with a bang version *method!* which
+will throw relevant exceptions
+
+If you want to see what is happening with the http
+session, grab an API instance with debugging enabled
+
+  api = ApprovalHub::API.uat_with_debugging(username,password)
+  # or
+  api = ApprovalHub::API.prod_with_debugging(username,password)
+
+The URL's for each of the instances are set in the root
+of the module. It's unlikely these will change. If for
+some reason they do and I can't get around to updating
+the package you can use the default constructor
+  
+  # include a url and boolean indicating whether to turn on
+  # http session debugging 
+  api = ApprovalHub::API.new(url,username,password,enable_debugging)
+
+
+The Enterprise Approval Hub facilitates centralised 
+sign-off for any kind of request. See
+http://wiki.office.aol.com/wiki/ApprovalKiosk
+
+acknowledgements
+----------------
+Thanks to [HTTParty](https://github.com/jnunemaker/httparty) for making http fun!
+
+bugs
+----
+Send me an email

data/lib/approval_hub.rb

@@ -0,0 +1,23 @@
+module ApprovalHub
+  # approval hub API interfaces
+  REGISTER = "/Register"
+  DETAILS = "/getDetails"
+  DECLINE = "/DeclineRequest"
+  APPROVE = "/ApproveRequest"
+  CANCEL = "/deleteRequest"
+  
+  # approval hub status responses
+  PENDING = "Open"
+  APPROVED = "Approve"
+  REJECTED = "Decline"
+  NOT_FOUND = "Not Found"
+  
+  # default URLs
+  URL_UAT = "http://csoweb-m01.office.aol.com:8080/EnterpriseApprovalWS/hub/system"
+  URL_PROD = "https://approvals-hub.office.aol.com/EnterpriseApprovalWS/hub/system"  
+end
+
+require 'approval_hub/request'
+require 'approval_hub/detail'
+require 'approval_hub/api'
+

data/lib/approval_hub/api.rb

@@ -0,0 +1,255 @@
+require 'httparty'
+
+module ApprovalHub
+  #
+  # The ApprovalHub API
+  # 
+  class API
+    include HTTParty
+    
+    class << self
+      
+      # get an instance of the uat hub
+      # requires a username and password
+      #
+      def uat(username, password)
+        new(URL_UAT,username,password)
+      end
+      
+      # get an instance of the prod hub
+      # requires a username and password
+      #
+      def prod(username, password)
+        new(URL_PROD,username,password)
+      end
+      
+      # get an instance of the uat hub with session debugging
+      # requires a username and password
+      #
+      def uat_with_debugging(username,password)
+        new(URL_UAT,username,password, true)
+      end
+      
+      # get an instance of the prod hub with session debugging
+      # requires a username and password
+      #
+      def prod_with_debugging(username,password)
+        new(URL_PROD,username,password, true)
+      end
+      
+      # get an instance of your choosing
+      # requires a url, username, password and boolean indicating
+      # whether or not to turn on session debugging
+      #
+      def custom_config(config={})
+        raise(ArgumentError, "config cannot be empty") if config.empty?
+        new(config["url"], config["username"], config["password"], config["with_debugging"])
+      end
+    end
+    
+    def initialize(url, username, password, with_debugging=false)
+      raise ArgumentError if url.nil? || username.nil? || password.nil?
+      unless url.nil?
+        @uri = url
+      end
+      @auth = {:user => username, :pw => password}
+      if with_debugging
+        self.class.debug_output $stderr
+      end
+    end
+    
+    # Register your approval request with the hub
+    # Registration takes a Request object or a block
+    # returns true is successful else false
+    #
+    # example1:
+    #  api = ApprovalHub::API.uat("someuser","somepwd")
+    #  api.register do |r|
+    #     r.request_id        = "001"
+    #     r.requestor_id      = "neilcuk"
+    #     r.approver_id       = "kasperdulles[,others..]"
+    #     r.short_description = "A summary"
+    #     r.long_description  = "A lengthier expose"
+    #     r.url               = "http://url.to.source/system"
+    #  end
+    # 
+    # example2:
+    #  api = ApprovalHub::API.uat("someuser","somepwd")
+    #  r = ApprovalHub::Request.new
+    #  r.request_id        = "001"
+    #  r.requestor_id      = "neilcuk"
+    #  r.approver_id       = "kasperdulles[,others..]"
+    #  r.short_description = "A summary"
+    #  r.long_description  = "A lengthier expose"
+    #  r.url               = "http://url.to.source/system"
+    #  api.register(r)
+    #
+    def register(request = Request.new, &block)
+  	  register!(request,&block) rescue false
+    end
+    
+    # Same as register but will throw an exception
+    # if it encounteres an error
+    #
+    def register!(request = Request.new, &block)
+      begin
+        options = assemble_request(request,&block) 
+  	    request = self.class.get( @uri + REGISTER, options )
+      rescue Exception => e
+        raise e, "Unable to register approval request"
+      end
+      if request.response.code != "200"
+        raise "Approval hub denied request registration with code #{request.response.code}"
+      end
+      true
+    end
+    
+    # Retrieves a Detail object from the hub
+    # requires a request_id
+    # returns false if an error occured
+    # takes an optional block which will be passed
+    # the detail object
+    # 
+    def details(request_id, &block)
+      details!(request_id, &block) rescue false
+    end
+    
+    # Same as details but will throw an exception
+    # if it encounters an error
+    #  
+    def details!(request_id, &block)
+      raise "Request ID cannot be nil" if request_id.nil?
+      begin
+        options = {
+          :query => {
+            :requestID => request_id
+          }.merge!(@auth)
+        }
+        detail = self.class.get( @uri + DETAILS, options )
+        if detail["response"]["status"] == 200
+          detail = Detail.new(detail["ApprovalList"][0])
+          if block_given?
+            yield detail
+          else
+            detail
+          end
+        else
+          raise ArgumentError, "request not found"
+        end
+      rescue Exception => e
+        raise e, "Unable to retrieve details for #{request_id}"
+      end
+    end
+    
+    # Returns the status of the provided request id
+    # or false if some error occured
+    #
+    def status(request_id)
+      status!(request_id) rescue false
+    end
+    
+    # Same as status but will throw an excption
+    # if it encounters an error
+    #
+    def status!(request_id)
+      detail = details!(request_id)
+      if detail.open?
+        "Pending Approval"
+      elsif detail.approved?
+        "Approved"
+      elsif detail.declined?
+        "Declined"
+      end
+    end
+    
+    # Approve an open request
+    # Returns true if successful else false
+    #
+    def approve_request(request_id, approver_id)
+      approve_request!(request_id,approver_id) rescue false
+    end
+    
+    # Same as approve_request but will throw
+    # exception on error
+    #
+    def approve_request!(request_id, approver_id)
+      update_request(request_id,approver_id, ApprovalHub::APPROVE)
+    end
+    
+    # Cancel an open request
+    # Returns true if successful else false
+    #
+    def cancel_request(request_id, approver_id)
+      cancel_request!(request_id,approver_id) rescue false
+    end
+    
+    # Same as cancel_request but will throw
+    # exception on error
+    #
+    def cancel_request!(request_id, approver_id)
+      update_request(request_id,approver_id, ApprovalHub::CANCEL)
+    end
+    
+    # decline an open request.
+    # Takes an optional reason for rejection
+    # Returns true if success else false
+    #
+    def decline_request(request_id, approver_id, reason=nil)
+      decline_request!(request_id,approver_id,reason) rescue false
+    end
+    
+    # Same as decline_request but will throw
+    # exception on error
+    #
+    def decline_request!(request_id, approver_id, reason=nil)
+      update_request(request_id,approver_id, ApprovalHub::DECLINE,reason)
+    end
+    
+    private
+    
+    def update_request(request_id, approver_id, action, reason=nil)
+      options = { 
+  	    :query => { 
+  	      :requestID => request_id,
+  	      :actionedByCdid => approver_id,
+  	      :actionedByName => approver_id,
+  	      :actionedByWhen => Time.now.strftime("%Y-%m-%d %H:%M:%S"),
+  	      :reason         => reason
+  	    }.merge!(@auth) 
+  	  }
+  	  begin
+  	    response = self.class.get( @uri + action, options )
+  	    if response["status"] == 200
+  	      true
+  	    elsif response["status"] == 202
+  	      raise ArgumentError, "Request with id #{request_id} does not exist"
+  	    else
+  	      false
+  	    end
+  	  rescue Exception => e
+  	    raise e, "Unable to update approval request"
+  	  end
+    end
+    
+    def assemble_request(request,&block)
+      if block_given?
+        yield request
+      end
+      raise "approval request not valid" if not request.is_valid?
+      options ={
+        :query => {
+          :state =>'open', # default required during registration
+          :requestID => request.request_id,
+          :shortDescription => request.short_description,
+  	      :longDescription => request.long_description,
+  	      :url => request.url,
+  	      :requestorCdid => request.requestor_id,
+  	      :approverCdid => request.approver_id,
+  	      :requestTime => Time.now.strftime("%Y-%m-%d %H:%M:%S")
+        }.merge!(@auth)
+      }
+    end
+    
+  end
+  
+end

data/lib/approval_hub/detail.rb

@@ -0,0 +1,31 @@
+module ApprovalHub
+  class Detail
+    attr_reader :request_id, :long_description, :short_description
+    attr_reader :requestor_id, :approver_id, :url, :reason, :state
+    
+    def initialize(hash={})
+      unless hash.empty?
+        @request_id         = hash["requestID"]
+        @long_description   = hash["longDescription"]
+        @short_description  = hash["shortDescription"]
+        @requestor_id       = hash["requestorCDID"]
+        @approver_id        = hash["actionedByCDID"]
+        @url                = hash["url"]
+        @reason             = hash["reason"]
+        @state              = hash["state"]
+      end
+    end
+    
+    def approved?
+      not (state =~ /#{ApprovalHub::APPROVED}/i).nil?
+    end
+    
+    def declined?
+      not (state =~ /#{ApprovalHub::REJECTED}/i).nil?
+    end
+    
+    def open?
+      not (state =~ /#{ApprovalHub::PENDING}/i).nil?
+    end
+  end
+end

data/lib/approval_hub/request.rb

@@ -0,0 +1,19 @@
+module ApprovalHub
+  # A Request is passed to the hub for registration
+  #
+  class Request
+    attr_accessor :request_id, :long_description, :short_description
+    attr_accessor :requestor_id, :approver_id, :url
+  
+    # Will return false if fields have not been set
+    # TODO - return an errors hash stating why the request is not valid
+    def is_valid?
+      not request_id.nil?         ||
+          long_description.nil?   ||
+          short_description.nil?  ||
+          requestor_id.nil?       ||
+          approver_id.nil?        ||
+          url.nil?
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: approval_hub
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+  prerelease: 
+platform: ruby
+authors:
+- Neil Chambers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A library for interacting with the Enterprise Approval Kiosk
+email: neil.chambers@teamaol.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/approval_hub/api.rb
+- lib/approval_hub/detail.rb
+- lib/approval_hub/request.rb
+- lib/approval_hub.rb
+- README.md
+homepage: http://wiki.office.aol.com/wiki/ApprovalKiosk
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Approval Hub API
+test_files: []