dzero 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: '0889c270bd2f9cfe9505d504101d12addeb55162'
+  data.tar.gz: f96d26194929d27ffcfd78366337c9e47c1bf762
+SHA512:
+  metadata.gz: 1d53f684c5ea68a1b1fdc2024d2dec97eeb1d2f12d97cff2eb05289a9f75af3321c04f6420b813233fc6cc56415842279fd87deca179395d8dd66bbb7eb67c43
+  data.tar.gz: ad88b00ad20a467bedd3b40270b2c19bfee2bab6cc828f4f4df6f0ba93a21a63d67194d4ad31cf457706c36b6c34b363acc04a35ea3e0c5b95d0e4a92b16af91

data/README.md

@@ -0,0 +1,265 @@
+# DZero
+
+DZero is a robust and easy-to-use NCPDP Telecommunications Standard D.0 Message **parser** and **serializer**.
+
+🍊Battle Tested at [Instacart](https://www.instacart.com/opensource)
+
+## Installation
+
+Add this to your gemfile:
+```
+gem 'dzero'
+```
+
+And then run bundle install.
+
+## Features
+
+- ✅ Complete field mapping for all **26** D.0 Segment types.
+  - This means you can access field values by a simple name instead of it's 2-character identifier. (ex: `claim_segment[:fill_number]` instead of `claim_segment['D3']`)
+- ✅ Parse D.0 Requests or Responses with ease.
+  - ex: `DZero::Transmissions::Request.parse(your_raw_string)`
+- ✅ Build D.0 Requests or Responses with ease.
+  - ex: `DZero::Transmissions::Request.new(...)` (see [Building](#Building) below)
+- ✅ Supports multiple transaction groups
+  - ex: `request.transaction_groups[2].claim_segment`
+- ✅ Serialize a D.0 message to JSON
+  - ex: `request.to_json`
+
+## Usage
+
+### Parsing and Manipulating
+
+#### Parsing
+
+```ruby
+require 'dzero'
+
+request = DZero::Transmissions::Request.parse(raw_message_string)
+```
+
+The above snippet will return a new instance of `DZero::Transmissions::Request`.
+
+#### Reading the header
+
+```ruby
+pp request.header
+# =>
+# {:bin_number=>"999999",
+#  :version=>"D0",
+#  :transaction_code=>"B1",
+#  :processor_control_number=>"",
+#  :transaction_count=>"1",
+#  :service_provider_id_qualifier=>"01",
+#  :service_provider_id=>"1111111111",
+#  :date_of_service=>"20181106",
+#  :software=>""}
+```
+
+#### Reading a single segment
+
+```ruby
+request.transmission_group.patient_segment
+# => #<DZero::Segments::Patient>
+
+request.transmission_group.insurance_segment
+# => #<DZero::Segments::Insurance>
+
+request.transaction_groups.first.claim_segment
+# => #<DZero::Segments::Claim>
+
+request.transaction_groups[2].claim_segment
+# => #<DZero::Segments::Claim>
+```
+
+#### Reading a field in a segment
+
+Fields of a segment can be accessed via the `[]` method, which takes either a symbol or a string.
+
+```ruby
+segment = request.transaction_groups.first.claim_segment
+# => #<DZero::Segments::Claim>
+segment[:segment_identification]
+# => "07"
+segment["AM"]
+# => "07"
+segment[:quantity_dispensed]
+# => "2000"
+segment["E7"]
+# => "2000"
+```
+
+#### Modifying a field in a segment
+
+Fields of a segment can be accessed via the `[]` method, which takes either a symbol or a string. If a segment or field does not yet exist when it is attempted to be accessed, it will be created and added to the message.
+
+```ruby
+segment = request.transaction_groups.first.claim_segment
+segment[:quantity_dispensed]
+# => "2000"
+segment[:quantity_dispensed] = "9990"
+# => "9990"
+segment["E7"]
+# => "9990"
+segment["E7"] = "5555"
+# => "5555"
+segment[:quantity_dispensed]
+# => "5555"
+```
+
+#### Serializing to json
+
+`Request`, `Response`, `TransmissionGroup`, `TransactionGroup`, and `Segment` all have **`to_json`** methods.
+
+```ruby
+request.to_json
+```
+
+**`to_json`** takes two options:
+- **`:readable`** - if this is true, symbols will be used for the fields of a segment, instead of the field identifiers.
+- **`:key_group_by_segment_sym`** - if this is true, groups will be objects instead of arrays of objects. A group object will be keyed by the segment identifiers it contains.
+
+### Building
+
+For messages with a single transaction group, you can pass segments in with the **`segments`** argument. DZero will automatically filter the segments into the correct locations (either the **`transmission_group`** or the first **`transaction_group`**)
+
+```ruby
+require 'dzero'
+
+request = DZero::Transmissions::Request.new({
+  header: {
+    :bin_number=>"999999",
+    :version=>"D0",
+    :transaction_code=>"B1",
+    :processor_control_number=>"",
+    :transaction_count=>"1",
+    :service_provider_id_qualifier=>"01",
+    :service_provider_id=>"1111111111",
+    :date_of_service=>"20181106",
+    :software=>""
+  },
+  segments: [
+    DZero::Segments::Patient.build({
+      patient_first_name: 'AUSTIN',
+      patient_last_name: 'PIVARNIK',
+      patient_phone_number: '5555555555',
+    })
+  ]
+})
+```
+
+For more control over the structure of the message, you can manually construct the `transmission_group` and the `transaction_group`.
+
+```ruby
+require 'dzero'
+
+response = DZero::Transmissions::Response.new(
+  header: {
+    :bin_number=>"999999",
+    :version=>"D0",
+    :transaction_code=>"B1",
+    :processor_control_number=>"",
+    :transaction_count=>"1",
+    :service_provider_id_qualifier=>"01",
+    :service_provider_id=>"1111111111",
+    :date_of_service=>"20181106",
+    :software=>""
+  },
+  transmission_group: DZero::Transmissions::Groups::TransmissionGroup.new(
+    segments: [
+      DZero::Segments::ResponseMessage.build({
+        message: "TEST MESSAGE"
+      })
+    ]
+  ),
+  transaction_groups: [
+    DZero::Transmissions::Groups::TransactionGroup.new(
+      segments: [
+        DZero::Segments::ResponseStatus.build({
+          response_status: "C"
+        })
+      ]
+    ),
+    DZero::Transmissions::Groups::TransactionGroup.new(
+      segments: [
+        DZero::Segments::ResponseStatus.build({
+          response_status: "R"
+        })
+      ]
+    )
+  ]
+)
+```
+
+### Stringifying a message
+
+To render an instance of `Request` or `Response` into a D.0 string, simply call `#to_s` on the instance.
+
+```ruby
+request.to_s
+# => "999999D0B1          1011111111111     20181106          \u001E\u001CAM01\u001CCAAUSTIN\u001CCBPIVARNIK\u001CCQ5555555555"
+```
+
+### Serializing a message to JSON
+
+```rb
+request.to_json(readable: true, key_group_by_segment_sym: true)
+# => {
+#   "header": {
+#     "bin_number": "999999",
+#     "version": "D0",
+#     "transaction_code": "B1",
+#     "processor_control_number": "",
+#     "transaction_count": "1",
+#     "service_provider_id_qualifier": "01",
+#     "service_provider_id": "9999999999",
+#     "date_of_service": "11282018",
+#     "software": ""
+#   },
+#   "transmission_group": {
+#     "patient": {
+#       "segment_identification": "01",
+#       "patient_first_name": "AUSTIN",
+#       "patient_last_name": "PIVARNIK",
+#       "patient_street_address": "50 BEALE ST",
+#       "patient_city": "SAN FRANCISCO",
+#       "patient_state_or_province": "CA",
+#       "patient_zip_postal_code": "94105",
+#       "patient_phone_number": "5555555555"
+#     }
+#   },
+#   "transaction_groups": [
+#     {
+#       "claim": {
+#         "segment_identification": "07",
+#         "prescription_reference_number_qualifier": "1",
+#         "prescription_reference_number": "9999999999",
+#         "product_service_id_qualifier": "03",
+#         "product_service_id": "99999999999",
+#         "quantity_dispensed": "2000",
+#         "fill_number": "0",
+#         "days_supply": "1",
+#         "compound_code": "1",
+#         "dispense_as_written_product_selection_code": "0",
+#         "date_prescription_written": "20181025",
+#         "number_of_refills_authorized": "99",
+#         "prescription_origin_code": "1",
+#         "unit_of_measure": "EA",
+#         "level_of_service": "0",
+#         "patient_assignment_indicator": "Y",
+#         "pharmacy_service_type": "1"
+#       },
+#       "pricing": {
+#         "segment_identification": "11",
+#         "ingredient_cost_submitted": "A",
+#         "dispensing_fee_submitted": "{",
+#         "patient_paid_amount_submitted": "{",
+#         "percentage_sales_tax_rate_submitted": "1750{",
+#         "usual_and_customary_charge": "A",
+#         "gross_amount_due": "A",
+#         "basis_of_cost_determination": "01"
+#       }
+#     }
+#   ]
+# }
+```

data/lib/dzero/segments/01_patient.rb

@@ -0,0 +1,27 @@
+module DZero::Segments
+  class Patient < Base
+    Base.register_segment(self, identifier: '01')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'CX' => :patient_id_qualifier,
+        'CY' => :patient_id,
+        'C4' => :date_of_birth,
+        'C5' => :patient_gender_code,
+        'CA' => :patient_first_name,
+        'CB' => :patient_last_name,
+        'CM' => :patient_street_address,
+        'CN' => :patient_city,
+        'CO' => :patient_state_or_province,
+        'CP' => :patient_zip_postal_code,
+        'CQ' => :patient_phone_number,
+        'C7' => :place_of_service,
+        'CZ' => :employer_id,
+        '1C' => :smoker_non_smoker_code,
+        '2C' => :pregnancy_indicator,
+        'HN' => :patient_email_address,
+        '4X' => :patient_residence,
+      })
+    end
+  end
+end

data/lib/dzero/segments/02_pharmacy_provider.rb

@@ -0,0 +1,12 @@
+module DZero::Segments
+  class PharmacyProvider < Base
+    Base.register_segment(self, identifier: '02')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'EY' => :provider_id_qualifier,
+        'E9' => :provider_id,
+      })
+    end
+  end
+end

