Skip to content

Destination connectors ​

A channel has at least one destination and may have many. Each has its own filter, transformer, and connector, and it does not have to send anything: its filter can stop the message, and a JavaScript Writer may only run a script. Eleven types ship with the engine.

ConnectorSends data by
Channel WriterHanding the message to another channel on the same engine
Database WriterRunning a statement against a JDBC database
DICOM SenderOpening a DICOM association to a remote AE
Document WriterRendering a PDF or RTF
File WriterWriting to a local directory, FTP, SFTP, S3, SMB, or WebDAV
HTTP SenderMaking an HTTP request
JavaScript WriterRunning a script
JMS SenderPublishing to a JMS queue or topic
SMTP SenderSending email
TCP SenderOpening a TCP connection, MLLP included
Web Service SenderCalling a SOAP operation

Settings outside the connector's own fields ​

One block sits above the connector's own configuration, and every destination type has it. It controls the queue and what happens when a send fails. Queue Messages, Validate Response and Reattach Attachments are on the panel itself; the rest open from the wrench button beside Advanced Queue Settings. The queue-only settings are greyed out while Queue Messages is Never, and the retry settings stay available for Never and On Failure.

SettingDefaultDescription
Queue MessagesNeverNever, On Failure, or Always. Decides whether a failed send, or every send, goes to this destination's queue. Not every failure queues: a refused connection does, but a JavaScript Writer script that throws gives ERROR and is not queued; return QUEUED from the script to queue the message. On Failure sends directly only while the queue is empty; otherwise a new message joins the queue. See Queueing
Retry Count Before Queue/Error0Retries after the first failed attempt before the message queues or errors, so 0 means one attempt. Enabled only when Queue Messages is Never or On Failure
Retry Interval (ms)10000Wait between those attempts. Enabled when the queue is on or Retry Count Before Queue/Error is above 0
Rotate QueueNoMove a failing message to the back of the queue instead of blocking behind it. Queue on only
Queue Threads1Threads draining the queue. More than one drains it in parallel, so order is no longer guaranteed except within a Thread Assignment Variable group. Queue on only
Thread Assignment VariableGroups messages onto the same queue thread, so ordering is kept within a group when Rotate Queue is No. Enabled only when Queue Threads is above 1
Queue Buffer SizeDefault Queue Buffer Size from SettingsMessages held in memory before falling back to the database. The Administrator fills in the Settings value for a new destination and refuses to save a value of 0 or less. Queue on only
Include Filter/TransformerNoRe-run the destination's filter and transformer on each queue retry. Enabled only when the queue is on and Regenerate Template is Yes
Regenerate TemplateNoReplace the variables in the template and the other connector settings again on each retry, picking up map changes. Queue on only
Validate ResponseNoRun the response validator of the response transformer's inbound data type on the reply. This works only when that data type has a Response Validation section; a failed validation marks the message queued or errored. For HL7 v2, an error or rejected ACK, or a control ID that does not match, gives ERROR; a blank reply, or one that is not a valid ACK, gives QUEUED, which becomes ERROR when the queue is off. Available on the Channel Writer, Database Writer, HTTP Sender, JavaScript Writer, TCP Sender, and Web Service Sender, and greyed out on the DICOM Sender, Document Writer, File Writer, JMS Sender, and SMTP Sender. The TCP Sender is the only type that ships with this on
Reattach AttachmentsYesRe-insert attachment content before sending. No effect on the JMS Sender or the JavaScript Writer

The queue is off by default on every destination.

Field values are run through Velocity replacement before the send, so a directory, a filename, a URL, a subject line, or a header can carry data from the message. The JavaScript Writer is the exception: it has no templated fields.

Channel Writer ​

Hands the message to another channel on the same engine. A Channel Reader is the usual receiver, but the target channel's source does not have to be one: a channel with an HTTP Listener source receives the message and runs its destinations.

The Channel Writer settings on the channel editor's Destinations tab

SettingDefaultDescription
Channel IdnoneThe receiving channel
Template${message.encodedData}What the receiving channel gets as its raw message
Message MetadataMap variables to pass along. They arrive in the receiving channel's source map, not its channel map

