allscripts_api 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 315aedfaf84044bf6676dba411e2c73f5693aa0e
-  data.tar.gz: 4d37e4ebba1d080edb9766e80dbb672dae232fd8
+  metadata.gz: e7f2c6194381fdaa1b4069b22120b15d035333e2
+  data.tar.gz: 01520fdc6872cfefe47c6844cf3067ee075095c3
 SHA512:
-  metadata.gz: 1215aeb29079a1a44e68c07762cb52f2e3132e0d57666574d30a43a49f04dd015c2833157eecfda9e9f964cfc06125b6b82ffd4cf55e7cfcc45c300734db3bae
-  data.tar.gz: 2a12b36abd1eca7dddef706a0fdd96726c4500c4ee55af2e166a43aadfc3e3e0f4e650ac576dbbb359a74f759b5520ce1ae2622677c19c2e8fb78709251bc826
+  metadata.gz: edfadd90b79088c4de35c34a0884e2d11bd7946e50b2ce6409197e793175e28ce97e00b55c69ce5b0e224d3cd578bf09f2d5e23bf08955c0bab775fc4227dc07
+  data.tar.gz: e87bb431c75c9cd005bd147a8c0043444cbc73181bef5b323d099660fe12c90a51dd7315a08d2da4458d8c570a1267ba026b662303dae09a9d5240a818137b40

data/.pryrc

@@ -1,6 +1,7 @@
 require "allscripts_api"
 require "yaml"
 require "awesome_print"
+require "base64"
 AwesomePrint.pry!
 AwesomePrint.defaults = { raw: true }
 
@@ -24,4 +25,26 @@ def bc
   client.get_user_authentication("jmedici", "password01")
 
   client
-end
+end
+
+def document_params 
+  {
+    bytes_read: "0",
+    b_done_upload: false,
+    document_var: "",
+    patient_id: 19,
+    owner_code: "TW0001",
+    first_name: "Allison",
+    last_name: "Allscripts",
+    document_type: "sEKG",   #document_type_de.entrycode value GetDictionary
+    organization_name: "New World Health"
+  }
+end
+
+def pdf
+  File.open("spec/fixtures/hba1c_sample.pdf").read
+end
+
+def encoded_pdf
+  Base64.encode64(pdf)
+end

data/.rubocop.yml

@@ -2,7 +2,7 @@ AllCops:
   Exclude:
     - "bin/*"
     - .pryrc
-    - "spec/*"
+    - "spec/**/*"
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -19,10 +19,20 @@ Metrics/MethodLength:
   Max: 15
   Exclude:
     - "lib/allscripts_api/order.rb"
+    - "lib/allscripts_api/documents/document.rb"
 # Bumbing the max from 5 to 7 allows magic params to work nicely
 Metrics/ParameterLists:
   Max: 7
 
 Metrics/AbcSize:
   Exclude:
-    - "lib/allscripts_api/order.rb"
+    - "lib/allscripts_api/order.rb"
+    - "lib/allscripts_api/documents/document.rb"
+
+Metrics/BlockLength:
+  Exclude:
+    -
+    - "lib/allscripts_api/documents/document.rb"
+
+Metrics/LineLength:
+  Max: 90

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    allscripts_api (0.4.0)
+    allscripts_api (0.5.0)
       faraday (>= 0.12.2)
 
 GEM

data/lib/allscripts_api.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
+
 require "nokogiri"
 require "allscripts_api/configuration"
+require "allscripts_api/utilities/validator"
 require "allscripts_api/magic_params"
 require "allscripts_api/named_magic_methods"
 require "allscripts_api/ordering_methods"
 require "allscripts_api/order"
+require "allscripts_api/documents"
 require "allscripts_api/client"
 require "allscripts_api/version"
 
@@ -18,6 +21,10 @@ module AllscriptsApi
   class GetTokenError < RuntimeError
   end
 
+  # Error raised when required params are missing.
+  class MissingRequiredParamsError < RuntimeError
+  end
+
   # Error raised if AllscriptsApi.connect is called without configuring
   # the gem first
   class NoConfigurationError < RuntimeError

data/lib/allscripts_api/client.rb

@@ -7,6 +7,7 @@ module AllscriptsApi
   class Client
     include AllscriptsApi::NamedMagicMethods
     include AllscriptsApi::OrderingMethods
+    include AllscriptsApi::Documents::DocumentMethods
     attr_reader :adapter, :unity_url, :app_name, :token
     attr_writer :sso_token
 

data/lib/allscripts_api/configuration.rb

@@ -4,12 +4,12 @@ module AllscriptsApi
   # Configuration class to allow configuration on application
   # initialization. Configuration should look like the following.
   #
