User metadata

packages/client/src/schedule-helpers.ts

@@ -16,7 +16,9 @@ import { Headers } from '@temporalio/common/lib/interceptors';
 import {
   decodeArrayFromPayloads,
   decodeMapFromPayloads,
+  decodeOptionalSinglePayload,
   encodeMapToPayloads,
+  encodeOptionalToPayload,
   encodeToPayloads,
 } from '@temporalio/common/lib/internal-non-workflow';
 import { temporal } from '@temporalio/proto';
@@ -196,8 +198,7 @@ export function decodeOptionalStructuredCalendarSpecs(
 }
 
 export function compileScheduleOptions(options: ScheduleOptions): CompiledScheduleOptions {
-  const workflowTypeOrFunc = options.action.workflowType;
-  const workflowType = extractWorkflowType(workflowTypeOrFunc);
+  const workflowType = extractWorkflowType(options.action.workflowType);
   return {
     ...options,
     action: {
@@ -270,6 +271,10 @@ export async function encodeScheduleAction(
             }
           : undefined,
       header: { fields: headers },
+      userMetadata: {
+        summary: await encodeOptionalToPayload(dataConverter, action?.staticSummary),
+        details: await encodeOptionalToPayload(dataConverter, action?.staticDetails),
+      },
       priority: action.priority ? compilePriority(action.priority) : undefined,
     },
   };
@@ -320,6 +325,7 @@ export async function decodeScheduleAction(
   pb: temporal.api.schedule.v1.IScheduleAction
 ): Promise<ScheduleDescriptionAction> {
   if (pb.startWorkflow) {
+    const userMetadata = pb.startWorkflow?.userMetadata;
     return {
       type: 'startWorkflow',
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -336,6 +342,8 @@ export async function decodeScheduleAction(
       workflowExecutionTimeout: optionalTsToMs(pb.startWorkflow.workflowExecutionTimeout),
       workflowRunTimeout: optionalTsToMs(pb.startWorkflow.workflowRunTimeout),
       workflowTaskTimeout: optionalTsToMs(pb.startWorkflow.workflowTaskTimeout),
+      staticSummary: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.summary)) ?? undefined,
+      staticDetails: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.details)) ?? undefined,
       priority: decodePriority(pb.startWorkflow.priority),
     };
   }

packages/client/src/schedule-types.ts

