trizetto-api 0.1.2 → 0.2.1

data/lib/trizetto/api/eligibility/web_service/benefit_entity.rb

@@ -0,0 +1,54 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # When a benefit is related to an entity, such as a primary care provider,
+        # the entity details are captured here
+        #
+        # <b>Example XML</b>
+        #   <benefitentity>
+        #     <entitycode>Primary Care Provider</entitycode>
+        #     <name>JULIUS</name>
+        #     <first>GROLLMAN</first>
+        #     <identification_code_qualifier>Health Care Financing Administration National Provider Identifier</identification_code_qualifier>
+        #     <benefit_related_entity_id>1609858695</benefit_related_entity_id>
+        #     <benefit_related_entity_address_1>4101 TORRANCE BLVD</benefit_related_entity_address_1>
+        #     <benefit_related_entity_city>TORRANCE</benefit_related_entity_city>
+        #     <benefit_related_entity_state>CA</benefit_related_entity_state>
+        #     <benefit_related_entity_zip>90503</benefit_related_entity_zip>
+        #     <communicationnumberqualifier>Telephone</communicationnumberqualifier>
+        #     <communicationnumber>3103035750</communicationnumber>
+        #   </benefitentity>
+        #
+        # <b>Example</b>
+        #   benefit.entity.entity_code                   # => "Primary Care Provider"
+        #   benefit.entity.name                          # => "JULIUS"
+        #   benefit.entity.first                         # => "GROLLMAN"
+        #   benefit.entity.id                            # => "1609858695"
+        #   benefit.entity.identification_code_qualifier # => "Health Care Financing Administration National Provider Identifier"
+        #   benefit.entity.city                          # => "TORRANCE"
+        #   benefit.entity.communication_number          # => "3103035750"
+        #
+        class BenefitEntity < Node
+          KEY_CLEANUP =
+          {
+            entitycode:                   :entity_code,
+            communicationnumberqualifier: :communication_number_qualifier,
+            communicationnumber:          :communication_number,
+          }
+
+          PREFIX_TRANSLATIONS =
+          [
+            :benefit_related_entity
+          ]
+
+          def initialize(raw_hash = {})
+            super(raw_hash)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/trizetto/api/eligibility/web_service/dependent.rb

@@ -0,0 +1,72 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+        # A dependent in the eligibility XML.
+        #
+        # <b>NOTE: Not all fields have been transcribed to objects</b>
+        #
+        # <b>Example XML</b>
+        #
+        #   <dependent>
+        #     <trace_number>999999999</trace_number>
+        #     <trace_id>99TRIZETTO</trace_id>
+        #     <subscriberaddinfo>
+        #       <subsupplementalid>99</subsupplementalid>
+        #       <grouppolicynum>999</grouppolicynum>
+        #     </subscriberaddinfo>
+        #     <subscriberaddinfo>
+        #       <subsupplementalid>6P</subsupplementalid>
+        #       <grouppolicynum>999999999A6AG999</grouppolicynum>
+        #       <plansponsorname>BERGE-GREENHOLT</plansponsorname>
+        #     </subscriberaddinfo>
+        #     <date>
+        #       <datequalifier>Plan</datequalifier>
+        #       <date-of-service>20160101-99991231</date-of-service>
+        #     </date>
+        #     <date>
+        #       <datequalifier>Service</datequalifier>
+        #       <date-of-service>20180116</date-of-service>
+        #     </date>
+        #     <patientname>
+        #       <first>JUANA</first>
+        #       <middle>M</middle>
+        #       <last>ORN</last>
+        #     </patientname>
+        #     <sex>F</sex>
+        #     <date-of-birth>19630717</date-of-birth>
+        #     <relationship>
+        #       <insuredindicator>No</insuredindicator>
+        #       <relationshipcode>Spouse</relationshipcode>
+        #       <relationshiptypecode>Change</relationshiptypecode>
+        #       <relationshipreasoncode>Change in Identifying Data Elements</relationshipreasoncode>
+        #     </relationship>
+        #     <benefit>
+        #       <info>Active Coverage</info>
+        #       <coveragelevel>Employee and Spouse</coveragelevel>
+        #       <servicetype>Health Benefit Plan Coverage</servicetype>
+        #       <servicetypecode>30</servicetypecode>
+        #       <insurancetype>Preferred Provider Organization (PPO)</insurancetype>
+        #       <insurancetypecode>PR</insurancetypecode>
+        #       <plancoveragedescription>CDHP</plancoveragedescription>
+        #     </benefit>
+        #   </dependent>
+        #
+        # <b>Example</b>
+        #
+        #   dependent.trace_number   # => "999999999"
+        #   dependent.name.first     # => "JUNNA"
+        #   dependent.name.middle    # => "M"
+        #   dependent.name.last      # => "ORN"
+        #   dependent.name.sex       # => "F"
+        #   dependent.name.benefits  # => [ Array of Benefits ]
+        class Dependent < Patient
+          def initialize(raw_hash = {})
+            super(raw_hash)
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/trizetto/api/eligibility/web_service/do_inquiry_response.rb

