API Reference

Your code class inherits from BaseCustomFunction. The following sections describe all the properties and methods available to you.

Lifecycle Hooks

Override these methods to hook into the execution lifecycle. All are optional.

Method	Thread	Description

Method	Thread	Description
`OnStart()`	UI	Called once before the first message. Initialize objects, prompt for user input.
`Run()`	Background	Called once per message when F5 is pressed.
`RunOnce()`	Background	Called once for the selected message when F10 is pressed.
`OnFinish()`	UI	Called once after all messages are processed. Cleanup, summary output.
`OnError(Exception ex)`	UI	Called if an unhandled exception occurs during message processing.
`OnUserInterfaceSetup(UserInterfaceElements)`	UI	Customize toolbar buttons before execution begins.

Message Access

Member	Type	Description

Member	Type	Description
`Message`	`IMessageData`	The raw message data for the current message. `Message.Data` returns the raw HL7 string.
`HL7Message`	`HL7Message`	The parsed HL7 message (lazy; same as calling `GetParsedMessage()`).
`GetParsedMessage()`	`HL7Message`	Returns a parsed `HL7Message` for the current message. You can navigate and modify fields on this object.
`MessageCollection`	`MessageCollection`	The message collection from the active tab.
`MessageIndex`	`int`	The zero-based index of the current message within the collection.
`MessageCollections`	`List<MessageCollectionInfo>`	All message collections currently loaded in HL7Spy (all open tabs).

Saving Output

Use SaveMessage() to collect messages into named output collections. After execution, each collection opens as a new tab in HL7Spy.

Method	Description

Method	Description
`SaveMessage(HL7Message message, string collectionName)`	Save a parsed message to the named collection.
`SaveMessage(string message, string collectionName)`	Save a raw HL7 string to the named collection.
`SaveMessage(IMessageData message, string collectionName)`	Save a message data object to the named collection.
`SaveMessage(IEnumerable<IMessageData> messages, string collectionName)`	Save multiple messages at once to the named collection.

Property	Type	Description

Property	Type	Description
`OutputCollections`	`IDictionary<string, MessageCollection>`	All output collections created during execution.
`SortPath`	`HL7Path`	Set this to an HL7 path to sort each output collection by that field. Leave `null` (the default) for no sorting.

Logging

Log entries appear in the Events tab. Double-clicking an event navigates to the associated message.

Method	Description

Method	Description
`Log(Severity severity, string message)`	Log a message with the given severity.
`Log(Severity severity, HL7Node node, string message)`	Log a message associated with a specific HL7 node.
`Log(Severity severity, HL7Path path, string message)`	Log a message associated with a specific HL7 path.

Severity levels: Informational, Warning, Error.

Property	Type	Description

Property	Type	Description
`HasErrors`	`bool`	Returns `true` if any log entry has severity `Error`.
`LogEvents`	`List<ErrorInfo>`	The full list of log entries for the current execution.
`LastError`	`Exception`	The most recent exception that occurred during a lifecycle hook.

Assertions

The Assert property provides validation helpers. Each failed assertion logs an Error to the Events tab. This is useful for building message validation functions.

Method	Description

Method	Description
`Assert.IsTrue(bool condition, string message, params object[] args)`	Log an error if `condition` is false.
`Assert.IsFalse(bool condition, string message, params object[] args)`	Log an error if `condition` is true.
`Assert.Equal(HL7Node node, string expected)`	Log an error if the node value does not equal `expected`.
`Assert.NotEqual(HL7Node node, string text)`	Log an error if the node value equals `text`.
`Assert.Empty(HL7Node node)`	Log an error if the node is not empty.
`Assert.NotEmpty(HL7Node node)`	Log an error if the node is empty.
`Assert.IsNumber(HL7Node node)`	Log an error if the node value is not a valid number.
`Assert.OneOf(HL7Node node, params string[] validValues)`	Log an error if the node value is not in the allowed list.
`Assert.OneOf(HL7Node node, IEnumerable<string> validValues)`	Log an error if the node value is not in the allowed list (enumerable overload).
`Assert.OneOf(HL7Path path, string previousValue, string proposedValue, IEnumerable<string> allowedTransitions)`	Validate state transitions. Transition format: `"AAA->BBB,CCC,DDD"` meaning AAA can transition to BBB, CCC, or DDD.
`Assert.ValidTimestamp(HL7ValueNode node, string pattern)`	Log an error if the value is not a valid timestamp matching `pattern`.
`Assert.MaximumLength(HL7ValueNode node, int maxLength)`	Log an error if the field value exceeds `maxLength` characters.
`Assert.MaximumLength(HL7Node node, int maxLength)`	Log an error if the node string exceeds `maxLength` characters.
`Assert.FieldRepetitionCount<T>(FieldNodeList<T> list, int expected)`	Log an error if the field repetition count does not match `expected`.
`Assert.ValidSegmentOrder(HL7Message message, string expectedOrder)`	Log an error if the segment order does not match the expected regex pattern.

