User Tools

Site Tools


sib:lstnclr

Example 1 - Listeners and callers

In this tutorial we will create a simple REST Listener and connect it to a General Caller which will return a message to the listener. For more information about the listener and caller concepts see the System Overview

File structure

  • Create the following directories in your workspace directory:
[workspace]/tut01/listener/mylistener/custom/
[workspace]/tut01/caller/mycaller/custom/

Project setup

The package.json file contains information about the project such as name, version, dependencies and scripts.

  • In the tut01-directory, create a file called package.json and add the following lines:
package.json
{
    "name": "tutorial01",
    "version": "1.0.0",
    "description": "My first SIB integration",
    "license": "UNLICENSED",
    "scripts": {},
    "dependencies": {
        "sib_restlistener": "^1.3.0",
        "sib_generalcaller": "^1.3.0"
    }
}

Notice the dependencies part. We are including the SIB components sib_restlistener and sib_generalcaller and stating that we want the latest versions that are compatible with version 1.3.0 of those. We will now install the SIB components by using the Node Package Manager.

  • In the tut01 directory, run the following command:
$ npm install

You now should have a new directory called node_modules containing the directories sib_restlistener and sib_generalcaller along with their sub dependencies.

Setting up a REST listener

We will now create the REST listener.

  • In the mylistener directory, create a file called mylistener.js. This file will be the starting point for the listener and in it we will create and start an instance of the sib_restlistener class as follows:
mylistener.js
var Listener = require("sib_restlistener");
new Listener(require("./custom/custom.js")).start();

Notice that we are creating an instance of the Listener using the new operator. We also provide the constructor of the class with the custom.js file (which we will create next). Lastly, we execute the start function of our listener instance.

REST listener custom configuration file

Our integration specific code for the listener will be in the custom.js file. In this wiki you can find template configuration files for all SIB components.

"use strict";

In the documentation you can find explanations for each of the fields and functions. We will go through a select few of them here.

port

Which port the service will listen to. Ports are specified for each environment (DEV, TEST, QA, PROD). In this example we will use the default environment - DEV. You can leave the port configuration as it is.

inputFormat

The inputFormat function is called each time the listener receives a request. This is where we format the input message into an internal SIB format that can be interpreted by our callers. The function takes three parameters:

  1. the mqtt topic that the message will be published to on the internal mqtt transport
  2. the message to publish
  3. callback function that takes the formatted message
  • Rewrite the inputFormat function so that it looks like this:
custom.js
inputFormat: (topic, msg, cb)=>{
    let query = msg.request.purl.q;    
    let formattedMsg = {
        _sibheader: msg._sibheader,
        fmtedkey: query.key === "value" ? true : false
    };
 
    cb(formattedMsg);
}

Notice that we include the _sibheader from the original message in our formatted message. The _sibheader contains information about mqtt topics, correlation id and more. It is mandatory to always include the _sibheader in every message.

topic

The topic field of the listener contains the topic to push messages to on the internal mqtt.

  • Set the topic to “SIB/TUTORIAL01/MSG”

Setting up a general caller

We will now create the General caller. In this example the caller will simply return a message depending on the input. In a real situation, of course, the caller would call some other system and then return the response.

General callers are the simplest caller type - it really does not do much. Instead it is up to the developer to write code in the getData function. You may notice that there is currently no RESTCaller implemented in the SIB. This is because http requests are so easy to make in NodeJS, so we have been using the general caller for this type of functionality.

  • In the mycaller directory, create a file called mycaller.js. This file will be the starting point for the caller and in it we will create and start an instance of the sib_generalcaller class as follows:
mycaller.js
var Caller = require("sib_generalcaller");
new Caller(require("./custom/custom.js")).start();

General caller custom configuration file

"use strict";

Make the following changes in the caller custom.js file:

getData

Rewrite the getData function to look like this:

getData: (topic, msg, cb)=>{
    let rspMsg = {
        success: true,
        message: msg.fmtedkey ? "Result is true" : "Result is false",
        _sibheader: msg._sibheader
    };
    cb(rspMsg);
}
inputFormat

Add the following row as the first row of the inputFormat function:

if(topic.indexOf("/RESPONSE") > -1) return null;

This tells the caller not to pickup and process its own response.

topic

The topic field of the caller contains the topic to subscribe to on the internal mqtt transport.

  • Set the topic to SIB/TUTORIAL01/#

Starting the integration

Using the node command

The easiest way to start the integration components is by using the node command. It might be a good idea to run them in this way for debugging purposes.

In the mylistener directory type:

$ node mylistener.js

Then do the same thing for the caller in a separate console.

Using pm2

For starting integrations and keeping them running continuously we use the Node Process Manager, pm2. To the REST listener using pm2, go to the mylistener directory and type:

$ pm2 start mylistener.js --name "SIB:Tutorial01.RESTListener"

To get a list of processes running in pm2 type:

$ pm2 list

And to stop a pm2 process type:

$ pm2 stop [process name or id]

The id used is the id displayed when running pm2 list.

Testing

To test the integration, make sure both the listener and caller are running. Then use your favorite tool for handling REST to send a request to the listener (eg. ARC - Advanced REST Client, or Postman etc).

The url should look like http://[hostname]:8818?key=value

This should result in a message saying “Result is true”. Any other value for the key parameter should result in a message saying “Result is false”. Not providing any key parameter should result in an error message saying that the parameter is missing.

Self study

Congratulations! You are now a fully fledged SIB developer! You should now be able to create your own instances of the SIB listeners and callers. If you want to try something for yourself I would suggest creating another listener or caller and connecting it to the components we have already created.

For instance, create an mqtt listener that publishes messages in the same format as the REST listener on the same topic.

sib/lstnclr.txt · Last modified: 2019/08/28 07:12 by ozzy