@@ -0,0 +1,168 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # The parsed response from an eligibility check
+        class DoInquiryResponse
+
+          # The SuccessCode in the XML response from the eligibility request.
+          #
+          # Takes on one of these values
+          # * <tt>Success</tt>                    - The request was well formed and  not missing any fields
+          # * <tt>ValidationFailure</tt>          - The request was not valid. Maybe a field  was formatted incorrectly or omitted.
+          # * <tt>PayerTimeout</tt>               - ?
+          # * <tt>PayerNotSupported</tt>          - ?
+          # * <tt>SystemError</tt>                - ?
+          # * <tt>PayerEnrollmentRequired</tt>    - ?
+          # * <tt>ProviderEnrollmentRequired</tt> - ?
+          # * <tt>ProductRequired</tt>            - ?
+          attr_accessor :success_code
+
+          # For a successful request that returned an eligibility response, the
+          # transaction identifier from Trizetto.  Seems to be 30 random alpha
+          # numeric characters
+          attr_accessor :transaction_id
+
+          # For a successful request, the name of the payer (insurance company)
+          attr_accessor :payer_name
+
+          # For a successful request, the identifier of the payer (insurance company)
+          attr_accessor :payer_id
+
+          # Any validation error or messages provided in the response
+          #
+          # *Example*
+          #   client.extra_processing_info.messages                                  # => ["Invalid InsuredFirstName Length."]
+          #   client.extra_processing_info.validation_failures.first.affected_fields # => ["InsuredFirstName"]
+          #   client.extra_processing_info.validation_failures.first.message         # => "Invalid InsuredFirstName Length."
+          #
+          # @see ExtraProcessingInfo
+          #
+          attr_accessor :extra_processing_info
+
+          # The eligibility response xml parsed into a hash.
+          attr_accessor :eligibility_response_as_hash
+
+          # The Subscriber in the eligibility XML.
+          #
+          # @see Subscriber
+          attr_accessor :subscriber
+
+          # The Dependent in the eligibility XML.
+          #
+          # @see Dependent
+          attr_accessor :dependent
+
+          # The infosource in the eligibilty XML
+          #
+          # @see InfoSource
+          attr_accessor :info_source
+
+          # The inforeceiver in the eligibilty XML
+          #
+          # @see InfoReceiver
+          attr_accessor :info_receiver
+
+
+          def initialize(response)
+            response = response.to_hash.dig(:do_inquiry_response, :do_inquiry_result) || {}
+
+            self.success_code    = response[:success_code]
+            self.response_as_xml = response[:response_as_xml]
+            self.extra_processing_info = ExtraProcessingInfo.new(response[:extra_processing_info])
+          end
+
+          def response_as_xml=(eligibility_response_xml_as_string)
+            parser = Nori.new(convert_tags_to: lambda { |tag| tag.snakecase.to_sym })
+            self.eligibility_response_as_hash = parser.parse(eligibility_response_xml_as_string || '')[:eligibilityresponse] || {}
+
+            self.transaction_id = eligibility_response_as_hash.dig(:infosource, :transactionid)
+            self.payer_name     = eligibility_response_as_hash.dig(:infosource, :payername)
+            self.payer_id       = eligibility_response_as_hash.dig(:infosource, :payerid)
+
+            # TODO: I have not yet been able to find an example of multiple subscribers
+            # in a response from trizetto.  But, I think if there were multiple
+            # subscribers matching a queruy, the would come back as <subscriber>...</subscriber><subscriber>...</subscriber>
+            # which Nori will turn into an array (subscriber: [...]).
+
+            if subscriber_xml = eligibility_response_as_hash[:subscriber]
+              raise MultipleSubscribersError if subscriber_xml.is_a?(Array)
+              self.subscriber = Subscriber.new(subscriber_xml)
+            end
+
+            if dependent_xml = eligibility_response_as_hash[:dependent]
+              raise MultipleDependentsError if dependent_xml.is_a?(Array)
+              self.dependent = Dependent.new(dependent_xml)
+            end
+
+            if info_source_xml = eligibility_response_as_hash[:infosource]
+              self.info_source = InfoSource.new(info_source_xml)
+            end
+
+            if info_receiver_xml = eligibility_response_as_hash[:inforeceiver]
+              self.info_receiver = InfoReceiver.new(info_receiver_xml)
+            end
+          end
+          protected :response_as_xml=
+
+          # Did we successfully get back an eligibility response from the payer.
+          #
+          # This does not mean the patient has active coverage.
+          #
+          # @return Boolean
+          def success?
+            success_code == 'Success' && [transaction_id, payer_name, payer_id].none?(&:blank?)
+          end
+
+          # The dependent or the subscriber - the best guess at who is the patient
+          def patient
+            dependent || subscriber
+          end
+
+          # Was the eligibility check rejected.  Eligibility checks may be rejected
+          # because they have expired, they don't exist, the payer service is unable
+          # to response, or there were errors with the request handled at the
+          # payer level instead of through Trizetto.  There can be _multiple_ rejections
+          # on a single request
+          #
+          # @see #rejections
+          def rejected?
+            !rejections.empty?
+          end
+
+          # Rejections can appear in the subscriber, info source, info receiver,
+          # and possibly in the dependent.  Additionaly, there can be _multiple_
+          # rejections in any one of those.  This collects them all
+          def rejections
+            [subscriber, dependent, info_receiver, info_source].compact.map(&:rejections).flatten.compact
+          end
+
+          # Validation errors handled at Trizetto's level
+          #
+          # @return ExtraProcessingInfo
+          def errors
+            self.extra_processing_info
+          end
+
+          # Does the patient we asked about have active insurance coverage for
+          # this service type code?  Service type codes are strings and the
+          # most common is 30, general health benefits coverage.
+          #
+          # <b>Example</b>
+          #
+          #   response.active_coverage_for?("30")  #=> true
+          #
+          # <b>References</b>
+          #
+          # * {http://www.x12.org/codes/health-care-service-type-codes/ Service Type Code Reference<}
+          def active_coverage_for?(service_type_code)
+            !!(patient && patient.benefits.any? do |benefit|
+              benefit.active_coverage? && benefit.service_type_codes.include?(service_type_code.to_s)
+            end)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trizetto/api/eligibility/web_service/extra_processing_info.rb

