Emanagement guide

Emanagement it's a ruby script that provides important functions to manage ejabberd rosters and other features using ejabberdctl, a control interface of Ejabberd server, designed to help the administrator control the functioning of the running ejabberd daemon.

 
We assume that the reader has some knowledge in XMPP protocol, otherwise, take a look at the XMPP RFC.

• Jabber Identifiers (JIDs) uniquely identify individual entities in the Jabber network. Read more.

• In XMPP, one's contact list is called a roster, which consists of any number of specific roster items, each roster item being identified by a unique JID (usually of the form contact@domain). A user's roster is stored by the user's server on the user's behalf so that the user may access roster information from any resource.

• In order to protect the privacy of instant messaging users and any other entities, presence and availability information is disclosed only to other entities that the user has approved. When a user has agreed that another entity may view its presence, the entity is said to have a subscription to the user's presence information.
   
  Subscription types::
  -> none: The user does not have a subscription to the contact's presence information, and the contact does not have a subscription to the user's presence information.
  -> to: The user has a subscription to the contact's presence information, but the contact does not have a subscription to the user's presence information.
  -> from: The contact has a subscription to the user's presence information, but the user does not have a subscription to the contact's presence information.
  -> both: Both the user and the contact have subscriptions to each other's presence information.

 

As we can see in the Social Stream Presence architecture scheme, our Xmpp Server only stores users's roster, it don't stores usernames and passwords, the authentication service is provided by the Social Stream Rails Application, therefore we will not have registered users in our xmpp server.
In Social Stream, the user's JID has the following structure: slug@domain .
Social Stream user's slug is building from the name, converting it to lowercase and replacing spaces with underscores. For example, if the user name is "Jonh Doe", the slug will be "jonh-doe".
If a user wants to know his slug, he can visit http://domain/api/me after log in, and get it from the slug's tag <slug>user's slug</slug>.

Shoulders to the wheel!

1. Reflect Social Stream's contacts to rosters.
2. Managing rosters with Emanagement
3. Option 3
4. Option 4
5. Option 5

 

Reflect Social Stream's contacts to rosters

We assume that the reader is already familiar with Social Stream Base.

• A contact is a link between two actors.
• Each contact has many ties, which determine the kind of the link through relations.
• Each activity is attached to a contact. The sender of the contact is the author of the activity and the receiver actor of the contact is the receiver of the activity.

 

In this guide, in a simple way, we will only differentiate between two types of contacts:

• Unidirectional: When the contact in the other way isn't established (or negative replied).
• Bidirectional: When the contact in the other way is established and positive replied.
   

When the unidirectional contact is established the sender ( User A ) adds the receiver ( User B ) to his roster with subscription type from.
When the unidirectional contact is established and positive replied in the other way, the bidirectional contact is established. In this case the sender adds the receiver to his roster with subscription type both and the receiver adds the sender to his roster with subscription type both too.

Unidirectional Social Stream contacts are reflected to xmpp rosters using this emagement function:
addBuddyToRoster userSid buddySid buddyNick buddyGroup subscription_type
that can be executed by this ruby function:
SocialStream::Presence::XmppServerOrder::addBuddyToRoster(userSid,buddySid,buddyNick,buddyGroup,subscription_type)

Bidirectional Social Stream contacts are reflected to xmpp rosters using this emagement function:
setBidireccionalBuddys userASid userBSid userANick userBNick groupForA groupForB
that can be executed by this ruby function:
SocialStream::Presence::XmppServerOrder::setRosterForBidirectionalTie(userASid,userBSid,userANick, userBNick,groupForA,groupForB)

A buddy it's just a roster item, a contact added to a roster.

Managing rosters with Emanagement

When a Social Stream contact is created or updated, the corresponding emanagement function will be called automatically, and the changes will be reflected in the ejabberd database.
However, emanagement provides more functions to manage rosters, that can help us in testing and maintenance tasks.

addBuddyToRoster userSid buddySid buddyNick buddyGroup subscription_type
removeBuddyFromRoster userSid buddySid
setBidireccionalBuddys userASid userBSid userANick userBNick groupForA groupForB
unsetBidireccionalBuddys userSid oldFriendSid oldFriendNick groupForOldFriend
getRoster username
removeRoster username
removeAllRosters
getAllUsersWithRoster
printAllRosters
printAllBidirecctionalBuddys

For example, to get the roster of a user with slug demo:

admin@localhost:~/ejabberd_scripts$ ./emanagement getRoster demo
------------------------
Init Ejabberd Maintenance script
------------------------
pamela-hall@localhost	Pamela	both	none	SocialStream
terry-alvarez@localhost	Terry	both	none	SocialStream
lois-johnson@localhost	Lois	both	none	SocialStream

Coming soon...