Dispatch Service

After installation, the Data Hub will accept and queue messages but it will not dispatch them until at least one destination is configured. Additional settings related to the Dispatch Service are also configurable.

Page Contents

Modifying the Configuration
General Settings
Destinations
Include and Exclude Criteria
Dispatching via SSL

Modifying the Configuration

To modify the Dispatch Service configuration:

Open [Application folder]\DispatchService\Dispatch.config.
Modify the file according to the subsections below.
Save the file.
Restart the Dispatch Service.

General Settings

The <settings> section defines configuration settings that apply to all destinations or to the Dispatch Service itself. If the setting is missing then the default value is used.

<offlineRetry>
- When a durable destination appears to be offline, the Data Hub automatically queues all data for that destination, and periodically checks if the destination has come back online. This setting determines how often it checks.
- Default: 60 seconds.
<errorRetry>
- When a message received an error response (e.g. HTTP 500) from a durable destination, the Data Hub automatically queues and periodically retries that message. This setting determines how often it retries delivery.
- Default: 6 hours.
<errorGiveup>
- When a message has been queued because of an error response, the Data Hub will eventually stop retrying that message and will discard it. This setting determines the minimum amount of time before it is discarded. (The message will not be discarded until an attempt is made that was after the time period.)
- Default: 7 days.
<loopLimit>
- The number of times a message is allowed to loop through this Hub (as indicated by the Via HTTP header) before being discarded and logged as an error.
- In most circumstances, looped messages imply a misconfigured dispatch service, either in this Data Hub instance or in an upstream or downstream instance. It is possible that messages can be manually re-sent to a Data Hub, though, so by default messages are allowed to loop through the Data Hub twice before being discarded.
- Default: 2.
<discardEmptyMessages>
- Occasionally the Data Hub will receive a HTTP POST with no body. This is a valid HTTP POST, but it will generally be rejected by any PreEmptive Analytics endpoint, resulting in the message being queued in the error queue. In order to avoid spurious messages in the error queue, the Data Hub can automatically discard these messages.
- Default: true.
<dispatchFromEndpoint>
- It is possible, for troubleshooting purposes, to prevent dispatching messages from the endpoint queue. If set to false, messages will remain in the endpoint queue. Only messages in the offline and error queues will be processed.
- Default: true.

The three time span settings can be expressed either in seconds with an optional fractional part with millisecond precision (ss[.fff]) or in .NET TimeSpan format ([d.]hh:mm[:ss[.fff]]). These time spans may not be negative, nor greater than the largest time span supported by .NET.

Example: Three ways to express a time span of "every 24 hours"

<errorRetry>86400</errorRetry>
<errorRetry>24:00</errorRetry>
<errorRetry>1.00:00</errorRetry>

Destinations

The <destinations> section defines the destinations to which the Dispatch Service will attempt to dispatch messages. Each destination is represented by a <destination> element, with the following attributes:

id (Required)
- The unique, case-insensitive identifier for this destination. Used in logging, in the names of queues, and in performance counters.
- This value cannot start with an underscore (_) and cannot be longer than 127 characters, nor 241 UTF-8 bytes.
- In general, this identifier should not be changed after the destination has been added. Changing a destination ID (and restarting the Dispatch Service) causes the Dispatch Service to assume that a new destination has been added an an old destination has been removed. Under normal circumstances, the Dispatch Service will remove the queues for the old destination. If messages are in the offline or error queues for that destination, though, deleting the queues would discard those messages. Because of this concern, the Dispatch Service will issue an error and fail to start if a deleted destination has queued messages.
  - If you are sure you want the queues to be removed, even though they have data, you must manually purge the queues in question before restarting the Dispatch Service.
url (Required)
- A valid HTTP(S) URL for this destination.
- If no port is specified, the default port for the protocol will be used.
durable
- If true or omitted, messages that do not result in successful responses will be queued and retried. The destination is durable.
- If false, incoming messages that do not result in successful responses will be dropped. Any messages queued from before this setting was false will remain queued. The destination is non-durable.

