Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Jabber Endpoint

The Jabber Endpoint is used when you would like to have code invoked when an instant message is received by TORO Integrate.

Properties

Name Default Description
Host (required) Jabber server host
Port 5222 Jabber server port
Username (required) Jabber client username
Password (required) Jabber client password
Service Name (required) The service name of the XMPP service (i.e., the XMPP domain).
Service (required) The service to execute under this alias
Run As 'Anonymous' The user to run the service in behalf of. This is logged to tracker
Log to Tracker false Flag determining whether executions should be logged to the tracker
Document Type 'Jabber' The document type to be registered to the tracker when this endpoint is triggered

Reply

Additional properties can be configured related to the reply behavior of the endpoint:

Name Default Description
Reply with Service Response false If set to true, this will automatically reply with the returned value of your service (limited to java.lang.String and groovy.lang.GString)
Use Object Converter on Service Response false If set to true, this will allow the endpoint to reply with an object marshalled by an object converter

Advanced

For advanced cases, there are more properties available:

Name Default Description
Security Mode 'if possible' Sets the TLS security mode used when making the connection.
Ping Interval 20s Pings the server periodically. This setting will ensure the connection will not be dropped.
Connection timeout 50000ms How long the socket will wait until a TCP connection is established in milliseconds.
Packet reply timeout 10000ms Set the stanza (packet) reply timeout in milliseconds. If no reply to a request was received within the timeout period, an exception will be thrown.
Resource name 'jabber/[endpoint_name]' Set the resource to use. If resource is null, then the server will automatically create a resource for the client.
Keystore path Sets the path to the keystore file. The key store file contains the certificates that may be used to authenticate the client to the server, in the event the server requests or requires it.
Keystore type Sets the keystore type.
PKCS11 Library Sets the PKCS11 library file location, needed when the Keystore type is PKCS11.
Enable compression false Sets if the connection is going to use stream compression. Stream compression will be requested after TLS was established (if TLS was enabled) and only if the server offered stream compression. With stream compression, network traffic can be reduced up to 90%.
Allow empty username false Allow null or an empty string as username. Some SASL mechanisms (e.g. SASL External) may also signal the username (as "authorization identity"), in which case Smack should not throw an IllegalArgumentException when the username is not set.

Service

When the endpoint is triggered, the following variables are exposed to the configured service:

Name Type Description
parameters java.util.Map A map containing all variables below
esbPackage ESBPackage The Integrate Package that contains this endpoint
properties java.util.Map Contains all the properties associated with the endpoint
message io.toro.integrate.jabber.Message The message object
content java.lang.String The default body of the message, or null if the body has not been set. The body is the main message content.
error io.toro.integrate.jabber.XMPPError The error associated with this packet, or null if there are no errors.
chat io.toro.integrate.jabber.Chat Jabber chat client which can be used to send messages & perform other operations.
to java.lang.String The stanza (packet) is being sent "to", or null if the value is not set. The XMPP protocol often makes the "to" attribute optional, so it does not always need to be set.
from java.lang.String The stanza (packet) is being sent "from" or null if the value is not set. The XMPP protocol often makes the "from" attribute optional, so it does not always need to be set.
subject java.lang.String The subject of the message, or null if the subject has not been set. The subject is a short description of the message's contents.
language java.lang.String The language, or null if one has not been set.
threadId java.lang.String The thread ID of the message, which is a unique identifier for a sequence of "chat" messages. If no thread ID is set, null will be returned.
internalId java.lang.String Tracker internal ID. If the endpoint was configured to not track, this value will be null.

Gloop as a Service

Consider the following endpoint configuration, for Atlassian's Hipchat:

GuessingEndpoint's configuration

It uses a gloop service called GuessingGame, which asks the user what number it currently thinks of. The service responds with hints as to whether the actual number is higher or lower than the current guess. See it in action:

Chatbot demo

Name Type Description
parameters java.util.Map A map containing all variables below
esbPackage ESBPackage The Integrate Package that contains this endpoint
properties java.util.Map Contains all the properties associated with the endpoint
message Message The message object
content java.lang.String The default body of the message, or null if the body has not been set. The body is the main message content.
error XMPPError The error associated with this packet, or null if there are no errors.
chat Chat Jabber chat client which can be used to send messages & perform other operations.
to java.lang.String The stanza (packet) is being sent "to", or null if the value is not set. The XMPP protocol often makes the "to" attribute optional, so it does not always need to be set.
from java.lang.String The stanza (packet) is being sent "from" or null if the value is not set. The XMPP protocol often makes the "from" attribute optional, so it does not always need to be set.
subject java.lang.String The subject of the message, or null if the subject has not been set. The subject is a short description of the message's contents.
language java.lang.String The language, or null if one has not been set.
threadId java.lang.String The thread ID of the message, which is a unique identifier for a sequence of "chat" messages. If no thread ID is set, null will be returned.
internalId java.lang.String Tracker internal ID. If the endpoint was configured to not track, this value will be null.

Groovy as a Service

Consider the following groovy stub:

1
2
3
4
5
6
7
class GuessingGame {

    public String guess( Chat chat, Message message, String from ) {
        String msg = message.getBody();
        // Implementation omitted
        return "Try to guess what number I'm thinking!"
    }

By querying the properties from the injected Message, we can add conditions that direct the behavior of the replies, such as inviting the user for a guessing game. The returned String value in this method is sent back to the user as a chat reply.

Similar to the gloop example, we can configure the endpoint into the following:

GuessingEndpoint's configuration

…the only difference being, this time we use our GuessingGame code as the endpoint service.

Chatbot demo

More Examples

The distribution ships with an Integrate package called examples, which contains services demonstrating more use cases.