Discourse

1. Overview

Discourse is a modern, open-source platform for community discussions, mailing lists, and long-form chat. It's designed for civilized conversation and is used by companies and communities worldwide to host their forums.

The GoInsight Discourse node allows you to automate and integrate your forum management tasks directly into your workflows. You can perform a wide range of administrative and content management actions, including:

• User Management: Create new users, retrieve user lists, and manage their group memberships.
• Group Administration: Create, update, and retrieve community groups.
• Content Creation: Programmatically create and update posts and topics.
• Category Organization: Manage the structure of your forum by creating, updating, and listing categories.

2. Prerequisites

Before using this node, you must have:

• A valid account with access to a Discourse instance.
• API access enabled on your Discourse instance.
• An API Key and API Username with the necessary permissions to perform the desired actions. You may need administrator privileges to generate these credentials.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides operations to manage the core resources of a Discourse forum, such as Categories, Groups, Posts, Topics, and Users.

Operation Details

Add a User to a Group

Add a user to a specific group in Discourse

Input Parameters:

• GroupId: The ID of the group to add the user to
• Username: The username of the user to add to the group

Output:

• Success (bool): Whether the user was successfully added to the group
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Create a Category

Create a new category in Discourse

Input Parameters:

• CategoryData: The data for the category in JSON format (at least 'name' field required, optional 'color', 'text_color', etc.)

Output:

• Category (object): The created category object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Create a Group

Create a new group in Discourse

Input Parameters:

• GroupData: The data for the group in JSON format (at least 'name' field required, optional 'automatic_membership_email_domains', etc.)

Output:

• CreatedGroup (object): The created group object
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Create a Post

Create a new post in Discourse

Input Parameters:

• PostData: The data for the post in JSON format (at least 'raw' field required, optional 'title', 'category', 'topic_id', etc.)

Output:

• Post (object): The created post object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Create a User

Create a new user in Discourse

Input Parameters:

• UserData: The data for the user in JSON format (at least 'username', 'name', 'email', 'password' fields required, optional additional fields)

Output:

• User (object): The created user object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Get Many Categories

Get many categories from discourse

Output:

• Categories (object-array): List of category objects
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Get Many Groups

Get many groups from Discourse

Output:

• Groups (object-array): List of group objects
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Get Many Posts

Retrieve multiple posts from a specific topic in Discourse

Input Parameters:

• TopicId: The ID of the topic to retrieve posts from

Output:

• Posts (object-array): Array of retrieved post objects
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Get Many Topics

Retrieve multiple topics from Discourse, optionally filtered by category

Input Parameters:

• CategoryId: Optional category ID to filter topics (if provided, gets topics from this category; otherwise, gets latest topics)

Output:

• Topics (object-array): Array of retrieved topic objects
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Get Many Users

Get many users from discourse

Options:

• ListFlag: List type identifier, optional values include "all" (all users), "active" (active users), "new" (new users), etc., default is "all".

Output:

• Users (object-array): Users messages
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Get a Group

Get a specific group from Discourse

Input Parameters:

• GroupName: The name of the group to fetch

Output:

• Group (object): The fetched group object
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Get a Post

Retrieve a specific post from Discourse by ID

Input Parameters:

• PostId: The ID of the post to retrieve

Output:

• Post (object): The retrieved post object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Get a User

Get a single user from Discourse by username

Input Parameters:

• Username: The username of the user to retrieve.

Output:

• User (object): The retrieved user object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Remove a User from a Group

Remove a user from a specific group in Discourse

Input Parameters:

• GroupId: The ID of the group to remove the user from
• Username: The username of the user to remove from the group

Output:

• Success (bool): Whether the user was successfully removed from the group
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

Update a Category

Update an existing category in Discourse

Input Parameters:

• CategoryId: The ID of the category to update
• CategoryData: The updated data for the category in JSON format (fields to update, e.g., 'name', 'color')

Output:

• UpdatedCategory (object): The updated category object
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Update a Group

Update an existing group in Discourse

Input Parameters:

• GroupId: The ID of the group to update
• GroupData: The updated data for the group in JSON format (fields to update, e.g., 'visible', 'name')

Output:

• UpdatedGroup (object): The updated group object
• StatusCode (number): HTTP response code
• ErrorMessage (string): HTTP response error message

Update a Post

Update a specific post in Discourse by ID

Input Parameters:

• PostId: The ID of the post to update
• UpdateData: The data to update the post with in JSON format (e.g., {'raw': 'Updated content'})

Output:

• Post (object): The updated post object
• StatusCode (number): Http response code
• ErrorMessage (string): Http response error message

5. Example Usage

This section will guide you through creating a simple workflow to post a new topic to your Discourse forum using the "Create a Post" operation.

The workflow will consist of three nodes: Start -> Discourse: Create a Post -> Answer.

Step-by-Step Guide

1. Add the Discourse Node:
   • In the workflow canvas, click the + button to add a new node.
   • In the panel that appears, select the "Tools" tab.
   • Find and select "Discourse" from the list of tools.
   • From the list of supported operations for Discourse, click on "Create a Post" to add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Post" node to open its configuration panel on the right.
   • Credentials: In the "Credentials" field at the top of the panel, click the dropdown menu and select your pre-configured Discourse credential.
   • Parameters: Fill in the required input parameters.
   • PostData: This field requires a JSON-formatted string containing the details of the post you want to create. To create a new topic, you must include a title and the content in raw. You can also specify a category ID. For example:
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
   • Click the "Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the post was created successfully.

After completing these steps, your workflow is fully configured. When you run it, a new topic will be automatically created in the specified category on your Discourse forum.

6. FAQs

Q: Why am I getting a 403 Forbidden error?

A: A 403 error typically indicates a permissions issue. Please check the following:

• API Key Scopes: Ensure the API key you are using has the necessary permissions (scopes) to perform the intended action. For example, creating users or categories often requires admin-level permissions.
• User Privileges: Verify that the user associated with the API key has the appropriate privileges within the Discourse forum itself.

Q: How do I format the JSON data for inputs like PostData or UserData?

A: The input must be a valid JSON string. You can construct this string using previous nodes (like a Code node) or enter it manually. For a complete list of available fields for each object, refer to the official Discourse API documentation. For example, to create a post, the minimum required field is raw. A more complete example for creating a new topic would be: {"title": "My Post Title", "raw": "This is the post content.", "category": 5}.

Q: How can I find the ID for a specific category or group?

A: You can use the "Get Many Categories" or "Get Many Groups" operations within your workflow. These operations will return a list of all available categories or groups, including their respective IDs. You can then use the output from these nodes as input for other operations that require an ID.

7. Official Documentation

For more detailed information about the Discourse API, including all available parameters and advanced functionalities, please refer to the Discourse Official API Documentation.