data/lib/dzero/segments/03_prescriber.rb

@@ -0,0 +1,22 @@
+module DZero::Segments
+  class Prescriber < Base
+    Base.register_segment(self, identifier: '03')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'EZ' => :prescriber_id_qualifier,
+        'DB' => :prescriber_id,
+        'DR' => :prescriber_last_name,
+        'PM' => :prescriber_phone_number,
+        '2E' => :primary_care_provider_id_qualifier,
+        'DL' => :primary_care_provider_id,
+        '4E' => :primary_care_provider_last_name,
+        '2J' => :prescriber_first_name,
+        '2K' => :prescriber_street_address,
+        '2M' => :prescriber_city_address,
+        '2N' => :prescriber_state_province_address,
+        '2P' => :prescriber_zip_postal_zone,
+      })
+    end
+  end
+end

data/lib/dzero/segments/04_insurance.rb

@@ -0,0 +1,29 @@
+module DZero::Segments
+  class Insurance < Base
+    Base.register_segment(self, identifier: '04')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'C2' => :cardholder_id,
+        'CC' => :cardholder_first_name,
+        'CD' => :cardholder_last_name,
+        'CE' => :home_plan,
+        'FO' => :plan_id,
+        'C9' => :eligibility_clarification_code,
+        'C1' => :group_id,
+        'C3' => :person_code,
+        'C6' => :patient_relationship_code,
+        'MG' => :other_payer_bin_number,
+        'MH' => :other_payer_processor_control_number,
+        'NU' => :other_payer_cardholder_id,
+        'MJ' => :other_payer_group_id,
+        '2A' => :medigap_id,
+        '2B' => :medicaid_indicator,
+        '2D' => :provider_accept_assignment_indicator,
+        'G2' => :cms_part_d_defined_qualified_facility,
+        'N5' => :medicaid_id_number,
+        'N6' => :medicaid_agency_number,
+      })
+    end
+  end
+end