-  # AllscriptsApi.configure do |config|
-  #   config.app_name = 'YOUR_APP_NAME_HERE'
-  #   config.app_username = 'YOUR_APP_USERNAME_HERE'
-  #   config.app_password = 'YOUR_APP_PASSWORD_HERE'
-  #   config.faraday_adapter = Faraday.some_adapter # default = Faraday.default_adapter
-  # end
+  #   AllscriptsApi.configure do |config|
+  #     config.app_name = 'YOUR_APP_NAME_HERE'
+  #     config.app_username = 'YOUR_APP_USERNAME_HERE'
+  #     config.app_password = 'YOUR_APP_PASSWORD_HERE'
+  #     config.faraday_adapter = Faraday.some_adapter # default = Faraday.default_adapter
+  #   end
   class Configuration
     attr_accessor :app_name, :app_password, :app_username, :faraday_adapter
     # The initialize method may be passed a block, but defaults to fetching

data/lib/allscripts_api/documents.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "allscripts_api/documents/document_methods"
+require "allscripts_api/documents/document"
+require "allscripts_api/documents/document_sender"

data/lib/allscripts_api/documents/document.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module AllscriptsApi
+  module Documents
+    # A value object wrapped around a Nokogiri::XML::Builder
+    # DSL that builds properly formatted XML for
+    # {AllscriptsApi::OrderingMethods.save_document_image}
+    # @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Builder
+    class Document
+      # rubocop:disable LineLength
+      # required parameters for building the XML, omitting any raises {MissingRequiredParamsError}
+      REQUIRED_PARAMS =
+        %i[bytes_read document_type first_name last_name
+           organization_name owner_code].freeze
+      # Builder method for returning XML needed to save document images
+      #
+      # @param file_name [String] name of the file you wish to save
+      # @param command [String] i for insert, e for delete (entered in error), u for update
+      # @param params [Hash] any other params you may wish to pass to the api
+      # params may look like the following, all of which are required:
+      # @option params [String] :bytes_read number of bytes in the chunk (use 0 for 1 big chunk)
+      # @option params [String] :b_done_upload should be passed in as false,
+      # @option params [String] :document_var should be empty unless you are saving or updating
+      # @option params [String] :patient_id
+      # @option params [String] :owner_code  EntryCode value from GetProvider
+      # @option params [String] :first_name patient first name
+      # @option params [String] :last_name patient last name
+      # @option params [String] :document_type document_type_de entrycode from value GetDictionary, for example, "sEKG"
+      # @option params [String] :organization_name  the org's name, e.g. "New World Health"
+      # @option params [String] :encounter_id  defaults to 0 to open a new encounter
+      # @option params [String] :orientation  defaults to 1. 1=No Rotation, 2=Rot 90 deg, 3=Rot 180 Deg, 4=Rot 270 Deg
+      # @see The '.pryrc' file for an example params hash
+      # @return [String] xml formatted for {AllscriptsApi::OrderingMethods#save_document_image}
+      # on required and optional params
+      # rubocop:enable LineLength
+      def self.build_xml(file_name, command = "i", params)
+        Utilities::Validator.validate_params(REQUIRED_PARAMS, params)
+        encounter_date_time = DateTime.now.strftime("%Y-%m-%d %H:%m:%S")
+        builder = Nokogiri::XML::Builder.new
+        builder.document do
+          # i for insert, e for delete (entered in error), u for update
+          builder.item("name" => "documentCommand",
+                       "value" => command)
+          # document_type_de.entrycode value GetDictionary
+          builder.item("name" => "documentType",
+                       "value" => params[:document_type])
+          # file offset of the current chunk to upload
+          # not yet supported by allscripts_api gem
+          builder.item("name" => "offset",
+                       "value" => "0")
+          # how many bytes in current chunk
+          builder.item("name" => "bytesRead", "value" => params[:bytes_read])
+          # false until the last chunk, then call SaveDocumentImage
+          # once more with true
+          builder.item("name" => "bDoneUpload",
+                       "value" => params[:b_done_upload] || "false")
+          # empty for first chunk, which will then return the GUID to use for
+          # subsequent calls
+          builder.item("name" => "documentVar",
+                       "value" => params[:document_var] || "")
+          # documentid only applies to updates
+          # not yet supported by allscripts_api gem
+          builder.item("name" => "documentID",
+                       "value" => "0")
+          # actual file name
+          builder.item("name" => "vendorFileName", "value" => file_name)
+          # Valid encounterID from GetEncounter Set to "0" to create encounter
+          # based on ahsEncounterDDTM value
+          builder.item("name" => "ahsEncounterDTTM",
+                       "value" => params[:encounter_time] ||
+                                  encounter_date_time)
+          builder.item("name" => "ahsEncounterID",
+                       "value" => params[:encounter_id] || "0")
+          # EntryCode value from GetProvider
+          builder.item("name" => "ownerCode", "value" => params[:owner_code])
+          # required to ensure the proper patient is identified
+          builder.item("name" => "organizationName",
+                       "value" => params[:organization_name])
+          # required for event table entries, audit
+          builder.item("name" => "patientFirstName",
+                       "value" => params[:first_name])
+          builder.item("name" => "patientLastName",
+                       "value" => params[:last_name])
+          # Indicate how to display in TouchWorks EHR UI:
+          # 1=No Rotation, 2=Rot 90 deg, 3=Rot 180 Deg, 4=Rot 270 Deg
+          builder.item("name" => "Orientation",
+                       "value" => params[:orientation] || "1")
+          builder.item("name" => "auditCCDASummary",
+                       "value" => "N")
+        end
+        # This is a hack to get around Nokogiri choking on
+        # {Nokogiri::XML::Builder.doc}
+        builder.to_xml.gsub("document>", "doc>")
+      end
+    end
+  end
+end

