Docs/Developer SDK/API Reference

API Reference

Quick reference for the main FireSonic SDK interfaces and helpers.

This page is a compact lookup for the public FireSonic SDK surface. Follow the linked topic pages for lifecycle behavior, examples, configuration guidance, and recommended usage patterns.

Core scripting

Detailed guide → Lifecycle Hooks

IntegrationScript

Method	Returns	Purpose
`scriptVersion()`	`String`	Report the active script version.
`onStartup()`	`void`	Called once after script construction and dependency injection.
`shouldProcess(MessageEnvelope)`	`FilterResult`	Accept or intentionally filter the current message.
`preConvert(MessageEnvelope)`	`MessageEnvelope`	Normalize or replace the parsed HL7 message before core conversion.
`postConvert(MessageEnvelope, Bundle)`	`Bundle`	Patch or enrich the generated FHIR Bundle after core conversion.
`postValidation(MessageEnvelope, Bundle, SemanticValidationResult)`	`void`	Inspect semantic-validation results before the final delivery decision.
`onShutdown()`	`void`	Called before the current script generation is unloaded.

MessageEnvelope

Property	Meaning	Typical use
`id`	Unique FireSonic message identifier.	Logging and correlation.
`rawHL7`	Original immutable HL7 payload.	Diagnostics and audit.
`messageCode`	MSH-9.1, such as ADT, ORU, or ORM.	Routing and workflow selection.
`triggerEvent`	MSH-9.2, such as A01, A40, or R01.	Workflow selection.
`messageControlId`	MSH-10 message control identifier.	Deduplication and tracing.
`hl7Message`	Parsed mutable HAPI HL7 message.	Read or normalize HL7 before conversion.
`remoteAddress`	Sender network address when available.	Sender diagnostics.
`receivedAt`	Message receive/create timestamp.	Logging and audit.

FilterResult

Method	Returns	Purpose
`FilterResult.accept()`	`FilterResult`	Allow processing to continue.
`FilterResult.reject(reason)`	`FilterResult`	Stop processing with a human-readable reason.
`isAccepted()`	`boolean`	Check whether the message was accepted.
`getReason()`	`String`	Read the rejection reason.

Dependency injection

Detailed guide → Dependency Injection

Annotation	Injected type	Purpose
`@InjectFhir`	`FhirClient`	FHIR searches, Bundle posting, terminology translation, and native HAPI access.
`@InjectCache`	`ScriptCacheFactory`	Create TTL, singleton, and refreshing caches.
`@InjectMetrics`	`ScriptMetrics`	Record extra script-side FHIR operation metrics.
`@InjectSupport`	`ScriptSupport`	Retries, sleep/backoff, and list chunking.
`@InjectHttp`	`ScriptHttpClientFactory`	Create named, thread-safe clients for customer-specific non-FHIR REST integrations.
`@ScriptProperty("key")`	String / boolean / Set / Map / etc.	Inject values from `script.properties`.

FHIR API

Detailed guide → FHIR Client

FhirClient

Method	Returns	Purpose
`original()`	`IGenericClient`	Access the native HAPI FHIR generic client. Bypasses SDK wrapper behavior.
`postBundle(Bundle)`	`Bundle`	Post or deliver a Bundle according to runtime/SDK policy.
`postTransaction(Bundle)`	`Bundle`	Post a FHIR transaction Bundle.
`findPatientByIdentifier(Identifier)`	`Optional<Patient>`	Find a unique Patient by identifier.
`findEncounterByIdentifier(Identifier)`	`Optional<Encounter>`	Find a unique Encounter by identifier.
`search(resourceType, params)`	`List<Resource>`	Return resources from the first search-result page.
`search()`	`FhirSearch`	Create a fluent search builder.
`searchBundle(resourceType, params, count, elements...)`	`Bundle`	Return the raw search Bundle with paging links and metadata.
`searchByReference(...)`	`Bundle`	Run a reference search and return the result Bundle.
`searchByUrl(nextUrl)`	`Bundle`	Continue a paged search using the server-provided next URL.
`translate()`	`FhirTranslate`	Create a fluent terminology translation builder.
`translate(srcSystem, srcCode, tgtSystem)`	`Parameters`	Return the raw ConceptMap `$translate` response.
`translateCode(srcSystem, srcCode, tgtSystem)`	`String`	Return the translated code, or `null` when none is available.

Caching, metrics, and support

Detailed guide → Caching · Detailed guide → Metrics & Support

Cache APIs

Type	Key methods	Purpose
`ExpiringCache<K,V>`	`getIfPresent`, `get`, `put`, `invalidate`, `invalidateAll`, `asMap`	Many keyed values with TTL and optional size bounds.
`SingletonExpiringCache<T>`	`getIfPresent`, `set`, `invalidate`	One temporary value with TTL.
`RefreshingValueCache<T>`	`get`, `load`, `refresh`, `invalidate`, `peek`	Periodically refreshed reference data.
`ScriptCacheFactory`	`createTtlCache`, `createSingletonTtlCache`, `createRefreshingCache`	Create SDK-managed cache instances.

ScriptMetrics

Method	Purpose
`onFhirBundlePosted()`	Record a successful extra FHIR Bundle operation initiated by script logic.
`onFhirRequestFailed()`	Record a failed extra FHIR operation before propagating/handling the failure.

Do not double-count standard delivery

FireSonic already records the normal platform Bundle-delivery path. Use ScriptMetrics only for additional FHIR operations initiated explicitly by script logic.

ScriptSupport

Method	Purpose
`sleepMillis(millis)`	Sleep/backoff helper.
`withRetries(label, delays, action)`	Run an action with retries and return a value.
`runWithRetries(label, delays, action)`	Run a void action with retries.
`chunk(items, size)`	Split a list into chunks.

