August 9, 2016 Philip Aston

Diffusion Cloud on Bluemix: Subscribe to a JSON topic in 5 steps

JSON (JavaScript Object Notation) is an incredibly versatile, simple to understand, and lightweight data format. Though it has JavaScript in the name, as a text-based format, it is language independent and provides a perfect way to transmit data that has an inherent structure.

In my first post, I showed how you can publish to a JSON topic in 5 steps. Today I’ll show how to use the Diffusion JavaScript API to subscribe to a JSON topic and interact with the topic value as a native JavaScript object.

To try this demo, you need a Diffusion Cloud service. You can get a Free edition of Diffusion Cloud from Bluemix.

1. Create an HTML file that imports diffusion.js

The Diffusion JavaScript API is hosted on You can link to this version from your JavaScript browser clients.

     <title>JSON example</title>
     <script type="text/javascript" src=""></script>
     <span>The value of topic/json is: </span>
     <span id="display">Unknown</span>

Create a span inside the body of your HTML file that you can use to display the JSON values the client receives from the topic. In this example it has id="display".

2. Connect to your Diffusion Cloud service

Connect to your Diffusion Cloud service using the URL shown on your Diffusion Cloud Dashboard.

From Bluemix, click on Diffusion Cloud in your list of services, then click the “OPEN DIFFUSION CLOUD FROM PUSH TECHNOLOGY DASHBOARD” button to get to the Dashboard. Here you’ll find your service name and URL.

On the Dashboard, you’ll also find the System Users table. To connect to your Diffusion Cloud service and subscribe to topics, you’ll need a user who has permission to subscribe to topics. You can create that user here. Click on the plus sign (+) to open the ‘Add Users’ wizard. In it, add a user called ‘client’ and give the user the ‘CLIENT’ role.

OK – you’re ready to connect. Add a script to the body of the HTML file that calls diffusion.connect():

     <span>The value of topic/json is: </span>
     <span id="display">Unknown</span>
     <script type="text/javascript">
              host : '',
              principal : 'client',
              credentials : 'password'
          }).then(function(session) {
                  alert('Connected: ' + session.isConnected());

Replace ‘’ with the URL of your Diffusion Cloud service and ‘password’ with the password you defined for your user ‘client’. At the moment, the HTML page will pop up a dialogue box to let you know that the JavaScript client within connected successfully to Diffusion Cloud.

3. Subscribe to a JSON topic

Now to replace the notification box code with code that subscribes to a JSON topic when the client connects.

Before the diffusion.connect() call, add a new function called subscribeToJsonTopic():

function subscribeToJsonTopic(session) {

And call this function when the client successfully connects to Diffusion Cloud, by replacing what was in the then () call with this:


Now, when the client connects to Diffusion Cloud, instead of popping up a dialogue box it subscribes to the topic ‘topic/json’.

4. Use a value stream to receive the JSON value

At this point the example is subscribing to a topic, but not doing anything with the updates from it.

To receive updates from the JSON topic, create a stream and register it against the topic.

With JSON topics you can use streams known as value streams. Value streams are typed, and only receive updates from topics that have a matching type. Using value streams has the advantage that they cache the value of the last update. This means they can receive a diff from Diffusion Cloud, which describes only the difference between the new update and the cached value, and apply that diff to the cached value to get the new value. This reduces the amount of bytes sent across the network.

To register a value stream and receive updates from your JSON topic, ensure that you register it against the topic or against a topic in its path.

Back in the subscribeToJsonTopic() function, add the following code after the topic subscription:'topic/json').asType(diffusion.datatypes.json())
                            .on('value', function(topic, specification, newValue, oldValue) {
    console.log("Update for " + topic, newValue.get());

This causes the client to print the JSON value of the topic to the browser console whenever the value is updated.

5. Access the data in the JSON value using native JavaScript addressing

Just printing out all the JSON sent through the topic on the console is not very pretty (or useful). Maybe you want to access just one field in the JSON. JavaScript makes it easy to refer directly to these fields by their keys.

Say JSON published topic has the following format:

   "timestamp": 1461575476465,
        {"id": "0115", "pulse" : 81, "bp" : "127/87" },
        {"id": "0121", "pulse" : 68, "bp" : "124/83" }, 
        {"id": "0766", "pulse" : 73, "bp" : "133/89" }, 
        {"id": "1243", "pulse" : 92, "bp" : "138/90" }, 
        {"id": "1244", "pulse" : 62, "bp" : "119/77" } 

To get the value of the pulse field for the first patient in the list, you would use the following JavaScript:


Combine this with code to output to the area of the web page with the id ‘display’ to show that piece of data in the browser. Add the following line after or instead of the call to console.log:

document.getElementById('display').innerHTML = 


You can use the steps in this example to receive data from any JSON topic. To see it working though, you need a JSON topic that is being updated. Check out the companion post: “Publish to a JSON topic in 5 steps” to create and update a JSON topic from a Java client.

Watch a short video demo on how to publish and subscribe to Diffusion Cloud.

Want to see how easy it is to get started with Diffusion Cloud? Sign up for a free demo here.



Enjoy the rich functionality of Diffusion 6.7 as part of your event-driven application.

Quick Start Guide

Step-by-step guide to getting started.

Diffusion Cloud

SaaS offering that focuses on business.

Diffusion On-Premise

A pub-sub platform for real-time applications.