📗 Discourse Admin Manual

Documentation & Support Collaboration
1

Our manual for using the administrative Discourse features. Mostly applicable to all Discourse installations, but some instructions are specific to the plugins and custom modifications we did for edgeryders.eu. For instructions for normal forum use, see our Discourse User Manual for edgeryders.eu.

Content

1. Working with topics and posts

2. Working with categories

3. Working with tags

4. Working with users

5. Understanding notifications

6. Other aspects

1. Working with topics and posts

1.1. How to delete an unwanted topic?

Click “Wrench icon → Delete topic” below the topic.

Deleted topics are retrievable at Edgeryders (reference).

1.2. How to see the deleted content written by a certain user?

  1. As an admin user, visit the user’s profile page (example: user matthias).
  2. Click the button “Expand”.
  3. At the top, you’ll see “[number] deleted posts”. Click that.
  4. A list will appear with all content this user wrote that was deleted, also showing in the right side by whom (the user, or an admin).

1.3. How to post to the official blog?

The official blog is a collection of slightly better editorialized posts about Edgeryders as a community and a company. It is accessible from the Company drop-down menu on the top right.

In the edgeryders.eu website, the official blog is not a category but a view of the Discourse tag blog. Admins and moderators can include any topic for being published on the blog. To do so:

  1. Write the post. Remember: you are aiming for an audience beyond that of the community, so do not take too much for granted. If you are making a point that needs some background information, provide it. A good form is a one-sentence mention plus a link:

    Back in 2016, we had been active in some project. The point was to achieve this and this other goal. We succeeded, but we have never been completely happy for this reason. Now, we are moving on to the next level.

  2. Choose a category for it. A blog post can be in any category. If you are writing an update about a project, the best is probably to write within the project category. If the project has no category or lives in a private one, Campfire is a good fallback position, plus assigning the ‘project-*’ tag to the topic that corresponds to the project.

  3. Add a nice image. Posts with pictures are always nicer and more effective.

  4. Add the blog tag. This is done in the “choose optional tags for this topic” field in the edit screen. The tag tells the platform that your new topic should be visualized in the blog. Note that only moderator and administrator users can use this tag, so you might have to ask one of them to do this for you.

  5. Make sure the image preview displays correctly. The blog view takes the first picture in the post and displays it as an “ultrawide” preview image in format 690×150 px. If this results in a good preview of your picture, no need to do anything. If it looks bad (maybe it cuts people’s heads off) do the following:

    1. With an image editor, crop your image (or another image) to proportions 690:150 (for example 690×150 px or 1380×300 px etc., as large as it fits for the excerpt of your source image that you want to show as the preview).

    2. Upload it at the top of your post.

    3. Edit the line of code relating to the uploaded image, so that it ends with width="1" height="1">. This will “hide” the preview picture in the full topic view by displaying it in 1×1 px size. A full line will look something like this:

       <img src="/uploads/default/original/2X/1/136c0f.jpg" width="1" height="1">

    4. The ultrawide version of the image that you provided may also look good in your main text (so you can delete the version uploaded earlier). But in case you want to display it in full height (not in the preview format) on the topic’s page, you can keep both versions. The code will then look something like this:

       [some text of the topic might be here, before the images]
 <img src="/uploads/default/original/2X/1/136c0f.jpg" width="1" height="1">
 <img src="/uploads/default/original/2X/f/fedfbc1.jpg" width="690" height="388">
 [remaining text of the topic]

      The first line displays the ultrawide picture only in the blog view; the second one display the full height image in the main text. Remember you have to upload both the original and the cropped file, as they are images with different content now.

1.4. How to create topic templates?

A topic template allows to pre-fill the body of the Discourse editor with text when starting a new topic in a certain category. You can provide questions to answer or other hints for writing a good topic for that category. With this technique, the user has to first go to the corresponding category (for example using a link you provided) and then click the + New Topic button. If you rather want to provide a link that opens a new-topic editor right away, see the section on new-topic links.

To create a topic template:

  1. You need to be a Discourse admin or moderator user to access this function.

  2. Go to the category overview page of the category where you want to add the topic template.

  3. Click Edit in the top right.

  4. Go to tab “Topic Template”.

  5. Enter the topic template text. You can use the same Markdown formatting as in the regular Discourse editor.

  6. Click Save Category.

  7. Click + New Topic to see if your topic template works as expected.

1.5. How to create a new-topic link?

Discourse has a hidden feature where you can provide a special link, and clicking it will open a new topic editor that you can pre-fill with title, body text and tags. To encode your title or body text, use an online URL encoder; the one at toolsvoid.com is nice because it uses “+” to encode space characters, which makes the links shorter and more readable. The link has the following format:

/new-topic?title=…&body=…&category=cat/subcat&tags=tag1,tag2

You can also specify the categories by their numeric ID rather than their name. This is better because such a link does not break when the category is renamed. In that case, the link format is:

/new-topic?title=…&body=…&category_id=123&tags=tag1,tag2

If you want both a topic template when clicking the regular + New Topic button and a link that opens a new editor, pre-filled with the same text, you need to provide the pre-filling text twice, once for each technique. Because even when omitting the &body= parameter in new-topic links, it will overwrite the topic template text, in this case with nothing.

1.6. How to use event topics?

We have installed a plugin that allows to mark a topic as an event, by adding the event start and end time to it. RSVP functionality is then also available, but we did not use that yet.

So far, we have enabled this option only in selected categories. To enable it in a new category, edit the category in tab “Settings” and enable “Allow events to be added to topics in this category (overrides site setting).” Then configure the event behavior with the further settings below that.

The event information is also available via JSON. See for example this JSON excerpt from an example topic in JSON format:

{
    ...
    "event": {
        "start": "2019-11-19T10:00:15+01:00",
        "end": "2019-11-29T16:00:15+01:00",
        "timezone": "Europe/Brussels"
    },
    ...
}

