User metadata (#1657)

Co-authored-by: James Watkins-Harvey <james.watkinsharvey@temporal.io>

Author: THardy98

packages/client/src/schedule-helpers.ts

@@ -7,6 +7,7 @@ import {
   extractWorkflowType,
   LoadedDataConverter,
 } from '@temporalio/common';
+import { encodeUserMetadata, decodeUserMetadata } from '@temporalio/common/lib/user-metadata';
 import {
   encodeUnifiedSearchAttributes,
   decodeSearchAttributes,
@@ -196,8 +197,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 +270,7 @@ export async function encodeScheduleAction(
             }
           : undefined,
       header: { fields: headers },
+      userMetadata: await encodeUserMetadata(dataConverter, action.staticSummary, action.staticDetails),
       priority: action.priority ? compilePriority(action.priority) : undefined,
     },
   };
@@ -320,6 +321,7 @@ export async function decodeScheduleAction(
   pb: temporal.api.schedule.v1.IScheduleAction
 ): Promise<ScheduleDescriptionAction> {
   if (pb.startWorkflow) {
+    const { staticSummary, staticDetails } = await decodeUserMetadata(dataConverter, pb.startWorkflow?.userMetadata);
     return {
       type: 'startWorkflow',
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -336,6 +338,8 @@ export async function decodeScheduleAction(
       workflowExecutionTimeout: optionalTsToMs(pb.startWorkflow.workflowExecutionTimeout),
       workflowRunTimeout: optionalTsToMs(pb.startWorkflow.workflowRunTimeout),
       workflowTaskTimeout: optionalTsToMs(pb.startWorkflow.workflowTaskTimeout),
+      staticSummary,
+      staticDetails,
       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

@@ -24,6 +24,7 @@ import {
   WorkflowIdConflictPolicy,
   compilePriority,
 } from '@temporalio/common';
+import { encodeUserMetadata } from '@temporalio/common/lib/user-metadata';
 import { encodeUnifiedSearchAttributes } from '@temporalio/common/lib/converter/payload-search-attributes';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
 import { History } from '@temporalio/common/lib/proto-utils';
@@ -32,6 +33,7 @@ import {
   decodeArrayFromPayloads,
   decodeFromPayloadsAtIndex,
   decodeOptionalFailureToOptionalError,
+  decodeOptionalSinglePayload,
   encodeMapToPayloads,
   encodeToPayloads,
 } from '@temporalio/common/lib/internal-non-workflow';
@@ -509,7 +511,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);
@@ -1220,6 +1222,7 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: options.cronSchedule,
       header: { fields: headers },
+      userMetadata: await encodeUserMetadata(this.dataConverter, options.staticSummary, options.staticDetails),
       priority: options.priority ? compilePriority(options.priority) : undefined,
       versioningOverride: options.versioningOverride ?? undefined,
     };
@@ -1262,7 +1265,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,
@@ -1290,6 +1292,7 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: opts.cronSchedule,
       header: { fields: headers },
+      userMetadata: await encodeUserMetadata(this.dataConverter, opts.staticSummary, opts.staticDetails),
       priority: opts.priority ? compilePriority(opts.priority) : undefined,
       versioningOverride: opts.versioningOverride ?? undefined,
     };
@@ -1425,8 +1428,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

@@ -125,6 +125,14 @@ export interface ActivityOptions {
    */
   versioningIntent?: VersioningIntent; // eslint-disable-line deprecation/deprecation
 
+  /**
+   * A fixed, single-line 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.
+   */
+  summary?: string;
+
   /**
    * Priority of this activity
    */
@@ -193,4 +201,12 @@ export interface LocalActivityOptions {
    * - `ABANDON` - Do not request cancellation of the activity and immediately report cancellation to the workflow.
    */
   cancellationType?: ActivityCancellationType;
+
+  /**
+   * A fixed, single-line 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.
+   */
+  summary?: string;
 }

packages/common/src/converter/payload-converter.ts

@@ -44,6 +44,18 @@ export function toPayloads(converter: PayloadConverter, ...values: unknown[]): P
   return values.map((value) => converter.toPayload(value));
 }
 
+/**
+ * Run {@link PayloadConverter.toPayload} on an optional value, and then encode it.
+ */
+export function convertOptionalToPayload(
+  payloadConverter: PayloadConverter,
+  value: unknown
+): Payload | null | undefined {
+  if (value == null) return value;
+
+  return payloadConverter.toPayload(value);
+}
+
 /**
  * Run {@link PayloadConverter.toPayload} on each value in the map.
  *

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

@@ -1,5 +1,5 @@
 import { Payload } from '../interfaces';
-import { arrayFromPayloads, fromPayloadsAtIndex, toPayloads } from '../converter/payload-converter';
+import { arrayFromPayloads, fromPayloadsAtIndex, PayloadConverter, toPayloads } from '../converter/payload-converter';
 import { PayloadConverterError } from '../errors';
 import { PayloadCodec } from '../converter/payload-codec';
 import { ProtoFailure } from '../failure';
@@ -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 { payloadConverter, payloadCodecs } = 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.
  */

packages/common/src/internal-workflow/index.ts

@@ -1,2 +1,7 @@
 export * from './enums-helpers';
-export * from './objects-helpers';
+export {
+  filterNullAndUndefined,
+  mergeObjects,
+  // ts-prune-ignore-next
+  deepMerge,
+} from './objects-helpers';

packages/common/src/internal-workflow/objects-helpers.ts

@@ -35,3 +35,33 @@ export function mergeObjects<T extends Record<string, any>>(
 
   return changed ? (merged as T) : original;
 }
+
+function isObject(item: any): item is Record<string, any> {
+  return item && typeof item === 'object' && !Array.isArray(item);
+}
+
+/**
+ * Recursively merges two objects, returning a new object.
+ *
+ * Properties from `source` will overwrite properties on `target`.
+ * Nested objects are merged recursively.
+ *
+ * Object fields in the returned object are references, as in,
+ * the returned object is not completely fresh.
+ */
+export function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+  const output = { ...target };
+
+  if (isObject(target) && isObject(source)) {
+    for (const key of Object.keys(source)) {
+      const sourceValue = source[key];
+      if (isObject(sourceValue) && key in target && isObject(target[key] as any)) {
+        output[key as keyof T] = deepMerge(target[key], sourceValue);
+      } else {
+        (output as any)[key] = sourceValue;
+      }
+    }
+  }
+
+  return output;
+}

