XEP-0406: Mediated Information eXchange (MIX): MIX Administration

Table 1: Standard MIX Nodes

3.1.1 Roles

There are a number of MIX roles for each channel, listed in the following table. Rights will be assigned to the various roles in the channel configuration node.

3.1.2 Allowed

This node represents a list of JIDs that are allowed to become participants. If the Allowed node is not present, all JIDs are allowed. This node is accessed and managed using standard pubsub. The Allowed list is always considered in conjunction with the banned list, stored in the banned node. Only Administrators and Owners have write permission to the Allowed node and are also the only roles that are allowed to subscribe to this node. The Allowed node is a permanent node. Each item contains a real bare JID. The following example shows how the Allowed list can specify single JIDs and domains.

Example 1. Allowed Node

<items node='urn:xmpp:mix:nodes:allowed'>
  <item id='shakespeare.example'/>
  <item id='alice@wonderland.example'/>
</items>

3.1.3 Banned

This node represents a list of JIDs that are explicitly not allowed to become participants. The values in this list take priority over values in the Allowed node. This node is accessed and managed using standard pubsub Only Administrators and Owners have write permission to the Banned node and are also the only roles that are allowed to subscribe to this node. Each item contains a real bare JID. The Banned node can contain bare JIDs and/or domains. The Banned node is a permanent node.

Example 2. Banned Node

<items node='urn:xmpp:mix:nodes:banned'>
  <item id='lear@shakespeare.example'/>
  <item id='macbeth@shakespeare.example'/>
</items>

3.1.4 Configuration Node

The Configuration node holds the configuration of the channel as a single item, named by the date-time of the last update to the configuration. The Configuration node is a permanent node with a maximum of one item. Previous configuration history MAY be accessed by MAM. Users with read access to the configuration node MAY subscribe to the configuration node to get notification of configuration change. This node is accessed and managed using standard pubsub. The configuration node is OPTIONAL for a MIX channel. For example, configuration choices could be fixed and not exposed. A subset of the defined configuration options MAY be used and additional non-standard configuration options MAY be added. JIDs in the configuration MUST be real bare JIDs and not proxy JIDs. If configuration options to control functionality of the nature described here are provided, the options defined in this standard MUST be used. The following configuration attributes are defined:

The configuration node is in Data Forms (XEP-0004) [2] format and includes all of the options used by the channel, including values for options using default values. This means that the value in the form can be directly mapped with the form returned by configuration administration commands. Configuration nodes will typically have a large number of elements. The following short example is provided to illustrate the syntax of the configuration node.

Example 3. Configuration Node

<items node='urn:xmpp:mix:nodes:config'>
  <item id='2016-05-30T09:00:00'>
      <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:1</value>
        </field>
        <field var='Owner'>
            <value>hecate@shakespeare.example</value>
            <value>greymalkin@shakespeare.example</value>
        </field>
        <field var='Messages Node Subscription'>
           <value>allowed</value>
         </field>
         <field var='No Private Messages'>
            <value>true</value>
         </field>
         </x>
  </item>
</items>

4.1.1 Creating a Channel

Example 4. Creating a Channel with Client Specified Parameters

<iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
  <create channel='coven' xmlns='urn:xmpp:mix:1'>
     <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:1</value>
        </field>
        <field var='Owner'>
            <value>hecate@shakespeare.example</value>
            <value>greymalkin@shakespeare.example</value>
        </field>
        <field var='Messages Node Subscription'>
           <value>allowed</value>
         </field>
        <field var='JID Visibility'>
           <value>jid-mandatory-visible</value>
         </field>
         <field var='No Private Messages'>
            <value>true</value>
         </field>
         </x>
  </create>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
  <create channel='coven' xmlns='urn:xmpp:mix:1'/>
</iq>

4.1.2 Modifying Channel Information

Authorized users, typically owners and sometimes administrators, MAY modify the channel information. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the information node. The values in the form show current values, which be defaults or MAY have been explicitly set. In the following example, the channel name was previously set, but other values were not.

Example 5. Getting Information Form

 <iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
     <pubsub xmlns='http://jabber.org/protocol/'>
         <items node='urn:xmpp:mix:nodes:info'/>
     </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/'>
     <items node='urn:xmpp:mix:nodes:info'>
       <item>
         <x xmlns='jabber:x:data' type='form'>
           <field var='FORM_TYPE' type='hidden'>
             <value>urn:xmpp:mix:1</value>
           </field>
           <title>Information Node Modification</title>
           <field type='text-multi'
                  label='Channel Name'
                   var='Name'>
              <value>Witches Coven</value>
            </field>
            <field type='text-multi'
                   label='Channel Description'
                   var='Description'/>
             <field type='jid-single'
                    label='Channel Administrative Contact'
                    var='Contact'/>
          </x>
      </item>
    </items>
  </pubsub>