2. Working with categories

2.1. How to find the ID of a category?

You need the category if you want to create a permalink to the category under “Admin → Customize → Permalinks”. While topic IDs appear at the end of URLs, it’s not that simple with categories. But here is a solution:

  1. Install a browser extension that allows to view JSON content properly formatted in the browser. For example in Chrome / Chromium, JSON Formatter is a popular open source extension for this purpose.

  2. Modify the extension settings of the JSON viewer extension to let it access your page data on click only. We don’t want anything to spy on you, do we.

  3. Go to the Categories overview page), then append .json to the URL and visit that page.

  4. Activate the extension to see the JSON content on this page properly formatted.

  5. Find the category I in this JSON document.

    • For top-level categories, you will find an attribute categories_list → categories → [list item] → id for the list item with the suitable name attribute.

    • For sub-level categories, you will find an attribute categories_list → categories → [list item] → subcategory_ids for the list item of the corresponding parent category. The order of entries in subcategory_ids is the same as the order of sub-categories below this parent category, so you can find the one for the sub-categoriy in question.

2.2. How to convert a category into a topic?

This is not possible with any dedicated Discourse feature. You have to do the following steps manually:

  1. Edit the “About the … category” topic in the category and copy&paste its content to a new topic in a new category.

  2. Adjust ownership for the topic now containing the “About the … category” content: click “three dots menu” (below the topic), then “wrench icon” (for “Admin actions”), then “Change Ownership”.

  3. Assign all topics in the category to other categories. As a moderator / admin:

    1. Click the “list icon” on the top left of the list of topics in this category. A list of checkboxes will appear, and some buttons.
    2. Select some (or to select all, scroll till you reach the bottom, then click “Select All”).
    3. Click the “wrench icon” in the top right, select “Bulk Actions” from its menu.
    4. Execute the “Set Category” bulk action.
    5. Repeat as needed until no topics are left in this category. (Except for the special “About the … category” one, which you can’t move even if you try. We copied over its content above already.)

  4. Delete the category. (Click “Edit” on the category overview page, then “Delete category”.)

2.3. How to create a new top-level category for a project?

For the Edgeryders top-level project, we use a few custom-made Discourse features and conventions to make it look the way it does. Here’s how. Note that, to change the category structure and settings, you need to be a Discourse administrator (being moderator is not enough).

  1. Create a new top-level category for the new project.

  2. Configure a category color, based on the main color of your project’s logo, and add it to the allowed category colors in Discourse. By convention, the category color and logo color for project categories on edgeryders.eu should be a shade of blue. Configure that color in the settings dialog of your category.

  3. Upload a category image. From your project’s logo, prepare a category image (150×150 px in size, PNG format, transparent background). Then go to tab “Images” of the category’s settings dialog and upload that image.

    :exclamation: This step is important because only when a category logo is present, a category description will be shown at the top of the category’s page (resp. sub-category’s page). As a counterexample, see the “Documentation & Support” category.

  4. Configure the way subcategories are shown. In the settings dialog of your category, go to tab “Settings” and enable “Show subcategory list above topics in this category.” with “Subcategory List Style: Boxes”. This is our convention for project categories.

  5. Edit the category description – it’s in the auto-generated topic “About the [category name] category”, always visible at the top of the category’s topic list. There:

    • Add a one-sentence paragraph at the top, separated by an empty line. This will be used as the short-form category description in the /categories overview page, on the category’s own page, in the category dropdown list etc…

    • Add more content below the first paragraph to explain the purpose and content of your category in detail and to engage users. This can include images, embedded videos etc…

    • Select all text after the first paragraph, then click “gear icon → Hide Details” in the editor to wrap it into a [details=Show more] … [/details] tag. This will show the first summary paragraph and a “Show more” foldout link on the category’s page (and, as a side effect, also when viewing the “About the [category name] category” topic directly).

      Showing all “About” topic content on the category’s page is a custom feature we added to create a more engaging category page. In standard Discourse, the category’s page would only show the summary paragraph. While we use the [details=Show more] … [/details] tag to hide content dynamically, still keeping it accessible on the category’s page.

  6. Unlist the “About the … category” topic. Either from the “wrench icon” menu on the topic’s page, or from the bulk actions “wrench icon” menu on the category’s list of posts, after selecting only this one. This will hide the topic for all normal users, as it’s just redundant content for them, all shown at the top of the same category page already. Because the topic stays pinned, admin users however still see it at the top of the list, easily accessible for editing.

  7. Change the ownership of the first post in the “About the … category” topic to user “edgeryders”. Usually done to have a more uniform appearance as categories and not distract users by presuming a connection between categories and individual users. There might be exceptions of course, where such a connection exists, and in that case the ownership perhaps should not be touched.

  8. Create the subcategories. Follow roughly the same steps as above for creating top-level categories. Some option will not be available. But in particular, the option to create an unfoldable category decription should also work for subcategories.

2.4. How to create an access restricted category?

This is treated in its own topic here:

2.5. How to assign a topic to multiple categories?

