Universal Social Network Bus (USNB)#

USNB is a set of service components. You can use one or more of the following service components according to your needs:

• API Gateway: API proxy to all others.
• Entity Manager: manages users and identities.
• Subscription Manager: manages notifications based on subscriptions to events that are signaled from an external system.
• Message Transformer: transforms messages for each binding component
• Facebook Binding Component (No Messenger Platform): sends messages to facebook
• Facebook Binding Component (Messenger Platform): sends messages to facebook using messenger platform
• Email Binding Component: send messages via emails

This README contains the necessary steps to get the USNB up and running.

Setup

If you want to use all available USNB components, you have to install the following:

• RabbitMQ
• Nodejs and NPM (Node Package Manager)
• pm2
• MongoDB

Deployment

You can deploy the USNB components using whatever method you prefer; however, we recommend using the pm2 process manager for node.js. You can find in the folder deploy scripts for each one of the available components and a script to run them all called deploy.sh.

You just have to configure these scripts according to your environment. When you deploy all components, you should see them running in pm2.

1. Make a copy of the deploy folder under the deploy_X (e.g., deploy_local). Every deploy_* is ignored by git.
2. Modify each *.ecosystem.config.js script with credential details (email, facebook, etc.)
3. Replace /path/to/local/production/deployment/directory/ and /path/to/local/development/deployment/directory/ with the paths of your local production and development directories. Make sure your user has write access in these directories. The deploy script will automatically clone each component into it before running the scripts.
4. Replace /path/to/local/deploy/scripts with the path to your local version of the deploy directory.
5. Make also sure of updating the 'post-deploy' variable of each initialization script to correctly point out to your local deployment folders and initialization scripts.
6. Run deploy.sh specifying the environment as a parameter (dev, production)

$ ./deploy.hs dev

5. Check that all components are running via pm2:

$ pm2 list

There is also [another file](Link URL) containing all the required environment variables of all components if you don't want to use pm2.

Usage

You will interact with the API Gateway service.

Suppose API Gateway location is http://localhost:3025 for the following examples.

Entity Management

Register a user:

curl -X POST -H "Content-Type: application/json" -d '{
    "userId": "[email protected]",
    "name": "Test User"
}' "http://localhost:3025/users"

Register social interaction services identities for that user:

curl -X POST -H "Content-Type: application/json" -d '{
    "userId": "[email protected]",
    "serviceId": "facebookmessengerbot",
    "identity": "184858454541",
    "enabled": true
}' "http://localhost:3025/identities"


curl -X POST -H "Content-Type: application/json" -d '{
    "userId": "[email protected]",
    "serviceId": "email",
    "identity": "[email protected]",
    "enabled": true
}' "http://localhost:3025/identities"

In the case of Facebook Messenger, it will be the bot itself who will register the Facebook Messenger identity following checkbox plugin or the account linking processes.

Set the preferred social interaction for that user:

curl -X POST -H "Content-Type: application/json" -d '{
    "userId": "[email protected]",
    "serviceId": "facebookmessengerbot"
}' "http://localhost:3025/preferences"

Change it:

curl -X PUT -H "Content-Type: application/json" -d '{
    "serviceId": "email"
}' "http://localhost:3025/preferences/[email protected]"

Direct Messaging

Send a direct message to our user:

curl -X POST -H "Content-Type: application/json" -d '{
  "to": {
    "name": "[email protected]"
  },
  "message": {
    "text": "Are you there?"
  }
}' "http://localhost:3025/messages"

Events, Subscriptions and Indirect Messaging

Create an event:

curl -X POST -H "Content-Type: application/json"  -d '{
    "eventId": "myEvent",
    "title": "One great event"
}' "http://localhost:3025/events"

Create a subscription for our user:

curl -X POST -H "Content-Type: application/json" -d '{ 
    "eventId": "myEvent", 
    "alertEndpoint": "[email protected]"
}' "http://localhost:3025/subscriptions"

Send an indirect message to users subscribed to 'myEvent':

curl -X POST -H "Content-Type: application/json" -d '{
    "eventId": "myEvent", 
    "title": "This is the title of the signal", 
    "text": "this is the body of the signal", 
    "instancedata": "User defined metadata"
}' "http://localhost:3025/signals"

In this example, '[email protected]' will receive the message through the social interaction service specified in: 'http://localhost:3025/preferences/[email protected]'

If it's really necessary, you can associate a subscription to a particular social interaction service; for example, you can create one email and one Facebook Messenger subscription to our event:

curl -X POST -H "Content-Type: application/json" -d '{ 
    "eventId": "myEvent", 
    "alertEndpoint": "[email protected]", 
    "endpointType" : "email",
}' "http://localhost:3025/subscriptions"

curl -X POST -H "Content-Type: application/json" -d '{ 
    "eventId": "myEvent", 
    "alertEndpoint": "[email protected]", 
    "endpointType" : "facebookmessengerbot",
}' "http://localhost:3025/subscriptions"

In this case, user '[email protected]' will receive the same message by both email and Facebook Messenger.

You can send the message only to users subscribed using a certain service using the 'filterBy' option; for example, send the signal only to subscriptions using email:

curl -X POST -H "Content-Type: application/json" -d '{
    "eventId": "myEvent", 
    "title": "This is the title of the signal", 
    "text": "this is the body of the signal", 
    "instancedata": "User defined metadata",
    "filterBy": "email"
}' "http://localhost:3025/signals"

The 'filterBy' option has no effect if there are users subscribed to the corresponding event without social interaction services explicetily associated to that subscription.

Contribution guidelines

You can contribute by:

• Writing tests
• Code review
• Writing new binding components

Who do I talk to?

• Rafael Angarita: rafael.angarita AT inria.fr (main developer)
• Nikolaos Georgantas nikolaos.georgantas AT inria.fr (designer)
• Valérie Issarny valerie.issarny AT inria.fr (designer)