Translations

Translations let you define field-level transformations and apply them in bulk.

Method	Description

Method	Description
`AddTranslation(ITranslator translator)`	Register a custom translator.
`AddTranslation(Predicate<HL7Message> when, Action<HL7Message> execute)`	Register a conditional translation: `execute` runs only when the `when` predicate returns true.
`PerformTranslations(HL7Message message)`	Apply all registered translations to the message.

Anonymization

The Anonymizer class tracks replacement values by a key (typically a patient identifier like PID-3). This ensures consistent anonymization across all messages for the same patient.

Method	Description

Method	Description
`GetAnonymizer(string key)`	Get or create an `Anonymizer` instance for the given key. The key is typically a patient identifier.
`GetDataGenerator(string key)`	Get a `DataGenerator` for generating realistic replacement data. The built-in generator is `"USA"`.

Key Anonymizer methods:

Method	Description

Method	Description
`Replace(string initialValue, string replacementValue)`	Register a text replacement. Returns `true` if this is the first time the value was registered.
`Replace(HL7Node node, string replacementValue, bool includeInFreeTextReplacement)`	Replace the value of an HL7 node and optionally include it in free-text search-and-replace.
`Replace(DTM dateTime, string replacementValue, bool includeInFreeTextReplacement)`	Replace a date/time value.
`UpdateDateTime(HL7Node dateTime, TimeSpan delta, bool includeInFreeTextReplacement)`	Shift a date/time value by the given delta.
`ReplaceFullText(string message, params string[] dateFormats)`	Perform a bulk search-and-replace on the full message text using all registered replacements.
`Contains(HL7Node node)`	Check if a replacement has already been registered for this node.
`Get(HL7Node node)`	Retrieve the `ReplacementItem` for a given node.

Progress and Cancellation

Member	Description

Member	Description
`UpdateStatus(string message, int percent)`	Update the status bar with a message and percentage (0–100).
`UpdateStatus(string message, int index, int count)`	Update the status bar with a message and progress calculated from `index` / `count`.
`Cancel`	Set to `true` to stop processing after the current message. Also set automatically when the user clicks Stop.

UI Thread Access

Because Run() and RunOnce() execute on a background thread, you must marshal any UI operations (such as showing a dialog) to the UI thread.

Method	Description

Method	Description
`RunInMainThread(bool synchronous, Action method)`	Execute `method` on the UI thread. If `synchronous` is `true`, the call blocks until the action completes.

Embedded Resources

Method	Description

Method	Description
`GetEmbeddedResource(string resourceName)`	Returns a `Stream` for the named embedded resource. Tries an exact name match first, then falls back to case-insensitive matching.
`ReadEmbeddedResource(string resourceName)`	Returns the full text content of the named embedded resource as a `string`.

Debugging

Method	Description

Method	Description
`Break()`	Trigger a debugger break. If a debugger is attached, it breaks immediately. Otherwise, it launches the debugger attach dialog.

State Properties

Property	Type	Description

Property	Type	Description
`RunTypeRequested`	`RunType`	The execution mode: `CompileOnly`, `Run`, `RunOnce`, `Next`, or `Previous`.
`HasErrors`	`bool`	`true` if any log event has severity `Error`.
`LogEvents`	`List<ErrorInfo>`	All log entries for the current execution.
`LastError`	`Exception`	The most recent exception from a lifecycle hook.