Database Writer ​

Runs an insert, update, or delete against a database. Write it in SQL or build it in JavaScript.

The Database Writer settings on the channel editor's Destinations tab

SettingDefaultDescription
DriverPlease Select OneJDBC driver. Required, JavaScript mode included. See drivers and URL templates
URLJDBC connection URL
Username / PasswordDatabase credentials
Use JavaScriptNoBuild the statement in JavaScript instead of SQL
SQL / JavaScriptThe statement. The Generate buttons above it build a starting statement, or in JavaScript mode a connection block, from the settings above. In SQL mode each ${} is bound as a parameter rather than pasted in as text; see Where Velocity is used

JavaScript mode

As on the Database Reader, the connector opens no database connection in this mode and the script opens its own. Driver is required either way. While it reads Please Select One the Administrator saves the channel disabled and shows an error dialog listing the problem. URL is validated only when Use JavaScript is No, and the credentials are never validated. Generate: Connection, enabled only in this mode, pastes all four values, the password in plain text among them, into a connection block at the top of the script, and Generate: Insert inserts a dbConn.executeUpdate(...) line at the caret for the table you pick. Those values are string literals in the script from then on. Editing the fields does not change them, and the connector's own copies are never read at runtime.

The generated block opens a connection and closes it in a finally, with nothing in between until you add the statements yourself. What the script returns decides the response: nothing at all is a SENT with Database write success, a Response is used as-is, a Status sets only the status, and anything else becomes the response data.

Clicking the Use JavaScript radio rewrites the script field: Yes replaces its contents with the generated block, No empties it. Reopening a saved channel does not.

DICOM Sender ​

Opens an association to a remote application entity and sends the message as DICOM.

The DICOM Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
Remote Host127.0.0.1Destination host
Remote Port104Destination port
Remote Application EntityAE title being called. Blank calls DCMRCV
Local Host / Local Port / Local Application EntityLocal Application Entity is the AE title the connector calls with. In 4.7.0 Local Host and Local Port do not change the connection's source address or port: set to 127.0.0.2 and 7795, or either one alone, the connection still comes from 127.0.0.1 on an ephemeral port
Template${DICOMMESSAGE}Content sent
User Name / Pass CodeCredentials for user identity negotiation. Pass Code is effective only with a User Name
Request Positive User Identity ResponseNoRequire the remote AE to confirm the identity. Effective only with a User Name
Request Storage CommitmentNoAsk for a storage commitment after the send
PriorityMediumHigh, Medium, or Low. Sets the priority field of the C-STORE request. In 4.7.0 Medium sends 0, Low sends 1 and High sends 2, while the DICOM standard defines 0 as medium, 1 as high and 2 as low, so High and Low are swapped on the wire
Max Async operations0Maximum outstanding operations invoked asynchronously. Unlimited by default
Pack PDVNoPack command and data PDVs into one P-DATA-TF PDU
Default Presentation SyntaxNoOffer the default transfer syntax in its own presentation context
TCP DelayYesLeave Nagle's algorithm on

Timing

SettingDefaultDescription
TCP Connection Timeout (ms)0Connect timeout. 0 waits indefinitely
Timeout A-ASSOCIATE-AC (ms)5000Wait for the association to be accepted
DIMSE-RSP timeout (s)60Wait for a DIMSE response
DIMSE-RSP interval period (s)10Interval for the association reaper
A-RELEASE-RP timeout (s)5Has no effect in 4.7.0: the value is passed to the DICOM library, which never reads it
Socket Close Delay After A-ABORT (ms)50Delay before closing after an abort
Shutdown delay (ms)1000Delay before the listening socket is closed

Buffers

SettingDefaultDescription
P-DATA-TF PDUs max length sent (KB)16Maximum PDU length sent
P-DATA-TF PDUs max length received (KB)16Maximum PDU length accepted
Send Socket Buffer Size (KB)00 leaves the OS default
Receive Socket Buffer Size (KB)00 leaves the OS default
Transcoder Buffer Size (KB)1Buffer used when transcoding