data/lib/dzero/segments/05_coord_of_benefits.rb

@@ -0,0 +1,27 @@
+module DZero::Segments
+  class CoordOfBenefits < Base
+    Base.register_segment(self, identifier: '05')
+
+    def self.field_id_to_symbol
+      super.merge({
+        '4C' => :coordination_of_benefits_other_payments_count,
+        '5C' => :other_payer_coverage_type,
+        '6C' => :other_payer_id_qualifier,
+        '7C' => :other_payer_id,
+        'E8' => :other_payer_date,
+        'A7' => :internal_control_number,
+        'HB' => :other_payer_amount_paid_count,
+        'HC' => :other_payer_amount_paid_qualifier,
+        'DV' => :other_payer_amount_paid,
+        '5E' => :other_payer_reject_count,
+        '6E' => :other_payer_reject_code,
+        'NR' => :other_payer_patient_responsibility_amount_count,
+        'NP' => :other_payer_patient_responsibility_amount_qualifier,
+        'NQ' => :other_payer_patient_responsibility_amount,
+        'MU' => :benefit_stage_count,
+        'MV' => :benefit_stage_qualifier,
+        'MW' => :benefit_stage_amount,
+      })
+    end
+  end
+end

data/lib/dzero/segments/06_workers_comp.rb

