The events for which scripts or COM implementations may be invoked

Classes

BaseBase class for events; never actually passed to a program

ConvertTextCalled by the File Interface when it needs to convert a line of ascii text into a message

BuildTextCalled by a File Interface when it has an HL7 Message it needs to convert to ascii text.

The script has the option to populate the RawLine variable, or to fill the fields list, in which case RawLine will be ignored

ConvertXmlCalled by the File Interface when it needs to convert an XML File into a message.

The message is empty, and needs to be filled out (no MSH)

The document is

BuildXmlCalled by a File Interface when it has an HL7 Message it needs to convert to an XML File

The script can specify an output character encoding (defaults to UTF-8), and must populate the XML Dom (MsXml Dom)

ReceiveSmsThis event is called when an incoming sms message is received. The event will keep being called until the event call doesn't return an error This event must take <15 seconds to execut

ValidateMessageThis event is called whenever an interface is configured to perform script validation of messages. The script should set the Error property of the event if there is a problem with the message

ValidationDocumentThis event is called whenever a CDA interface is configured to perform script validation of documents. The script should set the Error property of the event if there is a problem with the document

UserInitiatedThis event is called manually by a user through the web interface. It may be called to simply execute, or it may be called to execute against an interface, a message, or a document. You can use the Kind Property to determine which it is being run against.

KernelStartThis event is called when the kernel has finised loading and immediately before the kernel starts. This event will not be called if "no interfaces start automatically" is selected in the HL7Connect Manager, to allow the administrator to successfully start HL7Connect to change a bad startup script

KernelStopThis event is called after all interfaces have stopped or been terminated, but before the internal modules such as the database layer are shutdown

NotificationEventThis event is called when a notification is sent to a script notification handler

RASBaseBase event class for RAS related events

RASConnectCalled when a RAS connection is established. Not implemented yet

RASDisconnectCalled when a RAS connection is disconnected/lost. Not implemented yet

