WebSocket Client
The WebSocket Client origin reads data from a WebSocket server endpoint. Use the origin to read data from a WebSocket resource URL. The origin can also send responses back to the origin system when used in a microservice pipeline. For information about supported versions, see Supported Systems and Versions.
When the pipeline starts, the WebSocket Client origin opens a connection to the WebSocket server endpoint and optionally sends an initial message to the server. The WebSocket server then pushes data to the WebSocket Client origin. The origin creates and sends a batch as soon as the data arrives. The size of each batch varies, based on the size of the data sent by the server endpoint. When the pipeline stops, the origin notes where it stops reading and closes the connection to the endpoint.
When the pipeline starts again, the WebSocket Client origin continues processing from where it stopped by default. You can reset the origin to process all requested data.
When you configure the WebSocket Client origin, you define the resource URL and headers to use for the requests. You configure whether the origin uses no authentication or basic authentication to connect to the WebSocket server endpoint.
When you want the origin to send responses back to the origin system as part of a microservice pipeline, you configure the data format and other characteristics of the responses.
You can also configure SSL/TLS properties, including default transport protocols and cipher suites.
Read REST Response Data from Data Collector
You can use the WebSocket Client origin to read REST response JSON data generated by Data Collector.
Data Collector can serve as a WebSocket server endpoint, as a WebSocket server is simply a TCP application listening on any port of a server that follows a specific protocol.
For example, let's say that your Data Collector runs twenty pipelines and you want to receive an email when any pipeline state changes to Run_Error. Instead of configuring email notifications for all twenty pipelines, you'd like to configure a single global email notification for all of the running pipelines.
- Add a WebSocket Client origin and configure the origin to read from the
following resource
URL:
ws://<Data Collector host>:<Data Collector port>/rest/v1/webSocket?type=status
- Configure the origin to use basic authentication, and then enter a valid Data Collector user name and password on the Credentials tab.
- On the Data Format tab, configure the origin to process the JSON data format.
- Add an Email executor to the canvas and connect it to the origin.
- On the Email tab of the executor, enter the following
condition so that the executor sends an email only when a pipeline state changes
to
Run_Error:
${record:value('/status') == 'RUN_ERROR'}
- Configure the email IDs, subject, and body for the executor.
For more details about configuring the executor, see Email Executor. Before you run a pipeline that includes the Email executor, you must enable Data Collector to send email.
The configured pipeline looks like this:
Generated Microservice Responses
In a microservice pipeline, the WebSocket Client origin can send a response back to the originating WebSocket server.
- Records received from microservice destinations
- Pipeline error records received when the pipeline is configured to use the Send Response to Origin pipeline error handling
The origin generates a single response for each batch of records received. The origin can generate the response in JSON or XML format. The response can include an envelope or only raw data.
Responses with an Envelope
Response Key or Element | Value |
---|---|
httpStatusCode | The status code associated with the records in the
response. If the records in the generated response share the same status code, the code is written to the httpStatusCode key or element. If the records have different status codes, the httpStatusCode is set to 207 for multiple statuses. |
data | A list of records passed to the origin by the microservice destinations used in the pipeline. |
error | A list of pipeline error records passed to the origin by the Send Response to Origin pipeline error handling. |
errorMessage | The error message associated with the first error
record in the response. Used only when the response includes error records. |
{
"httpStatusCode":<status code>,
"data":[<list of success records>],
"error":[<list of error records>],
"errorMessage": <error message, if any>
}
Raw Responses
When configured to send a raw response, the origin generates a response that contains either the list of records passed from the microservice destinations or the list of error records passed by the Send Response to Origin pipeline error handling. If the origin receives data records from destinations and error records from the pipeline, then the origin includes only the error records in the response. If the origin receives no data records from destinations and no error records from the pipeline, then the origin generates an empty response.
Sample Responses
- Single record
- The origin receives a single record from the Send Response to Origin
destination. The destination is configured to use the 200 status code.For a response with an envelope, the origin sends the following response:
{ "httpStatusCode":200, "data":[{"ID":"103","NAME":"Jack","AGE":"37","STATE":"MD"}], "error":[], "errorMessage":null }
For a raw response, the origin sends the following response:{"ID":"103","NAME":"Jack","AGE":"37","STATE":"MD"}
- Multiple data and error records
- The origin receives several records, data and error. Because each record has
a different status code, the response uses status code 207 for multiple
statuses. The errorMessage key includes the error associated with the first
record which has a missing ID. The origin is configured to present multiple
records as multiple JSON objects.For a response with an envelope, the origin sends the following response:
{ "httpStatusCode":207, "data":[{"ID":"248","NAME":"Pina","AGE":"24","STATE":"RI"}], "error":[{"NAME":"Liz","AGE":"37","STATE":"DE"}, {"ID":"302","NAME":"Roco","AGE":"","STATE":"CA"}], "errorMessage":"COMMON_0001 - Stage precondition: CONTAINER_0051 - Unsatisfied precondition(s) '${record:exists('/ID')}'" }
For a raw response, the origin sends the following response:{"NAME":"Liz","AGE":"37","STATE":"DE"}, {"ID":"302","NAME":"Roco","AGE":"","STATE":"CA"}
Data Formats
The WebSocket Client origin processes data differently based on the data format that you select.
The WebSocket Client origin processes data formats as follows:
- Binary
- Generates a record with a single byte array field at the root of the record.
- Datagram
- Generates a record for every message. The origin can process collectd messages, NetFlow 5 and NetFlow 9 messages, and the following types of syslog messages:
- Delimited
- Generates a record for each delimited line.
- JSON
- Generates a record for each JSON object. You can process JSON files that include multiple JSON objects or a single JSON array.
- Log
- Generates a record for every log line.
- Protobuf
- Generates a record for every protobuf message. By default, the origin assumes messages contain multiple protobuf messages.
- SDC Record
- Generates a record for every record. Use to process records generated by a Data Collector pipeline using the SDC Record data format.
- Text
- Generates a record for each line of text or for each section of text based on a custom delimiter.
- XML
- Generates records based on a user-defined delimiter element. Use an XML element directly under the root element or define a simplified XPath expression. If you do not define a delimiter element, the origin treats the XML file as a single record.
Configuring a WebSocket Client Origin
Configure a WebSocket Client origin to read data from a WebSocket server endpoint.