Project:Sandbox

The StructuredDiscussions extension provides a discussion and collaboration system for talk pages.

This page covers how to install and administer Structured Discussions; for a guide to using it, see .

You can try out Structured Discussions yourself at the 1>Project_talk:Sandbox/Flow_test|Sandbox talk page.

This extension was previously known as Flow, and names in some places (like the Git repository) still reflect that.

The StructuredDiscussions extension was developed by the name>Special:MyLanguage/Collaboration|Collaboration team at the Wikimedia Foundation. It is still being maintained to fix bugs, but url>mailarchive:wikitech-l/2015-September/082993.html|no substantial development on the extension has been done since 2015, other than a rename to "StructuredDiscussions" in September 2017. 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 Structured Discussions.

Vagrant
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.

Manual
To install the extension manually:

Post install
You also need to run the command "<tvar|cmd>composer update --no-dev</>" from the command line, on the folder where MediaWiki is installed, even if you don't download from git.

Make sure you follow the full instructions for section>#Enabling or disabling StructuredDiscussions</>|enabling or disabling StructuredDiscussions, including the scripts mentioned there.

Dependencies

 * required


 * <tvar|echo></> - for notifications (e.g. replies to your post)


 * It is required to have an object cache. It is recommended that you use memcached for this.  You may encounter problems with Redis currently.


 * <tvar|func></> - for the templates that are automatically installed (e.g. #time)
 * = true  Required for <tvar|special>Special:EnableStructuredDiscussions</> 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


 * <tvar|parso>Parsoid</> for the option to store posts as HTML <tvar|param></> which improves performance. This is how WMF wikis are configured, and hence is the most tested configuration by far.  If you use <tvar|vagrant>MediaWiki-Vagrant</>, enabling <tvar|sd>StructuredDiscussions</> enables Parsoid and sets the format to 'html'.


 * optional


 * <tvar|beta></> - if you want to use the opt-in beta feature for user talk.


 * <tvar|cldr></> - for human-friendly timestamps such as "3 days ago"


 * <tvar|ve></> - for VisualEditor support (<tvar|dcl> </>)


 * bug? if you have the VisualEditor present (e.g. perhaps to provide <tvar|oui>OOUI</>),then StructuredDiscussions will attempt to contact Parsoid even if VE is not enabled


 * StructuredDiscussions can integrate with <tvar|abuse></>, <tvar|black></>, and <tvar|confirm></>, see <tvar|spam></>


 * <tvar|sd>StructuredDiscussions</> will integrate with <tvar|cu></> if you have it installed.


 * <tvar|thanks></> - to "Thank" users for their posts


 * <tvar|log></> - for analytics

Verifying installation
Visit one of the pages you enabled for StructuredDiscussions (see <tvar|1></>) and try adding a topic and editing its header.

Upgrading
The <tvar|1> </> variable, which enumerated StructuredDiscussions boards, was removed as part of <tvar|phab>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 <tvar|1> </>.

Enabling or disabling StructuredDiscussions
To enable or disable StructuredDiscussions for a namespace, first run <tvar|1></> on the affected namespaces (or you can do it on <tvar|2> </>).

E.g. if you are about to enable or disable it on <tvar|1>NS_TALK (1)</> and <tvar|2>NS_USER_TALK (3)</> as shown in the PHP config below:

If <tvar|1>mwscript</> is not configured, replace <tvar|2> </> with <tvar|3> </>

After the above, set <tvar|1> </> for particular namespaces.

For example:

Do not reassign the global (<tvar|1> </>).

To enable it on a single page, use <tvar|1>Special:EnableStructuredDiscussions</>.

This requires the flow-create-board right, which can be granted to any group (see 1>Special:MyLanguage/Manual:User rights#Changing group permissions</>|Manual:User rights#Changing group permissions).

See <tvar|1></> for how to turn off all StructuredDiscussions pages on your wiki.

Parsoid configuration
StructuredDiscussions uses the 1>Requests for comment/PHP Virtual REST Service</>|Virtual REST Service to contact a Parsoid or RESTBase service.

If your wiki loads the <tvar|1></> extension, then you've probably already set this up.

Look for the following in your <tvar|1> </>:

A single Parsoid server can handle multiple wikis.

The Parsoid <tvar|1> </> setting identifies your wiki configuration to Parsoid.

By default it is set to the hostname named by <tvar|1> </>, 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 <tvar|1> </> like:

Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in the <tvar|1> </> property if not specified.

The "prefix" property can also be omitted unless you are running an older version of Parsoid.

Make sure the <tvar|1> </> and <tvar|2> </> listed in Parsoid's <tvar|3> </> match what's in your wiki's <tvar|4> </>.

See 1>Parsoid/Setup#Configuration</>|Parsoid/Setup#Configuration for more details.

"maximum function nesting level of '100' reached, aborting"
If you get this error, you need to set <tvar|nl> </>, probably in <tvar|ini> .</>

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

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

StructuredDiscussions defines many actions such as <tvar|1> </> and <tvar|2> </> (see the list in <tvar|3></>). 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 <tvar|1>'sysop'</> group have the <tvar|2> </> permission to edit anyone's post. You can override which groups have which permissions and what permissions are required for each Flow action; see 1>Special:MyLanguage/Manual:User rights</>|Manual:User rights for an overview of permissions.

Migrating existing pages
To migrate a single existing page, use <tvar|1>Special:EnableStructuredDiscussions</>. It will handle archiving of a single page (then enabling StructuredDiscussions) automatically.

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

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

System messages
Using the "Source editing" option on StructuredDiscussions boards makes visible the help text <tvar|1> </>.

The "uses markup" part is linked through the system message <tvar|1>MediaWiki:Flow-wikitext-editor-help-uses-wikitext</> which makes use of an interwiki link to <tvar|2>MediaWiki.org</>.

In some cases, this interwiki link, instead of pointing to <tvar|1></> on <tvar|2>MediaWiki.org</>, points to a (usually non-existent) <tvar|3>Help:Formatting</> page on the host Wiki.

This can be corrected by changing the interwiki link on <tvar|1>MediaWiki:Flow-wikitext-editor-help-uses-wikitext</> to an external link such as <tvar|2>. </>

Troubleshooting
Not getting Flow as expected?

There are different fixes, depending on the source of the problem:

Wrong Custom-Namespace Declaration Order
The Flow declares must go after the declare for a custom namespace.

Correct order is:

Wrong Native Constants
Talk pages in the 1>Extension_default namespaces#MediaWiki Core</>|Main namespace are defined as <tvar|2> </>, not <tvar|3> </>

The correct declaration is:

$wgNamespaceContentModels[NS_TALK] = 'flow-board';

Non-Registered Extension Constants
<tvar|1></> namespace constant is 2>Extension default namespaces#Page Forms</>|supposed to be <tvar|3> </>.

But that constant does not work in the Flow declare-- you must use the actual number: 107.

This works:

$wgNamespaceContentModels[107] = 'flow-board';

It's unknown to this author whether <tvar|1>Page_Forms</> failed to register its constants correctly, or whether all extension must use numbers (not constants) with Flow.

See list of 1>Extension default namespaces</>|some other extension namespace constants.

Old Remnants
If you're correctly getting Flow on all talk-pages in a namespace, except for one page in that namespace, there may be remnant junk in the talk page (even if it appears empty). Do the following:


 * 1) Browse to the talk page that won't load Flow, e.g.: Portal_Talk:Welcome
 * 2) Delete the Talk page using the Delete tab.
 * 3) Go to the content page for that talk page, e.g.: Portal:Welcome
 * 4) Click Discuss.
 * 5) You get Flow.

Architecture
See <tvar|1>Flow/Architecture</>.

Spam
See <tvar|1></> for more information on how to fight spam in Flow.

Moderation
See <tvar|1></> for more information on moderation in Flow.

Export and Import
There is maintenance script to export Flow data similar to <tvar|1>Manual:DumpBackup.php</>

T114703 - gives some hints about the import.