This is not supported by Discourse, also not with plugins. Its whole architecture is based on “one topic, one category” (see). Depending on what you want to achieve, one of the following alternative solutions can be suitable:

  • Sequential use of multiple categories. Instead of assigning multiple categories at once, you would assign one, wait for some days or weeks, and the move the topic to another category. This can be suitable to attract attention in a highly frequented category first (in our case that’s Campfire) while moving it later to a more focused category with a more specific audience.

    Users who contributed or subscribed to the topic while before switching categories will still receive notifications after the switch. In principle, a plugin could be created to add the category switching as an automated action to the topic timer feature; such a plugin does not exist yet, though.

  • Assigning tags. This is the core feature Discourse provides for multiple categorizations per topic (see). A topic can have one category, but any number of tags. Using tags incl. the tag groups feature to create a hierarchy between them can be very similar to a secondary category, as demonstrated by the cat2-* tags here on edgeryders.eu.

    The tags used as secondary categories will have to be presented prominently on the frontpage to make sure they get used. Our current approach does not work for that – the “What we care about” topic, tucked away in the Community menu, gets about 120 views per month on average.

  • Assigning tags, and subscribing people to them. Using tags as secondary categories will be most powerful when users understand that they can and should subscribe to tags, just as they can subscribe to categories. On the edgeryders.eu platform, as of 2020-05 none of these features is in widespread use, though: there are 55 category subscribers :lock: (40 of which subscribing to 2 categories or less) and 11 tag subscribers :lock:.

    A possible solution to this is to subscribe users to tags they are (probably) interested in, based on their observed interests. This can be done manually by staff users. If everyone gets subscribed to a limited, fixed amount of tags and this is part of the terms of use, it will not be seen as spam. People would also be able to manually unsubscribe and would not get re-subscribed to the same tag again.

    There is currently no Discourse feature or plugin to support this, but some attempts at creating such a function. The simplest-to-implement option would be a cron script that uses Ruby Console and runs every night to subscribe new users to a tag gems or similar that is used to attract user attention across category limits. Instead of force-subscribing users, sending them links to subscribe to tags comfortably is another option; similarly, there is no feature of plugin in Discourse to do so, but ways to develop one.

  • Inviting users to topics. A finely targetable way to attract user attention to topics is to use the “invite to topic” feature in Discourse. There is currently no feature or plugin to automate this (see), but one could be developed, for example a cron script interacting with the Discourse ActiveRecord interface, inviting people based on a detected match of detected or tagged keywords and user interest.

  • Mentioning users. Just to complete this list: @mentioning users in a topic is also a way to draw their attention to it. Doing this in bulk is less click work than inviting users to a topic in bulk, as it allows to copy&paste lists of usernames. However, it also makes topics look ugly. Hiding the mentions into a [details="…"] … [/details] section might provide a solution to that.

2.6. How to get a list of users who contributed to a category?

There are two options:

  • Main contributors per top-level category. To get a list of the main contributors (by default those with ≥8 posts in a top-level category) and their post counts for each top-level category, use the Data Explorer query “Posts: by top-level category and user” (link for moderators, link for admins). It does not allow to see only contributors to a specific sub-category, though.

  • All contributors for one category or sub-category. To get a list of all users who contributed to a specific top-level category or sub-category of your choice, together with their post counts, use the Data Explorer query “Posts: by user, for one category” (link for moderators, link for admins).

3. Working with tags

We need to use tags this since we want to employ tags as additional ordering scheme to tag by “aspects of wellbeing” etc… Tags in Discourse can be assigned to topics, but not individual posts. Recent versions of Discourse have made tags a core feature (info).

3.1. How to tag content in bulk?

  1. Go to any suitable list of content (for example, a category page).
  2. Click “list icon” in the top left corner of the actual content table. (Mouseover text is “toggle bulk selection of topic”.)
  3. Select all content items to tag, using the checkboxes that appeared. (If you click “Select All”, it will only select the visible content on the page, so click to reload more until you reach the bottom if you want top operate on the whole category.)
  4. Click “wrench icon” in the top right, then “Append Tags”.
  5. Select existing tags or enter new tags, then confirm with the “Append Tags” button.

3.2. How to remove a tag?

  1. Go to the global list of tags.
  2. Click on a tag.
  3. Click the “trash can” icon to delete the tag. (The content tagged with it will be kept, of course.)

Since the /tags page lists only tags used at least once, not-in-use tags cannot be deleted this way. Still, they clutter the namespace of proposed tags when tagging content. To delete them, construct their URL in the form https://edgeryders.eu/tags/{tagname}, then proceed as above.

3.3. How to know what tags are for what purpose?

Here’s a short reference (to be extended):

  • Tags for project content. We use Discourse in a way that involves frequent re-categorizing of content, depending on our needs. Also, project-based categories are regularly dismantled after the end of the project, and the content is sorted into broader categories, to keep the numbers of categories small. In order to still keep together project content, we use the “project-*” tags, made from the prefix and the project’s name. It is not necessary to tag project content while there is a project category, only when dismantling that.

  • Tags for ethnographic coding. Tags of the form ethno-* are used by Open Ethnographer to define ethnographic corpora for the various research projects where Open Ethnographer is in use (details).

  • Tag to indicate coding priority. The code codepriority can be used to tell ethnographers which content to prioritise when coding.

  • Tags for the wellbeing ontology. Tags of the form cat2-* are used to sort topics into our wellbeing ontology. Navigation using that tagging is available in the main menu under “Community → What We Care About”.

  • Tag blog: Used for all topics that we want to give prominence in the official Edgeryders blog (“Company → Official Blog” in the menu). Assigning this tag automatically adds it to the blog, but the tag can only be used by Discourse moderators and admins. This includes all topics that were in the “Blog” group of our Drupal-based platform. You can subscribe to our blog with your RSS reader, as Discourse has RSS for everything. In this case, it’s Edgeryders - Topics tagged blog.

  • Tags for Drupal content types: Upon import from Drupal, tags were assigned to keep track of the original node’s content type. These are: task, wiki, document, event, challenge_response, group, minisite_page, journal, page, infopage. These tags will eventually be removed, once we are sure we don’t need them to finish Drupal-to-Discource migration related tasks. Tag post has already been removed, as posts did not have any special features to be aware of.

3.4. How to filter a list of tagged topics also by category?

This is a “hidden” feature without a way to do this in the graphical interface, because we disabled the “tag” filter on category pages. So this feature is used by constructing a URL in the following way, as also documented here:

https://edgeryders.eu/tags/c/{category-slug}/{tag-name}

For example:

https://edgeryders.eu/tags/c/openvillage/event

Note that the same list results can also be shown by constructing a search query with tag and category filters set, but the format of the output will be different. Example:

Search results for 'tags:event #openvillage' - Edgeryders

4. Working with users

4.1. How to be notified about new user signups?

How to be notified. To be notified about new user signups, simply subscribe to topic “New members on edgeryders.eu”. Use the “Tracking” or “Watching” notification level, and updates from this topic will be included in your regular Discourse notifications, both on the platform and via e-mail. Discourse will add one comment to this topic whenever a new member registers on edgeryders.eu. (Note, when somebody only registers on our login site communities.edgeryders.eu but never logs in to edgeryders.eu, this will not trigger a notification.)

How to not be notified. By default, a user will not be notified about any updates to this topic, until they choose to as described above. (This is implemented by setting this topic to “Unlisted”. Unlisted topics do not appear in the “Latest” tab for anyone, or in the “New” tab of people who subscribed to this topic’s category. This is better than requiring everyone with access to this topic to set it manually to “Muted” in order to not get notifications, but basically has the same effect.)

Access to the user signup feed topic. This topic is in our “Documentation & Support → Unpublished” category, so it is not accessible to the public. This allows to link to this topic from a public topic without giving access to it; for example the link above in this manual.

How to set this up for your own Discourse installation.

  1. Install our plugin edgeryders-signup-notification.

  2. Create a topic that should act as the user signup feed, place it in an access protected category, an set it to “unlisted” (see above for the reasons).

  3. Enter the topic ID of your signup feed topic in the settings of the edgeryders-signup-notification plugin.

4.2. How to welcome new members on the platform?

See topic “Welcoming new members” (access restricted).

4.3. How to see user statistics?

The platform serves a screen with the full history and participation stats for each user. Example, for username moe: Profile - moe - Edgeryders . There is also a summary version in the Users item in the hamburger menu. And it is wonderful to use: filterable, sortable by any statistic with one click.

There are obvious data structure implications. Implicitly, a network is being induced where the users are nodes, and there are two layers of edges: A likes-the-content of B and A replies-to-the-content-of B. This means that, in the data structure, there is a full users-to-content bipartite network. Would like to discuss this with @matthias in the not-too-distant future.

4.4. How to obtain data with user consent for research use?

The Edgeryders platform has a feature called an ethical consent funnel. This serves to users trying to post for the first time a popup form that we call the “consent funnel”: it asks users to answer some questions before they are able to post in certain categories. They can only proceed past the form when they have answered its questions correctly. We interpret this sequence of events as follows: the user has given informed consent to participating in a research project with Edgeryders, and has understood the nature of her part in the exercise.

Accessing these data requires API access. See the API documentation.

4.5. How to delete a user account?

Please follow the hints given in our website manual, section “4.1. Deleting your account”.

In some cases, you have to temporarily adjust the following Discourse settings to be able to delete all posts of a user at once, and then the user:

You need to be administrator (not just moderator) to be able to do this. Remember to re-set these settings to their previous values afterwards, as they serve as safeguards against harm done accidentally or intentionally by staff users.

4.6. How to fix a user’s signup problem?

When somebody tries to sign up but, sometimes they get stuck, most likely because the e-mail address validation e-mail gets caught up in their spam filter. In these cases the problem can be fixed with the help of an admin of communities.edgeryders.eu, as shown below.

These instructions have been tested with current Chrome (Chromium) and Firefox in 2019-02.

  1. Find and contact a communities.edgeryders.eu admin via this list for help, or if you are that admin yourself, proceed as below. (Being a moderator on communities.edgeryders.eu is not enough as these cannot use the “Impersonate” feature.)

  2. Open an “incognito window” (Chrome) or “private window” (Firefox), and perform all the following actions with browser tabs in that window until the instructions say to go back to your normal browser window.

    (You could keep working in your normal browser window, but would be logged out at the end of the process. Using an incognito window prevents that, as it allows a parallel login.)

  3. Log in as admin on communities.edgeryders.eu.

  4. Find the record of the user with the incomplete signup under “☰ → Admin → Users → New”. Users which did not yet successfully validate their e-mail address are shown in gray in that list.

  5. Click on the user record in that list, make sure the user’s e-mail address does not contain a mistake, and then click “Permissions → Activate Account”.

  6. At the page bottom, click Impersonate. This will log you in as that user until you log out or close the incognito / private window.

  7. In a new browser tab, visit the Edgeryders Communities platform which the user wanted to join, such as edgeryders.eu.

  8. Click “Log In” in the top right. This will immediately log in the user you impersonated on communities.edgeryders.eu. Since it is their first login there, it will create the user’s account and take over their username, name, e-mail address and profile picture from communities.edgeryders.eu.

  9. Log out as the impersonated user, or just close the incognito / private browser window.

  10. Back in your own normal account on an Edgeryders Communities platform such as edgeryders.eu, you can now @mention the new user or send them a message, because you created their account on this platform with admin tools. The system will send them an e-mail about the @mention or message, but of course if the user has a badly configured spam filter that e-mail might get caught up there again.

The above process can also be used to create an account for a user who did not even attempt to sign up themselves. The admin user would simply simulate the user filling the signup form, and then proceed as admin user for account activation and creating the connected account on an Edgeryders Communities site. When doing this, make extra sure to use the right e-mail address, as the process allows to create accounts (and cause e-mails from these accounts) for people who never wanted one.

4.7. How to change a user’s password?

A user can change their own password only via the “I forgot my password” link on the Discourse login form (in our case, the Discourse based SSO login form). They have to click a link in a password reset e-mail that they will receive.