data/lib/allscripts_api/documents/document_methods.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AllscriptsApi
+  module Documents
+    # A collection of named convenience methods that map
+    # to Allscripts magic actions related to documents.
+    # These methods are included in {AllscriptsApi::Client}
+    # and can be accessed from instances of that class.
+    module DocumentMethods
+      # rubocop:disable LineLength
+      # a wrapper around SaveDocumentImage, which saves pdfs to Allscripts
+      #
+      # @param patient_id [String] patient id
+      # @param document_params [String] XML produced by {AllscriptsApi::Documents::Document.build_xml}
+      # @param document_buffer [String] a byte array of document data for the current chunk.
+      # @param base_64_data [String] Alternative to using the Data parameter. If Data parameter is empty/null, Unity will check for presence of content in Base64Data. Note: In the Parameter1 XML, bytesRead is still the number of document bytes and not the base-64 string length.
+      # @return [Hash, MagicError] a confirmation or error
+      # rubocop:Enable LineLength
+      def save_document_image(patient_id, document_params,
+                              document_buffer = nil, base_64_data = nil)
+        params =
+          MagicParams.format(
+            user_id: @allscripts_username,
+            patient_id: patient_id,
+            parameter1: document_params,
+            parameter6: base_64_data,
+            data: document_buffer
+          )
+        results = magic("SaveDocumentImage", magic_params: params)
+        results["savedocumentimageinfo"]
+      end
+    end
+  end
+end

data/lib/allscripts_api/documents/document_sender.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AllscriptsApi
+  module Documents
+    # Wraps {AllscriptsApi::Documents::Document.build_xml} and
+    # {AllscriptsApi::Documents::DocumentMethods#save_document_image}
+    # to handle the 2 step document image saving process
+    class DocumentSender
+      # rubocop:disable LineLength
+      # The new method sets up eerything needed to run {#send_document}
+      #
+      # @example Usage Example
+      #   document_params =
+      #     {
+      #       bytes_read: "0",
+      #       b_done_upload: false,
+      #       document_var: "",
+      #       patient_id: 19,
+      #       owner_code: "TW0001",
+      #       first_name: "Allison",
+      #       last_name: "Allscripts",
+      #       document_type: "sEKG",
+      #       organization_name: "New World Health"
+      #     }
+      #   ds = AllscriptsApi::Documents::DocumentSender.new(client, pdf, "test.pdf", document_params)
+      #   ds.send_document
+      #
+      # @param client [AllscriptsApi::Client] pass in an authorized client
+      # @param document [String] the string contents of the pdf to be saved
+      # @param file_name [String] the name of the file to be saved, usually ending in .pdf
+      # @param params [Hash] a hash of params for use in saving a document
+      # @see {AllscriptsApi::Dpcuments::DocumentSender} for details
+      # @return [AllscriptsApi::Documents::DocumentSender]
+      # rubocop:enable LineLength
+      def initialize(client, document, file_name, params)
+        @params = params
+        @patient_id = @params[:patient_id]
+        raise MissingRequiredParamsError, "patient_id required" unless @patient_id
+        @client = client
+        @document = Base64.encode64(document)
+        @file_name = file_name
+      end
+
+      # Sends the document in 2 steps, first the doc itself, then
+      # a confirmation that it is done and ready to be saved.
+      # @return [Hash, MagicError] a confirmation or error
+      def send_document
+        @params[:b_done_upload] = "false"
+        first_step_xml =
+          Documents::Document.build_xml(@file_name, "i", @params)
+        results =
+          @client.save_document_image(@patient_id,
+                                      first_step_xml, @document)
+        @params[:b_done_upload] = "true"
+        @params[:document_var] = results[0]["documentVar"]
+        second_step_xml =
+          Documents::Document.build_xml(@file_name, "i", @params)
+        @client.save_document_image(@patient_id,
+                                    second_step_xml, @document)
+      end
+    end
+  end
+end