TLS

SettingDefaultDescription
TLSNo TLSNo TLS, 3DES, AES, or Without. No TLS greys out every other setting in this table. With the JDK's default security settings on Java 17 and 21, 3DES, AES and Without fail; see the box under DICOM Listener
Client Authentication TLSYesEnable client authentication for TLS
Accept ssl v2 TLS handshakeYesYes removes the SSLv2Hello handshake from the connector's protocols, so the label reads opposite to its effect
Keystore / Keystore Password / Key PasswordIdentity presented to the remote AE
Trust Store / Trust Store PasswordCertificates this connector will trust

With TLS on, fill in Keystore and Trust Store: left blank, the sender falls back to the DICOM library's sample paths, resource:tls/test_sys_1.p12 and resource:tls/mesa_certs.jks, which the 4.7.0 release does not ship.

Document Writer ​

Renders the message as a document and writes it out.

The Document Writer settings on the channel editor's Destinations tab

SettingDefaultDescription
OutputFileFile, Attachment, or Both. Attachment and Both attach the rendered document to the message, and the destination's response contains the attachment Id. Attachment greys out Directory, File Name, and Test Write
DirectoryWhere the file goes. Test Write checks that the directory can be written
File NameName of the file written
Document TypePDFPDF or RTF
EncryptedNoEncrypt the PDF. RTF greys this out
PasswordPassword on the encrypted PDF. Enabled, and required, only when Encrypted is Yes
Page Size8.5 x 11 inchesWidth, height, and unit, with a drop-down of standard page sizes beside the unit. Width and height must be above 0, and PDFs enforce a minimum of 26 mm
HTML TemplateThe HTML rendered into the document

File Writer ​

Writes the message to a file. Method is the first choice: it decides how the location is addressed, whether credentials apply, which connection fields are available, and which File Exists options you get.

The File Writer settings on the channel editor's Destinations tab

Method ​

MethodLocationCredentialsAlso enables
fileDirectory, a single fieldnonenothing
ftpftp:// host, then a pathAnonymous, or a username and passwordPassive Mode, Validate Connection, Timeout, Advanced Options
sftpsftp:// host, then a pathA username always, and a password unless the Advanced Options use a different authenticationTimeout, Advanced Options
Amazon S3S3 Bucket, then a pathAnonymous, or an AWS Access Key ID and Secret Access Key. Neither is required when the Advanced Options use the default credential provider chainTimeout, Advanced Options
smbsmb:// host, then a pathalways requiredTimeout, Advanced Options
webdavhttp:// or https:// host, then a pathAnonymous, or a username and passwordSecure Mode

Two methods restrict what else you can choose. Append is not available under S3 or WebDAV, so File Exists offers only Overwrite and Error, and selecting either method switches an existing Append setting to Overwrite. S3 additionally forces Create Temp File to No. Under S3 the credential fields are relabelled AWS Access Key ID and AWS Secret Access Key.

Broken in 4.7.0

A File Writer set to webdav writes nothing: the message is left at RECEIVED, and the server log shows NoClassDefFoundError: org/jdom/input/DOMBuilder. Fix proposed in engine PR #546, not yet in a release.

On Windows, Directory under file can be a UNC path such as \\server\share\outbound. The Administrator stores it with forward slashes, //server/share/outbound, which Windows still reads as the same share. The account the OIE service runs as needs access to the share. On Linux, mount the share, in /etc/fstab or with an automounter, and point the file method at the mount point.

SettingDefaultDescription
Timeout (ms)10000How long to wait when connecting
Keep Connection OpenYesKeep the connection open after writing
Max Idle Time (ms)0Idle time before a kept connection is closed. 0 is infinite. Enabled only when Keep Connection Open is Yes
Secure ModeYesWebDAV over HTTPS
Passive ModeYesFTP passive transfers
Validate ConnectionYesTest the connection before writing

Per-protocol extras sit behind Advanced Options; see file protocol advanced settings.

Writing the file ​