@@ -0,0 +1,30 @@
+module DZero::Segments
+  class WorkersComp < Base
+    Base.register_segment(self, identifier: '06')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'DY' => :date_of_injury,
+        'CF' => :employer_name,
+        'CG' => :employer_street_address,
+        'CH' => :employer_city_address,
+        'CI' => :employer_state_province_address,
+        'CJ' => :employer_zip_postal_code,
+        'CK' => :employer_phone_number,
+        'CL' => :employer_contact_name,
+        'CR' => :carrier_id,
+        'DZ' => :claim_reference_id,
+        'TR' => :billing_entity_type_indicator,
+        'TS' => :pay_to_qualifier,
+        'TT' => :pay_to_id,
+        'TU' => :pay_to_name,
+        'TV' => :pay_to_street_address,
+        'TW' => :pay_to_city_address,
+        'TX' => :pay_to_state_province_address,
+        'TY' => :pay_to_zip_postal_zone,
+        'TZ' => :generic_equivalent_product_id_qualifier,
+        'UA' => :generic_equivalent_product_id,
+      })
+    end
+  end
+end

data/lib/dzero/segments/07_claim.rb

@@ -0,0 +1,52 @@
+module DZero::Segments
+  class Claim < Base
+    Base.register_segment(self, identifier: '07')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'EM' => :prescription_reference_number_qualifier,
+        'D2' => :prescription_reference_number,
+        'E1' => :product_service_id_qualifier,
+        'D7' => :product_service_id,
+        'EN' => :associated_prescription_reference_number,
+        'EP' => :associated_prescription_date,
+        'SE' => :procedure_modifier_code_count,
+        'ER' => :procedure_modifier_code,
+        'E7' => :quantity_dispensed,
+        'D3' => :fill_number,
+        'D5' => :days_supply,
+        'D6' => :compound_code,
+        'D8' => :dispense_as_written_product_selection_code,
+        'DE' => :date_prescription_written,
+        'DF' => :number_of_refills_authorized,
+        'DJ' => :prescription_origin_code,
+        'NX' => :submission_clarification_code_count,
+        'DK' => :submission_clarification_code,
+        'ET' => :quantity_prescribed,
+        'C8' => :other_coverage_code,
+        'DT' => :special_packaging_indicator,
+        'EJ' => :originally_prescribed_id_qualifier,
+        'EA' => :originally_prescribed_code,
+        'EB' => :originally_prescribed_quantity,
+        'CW' => :alternate_id,
+        'EK' => :scheduled_prescription_id_number,
+        '28' => :unit_of_measure,
+        'DI' => :level_of_service,
+        'EU' => :prior_authorization_type_code,
+        'EV' => :prior_authorization_number_submitted,
+        'EW' => :intermediary_authorization_type_id,
+        'EX' => :intermediary_authorization_id,
+        'HD' => :dispensing_status,
+        'HF' => :quantity_intended_to_be_dispensed,
+        'HG' => :days_supply_intended_to_be_dispensed,
+        'NV' => :delay_reason_code,
+        'K5' => :transaction_reference_number,
+        'MT' => :patient_assignment_indicator,
+        'E2' => :route_of_administration,
+        'G1' => :compound_type,
+        'N4' => :medicade_icn,
+        'U7' => :pharmacy_service_type,
+      })
+    end
+  end
+end