Example: A PreEmptive Analytics for Team Foundation Server instance located on internal machine "patfs.example.internal", to which all incoming messages will be delivered

<destination id="PA TFS" url="http://patfs.example.internal:8000/message/Endpoint.ashx" />

Example: An internal test destination, for which data loss during destination downtime is preferable to using disk space on the Data Hub host

<destination id="QA" url="http://testing.example.internal/endpoint" durable="false" />

Include and Exclude Criteria

Each destination can be configured to only include certain messages, or to exclude certain messages, or a combination of the two. This is done via the following two optional child elements of <destination>:

<include>...</include>
- Contains a list of criteria as child elements. If the message satisfies any of these criteria, the message will be dispatched.
- If present, it cannot be empty.
- Default (if missing): includes all messages.
<exclude>...</exclude>
- Contains a list of criteria as child elements. If the message satisfies any of these criteria, the message will not be dispatched.
- Exclude criteria takes precedence over include criteria.
- If present, cannot be empty.
- Default (if missing): excludes no messages.

There are three criteria elements, using a tree-like grammar to form criteria patterns. Each node in the tree is evaluated, starting from the root <include> or <exclude> element. If the node fails to match, none of its children are evaluated, but siblings will continue to be evaluated. If it matches and has children, the matching process continues with its children. If it matches and has no children (i.e. it is a leaf node), then the message matches the pattern and is processed. Match evaluation continues until a match has been made or the tree has been exhausted.

<all/>
- All messages will satisfy this criteria.
- Cannot be a sibling of any other element.
- Cannot have any children.
<company id="...">...</company>
- Satisfied by any message with a matching company ID.
- If id is a GUID, all GUID formats used by PreEmptive Analytics clients will be checked on incoming messages.
- Cannot be nested beneath another <company> or <application>.
<application id="...">...</application>
- Satisfied by any message with a matching application ID.
- If id is a GUID, all GUID formats used by PreEmptive Analytics clients will be checked on incoming messages.
- Must be a child of <company>.

Another way to think about the match syntax is that sibling nodes have an "OR" relationship, and parent/child nodes have an "AND" relationship.

Example: A destination that will receive all messages for a single specific company

<destination id="PA TFS" url="http://patfs.example.internal:8000/message/Endpoint.ashx">
    <include>
        <company id="{CAFEBABE-0000-0000-0000-000000000000}" />
    </include>
</destination>

Example: A destination that will receive all messages for two specific applications (only)

<destination id="Runtime Intelligence" url="https://so-s.info/endpoint">
    <include>
        <company id="{CAFEBABE-0000-0000-0000-000000000000}">
            <application id="{00ABC123-0000-0000-0000-000000000000}" />
            <application id="{00FACADE-0000-0000-0000-000000000000}" />
        </company>
    </include>
</destination>

Example: A destination that will receive all messages for the above company, except those for a single specific application ID

<destination id="Dev Workbench" url="http://dev-workbench.example.internal/endpoint">
    <include>
        <company id="{CAFEBABE-0000-0000-0000-000000000000}" />
    </include>
    <exclude>
        <company id="{CAFEBABE-0000-0000-0000-000000000000}">
            <application id="{00000BAD-0000-0000-0000-000000000000}" />
        </company>
    </exclude>
</destination>

More examples can be found in the comments of the Dispatch.config file.

Dispatching via SSL

The Dispatch Service requires no additional configuration to dispatch messages to destinations over SSL, provided the destination supports it. Simply enter the URL with https as the protocol when configuring destination entries.

Example: A destination configured to listen for HTTPS connections on the default port, 443

<destination id="Secure" url="https://secure.example.internal/endpoint" />

Example: A destination configured to listen for HTTPS connections on port 1889

<destination id="Custom Secure" url="https://secure.example.internal:1889/endpoint" />