SettingDefaultDescription
File NameName of the file written
File ExistsAppendAppend, Overwrite, or Error when the file is already there. Append is unavailable under S3 and WebDAV
Create Temp FileNoWrite under a temporary name and rename on completion. Not available under S3, and greyed out and set to No whenever File Exists is Append
File TypeTextText or Binary. Binary base64 decodes the content before writing
EncodingDefaultCharacter set, Text only
TemplateContent written

HTTP Sender ​

Makes an HTTP request and treats the reply as the response.

The HTTP Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
URLAddress the request goes to
MethodPOSTPOST, GET, PUT, DELETE, or PATCH
ContentRequest body. Enabled only for POST, PUT, and PATCH, and greyed out when Content Type is application/x-www-form-urlencoded
Content Typetext/plainValue of the request's Content-Type header. Enabled only for POST, PUT, and PATCH. With application/x-www-form-urlencoded, the query parameters are encoded into the request body
Data TypeTextText or Binary. Binary base64 decodes the content before sending. Enabled only for POST, PUT, and PATCH, and greyed out with application/x-www-form-urlencoded
Charset EncodingUTF-8Character set for the body. Enabled only for POST, PUT, and PATCH, with Data Type Text
MultipartNoSend the request as multipart. Enabled only for POST, and greyed out and set to No with application/x-www-form-urlencoded
Send Timeout (ms)30000Connect and socket timeout
HeadersRequest headers. Use Map takes them from a map variable instead of the table
Query ParametersQuery string parameters, same Use Map option
AuthenticationNoSend credentials with the request
Authentication TypeBasicBasic or Digest. The Preemptive checkbox beside them is off by default and sends the authorization header with the initial request, instead of only when the server asks. With Digest, the engine answers the server's 401 challenge with a second request that carries the computed Authorization header, so the Headers table needs no Authorization entry. With Preemptive on, the engine reads an Authorization: Digest header from the Headers table, takes its parameters (such as realm, nonce, algorithm and qop), and sends the computed header on the first request. With Preemptive on and no such header, Digest behaves as with Preemptive off
Username / PasswordCredentials
Use Proxy ServerNoRoute through a proxy
Proxy Address / Proxy PortThe proxy
Override Local BindingNoBind a specific local address for the outbound connection. No uses 0.0.0.0
Local Address0.0.0.0The local address the connection is bound to. Enabled only when Override Local Binding is Yes, and the value may use Velocity replacement
Response ContentPlain BodyPlain Body passes the reply body through as a raw string. XML Body returns the body as XML, and adds the status line and headers only when Include Metadata is Yes
Parse MultipartYesSplit a multipart reply into parts. XML Body only
Include MetadataNoInclude status line and headers. XML Body only
Binary MIME Typesapplication/.*(?<!json|xml)$|image/.*|video/.*|audio/.*Reply content types treated as binary and base64 encoded. The Regular Expression checkbox is on by default; unchecked, enter several types separated by commas

JavaScript Writer ​

Runs a script, which can send data anywhere itself or nowhere at all. What the script returns decides the response: nothing at all is a SENT with JavaScript evaluation successful., a Response is used as-is, a Status sets only the status, and anything else becomes the response data. A script that throws gives ERROR.

The JavaScript Writer settings on the channel editor's Destinations tab

SettingDescription
JavaScriptThe script to run

Unlike the JavaScript Reader, this connector has the full message scope: channelMap, connectorMap, sourceMap, responseMap, and connectorMessage are all available. See Script Scope and User API.

JMS Sender ​

Publishes to a JMS queue or topic. The connection fields are the same as the JMS Listener, except that there is no Durable checkbox: Use JNDI, Provider URL, Initial Context Factory, Connection Factory Name, Connection Factory Class, Connection Properties, Username, Password, Client ID, Destination Type, and Destination Name. Use JNDI Yes greys out Destination Type and Connection Factory Class. No greys out Provider URL, Initial Context Factory, and Connection Factory Name. As for the JMS Listener, select the library resource with the provider's client jars on this destination's own entry in Set Dependencies > Library Resources; without it the send is ERROR with a ClassNotFoundException for the factory class.