HL7 API

Detailed guide → Working with HL7

HL7Helper

Method	Purpose
`getSegment(message, name)`	Get the first segment by name.
`hasSegment(message, path)`	Check whether a segment/path exists.
`get(message, path)`	Read a HAPI Terser path.
`set(message, path, value)`	Set a HAPI Terser path.
`clear(message, path)`	Clear a field/segment path.
`clearRepeatedSegments(message, name)`	Clear repeated top-level segments.
`copy(message, from, to)`	Copy an HL7 value.
`safeGet(segment, field, ...)`	Read a field safely.
`getMessageCode(...)` / `getTriggerEvent(...)`	Read MSH-9 message code / trigger event.
`getMessageControlId(...)`	Read MSH-10.
`readTS(...)` / `getDTM(...)` / `readDT(...)`	Parse common HL7 date/time values.

Semantic Validation API

Detailed guide → Semantic Rules

SemanticRulesDsl / SemanticRuleBuilder

Element	Purpose
`rule("...")`	Declare a rule with a stable identifier.
`severity`	Set INFO, WARNING, or ERROR.
`category`	Group related rules by business domain.
`title`	Set the human-readable rule name.
`description`	Explain the validation requirement.
`failureMessage`	Set the default reported message.
`appliesTo(...)`	Restrict the rule to one or more HL7 scopes. If omitted, the rule is global.
`validate { ctx, issues -> ... }`	Define validation logic for the generated FHIR Bundle.

SemanticRuleContext

Method	Purpose
`bundle()`	Return the generated FHIR Bundle.
`envelope()`	Return the current MessageEnvelope.
`messageCode()`	Return the HL7 message type.
`triggerEvent()`	Return the HL7 trigger event.
`resources(Class)`	Return all resources of the requested FHIR type.
`each(...)`	Iterate over matching resources.
`exists(...)`	Return true when any resource satisfies a predicate.
`findAll(...)`	Return all resources satisfying a predicate.
`count(Class)`	Count generated resources of the specified type.
`resourcesByFhirType(String)`	Return resources by FHIR resource type name.

SemanticIssueCollector

Method	Purpose
`add(rule)`	Report a validation issue not associated with a specific FHIR resource.
`add(rule, resource)`	Report an issue for the supplied FHIR resource.
`add(rule, resource, message)`	Report an issue with a custom message.
`issues()`	Return the immutable list of collected issues.

SemanticValidationResult / SemanticIssue

Type / Method	Purpose
`SemanticValidationResult.issues()`	Return all collected semantic issues.
`isEmpty()`	Check whether validation produced no issues.
`hasErrors()` / `hasWarnings()` / `hasInfo()`	Check whether a severity is present.
`errors()` / `warnings()` / `info()`	Return issues filtered by severity.
`bySeverity(...)`	Return issues for a requested severity.
`byRuleId()`	Group issues by rule identifier.
`summary()`	Return a compact summary such as `errors=1, warnings=2, info=0`.
`diagnostics()`	Build human-readable diagnostics for logs, notifications, or administrative views.
`SemanticIssue`	Contains `ruleId`, `severity`, `message`, optional `resourceType`, and optional `resourceId`.

HTTP API

Detailed guide → HTTP Client

ScriptHttpClientFactory

Method	Returns	Purpose
`create(String name, Map<String, ?> properties)`	`ScriptHttpClient`	Create a named client from an injected property map.
`create(String name, ScriptHttpClientConfig config)`	`ScriptHttpClient`	Create a named client from an existing immutable configuration.
`newConfigBuilder()`	`ScriptHttpClientConfigBuilder`	Create a mutable configuration builder.

ScriptHttpClient

Method	Returns	Purpose
`get(String path)`	`ScriptHttpResponse`	Send a synchronous GET request.
`get(String path, Map<String, ?> queryParameters)`	`ScriptHttpResponse`	Send a synchronous GET request with URL-encoded query parameters.
`postJson(String path, Object payload)`	`ScriptHttpResponse`	Serialize the payload as JSON and send a synchronous POST request.
`postJsonAsync(String path, Object payload)`	`void`	Send a best-effort asynchronous JSON POST request.
`postJsonAsync(String path, Object payload, callback)`	`void`	Send an asynchronous JSON POST and invoke a completion callback.

ScriptHttpResponse

Method	Returns	Purpose
`getStatusCode()`	`int`	Return the HTTP status code.
`getBody()`	`String`	Return the UTF-8 response body.
`getHeaders()`	read-only headers	Return response headers.
`isSuccessful()`	`boolean`	Return true for HTTP status codes 200–299.

ScriptHttpClientConfigBuilder

Method	Purpose
`from(Map<String, ?> properties)`	Create and validate configuration from a property map.
`setBaseUrl(String)`	Set the target REST service base URL.
`setAuthType(ScriptHttpAuthType)`	Set NONE, BASIC, or BEARER authentication.
`setUsername(String)`	Set the Basic authentication username.
`setPassword(String)`	Set the Basic authentication password.
`setBearerToken(String)`	Set the Bearer token.
`setConnectTimeoutMs(int)`	Set the connection timeout.
`setRequestTimeoutMs(int)`	Set the complete request timeout.
`setMaxResponseBytes(long)`	Set the maximum accepted response size.
`build()`	Validate and create an immutable HTTP-client configuration.

Reference scope

This page lists the SDK APIs most commonly used by integration scripts and semantic rules. Use the detailed guide pages for lifecycle semantics, thread-safety requirements, runtime behavior, and complete usage examples.