<abstract>This specification defines how to administer Multi-User Chat rooms and services using Ad-Hoc Commands.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0045</spec>
<spec>XEP-0050</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.0.1</version>
<date>2012-09-25</date>
<initials>psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>&xep0045; defines a widely-implemented XMPP extension for chatrooms. The MUC specification covers a number of common administrative use cases, such as kicking and banning users, granting voice, and changing user affiliations (moderator, admin, etc.). However, the protocols for these use cases are "hardcoded" and not as flexible or extensible as we might like. A more flexible approach would be to use &xep0050; (which did not exist when MUC was originally being developed) so that any implementation or deployment of a MUC service could define its own commands, as was done for core XMPP servers in &xep0133;. This specification defines such a framework for MUC services, including in-room administration as well as administration of the MUC service as a whole (e.g., banning users across all rooms).</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ul>
<li>Enable users with appropriate privileges to perform common administrative tasks with respect to Multi-User Chat rooms and services.</li>
<li>Re-use Ad-Hoc Commands for maximum flexibility.</li>
</ul>
</section1>
<section1topic='Discovery'anchor='disco'>
<p>A MUC service MUST advertise any administrative commands it supports via &xep0030; (as described in <cite>XEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service in question.</p>
<p>All supported Ad-Hoc Command nodes MUST be included in the &xep0115; hash generated by a MUC service.</p>
<p>The &xep0004; FORM_TYPE for MUC administration is "urn:xmpp:muc-admin". Fields defined in this specification are of the form "urn:xmpp:muc-admin:*". Particular implementations and deployments MAY define their own commands as fields to be included in data forms scoped by the "urn:xmpp:muc-admin" FORM_TYPE; in accordance with &xep0068;, the names of such fields SHOULD use &clark; (e.g., "{http://www.example.com/muc-admin}foo").</p>
</section1>
<section1topic='Use Cases'anchor='usecases'>
<p>This document defines a profile of <cite>XEP-0050: Ad-Hoc Commands</cite> that enables a MUC administrator to complete the use cases listed below. (Any overlap with existing administrative use cases currently defined in XEP-0045 is noted below.)</p>
<ol>
<li>Modify Room Subject</li>
<li>Set Occupant Role</li>
<li>Set User Affiliation</li>
<li>Assign Occupant Nickname</li>
<li>Clear Room History</li>
<li>Report a Spammer</li>
</ol>
<p>Some of these scenarios can apply to a single room or to multiple rooms. If the request is sent to a room JID (e.g., coven@chat.shakespeare.lit), then the interaction applies to that room only and the data form generated by the service might include a hidden field specifying the room. If the request is sent to the service's JID (e.g., chat.shakespeare.lit), the data form generated by the service might include a boolean flag specifying whether the interaction applies to all rooms on the service. The examples below illustrate these settings.</p>
<p>This use case provides the same functionality as the protocol described in Section 8.1 of XEP-0045. The following command sequence mirrors the examples in Section 8.1 of XEP-0045.</p>
<examplecaption='Admin Requests to Modify a Room Subject'><![CDATA[
<p>Unless an error occurs (see the <linkurl='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form. Notice that, since the request was sent to a particular room, the interaction applies to that room only (in this case, the data form includes an optional hidden field specifying the room).</p>
<examplecaption='Service Returns Modify Room Subject Form to Admin'><![CDATA[
<p>Notification of completion MAY include the processed data in a data form of type "result", although strictly speaking this is unnecessary since the subject change will be sent in the room.</p>
<p>This use case provides the same functionality as the protocol described in Sections 8.2, 8.3, and 8.4 of XEP-0045. However, the 'role' field is more easily extensible so that implementations can include their own values (e.g., a new role of "scribe"). The following command sequence mirrors the examples in Section 8.2 of XEP-0045.</p>
<examplecaption='Admin Requests to Modify an Occupant Role'><![CDATA[
<section2topic='Set User Affiliation'anchor='set-user-affiliation'>
<p>This use case provides the same functionality as the protocol described in Sections 9.1, 9.3, 9.4, 9.6, 9.7, 10.3, 10.4, 10.6, and 10.7 of XEP-0045. However, the 'affiliation' field is more easily extensible so that implementations can include their own values (e.g., a new affiliation of "creator"). The following command sequence mirrors the examples in Section 10.3 of XEP-0045.</p>
<examplecaption='Admin Requests to Modify a User Affiliation'><![CDATA[
<p>This use case enables a moderator or administrator to assign a new nickname to an occupant. This functionality can be helpful in situations where an occupant specifies or receives a temporary or inscrutable nickname on joining the room (e.g., "Call-In-User-7"), but the administrator wants to assign a more user-friendly nickname (e.g., "Peter Saint-Andre").</p>
<examplecaption='Admin Requests to Assign an Occupant Nickname'><![CDATA[
<section2topic='Report a Spammer'anchor='report-spammer'>
<p>This use case enables a moderator or administrator to report a particular user as a spammer. Typically such a report will trigger further events such as those described in &xep0268;.</p>
<examplecaption='Admin Requests to Report a Spammer'><![CDATA[
<p>Several error conditions are possible when an entity sends a command request to the service, as defined in the following table. If one of these error conditions occurs, the service MUST return an error stanza to the requesting entity.</p>
<tablecaption='Error Conditions'>
<tr>
<th>Condition</th>
<th>Cause</th>
</tr>
<tr>
<td>&conflict;</td>
<td>The command cannot be completed because of a data or system conflict (e.g., a user already exists with that username).</td>
</tr>
<tr>
<td>&feature;</td>
<td>The specific command is not supported (even though the ad-hoc commands protocol is).</td>
</tr>
<tr>
<td>&forbidden;</td>
<td>The requesting entity does not have sufficient privileges to perform the command.</td>
</tr>
<tr>
<td>¬allowed;</td>
<td>No entity is allowed to perform the command (e.g., retrieve the CEO's roster).</td>
</tr>
<tr>
<td>&unavailable;</td>
<td>The ad-hoc commands protocol is not supported.</td>
<p>For the syntax of these errors, see &xep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p>
<p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p>
<p>XEP-0068 defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. The reserved fields for the 'urn:xmpp:muc-admin' namespace are specified below.</p>
<codecaption='Registry Submission'><![CDATA[
<form_type>
<name>urn:xmpp:muc-admin</name>
<doc>XEP-xxxx</doc>
<desc>Forms used for administration of MUC rooms and services.</desc>
<fieldvar='newnick'
type='text-single'
label='The new nickname to be assigned to a room occupant'/>
<fieldvar='nick'
type='text-single'
label='The current nickname of a room occupant'/>
<fieldvar='roomjid'
type='jid-single'
label='The Jabber ID of MUC room'/>
<fieldvar='roomjids'
type='jid-multi'
label='The Jabber IDs of one or more rooms to which an operation applies'/>
<fieldvar='subject'
type='text-single'
label='The text of a room subject'/>
</form_type>
]]></code>
</section2>
</section1>
<section1topic='XML Schema'>
<p>Because the protocol defined here is a profile of <cite>XEP-0050: Ad-Hoc Commands</cite>, no schema definition is needed.</p>
