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

Rafael Angarita's avatar
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's avatar
rafaelangarita committed
6

Rafael Angarita's avatar
Rafael Angarita committed
7 8 9
* [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)
Rafael Angarita's avatar
Rafael Angarita committed
10 11
* [Messenger Persona](https://gitlab.inria.fr/usnb/facebook-bc)  - DEPRECATED: see Messenger Persona (Messenger Platform API) instead
* [Messenger Persona (Messenger Platform API)](https://gitlab.inria.fr/usnb/messenger-persona)
Rafael Angarita's avatar
Rafael Angarita committed
12
* [Slack Persona](https://gitlab.inria.fr/usnb/slack-persona)
Rafael Angarita's avatar
Rafael Angarita committed
13
* [Email Persona](https://gitlab.inria.fr/usnb/email-bc) - DEPRECATED: see Gmail Persona instead
Rafael Angarita's avatar
Rafael Angarita committed
14
* [Gmail Persona](https://gitlab.inria.fr/usnb/gmail-persona)
rafaelangarita's avatar
rafaelangarita committed
15

Rafael Angarita's avatar
Rafael Angarita committed
16 17 18 19
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's avatar
rafaelangarita committed
20

Rafael Angarita's avatar
Rafael Angarita committed
21 22 23

### Outgoing Work ###

Rafael Angarita's avatar
Rafael Angarita committed
24
We are currently working on specializing USNB for the online learning context with a social perspective. Social Learning Network (SLN) is considered as a type of social network among learners, teachers, and modules of learning. It encapsulates a wide variety of scenarios, in which learners can learn from each others through interaction.We are currently extending USNB for  supporting an Online Social Learning Network Services (OSLN), so that trainees may experiment concrete online participation (e.g., discussion together via the  Social Communication Bus) in relation with their training. Here, the online social learning network is a type of social network that results from interaction between learners, teachers, and modules of learning. (e.g., the Coursera and MOOC courses). In addition, increasing participant engagement (i.e., course completion time) has been investigated through integrating a recommendation system to USNB to offer appropriate study partners to learners. Offering appropriate study partners can encourage learners to be more active and stay in the courses. Last but not least, getting benefit from the user interactive environment provided by USNB, the learners can communicate to the recommended study partners through their social network messengers as well as the course forum.
Rafael Angarita's avatar
Rafael Angarita committed
25

Rafael Angarita's avatar
Rafael Angarita committed
26
Recently, we have specialized the Messenger and Slack personae. You can check them out in their respective repositories -see the links above-.
Rafael Angarita's avatar
Rafael Angarita committed
27 28 29



rafaelangarita's avatar
rafaelangarita committed
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
### 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's avatar
Rafael Angarita committed
49
## Usage ##
rafaelangarita's avatar
rafaelangarita committed
50

Rafael Angarita's avatar
Rafael Angarita committed
51
You will interact with the [API Gateway](https://gitlab.inria.fr/usnb/api-gateway) service. 
rafaelangarita's avatar
rafaelangarita committed
52

Rafael Angarita's avatar
Rafael Angarita committed
53
Suppose API Gateway location is http://localhost:3025 for the following examples.
rafaelangarita's avatar
rafaelangarita committed
54 55


Rafael Angarita's avatar
Rafael Angarita committed
56 57 58
### Entity Management ###

Register a user:
rafaelangarita's avatar
rafaelangarita committed
59 60

```
Rafael Angarita's avatar
Rafael Angarita committed
61
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita's avatar
Rafael Angarita committed
62 63 64 65
    "userId": "user@universe.u",
    "name": "Test User"
}' "http://localhost:3025/users"
```
rafaelangarita's avatar
rafaelangarita committed
66

Rafael Angarita's avatar
Rafael Angarita committed
67
Register social interaction services identities for that user:
rafaelangarita's avatar
rafaelangarita committed
68

Rafael Angarita's avatar
Rafael Angarita committed
69
```
Rafael Angarita's avatar
Rafael Angarita committed
70
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita's avatar
Rafael Angarita committed
71 72 73 74 75 76 77
    "userId": "user@universe.u",
    "serviceId": "facebookmessengerbot",
    "identity": "184858454541",
    "enabled": true
}' "http://localhost:3025/identities"


Rafael Angarita's avatar
Rafael Angarita committed
78
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita's avatar
Rafael Angarita committed
79 80 81 82 83
    "userId": "user@universe.u",
    "serviceId": "email",
    "identity": "user@universe.u",
    "enabled": true
}' "http://localhost:3025/identities"
rafaelangarita's avatar
rafaelangarita committed
84 85
```

Rafael Angarita's avatar
Rafael Angarita committed
86 87 88
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's avatar
rafaelangarita committed
89

Rafael Angarita's avatar
Rafael Angarita committed
90
Set the preferred social interaction for that user:
rafaelangarita's avatar
rafaelangarita committed
91 92

```
Rafael Angarita's avatar
Rafael Angarita committed
93
curl -X POST -H "Content-Type: application/json" -d '{
Rafael Angarita's avatar
Rafael Angarita committed
94 95 96 97 98 99
    "userId": "user@universe.u",
    "serviceId": "facebookmessengerbot"
}' "http://localhost:3025/preferences"
```

Change it:
rafaelangarita's avatar
rafaelangarita committed
100 101

```
Rafael Angarita's avatar
Rafael Angarita committed
102
curl -X PUT -H "Content-Type: application/json" -d '{
Rafael Angarita's avatar
Rafael Angarita committed
103 104 105 106 107 108 109
    "serviceId": "email"
}' "http://localhost:3025/preferences/user@universe.u"
```

### Direct Messaging ###

Send a direct message to our user:
rafaelangarita's avatar
rafaelangarita committed
110

Rafael Angarita's avatar
Rafael Angarita committed
111 112 113 114 115 116 117 118 119
```
curl -X POST -H "Content-Type: application/json" -d '{
  "to": {
    "name": "user@universe.u"
  },
  "message": {
    "text": "Are you there?"
  }
}' "http://localhost:3025/messages"
rafaelangarita's avatar
rafaelangarita committed
120 121 122

```

Rafael Angarita's avatar
Rafael Angarita committed
123 124 125
### Events, Subscriptions and Indirect Messaging ###

Create an event:
rafaelangarita's avatar
rafaelangarita committed
126 127

```
Rafael Angarita's avatar
Rafael Angarita committed
128
curl -X POST -H "Content-Type: application/json"  -d '{
Rafael Angarita's avatar
Rafael Angarita committed
129 130
    "eventId": "myEvent",
    "title": "One great event"
Rafael Angarita's avatar
Rafael Angarita committed
131 132 133 134
}' "http://localhost:3025/events"
```

Create a subscription for our user:
rafaelangarita's avatar
rafaelangarita committed
135

Rafael Angarita's avatar
Rafael Angarita committed
136 137
```
curl -X POST -H "Content-Type: application/json" -d '{ 
Rafael Angarita's avatar
Rafael Angarita committed
138 139
    "eventId": "myEvent", 
    "alertEndpoint": "user@universe.u"
Rafael Angarita's avatar
Rafael Angarita committed
140 141
}' "http://localhost:3025/subscriptions"
```
rafaelangarita's avatar
rafaelangarita committed
142

Rafael Angarita's avatar
Rafael Angarita committed
143
Send an indirect message to users subscribed to 'myEvent':
rafaelangarita's avatar
rafaelangarita committed
144 145

```
Rafael Angarita's avatar
Rafael Angarita committed
146 147 148 149 150 151 152 153 154 155
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's avatar
rafaelangarita committed
156

Rafael Angarita's avatar
Rafael Angarita committed
157 158 159
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's avatar
rafaelangarita committed
160 161 162


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

curl -X POST -H "Content-Type: application/json" -d '{ 
Rafael Angarita's avatar
Rafael Angarita committed
170 171 172
    "eventId": "myEvent", 
    "alertEndpoint": "user@universe.u", 
    "endpointType" : "facebookmessengerbot",
Rafael Angarita's avatar
Rafael Angarita committed
173 174 175 176 177 178 179 180 181
}' "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's avatar
rafaelangarita committed
182 183


Rafael Angarita's avatar
Rafael Angarita committed
184 185 186 187 188 189 190 191 192 193 194 195 196
```
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's avatar
rafaelangarita committed
197 198 199 200 201 202 203 204 205 206


### Contribution guidelines ###

You can contribute by:

* Writing tests
* Code review
* Writing new binding components

Rafael Angarita's avatar
Rafael Angarita committed
207 208 209 210 211 212 213 214 215

### 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's avatar
Rafael Angarita committed
216
 
Rafael Angarita's avatar
Rafael Angarita committed
217

rafaelangarita's avatar
rafaelangarita committed
218 219
### Who do I talk to? ###

Rafael Angarita's avatar
Rafael Angarita committed
220 221 222
* 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)