@@ -0,0 +1,41 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # Validation failures from the DoInquiryRequest.
+        #
+        # <b>WSDL Reference</b>
+        #
+        #   <s:element minOccurs="0" maxOccurs="1" name="ExtraProcessingInfo" type="tns:ValidationFailureCollection" />
+        #
+        class ExtraProcessingInfo
+
+          # An array of strings, each a single validation failure
+          attr_accessor :messages
+
+          # An array of ValidationFailure, each indicating field that had errors
+          attr_accessor :validation_failures
+
+          def initialize(extra_processing_info)
+            self.messages = Array(extra_processing_info.dig(:all_messages, :string))
+
+            failures = extra_processing_info.dig(:failures,:validation_failure) || []
+            failures = [failures] if failures.is_a?(Hash)
+
+            self.validation_failures = failures.map do |failure|
+              ValidationFailure.new(failure)
+            end
+          end
+
+          def to_h
+            {
+              messages: messages,
+              validation_failures: validation_failures.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trizetto/api/eligibility/web_service/info_reciever.rb

@@ -0,0 +1,14 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+        #
+        # Information about the Receiver.  May include rejections
+        #
+        class InfoReceiver < Node
+          prepend Rejectable
+        end
+      end
+    end
+  end
+end

data/lib/trizetto/api/eligibility/web_service/info_source.rb

@@ -0,0 +1,14 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+        #
+        # Information about the Source.  May include rejections
+        #
+        class InfoSource < Node
+          prepend Rejectable
+        end
+      end
+    end
+  end
+end

data/lib/trizetto/api/eligibility/web_service/node.rb

@@ -0,0 +1,43 @@
+require 'ostruct'
+
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # Base class for parsed reponses in the eligibility response.
+        class Node < OpenStruct
+          def initialize(raw_hash = {})
+            required_keys = self.class.constants.include?(:REQUIRED_KEYS) ? self.class::REQUIRED_KEYS : {}
+            clean_hash = required_keys.merge(raw_hash)
+
+            cleanup_keys = self.class.constants.include?(:KEY_CLEANUP) ? self.class::KEY_CLEANUP : {}
+            cleanup_keys.each do |uglykey, friendly_key|
+              clean_hash[friendly_key] = clean_hash.delete(uglykey) if clean_hash.has_key?(uglykey)
+            end
+
+            # Convert prefixed keys "benefit_related_entity_id" to simple keys "id"
+            prefix_translations = self.class.constants.include?(:PREFIX_TRANSLATIONS) ? self.class::PREFIX_TRANSLATIONS : {}
+            prefix_translations.each do |key_prefix|
+              clean_hash.keys.each do |key|
+                if key.to_s =~ /^#{key_prefix}_(.*)$/
+                  clean_hash["#{$1}".to_sym] = clean_hash.delete(key)
+                end
+              end
+            end
+
+            super(clean_hash)
+
+            after_inititlize(clean_hash)
+          end
+
+          # Callback after the prased eligibility response has been cleaned up
+          def after_inititlize(hash)
+          end
+          protected :after_inititlize
+        end
+      end
+    end
+  end
+end
+

data/lib/trizetto/api/eligibility/web_service/patient.rb

@@ -0,0 +1,36 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # A Patient is either a Subscriber or Depedent.  This is the common
+        # attributes between the two
+        class Patient < Node
+
+          # @see PatientName
+          attr_accessor :name
+
+          # The benefits this patient has.
+          #
+          attr_accessor :benefits
+
+          KEY_CLEANUP = {
+            :patientid => :id
+          }
+
+          def initialize(raw_hash = {})
+            super(raw_hash)
+            self.name = PatientName.new(raw_hash[:patientname]) if raw_hash.has_key?(:patientname)
+
+            benefits_xml = raw_hash[:benefit] || []
+            benefits_xml = [benefits_xml] if benefits_xml.is_a?(Hash)
+
+            self.benefits = benefits_xml.map do |benefit_xml|
+              Benefit.new(benefit_xml)
+            end
+          end
+        end
+      end
+    end
+  end
+end