This of course fails when a suer cannot access their e-mail account anymore. It does not elp if te user is still logged in, as there is no option to change ones own password from within ones account settings. So also a moderator or admin using the “Impersonate” feature cannot do it this way, and there is also no admin user interface for that purpose (source).

However, there is a way to do this with the Rails console (source):

  1. Be very careful, including making a backup of the database (via the Discourse Admin interface).

  2. Log into the server via SSH:

    ssh discourse@server.edgeryders.eu

  3. Start the Rails console:

    cd /home/discourse/production/current && bundle exec rails console

  4. Execute these commands in the Rails console, with adapted e-mail address and password:

    u = User.find_by_email('name@example.com')
u.password='zKRR6vTZKvJAB84V9jdgeydS'
u.save!

  5. Press Ctrl + D to exit the Rails console.

4.8. How to mass-download profile pictures of category contributors?

Sometimes, you might like to create a publication that includes profile pictures of everyone who contributed to a specific category (or its sub-categories). We prepared a way that allows to mass-download these profile pictures to a chosen directory:

  1. Visit the Data Explorer query page “Users: for one category, with username and profile picture”.

  2. In field category_id, enter the ID of the category of interest. This can be any top-level or sub-level category on the platform. At the top of the page, you find a quick overview of the category IDs of our top-level categories. Otherwise, you can find the required category ID as the number in category links, which are all listed on the front page.

  3. Click ▸ Run to execute the query.

Now you’ll see a list of all users who contributed to the category, with a profile picture URL where available. (Users without a profile picture are included so that you can mention them with their username or with a placeholder picture, if desired.)

The next task is to mass-download these links. Here is one comfortable option for Firefox, but of course you can use whatever download manager solution you like:

  1. Install the Simple Mass Downloader extension.

  2. Select the text in the result table, but not text in the rest of the page.

  3. Right-click and select “Add selection-links to list”.

  4. In the next dialog, check all boxes, enter a to-be-created directory into “Set directory for checked files” and click “Download now”. This will all profile pictures into a directory of the given name inside your browser’s default download directory.

  5. If you don’t know where your downloads landed, you can find out via the normal “Downloads” button in the Firefox toolbar. Click that button, then “Show all Downloads” in its menu, then any folder button at the right of any of the downloaded profile picture files. That will open the profile picture download folder in your file manager application.

5. Understanding notifications

5.1. Notification types and places

Notification types. To understand Discourse notifications, we distinguish the following two different broad categories of notifications. (Discourse does not use this concept in their own manuals – we made it up.)

  • content notifications: Any notification about new content (topics and posts) to which a user is somehow subscribed. These show up on-platform in the “Unread” and “New” sections and sometimes by e-mail.

  • event notification: Any notification about a more specific event than simply “new content”, namely: direct reply, quotation, @mention, likes, invitation to a topic, edit of your post, private message, new topic, link to your topic. These show up on-platform as a blue bubble on the user menu and as an entry inside it, with an icon corresponding to the event type. They also sometimes show up as e-mails.

Notification places. As already briefly mentioned above, notifications can appear in different places:

  • user menu: The place where event notifications are shown on the edgeryders.eu platform: as little blue bubbles in the user menu, which always correspond to an entry in that user menu.

  • counters: The place where content notifications are shown on the edgeryders.eu platform: as counters in the user’s “New” (for new topics) and “Unread” (for new replies) sections in the frontpage and hamburger menu.

  • e-mail: An e-mail sent to the user’s registered e-mail address. One e-mail can contain one event notification, or one or more content notifications (aggregated according to the “Activity Summary” settings in a user’s account).

  • desktop: Desktop notifications. Not treated in more detail below, as they are simply a copy of event notifications that appear in the user menu. (Content notifications do not appear as desktop notifications, ever.)

    Desktop notifications appear only in a browser if the user enabled them by visiting the user settings form with that browser.

Trigger actions, notification types and notification places are connected by rules that govern what notifications Discourse will shown when and in which place, as detailed below.

5.2. Trigger actions and the notifications they create

