trizetto-api 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4fbff1ea29b8ff7be9a59a73684fbf34b4c4418
-  data.tar.gz: 6697e7baa4a73b991efb4462f880466ae5fbc858
+  metadata.gz: 60c7ed11ee2e04e48734c1e3b557c9e904d2e268
+  data.tar.gz: 3b35cbee1b0e2ffb45ae3e9533ec546983f4d130
 SHA512:
-  metadata.gz: eedcb3a711f90fdf8a1be47b85de37f4df7c4adcc55aba3ac3a387a362262f48da504bd7ad8144226789c8ed63afe155fff8cbd77af575a75ef953bb8e76807b
-  data.tar.gz: e9a45666b41c6cfd81f5b673f2aec1504021273a14db19b0e18cb3d682526c9899f18efe895b9062a2492b11d73bb08b2abd018fb98a89cf5a2c51a06a32682a
+  metadata.gz: 2471cf69c92ddac9b6b47d0d41c7dd8e020f7374418b9c08e2034907f783071ed052e45829c7fa3989c4ab5b6b32c1ea476d170de250868c2a7c995e602c4c91
+  data.tar.gz: 4888af1330a52c70b84535c44ae4c912866482109b5e853858390d1d156bf8236bcfd1ef3b4bc27ab5912a74d0c215daee47cd1ff644c8db253d3f24032f5df8

data/.travis.yml

@@ -1,5 +1,6 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.1
+  - 2.3.5
+  - 2.4.2
 before_install: gem install bundler -v 1.16.0

data/.yardopts

@@ -0,0 +1 @@
+--no-private -r README.md lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.2.1 (January 18, 2018) ##
+
+* Sets required minimum version for ruby to 2.3
+
+## 0.2.0 (January 18, 2018) ##
+
+* Make it simple to answer the question: does this person have insurance
+  coverage via the WebService Eligibility check.  The raw XML response is parsed
+  into plain old ruby objects.
+* Added tests (woo hoo)
+* Readme update with examples
+* Documented the WebService Eligibility check
+
 ## 0.1.2 (January 12, 2018) ##
 
 * Have the non-COR II Eligiblity check return an XML document.  YAY! We can

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trizetto-api (0.1.1)
+    trizetto-api (0.2.0)
       savon (~> 2.0)
       savon-multipart (~> 2.0)
 
@@ -12,6 +12,7 @@ GEM
       gyoku (>= 0.4.0)
       nokogiri
     builder (3.2.3)
+    byebug (9.1.0)
     diff-lcs (1.3)
     gyoku (1.3.1)
       builder (>= 2.1.2)
@@ -66,6 +67,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.16)
+  byebug (>= 9.0)
   rake (~> 10.0)
   rspec (~> 3.0)
   trizetto-api!

data/README.md

@@ -1,9 +1,13 @@
 # Trizetto::Api
 
