Websocket Messaging Task
The Websocket Messaging task provides two way messaging between Patriot and a third party messaging provider over a single websocket connection. Patriot connects out to a websocket server (a Messaging Bridge) which translates Patriot's messages into calls to the underlying messaging provider - for example an SMS gateway, a push notification service, or an in house messaging platform.
Because Patriot acts as the websocket client, no inbound ports, callback URLs or HTTP Namespace Reservations are required on the Patriot Task Server. Delivery status updates and inbound messages are delivered back over the same connection.
The task behaves like Patriot's other SMS Gateway tasks: it sends manual and automated messages, supports message formats, and can receive messages back for alarm acknowledgement and reporting.
The wire protocol that your Messaging Bridge must implement is documented in Websocket Messaging Protocol.
Prerequisites
- The Websocket Messaging Client module must be registered. The task will fail to start with a
WebsocketMessagingClient Module not registerederror if it is not. - A websocket server implementing the Websocket Messaging Protocol.
- The Patriot Server running the instance of the Task Service hosting the task must have network access to the websocket server.
- For secure connections (
wss://), the server's SSL certificate must be trusted by the Patriot Task Server machine.
Installing the Websocket Messaging Task
The task can be run on any machine running the Patriot Task Service. Ordinarily, the task should run on the primary Patriot server.
System Menu Item > Tasks > Task Settings
Please read TASK SETTINGS for general information about adding tasks.
Add a new instance of the Websocket Messaging task by selecting it from the Task Type drop down list.
Click the next button to continue. The Websocket Messaging task settings form will be displayed.
Websocket Messaging Task Settings
Many settings are common between Patriot's various messaging tasks. Only the settings specific to the Websocket Messaging task are described in detail below - see SMS Gateway Task Settings for the common messaging settings such as Header Message, Number to Use, Prefix, Attempts, Retries and Retry Wait.
Enter a Description of the task, e.g. Websocket Messaging.
The Task No. will default to the next free task number.
Select the Computer that this task is to be run on. This will default to the computer you are currently on. The chosen computer must have network access to your websocket server.
Backup: Check this box if you wish this task to be defined as a backup task.
Text log Filter level can be used for task troubleshooting purposes. It should be left to the default None.
Enter a System Account No. The system account number is used to log any task errors and other system generated signals, including the connection fail and restore signals described in Task Faults. If this account does not already exist you will need to set it up as a template under Maintenance > Clients > Templates, and import the System Generated Event Types.
Websocket Settings:
Headers are additional HTTP headers sent when opening the websocket connection, in the format Header1=Value1;Header2=Value2;.... Use \; or \= to include a literal semicolon or equals sign in a name or value. Entries which do not contain exactly one unescaped =, or which have an empty name, are ignored and logged as a warning. Leave this blank if your server does not require connection headers.
Websocket URL is the URL of your websocket server, e.g. wss://bridge.example.com/messaging. Both ws:// and wss:// are supported; wss:// is strongly recommended.
Websocket Config is a JSON string passed to your server in the Init message as the payload.config value. It typically carries the credentials or account details your server requires, e.g. {"userName":"123456","password":"ABC123DEF456"}. The contents are defined by your server - Patriot does not interpret them.
Patriot passes Websocket Config through as a JSON string, not as a nested JSON object. Your server must parse the payload.config string to read the values. See Init.
Recv. Message Type selects how inbound messages received from your server are interpreted. See Receiving Messages Back for the available types.
Message Processing Timeout is the number of minutes Patriot will wait for your server to report a final delivery status for a message it has sent. See Message Processing Timeout below.
Click Save to save task settings
Connection Behaviour
The task connects lazily - the websocket connection is opened on the first task cycle, and re-opened automatically if it drops.
On each task cycle the task will:
- Connect and initialise the websocket if it is not already connected and initialised. Initialisation must complete within 15 seconds.
- Send a Heartbeat to confirm the connection is healthy.
- Send any messages queued for delivery.
After a reconnect, Patriot re-sends the Init message and then re-subscribes to the delivery statuses of any messages that were still in flight, so that delivery results are not lost across a connection drop.
Message Processing Timeout
Patriot does not consider a message complete when it has been handed to your server - it waits for a Message Delivery Status Update with a final success or error status. Message Processing Timeout limits how long it will wait.
Every message the task sends is tracked until a final status is received, so the timeout applies to all messages sent by the task.
Setting Message Processing Timeout to 0 turns message timeouts off - Patriot will wait indefinitely for a delivery status.
The timeout is measured in whole task cycles, so a message is timed out on the first task cycle at or after the configured number of minutes.
When a message times out:
- A
Timed out waiting for a status updateerror is written to the task log. - An Unsubscribe From Message message is sent so your server stops reporting on it.
- A GSM Error signal,
Timeout sending to <destination>, is logged against the account the message was for. - The message is released back to the messaging queue and follows the task's normal Attempts, Retries and Retry Wait behaviour.
A late delivery status arriving after the timeout is ignored - the message is no longer being tracked.
Leaving Message Processing Timeout at 0 means a message your server never reports on is never retried and never fails. Patriot will keep it in its in flight list - and re-subscribe to it after every reconnect - until the task is restarted. A non-zero value is recommended unless your server is guaranteed to report a final status for every message.
Task Cycle
The task does its work on a repeating task cycle. After each cycle completes the task waits 5 seconds before running the next one, so a cycle runs approximately every 5 seconds - slightly longer if the previous cycle took time to complete, for example while working through a backlog of queued messages.
Everything the task does periodically - connecting, initialising, heartbeating, sending queued messages and timing out messages awaiting a delivery status - happens on this cycle. Inbound messages from your server are the exception: they are processed as soon as they arrive, not on the cycle.
Task Faults
The task is placed into a fault state, and a Receive Fail signal is logged against the System Account No., when:
- the connection or initialisation fails while sending a heartbeat,
- your server responds to Init with
success: false, - no Heartbeat Response was received for the previous heartbeat, or
- the heartbeat could not be sent.
When a heartbeat response is next received the fault is cleared and a Receive Restore signal is logged.
Messages which cannot be sent - because the connection or initialisation failed, or because your server reported an error delivery status - are treated as failed sends and follow the task's normal Attempts, Retries and Retry Wait behaviour.
Troubleshooting
Task fails to start with "WebsocketMessagingClient Module not registered"
The Websocket Messaging Client module is not registered on this system. Contact Patriot Systems to arrange registration.
"Websocket URL not configured" logged repeatedly
The Websocket URL task setting is empty. Enter the URL of your websocket server.
"Failed to connect to websocket"
Check that the Patriot Task Server can reach the URL and port, that any firewalls permit the outbound connection, and - for wss:// URLs - that the server's SSL certificate is trusted by the Task Server machine. Confirm any required Headers are configured correctly.
"Initialisation failed"
Your server rejected the Init message. The error text reported by your server is included in the log message and the fault description. Check the Websocket Config value is the JSON your server expects.
"No heartbeat response received"
Your server is not replying to Heartbeat messages with a Heartbeat Response. The connection is treated as unhealthy until one is received.
Messages send but never complete
Your server must send a Message Delivery Status Update with a success or error status for each message. Until then Patriot considers the message in flight and will re-subscribe to it after any reconnect. If Message Processing Timeout is 0 the message will stay in flight indefinitely - see Message Processing Timeout.
"Timed out waiting for a status update"
Your server did not report a final delivery status within the Message Processing Timeout. Either your server is slow or is not reporting statuses for these messages, or the timeout is set too low for the messaging provider in use.
For general task troubleshooting see Task Diagnostics. Set Text log Filter level to Debug to log the full JSON of every message sent and received.