Which notifications are sent for which action is influenced by several factors. The most important one is the notification level configured per user for topics, categories and tags. But there are other factors as well ­– here are the details:

  1. When you create a new topic, Discourse creates:

    • Content notifications: For users who subscribed to the topic’s category (which could be “Uncategorized”) with level “Watching First Post” or higher, or to any of the tags that you added to the topic with level “Watching” or higher.

    • Event notifications for “new topic”: For the same users who got the content notifications already. This is the only case where content notifications also result in an associated event notification – the same behavior does not apply for replies to content a user is subscribed to, only for the “new topic” case!

    • Event notifications for “quoted”: For users you quoted in the topic, if any. [TODO Check if this also applies when a user set the topic’s category or any of its tags to subscription level “Muted”. Probably it does. Also find out if and how user muting influences this notification.] If this event notification leads to an e-mail to the user depends on the user’s setting “user menu → Preferences → Email → Send me an email when someone quotes me, replies to my post, mentions my @username, or invites me to a topic”. It is enabled by default.

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail. [TODO: Check if link notifications can only appear for posts that started a topic, or indeed for all posts. If necessary, also adapt this below where the same event is treated for editing post content. Also find out if and how user muting influences this notification.]

    • Event notifications for “@mention”: For users you @mentioned in the topic, if any. The same restrictions as for the “quoted” event apply, see above.

  2. When you post in an existing topic, Discourse creates:

    • Content notifications: For users who subscribed with level “Tracking” or higher to the topic itself, to the topic’s category, or to any of its tags. These subscriptions form a hierarchy: if the user muted the notifications of the topic’s category or any of its tags, she will still get the notification if she overrode that setting on the topic level explicitly.

      Subscribed users also include those who have been reading the topic for some time. as governed by the setting “Automatically track topics I enter” in “user menu → Preferences → Notifications”. The default value is “after 3 minutes”.

      Subscribed users also include the topic’s original author, who is automatically subscribed in level “Watching” (the highest) to the topic she created, until manually overwriting that. When transferring authorship of a topic to another user, it does not affect the notification level set for the topic by the the original or the new author.

    • Event notifications for “direct reply”: For the user to whom you replied. If you reply to the first post or whole topic, it counts as a direct reply to the topic author. [TODO: Confirm that e-mails are only sent for direct replies, not for indirect ones.]

    • Event notifications for “quoted”: (For details, see above for the same event.)

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail.

    • Event notifications for “@mention”: (For details, see above for the same event, and about auto-tracking of topics in muted categories and tags as documented for “quoted” events above.)

  3. When you like a post, Discourse creates:

    • Event notifications for “Like”: For the author of the post you liked, but only if this is allowed by the user setting “Notify when liked”. Note that wiki posts are not treated specially: only the user shown in the avatar icon is considered the author of the post who will be notified about likes.

  4. When you invite somebody to a topic, Discourse creates:

    • Event notifications for “Invite”: For the user you invited. If this event notification results in an e-mail depends on the user setting “user menu → Preferences → Email → Send me an email when someone quotes me, replies to my post, mentions my @username, or invites me to a topic”. It is enabled by default.

  5. When you edit the content of a post: If the post is your own, no notifications whatsoever are created. Otherwise, it does not matter if this post is wiki or not, or if it is the first post of a topic or not. Discourse creates the following notifications:

    • Event notifications for “Edit”: For the author of the post. Note that wiki posts are not treated specially: only the user shown in the avatar icon is considered the author of the post who will be notified about likes. For the e-mail created by this event notification, the same restrictions as for the “quoted” event apply, see above.

    • Event notifications for “quoted”: (For details, see above for the same event.) [TODO: Find out if this notification is created at all when editing post – we haven’t see it in practice so far.]

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail. [TODO: Find out if this notification is created at all when editing post – we haven’t see it in practice so far.]

    • Event notifications for “@mention”: For anyone @mentioned in the new version of the post and has not set the subscription for the topic, category or tag to “Muted”. The on-platform notification will appear to come from the editing user, which is confusing where this is not the original author of the post. (For more details, see above for the same event, and about auto-tracking of topics in muted categories and tags as documented for “quoted” events above.) [TODO: Find out if and how user muting influences this notification.]

  6. When you change the category of a topic, Discourse creates:

    • Content notifications: For users who subscribed to the topic’s new category with level “Watching First Post” or higher, and have not read the topic before. However, if you add the tag with the admin bulk actions feature, no content notification is created.

    • Event notifications for “new topic”: For the same users who got the content notifications already. [TODO: Confirm that this really happens. Maybe not, because the topic is not exactly “new”.]

  7. When you add a tag to a topic, Discourse creates:

    • Content notifications: For users who subscribed to the tags that you added to the topic, with level “Watching” or higher, and have not read the topic before. However, if you add the tag with the admin bulk actions feature, no content notification is created.

    • Event notifications for “new topic”: For the same users who got the content notifications already. [TODO: Confirm that this really happens. Maybe not, because the topic is not exactly “new”.]

  8. When you send somebody a private message, Discourse creates:

    • Event notifications for “private message”: For the recipient(s) of the message. This notification will be shown on-platform, and possibly by e-mail. The latter depends on the user setting “user menu → Preferences → Email → Send me an email when someone messages me …”. It is enabled by default.

5.3. Where and when does Discourse show content notifications?

If the event-triggering user is muted by the recipient (under “Account Menu → Preferences → Notifications → Users: Muted”) or if the content is muted by the recipient, the notification event is not shown anywhere. Else, it is always shown as on-platform, and maybe by e-mail, as governed by the highest notification level found among the user’s settings for the topic, category and applied tags.

An e-mail is however not sent immediately. If the target user is active on the platform (“clicks any link or button”) after the on-platform notification was created, no e-mail is sent because the platform assumes that the user already saw the blue notification bubble (even if not opening the menu and clicking on the notification). The platform will wait for a minimum of 10 minutes for such activity (see in “user menu → Preferences → Email”: “We’ll only email you if we haven’t seen you in the last 10 minutes.”). This is the default behavior, but the user can also configure Discourse to send e-mails even when she is active on the platform.

In addition, the platform will wait longer than 10 minutes before sending an e-mail, as required to give users a chance to finalize their content first by re-editing it after posting. Currently, this is 10 minutes for normal content, so no additional wait time over the default 10 minutes from “waiting for user activity” (see config parameter “email time window mins”). It is however 20 minutes for private messages (see config parameter “private email time window mins”). [TODO: Confirm if that latter config parameter indeed refers to private messages, or to posts in protected categories.]

In addition, the platform might wait even longer before sending an e-mail, depending on the user’s subscription level for the concerned content. Subscription levels have the following effects:

  • Notification level “Muted”: The notification is not shown on-platform, and also not by e-mail.

  • Notification level “Normal:” The notification is not shown on-platform, and also not by e-mail. The user can still get a notification for quotes, a direct reply or an @mention, but this is covered under “Event notifications” below.

  • Notification level “Tracking”: “New” counter for a new topic in a tracked category / with a tracked tag, “Unread” counter for every new reply in a tracked topic. These are entries in the user’s “New” resp. “Unread” tabs on the platform. Note that entries in the “New” tab will disappear automatically again as governed by the user’s setting “user menu → Preferences → Notifications→ Consider topics new when:”.

    If the content results in a current entry in the “Unread” or “New” tab, an e-mail is sent for that content if the user has enabled the setting “When I don’t visit here, send me an email summary of popular topics and replies”. These e-mails are aggregated into activity summary e-mails (“digests”) according to the maximum frequency configured by the user. [TODO: Find out the default value for that setting and the associated frequency setting.] In addition, there is a user setting that lets users exclude “New” tab content from new users in e-mails, as they are spammers with some likelyhood (see user setting “Include content from new users in summary emails”). [TODO: Document what the default value for that setting is.]

  • Notification level “Watching”: Like “Tracking”, but e-mails are sent immediately. So they are not included into the next digest / activity summary.