</iq>

Example 6. Modifying Channel Information

 <iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
     <publish node='urn:xmpp:mix:nodes:info'>
       <items>
          <item>
            <x xmlns='jabber:x:data' type='submit'>
              <field var='FORM_TYPE' type='hidden'>
                <value>urn:xmpp:mix:1</value>
              </field>
              <field var='Name'>
                 <value>Witches Coven</value>
              </field>
              <field var='Description'>
                 <value>A location not far from the blasted heath where
                        the three witches meet</value>
              </field>
              <field var='Contact'>
                 <value>greymalkin@shakespeare.example</value>
              </field>
           </x>
         </item>
       </items>
     </publish>
  </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:info'>
        <items>
           <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'/>
         </items>
       </publish>
   </pubsub>
</iq>

4.1.3 Modifying Channel Configuration

Channel owners are allowed to modify the channel configuration. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the configuration node. Other clients MAY be authorized to use this command to see the channel configuration, but only owners MAY update the configuration. The values in the form show current values, which MAY be defaults or MAY have been explicitly set. The following example shows a short form returned to illustrate the syntax. A typical configuration form will be much larger with many fields. Modifying channel configuration is done directly by a client. Note that an Owner MUST be specified. When the configuration node is modified, the server MUST set the 'Last Change Made By' attribute to the JID of the user making the change.

Example 7. Getting Configuration Form

 <iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <items node='urn:xmpp:mix:nodes:config'/>
     </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
     <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <items xmlns='urn:xmpp:mix:1'  node='urn:xmpp:mix:nodes:config'>
        <item>
          <x xmlns='jabber:x:data' type='form'>
            <field var='FORM_TYPE' type='hidden'>
              <value>urn:xmpp:mix:1</value>
            </field>
              <title>Configuration Node Modification</title>
            <field type='jid-multi'
                   label='Channel Administrator'
                   var='Administrator'/>
          </x>
        </item>
     </items>
   </pubsub>
</iq>

Example 8. Modifying Channel Configuration

 <iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:config'>
        <items>
          <item>
            <x xmlns='jabber:x:data' type='submit'>
              <field var='FORM_TYPE' type='hidden'>
                 <value>urn:xmpp:mix:1</value>
              </field>
              <field var='Owner'>
                 <value>hecate@shakespeare.example</value>
                 <value>greymalkin@shakespeare.example</value>
              </field>
              <field var='Messages Node Subscription'>
                <value>allowed</value>
              </field>
              <field var='JID Visibility'>
                <value>jid-mandatory-visible</value>
              </field>
              <field var='No Private Messages'>
                <value>true</value>
             </field>
           </x>
         <item/>
       <items/>
     </publish>
   </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
      <publish node='urn:xmpp:mix:nodes:config'>
        <item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'/>
       </publish>
   </pubsub>
</iq>

4.1.4 Controlling Channel Participants

Owners and Administrators are allowed to control which users can participate in a channel by use of Allowed and Banned lists using PubSub. These operations follow Publish-Subscribe (XEP-0060) [3] which sets out detailed protocol use and error handling. Allowed and Banned lists MAY be read by PubSub get of the Banned and Allowed Nodes. This operation MAY be used by users as controlled by 'Allowed Node Subscription' and 'Banned Node Subscription' configuration node options (default Administrators).

Example 9. Client Reads Allowed Node

<iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='get'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
         <items node='urn:xmpp:mix:nodes:allowed'/>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
         <items node='urn:xmpp:mix:nodes:allowed'>
            <item id='shakespeare.example'/>
            <item id='alice@wonderland.example'/>
         </items>
    </pubsub>
</iq>

Example 10. Client Adds a JID to the Allowed Node

<iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <publish node='urn:xmpp:mix:nodes:allowed'>
            <item id='marlow.example'/>
         </publish>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>

Example 11. Client Removes a JID from the Banned Node

<iq from='hag66@shakespeare.example/UUID-a1j/7533'
    id='lx09df27'
    to='mix.shakespeare.example'
    type='set'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'>
        <retract node='urn:xmpp:mix:nodes:banned'>
            <item id='lear@shakespeare.example'/>
        </retract>
    </pubsub>
</iq>

<iq from='mix.shakespeare.example'
    id='lx09df27'
    to='hag66@shakespeare.example/UUID-a1j/7533'
    type='result'>
    <pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>

Split out from MIX 0.10.0;