The JMS Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
Template${message.encodedData}Message body published

SMTP Sender ​

Sends email.

The SMTP Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
SMTP HostMail server
SMTP Port25Mail server port
Override Local BindingNoBind a specific local address and port for the outbound connection
Local Address / Local Port0.0.0.0 / 0The local binding. Enabled only when Override Local Binding is Yes
Send Timeout (ms)5000Connect and socket timeout
EncryptionNoneNone, STARTTLS, or SSL
Use AuthenticationNoAuthenticate to the server. No greys out Username and Password
Username / PasswordSMTP credentials
ToRecipients, comma separated
FromSender address
SubjectSubject line of the email
Charset EncodingDefaultCharacter set for the body
HTML BodyNoSend the body as HTML rather than plain text
BodyBody of the email
HeadersAdditional headers. Use Map takes them from a map variable
AttachmentsFiles attached, each with a name, content, and MIME type. Use List takes them from a list variable

The Administrator has fields for To and From only. cc, bcc, and replyTo exist in the connector's saved properties but have no field.

TCP Sender ​

Opens a TCP connection and sends the message, MLLP framing included.

The TCP Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
ModeClientClient connects out, and is the only mode with Remote Address, Remote Port, Override Local Binding, and Keep Connection Open. Server binds and waits, and is the only mode with Max Connections
Remote Address127.0.0.1Where to connect
Remote Port6660Port to connect to
Override Local BindingNoBind a specific local address and port. Client mode only
Local Address / Local Port0.0.0.0 / 0The local binding. Enabled in Server mode, or in Client mode when Override Local Binding is Yes
Send Timeout (ms)5000How long to keep the connection open when Keep Connection Open is Yes. 0 keeps it open indefinitely. Enabled only when Keep Connection Open is Yes
Buffer Size (bytes)65536Applied to both the socket receive buffer and the socket send buffer, and to the output stream buffer
Max Connections10Concurrent connections accepted. Server mode only
Keep Connection OpenNoHold the connection open between messages. Client mode only, and Yes is what enables Send Timeout and Check Remote Host
Check Remote HostNoTest the connection is still alive before sending. Enabled only when Keep Connection Open is Yes
Response Timeout (ms)5000Wait for a reply. Also used as the connect timeout
Ignore ResponseNoA checkbox beside Response Timeout. Sends without waiting for a reply, and ticking it disables Queue on Response Timeout
Queue on Response TimeoutYesQueue the message when no reply arrives, rather than erroring. Has no effect unless the destination queue is on
Data TypeTextText or Binary. Binary base64 decodes before sending
EncodingDefaultCharacter set, Text only
Transmission ModeMLLPMLLP or Basic TCP. Sample Frame previews the framing bytes. See transmission modes
Template${message.encodedData}Content sent

Validate Response is on by default for this destination.

Web Service Sender ​

Calls a SOAP operation.

The Web Service Sender settings on the channel editor's Destinations tab

SettingDefaultDescription
WSDL URLWSDL to read. Get Operations populates the fields below from it
ServiceService from the WSDL
Port / EndpointPort from the WSDL
Location URIEndpoint address, when it differs from the one in the WSDL
SOAP ActionSOAPAction header
OperationPress Get OperationsOperation from the WSDL. Used to generate the SOAP Envelope and fill in SOAP Action, and not read when the message is sent
SOAP EnvelopeThe envelope sent. Generated from the WSDL, then edited
Invocation TypeTwo-WayTwo-Way waits for a response, One-Way does not
Socket Timeout (ms)30000Connection and socket timeout. 0 is infinite
AuthenticationNoSend credentials with the request. They are also used to fetch the WSDL
Username / PasswordCredentials
HeadersRequest headers. Use Map takes them from a map variable
Use MTOMNoSend attachments as MTOM
AttachmentsAttachments, each with an ID, Content (Base64 encoded), and MIME Type. The table is enabled only when Use MTOM is Yes. Use List takes them from a list variable