Extension:StructuredDiscussions

The StructuredDiscussions extension provides a discussion and collaboration system for talk pages. This page covers how to install and administer StructuredDiscussions; for a guide to using it, see Help:StructuredDiscussions. You can try out StructuredDiscussions yourself at the Sandbox talk page.

The StructuredDiscussions extension was developed by the Collaboration team at the Wikimedia Foundation. It is still being maintained to fix bugs, but no substantial development on the extension has been done since 2015. Development may possibly start again in the future. For more information on the development status of this extension, as well as an overview of its design, see StructuredDiscussions.

Installing
The easiest way to install StructuredDiscussions locally is to use the MediaWiki-Vagrant appliance and enable its flow role. This is only intended for development/local testing.

To install the extension manually:

You must run "update.php" as the web server user (depends on configuration, but could be e.g. www-data). Otherwise, it can leave temporary  files that MediaWiki may be unable to open (T55791). If you get a "Permission denied" error upon first visiting a Flow board you have to delete these files. Also, update.php will create FlowMention to support Flow's mention feature in VE (either @ or a toolbar menu provides a convenient auto-complete interface for mentions).

If you install from git, you will also need to run "composer update".

Make sure you follow the full instructions for enabling or disabling Flow, including the scripts mentioned there.

Dependencies

 * required: Extension:Echo for notifications (e.g. replies to your post)
 * required: It is required to have an object cache. It is recommended that you use memcached for this.  You may encounter problems with Redis currently.
 * required: Extension:ParserFunctions for the templates that are automatically installed (e.g. #time)
 * required: $wgContentHandlerUseDB. Required for Special:EnableFlow and to avoid corruption if you change the content model of namespaces (towards or away from StructuredDiscussions) if there are already pages in that namespace.
 * strongly recommended: Parsoid for the option to store posts as HTML which improves performance. This is how WMF wikis are configured, and hence is the most tested configuration by far. If you use MediaWiki-Vagrant, enabling StructuredDiscussions enables Parsoid and sets the format to 'html'.
 * optional: Extension:BetaFeatures if you want to use the opt-in beta feature for user talk.
 * optional: Extension:CLDR for human-friendly timestamps such as "3 days ago"
 * optional: Extension:VisualEditor for VisualEditor support
 * bug? if you have the VisualEditor present (e.g. perhaps to provide OOjs UI),then StructuredDiscussions will attempt to contact Parsoid even if VE is not enabled
 * optional: StructuredDiscussions can integrate with Extension:AbuseFilter, Extension:SpamBlacklist, and Extension:ConfirmEdit, see /Spam
 * optional: StructuredDiscussions will integrate with Extension:CheckUser if you have it installed.
 * optional: Extension:Thanks to "Thank" users for their posts
 * optional: Extension:EventLogging for analytics

Only for REL_1_24

 * required: Extension:Mantle (install REL_1_24 of that as well).

Verifying installation
Visit one of the pages you enabled for StructuredDiscussions (see ) and try adding a topic and editing its header.

Upgrading
The  variable, which enumerated StructuredDiscussions boards, was removed as part of T105574. Before upgrading to 1.26 or later, run the maintenance scripts:

The first script is part of MediaWiki core.

Configuration
Here are some settings you need to make in.

Enabling or disabling StructuredDiscussions
To enable or disable StructuredDiscussions for a namespace, first run populateContentModel.php on the affected namespaces (or you can do it on ). E.g. if you are about to enable or disable it on NS_TALK (1) and NS_USER_TALK (3) as shown in the PHP config below:

If mwscript is not configured, replace  with

After the above, set  for particular namespaces. For example:

Do not reassign the global (.

To enable it on a single page, use Special:EnableFlow. This requires the flow-create-board right, which can be granted to any group (see Manual:User rights).

Parsoid configuration
StructuredDiscussions uses the Virtual REST Service to contact a Parsoid or RESTBase service. If your wiki loads the VisualEditor extension, then you've probably already set this up. Look for the following in your :

A single Parsoid server can handle multiple wikis. The Parsoid  setting identifies your wiki configuration to Parsoid. By default it is set to the hostname named by, but you can pick an arbitrary string. Older versions of Parsoid also used a unique "prefix" to identify the server; you may need to list that here as well.

Parsoid must have been configured to match, using a line in Parsoid's  like: Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in the  property if not specified. The "prefix" property can also be omitted unless you are running an older version of Parsoid. Make sure the  and   listed in Parsoid's   match what's in your wiki's.

See Parsoid/Setup for more details.

"maximum function nesting level of '100' reached, aborting"
If you get this error, you need to set, probably in.

"Exception Caught: CAS is not implemented in Xyz"
StructuredDiscussions invokes  and some cache implementations including   (APCBagOStuff) don't implement CAS. You probably need to use a different cache, for example install memcached and set.

Permissions
Users must have the core  permission to perform any write action in StructuredDiscussions. Many wikis only grant this permission to the 'user' (logged-in) or 'autoconfirmed' group.

StructuredDiscussions defines many actions such as  and   (see the list in ). The permissions vary depending on whether the post is your own and whether it has been moderated. For example, by default users can edit their own posts, but only users in the 'sysop' group have the  permission to edit anyone's post. You can override which groups have which permissions and what permissions are required for each Flow action; see Manual:User rights for an overview of permissions.

Migrating existing pages
To migrate a single existing page, use Special:EnableFlow. It will handle archiving of a single page (then enabling StructuredDiscussions) automatically.

The script  automates this namespace conversion and archiving, see StructuredDiscussions/Converting talk pages. It is somewhat WMF-specific, so evaluate its operation and backup your database before running it. Another script  converts LiquidThreads pages and their threads to Flow boards and topics, see StructuredDiscussions/Converting LiquidThreads. Similar caveats apply.

Flow adds a Topic: namespace, see Extension default namespaces. You can visit Special:PrefixIndex/Topic: to see if there are existing pages that conflict with this; if so run the maintenance script.

System messages
Using the "Source editing" option on StructuredDiscussions boards makes visible the help text. The "uses markup" part is linked through the system message MediaWiki:Flow-wikitext-editor-help-uses-wikitext which makes use of an interwiki link to MediaWiki.org.

In some cases, this interwiki link, instead of pointing to Help:Formatting on MediaWiki.org, points to a (usually non-existent) Help:Formatting page on the host Wiki. This can be corrected by changing the interwiki link on MediaWiki:Flow-wikitext-editor-help-uses-wikitext to an external link such as.

Architecture
See StructuredDiscussions/Architecture.

Spam
See Extension:StructuredDiscussions/Spam for more information on how to fight spam in Flow.

Moderation
See Extension:StructuredDiscussions/Moderation for more information on moderation in Flow.