5.4. Where and when does Discourse show event notifications?

Not at all from blocked users. If the event-triggering user is muted by the recipient (under “Account Menu → Preferences → Notifications → Users: Muted”), the notification event is not shown anywhere.

As user menu and desktop notifications. By default, the notification is always shown as in the user menu and (if the user enabled them) as a desktop notification. [TODO: not sure about this, to be checked]. Event notifications do not influence the “New” and “Unread” counters.

As e-mail. Depending on the triggering event and the user’s settings for such an event, it will also be sent as an e-mail. See the list of triggering events above for the details.

Anyway, an e-mail is not sent immediately: if the target user is active on the platform for a certain time window after the on-platform notification was created, no e-mail is sent. The default time window is 10 minutes but users can change this in “user menu → Preferences → Email”: “We’ll only email you if we haven’t seen you in the last 10 minutes.” In addition, a user can also change this default behavior in the user settings to send e-mails even when she is active on the platform.

6. Other aspects

6.1. How to work with the Discourse API?

We supply the standard public and access protected Discourse APIs, and also our own extensions to the access protected Discourse API that allow access to ethical consent data and to OpenEthnograper codes and annotations.

All the details are documented here:

6.2. How to create a custom Discourse theme?

This is treated in its own topic here:

6.3. How to create a Data Explorer query?

Data Explorer is an official Discourse plugin that allows to create and run SQL queries against the live Discourse database. It allows to create any kinds of up-to-date statistics and to extract any data that Discourse has stored. There is also a way to make these queries accessible to others than just admins, even to the general public.

General instructions for creating and sharing a Data Explorer query:

  1. Go to “☰ → Admin → Plugins → Data Explorer”. You’ll see a list of queries that you can visit and run from their details page.

  2. To create a new query, clic +, enter a query name and click + Create New. This brings you to the detail page for editing and executing the query.

  3. Add a description, enter your SQL query, and click ▸ Save Changes and Run to test your query. The right-hand list of SQL tables and columns helps you create the right query. You can copy & paste the SQL from a similar, existing Data Explorer query to have a starting point, either from our list of queries or from the official list of cool Discourse Data Explorer queries.

  4. To make your query adaptable without having to change the SQL code, you can add parameters. This is esp. relevant if you want to make it accessible to other users, because non-admins can only execute the query but not change its SQL code. There is no complete documentation about parameter usage anywhere so far, but the following example section shows all the relevant options. You place it at the beginning of your query, and use the colon-prefixed identifiers to refer to the parameter inside your SQL.

    -- [params]