@@ -783,6 +783,8 @@ export type ScheduleOptionsStartWorkflowAction<W extends Workflow> = {
   | 'workflowExecutionTimeout'
   | 'workflowRunTimeout'
   | 'workflowTaskTimeout'
+  | 'staticDetails'
+  | 'staticSummary'
 > & {
     /**
      * Workflow id to use when starting. Assign a meaningful business id.
@@ -815,6 +817,8 @@ export type ScheduleDescriptionStartWorkflowAction = ScheduleSummaryStartWorkflo
     | 'workflowExecutionTimeout'
     | 'workflowRunTimeout'
     | 'workflowTaskTimeout'
+    | 'staticSummary'
+    | 'staticDetails'
     | 'priority'
   >;
 

packages/client/src/types.ts

@@ -69,7 +69,23 @@ export type WorkflowExecutionDescription = Replace<
   {
     raw: DescribeWorkflowExecutionResponse;
   }
->;
+> & {
+  /**
+   * General fixed details for this workflow execution that may appear in UI/CLI.
+   * This can be in Temporal markdown format and can span multiple lines.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticDetails: () => Promise<string | undefined>;
+
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary: () => Promise<string | undefined>;
+};
 
 export type WorkflowService = proto.temporal.api.workflowservice.v1.WorkflowService;
 export const { WorkflowService } = proto.temporal.api.workflowservice.v1;

packages/client/src/workflow-client.ts

@@ -32,7 +32,9 @@ import {
   decodeArrayFromPayloads,
   decodeFromPayloadsAtIndex,
   decodeOptionalFailureToOptionalError,
+  decodeOptionalSinglePayload,
   encodeMapToPayloads,
+  encodeOptionalToPayload,
   encodeToPayloads,
 } from '@temporalio/common/lib/internal-non-workflow';
 import { filterNullAndUndefined } from '@temporalio/common/lib/internal-workflow';
@@ -511,7 +513,7 @@ export class WorkflowClient extends BaseClient {
 
   protected async _start<T extends Workflow>(
     workflowTypeOrFunc: string | T,
-    options: WithWorkflowArgs<T, WorkflowOptions>,
+    options: WorkflowStartOptions<T>,
     interceptors: WorkflowClientInterceptor[]
   ): Promise<string> {
     const workflowType = extractWorkflowType(workflowTypeOrFunc);
@@ -1226,6 +1228,10 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: options.cronSchedule,
       header: { fields: headers },
+      userMetadata: {
+        summary: await encodeOptionalToPayload(this.dataConverter, options?.staticSummary),
+        details: await encodeOptionalToPayload(this.dataConverter, options?.staticDetails),
+      },
       priority: options.priority ? compilePriority(options.priority) : undefined,
       versioningOverride: options.versioningOverride ?? undefined,
     };
@@ -1268,7 +1274,6 @@ export class WorkflowClient extends BaseClient {
   protected async createStartWorkflowRequest(input: WorkflowStartInput): Promise<StartWorkflowExecutionRequest> {
     const { options: opts, workflowType, headers } = input;
     const { identity, namespace } = this.options;
-
     return {
       namespace,
       identity,
@@ -1296,6 +1301,10 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: opts.cronSchedule,
       header: { fields: headers },
+      userMetadata: {
+        summary: await encodeOptionalToPayload(this.dataConverter, opts?.staticSummary),
+        details: await encodeOptionalToPayload(this.dataConverter, opts?.staticDetails),
+      },
       priority: opts.priority ? compilePriority(opts.priority) : undefined,
       versioningOverride: opts.versioningOverride ?? undefined,
     };
@@ -1431,8 +1440,13 @@ export class WorkflowClient extends BaseClient {
           workflowExecution: { workflowId, runId },
         });
         const info = await executionInfoFromRaw(raw.workflowExecutionInfo ?? {}, this.client.dataConverter, raw);
+        const userMetadata = raw.executionConfig?.userMetadata;
         return {
           ...info,
+          staticDetails: async () =>
+            (await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.details)) ?? undefined,
+          staticSummary: async () =>
+            (await decodeOptionalSinglePayload(this.client.dataConverter, userMetadata?.summary)) ?? undefined,
           raw,
         };
       },

packages/common/src/activity-options.ts

@@ -124,6 +124,14 @@ export interface ActivityOptions {
    */
   versioningIntent?: VersioningIntent;
 
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary?: string;
+
   /**
    * Priority of this activity
    */
@@ -192,4 +200,12 @@ export interface LocalActivityOptions {
    * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
    */
   cancellationType?: ActivityCancellationType;
+
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary?: string;
 }

packages/common/src/internal-non-workflow/codec-helpers.ts

@@ -72,6 +72,17 @@ export async function decodeOptionalSingle(
   return await decodeSingle(codecs, payload);
 }
 
+/** Run {@link PayloadCodec.decode} and convert from a single Payload */
+export async function decodeOptionalSinglePayload<T>(
+  dataConverter: LoadedDataConverter,
+  payload?: Payload | null | undefined
+): Promise<T | null | undefined> {
+  const { payloadCodecs, payloadConverter } = dataConverter;
+  const decoded = await decodeOptionalSingle(payloadCodecs, payload);
+  if (decoded == null) return decoded;
+  return payloadConverter.fromPayload(decoded);
+}
+
 /**
  * Run {@link PayloadConverter.toPayload} on value, and then encode it.
  */
@@ -80,6 +91,20 @@ export async function encodeToPayload(converter: LoadedDataConverter, value: unk
   return await encodeSingle(payloadCodecs, payloadConverter.toPayload(value));
 }
 
+/**
+ * Run {@link PayloadConverter.toPayload} on an optional value, and then encode it.
+ */
+export async function encodeOptionalToPayload(
+  converter: LoadedDataConverter,
+  value: unknown
+): Promise<Payload | null | undefined> {
+  if (value == null) return value;
+
+  const { payloadConverter, payloadCodecs } = converter;
+  const payload = payloadConverter.toPayload(value);
+  return await encodeSingle(payloadCodecs, payload);
+}
+
 /**
  * Decode `payloads` and then return {@link arrayFromPayloads}`.
  */

packages/common/src/workflow-options.ts

@@ -193,6 +193,21 @@ export interface BaseWorkflowOptions {
    */
   typedSearchAttributes?: SearchAttributePair[] | TypedSearchAttributes;
 
+  /**
+   * General fixed details for this workflow execution that may appear in UI/CLI.
+   * This can be in Temporal markdown format and can span multiple lines.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticDetails?: string;
+  /**
+   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * This can be in single-line Temporal markdown format.
+   *
+   * @experimental User metadata is a new API and suspectible to change.
+   */
+  staticSummary?: string;
+
   /**
    * Priority of a workflow
    */

packages/test/src/test-integration-workflows.ts

@@ -8,7 +8,7 @@ import { msToNumber, tsToMs } from '@temporalio/common/lib/time';
 import { TestWorkflowEnvironment } from '@temporalio/testing';
 import { CancelReason } from '@temporalio/worker/lib/activity';
 import * as workflow from '@temporalio/workflow';
-import { defineQuery, defineSignal } from '@temporalio/workflow';
+import { defineQuery, defineSignal, setHandler } from '@temporalio/workflow';
 import { SdkFlags } from '@temporalio/workflow/lib/flags';
 import {
   ActivityCancellationType,
@@ -19,6 +19,8 @@ import {
   TypedSearchAttributes,
   WorkflowExecutionAlreadyStartedError,
 } from '@temporalio/common';
+import { temporal } from '@temporalio/proto';
+import { decodeOptionalSinglePayload } from '@temporalio/common/lib/internal-non-workflow';
 import { signalSchedulingWorkflow } from './activities/helpers';
 import { activityStartedSignal } from './workflows/definitions';
 import * as workflows from './workflows';
@@ -1414,3 +1416,102 @@ test('Workflow can return root workflow', async (t) => {
     t.deepEqual(result, 'empty test-root-workflow-length');
   });
 });
+
+export async function userMetadataWorkflow(): Promise<string> {
+  let done = false;
+  const signalDef = defineSignal('done');
+  setHandler(signalDef, () => {
+    done = true;
+  });
+
+  // That workflow should call an activity (with summary)
+  const { activityWithSummary } = workflow.proxyActivities({ scheduleToCloseTimeout: '10s' });
+  await activityWithSummary.runWithOptions(
+    {
+      staticSummary: 'activity summary',
+    },
+    []
+  );
+  // Should have a timer (with summary)
+  await workflow.sleep(5, { summary: 'timer summary' });
+  // Set current details
+  workflow.setCurrentDetails('current wf details');
+  // Unblock on var -> query current details (or return)
+  await workflow.condition(() => done);
+  return workflow.getCurrentDetails();
+}
+
+test('User metadata on workflow, timer, activity', async (t) => {
+  const { createWorker, startWorkflow } = helpers(t);
+  const worker = await createWorker({
+    activities: {
+      async activityWithSummary() {},
+    },
+  });
+
+  await worker.runUntil(async () => {
+    // Start a workflow with static details
+    const handle = await startWorkflow(userMetadataWorkflow, {
+      staticSummary: 'wf static summary',
+      staticDetails: 'wf static details',
+    });
+    // Describe workflow -> static summary, static details
+    const desc = await handle.describe();
+    t.true((await desc.staticSummary()) === 'wf static summary');
+    t.true((await desc.staticDetails()) === 'wf static details');
+
+    await handle.signal('done');
+    const res = await handle.result();
+    t.true(res === 'current wf details');
+
+    // Get history events for timer and activity summaries.
+    const resp = await t.context.env.client.workflowService.getWorkflowExecutionHistory({
+      namespace: t.context.env.client.options.namespace,
+      execution: {
+        workflowId: handle.workflowId,
+        runId: handle.firstExecutionRunId,
+      },
+    });
+    for (const event of resp.history?.events ?? []) {
+      if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_WORKFLOW_EXECUTION_STARTED) {
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'wf static summary'
+        );
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.details ?? {}
+          ),
+          'wf static details'
+        );
+      } else if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_ACTIVITY_TASK_SCHEDULED) {
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'activity summary'
+        );
+      } else if (event.eventType === temporal.api.enums.v1.EventType.EVENT_TYPE_TIMER_STARTED) {
+        t.deepEqual(
+          await decodeOptionalSinglePayload(
+            t.context.env.client.options.loadedDataConverter,
+            event.userMetadata?.summary ?? {}
+          ),
+          'timer summary'
+        );
+      }
+    }
+
+    // Run metadata query -> get current details
+    const wfMetadata = (await handle.query('__temporal_workflow_metadata')) as temporal.api.sdk.v1.IWorkflowMetadata;
+    t.deepEqual(wfMetadata.definition?.signalDefinitions?.length, 1);
+    t.deepEqual(wfMetadata.definition?.signalDefinitions?.[0].name, 'done');
+    t.deepEqual(wfMetadata.definition?.queryDefinitions?.length, 3); // default queries
+    t.deepEqual(wfMetadata.currentDetails, 'current wf details');
+  });
+});

packages/test/src/test-schedules.ts

@@ -881,4 +881,31 @@ if (RUN_INTEGRATION_TESTS) {
       await handle.delete();
     }
   });
+
+  test.serial('User metadata on schedule', async (t) => {
+    const { client } = t.context;
+    const scheduleId = `schedule-with-user-metadata-${randomUUID()}`;
+    const handle = await client.schedule.create({
+      scheduleId,
+      spec: {},
+      action: {
+        type: 'startWorkflow',
+        workflowType: dummyWorkflow,
+        taskQueue,
+        staticSummary: 'schedule static summary',
+        staticDetails: 'schedule static details',
+      },
+    });
+
+    try {
+      const describedSchedule = await handle.describe();
+      t.deepEqual(describedSchedule.spec.calendars, []);
+      t.deepEqual(describedSchedule.spec.intervals, []);
+      t.deepEqual(describedSchedule.spec.skip, []);
+      t.deepEqual(describedSchedule.action.staticSummary, 'schedule static summary');
+      t.deepEqual(describedSchedule.action.staticDetails, 'schedule static details');
+    } finally {
+      await handle.delete();
+    }
+  });
 }