-Ruby wrapper for Trizetto APIs
+[![Build Status](https://travis-ci.org/GoodMeasuresLLC/trizetto-api.svg?branch=master)](https://travis-ci.org/GoodMeasuresLLC/trizetto-api)
+
+Ruby wrapper for Trizetto APIs for Ruby 2.3 and above.
 
 ## Installation
 
+<b>Requires Ruby 2.3 or above</b>
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -18,12 +22,20 @@ Or install it yourself as:
 
     $ gem install trizetto-api
 
+
 ## Usage
 
 ### Use the Eligibility Web Service with an XML payload to check eligibility in realtime
 
 This uses name/value pairs in a request and returns an XML docunment as a response.
-You can force this API to return an X12 document if you like pain.
+
+To simply check if the patient is covered by a health plan
+
+```ruby
+GENERAL_HEALTH_PLAN_COVERAGE_CODE = "30"
+response = client.do_inquiry({...})
+response.active_coverage_for?(GENERAL_HEALTH_PLAN_COVERAGE_CODE)  #=> true | false
+```
 
 ```ruby
 require 'trizetto/api'
@@ -33,12 +45,13 @@ Trizetto::Api.configure do |config|
   config.password = 'Super Top Secret'
 end
 
-
-client = Trizetto::Api::Eligibility::WebService.new({
-  pretty_print_xml: true,
-  log: true,
-  log_level: :debug,
+client = Trizetto::Api::Eligibility::WebService::Client.new({
+  # You probably don't want logging enable unless you are being very careful to protect PHI in logs
+  # pretty_print_xml: true,
+  # log: true,
+  # log_level: :debug,
 })
+
 response = client.do_inquiry({
   'ProviderLastName': 'BLUE CROSS BLUE SHIELD OF MASSACHUSETTS',
   'NPI':              'YOUR NPI HERE',
@@ -48,13 +61,44 @@ response = client.do_inquiry({
   'GediPayerId':      'N4222',
 })
 
-puts response.to_hash[:do_inquiry_response][:do_inquiry_result][:success_code]
+# Were there validation errors with the request?
+response.success?                                          # => false
+response.success_code                                      # => "ValidationFailure"
+response.errors.messages                                   # => ["Please enter InsuranceNum."]response.errors.validation_failures.first.affected_fields  # => ["InsuranceNum"]
+response.errors.validation_failures.first.message          # => "Please enter InsuranceNum."
+
+
+# Did we successfully get back an eligibility response from the payer.
+response.success?                   # => true
+response.success_code               # => "Success"
+response.transaction_id             # => "c6eb40c5584f0496be3f3a48d0ddfd"
+response.payer_name                 # => "BLUE CROSS BLUE SHIELD OF MASSACHUSETTS"
+response.active_coverage_for?("30") # => true
+
+# Was the response rejected? We got back an eligibility response, but probably the patient wasn't found
+response.success?                           # => true
+response.success_code                       # => "Success"
+response.active_coverage_for?("30")         # => false
+response.rejected?                          # => true
+response.rejectsions.count                  # => 1
+response.rejectsions.first.reason           # => "Patient Birth Date Does Not Match That for the Patient on the Database"
+response.rejectsions.first.follow_up_action # => "Please Correct and Resubmit"
+
+# What active insurance coverages of service_type_code=30 does this patient have?
+coverages = response.patient.benefits.select {|benefit| benefit.active_coverage? && benefit.service_type_codes.include?("30")}
+coverages.count                # => 2
+coverages.first.insurance_type # => "Preferred Provider Organization (PPO)"
+coverages.last.insurance_type  # => "Medicare Part A"
+coverages.first.messages       # => nil
+coverages.last.messages        # => ["BCBSMA IS PRIME"]
+
+# Find all the benefit information for service_type_code=30
+benefits = response.patient.benefits.select {|benefit| benefit.service_type_codes.include?("30")}
+
+benefits.map(&:info).uniq # => ["Active Coverage", "Deductible", "Coverage Basis", "Out of Pocket (Stop Loss)", "Services Restricted to Following Provider"]
 
-source = response.to_hash[:do_inquiry_response][:do_inquiry_result][:response_as_xml]
-puts Nokogiri::XML(source).to_xml
 ```
 
-
 ### Use the CORE2 API with an X12 payload to check eligibility in realtime
 
 This returns an X12/271 response.  You will need to understand how to build

data/lib/trizetto/api/eligibility/core2.rb

@@ -11,10 +11,9 @@ module Trizetto
       #
       # As of right now, you have to generate the correct X12/271 payload.
       #
-      # See Also
-      #
-      # - Eligibility 270/271 Companion Guide: https://mytools.gatewayedi.com/webcontent/Eligibility_Companion_Guide.pdf
+      # <b<References</b>
       #
+      # - {https://mytools.gatewayedi.com/webcontent/Eligibility_Companion_Guide.pdf Eligibility 270/271 Companion Guide}
       class Core2
         def initialize(options={})
           @client = Savon.client({
@@ -55,20 +54,22 @@ module Trizetto
           }.merge(options))
         end
 
-
-        # TODO: Understand the X12 format and allow options to be passed in, then generate the X12 message
+        # Performs an eligiblity check using the CORE II Eligibility API via X12/270
+        #
+        # <b>TODO</b>
+        # - Understand the X12 format and allow options to be passed in, then generate the X12 message
         #
         def check_eligibility(options = {})
-        @client.call(:real_time_transaction, message: {
-          'PayloadType': 'X12_270_Request_005010X279A1',
-          'ProcessingMode': 'RealTime',
-          'PayloadID': SecureRandom.uuid,
-          'TimeStamp': Time.now.utc.xmlschema,
-          'SenderID': Trizetto::Api.configuration.username,
-          'ReceiverID': 'GATEWAY EDI',
-          'CORERuleVersion': '2.2.0',
-          'Payload': options[:payload]
-        });
+          @client.call(:real_time_transaction, message: {
+            'PayloadType': 'X12_270_Request_005010X279A1',
+            'ProcessingMode': 'RealTime',
+            'PayloadID': SecureRandom.uuid,
+            'TimeStamp': Time.now.utc.xmlschema,
+            'SenderID': Trizetto::Api.configuration.username,
+            'ReceiverID': 'GATEWAY EDI',
+            'CORERuleVersion': '2.2.0',
+            'Payload': options[:payload]
+          });
         end
       end
     end

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

@@ -1,74 +1,136 @@
+require 'ostruct'
+
+require File.dirname(__FILE__) + "/web_service/rejectable.rb"
+require File.dirname(__FILE__) + "/web_service/node.rb"
+require File.dirname(__FILE__) + "/web_service/patient.rb"
+
+Dir[File.dirname(__FILE__) + '/web_service/*.rb'].each {|file| require file }
+
 module Trizetto
   module Api
     module Eligibility
+      module WebService
 
-      # Ruby Wrapper for the Eligibility Web Service
-      #
-      # Performs a real time eligibility check using the non-CORE II Web Service
-      #
-      # The webservice provides 3 eligibility checks:
-      #
-      # - +DoInquiry+
-      # - +DoInquiryByX12Data+
-      # - +DoInquiryByX12DataWith271Response+
-      #
-      # This API, currently, only uses the +DoInquiry+ check.  For X12 requests
-      # the CORE II client is recommended instead.
-      #
-      # See Also:
-      #
-      # - Service Description: https://services.gatewayedi.com/eligibility/service.asmx
-      # - WSDL: https://services.gatewayedi.com/eligibility/service.asmx?WSDL
-      # - Realtime Eligibiliy Webservice Companion Guide: https://mytools.gatewayedi.com/Help/documents/Eligibility/Realtime%20Eligibility%20Webservice%20Companion%20Guide.pdf
-      # - Realtime Eligibiliy Webservice Vendor Toolkit: https://mytools.gatewayedi.com/Help/documents/Eligibility/Realtime%20Eligibility%20Webservice%20Vendor%20Toolkit.pdf
-      # - Eligibility Companion Guide by Payer: https://mytools.gatewayedi.com/help/documents/Eligibility/Payer%20Specific%20Required%20Data%20Elements-2010.pdf
-      class WebService < Trizetto::Api::WebService
-        def initialize(options={})
-          super(options.merge({
-            wsdl:        File.join( File.dirname(__FILE__), 'web_service.wsdl' ),
-            endpoint:    Trizetto::Api.configuration.eligibiltiy_webservice_endpoint,
-          }))
-        end
+        # Raised when the response from Trizetto includes multiple subscribers
+        #
+        # If raised, please scrub the response for PHI and create an issue in
+        # github and include the scrubbed (NO PHI!!) reponse XML.
+        class MultipleSubscribersError < StandardError; end
 
-        # Required Field:
-        #   +GediPayerId+        - The Gateway EDI specific payer identifier
-        #   +ProviderLastName+   - Provider Last Name/Organization Name
-        #   +NPI+                - National Provider Identifier
+        # Raised when the response from Trizetto includes multiple dependents
         #
-        # Situational Fields:
+        # If raised, please scrub the response for PHI and create an issue in
+        # github and include the scrubbed (NO PHI!!) reponse XML.
+        class MultipleDependentsError < StandardError; end
+
+
+        # Ruby Wrapper for the Eligibility Web Service
         #
-        #   +ProviderFirstName+  - Provider First Name
-        #   +InsuredFirstName+   - Subscriber First Name
-        #   +InsuredLastName+    - Subscriber Last Name
-        #   +InsuranceNum+       - Subscriber Id
-        #   +InsuredDob+         - Subscriber DOB
-        #   +InsuredGender+      - Subscriber Gender
-        #   +DependentFirstName+ - Dependent First Name
-        #   +DependentLastName+  - Dependent Last Name
-        #   +DependentDob+       - Dependent DOB
-        #   +DependentGender+    - Dependent Gender
+        # Performs a real time eligibility check using the non-CORE II Web Service
         #
-        # Note: Some payers require additional information than those listed above. Please refer to the
-        # companion guide for the additional parameters required by few payers. A valid inquiry submitted
-        # to those payers must also account for the additional payer specific parameters. “InsuranceNum,” in
-        # particular, is not a required field for all transactions, but is required by almost all payers.
+        # The webservice provides 3 eligibility checks:
         #
-        # See Also:
+        # * <tt>DoInquiry</tt>
+        # * <tt>DoInquiryByX12Data</tt>
+        # * <tt>DoInquiryByX12DataWith271Response</tt>
         #
-        # - Service Description: https://services.gatewayedi.com/eligibility/service.asmx?op=DoInquiry
-        def do_inquiry(parameters={})
-          @client.call(:do_inquiry, message: { 'Inquiry': {
-            'ResponseDataType': 'Xml',
-            'Parameters': {
-            'MyNameValue': parameters.map do |name, value|
-                {'Name': name, 'Value': value}
-              end
-            }}})
-        end
+        # This API, currently, only uses the +DoInquiry+ check.  For X12 requests
+        # the CORE II client is recommended instead.
+        #
+        # <b>Example</b>
+        #
+        #   client = Trizetto::Api::Eligibility::WebService::Client.new
+        #
+        #   response = client.do_inquiry({
+        #     'ProviderLastName': 'YOUR COMPANY NAME HERE',
+        #     'NPI':              'YOUR NPI HERE',
+        #     'InsuredFirstName': 'Mickey',
+        #     'InsuredLastName':  'Mouse',
+        #     'InsuredDob':       '19281118',
+        #     'GediPayerId':      'N4222',
+        #   })
+        #
+        # @see DoInquiryResponse
+        #
+        # *References*
+        # * {https://services.gatewayedi.com/eligibility/service.asmx ServiceDescription}
+        # * {https://services.gatewayedi.com/eligibility/service.asmx?WSDL WSDL}
+        # * {https://mytools.gatewayedi.com/Help/documents/Eligibility/Realtime%20Eligibility%20Webservice%20Companion%20Guide.pdf Realtime Eligibiliy Webservice Companion Guide}
+        # * {https://mytools.gatewayedi.com/Help/documents/Eligibility/Realtime%20Eligibility%20Webservice%20Vendor%20Toolkit.pdf Realtime Eligibiliy Webservice Vendor Toolkit}
+        # * {https://mytools.gatewayedi.com/help/documents/Eligibility/Payer%20Specific%20Required%20Data%20Elements-2010.pdf Eligibility Companion Guide by Payer}
+        class Client < Trizetto::Api::WebService
 
-        alias_method :check_eligibility, :do_inquiry
+          def initialize(options={})
+            super(
+              options.merge(
+                {
+                  wsdl:        File.join( File.dirname(__FILE__), 'web_service.wsdl' ),
+                  endpoint:    Trizetto::Api.configuration.eligibiltiy_webservice_endpoint,
+                }
+            ))
+          end
+
+          # Performs an eligibility check using the trizetto eligibility SOAP API
+          #
+          # In this request, your company is the Provider, you are providing
+          # services to an individual.  For the +ProviderLastName+, you should use
+          # you company's name.  For the +NPI+, you should use your company's
+          # National Provider Identifier.
+          #
+          # The +GediPayerId+ is the insurance company.  You want them to pay for the
+          # service you have or will provide.  You will need to get these values
+          # from Trizetto.
+          #
+          # Required and optional fields will depend on the Payer being checked.
+          # Some payers require additional information than those listed below.
+          # Refer to the companion guide for the required additional parameters.
+          # A valid inquiry submitted to those payers must also account for the
+          # additional payer specific parameters. +InsuranceNum+ in particular,
+          # is not a required field for all transactions, but is required by
+          # almost all payers.
+          #
+          # <b>Always Required Fields</b>
+          #
+          # * <tt>GediPayerId</tt>      - The Gateway EDI specific payer identifier
+          # * <tt>ProviderLastName</tt> - Provider Last Name/Organization Name.
+          # * <tt>NPI</tt>              - National Provider Identifier
+          #
+          # <b>Situational Fields</b>
+          #
+          # * <tt>ProviderFirstName</tt>  - Provider First Name
+          # * <tt>InsuredFirstName</tt>   - Subscriber First Name
+          # * <tt>InsuredLastName</tt>    - Subscriber Last Name
+          # * <tt>InsuranceNum</tt>       - Subscriber Id
+          # * <tt>InsuredDob</tt>         - Subscriber DOB
+          # * <tt>InsuredGender</tt>      - Subscriber Gender
+          # * <tt>DependentFirstName</tt> - Dependent First Name
+          # * <tt>DependentLastName</tt>  - Dependent Last Name
+          # * <tt>DependentDob</tt>       - Dependent DOB
+          # * <tt>DependentGender</tt>    - Dependent Gender
+          # * <tt>GroupNumber</tt>        -
+          # * <tt>ServiceTypeCode</tt>    - What type of provider service.  30 is Health Plan Benefit Coverage, "General healthcare benefits for the member's policy or contract"
+          #
+          # <b>References</b>
+          # * {https://services.gatewayedi.com/eligibility/service.asmx?op=DoInquiry Service Description}
+          # * {http://www.x12.org/codes/health-care-service-type-codes/ Service Type Codes}
+          #
+          # @return DoInquiryResponse
+          def do_inquiry(parameters={})
+            DoInquiryResponse.new(
+              @client.call( :do_inquiry, message: { 'Inquiry': {
+                'ResponseDataType': 'Xml',
+                'Parameters': {
+                  'MyNameValue': parameters.map { |name, value|
+                     {'Name': name, 'Value': value}
+                   }
+                }
+              }})
+            )
+          end
+
+          alias_method :check_eligibility, :do_inquiry
+        end
       end
     end
   end
 end
-

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

@@ -0,0 +1,117 @@
+module Trizetto
+  module Api
+    module Eligibility
+      module WebService
+
+        # A Benefit provided by the insurance.
+        #
+        # <b>Example XML</b>
+        #
+        #   <benefit>
+        #     <info>Out of Pocket (Stop Loss)</info>
+        #     <coveragelevel>Family</coveragelevel>
+        #     <servicetype>Health Benefit Plan Coverage</servicetype>
+        #     <servicetypecode>30</servicetypecode>
+        #     <time_period_qualifier>Remaining</time_period_qualifier>
+        #     <benefitamount>13097.6</benefitamount>
+        #     <plannetworkindicator>In Plan-Network</plannetworkindicator>
+        #     <message>BUT NO MORE THAN INDIVIDUAL AMOUNT PER MEMBER (ACCUMULATES WITH OUT-OF-NETWORK AMOUNTS)</message>
+        #     <message>CALCULATION INCLUDES DEDUCTIBLE, COPAYMENTS AND COINSURANCE FOR MEDICAL AND PRESCRIPTION DRUG BENEFITS.</message>
+        #   </benefit>
+        #
+        # <b>Example</b>
+        #
+        #   benefit.info     # => "Out of Pocket (Stop Loss)"
+        #   benefit.messages # => ["BUT NO MORE THAN...", "CALCULATION INCLUDES ...."]
+        #
+        # <b>Example XML</b>
+        #
+        #   <benefit>
+        #     <info>Active Coverage</info>
+        #     <coveragelevel>Family</coveragelevel>
+        #     <servicetype>Health Benefit Plan Coverage</servicetype>
+        #     <servicetypecode>30</servicetypecode>
+        #     <insurancetype>Preferred Provider Organization (PPO)</insurancetype>
+        #     <insurancetypecode>PR</insurancetypecode>
+        #     <plancoveragedescription>PPO - PREFERRED BLUE PPO SAVER</plancoveragedescription>
+        #   </benefit>
+        #
+        # <b>Example</b>
+        #
+        #   benefit.info                # => "Active Coverage<"
+        #   benefit.service_type_codes  # => ["30"]
+        #
+        class Benefit < Node
+          REQUIRED_KEYS =
+          {
+            info:               '',
+            service_type_codes: [],
+            messages:           [],
+          }
+
+          KEY_CLEANUP =
+          {
+            benefitamount:           :benefit_amount,
+            benefitentity:           :entity,
+            coveragelevel:           :coverage_level,
+            datequalifier:           :date_qualifier,
+            insurancetype:           :insurance_type,
+            insurancetypecode:       :insurance_type_code,
+            plancoveragedescription: :plan_coverage_description,
+            plannetworkindicator:    :plan_network_indicator,
+            quantityqualifier:       :quantity_qualifier,
+            servicetype:             :service_type,
+            servicetypecode:         :service_type_code,
+          }
+
+          def initialize(raw_hash = {})
+            clean_hash = raw_hash.dup
+
+            # Convert message, which is either a single or multiple entry int
+            # the SOAP, which then gets turned into a string or an array by
+            # Nori into a messages aaray
+            clean_hash[:messages] = Array(clean_hash.delete(:message)) if clean_hash.has_key?(:message)
+
+            # Service type codes indicate the type of benefit.
+            # The magic decoder for ID => human meaning is here: http://www.x12.org/codes/health-care-service-type-codes/
+            # Multiple service type codes with the same benfit are combined with a ^
+            # so we turn a single servicetypecode entry into an array of service types
+            clean_hash[:service_type_codes] = (clean_hash.delete(:servicetypecode) || '').split("^")
+
+            super(clean_hash)
+
+            if self.entity.is_a?(Hash)
+              self.entity = BenefitEntity.new(self.entity)
+            end
+          end
+
+          # Is this active insurance coverage?
+          def active_coverage?
+            info == "Active Coverage"
+          end
+
+          def inactive?
+            info == "Inactive"
+          end
+
+          def co_insurance?
+            info == "Co-Insurance"
+          end
+
+          def limitation?
+            info == "Limitations"
+          end
+
+          def non_covered?
+            info == "Non-Covered"
+          end
+
+          def primary_care_provider?
+            info == "Primary Care Provider"
+          end
+        end
+      end
+    end
+  end
+end
+