Help Manual - MSMQ Destination

Using the MSMQ Destination Component

The MSMQ Destination Component is an SSIS data flow pipeline component that can be used to send messages to a Microsoft Message Queue. There are four pages of configuration:

• General
• Advanced
• Columns
• Error Handling

General Page

Note: several properties in the destination component and the connection manager also exist as advanced fields on the columns page. Properties set at the component and connection manager level will be applied to every outgoing message. If any of these properties are also set on the columns page, the column's value will be used instead, potentially allowing a different value for each outgoing message.

Connection Manager

The destination component requires an MSMQ connection manager. The Connection Manager drop-down will show a list of all the KingswaySoft MSMQ connection managers and Microsoft MSMQ connection managers that have been created in the current SSIS package

Action

The Action specifies how you want to write to the MSMQ queue service. There are 2 Actions:

• Create
• Delete(since v21.2)

Time To Be Received

The maximum time in seconds that a message will remain in the queue after it is sent. If this time expires the message is discarded. Setting this value to 0 will create messages that have an unlimited time to be received

Time To Reach Queue

The maximum time in seconds that a message will take to reach the queue before it is discarded. Setting this value to 0 will create messages that will not be discarded no matter how long they take to reach the queue.

Priority

The priority of sent messages.

Connector Type

A GUID defined by the application and used in conjunction with connector applications or message encryption. This GUID allows a receiving application to interpret message properties that were set by the sending application but that are usually set by Message Queuing. This must be set when any of the following properties/columns are used: AuthenticationProviderName, AuthenticationProviderType, DestinationSymmetricKey, DigitalSignature. This property is optional and does not need to be set if you are using default encryption settings.

Body Column Type(since v6.2)

The Body Column Type allows you to specify whether you want to write the binary content of the message or the text content of the message to the Microsoft Message Queue. There are two different modes available for Body column types: Binary and Text. The default setting is Text.

Encoding(since v6.2)

The encoding that will be used to convert the message body to a byte array when sending the message. This option is only available when the Body Column Type is Text.

Wrap Messages in XML

Messages written to MSMQ are often XML messages. If the body of your text message is not in XML format, check this option to allow MSMQ to convert to XML format. This option is only available when the Body Column Type is Text.

Refresh Component Button

Clicking the Refresh Component button causes the component to retrieve the latest metadata and update each field to its most recent metadata. It will remove any custom fields that have been added to the columns page.

Map Unmapped Fields Button

By clicking this button, the component will try to map any unmapped attributes by matching their names with the input columns from upstream components. This is useful when your source component has recently added more columns, in which case you can use this button to automatically establish the association between input columns and unmapped destination attributes.

Clear All Mappings Button

By clicking this button, the component will reset all your mappings in the destination component.

Expression fx Icon

Click the blue fx icon to launch SSIS Expression Editor to enable dynamic updates of the property at run time.

Generate Documentation Icon

Click the Generate Documentation icon to generate a Word document that describes the component's metadata including relevant mapping, and so on.

Advanced Page

Use Default Authentication Settings

Determines whether messages should be sent with authentication or not. Non-default authentication settings can be used by adding them as input columns on the columns page.

Encryption Algorithm

The algorithm used to encrypt messages. There are three options: None, Rc2, and Rc4. If None is selected the messages will not be encrypted.

Use Dead Letter Queue

If this option is enabled the message-queuing computer that cannot deliver the message before its time-to-reach-queue timer expires will place the undelivered message in the nontransactional dead-letter queue of that computer.

Use Journal Queue

Determines if the journal queue will be used for sent messages. Journal queues store copies of messages that are processed and removed from the queue.

Use Tracing

Determines if tracing should be used for sent messages.

Columns Page

The Columns page allows you to map the columns from upstream components to destination attributes.

On the Columns page, you will see a grid as shown below.

• Input Column: You can select an input column from an upstream component here.
• Destination Field: The attribute/field that you want to write data to.
• Data Type: This column indicates the type of value for the current attribute.
• Unmap: This button provides a convenient way to unset the mapping for the selected attribute/field.

Add Button

Clicking the Add button will bring up a dialog that will allow advanced fields to be added; this will allow you to set additional properties on outgoing messages. The values of incoming data for advanced fields will override any matching properties set in the component.

Error Handling Page

The Error Handling page allows you to specify how errors should be handled when they happen.

There are three options available:

1. Fail on error
2. Redirect rows to error output
3. Ignore error

When the Redirect rows to error output option is selected, rows that failed to write to MSMQ will be redirected to the 'Error Output' of the Destination Component. As indicated in the screenshot below, the green output connection represents rows that were successfully written, and the red 'Error Output' connection represents rows that were erroneous. The 'MsmqErrorMessage' output column found in the 'Error Output' may contain the error message that was reported by MSMQ or the component itself.

Note: Use extra caution when selecting Ignore error option, since the component will remain silent for any errors that have occurred.