data/lib/dzero/segments/08_dur_pps.rb

@@ -0,0 +1,17 @@
+module DZero::Segments
+  class DurPps < Base
+    Base.register_segment(self, identifier: '08')
+
+    def self.field_id_to_symbol
+      super.merge({
+        '7E' => :dur_pps_code_counter,
+        'E4' => :reason_for_service_code,
+        'E5' => :professional_service_code,
+        'E6' => :result_of_service_code,
+        '8E' => :dur_pps_level_of_effort,
+        'J9' => :dur_co_agent_id_qualifier,
+        'H6' => :dur_co_agent_id,
+      })
+    end
+  end
+end

data/lib/dzero/segments/09_coupon.rb

@@ -0,0 +1,13 @@
+module DZero::Segments
+  class Coupon < Base
+    Base.register_segment(self, identifier: '09')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'KE' => :coupon_type,
+        'ME' => :coupon_number,
+        'NE' => :coupon_value_amount,
+      })
+    end
+  end
+end

data/lib/dzero/segments/10_compound.rb

@@ -0,0 +1,20 @@
+module DZero::Segments
+  class Compound < Base
+    Base.register_segment(self, identifier: '10')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'EF' => :compound_dosage_form_description_code,
+        'EG' => :compound_dispensing_unit_form_indicator,
+        'EC' => :compound_ingredient_component_count,
+        'RE' => :compound_product_id_qualifier,
+        'TE' => :compound_product_id,
+        'ED' => :compound_ingredient_quantity,
+        'EE' => :compound_ingredient_drug_cost,
+        'UE' => :compound_ingredient_basis_of_cost_determination,
+        '2G' => :compound_ingredient_modifier_code_count,
+        '2H' => :compound_ingredient_modifier_code,
+      })
+    end
+  end
+end

data/lib/dzero/segments/11_pricing.rb

@@ -0,0 +1,26 @@
+module DZero::Segments
+  class Pricing < Base
+    Base.register_segment(self, identifier: '11')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'D9' => :ingredient_cost_submitted,
+        'DC' => :dispensing_fee_submitted,
+        'BE' => :professional_service_fee_submitted,
+        'DX' => :patient_paid_amount_submitted,
+        'E3' => :incentive_amount_submitted,
+        'H7' => :other_amount_claimed_submitted_count,
+        'H8' => :other_amount_claimed_submitted_qualifier,
+        'H9' => :other_amount_claimed_submitted,
+        'HA' => :flat_sales_tax_amount_submitted,
+        'GE' => :percentage_sales_tax_amount_submitted,
+        'HE' => :percentage_sales_tax_rate_submitted,
+        'JE' => :percentage_sales_tax_basis_submitted,
+        'DQ' => :usual_and_customary_charge,
+        'DU' => :gross_amount_due,
+        'DN' => :basis_of_cost_determination,
+        'N3' => :medicaid_paid_amount    ,
+      })
+    end
+  end
+end

