TCP Trigger

Listen for raw TCP connections coming to Frends.

In order to launch a Process in response to a raw TCP message, TCP Trigger can be used.

You can learn more about Triggers in general here.

What is TCP Trigger?

TCP Trigger is similar to API and HTTP Triggers, but instead of having incoming HTTP request, the Trigger listens for raw TCP messages coming to network interfaces on the Agent machine. Process is triggered by TCP Trigger once a complete message has been received, up to the defined end of message bytes.

Usage

To use a Trigger in your Process, add it to your Process canvas, and connect it to the beginning of your Process using a Sequence flow. If you are using multiple Triggers in your Process, all Triggers must connect to the same shape, which is also the first non-Trigger shape in your Process.

Once added to your Process, you can change the Trigger's type to match your requirement and give it a unique name. By default, the Trigger's type will provide a corresponding name for the Trigger. You can then configure the parameters for the chosen Trigger type.

By default, the TCP Trigger will listen and respond to any TCP message that the server receives in its network interfaces. Provided parameters can be used to limit which IP addresses the Trigger responds to for both client and receiver side, as well as how many simultaneous connections are allowed to be handled at once. You can also configure the format of the data transfer that is expected to be received, such as text encoding used and how to identify end of message.

Messages can be sent back to the client using #process.SendTcpMessage method, or by returning a value using Return shape. Null return will not send a response back to the client, while anything else will be sent back as a message in string format.

Configuration

To set up an TCP Trigger, add the shape to Process canvas and connect it as part of your Process. After that, you can select the Trigger type and configure the parameters for it.

The common parameters available for all Triggers are explained on the Trigger reference page. The following configuration parameters are available for TCP Trigger.

Address

Defines the IPv4 address that the Trigger listens to. If using a specific IP address here, the same IP address ha to be defined for some network interface on the server as well.

0.0.0.0 can be used to listen to all network interfaces.

Port

Defines the port that the Trigger listens to for incoming connections.

Allowed IP Addresses

Comma separated list of allowed client IP addresses, or IP address ranges that are allowed to connect.

0.0.0.0/0 can be used to allow all clients and connections.

Maximum Open Connections

Number of connections that are allowed to be open at the same time. Effectively limits the number of Processes being executed at the same time.

Idle Timeout in Seconds

If set, the connection will be closed after the set amount of seconds if no data has been received during that time.

Set to 0 for no timeout.

Connection Identifier

Specifies how the client for each connection is identified, in order to send data to an open connection to client outside the Process that was triggered.

Client can be identified either by both its IP address and Port, or only by the IP address.

Data Mode

Selects whether the incoming message is intepreted as textual data or as binary data.

Currently only text data is supported.

Encoding

Encoding used to intepret the textual data from binary stream.

Can be either ASCII or UTF-8.

Termination Event

How to determine the end of a message.

Currently only character sequence is supported.

Hex String for Termination Sequence

Specifies the termination character sequence as a hex string for the binary representation of chosen character sequence.

For example, 0A is the line feed (LF) character, while 68 65 6C 6C 6F translates to 'hello'.

Defaults to 0A.

Append Termination Sequence to All Outgoing Messages

Toggle value which if enabled, appends the termination sequence to all outgoing TCP messages from the Process.

Defaults to enabled.

Do not log trigger parameters

Toggle option that when enabled, hides the Trigger parameters from being logged in Process Instances.

Reference Values

In addition to the default Trigger reference values, TCP Trigger provides the following additional values.

#trigger.data (Frends.ExecutableProcess.CaseInsensitivePropertyTree)

Object containing the data derived from input parameters and the resulting data from processing the Trigger.

#trigger.data.connectionId (String)

Field containing the identifier for the client that opened the connection. Contains the IP address and optionally port for the client, if the client identifier parameter was set to contain both.

#trigger.data.message (String)

Contains the received message, up to a received termination character sequence (not included in message).

Related Process Reference Values

While not provided by the TCP Trigger, these Process Reference Values can be used alongside TCP Trigger for additional functionality.

#process.SendTcpMessage (String senderId, String clientId, String message)

Method for sending TCP messages from a Process to a client who opened a connection.

SenderId (String)

SenderId should contain the IP address and port representing the network interface that is used to send the message to a client. For example,"0.0.0.0:38000" can be used for broadcasting through all available network interfaces, from port 38000.

ClientId (String)

ClientId should contain the client identifier that opened a connection to us. Format should match the client identifier parameter defined in TCP Trigger parameters. For example, value "10.0.0.27:1337" could be used if both IP address and port were chosen to represent a client.

Message (String)

Message contains the content we are sending over the TCP connection to the client. Should contain the terminating character sequence, unless it is chosen to be automatically appended.