packages/common/src/user-metadata.ts

@@ -0,0 +1,58 @@
+import { temporal } from '@temporalio/proto';
+import { convertOptionalToPayload, PayloadConverter } from './converter/payload-converter';
+import { LoadedDataConverter } from './converter/data-converter';
+import { decodeOptionalSinglePayload, encodeOptionalSingle } from './internal-non-workflow';
+
+/**
+ * User metadata that can be attached to workflow commands.
+ */
+export interface UserMetadata {
+  /** @experimental A fixed, single line summary of the command's purpose */
+  staticSummary?: string;
+  /** @experimental Fixed additional details about the command for longer-text description, can span multiple lines */
+  staticDetails?: string;
+}
+
+export function userMetadataToPayload(
+  payloadConverter: PayloadConverter,
+  staticSummary: string | undefined,
+  staticDetails: string | undefined
+): temporal.api.sdk.v1.IUserMetadata | undefined {
+  if (staticSummary == null && staticDetails == null) return undefined;
+
+  const summary = convertOptionalToPayload(payloadConverter, staticSummary);
+  const details = convertOptionalToPayload(payloadConverter, staticDetails);
+
+  if (summary == null && details == null) return undefined;
+
+  return { summary, details };
+}
+
+export async function encodeUserMetadata(
+  dataConverter: LoadedDataConverter,
+  staticSummary: string | undefined,
+  staticDetails: string | undefined
+): Promise<temporal.api.sdk.v1.IUserMetadata | undefined> {
+  if (staticSummary == null && staticDetails == null) return undefined;
+
+  const { payloadConverter, payloadCodecs } = dataConverter;
+  const summary = await encodeOptionalSingle(payloadCodecs, convertOptionalToPayload(payloadConverter, staticSummary));
+  const details = await encodeOptionalSingle(payloadCodecs, convertOptionalToPayload(payloadConverter, staticDetails));
+
+  if (summary == null && details == null) return undefined;
+
+  return { summary, details };
+}
+
+export async function decodeUserMetadata(
+  dataConverter: LoadedDataConverter,
+  metadata: temporal.api.sdk.v1.IUserMetadata | undefined | null
+): Promise<UserMetadata> {
+  const res = { staticSummary: undefined, staticDetails: undefined };
+  if (metadata == null) return res;
+
+  const staticSummary = (await decodeOptionalSinglePayload<string>(dataConverter, metadata.summary)) ?? undefined;
+  const staticDetails = (await decodeOptionalSinglePayload<string>(dataConverter, metadata.details)) ?? undefined;
+
+  return { staticSummary, staticDetails };
+}