SDK Troubleshooting
Diagnose script loading, semantic rules, HL7/FHIR behavior, and managed HTTP client failures.
Start by reproducing the problem locally with the same HL7 input and configuration. Isolate the failing SDK layer before changing code or runtime settings.
Troubleshooting workflow
- Reproduce the problem locally with the representative HL7 message.
- Identify the lifecycle hook, semantic rule, FHIR operation, HTTP call, or cache involved.
- Inspect
MessageEnvelope, the parsed HAPI HL7 message, and the generated FHIR Bundle under the debugger. - Read the actual exception, validation issue, or HTTP response before changing configuration.
- Temporarily isolate external FHIR/REST dependencies if needed.
- Fix the root cause and add a regression test for the scenario.
Scripts and configuration
| Problem | Likely cause | Action |
|---|---|---|
| Script generation does not load | Compile error, wrong package/import, missing dependency | Run the SDK locally and fix compile/startup errors before deployment. |
| Sandbox validation fails | Restricted class/API or forbidden operation | Move the operation to a managed SDK API or supported helper instead of bypassing the sandbox. |
| Script hook times out | Slow external call, blocking logic, or unexpectedly large work | Inspect the hook under the debugger; move non-critical work async and keep expensive operations out of fast hooks. |
Injected field is null | Missing injection annotation, wrong field type/import | Verify the SDK injection annotation and declared field type. |
Property is null | Missing key, typo, or unresolved environment placeholder | Check script.properties, environment variables, and validate required configuration in onStartup(). |
| Message filtered unexpectedly | shouldProcess() returned reject | Log the rejection reason and inspect message code, trigger event, and workflow metadata. |
| HL7 value not changed | Wrong helper path, repetition, or branch never executed | Debug the parsed HAPI message and verify the exact helper path and lifecycle hook. |
Bundle invalid after postConvert() | Resource/reference enrichment broke the Bundle | Inspect the generated Bundle locally and validate resource/reference changes before delivery. |
| Script change not activated Commercial | Hot-reload generation failed compilation or initialization | Inspect hot-reload logs. The previous valid generation remains active when the replacement fails. |
Semantic rules
| Problem | Likely cause | Action |
|---|---|---|
| Rule does not load | Groovy/DSL compilation error or missing required metadata | Verify imports plus severity, title, description, failureMessage, and validate. |
| Duplicate rule ID | Two loaded rules use the same stable identifier | Assign a unique rule ID and reload the rule set. |
| Rule never runs | appliesTo(...) does not match the incoming workflow | Compare the rule scope with messageCode and triggerEvent. |
| Global rule runs unexpectedly | appliesTo(...) was omitted | Add explicit scopes when the requirement is not universal. |
| ERROR rule did not reject | The rule never added an issue or the scope did not match | Verify ERROR severity and confirm that issues.add(...) executes. |
| Edited rule not activated Commercial | New generation failed compilation/validation | Inspect reload diagnostics. FireSonic keeps the previous valid rule generation active. |
FHIR Client
| Problem | Action |
|---|---|
| Identifier lookup returns no resource | Verify the identifier system/value and confirm the expected resource exists on the configured FHIR server. |
| Search returns unexpected resources | Check the resource type, search parameters, coding systems, and query values. |
| Search stops after the first page | Use searchBundle(...), inspect the Bundle next link, and continue with searchByUrl(nextUrl). |
| Terminology translation fails | Verify the terminology endpoint, source/target code systems, authentication, and outbound TLS trust. |
| Direct HAPI operation behaves differently | Remember that original() exposes the underlying HAPI generic client and bypasses SDK wrapper behavior. |
HTTP client
Response vs exception
HTTP 4xx/5xx responses are completed HTTP exchanges and are returned as ScriptHttpResponse. Connectivity, timeout, TLS, serialization, and response-read failures raise ScriptHttpException.
| Problem | Action |
|---|---|
| Client cannot be created | Verify baseUrl, authentication configuration, credentials, timeouts, and response-size limits. |
| HTTP 4xx | Inspect the response body/status; this normally indicates a request, authentication, authorization, or business-validation problem. |
| HTTP 5xx | Inspect the response and decide explicitly whether the operation is safe to retry. |
ScriptHttpException | Check connectivity, request timeout, TLS trust, payload serialization, and response reading. |
| Retry helper does not retry an HTTP response | Retry helpers do not decide which HTTP status is retryable. Inspect the response and throw only for the statuses/operations you intentionally retry. |
Async callback receives error | A transport/timeout/read failure occurred. The HTTP response is expected to be unavailable for that failed exchange. |
Caching
| Problem | Action |
|---|---|
| Reference data is stale | Review the TTL/refresh interval and verify that the refreshing-cache loader still succeeds. |
| Cached value disappears unexpectedly | Check the configured TTL and whether the entry was evicted by the maximum-size limit. |
| Cache is recreated for every message | Create reusable caches during onStartup() and keep them on the script generation. |
| Refreshing cache repeatedly fails | Debug the loader's FHIR/HTTP dependency and confirm the old/last-good reference value behavior expected by the project. |
Local SDK and debugging
| Problem | Action |
|---|---|
No Bundle appears under output/ | Verify the input message was processed, the configured sdk.output.mode, and any filter/rejection result. |
| HL7 test file is not picked up | Confirm the input path/file name and that the SDK launcher is using the expected working directory. |
| Bundle generated but not sent to development FHIR server | Verify sdk.output.mode=fhirserver, FHIR URL, authentication, network reachability, and TLS trust. |
| Breakpoint is never hit | Confirm the input actually reaches that lifecycle hook or workflow branch and that the IDE is debugging the expected launcher/process. |
| Behavior differs from test to production | Compare script/rule versions, properties, environment variables, external endpoints, and active generations. |
Useful diagnostics
- Use Testing & Debugging to reproduce the failure under IntelliJ IDEA or Eclipse.
- Inspect the raw HL7 input and generated
output/bundle.json. - Use focused Spock/JUnit tests to reduce the failure to one hook, workflow, or semantic rule.
- Check FireSonic startup/hot-reload logs for script and rule generation failures.
- Use the Platform Administration Console for runtime message diagnostics after deployment.
- Consult the focused FHIR Client, HTTP Client, Caching, and Semantic Rules articles for API-specific behavior.
Make the fix permanent
After correcting an integration defect, add a regression test using the HL7/FHIR case that exposed it. This prevents the same edge case from reappearing in a later script or rule generation.