-- date :start_date = 2019-08-27
-- text :period = week
-- null int :topic_id

    (There is also an advanced technique of deriving ENUM values from entered parameters, shown here.)

  5. To make the query accessible to more users than just admins, enter names of user groups into the box “Allow groups to access this query”. Then, in the list of queries, you’ll find group-specific access links that you can share with users in the respective groups. Users can also see an overview of data explorer queries accessible to a group they are part of by visiting tab “Reports” of the group’s page (example URL).

    The query’s page in the admin backend is still only accessible to admins (for example, a URL of the form https://edgeryders.eu/admin/plugins/explorer?id=30).

6.4. Staff

Staff members are official representatives of this community. There are two kinds of Staff:

  1. Admins, who can do anything and configure anything on this site.
  2. Moderators, who can edit all posts and users, but cannot add categories or change any site settings.

Staff members can exercise their admin superpowers any time via the admin dashboard at /admin. You can also access it via the “hamburger” menu ☰ in the upper right. Admin functions are generally marked with the wrench :wrench: icon, so look for that.

To add additional staff members:

6.5. Social Logins

Users can log in with traditional local username and password accounts. You may want to add:

You can also set up single-sign on, or even build your own login method.

6.6. Test Your Email

Email is required for new account signups and notifications. Test your email to make sure it is configured correctly! Visit the admin email settings, then enter an email address in the “email address to test” field and click send test email.

  • You got the test email? Great! Read that email closely, it has important email deliverability tips.

  • You didn’t get the test email? This means your users probably aren’t getting any signup or notification emails either.

  • Email deliverability can be hard. Read Email Service Configuration.

If you’d like to enable replying to topics via email, see this howto.

6.7. Categories

You have three default categories:

  1. Site Feedback – general discussion about the site itself. It’s important!

  2. Lounge – a perk for users at trust level 3 and higher

  3. Staff – visible only to staff (admins and moderators)

Don’t create too many initial categories, as you can overwhelm your audience. You can always add more categories, and easily bulk recategorize topics later. It’s better to figure out the organization as you go rather than assuming you’ll get it all right from the beginning (hint: you won’t).

To add a category, visit the categories page, then click Create Category at the upper right. You can set security per-category so only certain groups of users can see topics in that category.

Every category has an initial “About this category” topic. This topic will be pinned to the top of the category, and the description you enter will be used in a bunch of places. Be sure to give your new category a good, clear description, so people understand what belongs there!

6.8. Pinned Topics and Banners

Note that pinning topics does work a little differently in Discourse:

  • Once someone reads to the bottom of a pinned topic, it is automatically unpinned for them specifically. They can change this via the personal pin controls at the bottom of the topic.

  • When staff pins a topic, they can pin it globally to all topic lists, or just within its category.

If a pin isn’t visible enough, you can also turn one single topic into a banner. The banner topic floats on top of all topics and all primary pages. Users can permanently dismiss this floating banner by clicking the × in the upper right corner.

To make (or remove) a pin or a banner, use the admin wrench at the top right or bottom of the topic.

6.9. New User Sandbox and the Trust System

If your discussion area is be open to the public, new visitors will arrive that are initially strangers to the community. Discourse has a trust system where users can, over time, earn the trust of the community and gain abilities to assist in governing their community.

Discourse is designed to offer safe defaults for public communities, even with no active moderation.

> 0 (new) → 1 (basic) → 2 (member) → 3 (regular) → 4 (leader)

All new users start out in a sandbox with restrictions for everyone’s safety. Trust level 0 (new) users cannot …

  • post more than 2 hyperlinks

  • post any images or file attachments

  • send private messages

  • flag posts or topics

  • have actual links in the “about me” field of their profile

  • @name mention more than 2 users in a post

Every action a user can take is rate limited for safety, and especially so for new users. But don’t worry, new users can transition to trust level 1 in about 10 minutes of reading.

These defaults are safe, but note that while in “bootstrap mode” after you set up your site, all new users will be granted trust level 1 until you reach 50 users.

6.10. Sending Invitations

One way to get people to visit your site is to invite them via email. You can do this via:

  • The Invite button at the bottom of the topic.

  • The Invite area on your profile page.

The invite area on your profile page also includes advanced Staff methods of sending bulk invites, and inviting users into groups.

6.11. Maintenance

6.12. Need more Help?

For more assistance on configuring and running your Discourse forum, see meta.discourse.org. In particular, documentation is kept there in the howto category, and especially relevant howtos from there include:

4 Likes
5

How to move a comment thread to a different topic?
Context: We have some comments where questions are asked and answered about a different topic. After getting consent from the people who posted the comments, I would like to move them onto the original topic - how do I do this @matthias?

6

Moving posts to a different topic can be done by moderators like this:

  1. Click the wrench icon in the top right of the page (not the one below a topic’s text).
  2. Choose “Select Posts …”.
  3. Scroll to the posts you want to move, and for each click the new button “select” that has appeared there now. (Or “select +below” as a shortcut to move a whole thread.)
  4. Click “Move to …” in the floating menu to the right that has appeared, and select the topic to move them to.
7

@alberto sorry to be writing here, but a quick question - I am having trouble with setting up new accounts to the platform for the next batch of interviews, it seems like none of the account registration emails is going through, and I have tried numerous temp mails, it seems like it got somewhat chocked.

8

Indeed, I found 4-5 new accounts in https://communities.edgeryders.eu that were not activated, and I activated them manually. You should now be able to use those accounts to log into Edgeryders. Also ping @matthias to find out if he noticed any issue with account creation.

1 Like
9

@alberto @matthias the problem seems to be still there, I am not getting the activate your account link for new accounts:/

10

But you should able to get in with the password regardless, once I activate them, right?

11

I can and I did for the one’s you activated, but I cannot set up new ones for some reason:/

12

I can see that Alberto activated the accounts you created today (@PL68Tadek30aUKR, @PL69Jurek30aUKR, @PL70Wladzio20aUKR) and that right now there are no accounts created by you that are yet to be activated.

However: I checked one of the accounts you created. Account creation time was 9:44, but the account activation e-mail was sent 14:21. And since sharklasers.com etc. typically discard incoming e-mails after an hour, you just missed the e-mail when it finally arrived.

Tried to create a new account with a sharklasers.com e-mail address like you were doing … activation e-mail arrived in 30 s, could activate the account. Tried to re-activate one of the accounts you created today … same result. So the e-mailing delay was temporary.

This means the following process can provide a workaround for you, if the issue happens again:

  1. If the activation e-mail does not arrive within 10 minutes, it’s better to wait for a few hours to let the e-mailing delay issue resolve itself.

  2. Try to log in with your new account at https://communities.edgeryders.eu/login. You will be shown this message:

    You can’t log in yet. We previously sent an activation email to you at […]. Please follow the instructions in that email to activate your account.

  3. Click “Resend Activation Email” to try again if you will receive that activation e-mail now.

Tried to figure out what caused the e-mail delays, and it’s a hickup in the job queing system called “Sidekiq” that is responsible for communities.edgeryders.eu sending its e-mails. Here’s a chart of its processed and failed job counts over the last 6 months:

image
image1170×260 52.2 KB

The uptick of both failures and processed jobs at the very right is the current hickup. Since processed jobs did go up in parallel, most or all jobs got done after some delay, that is, after one or more failed retries. So it’s an inconvenience that will settle out today or tomorrow, like the similar event ca. 3.5 months ago in the chart.

The 135 jobs currently still in the retries queue are indeed all of type “Jobs::UserEmail” or “Jobs::CriticalUserEmail” (the latter covering signups) and failed previously with one of these error message:

  • “Jobs::HandledExceptionWrapper: Wrapped Net::OpenTimeout: execution expired”
  • “ActiveRecord::ConnectionTimeoutError: could not obtain a connection from the pool within 5.000 seconds (waited 5.000 seconds); all pooled connections were in use”

Causes of the first issue can be various (see), esp. including temporary or permanent network misconfiguration or misbehavior. However, the occasionally seen second message together with the fact that we operate our own little mailserver points to a more specific cause in our case: probably a little DoS (Denial of Service) attack that blocks ports on our mailserver so that our own software cannot access it in a timely manner anymore.

This is a new problem to me, and one more reason not to operate ones own mailserver anymore (unlike in 2012 when we started with that practice and e-mail sending was fundamentally simpler). We’ll end that practice when doing our big server migration in 2023, but for now, I’m afraid you have to live with the workaround from above. (Or just be more lucky :stuck_out_tongue: since about 97% of days don’t have this problem.)

1 Like