data/lib/dzero/segments/12_prior_auth.rb

@@ -0,0 +1,23 @@
+module DZero::Segments
+  class PriorAuth < Base
+    Base.register_segment(self, identifier: '12')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'PA' => :request_type,
+        'PB' => :request_period_date_begin,
+        'PC' => :request_period_date_end,
+        'PD' => :basis_of_request,
+        'PE' => :authorized_representative_first_name,
+        'PF' => :authorized_rep_last_name,
+        'PG' => :authorized_rep_street_address,
+        'PH' => :authorized_rep_city,
+        'PJ' => :authorized_rep_state_province,
+        'PK' => :authorized_rep_zip_postal_code,
+        'PY' => :prior_authorization_number_assigned,
+        'F3' => :authorization_number,
+        'PP' => :prior_authorization_supporting_documentation,
+      })
+    end
+  end
+end

data/lib/dzero/segments/13_clinical.rb

@@ -0,0 +1,19 @@
+module DZero::Segments
+  class Clinical < Base
+    Base.register_segment(self, identifier: '13')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'VE' => :diagnosis_code_count,
+        'WE' => :diagnosis_code_qualifier,
+        'DO' => :diagnosis_code,
+        'XE' => :clinical_information_counter,
+        'ZE' => :measurement_date,
+        'H1' => :measurement_time,
+        'H2' => :measurement_dimension,
+        'H3' => :measurement_unit,
+        'H4' => :measurement_value,
+      })
+    end
+  end
+end

data/lib/dzero/segments/14_additional_documentation.rb

@@ -0,0 +1,25 @@
+module DZero::Segments
+  class AdditionalDocumentation < Base
+    Base.register_segment(self, identifier: '14')
+
+    def self.field_id_to_symbol
+      super.merge({
+        '2Q' => :additional_documentation_type_id,
+        '2V' => :request_period_begin_date,
+        '2W' => :request_period_recert_revised_date,
+        '2U' => :request_status,
+        '2S' => :length_of_need_qualifier,
+        '2R' => :length_of_need,
+        '2T' => :prescriber_supplier_date_signed,
+        '2X' => :supporting_documentation,
+        '2Z' => :question_number_letter_count,
+        '4B' => :question_number_letter,
+        '4D' => :question_percent_response,
+        '4G' => :question_date_response,
+        '4H' => :question_dollar_amount_response,
+        '4J' => :question_numeric_response,
+        '4K' => :question_alphanumeric_response,
+      })
+    end
+  end
+end

data/lib/dzero/segments/15_facility.rb

@@ -0,0 +1,16 @@
+module DZero::Segments
+  class Facility < Base
+    Base.register_segment(self, identifier: '15')
+
+    def self.field_id_to_symbol
+      super.merge({
+        '8C' => :facility_id,
+        '3Q' => :facility_name,
+        '3U' => :facility_street_address,
+        '5J' => :facility_city_address,
+        '3V' => :facility_state_province_address,
+        '6D' => :facility_zip_postal_zone,
+      })
+    end
+  end
+end

data/lib/dzero/segments/16_narrative.rb

@@ -0,0 +1,11 @@
+module DZero::Segments
+  class Narrative < Base
+    Base.register_segment(self, identifier: '16')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'BM' => :narrative_message,
+      })
+    end
+  end
+end

data/lib/dzero/segments/20_response_message.rb

@@ -0,0 +1,11 @@
+module DZero::Segments
+  class ResponseMessage < Base
+    Base.register_segment(self, identifier: '20')
+
+    def self.field_id_to_symbol
+      super.merge({
+        'F4' => :message,
+      })
+    end
+  end
+end