Rosters Component

From OnSIP Developer Wiki
Jump to: navigation, search

Contents

Overview

The Junction Networks XMPP API can be used to request roster suggestions for ANY XMPP client that is compliant with XEP 0144: Roster Item Exchange. The roster item exchange XEP specifies a mechanism for 3rd party XMPP entities (in this case the Junction Networks XMPP API Rosters Component) to suggest additions, modifications, and deletions to an XMPP client's roster. The suggestions that the Rosters Component will make will be those users in your authorized Junction Networks domains. For instance, when bob@acme.com authenticates with the Junction Networks XMPP API and then requests roster information for the first time, he will receive a series of roster add requests for every user in his organization. The next time he requests roster information he will only receive deltas, that is, add requests of any new users since his last request, modify requests for any user's who have changed contact information, and delete requests for any users who may have been deleted.

Note: commands.rosters.xmpp.onsip.com will only send roster item suggestions to your XMPP client. Only after your XMPP Client uses the suggestions to make the appropriate roster management request back to your XMPP server, will the items be modified in your roster. Please read RFC 3921: Roster Management for more information about making changes to your roster. Specifically sections 7.4 (Adding a Roster Item), 7.5 (Updating a Roster Item), and 7.6 (Deleting a Roster Item).

JID

commands.rosters.xmpp.onsip.com

Command Nodes


push-roster-groups

Request for Roster Item Exchange information to be sent to the requesting XMPP client.

Authorization Requirements

Roster groups will be pushed down for each domain a JID is authorized in at the time of the request. If JID xmpp:bob@acme.com has authorized for SIP addresses bob@acme.com and bob@example.com then the push-roster-groups request will send roster suggestions for both the acme.com AND example.com domains.

Input Fields

jid 
(optional) full JID to push roster groups to, if not provided the JID in the IQ from attribute will be assumed

Single Stage Execution

In order to receive roster suggestions based on your OnSIP SIP domain you may execute this command node in a single step. Submit an ad-hoc request with input fields named above to the commands.rosters.xmpp.onsip.com component. The jid parameter is optional, if submitted the parameter can be used to push a third party JID it's roster item suggestions. In the normal case of authorizing the requesting JID however, the parameter may be excluded.

Request to commands.rosters.xmpp.onsip.com

<iq type="set" to="commands.rosters.xmpp.onsip.com" id="aacea" >
  <command xmlns="http://jabber.org/protocol/commands" node="push-roster-groups" />
</iq>

Multi-stage Execution

N/A

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

Upon a successful execution of the authorize-plain command an IQ type result is returned a command node with status completed. Asynchronous to the IQ result however the requester may receive 0 or 1 rosterx item add, modify, or delete requests. Please see XEP 0144: Roster Item Exchange for the rules of syntax regarding Roster Item Exchange requests. The commands.rosters.xmpp.onsip.com service only implements Roster Item Exchange over IQ.

Response Fields

N/A

Successful Response
<iq from="commands.rosters.xmpp.onsip.com" type="result" 
    to="foo!example.onsip.com@dashboard.onsip.com/theresource" id="aacea" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed" 
           node="push-roster-groups" sessionid="9a69e10043633f67a45ae63d1a1e504f" />
</iq>

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response

N/A

Additional Information

The commands.rosters.xmpp.onsip.com service only implements Roster Item Exchange over IQ. Please see XEP 0144: Roster Item Exchange for more information regarding syntax and semantics. Also for information on how to correctly handle roster modifications please see the roster management section of RFC 3921.

Roster Add Requests
<iq from="commands.rosters.xmpp.onsip.com" type="set" 
    to="foo!example.onsip.com@dashboard.onsip.com/theresource" id="1696" >
  <x xmlns="http://jabber.org/protocol/rosterx">
    <item action="add" name="Darth Vader" jid="anakin.skywalker@example.onsip.com" >
      <group>example.onsip.com</group>
    </item>
    <item action="add" name="Darth Sidious" jid="emperor.palpatine@example.onsip.com" >
      <group>example.onsip.com</group>
    </item>
  </x>
</iq>

Being a request/response mechanism - all IQ requests must be accompanied by some response. An appropriate client response to the add here is

<iq type="result" to="commands.rosters.xmpp.onsip.com" id="1696" />
Roster Modify Requests
<iq from="commands.rosters.xmpp.onsip.com" type="set" 
    to="foo!example.onsip.com@dashboard.onsip.com/theresource" id="3334" >
  <x xmlns="http://jabber.org/protocol/rosterx">
    <item action="modify" name="Darth Dizzle Vader" jid="anakin.skywalker@example.onsip.com" >
      <group>example.onsip.com</group>
    </item>
  </x>
</iq>
RosterX Delete Requests
<iq from="commands.rosters.xmpp.onsip.com" type="set" 
    to="enoch!example.onsip.com@dashboard.onsip.com/theresource" id="4907" >
  <x xmlns="http://jabber.org/protocol/rosterx">
    <item action="delete" name="Darth Dizzle Vader" jid="anakin.skywalker@example.onsip.com" >
      <group>example.onsip.com</group>
    </item>
  </x>
</iq>
Personal tools