Satori Docs

Your definitive guide to subscribing and publishing live data

Streambots™ Direct link

Streambots™ allow you to define and execute custom logic on each message in a message stream, a.k.a. channel. Streambots™ subscribe to real-time messaging (RTM) channels and execute custom code for every message received in those channels. In addition, Streambots™ can publish content to any RTM channel in its project and can use views to filter on a message stream to receive only a desired subset of messages. 

For example, you could build a Streambot™ that intercepts messages from a stream, analyzes their contents looking for certain keywords, and sends messages back to the RTM channel.

You develop your Streambots™ on the Satori platform. See the Streambots™ Quickstarts to get started.

During the Beta phase, Streambots™ only communicate with RTM and cannot call out to external URLs. Streambots™ cannot write to files or access the file system, spawn processes, open sockets, or perform any I/O beyond communicating with RTM via publishing and subscribing to channels.

You can develop Streambots™ using the following languages:

  • Java: The satori-bot-example provides a starting point for creating your own Java-based Streambot™. It makes use of the Streambot™ executor from the Satori Streambot™ SDK which allows you to run, debug, and test your Streambot™ on your local machine (running locally) using either the command line or a Java IDE (e.g. IntelliJ). Building the satori-bot-example generates a .jar file which can then be uploaded to the Dev Portal.

  • JavaScript: The bot.js file in the satori-bot-example package can be executed locally from the command line for testing and then uploaded to the Dev Portal for execution. Alternatively, the JavaScript code can be entered directly in a code editor available in the Dev Portal for execution. The satori-bot-example provides a starting point for creating your own JavaScript-based Streambot™. 
    To run JavaScript Streambot™, you need to have the JDK version 1.8u144 or higher.

Run Streambot™ Instances Direct link

To run a Streambot™, you provide your Streambot™ implementation and configure and create instances of the Streambot™. Each Streambot™ instance is a running Streambot™ in the Satori environment, subscribing to channels and processesing the messages it receives. In the Dev Portal, you create Streambot™ instances and then start and stop the instances. You can also view the log for each instance.

Each Streambot™ instance is configured to specify the channels to which it will subscribe. Each channel may have an optional query to filter the messages (see Views). Additionally, you can create custom configuration JSON parameters that are passed to the Streambot™ instance when it is launched. 

Each Streambot™ instance must use the appkey and endpoint for the Dev Portal project on which you deployed the Streambot™.

You instantiate Streambots™ as follows:

  • Java Streambots™: A Java Streambot™ is instantiated based on your implementation of the Bot interface, which you will compile and package into a JAR file using the gradle botJar task as described in Deploy. On the Dev Portal, you upload that JAR file for a specific project. You can instantiate multiple instances of your Streambot™, being able to simultaneously process different RTM streams. RTM will execute your Java Streambots™ using Java 8. 
  • JavaScript Streambots™: A JavaScript Streambot™ consists of a .js file with a function that processes messages. You can either upload the .js file containing your Streambot™ implementation to the Dev Portal or use the Dev Portal’s built-in code editor to write your JavaScript implementation directly online. RTM will execute your JavaScript implementation using the Java 8 scripting engine.

Run a Streambot™ from the Dev Portal

When you run a Streambot™ from the Dev Portal, RTM handles the deployment and availability of your Streambot™, providing the following benefits:

  • Versioning with the ability to change instances when needed
  • High availability and monitoring

This is the recommended way to run a Streambot™. See Deploy the Streambot™ for an example.

To upload a new Streambot™ and run an instance:

  1. Navigating to Streambots > Create a Streambot.
  2. Specify the configuration properties for the Streambot™ instance.
  3. Upload the source code of your Streambot™, or enter your JavaScript code in the online editor.
  4. When you click Create, the first instance of the Streambot™ is started.

To run an instance of a Streambot™ previously uploaded:

  1. Navigate to Projects > My projects > your project.
  2. In the Streambot instances tab for the project, click an instance name to start the instance.
  3. Alternatively, click a Streambot™ name to create a new instance for the Streambot™.

Run a Streambot™ Locally

To run a Streambot™ locally, you provide a JSON configuration file that specifies the configuration properties. See Run the Streambot™ Locally for an example.

This method is used primarily for testing a Streambot™.

Streambot™ Versions Direct link

A Streambot™ version is a specific version of your Streambot™ implementation that you provide on the Dev Portal. Streambot™ versions are defined in the Dev Portal, where you can deploy multiple versions.

The number of versions that your organization can create depends on your account type.

The Streambots page of the Dev Portal includes a list of all Streambots™, versions, and instances for your organization.

Streambot™ Logging Direct link

You can write and read log events of your Streambot™ as below.

  • Java Streambots™: The SDK provides a logging framework to generate log events in your Streambot™. When you log an event, the logger posts the logged message to the Streambot™ console page on the Dev Portal.
    Use the BotContext.getLogger method to retrieve an instance of the logger. The following code sample shows a log event in satori-bot-example.

import org.slf4j.Logger;
...
private static final Logger logger = BotContext.getLogger(MyBot.class);
...
logger.info("Set up done for example Streambot™");
  • JavaScript Streambots™: The logs will be available in the Dev Portal when logging is done via console.log.

  • Dev Portal: View the log events in the Console section by navigating to Projects > My Projects > your project > Streambot instances > your Streambot™ instance.