Docs/Developer SDK/Lifecycle Hooks

Lifecycle Hooks

Understand exactly where customer code runs in the FireSonic processing pipeline.

The main customer script implements IntegrationScript. FireSonic invokes each hook at a defined point in either the message lifecycle or the script-generation lifecycle.

Message lifecycle

The message lifecycle covers per-message processing. These hooks are invoked for each incoming HL7 message and are the main place for message filtering, HL7 normalization, FHIR enrichment, and semantic validation actions.

shouldProcess(envelope) decides whether the message should continue or be intentionally filtered.
preConvert(envelope) modifies or replaces the parsed HL7 message before core mapping starts.
postConvert(envelope, bundle) enriches or patches the generated FHIR Bundle after core mapping.
postValidation(...) inspects semantic-validation issues after rule evaluation and can perform follow-up actions.

Script-generation lifecycle

The script-generation lifecycle covers initialization and shutdown of the active script generation. These hooks are not executed for every message. They are used for startup validation, one-time resource initialization, version reporting, and cleanup when a script generation is replaced or unloaded.

scriptVersion() reports the active workflow version.
onStartup() validates configuration and initializes generation-wide resources such as caches or managed clients.
onShutdown() releases generation-specific resources when the active generation is unloaded.

Hook reference

Hook	Lifecycle	Responsibility	Return
`scriptVersion()`	Generation	Report the active script version.	String
`onStartup()`	Generation activation	Validate configuration and initialize generation-wide resources.	void
`shouldProcess(envelope)`	Per message	Accept the message or intentionally filter it using `FilterResult`.	FilterResult
`preConvert(envelope)`	Per message	Normalize or replace the parsed HL7 message before built-in mapping.	MessageEnvelope
`postConvert(envelope,bundle)`	Per message	Patch, enrich, or apply organization-specific workflow logic to the generated FHIR Bundle.	Bundle
`postValidation(...)`	Per message	Inspect semantic validation results and react before delivery.	void
`onShutdown()`	Generation unload	Release resources owned by the active script generation.	void

Choosing the right hook

Need	Hook
Accept or intentionally filter an incoming message	`shouldProcess()`
Normalize HL7 before the core mapper runs	`preConvert()`
Enrich generated FHIR or run customer-specific workflow logic	`postConvert()`
React to INFO, WARNING, or ERROR semantic issues	`postValidation()`
Validate configuration or initialize caches/clients	`onStartup()`
Release generation-wide resources	`onShutdown()`

Message lifecycle

MESSAGE LIFECYCLEplatform core + customer workflow hooks

SDK hookPlatform core

HL7 MessageMessageEnvelope

→

shouldProcess()Accept / filter

→

preConvert()Normalize HL7

→

Core MapperHL7 → FHIR

postConvert()Enrich / workflow

←

Semantic ValidationEvaluate context

←

postValidation()React to issues

←

FHIR DeliveryTransaction Bundle

Script-generation lifecycle

A script generation is loaded as one unit. FireSonic prepares the generation, injects supported services and properties into the main IntegrationScript, invokes onStartup(), and then uses that generation for message processing until it is unloaded.

SCRIPT GENERATIONload · inject · initialize · run · unload

Load generationCompile & prepare

→

InjectServices & properties

→

onStartup()Initialize

→

Active generationProcess messages

→

onShutdown()Release resources

Automatic hot reload Commercial

Commercial FireSonic editions can compile and validate a new script generation and activate it without restarting the FireSonic runtime. Invalid generations do not replace the active generation.