data/lib/allscripts_api/named_magic_methods.rb

@@ -105,12 +105,12 @@ module AllscriptsApi
     end
 
     # gets patient's demographic info, insurance, guarantor, and PCP info
-    # Note that this method is litely to return blank data sets 
+    # Note that this method is litely to return blank data sets
     # for invalid IDs rather than raising an error
     #
     # @param patient_id [String] patient id
     # @param mrn [String|nil] medical record number, if patient id is unknown
-    # @parma order_id [String|nil] optionally used to get info for a secific
+    # @param order_id [String|nil] optionally used to get info for a secific
     # patient order
     # @return [String, AllscriptsApi::MagicError] patient demographics
     def get_patient_full(patient_id, mrn = nil, order_id = nil)
@@ -159,8 +159,7 @@ module AllscriptsApi
     #
     # @param start_date [Date] start date inclusive
     # @param end_date [Date] end date inclusive
-    # @return [Array<Hash>, Array, MagicError] a list of scheduled appointments,
-    # an empty array, or an error
+    # @return [Array<Hash>, Array, MagicError] a list of scheduled appointments, an empty array, or an error
     def get_schedule(start_date, end_date)
       params =
         MagicParams.format(
@@ -171,6 +170,15 @@ module AllscriptsApi
       results["getscheduleinfo"]
     end
 
+    # a wrapper around GetEncounterList
+    #
+    # @param patient_id [String] patient id
+    # @param encounter_type [String] encounter type to filter on from Encounter_Type_DE
+    # @param when_or_limit [String] filter by specified date
+    # @param nostradamus [String] how many days to look into the future. Defaults to 0. 
+    # @param show_past_flag [String] show previous encounters, "Y" or "N". Defaults to Y
+    # @param billing_provider_user_name [String] filter by user name (if specified)
+    # @return [Array<Hash>, Array, MagicError] a list of encounters
     def get_encounter_list(patient_id = "", encounter_type = "",
                            when_or_limit = "", nostradamus = 0,
                            show_past_flag = "Y",

data/lib/allscripts_api/order.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module AllscriptsApi
-  # A value object wrapped around a `Nokogiri::XML::Builder` DSL that builds
-  # properly formatted XML for `AllscriptsApi::OrderingMEthods.save_order`
+  # A value object wrapped around a Nokogiri::XML::Builder DSL that builds
+  # properly formatted XML for {AllscriptsApi::OrderingMethods#save_order}
+  # @see https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Builder
   class Order
     # Builder method for returning XML
     #

data/lib/allscripts_api/utilities/validator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AllscriptsApi
+  module Utilities
+    # Simple module that provides `validate_params`
+    # which  raises {MissingRequiredParamsError} if
+    # if required params are missing.
+    module Validator
+      # Raises and error if required params are missing
+      # @param required_params [Array<Symbol>]
+      # @param params [Hash] params to be validated
+      def self.validate_params(required_params, params)
+        # TODO: describe why this works
+        missing_keys = required_params - params.keys
+        unless missing_keys.empty?
+          raise MissingRequiredParamsError,
+                "The key(s) #{missing_keys} is/are required for this method."
+        end
+      end
+    end
+  end
+end

data/lib/allscripts_api/version.rb

@@ -2,5 +2,5 @@
 
 module AllscriptsApi
   # gem version declaration
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: allscripts_api
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Chase
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-04 00:00:00.000000000 Z
+date: 2018-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -247,10 +247,15 @@ files:
 - lib/allscripts_api.rb
 - lib/allscripts_api/client.rb
 - lib/allscripts_api/configuration.rb
+- lib/allscripts_api/documents.rb
+- lib/allscripts_api/documents/document.rb
+- lib/allscripts_api/documents/document_methods.rb
+- lib/allscripts_api/documents/document_sender.rb
 - lib/allscripts_api/magic_params.rb
 - lib/allscripts_api/named_magic_methods.rb
 - lib/allscripts_api/order.rb
 - lib/allscripts_api/ordering_methods.rb
+- lib/allscripts_api/utilities/validator.rb
 - lib/allscripts_api/version.rb
 homepage: https://github.com/Avhana/allscripts_api
 licenses: []