 | Structured Discussions is no longer in feature development, and new deployments have been suspended. See more information in theWikitech mailing list. |
| This extension is currently not actively maintained! Although it may still work, any bug reports or feature requests will more than likely be ignored. If you are interested in taking on the task of developing and maintaining this extension,you can request repository ownership. As a courtesy, you may want to contact the author. You should also remove this template and list yourself as maintaining the extension in the page's {{Extension}} infobox. |
TheStructuredDiscussions 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, seeHelp:Structured Discussions.You can try out Structured Discussions yourself at theSandbox talk page.
This extension was previously known asFlow, and names in some places (like the Git repository) still reflect that.
The StructuredDiscussions extension was developed by theCollaboration team at the Wikimedia Foundation.It is still being maintained to fix bugs, butno substantial development on the extension has been done since 2015, other than a rename to "StructuredDiscussions" in September 2017.For more information on the development status of this extension, as well as an overview of its design, seeStructured Discussions.
 Warning: | This extension is currently incompatible withtemporary accounts. Temporary accounts can be disabled with $wgAutoCreateTempUser['enabled']=false; in your LocalSettings.php. |
 Caution: | Note that StructuredDiscussions is not compatible with SQLite. |
$wgVirtualRestConfig['modules']['parsoid']['url'] to point to therest.php of your wiki.Flow folder to yourextensions/ directory.cdextensions/gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/Flowcomposer install --no-dev in the extension directory.(SeeT173141 for potential complications.)wfLoadExtension('Flow');
Done – Navigate toSpecial:Version on your wiki to verify that the extension is successfully installed.
Vagrant installation:
vagrant roles enable flow --provision/tmp/mw-UIDGeneratorUUID-UID-xx 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).Make sure you follow the full instructions forenabling or disabling StructuredDiscussions, including the scripts mentioned there.
$wgFlowContentFormat = 'html';) which improves performance. This is how WMF wikis are configured, and hence is the most tested configuration by far. If you useMediaWiki-Vagrant, enabling StructuredDiscussions enables Parsoid and sets the format to 'html'.Visit one of the pages you enabled for StructuredDiscussions (see#Configuration) and try adding a topic and editing its header.
Here are some settings you need to make inLocalSettings.php.
| MediaWiki version: | ≤ 1.34 |
To enable or disable StructuredDiscussions for a namespace in MediaWiki before 1.35, first runpopulateContentModel.php on the affected namespaces (or you can do it onall).From 1.35 onward, this is no longer needed.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:
mwscriptpopulateContentModel.php--wiki=somewiki--ns=1--table=revisionmwscriptpopulateContentModel.php--wiki=somewiki--ns=1--table=archivemwscriptpopulateContentModel.php--wiki=somewiki--ns=1--table=pagemwscriptpopulateContentModel.php--wiki=somewiki--ns=3--table=revisionmwscriptpopulateContentModel.php--wiki=somewiki--ns=3--table=archivemwscriptpopulateContentModel.php--wiki=somewiki--ns=3--table=page
If mwscript is not configured, replacemwscript populateContentModel.php withphp maintenance/populateContentModel.php
After the above, set$wgNamespaceContentModels[namespace] for particular namespaces.For example:
// These lines enable StructuredDiscussions on the "Talk" and "User talk" namespaces// All the NS_* constants here: https://www.mediawiki.org/wiki/Manual:Namespace_constants$wgNamespaceContentModels[NS_TALK]='flow-board';$wgNamespacesWithSubpages[NS_TALK]=true;$wgNamespaceContentModels[NS_USER_TALK]='flow-board';$wgNamespacesWithSubpages[NS_USER_TALK]=true;
Donot reassign the global ($wgNamespaceContentModels =
To enable it on a single page, useSpecial:EnableStructuredDiscussions.This requires the flow-create-board right, which can be granted to any group (seeManual:User rights#Changing group permissions).
$wgGroupPermissions['somegroup']['flow-create-board']=true;
SeeExtension:StructuredDiscussions/Turning off all StructuredDiscussions for how to turn off all StructuredDiscussions pages on your wiki.
 | Parts of this page (those related to Parsoid's LocalSettings.js) areoutdated. It was written for an older version of MediaWiki and may not apply to the most recent version. If you have checked or updated this page and found the content to be suitable, please remove this notice. See thetalk page for a possible discussion on this. |
StructuredDiscussions uses theVirtual REST Service to contact a Parsoid or RESTBase service.If your wiki loads theVisualEditor extension, then you've probably already set this up.Look for the following in yourLocalSettings.php:
$wgVirtualRestConfig['modules']['parsoid']=array(// URL to the Parsoid instance// Use port 8142 if you use the Debian package'url'=>'http://localhost:8000',// Parsoid "domain", see below (optional)'domain'=>'localhost',// Parsoid "prefix", see below (optional)'prefix'=>'localhost',);
A single Parsoid server can handle multiple wikis.The Parsoiddomain setting identifies your wiki configuration to Parsoid.By default it is set to the hostname named by$wgCanonicalServer, 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'slocalsettings.js like:
parsoidConfig.setMwApi({uri:'http://path/to/my/wiki/api.php',domain:'localhost',prefix:'localhost'});
Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in theuri property if not specified.The "prefix" property can also be omitted unless you are running an older version of Parsoid.Make sure thedomain andprefix listed in Parsoid'slocalsettings.js match what's in your wiki'sLocalSettings.php.
SeeParsoid/Setup#Configuration for more details.
If you get this error, you need to setxdebug.max_nesting_level = 200, probably in/etc/php5/apache2/php.ini.[1]
StructuredDiscussions invokes$cache->cas() and some cache implementations includingCACHE_ACCEL (APCBagOStuff) don't implementCAS.You probably need to use a different cache, for example installmemcached and set$wgMainCacheType = CACHE_MEMCACHED;.
Users must have the coreedit permission to perform any write action in StructuredDiscussions.Many wikis only grant this permission to the 'user' (logged-in) group.
StructuredDiscussions defines many actions such asedit-post anddelete-topic (see the list inFlowActions.php).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 theflow-edit-post permission to edit anyone's post.You can override which groups have which permissions and what permissions are required for each Flow action; seeManual:User rights for an overview of permissions.
To migrate a single existing page, useSpecial:EnableStructuredDiscussions.It will handle archiving of a single page (then enabling StructuredDiscussions) automatically.
The scriptmaintenance/convertNamespaceFromWikitext.php automates this namespace conversion and archiving, seeFlow/Converting talk pages.It is somewhat WMF-specific, so evaluate its operation and backup your database before running it.Another scriptmaintenance/convertAllLqtPages.php convertsLiquidThreads pages and their threads to Flow boards and topics, seeFlow/Converting LiquidThreads. Similar caveats apply.
Flow adds aTopic: namespace, seeExtension default namespaces#flow.You can visitSpecial:PrefixIndex/Topic: to see if there are existing pages that conflict with this; if so run the maintenance scriptmaintenance/namespaceDupes.php.
| parameter | default | comment | ||
|---|---|---|---|---|
| $wgFlowHelpPage | //www.mediawiki.org/wiki/Special:MyLanguage/Help:Extension:Flow | URL for more information about the Flow notification system | ||
| $wgFlowCluster | false | $wgFlowCluster will define what external DB server should be used. If set to false, the current database will be used to read/write data from/to.If StructuredDiscussions data is supposed to be stored on an external database, set the value of this variable to the $wgExternalServers key representing that external connection. | ||
| $wgFlowDefaultWikiDb | false | Database to use for StructuredDiscussions metadata. Set to false to use the wiki db. Any number of wikis can and should share the same StructuredDiscussions database. The actual database name is stored inside internal tables for each message. Changing the database name after messages have been posted will cause old threads to become inaccessible. | ||
| $wgFlowExternalStore | false | Used for content storage. False to store content in StructuredDiscussions db.Otherwise a cluster or list of clusters to use with ExternalStore.Provided clusters must exist in $wgExternalStores.Multiple clusters required for HA, so inserts can continue if one of the masters is down for maint or any other reason. $wgFlowExternalStore = array( 'DB://cluster24', 'DB://cluster25' ); | ||
| $wgFlowContentFormat | html | By default, StructuredDiscussions will store content in HTML. However, this requires having Parsoid up and running, as it'll be necessary to convert HTML to wikitext for the basic editor.(n.b. to use VisualEditor, you'll definitely need Parsoid, so if you do support VE, might as well set this to HTML right away) If $wgFlowParsoidURL is null, $wgFlowContentFormat will be forced to wikitext. The 'wikitext' format is likely to be deprecated in the future. | ||
| $wgFlowParsoidURL | null |
StructuredDiscussions Parsoid config Please note that this configuration is separate from VE's Parsoid config. | ||
| $wgFlowParsoidPrefix | null |
Flow Parsoid config Please note that this configuration is separate from VE's Parsoid config. | ||
| $wgFlowParsoidTimeout | null |
Flow Parsoid config Please note that this configuration is separate from VE's Parsoid config. | ||
| $wgFlowParsoidForwardCookies | false |
Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read). If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is This feature requires a non-locking session store.The default session store will not work and will cause deadlocks when trying to use this feature.If you experience deadlock issues, enable $wgSessionsInObjectCache. WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP. For security reasons, it is strongly recommended that | ||
| $wgFlowDefaultLimit | 10 | Limits for paging | ||
| $wgFlowMaxLimit | 100 | Limits for paging | ||
| $wgFlowMaxMentionCount | 100 | Maximum number of users that can be mentioned in one comment | ||
| $wgFlowMaxThreadingDepth | 8 | Max threading depth | ||
| $wgFlowCacheTime | 60 * 60 * 24 * 3 | The default length of time to cache StructuredDiscussions data in memcache. This value can be tuned in conjunction with measurements of cache hit/miss ratios to achieve the desired tradeoff between memory usage, db queries, and response time.The initial default of 3 days means StructuredDiscussions will attempt to keep in memcache all data models requested in the last 3 days. | ||
| $wgFlowCacheVersion | 4.9 | A version string appended to cache keys. Bump this if cache format or logic changes.StructuredDiscussions can be a cross-wiki database accessed by wikis running different versions of the Flow code; WMF sometimes overrides this globally in wmf-config/CommonSettings.php | ||
| $wgFlowAbuseFilterGroup | 'flow' | Custom group name for AbuseFilter Acceptable values:
| ||
| $wgFlowAbuseFilterEmergencyDisableThreshold | 0.10 | AbuseFilter emergency disable values for StructuredDiscussions | ||
| $wgFlowAbuseFilterEmergencyDisableCount | 50 | AbuseFilter emergency disable values for StructuredDiscussions | ||
| $wgFlowAbuseFilterEmergencyDisableAge | 86400 // One day. | AbuseFilter emergency disable values for StructuredDiscussions | ||
| $wgFlowAjaxTimeout | 30 | Timeout for StructuredDiscussions's AJAX requests (only affects ones that go through flow-api.js), in seconds | ||
| $wgFlowCoreActionWhitelist | array( 'info', 'protect', 'unprotect', 'unwatch', 'watch', 'history', 'wikilove', 'move', 'delete' ); | Actions that must pass through to MediaWiki on StructuredDiscussions-enabled pages | ||
| $wgFlowServerCompileTemplates | false | When set totrue StructuredDiscussions will compile templates into their intermediate forms on every run. When set tofalse Flow will use the versions already written to disk. Production should always have this set tofalse. | ||
| $wgFlowSearchServers,$wgFlowSearchConnectionAttempts,$wgFlowSearchBannedPlugins,$wgFlowSearchOptimizeIndexForExperimentalHighlighter,$wgFlowSearchMaxShardsPerNode,$wgFlowSearchRefreshInterval,$wgFlowSearchMaintenanceTimeout,$wgFlowSearchReplicas,$wgFlowSearchShardCount,$wgFlowSearchCacheWarmers,$wgFlowSearchMergeSettings,$wgFlowSearchIndexAllocation,$wgFlowSearchEnabled | N/A | These former settings wereremoved because the code was unmaintained and broken. (You can look at theprevious documentation if you want.) There is currently no code for supporting search in StructuredDiscussions. |
Using the "Source editing" option on StructuredDiscussions boards makes visible the help text"Wikitextuses markup and you can preview the result anytime.".The "uses markup" part is linked through the system messageMediaWiki: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 toHelp: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 onMediaWiki:Flow-wikitext-editor-help-uses-wikitext to an external link such as
[https://www.mediawiki.org/wiki/Help:Formatting uses markup].Not getting Flow as expected?There are different fixes, depending on the source of the problem:
When you get messages likeConversion from 'html' to 'wikitext' was requested, but core's Parser only supports 'wikitext' to 'html' conversion, you probably have a version of MediaWiki (e.g. REL1_39) where the StrucuredDiscussions extension does not use the zero-configparsoid.For using visual editor on discussions, you must manually configure parsoid-php.
For REL1_39 of MediaWiki and StructuredDiscussions, be sure to do all of the following:
wfLoadExtension('Flow');
wfLoadExtension('Parsoid',"$IP/vendor/wikimedia/parsoid/extension.json");
$wgVirtualRestConfig['modules']['parsoid']
Older versions of MediaWiki may need Parsoid-JS and perhaps a code patch:
If the problem persists,this discussion might be of some help.
The Flow declares must goafter the declare for a custom namespace.Correct order is:
define("NS_PORTAL_TALK",3005);$wgExtraNamespaces[NS_PORTAL_TALK]="Portal_Talk";$wgNamespaceContentModels[NS_PORTAL_TALK]='flow-board';$wgNamespacesWithSubpages[NS_PORTAL_TALK]=true;
Talk pages in the Main namespace are defined asNS_TALK,notNS_MAIN_TALK
The correct declaration is:
$wgNamespaceContentModels[NS_TALK] = 'flow-board';
Extension:Page Forms namespace constant issupposed to bePF_NS_FORM_TALK.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 Page_Forms failed to register its constants correctly, or whetherall extension must use numbers (not constants) with Flow.See list ofsome other extension namespace constants.
If you're correctly getting Flow on all talk-pages in a namespace, except forone page in that namespace, there may be remnant junk in the talk page (even if it appears empty).Do the following:
To get Parsoid to work with StructuredDiscussions (Flow):
LocalSettings.php, explicitely load Parsoid like so:wfLoadExtension( 'Parsoid', "vendor/wikimedia/parsoid/extension.json" );For more details, seeExtension talk:StructuredDiscussions/2022#h-VisualEditor does not work on Flow (Structured discussions) talk pages.-20221212122400.
SeeExtension:StructuredDiscussions/Spam for more information on how to fight spam in Flow.
SeeExtension:StructuredDiscussions/Moderation for more information on moderation in Flow.
There is maintenance script to export Flow data similar toManual:DumpBackup.php
php extensions/Flow/maintenance/dumpBackup.php
T114703 - gives some hints about the import.
 | This extension is being used on one or moreWikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia'sCommonSettings.php andInitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki'sSpecial:Version page. |
 | This extension is included in the following wiki farms/hosts and/or packages: |