hln_ice 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.rspec +3 -0
- data/.rubocop.yml +13 -0
- data/CHANGELOG.md +5 -0
- data/LICENSE.txt +21 -0
- data/README.md +156 -0
- data/Rakefile +12 -0
- data/lib/hln_ice/client.rb +455 -0
- data/lib/hln_ice/version.rb +5 -0
- data/lib/hln_ice.rb +8 -0
- data/sig/hln_ice.rbs +4 -0
- metadata +100 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 5cc821a0690dfaa750fb0dd36f1409a8a20054486318166f708bd8a266ff5c7a
|
|
4
|
+
data.tar.gz: 424486397d7ae838ee6af769155deef6a8b5bff76309291470a295c10eb58389
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 172c72400334ad1e9ca73b37fd7c77c7227386336e44e5d751c69d1bf40e021664ac0ceeeb835361924d6ddaff6cc0898420e07f5088fe72925821fdfa35bf11
|
|
7
|
+
data.tar.gz: 1ee834f1abd93c7cb9dc19453a7afd111a39f5745ad12d3d6345bae406805c9fb837fa3aacb80ecc03e9fe81c1cfe6d36d36b6790be2ed657aa0596e147f624d
|
data/.rspec
ADDED
data/.rubocop.yml
ADDED
data/CHANGELOG.md
ADDED
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sam Sohn
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# HlnIce
|
|
2
|
+
|
|
3
|
+
A Ruby client for the [HLN ICE](https://www.hln.com/ice/) (Immunization Calculation Engine), an OpenCDS clinical decision-support service for immunization forecasting.
|
|
4
|
+
|
|
5
|
+
Given a patient's demographics and immunization history, `HlnIce` builds the
|
|
6
|
+
VMR (Virtual Medical Record) request, calls the ICE evaluation endpoint, and
|
|
7
|
+
parses the response into:
|
|
8
|
+
|
|
9
|
+
- a full list of **recommendations** (one per vaccine group, with status, reasons, and administration intervals), and
|
|
10
|
+
- a **simplified status** map keyed by vaccine group — e.g. `{ ipv_opv: "overdue", mmr: "compliant" }`.
|
|
11
|
+
|
|
12
|
+
The gem has no Rails or ActiveSupport dependency; it takes an injected logger
|
|
13
|
+
so it can run in any Ruby application.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
Add the gem to your application's `Gemfile`:
|
|
18
|
+
|
|
19
|
+
```ruby
|
|
20
|
+
gem "hln_ice"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Then run:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
bundle install
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Or install it directly:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
gem install hln_ice
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
### Creating a client
|
|
38
|
+
|
|
39
|
+
```ruby
|
|
40
|
+
client = HlnIce::Client.new(base_url: "https://ice.example.com")
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
All options:
|
|
44
|
+
|
|
45
|
+
| Option | Default | Description |
|
|
46
|
+
| ------------- | ------------------------ | ----------------------------------------------------- |
|
|
47
|
+
| `base_url:` | _(required)_ | Base URL of the ICE OpenCDS service. |
|
|
48
|
+
| `timeout:` | `30` | HTTP request timeout, in seconds. |
|
|
49
|
+
| `max_retries:`| `3` | Number of retries on a failed evaluation request. |
|
|
50
|
+
| `retry_delay:`| `1` | Seconds to wait between retries. |
|
|
51
|
+
| `logger:` | `Logger.new($stdout)` | Any `Logger`-compatible object. In Rails, pass `Rails.logger`. |
|
|
52
|
+
|
|
53
|
+
```ruby
|
|
54
|
+
# In a Rails app, reuse the application logger:
|
|
55
|
+
client = HlnIce::Client.new(base_url: ENV["ICE_URL"], logger: Rails.logger)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Checking availability
|
|
59
|
+
|
|
60
|
+
```ruby
|
|
61
|
+
client.available? # => true / false
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Evaluating immunizations
|
|
65
|
+
|
|
66
|
+
Pass a patient hash with their demographics and (optionally) prior
|
|
67
|
+
immunization events:
|
|
68
|
+
|
|
69
|
+
```ruby
|
|
70
|
+
patient_data = {
|
|
71
|
+
patient: {
|
|
72
|
+
id: "12345",
|
|
73
|
+
date_of_birth: "2020-01-01", # parseable date string
|
|
74
|
+
gender: "M" # "M", "F", or blank (defaults to "U")
|
|
75
|
+
},
|
|
76
|
+
immunizations: [
|
|
77
|
+
{
|
|
78
|
+
clinicalStatements: {
|
|
79
|
+
substanceAdministrationEvents: [
|
|
80
|
+
{
|
|
81
|
+
substance: {
|
|
82
|
+
substanceCode: { code: "10", displayName: "Polio" }
|
|
83
|
+
},
|
|
84
|
+
administrationTimeInterval: { low: "2020-03-01", high: "2020-03-01" }
|
|
85
|
+
}
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
]
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
result = client.evaluate_immunizations(patient_data)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### The result
|
|
96
|
+
|
|
97
|
+
On success:
|
|
98
|
+
|
|
99
|
+
```ruby
|
|
100
|
+
{
|
|
101
|
+
success: true,
|
|
102
|
+
data: {
|
|
103
|
+
raw_xml: "<...the decoded ICE response XML...>",
|
|
104
|
+
patient: { id: "12345", birth_date: "2020-01-01", gender: "M" },
|
|
105
|
+
recommendations: [
|
|
106
|
+
{
|
|
107
|
+
vaccine: { code: "10", code_system: "...", name: "Polio Vaccine Group" },
|
|
108
|
+
status: { code: "RECOMMENDED", name: "Recommended" },
|
|
109
|
+
reasons: [{ code: "DUE_NOW", name: "Due Now" }],
|
|
110
|
+
intervals: { proposed: { low: "2020-03-01", high: "2020-04-01" } }
|
|
111
|
+
}
|
|
112
|
+
],
|
|
113
|
+
simplified_status: { ipv_opv: "overdue" }
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
On failure (service error, timeout after retries, or unparseable response):
|
|
119
|
+
|
|
120
|
+
```ruby
|
|
121
|
+
{ success: false, error: "ICE service error: 400 - ..." }
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Always branch on `result[:success]` before reading `result[:data]`.
|
|
125
|
+
|
|
126
|
+
### Simplified status values
|
|
127
|
+
|
|
128
|
+
`simplified_status` maps each recognized vaccine group to one of:
|
|
129
|
+
|
|
130
|
+
| Value | Meaning |
|
|
131
|
+
| ------------------ | ----------------------------------------------------------- |
|
|
132
|
+
| `"compliant"` | Up to date (ICE `FUTURE_RECOMMENDED` / `NOT_RECOMMENDED`). |
|
|
133
|
+
| `"overdue"` | A dose is recommended now (ICE `RECOMMENDED`). |
|
|
134
|
+
| `"conditional"` | Conditionally recommended (ICE `CONDITIONAL`). |
|
|
135
|
+
| `"medically_exempt"` | Conditional status with a medical-exemption reason. |
|
|
136
|
+
|
|
137
|
+
The recognized vaccine-group keys are: `:dtap_tdap`, `:hep_a`, `:hep_b`,
|
|
138
|
+
`:hib`, `:hpv`, `:mcv4`, `:mmr`, `:pcv`, `:ipv_opv`, and `:var`.
|
|
139
|
+
|
|
140
|
+
## Development
|
|
141
|
+
|
|
142
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then,
|
|
143
|
+
run `rake spec` to run the tests. You can also run `bin/console` for an
|
|
144
|
+
interactive prompt that will allow you to experiment.
|
|
145
|
+
|
|
146
|
+
To install this gem onto your local machine, run `bundle exec rake install`.
|
|
147
|
+
|
|
148
|
+
## Contributing
|
|
149
|
+
|
|
150
|
+
Bug reports and pull requests are welcome on GitHub at
|
|
151
|
+
https://github.com/PrimaryDotHealth/hln_ice.
|
|
152
|
+
|
|
153
|
+
## License
|
|
154
|
+
|
|
155
|
+
The gem is available as open source under the terms of the
|
|
156
|
+
[MIT License](https://opensource.org/licenses/MIT).
|
data/Rakefile
ADDED
|
@@ -0,0 +1,455 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "date"
|
|
4
|
+
require "json"
|
|
5
|
+
require "base64"
|
|
6
|
+
require "logger"
|
|
7
|
+
require "securerandom"
|
|
8
|
+
require "httparty"
|
|
9
|
+
require "nokogiri"
|
|
10
|
+
|
|
11
|
+
module HlnIce
|
|
12
|
+
# Client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
|
|
13
|
+
#
|
|
14
|
+
# Evaluates a patient's immunization history against the ICE forecasting
|
|
15
|
+
# rules and returns both the raw recommendations and a simplified status
|
|
16
|
+
# mapping keyed by vaccine group.
|
|
17
|
+
class Client
|
|
18
|
+
# Mapping from ICE status codes to our status keys
|
|
19
|
+
STATUS_MAPPING = {
|
|
20
|
+
"CONDITIONAL" => "conditional",
|
|
21
|
+
"FUTURE_RECOMMENDED" => "compliant",
|
|
22
|
+
"NOT_RECOMMENDED" => "compliant",
|
|
23
|
+
"RECOMMENDED" => "overdue",
|
|
24
|
+
}.freeze
|
|
25
|
+
|
|
26
|
+
# Mapping from ICE vaccine groups to our immunization keys
|
|
27
|
+
VACCINE_MAPPING = {
|
|
28
|
+
"DTP Vaccine Group" => :dtap_tdap,
|
|
29
|
+
"Hep A Vaccine Group" => :hep_a,
|
|
30
|
+
"Hep B Vaccine Group" => :hep_b,
|
|
31
|
+
"Hib Vaccine Group" => :hib,
|
|
32
|
+
"HPV Vaccine Group" => :hpv,
|
|
33
|
+
"Meningococcal Vaccine Group" => :mcv4,
|
|
34
|
+
"MMR Vaccine Group" => :mmr,
|
|
35
|
+
"Pneumococcal Vaccine Group" => :pcv,
|
|
36
|
+
"Polio Vaccine Group" => :ipv_opv,
|
|
37
|
+
"Varicella Vaccine Group" => :var,
|
|
38
|
+
}.freeze
|
|
39
|
+
|
|
40
|
+
attr_reader :base_url, :timeout, :max_retries, :retry_delay, :logger
|
|
41
|
+
|
|
42
|
+
def initialize(base_url:, timeout: 30, max_retries: 3, retry_delay: 1, logger: nil)
|
|
43
|
+
@base_url = base_url
|
|
44
|
+
@timeout = timeout
|
|
45
|
+
@max_retries = max_retries
|
|
46
|
+
@retry_delay = retry_delay
|
|
47
|
+
@logger = logger || Logger.new($stdout)
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# Check if the ICE service is available
|
|
51
|
+
def available?
|
|
52
|
+
url = "#{base_url}/opencds-decision-support-service/version"
|
|
53
|
+
|
|
54
|
+
begin
|
|
55
|
+
response = HTTParty.get(
|
|
56
|
+
url,
|
|
57
|
+
timeout:
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
response.success?
|
|
61
|
+
rescue => e
|
|
62
|
+
logger.error("ICE service unavailable: #{e.message}")
|
|
63
|
+
false
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# Evaluate immunizations using patient data
|
|
68
|
+
def evaluate_immunizations(patient_data)
|
|
69
|
+
url = "#{base_url}/opencds-decision-support-service/api/resources/evaluate"
|
|
70
|
+
|
|
71
|
+
# Build the payload for the ICE service
|
|
72
|
+
payload = build_ice_payload(patient_data)
|
|
73
|
+
|
|
74
|
+
# Make the request with retries
|
|
75
|
+
response = nil
|
|
76
|
+
retries = 0
|
|
77
|
+
|
|
78
|
+
begin
|
|
79
|
+
response = HTTParty.post(
|
|
80
|
+
url,
|
|
81
|
+
body: payload.to_json,
|
|
82
|
+
headers: {
|
|
83
|
+
"Content-Type": "application/json",
|
|
84
|
+
"Accept": "application/json"
|
|
85
|
+
},
|
|
86
|
+
timeout:
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
if response.success?
|
|
90
|
+
parse_ice_response(response.body)
|
|
91
|
+
else
|
|
92
|
+
handle_error_response(response)
|
|
93
|
+
end
|
|
94
|
+
rescue => e
|
|
95
|
+
retries += 1
|
|
96
|
+
if retries <= max_retries
|
|
97
|
+
logger.warn("Retrying ICE request (#{retries}/#{max_retries}): #{e.message}")
|
|
98
|
+
sleep(retry_delay)
|
|
99
|
+
retry
|
|
100
|
+
else
|
|
101
|
+
logger.error("Error evaluating immunizations after #{max_retries} retries: #{e.message}")
|
|
102
|
+
{ success: false, error: "Error evaluating immunizations: #{e.message}" }
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
private
|
|
108
|
+
# Plain-Ruby equivalent of ActiveSupport's `blank?`.
|
|
109
|
+
def blank?(value)
|
|
110
|
+
return true if value.nil?
|
|
111
|
+
return value.strip.empty? if value.is_a?(String)
|
|
112
|
+
return value.empty? if value.respond_to?(:empty?)
|
|
113
|
+
|
|
114
|
+
false
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
# Plain-Ruby equivalent of ActiveSupport's `present?`.
|
|
118
|
+
def present?(value)
|
|
119
|
+
!blank?(value)
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
def build_ice_payload(patient_data)
|
|
123
|
+
# Extract patient information
|
|
124
|
+
patient_id = patient_data[:patient][:id]
|
|
125
|
+
date_of_birth = patient_data[:patient][:date_of_birth]
|
|
126
|
+
gender = patient_data[:patient][:gender]
|
|
127
|
+
gender = "U" if blank?(gender) # Set default to 'U' if blank
|
|
128
|
+
|
|
129
|
+
# Log input data for debugging
|
|
130
|
+
logger.debug("ICE Input Data: #{JSON.pretty_generate(patient_data)}")
|
|
131
|
+
|
|
132
|
+
# Build the VMR XML
|
|
133
|
+
xml_payload = <<~XML
|
|
134
|
+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
|
135
|
+
<ns4:cdsInput xmlns:ns2="org.opencds"
|
|
136
|
+
xmlns:ns3="org.opencds.vmr.v1_0.schema.vmr"
|
|
137
|
+
xmlns:ns4="org.opencds.vmr.v1_0.schema.cdsinput"
|
|
138
|
+
xmlns:ns5="org.opencds.vmr.v1_0.schema.cdsoutput">
|
|
139
|
+
<templateId root="2.16.840.1.113883.3.795.11.1.1"/>
|
|
140
|
+
<cdsContext>
|
|
141
|
+
<cdsSystemUserPreferredLanguage code="en" codeSystem="2.16.840.1.113883.6.99" displayName="English"/>
|
|
142
|
+
</cdsContext>
|
|
143
|
+
<vmrInput>
|
|
144
|
+
<templateId root="2.16.840.1.113883.3.795.11.1.1"/>
|
|
145
|
+
<patient>
|
|
146
|
+
<templateId root="2.16.840.1.113883.3.795.11.2.1.1"/>
|
|
147
|
+
<id root="2.16.840.1.113883.3.795.12.100.11" extension="#{patient_id}"/>
|
|
148
|
+
<demographics>
|
|
149
|
+
<birthTime value="#{format_date_for_ice(date_of_birth)}"/>
|
|
150
|
+
<gender code="#{gender}" codeSystem="2.16.840.1.113883.5.1"/>
|
|
151
|
+
</demographics>
|
|
152
|
+
<clinicalStatements>
|
|
153
|
+
<substanceAdministrationEvents>
|
|
154
|
+
XML
|
|
155
|
+
|
|
156
|
+
# Add immunization records if available
|
|
157
|
+
if present?(patient_data[:immunizations])
|
|
158
|
+
patient_data[:immunizations].each do |imm|
|
|
159
|
+
next unless present?(imm.dig(:clinicalStatements, :substanceAdministrationEvents))
|
|
160
|
+
|
|
161
|
+
imm[:clinicalStatements][:substanceAdministrationEvents].each do |event|
|
|
162
|
+
next unless present?(event.dig(:substance, :substanceCode))
|
|
163
|
+
|
|
164
|
+
substance_code = event[:substance][:substanceCode]
|
|
165
|
+
|
|
166
|
+
# Format dates to ICE format (YYYYMMDD)
|
|
167
|
+
low_date = format_date_for_ice(event[:administrationTimeInterval][:low])
|
|
168
|
+
high_date = format_date_for_ice(event[:administrationTimeInterval][:high])
|
|
169
|
+
|
|
170
|
+
xml_payload += <<~XML
|
|
171
|
+
<substanceAdministrationEvent>
|
|
172
|
+
<templateId root="2.16.840.1.113883.3.795.11.9.1.1"/>
|
|
173
|
+
<id root="#{event[:id] || SecureRandom.uuid}"/>
|
|
174
|
+
<substanceAdministrationGeneralPurpose code="384810002" codeSystem="2.16.840.1.113883.6.5"/>
|
|
175
|
+
<substance>
|
|
176
|
+
<id root="#{event[:substance][:id] || SecureRandom.uuid}"/>
|
|
177
|
+
<substanceCode code="#{substance_code[:code]}"
|
|
178
|
+
codeSystem="2.16.840.1.113883.12.292"
|
|
179
|
+
displayName="#{substance_code[:displayName]}"
|
|
180
|
+
originalText="#{substance_code[:displayName]}"/>
|
|
181
|
+
</substance>
|
|
182
|
+
<administrationTimeInterval low="#{low_date}" high="#{high_date}"/>
|
|
183
|
+
</substanceAdministrationEvent>
|
|
184
|
+
XML
|
|
185
|
+
end
|
|
186
|
+
end
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
# Close the XML
|
|
190
|
+
xml_payload += <<~XML
|
|
191
|
+
</substanceAdministrationEvents>
|
|
192
|
+
</clinicalStatements>
|
|
193
|
+
</patient>
|
|
194
|
+
</vmrInput>
|
|
195
|
+
</ns4:cdsInput>
|
|
196
|
+
XML
|
|
197
|
+
|
|
198
|
+
# Log the generated XML for debugging
|
|
199
|
+
logger.debug("Generated ICE XML: #{xml_payload}")
|
|
200
|
+
|
|
201
|
+
# Base64 encode the XML
|
|
202
|
+
base64_encoded_payload = Base64.strict_encode64(xml_payload)
|
|
203
|
+
|
|
204
|
+
# Build the full payload
|
|
205
|
+
{
|
|
206
|
+
"interactionId" => {
|
|
207
|
+
"scopingEntityId" => "org.nyc.cir",
|
|
208
|
+
"interactionId" => "#{patient_id}-#{Time.now.to_i}",
|
|
209
|
+
"submissionTime" => (Time.now.to_f * 1000).to_i
|
|
210
|
+
},
|
|
211
|
+
"evaluationRequest" => {
|
|
212
|
+
"clientLanguage" => "en",
|
|
213
|
+
"clientTimeZoneOffset" => "+0000",
|
|
214
|
+
"kmEvaluationRequest" => [
|
|
215
|
+
{
|
|
216
|
+
"kmId" => {
|
|
217
|
+
"scopingEntityId" => "org.nyc.cir",
|
|
218
|
+
"businessId" => "ICE",
|
|
219
|
+
"version" => "1.0.0"
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
],
|
|
223
|
+
"dataRequirementItemData" => [
|
|
224
|
+
{
|
|
225
|
+
"driId" => {
|
|
226
|
+
"containingEntityId" => {
|
|
227
|
+
"scopingEntityId" => "org.nyc.cir",
|
|
228
|
+
"businessId" => "ICEData",
|
|
229
|
+
"version" => "1.0.0"
|
|
230
|
+
},
|
|
231
|
+
"itemId" => "cdsPayload"
|
|
232
|
+
},
|
|
233
|
+
"data" => {
|
|
234
|
+
"informationModelSSId" => {
|
|
235
|
+
"scopingEntityId" => "org.opencds.vmr",
|
|
236
|
+
"businessId" => "VMR",
|
|
237
|
+
"version" => "1.0"
|
|
238
|
+
},
|
|
239
|
+
"base64EncodedPayload" => [base64_encoded_payload]
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
]
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
end
|
|
246
|
+
|
|
247
|
+
def parse_ice_response(response_body)
|
|
248
|
+
logger.info("ICE service response: #{response_body}")
|
|
249
|
+
|
|
250
|
+
result = JSON.parse(response_body)
|
|
251
|
+
|
|
252
|
+
if result.dig("finalKMEvaluationResponse", 0, "kmEvaluationResultData", 0, "data", "base64EncodedPayload", 0)
|
|
253
|
+
base64_result = result["finalKMEvaluationResponse"][0]["kmEvaluationResultData"][0]["data"]["base64EncodedPayload"][0]
|
|
254
|
+
decoded_result = Base64.decode64(base64_result)
|
|
255
|
+
|
|
256
|
+
# Parse the XML response
|
|
257
|
+
parsed_result = parse_xml_response(decoded_result)
|
|
258
|
+
|
|
259
|
+
{
|
|
260
|
+
success: true,
|
|
261
|
+
data: parsed_result
|
|
262
|
+
}
|
|
263
|
+
else
|
|
264
|
+
logger.warn("No valid response found in ICE output.")
|
|
265
|
+
{
|
|
266
|
+
success: false,
|
|
267
|
+
error: "No valid response found in ICE output."
|
|
268
|
+
}
|
|
269
|
+
end
|
|
270
|
+
rescue => e
|
|
271
|
+
logger.error("Error parsing ICE response: #{e.message}")
|
|
272
|
+
{ success: false, error: "Error parsing ICE response: #{e.message}" }
|
|
273
|
+
end
|
|
274
|
+
|
|
275
|
+
def parse_xml_response(xml_string)
|
|
276
|
+
# Parse the XML
|
|
277
|
+
doc = Nokogiri::XML(xml_string)
|
|
278
|
+
|
|
279
|
+
# Remove namespaces to simplify parsing
|
|
280
|
+
doc.remove_namespaces!
|
|
281
|
+
|
|
282
|
+
# Extract patient information
|
|
283
|
+
patient = doc.xpath("//patient").first
|
|
284
|
+
return { raw_xml: xml_string } unless patient
|
|
285
|
+
|
|
286
|
+
patient_id = patient.xpath("./id").first["extension"] rescue nil
|
|
287
|
+
birth_time = patient.xpath("./demographics/birthTime").first["value"] rescue nil
|
|
288
|
+
gender = patient.xpath("./demographics/gender").first["code"] rescue nil
|
|
289
|
+
|
|
290
|
+
# Format birth date if present
|
|
291
|
+
birth_date = format_ice_date(birth_time)
|
|
292
|
+
|
|
293
|
+
# Extract vaccine recommendations
|
|
294
|
+
all_recommendations = []
|
|
295
|
+
|
|
296
|
+
doc.xpath("//substanceAdministrationProposal").each do |proposal|
|
|
297
|
+
# Get the substance code and name
|
|
298
|
+
substance_element = proposal.xpath("./substance/substanceCode").first
|
|
299
|
+
next unless substance_element
|
|
300
|
+
|
|
301
|
+
vaccine_code = substance_element["code"]
|
|
302
|
+
vaccine_name = substance_element["displayName"]
|
|
303
|
+
vaccine_code_system = substance_element["codeSystem"]
|
|
304
|
+
|
|
305
|
+
# Get the clinical observation result
|
|
306
|
+
observation = proposal.xpath(".//observationResult").first
|
|
307
|
+
next unless observation
|
|
308
|
+
|
|
309
|
+
# Get recommendation status
|
|
310
|
+
status_element = observation.xpath(".//observationValue/concept").first
|
|
311
|
+
next unless status_element
|
|
312
|
+
|
|
313
|
+
status_code = status_element["code"]
|
|
314
|
+
status_name = status_element["displayName"]
|
|
315
|
+
|
|
316
|
+
# Get interpretation reasons
|
|
317
|
+
reasons = []
|
|
318
|
+
observation.xpath(".//interpretation").each do |interpretation|
|
|
319
|
+
reason = {
|
|
320
|
+
code: interpretation["code"],
|
|
321
|
+
name: interpretation["displayName"]
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
# Add supplemental text if available
|
|
325
|
+
if interpretation["originalText"]
|
|
326
|
+
reason[:supplemental_text] = interpretation["originalText"]
|
|
327
|
+
end
|
|
328
|
+
|
|
329
|
+
reasons << reason
|
|
330
|
+
end
|
|
331
|
+
|
|
332
|
+
# Get administration time intervals if available
|
|
333
|
+
proposed_interval = proposal.xpath("./proposedAdministrationTimeInterval").first
|
|
334
|
+
valid_interval = proposal.xpath("./validAdministrationTimeInterval").first
|
|
335
|
+
|
|
336
|
+
intervals = {}
|
|
337
|
+
if proposed_interval
|
|
338
|
+
intervals[:proposed] = {
|
|
339
|
+
low: format_ice_date(proposed_interval["low"]),
|
|
340
|
+
high: format_ice_date(proposed_interval["high"])
|
|
341
|
+
}.compact
|
|
342
|
+
end
|
|
343
|
+
|
|
344
|
+
if valid_interval
|
|
345
|
+
intervals[:valid] = {
|
|
346
|
+
low: format_ice_date(valid_interval["low"]),
|
|
347
|
+
high: format_ice_date(valid_interval["high"])
|
|
348
|
+
}.compact
|
|
349
|
+
end
|
|
350
|
+
|
|
351
|
+
# Build the recommendation object
|
|
352
|
+
recommendation = {
|
|
353
|
+
vaccine: {
|
|
354
|
+
code: vaccine_code,
|
|
355
|
+
code_system: vaccine_code_system,
|
|
356
|
+
name: vaccine_name
|
|
357
|
+
},
|
|
358
|
+
status: {
|
|
359
|
+
code: status_code,
|
|
360
|
+
name: status_name
|
|
361
|
+
},
|
|
362
|
+
reasons:
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
# Only add intervals if they exist
|
|
366
|
+
recommendation[:intervals] = intervals if present?(intervals)
|
|
367
|
+
|
|
368
|
+
all_recommendations << recommendation
|
|
369
|
+
end
|
|
370
|
+
|
|
371
|
+
# Create simplified immunization status mapping
|
|
372
|
+
simplified_status = {}
|
|
373
|
+
|
|
374
|
+
# Process all recommendations to create the simplified mapping
|
|
375
|
+
all_recommendations.each do |recommendation|
|
|
376
|
+
vaccine_name = recommendation[:vaccine][:name]
|
|
377
|
+
status_code = recommendation[:status][:code]
|
|
378
|
+
|
|
379
|
+
# Map the vaccine name to our key
|
|
380
|
+
vaccine_key = VACCINE_MAPPING[vaccine_name]
|
|
381
|
+
next unless vaccine_key # Skip if we don't have a mapping
|
|
382
|
+
|
|
383
|
+
# Map the status code to our status
|
|
384
|
+
status = STATUS_MAPPING[status_code] || "overdue" # Default to overdue if unknown
|
|
385
|
+
|
|
386
|
+
# Special handling for conditional status based on reasons
|
|
387
|
+
if status == "conditional"
|
|
388
|
+
# Check if any reason indicates medical exemption
|
|
389
|
+
has_medical_exemption = recommendation[:reasons].any? { |r| r[:code] == "MEDICAL_EXEMPTION" }
|
|
390
|
+
if has_medical_exemption
|
|
391
|
+
status = "medically_exempt"
|
|
392
|
+
end
|
|
393
|
+
end
|
|
394
|
+
|
|
395
|
+
# Store in our simplified mapping
|
|
396
|
+
simplified_status[vaccine_key] = status
|
|
397
|
+
end
|
|
398
|
+
|
|
399
|
+
# Build the final result structure
|
|
400
|
+
{
|
|
401
|
+
raw_xml: xml_string,
|
|
402
|
+
patient: {
|
|
403
|
+
id: patient_id,
|
|
404
|
+
birth_date: birth_date || birth_time,
|
|
405
|
+
gender:
|
|
406
|
+
}.compact,
|
|
407
|
+
recommendations: all_recommendations, # Keep the original flat list for backward compatibility
|
|
408
|
+
simplified_status: # Add the simplified mapping
|
|
409
|
+
}
|
|
410
|
+
end
|
|
411
|
+
|
|
412
|
+
def handle_error_response(response)
|
|
413
|
+
error_message = "ICE service error: #{response.code}"
|
|
414
|
+
|
|
415
|
+
begin
|
|
416
|
+
error_details = JSON.parse(response.body)
|
|
417
|
+
error_message += " - #{error_details['message'] || error_details['error'] || response.body}"
|
|
418
|
+
rescue
|
|
419
|
+
error_message += " - #{response.body}"
|
|
420
|
+
end
|
|
421
|
+
|
|
422
|
+
logger.error(error_message)
|
|
423
|
+
{ success: false, error: error_message }
|
|
424
|
+
end
|
|
425
|
+
|
|
426
|
+
# Helper method to format ICE dates to standard format
|
|
427
|
+
def format_ice_date(ice_date)
|
|
428
|
+
return nil unless ice_date
|
|
429
|
+
|
|
430
|
+
# ICE dates are in format: YYYYMMDDHHMMSS.000+0000
|
|
431
|
+
if ice_date.match(/^(\d{4})(\d{2})(\d{2})/)
|
|
432
|
+
year = $1
|
|
433
|
+
month = $2
|
|
434
|
+
day = $3
|
|
435
|
+
"#{year}-#{month}-#{day}"
|
|
436
|
+
else
|
|
437
|
+
ice_date
|
|
438
|
+
end
|
|
439
|
+
end
|
|
440
|
+
|
|
441
|
+
# Helper method to format dates for ICE (YYYYMMDD)
|
|
442
|
+
def format_date_for_ice(date_string)
|
|
443
|
+
return nil unless date_string
|
|
444
|
+
|
|
445
|
+
begin
|
|
446
|
+
date = Date.parse(date_string)
|
|
447
|
+
# Format as YYYYMMDD
|
|
448
|
+
date.strftime("%Y%m%d")
|
|
449
|
+
rescue
|
|
450
|
+
# If parsing fails, try to use the original string
|
|
451
|
+
date_string
|
|
452
|
+
end
|
|
453
|
+
end
|
|
454
|
+
end
|
|
455
|
+
end
|
data/lib/hln_ice.rb
ADDED
data/sig/hln_ice.rbs
ADDED
metadata
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: hln_ice
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Sam Sohn
|
|
8
|
+
autorequire:
|
|
9
|
+
bindir: exe
|
|
10
|
+
cert_chain: []
|
|
11
|
+
date: 2026-06-22 00:00:00.000000000 Z
|
|
12
|
+
dependencies:
|
|
13
|
+
- !ruby/object:Gem::Dependency
|
|
14
|
+
name: base64
|
|
15
|
+
requirement: !ruby/object:Gem::Requirement
|
|
16
|
+
requirements:
|
|
17
|
+
- - "~>"
|
|
18
|
+
- !ruby/object:Gem::Version
|
|
19
|
+
version: '0.2'
|
|
20
|
+
type: :runtime
|
|
21
|
+
prerelease: false
|
|
22
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
23
|
+
requirements:
|
|
24
|
+
- - "~>"
|
|
25
|
+
- !ruby/object:Gem::Version
|
|
26
|
+
version: '0.2'
|
|
27
|
+
- !ruby/object:Gem::Dependency
|
|
28
|
+
name: httparty
|
|
29
|
+
requirement: !ruby/object:Gem::Requirement
|
|
30
|
+
requirements:
|
|
31
|
+
- - "~>"
|
|
32
|
+
- !ruby/object:Gem::Version
|
|
33
|
+
version: '0.21'
|
|
34
|
+
type: :runtime
|
|
35
|
+
prerelease: false
|
|
36
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
37
|
+
requirements:
|
|
38
|
+
- - "~>"
|
|
39
|
+
- !ruby/object:Gem::Version
|
|
40
|
+
version: '0.21'
|
|
41
|
+
- !ruby/object:Gem::Dependency
|
|
42
|
+
name: nokogiri
|
|
43
|
+
requirement: !ruby/object:Gem::Requirement
|
|
44
|
+
requirements:
|
|
45
|
+
- - "~>"
|
|
46
|
+
- !ruby/object:Gem::Version
|
|
47
|
+
version: '1.15'
|
|
48
|
+
type: :runtime
|
|
49
|
+
prerelease: false
|
|
50
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
51
|
+
requirements:
|
|
52
|
+
- - "~>"
|
|
53
|
+
- !ruby/object:Gem::Version
|
|
54
|
+
version: '1.15'
|
|
55
|
+
description: Evaluates a patient's immunization history against the HLN ICE forecasting
|
|
56
|
+
rules and returns both the raw recommendations and a simplified status mapping.
|
|
57
|
+
email:
|
|
58
|
+
- sam@primary.health
|
|
59
|
+
executables: []
|
|
60
|
+
extensions: []
|
|
61
|
+
extra_rdoc_files: []
|
|
62
|
+
files:
|
|
63
|
+
- ".rspec"
|
|
64
|
+
- ".rubocop.yml"
|
|
65
|
+
- CHANGELOG.md
|
|
66
|
+
- LICENSE.txt
|
|
67
|
+
- README.md
|
|
68
|
+
- Rakefile
|
|
69
|
+
- lib/hln_ice.rb
|
|
70
|
+
- lib/hln_ice/client.rb
|
|
71
|
+
- lib/hln_ice/version.rb
|
|
72
|
+
- sig/hln_ice.rbs
|
|
73
|
+
homepage: https://github.com/PrimaryDotHealth/hln_ice
|
|
74
|
+
licenses:
|
|
75
|
+
- MIT
|
|
76
|
+
metadata:
|
|
77
|
+
allowed_push_host: https://rubygems.org
|
|
78
|
+
homepage_uri: https://github.com/PrimaryDotHealth/hln_ice
|
|
79
|
+
source_code_uri: https://github.com/PrimaryDotHealth/hln_ice
|
|
80
|
+
changelog_uri: https://github.com/PrimaryDotHealth/hln_ice/blob/main/CHANGELOG.md
|
|
81
|
+
post_install_message:
|
|
82
|
+
rdoc_options: []
|
|
83
|
+
require_paths:
|
|
84
|
+
- lib
|
|
85
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
86
|
+
requirements:
|
|
87
|
+
- - ">="
|
|
88
|
+
- !ruby/object:Gem::Version
|
|
89
|
+
version: 3.1.0
|
|
90
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
91
|
+
requirements:
|
|
92
|
+
- - ">="
|
|
93
|
+
- !ruby/object:Gem::Version
|
|
94
|
+
version: '0'
|
|
95
|
+
requirements: []
|
|
96
|
+
rubygems_version: 3.5.3
|
|
97
|
+
signing_key:
|
|
98
|
+
specification_version: 4
|
|
99
|
+
summary: Ruby client for the HLN ICE (Immunization Calculation Engine) OpenCDS service.
|
|
100
|
+
test_files: []
|