README.md 7.89 KB
Newer Older
Rafael Angarita committed
1
# Universal Social Network Bus (USNB)#
rafaelangarita committed
2

Rafael Angarita committed
3 4 5
Computer-mediated communication can be defined as any form of human communication achieved through computer technology. From its beginnings, it has been shaping the way humans interact with each other, and it has influenced many areas of society. There exist a plethora of social interaction services enabling computer-mediated social communication (e.g., Skype, Facebook Messenger, Telegram, WhatsApp, Twitter, Slack, etc.). Based on personal preferences, users may prefer a social interaction services rather than another. As a result, users sharing same interests may not be able to interact since they are using incompatible technologies. To tackle this interoperability barrier, we propose USNB, a middleware solution targeted to enable the interaction via heterogeneous social interaction services.

USNB is composed by set of service components. You can use one or more of the following service components according to your needs:
rafaelangarita committed
6

Rafael Angarita committed
7 8 9 10 11 12
* [API Gateway](https://gitlab.inria.fr/usnb/api-gateway)
* [Entity Manager](https://gitlab.inria.fr/usnb/entity-manager)
* [Message Transformer](https://gitlab.inria.fr/usnb/message-transformer)
* [Facebook Binding Component (No Messenger Platform)](https://gitlab.inria.fr/usnb/facebook-bc)
* [Facebook Binding Component (Messenger Platform)](https://gitlab.inria.fr/usnb/facebook-bc-bot-appcivist)
* [Email Binding Component](https://gitlab.inria.fr/usnb/email-bc)
rafaelangarita committed
13

Rafael Angarita committed
14 15 16 17
This README contains the necessary steps to get the USNB up and running. If you want to read more about USNB, check the following articles:

* Rafael Angarita, Nikolaos Georgantas, Cristhian Parra, James Holston, Valérie Issarny. [Leveraging the Service Bus Paradigm for Computer-mediated Social Communication Interoperability](https://hal.inria.fr/hal-01485213). Proc. Software Engineering in Society Track at ICSE’2017. https://hal.inria.fr/hal-01485213.
* Rafael Angarita, Nikolaos Georgantas, Valérie Issarny. [USNB: Enabling Universal Online Social Interactions](https://hal.inria.fr/hal-01591757/). Proc. 3rd IEEE Conference on Collaboration and Internet Computing (Best Paper Award). https://hal.inria.fr/hal-01591757.
rafaelangarita committed
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

### Setup ###

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

* [RabbitMQ](https://www.rabbitmq.com)
* [Nodejs](https://nodejs.org/) and [NPM (Node Package Manager)](https://www.npmjs.org/)
* [pm2](http://pm2.keymetrics.io/docs/usage/quick-start/) 
* [MongoDB](https://www.mongodb.com)

### Deployment ###

You can deploy the USNB components using whatever method you prefer; however, we recommend using the [pm2](http://pm2.keymetrics.io/docs/usage/quick-start/) 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:

![Screen Shot 2017-06-15 at 16.08.57.png](https://bitbucket.org/repo/XX5zzkb/images/1938485544-Screen%20Shot%202017-06-15%20at%2016.08.57.png)


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

Rafael Angarita committed
38
## Usage ##
rafaelangarita committed
39

Rafael Angarita committed
40
You will interact with the [API Gateway](https://gitlab.inria.fr/usnb/api-gateway) service. 
rafaelangarita committed
41

Rafael Angarita committed
42
Suppose API Gateway location is http://localhost:3025 for the following examples.
rafaelangarita committed
43 44


Rafael Angarita committed
45 46 47
### Entity Management ###

Register a user:
rafaelangarita committed
48 49

```
Rafael Angarita committed
50
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita committed
51 52 53 54
    "userId": "user@universe.u",
    "name": "Test User"
}' "http://localhost:3025/users"
```
rafaelangarita committed
55

Rafael Angarita committed
56
Register social interaction services identities for that user:
rafaelangarita committed
57

Rafael Angarita committed
58
```
Rafael Angarita committed
59
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita committed
60 61 62 63 64 65 66
    "userId": "user@universe.u",
    "serviceId": "facebookmessengerbot",
    "identity": "184858454541",
    "enabled": true
}' "http://localhost:3025/identities"


Rafael Angarita committed
67
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita committed
68 69 70 71 72
    "userId": "user@universe.u",
    "serviceId": "email",
    "identity": "user@universe.u",
    "enabled": true
}' "http://localhost:3025/identities"
rafaelangarita committed
73 74
```

Rafael Angarita committed
75 76 77
In the case of Facebook Messenger, it will be the bot itself who will register
the Facebook Messenger identity following [checkbox plugin](https://developers.facebook.com/docs/messenger-platform/plugin-reference/checkbox-plugin)
or the [account linking](https://developers.facebook.com/docs/messenger-platform/account-linking/v2.10) processes.
rafaelangarita committed
78

Rafael Angarita committed
79
Set the preferred social interaction for that user:
rafaelangarita committed
80 81

```
Rafael Angarita committed
82
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita committed
83 84 85 86 87 88
    "userId": "user@universe.u",
    "serviceId": "facebookmessengerbot"
}' "http://localhost:3025/preferences"
```

Change it:
rafaelangarita committed
89 90

```
Rafael Angarita committed
91
curl -X PUT -H "Content-Type: application/json" -d '{
Rafael Angarita committed
92 93 94 95 96 97 98
    "serviceId": "email"
}' "http://localhost:3025/preferences/user@universe.u"
```

### Direct Messaging ###

Send a direct message to our user:
rafaelangarita committed
99

Rafael Angarita committed
100 101 102 103 104 105 106 107 108
```
curl -X POST -H "Content-Type: application/json" -d '{
  "to": {
    "name": "user@universe.u"
  },
  "message": {
    "text": "Are you there?"
  }
}' "http://localhost:3025/messages"
rafaelangarita committed
109 110 111

```

Rafael Angarita committed
112 113 114
### Events, Subscriptions and Indirect Messaging ###

Create an event:
rafaelangarita committed
115 116

```
Rafael Angarita committed
117
curl -X POST -H "Content-Type: application/json"  -d '{
Rafael Angarita committed
118 119
    "eventId": "myEvent",
    "title": "One great event"
Rafael Angarita committed
120 121 122 123
}' "http://localhost:3025/events"
```

Create a subscription for our user:
rafaelangarita committed
124

Rafael Angarita committed
125 126
```
curl -X POST -H "Content-Type: application/json" -d '{ 
Rafael Angarita committed
127 128
    "eventId": "myEvent", 
    "alertEndpoint": "user@universe.u"
Rafael Angarita committed
129 130
}' "http://localhost:3025/subscriptions"
```
rafaelangarita committed
131

Rafael Angarita committed
132
Send an indirect message to users subscribed to 'myEvent':
rafaelangarita committed
133 134

```
Rafael Angarita committed
135 136 137 138 139 140 141 142 143 144
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, 'user@universe.u' will receive the message through the
social interaction service specified in: 'http://localhost:3025/preferences/user@universe.u'
rafaelangarita committed
145

Rafael Angarita committed
146 147 148
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:
rafaelangarita committed
149 150 151


```
Rafael Angarita committed
152
curl -X POST -H "Content-Type: application/json" -d '{ 
Rafael Angarita committed
153 154 155
    "eventId": "myEvent", 
    "alertEndpoint": "user@universe.u", 
    "endpointType" : "email",
Rafael Angarita committed
156 157 158
}' "http://localhost:3025/subscriptions"

curl -X POST -H "Content-Type: application/json" -d '{ 
Rafael Angarita committed
159 160 161
    "eventId": "myEvent", 
    "alertEndpoint": "user@universe.u", 
    "endpointType" : "facebookmessengerbot",
Rafael Angarita committed
162 163 164 165 166 167 168 169 170
}' "http://localhost:3025/subscriptions"
```

In this case, user 'user@universe.u' 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:
rafaelangarita committed
171 172


Rafael Angarita committed
173 174 175 176 177 178 179 180 181 182 183 184 185
```
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.
rafaelangarita committed
186 187 188 189 190 191 192 193 194 195


### Contribution guidelines ###

You can contribute by:

* Writing tests
* Code review
* Writing new binding components

Rafael Angarita committed
196 197 198 199 200 201 202 203 204

### License ###

 This software is provided under a dual license model designed to meet the 
 development and distribution needs of both commercial usage and open source 
 projects.
 
 If you intend to use this software for commercial purposes, contact the project
 members presented in the next section.
Rafael Angarita committed
205
 
Rafael Angarita committed
206

rafaelangarita committed
207 208
### Who do I talk to? ###

Rafael Angarita committed
209 210 211
* 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)