CheckMessageCalled by an incoming scripted message interface basis. If the script determines that a message is to be generated, then it should create one (using Kernel.CreateHL7Message or one of it's variants) and send it using the Event's SendMessage method

The script is called under two different circumstances (as configured). Either it is called on a regular schedule, or it is called when there are items in the virtual queue to be processed. If the event is called because there is a message or document in a virtual queue, then one of the IncomingMessage, IncomingDocument or IncomingDicom properties will be non-null, and the script must set IncomingHandled to true - or else the same item will be processed repeatedly

Note that this is the one place in HL7Connect where documents, messages and DICOM Images can mix - this event requires an outgoing message, but one of documents, messages or images will come in, depending on the configuration of the interface

KScript: the generated content is sent to the kernel as a v2.xml message (One message per execution). IncomingHandled is set to true if the script executes and the message is accepted. Note: KScript is not configured to work usefully with incoming dicom messages at this time.

CheckDocumentCalled by an incoming scripted message interface basis. If the script determines that a message is to be generated, then it should create one and send it using the SendMessage method

The script is called under two different circumstances (as configured). Either it is called on a regular schedule, or it is called when there are items in the virtual queue to be processed. If the event is called because there is a message or document in a virtual queue, then either the IncomingMessage or IncomingDocument properties will be non-null, and the script must set IncomingHandled to true - or else the same message will be processed repeatedly

Note that this is the one place in HL7Connect where documents and messages can mix - this event requires an outgoing message, but either documents or messages will come in, depending on the configuration of the interface

KScript: the generated content is sent to the kernel as a document (One document per execution). IncomingHandled is set to true if the script executes and the message is accepted.

CheckDicomMessageCalled by an incoming scripted dicom message interface basis. If the script determines that a message is to be generated, then it should create one and send it using the SendMessage method

The script is called under two different circumstances (as configured). Either it is called on a regular schedule, or it is called when there are items in the virtual queue to be processed. If the event is called because there is a message or document in a virtual queue, then either the IncomingMessage, IncomingDocument oir IncomingDicomMessage properties will be non-null, and the script must set IncomingHandled to true - or else the same message will be processed repeatedly

Note that this is the one place in HL7Connect where documents, hl7 messages and Dicom message can mix - this event produces an outgoing dicom message, but either documents or hl7 or dicom messages will come in, depending on the configuration of the interface

SendScriptMessageCalled by an outgoing scripted message interface when a message is to be sent. The script must populate a reply message, and set the return status.

SendScriptDocumentCalled by an outgoing scripted Document interface when a Document is to be sent. The script must populate the response (which is already created)

SendScriptDicomMessageCalled by an outgoing scripted Document interface when a Dicom Message is to be sent. The script must populate the response (which is already created)

ConversionParameterParameter for a conversion event - either for an incoming scripted interface (bound to a virtual queue), or as invoked through the web interface.

Only one of the 4 types of parameters will/can have a value.

ConversionConversion event - either for an incoming scripted interface (bound to a virtual queue), or as invoked through the web interface.

InterfaceBaseBase class for interface related events

InterfaceStartThis event is called when an interface starts.

Note that there is 2 levels of start. One, the kernel starts the interface (by user prompting, for instance). Then the actual transport layer is allowed to start. This event will only be called when the actual transport layer indicates to the kernel that it has successfully started.

Some carriers (file, http, email) will do this immediately. The LLP carrier will call this event whenever the remote system actually connects. In the context of the LLP interface this could better be called "OnInterfaceConnect"

InterfaceStopThis event is called when the interface stops. As with the OnInterfaceStart event, this is called when the transport layer stops, not when the user stops the interface (although these often happen at the same time). Again, with the LLP carrier, this will happen when the remote system disconnects

ReceiveMessageThis event is called when a message is received from an interface and the message has passed the sequence numbering and HL7 Validation checks. It exists to allow the user to impose custom validation checks, do message translation, and send the messages to interfaces or virtual queues.

The event handler can do anything it wants with the Message but it must leave it parsable and with the compulsory headers in the MSH populated. If the interface wishes to reject the message, it should set ErrorMessage and optionally ErrorCode

The message is logged prior to this event.

XSLT: the input is the original message, the output replaces the original message

ReceiveDocumentThis event is called when a Document is received from an interface and the Document has been parsed. It exists to allow the user to impose custom validation checks, do Document modification/translation, and send the Documents to interfaces or virtual queues.

The event handler can do anything it wants with the Document but it must leave it the compulsory CDA headers populated. If the interface wishes to reject the Document, it should set the response accordingly (before the script is executed, the response is "accepted", though the kernel will override this later when it processes the document if the script does not reject it).

The Document is logged prior to this event

XSLT: the input is the document message, the output replaces the original document

ReceiveDicom
  • ** note: DICOM Support is under development. DICOM events and types are already present in the
API for declarative purposes, DICOM is not supported, and the API should be expected to change without notice ***

This event is called when a Dicom Message is received from an interface and the message has been parsed and logged. It exists to allow the user to impose custom validation checks, do Message modification/translation, and send the Messages to interfaces or virtual queues.

The event handler can do anything it wants with the message, though the message generally needs to be valid afterwards

If the script wishes to reject the Message, it should set the Outcome accordingly (before the script is executed, the response is "unknown": the kernel will update this later when it processes the document if the script does not reject it).

The Message is logged prior to this event

XSLT: the input is the document message in XML format, the output replaces the original document

SendMessageThis event is called immediately before a message is sent. If the script chooses, it can build a reply in ReplyMessage and set UseReplyMessage. In this case, the message will not be sent an ReplyMessage will be sent as the response

The script is able to modify the Message as it chooses but it should maintain a valid MSH segment.

The logs are written after this event

Setting UseReplyMessage := true while sequencenumbering is in use can have unexpected consequences. It's best not to do this

Note that when this event is called with a message that is being passed through, the message is not stored (if the incoming interface message processing mode is "Pass-through with store", the message will be stored after the remote system has responded).

XSLT: the input is the message to be sent, the output replaces the message to be sent

SendDocumentThis event is called immediately before a Document is sent. If the script chooses, it can abort further document sending by setting the response to either droAccepted or droRejected.

The script is able to modify the Document as it chooses but it should maintain valid CDA headers. Note that any digital signatures in the document will not be updated automatically

The logs are written after this event

XSLT: the input is the document to be sent, the output replaces the document to be sent

SendDicomMessageThis event is called immediately before a Dicom Message is sent. If the script chooses, it can abort further message sending by setting the Response.Outcome to either droAccepted or droRejected.

The script is able to modify the message as it chooses but it should maintain a valid Dicom message.

The logs are written after this event

XSLT: the input is the message to be sent (in XML format used in the development environment), the output replaces the document to be sent

ReceiveDicomReplyThis event is called after a Dicom Message is sent, and a response has been received.

Before this event is called, the incoming reply is interpreted into the response that summarises the reply. The script can override the interpretation of the DICOM replies, and/or change the values in the one or more messages received from the external destination system

The logs are written after this event

MessageTimeoutThis event is called when a message has been sent and no reply was received. Usually this event is used to report errors and take other actions as desired. Note: You can stop the outgoing interface on which this error has occurred, but it will not actually stop until the script for this event has completed, so don't wait for the interface to stop (Started = false)

If the script chooses, it can build a reply in ReplyMessage and set UseReplyMessage. In this case, HL7connect will treat the ReplyMessage as the reply from the interface. Setting UseReplyMessage := true while sequencenumbering is in use can have unexpected consequences. It's best not to do this

DocumentSentOutcomeThis event is called when a Document has been sent to the transport layer. Either the document is accepted, rejected, or timed out (what is possible depends on the transport layer details)

Usually this event is used to handle errors and take other actions as desired. Note: You can stop the outgoing interface on which this error has occurred, but it will not actually stop until the script for this event has completed, so don't wait for the interface to stop (Started = false)

The response will be pre-populated with the response from the underlying transport layer. The script can override this if it wants,

ReceiveReplyThis event is called when a reply is received. The incoming message can be changed but MSH and MSA must be valid.

XSLT: the input is the reply from the other system, the output replaces the reply for further processing

SendReplyThis event is called once a reply has been generated for a message. The script is allowed full access to the reply message but should leave the MSH and MSA fields populated.

The logs are written after this event

This event is also a chance to queue the incoming message (SourceMessage) for other interfaces, but beware that the event will be called whether or not the message was accepted. (Use SourceMessage.Stored to check)

XSLT: the input is the reply that will be sent, the output replaces the reply

SendDicomReply
  • ** note: DICOM Support is under development. DICOM events and types are already present in the
API for declarative purposes, DICOM is not supported, and the API should be expected to change without notice ***

This event is called when an incoming interface is replying to a Dicom Message. There may be 0 to many response messages. The event will be called even if there is no proposed responses, and even if the message is being rejected.

The script can change the response messages, and also change the outcome. Note that if the outcome is anything other than droAccepted, then the response messages will ignored, and an Abort PDU sent instead.

The outgoing responses are logged subsequent to this event

FhirIncoming
  • ** note: FHIR is a prototype HL7 Specification. The interface details
are subject to change without notice ***

This event is called when receiving a request or sending a response on an incoming FHIR interface.

When receiving an request:

  • the script can manipulate some of the contents of the request
  • if the script sets the HTTPCode, HL7Connect will not process the request further
  • the script can consult the store to see what is stored there
When responding to a request:
  • the script can set any of the response content
Transaction notes:
  • both incoming and outgoing processing occur outside the database transaction where the content is saved to the transaction log (aka message store) and the FHIR storage (if configured)
The order of processing events:
  • actual transport receive
  • log content
  • run script
  • validate incoming
  • either:
  • pass it on to outgoing interface
  • or
  • core database transaction:
  • store request
  • route request
  • process against FHIR store
  • run outgoing script
  • validate outgoing
  • log content
  • send response
ExecuteHL7The event that is called when THL7V2Manager.executeScript is called.

ExecuteCDAThe event that is called when TCDAManager.executeScript is called.

ExecuteKScriptThe event that is called when TCDAManager.executeScript is called.

XdrFhirCalled when an XDS submission must be converted to FHIR Batch


© Kestral Computing P/L 2000 - 2003. HL7Connect v2.00-063 generated on 30-Nov 2015.
Keywords: HL7Connect.Events