MoinMoin: NotificationBot

This page explains details related to implementation of the notification bot that can be used by MoinMoin 1.7.

Communication protocol details

The notification bot sends notifications and communicates with users using Jabber/XMPP protocol suite. See http://www.jabber.org and http://www.xmpp.org for more information.

Requests to a wiki are sent using XMLRPC wiki interface v2 as described on http://www.jspwiki.org/wiki/WikiRPCInterface2, with some extensions (see below). Currently '&action=xmlrpc2' is added to the wiki URL, as required by MoinMoin.

Wiki processes communicate with the bot using a custom XMLRPC API, also documented on this page.

Wiki Interface extensions

Following functions must be supported by a wiki for the notification bot to work:

• utf8 getPage( utf8 pagename ): gets the raw wiki text of page, latest version.

• utf8 getPageHTML( utf8 pagename ): returs page rendered in HTML, latest version.

• array getAllPages(): returns a list of all pages. The result is an array of utf8 pagenames.

• struct getPageInfo( utf8 pagename ): returns a struct with elements:

  • name (utf8): the canonical page name.

  • lastModified (date): Last modification date, UTC.

  • author (utf8): author name.

  • version (int): current version

Additional functions specific to MoinMoin, not described elsewhere:

• bool revertPage( utf8 pagename, int version ): reverts page pagename to revision, returns true on success

• struct xmlrpc_searchPagesEx( utf8 query_string, utf8 search_type, int length, bool case, date mtime, bool regexp): returns a list of pages that meet specified search criteria

  • Arguments:

    • query_string: string to search for

    • search_type: "text" or "title"

    • length: length of context preview

    • case: should the search be case sensitive?

    • mtime: time of a last modification

    • regexp: should query_string be treated as a regular expression?

  • Returns a list of lists with following fields:
    1. Name of the page
    2. Context preview (wiki markup); relevant page text
    3. Page URL

• utf8 getUserLanguageByJID( utf8 jid ): returns a 2-letter code of the language that user identified by jid uses, or "en" if not specified

• utf8 getJabberAuthToken( utf8 jid, utf8 secret ): returns an auth token that can be used to authenticate consequent function calls made in a XMLRPC multicall as made by a user identified by the Jabber ID jid. It is assumed that:

  • Jabber ID must be unique among all wiki users
  • Jabber network is trusted enough, to assume that requests coming from given JID are not spoofed; this should be ok for normal sites

• utf8 applyAuthToken( utf8 auth_token ): authenticate following function calls as being done by a user assigned to the transmitted auth token; this should be the first function called in a multicall sequence; returns a Fault if the token has already expired or is invalid, "SUCCESS" otherwise.

Notification XMLRPC API reference

Following XMLRPC functions are provided by the XMLRPC component of the notification bot. Note that the first argument is always a secret, which is shared between wiki and the bot, and must match the value provided in bot's configuration file for the invocation to work. Notification text should contain all necessary data except from URLs, these will be appended by the bot.

• bool send_notification( utf8 secret, list jids¹ , struct notification²  ): sends notification to a list of Jabber IDs; always returns true

• bool addJIDToRoster( utf8 secret, utf8 jid ): asks the bot to add a given Jabber ID to its roster; always returns true

• bool removeJIDFromRoster( utf8 secret, utf8 jid ): asks the bot to remove a given Jabber JID from its roster and remove its subscription; always returns true

• ^1. list jids - a list of bare Jabber IDs

  ^2. struct notification - this is a rather complicated structure which holds context-dependent notification data. Following fields are interpreted:

  • utf8 action - required; describes the type of notification; allowed values: file_attached, page_changed, page_deleted, page_renamed, user_created

  • utf8 subject - required; subject of the notification message

  • list url_list - required (may be empty); list of URLs relevant to the notification; each URL is described by a struct with fields:

    • utf8 url - the URL itself

    • utf8 description - description of the URL (for example: "Link to the changed page")

  • utf8 text - required; plain-text body of the notification message, don't add any URLs in it - url_list is meant to be used for them in order to reduce information duplication when a user can communicate with Data Forms

  • utf8 editor - required; author of the change

  • utf8 comment - optional; provides a comment associated with file_attached, page_changed, page_deleted or page_renamed actions

  • utf8 old_name - required only for the page_renamed action; previous name of the page

  • utf8 page_name - required only for file_attached, page_changed, page_deleted and page_renamed actions

  • utf8 revision - required only for page_changed and page_renamed actions; specifies current revision of a page