Merge pull request cadence-workflow#287 from Bueller87/add-query-with-markdown-return-samples

feat: add Custom Workflow Controls (Markdoc query) samples

Author: Bueller87

README.md

@@ -27,6 +27,8 @@ These samples demonstrate various capabilities of Java Cadence client and server
     the result to a destination. The first activity can be picked up by any worker. However, the second and third activities
     must be executed on the same host as the first one.
 
+* **Custom Workflow Controls** ([`com.uber.cadence.samples.query`](src/main/java/com/uber/cadence/samples/query/)) — workflow queries that return **markdown** for Cadence Web (Markdoc buttons that **signal** workflows or **start** new workflows). **Requires Cadence Web v4.0.14+.** Copy-paste run instructions: [query samples README](src/main/java/com/uber/cadence/samples/query/README.md).
+
 ## Get the Samples
 
 Run the following commands:
@@ -79,6 +81,8 @@ top right corner from "Open" to "Closed" to see the list of the completed workfl
 Click on a *RUN ID* of a workflow to see more details about it. Try different view formats to get a different level of
 details about the execution history.
 
+For **query responses rendered as markdown** (Custom Workflow Controls), use **Cadence Web v4.0.14 or newer** and follow the [query samples README](src/main/java/com/uber/cadence/samples/query/README.md).
+
 ## Install Cadence CLI
 
 [Command Line Interface Documentation](https://mfateev.github.io/cadence/docs/08_cli)
@@ -118,7 +122,23 @@ execute together, we recommend that you run more than one instance of this worke
 The second command starts workflows. Each invocation starts a new workflow execution.
 
     ./gradlew -q execute -PmainClass=com.uber.cadence.samples.fileprocessing.FileProcessingStarter
-    
+
+### Custom Workflow Controls (Markdoc query responses)
+
+These samples need **Cadence Web v4.0.14+**. Run a **worker** in one terminal, then a **starter** in another. See [src/main/java/com/uber/cadence/samples/query/README.md](src/main/java/com/uber/cadence/samples/query/README.md) for full copy-paste steps.
+
+Worker (task list `query`):
+
+    ./gradlew -q execute -PmainClass=com.uber.cadence.samples.query.QueryWorker
+
+Starters (pick one per run):
+
+    ./gradlew -q execute -PmainClass=com.uber.cadence.samples.query.MarkdownQueryStarter
+    ./gradlew -q execute -PmainClass=com.uber.cadence.samples.query.LunchVoteStarter
+    ./gradlew -q execute -PmainClass=com.uber.cadence.samples.query.OrderFulfillmentStarter
+
+In Cadence Web, open the workflow → **Query** tab → run query **`Signal`**, **`options`**, or **`dashboard`** (matching the starter you used).
+
 ### Trip Booking
 
 Cadence implementation of the [Camunda BPMN trip booking example](https://github.com/berndruecker/trip-booking-saga-java)

src/main/java/com/uber/cadence/samples/query/LunchVoteStarter.java

@@ -0,0 +1,56 @@
+/*
+ *  Copyright 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Modifications copyright (C) 2017 Uber Technologies, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not
+ *  use this file except in compliance with the License. A copy of the License is
+ *  located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file. This file is distributed on
+ *  an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ *  express or implied. See the License for the specific language governing
+ *  permissions and limitations under the License.
+ */
+
+package com.uber.cadence.samples.query;
+
+import com.uber.cadence.client.WorkflowClient;
+import com.uber.cadence.client.WorkflowOptions;
+import java.time.Duration;
+import java.util.UUID;
+
+/** Starts a {@link LunchVoteWorkflow} execution. Use Cadence Web Query tab → options. */
+public final class LunchVoteStarter {
+
+  private LunchVoteStarter() {}
+
+  public static void main(String[] args) {
+    try {
+      WorkflowClient workflowClient = QuerySampleSupport.newWorkflowClient();
+
+      WorkflowOptions options =
+          new WorkflowOptions.Builder()
+              .setTaskList(QueryConstants.TASK_LIST)
+              .setExecutionStartToCloseTimeout(Duration.ofMinutes(12))
+              .setWorkflowId("lunch-vote-" + UUID.randomUUID())
+              .build();
+
+      LunchVoteWorkflow.WorkflowIface workflow =
+          workflowClient.newWorkflowStub(LunchVoteWorkflow.WorkflowIface.class, options);
+
+      // Starts the workflow asynchronously — the starter can exit immediately.
+      WorkflowClient.start(workflow::run);
+      System.out.println(
+          "Started LunchVoteWorkflow. In Cadence Web (v4.0.14+), open the run, Query tab → options.");
+      System.exit(0);
+    } catch (RuntimeException e) {
+      if (QuerySampleSupport.printHintIfDomainMissing(e)) {
+        System.exit(1);
+      }
+      throw e;
+    }
+  }
+}

src/main/java/com/uber/cadence/samples/query/LunchVoteWorkflow.java

@@ -0,0 +1,198 @@
+/*
+ *  Copyright 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Modifications copyright (C) 2017 Uber Technologies, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not
+ *  use this file except in compliance with the License. A copy of the License is
+ *  located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file. This file is distributed on
+ *  an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ *  express or implied. See the License for the specific language governing
+ *  permissions and limitations under the License.
+ */
+
+package com.uber.cadence.samples.query;
+
+import static com.uber.cadence.samples.query.QueryConstants.CLUSTER;
+import static com.uber.cadence.samples.query.QueryConstants.DOMAIN;
+import static com.uber.cadence.samples.query.QueryConstants.TASK_LIST;
+
+import com.uber.cadence.workflow.QueryMethod;
+import com.uber.cadence.workflow.SignalMethod;
+import com.uber.cadence.workflow.Workflow;
+import com.uber.cadence.workflow.WorkflowMethod;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Demonstrates interactive voting via Cadence Web (v4.0.14+). Signals accumulate votes and the
+ * query named {@code options} renders current results and vote buttons as markdown.
+ */
+public final class LunchVoteWorkflow {
+
+  private LunchVoteWorkflow() {}
+
+  /**
+   * Signal payload for a lunch vote. Public fields are required so Cadence's JSON data converter
+   * can deserialize the signal input. Field names must match the JSON keys in the Markdoc
+   * {@code input=} attribute (e.g. {@code input={"location":"Farmhouse","meal":"Red Thai Curry"}}).
+   */
+  public static class LunchOrder {
+    public String location;
+    public String meal;
+    public String requests;
+
+    /** No-arg constructor required for JSON deserialization. */
+    public LunchOrder() {}
+
+    public LunchOrder(String location, String meal, String requests) {
+      this.location = location;
+      this.meal = meal;
+      this.requests = requests;
+    }
+  }
+
+  /**
+   * The voting pattern: the workflow method keeps the execution open for a voting window, signals
+   * mutate state (accumulate votes), and the query reads that state to render the current results.
+   */
+  public interface WorkflowIface {
+
+    @WorkflowMethod(
+        name = QueryConstants.LUNCH_VOTE_WORKFLOW_TYPE,
+        executionStartToCloseTimeoutSeconds = 700,
+        taskList = TASK_LIST)
+    void run();
+
+    /** Visible as "options" in the Cadence Web Query dropdown. */
+    @QueryMethod(name = "options")
+    MarkdownFormattedResponse optionsQuery();
+
+    /**
+     * {@code name} sets the signal type string the worker listens for. It must match the
+     * {@code signalName} attribute in the Markdoc template so Cadence Web sends the right signal.
+     */
+    @SignalMethod(name = "lunch_order")
+    void lunchOrder(LunchOrder vote);
+  }
+
+  public static final class WorkflowImpl implements WorkflowIface {
+
+    private final List<LunchOrder> votes = new ArrayList<>();
+
+    private String cachedWorkflowId = "";
+    private String cachedRunId = "";
+
+    @Override
+    public void run() {
+      cachedWorkflowId = Workflow.getWorkflowInfo().getWorkflowId();
+      cachedRunId = Workflow.getWorkflowInfo().getRunId();
+      // Keep the workflow open for the voting period. Votes arrive via the lunchOrder signal
+      // while the workflow sleeps; Workflow.sleep is interruptible by signals.
+      Workflow.sleep(Duration.ofMinutes(10));
+    }
+
+    @Override
+    public MarkdownFormattedResponse optionsQuery() {
+      String workflowId = cachedWorkflowId;
+      String runId = cachedRunId;
+      String voteTable = makeLunchVoteTable(votes);
+      String menuTable = makeLunchMenu();
+
+      String data =
+          "\n## Lunch Options\n\n"
+              + "We're voting on where to order lunch today. Select the option you want to vote for.\n\n"
+              + "---\n\n"
+              + "### Current Votes\n\n"
+              + voteTable
+              + "\n"
+              + "### Menu Options\n\n"
+              + menuTable
+              + "\n\n---\n\n"
+              + "### Cast Your Vote\n\n"
+              + signalBlock(
+                  workflowId,
+                  runId,
+                  "Farmhouse - Red Thai Curry",
+                  "{\"location\":\"Farmhouse\",\"meal\":\"Red Thai Curry\",\"requests\":\"spicy\"}")
+              + signalBlock(
+                  workflowId,
+                  runId,
+                  "Ethiopian Wat",
+                  "{\"location\":\"Ethiopian\",\"meal\":\"Wat with Injera\",\"requests\":\"\"}")
+              + signalBlock(
+                  workflowId,
+                  runId,
+                  "Ler Ros - Tofu Bahn Mi",
+                  "{\"location\":\"Ler Ros\",\"meal\":\"Tofu Bahn Mi\",\"requests\":\"\"}")
+              + "\n{% br /%}\n\n"
+              + "*Vote closes when workflow times out (10 minutes)*\n\t";
+
+      return new MarkdownFormattedResponse(data);
+    }
+
+    /** Builds a Markdoc {@code {%- signal -%}} tag. Every attribute is required for Cadence Web
+     *  to route the signal to the correct workflow execution. */
+    private static String signalBlock(
+        String workflowId, String runId, String label, String jsonInput) {
+      return "{% signal \n"
+          + "\tsignalName=\"lunch_order\" \n"
+          + "\tlabel=\""
+          + label
+          + "\"\n"
+          + "\tdomain=\""
+          + DOMAIN
+          + "\"\n"
+          + "\tcluster=\""
+          + CLUSTER
+          + "\"\n"
+          + "\tworkflowId=\""
+          + workflowId
+          + "\"\n"
+          + "\trunId=\""
+          + runId
+          + "\"\n"
+          + "\tinput="
+          + jsonInput
+          + "\n/%}\n";
+    }
+
+    @Override
+    public void lunchOrder(LunchOrder vote) {
+      votes.add(vote);
+    }
+
+    private static String makeLunchVoteTable(List<LunchOrder> votes) {
+      if (votes.isEmpty()) {
+        return "| Location | Meal | Requests |\n|----------|------|----------|\n| *No votes yet* | | |\n";
+      }
+      StringBuilder table = new StringBuilder();
+      table.append("| Location | Meal | Requests |\n|----------|------|----------|\n");
+      for (LunchOrder vote : votes) {
+        table
+            .append("| ")
+            .append(vote.location != null ? vote.location : "")
+            .append(" | ")
+            .append(vote.meal != null ? vote.meal : "")
+            .append(" | ")
+            .append(vote.requests != null ? vote.requests : "")
+            .append(" |\n");
+      }
+      return table.toString();
+    }
+
+    private static String makeLunchMenu() {
+      return "| Picture | Description |\n"
+          + "|---------|-------------|\n"
+          + "| {% image src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/e/e2/Red_roast_duck_curry.jpg/200px-Red_roast_duck_curry.jpg\" alt=\"Red Thai Curry\" width=\"200\" /%} | **Farmhouse - Red Thai Curry**: A dish in Thai cuisine made from curry paste, coconut milk, meat, seafood, vegetables, and herbs. |\n"
+          + "| {% image src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/0/0c/B%C3%A1nh_m%C3%AC_th%E1%BB%8Bt_n%C6%B0%E1%BB%9Bng.png/200px-B%C3%A1nh_m%C3%AC_th%E1%BB%8Bt_n%C6%B0%E1%BB%9Bng.png\" alt=\"Tofu Bahn Mi\" width=\"200\" /%} | **Ler Ros - Tofu Bahn Mi**: A Vietnamese sandwich with a baguette filled with lemongrass tofu, vegetables, and fresh herbs. |\n"
+          + "| {% image src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/5/54/Ethiopian_wat.jpg/960px-Ethiopian_wat.jpg\" alt=\"Ethiopian Wat\" width=\"200\" /%} | **Ethiopian Wat**: A traditional Ethiopian stew made from spices, vegetables, and legumes, served with injera flatbread. |\n"
+          + "\n*(source: wikipedia)*";
+    }
+  }
+}

src/main/java/com/uber/cadence/samples/query/MarkdownFormattedResponse.java

@@ -0,0 +1,80 @@
+/*
+ *  Copyright 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Modifications copyright (C) 2017 Uber Technologies, Inc.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not
+ *  use this file except in compliance with the License. A copy of the License is
+ *  located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file. This file is distributed on
+ *  an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ *  express or implied. See the License for the specific language governing
+ *  permissions and limitations under the License.
+ */
+
+package com.uber.cadence.samples.query;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * The JSON shape Cadence Web (v4.0.14+) expects for formatted query responses. When a {@link
+ * com.uber.cadence.workflow.QueryMethod} returns this object, the default data converter serializes
+ * it to:
+ *
+ * <pre>{@code
+ * {
+ *   "cadenceResponseType": "formattedData",
+ *   "format": "text/markdown",
+ *   "data": "<your markdown string>"
+ * }
+ * }</pre>
+ *
+ * Cadence Web detects this shape and renders the {@code data} field as markdown (with Markdoc
+ * extensions) instead of displaying raw JSON.
+ */
+public final class MarkdownFormattedResponse {
+
+  private final String cadenceResponseType;
+  private final String format;
+  private final String data;
+
+  /**
+   * Constructor for JSON deserialization (e.g. Java clients using the Cadence SDK data converter).
+   * A no-arg constructor cannot populate {@code private final} fields; {@code @JsonCreator} with
+   * explicit properties is required.
+   */
+  @JsonCreator
+  private MarkdownFormattedResponse(
+      @JsonProperty("cadenceResponseType") String cadenceResponseType,
+      @JsonProperty("format") String format,
+      @JsonProperty("data") String data) {
+    this.cadenceResponseType = cadenceResponseType;
+    this.format = format;
+    this.data = data;
+  }
+
+  /**
+   * @param markdownData the markdown string to render in Cadence Web. May include Markdoc tags such
+   *     as {@code {%- signal -%}} and {@code {%- start -%}}.
+   */
+  public MarkdownFormattedResponse(String markdownData) {
+    // These two values are the required constants that Cadence Web checks for.
+    this("formattedData", "text/markdown", markdownData);
+  }
+
+  public String getCadenceResponseType() {
+    return cadenceResponseType;
+  }
+
+  public String getFormat() {
+    return format;
+  }
+
+  public String getData() {
+    return data;
+  }
+}