Skip to content

A platform for community discussion. Free, open, simple.

FEATURE: Add workflow action to award gamification scores (#42447)

Rafael dos Santos Silva5c42667a22f4
diff --git a/plugins/discourse-gamification/config/locales/client.en.yml b/plugins/discourse-gamification/config/locales/client.en.yml
index 63a518d147b..2b50daef809 100644
--- a/plugins/discourse-gamification/config/locales/client.en.yml
+++ b/plugins/discourse-gamification/config/locales/client.en.yml
@@ -103,3 +103,18 @@ en:
title: "Gamification"
name: "Name"
period: "Period"
+ discourse_workflows:
+ node_unavailable:
+ requires_gamification: "Requires the Gamification plugin to be enabled"
+ nodes:
+ "action:gamification_score": "Award score"
+ node_descriptions:
+ "action:gamification_score": "Add or deduct gamification points for a user"
+ gamification_score:
+ username: "User"
+ points: "Points"
+ points_description: "Number of points to award. Use a negative value to deduct points."
+ date: "Date"
+ date_description: "Date the points apply to (YYYY-MM-DD). Defaults to today."
+ description: "Description"
+ description_description: "Optional note shown alongside the score event."
diff --git a/plugins/discourse-gamification/config/locales/server.en.yml b/plugins/discourse-gamification/config/locales/server.en.yml
index 877303a4469..a05cdad4a44 100644
--- a/plugins/discourse-gamification/config/locales/server.en.yml
+++ b/plugins/discourse-gamification/config/locales/server.en.yml
@@ -25,3 +25,8 @@ en:
recalculate_scores_remaining: "You’ve reached the maximum number of recalculating scores. Please wait %{time_left} before trying again."
errors:
leaderboard_positions_not_ready: "We are generating your leaderboard. Try again in a few minutes."
+ discourse_gamification:
+ discourse_workflows:
+ gamification_score:
+ invalid_points: "Points must be a non-zero whole number, got: %{points}"
+ invalid_date: "Invalid date: %{date}"
diff --git a/plugins/discourse-gamification/lib/discourse_workflows/nodes/gamification_score/v1.rb b/plugins/discourse-gamification/lib/discourse_workflows/nodes/gamification_score/v1.rb
new file mode 100644
index 00000000000..8251941e24f
--- /dev/null
+++ b/plugins/discourse-gamification/lib/discourse_workflows/nodes/gamification_score/v1.rb
@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+if defined?(DiscourseWorkflows)
+ module DiscourseWorkflows
+ module Nodes
+ module GamificationScore
+ class V1 < DiscourseWorkflows::NodeType
+ OUTPUT_SCHEMA = {
+ "$schema" => Schema::DRAFT_URI,
+ "type" => "object",
+ "properties" => {
+ "score_event_id" => {
+ "type" => "integer",
+ },
+ "user_id" => {
+ "type" => "integer",
+ },
+ "username" => {
+ "type" => "string",
+ },
+ "points" => {
+ "type" => "integer",
+ },
+ "date" => {
+ "type" => "string",
+ },
+ "description" => {
+ "type" => %w[string null],
+ },
+ },
+ }.freeze
+
+ description(
+ name: "action:gamification_score",
+ version: "1.0",
+ defaults: {
+ icon: "trophy",
+ color: "yellow",
+ },
+ group: "discourse_actions",
+ available: -> { SiteSetting.discourse_gamification_enabled },
+ unavailable_reason_key: "discourse_workflows.node_unavailable.requires_gamification",
+ capabilities: {
+ run_scope: "per_item",
+ },
+ output_contracts: [{ schema: OUTPUT_SCHEMA }],
+ properties: {
+ username: {
+ type: :string,
+ required: true,
+ ui: {
+ control: :user,
+ },
+ },
+ points: {
+ type: :integer,
+ required: true,
+ ui: {
+ expression: true,
+ },
+ },
+ date: {
+ type: :string,
+ required: false,
+ ui: {
+ expression: true,
+ },
+ },
+ description: {
+ type: :string,
+ required: false,
+ ui: {
+ expression: true,
+ },
+ },
+ },
+ )
+
+ def execute(exec_ctx)
+ items =
+ exec_ctx.input_items.map.with_index do |_item, item_index|
+ config = {
+ "username" => exec_ctx.get_node_parameter("username", item_index),
+ "points" => exec_ctx.get_node_parameter("points", item_index),
+ "date" => exec_ctx.get_node_parameter("date", item_index),
+ "description" => exec_ctx.get_node_parameter("description", item_index),
+ }
+
+ wrap(process(exec_ctx, config, item_index))
+ end
+
+ [items]
+ end
+
+ private
+
+ def process(exec_ctx, config, item_index)
+ user = exec_ctx.find_user(username: config["username"])
+ points = parse_points(config["points"], item_index)
+ date = parse_date(config["date"], item_index)
+
+ event =
+ ::DiscourseGamification::GamificationScoreEvent.create!(
+ user_id: user.id,
+ date:,
+ points:,
+ description: config["description"].presence,
+ )
+
+ {
+ score_event_id: event.id,
+ user_id: user.id,
+ username: user.username,
+ points: event.points,
+ date: event.date.to_s,
+ description: event.description,
+ }
+ end
+
+ def parse_points(value, item_index)
+ points = Integer(value.to_s, exception: false)
+ if points.nil? || points.zero?
+ raise_node_error!(
+ I18n.t(
+ "discourse_gamification.discourse_workflows.gamification_score.invalid_points",
+ points: value,
+ ),
+ item_index:,
+ )
+ end
+ points
+ end
+
+ def parse_date(value, item_index)
+ return Time.zone.today if value.blank?
+
+ Date.parse(value.to_s)
+ rescue Date::Error
+ raise_node_error!(
+ I18n.t(
+ "discourse_gamification.discourse_workflows.gamification_score.invalid_date",
+ date: value,
+ ),
+ item_index:,
+ )
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-gamification/plugin.rb b/plugins/discourse-gamification/plugin.rb
index 7359049b720..cb5f0c5c2d6 100644
--- a/plugins/discourse-gamification/plugin.rb
+++ b/plugins/discourse-gamification/plugin.rb
@@ -72,6 +72,13 @@ after_initialize do
Guardian.include(DiscourseGamification::GuardianExtension)
end
+ if respond_to?(:register_discourse_workflows_node)
+ register_discourse_workflows_node do
+ require_relative "lib/discourse_workflows/nodes/gamification_score/v1"
+ DiscourseWorkflows::Nodes::GamificationScore::V1
+ end
+ end
+
add_directory_column(
"gamification_score",
query: DiscourseGamification::DirectoryIntegration.query,
diff --git a/plugins/discourse-gamification/spec/lib/discourse_workflows/nodes/gamification_score/v1_spec.rb b/plugins/discourse-gamification/spec/lib/discourse_workflows/nodes/gamification_score/v1_spec.rb
new file mode 100644
index 00000000000..592883249a4
--- /dev/null
+++ b/plugins/discourse-gamification/spec/lib/discourse_workflows/nodes/gamification_score/v1_spec.rb
@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseWorkflows::Nodes::GamificationScore::V1 do
+ fab!(:user)
+
+ let(:sandbox) { DiscourseWorkflows::JsSandbox.new({ "$json" => {} }) }
+ after { sandbox.dispose }
+
+ before do
+ SiteSetting.enable_discourse_workflows = true
+ SiteSetting.discourse_gamification_enabled = true
+ end
+
+ def execute_node(configuration:, item: { "json" => {} })
+ action = described_class.new(parameters: configuration)
+ input_items = [item]
+ resolver =
+ DiscourseWorkflows::ExpressionResolver.new(
+ { "$json" => item.fetch("json") { {} } },
+ sandbox: sandbox,
+ )
+ exec_ctx =
+ DiscourseWorkflows::Executor::NodeExecutionContext.new(
+ input_items: input_items,
+ user: Discourse.system_user,
+ resolver: resolver,
+ parameters: configuration,
+ property_schema: described_class.property_schema,
+ node_context: {
+ },
+ )
+ items = action.execute(exec_ctx)[0]
+ items.first["json"]
+ end
+
+ describe "#execute" do
+ it "creates a score event for the user", :aggregate_failures do
+ config = {
+ "username" => user.username,
+ "points" => 10,
+ "description" => "Helped in the support forum",
+ }
+
+ result = nil
+ expect { result = execute_node(configuration: config) }.to change {
+ DiscourseGamification::GamificationScoreEvent.count
+ }.by(1)
+
+ event = DiscourseGamification::GamificationScoreEvent.last
+ expect(event.user_id).to eq(user.id)
+ expect(event.points).to eq(10)
+ expect(event.date).to eq(Time.zone.today)
+ expect(event.description).to eq("Helped in the support forum")
+
+ expect(result["score_event_id"]).to eq(event.id)
+ expect(result["user_id"]).to eq(user.id)
+ expect(result["username"]).to eq(user.username)
+ expect(result["points"]).to eq(10)
+ expect(result["date"]).to eq(Time.zone.today.to_s)
+ expect(result).to match_node_output_schema(described_class)
+ end
+
+ it "accepts negative points to deduct score" do
+ config = { "username" => user.username, "points" => -5 }
+
+ execute_node(configuration: config)
+
+ expect(DiscourseGamification::GamificationScoreEvent.last.points).to eq(-5)
+ end
+
+ it "uses the provided date" do
+ config = { "username" => user.username, "points" => 3, "date" => "2026-01-15" }
+
+ result = execute_node(configuration: config)
+
+ expect(DiscourseGamification::GamificationScoreEvent.last.date).to eq(Date.new(2026, 1, 15))
+ expect(result["date"]).to eq("2026-01-15")
+ end
+
+ it "stores a nil description when blank" do
+ config = { "username" => user.username, "points" => 3, "description" => "" }
+
+ execute_node(configuration: config)
+
+ expect(DiscourseGamification::GamificationScoreEvent.last.description).to be_nil
+ end
+
+ it "raises when the user does not exist" do
+ config = { "username" => "nonexistent", "points" => 10 }
+
+ expect { execute_node(configuration: config) }.to raise_error(DiscourseWorkflows::NodeError)
+ end
+
+ it "raises when points is zero" do
+ config = { "username" => user.username, "points" => 0 }
+
+ expect { execute_node(configuration: config) }.to raise_error(DiscourseWorkflows::NodeError)
+ end
+
+ it "raises when points is not a number" do
+ config = { "username" => user.username, "points" => "lots" }
+
+ expect { execute_node(configuration: config) }.to raise_error(DiscourseWorkflows::NodeError)
+ end
+
+ it "raises when the date is invalid" do
+ config = { "username" => user.username, "points" => 5, "date" => "not-a-date" }
+
+ expect { execute_node(configuration: config) }.to raise_error(DiscourseWorkflows::NodeError)
+ end
+ end
+end