activities/basics

154 notes in this subject, read out of this brain and free to use. This is page 3 of 3.

Proxy multiple Activities with same options

You can proxy multiple Activities from the same `proxyActivities` call if you want them to share the same timeouts, retries, and options: ```ts export async function Workflow(name: string): Promise<string> { const { act1, act2, act3 } = proxyActivities<typeof activities>(); await act1(); await Promise.all([act2, act3]); } ```

Register Activities with dependencies in Worker

When registering Activities created with dependency injection, pass your shared dependencies accordingly: ```ts import { createActivities } from './activities'; async function run() { const db = { async get(_key: string) { return 'Temporal'; }, }; const worker = await Worker.create({ taskQueue: 'dependency-injection', workflowsPath: require.resolve('./workflows'), activities: createActivities(db), }); await worker.run(); } ```

Activities must be separately registered from Workflows

Activities cannot be in the same file as Workflows and must be separately registered with a Worker.

Activities execute in standard Node.js environment

Activities execute in the standard Node.js environment, not in the Temporal Workflow sandbox.

Activity may be retried repeatedly, use idempotency keys

Activities may be retried repeatedly, so you may need to use idempotency keys for critical side effects to ensure operations are not duplicated.

Simple Activity function example in TypeScript

Example Activity that accepts a string parameter and returns a Promise<string>: ```ts export async function greet(name: string): Promise<string> { return `👋 Hello, ${name}!`; } ```

Large Event Histories can affect Worker performance

All Payload data is recorded in the Workflow Execution Event History. Large Event Histories can affect Worker performance because the entire Event History could be transferred to a Worker Process with a Workflow Task.

Use single object argument for Activity parameters

When passing application data to Activities, it is recommended to use a single object as an argument that wraps the application data. This allows you to change what data is passed to the Activity without breaking a function or method signature.

Activity return values must be serializable

All data returned from an Activity must be serializable. In TypeScript, the return value is always a Promise.

Activity return values subject to payload size limits

Activity return values are subject to payload size limits in Temporal. The default payload size limit is 2MB, and there is a hard limit of 4MB for any gRPC message size. All return values are recorded in the Workflow Execution Event History.

Customize Activity Type with custom name in Worker registration

You can customize the name of the Activity when you register it with the Worker. Example: ```ts import { Worker } from '@temporalio/worker'; import { greet } from './activities'; async function run() { const worker = await Worker.create({ workflowsPath: require.resolve('./workflows'), taskQueue: 'snippets', activities: { activityFoo: greet, }, }); await worker.run(); } ``` In this example, the Activity name is `activityFoo`.

TypeScript SDK activities documentation structure

The TypeScript SDK activities documentation includes the following topics: Activity basics, Activity execution, Timeouts, Asynchronous Activity, Benign exceptions, and Standalone Activities.

Standalone Activity definition - TypeScript

A Standalone Activity is written identically to a Workflow Activity. The Activity function is an async function that may throw ApplicationFailure. An Activity can be executed both as a Standalone Activity and as a Workflow Activity. Example: ```typescript import { ApplicationFailure } from '@temporalio/activity'; export async function greet(name: string): Promise<string> { if (typeof name !== 'string') { throw ApplicationFailure.create({ message: 'name must be a string', nonRetryable: true }); } return `Hello, ${name}!`; } ```

Standalone Activities minimum SDK version

Standalone Activities require Temporal TypeScript SDK v1.17.0 or higher, and Temporal CLI v1.7.0 or higher.

Activity summary using executeWithOptions

You can attach a summary to activities by calling executeWithOptions on the activity proxy with a staticSummary option. The arguments to the activity must be passed as an array. The summary format is a string limited to 200 bytes.

Example: activity with summary using executeWithOptions

const { yourActivity } = proxyActivities<typeof activities>({ startToCloseTimeout: '10 seconds' }); export async function yourWorkflow(input: string): Promise<string> { const result = await yourActivity.executeWithOptions( { staticSummary: 'Processing user data' }, [input] ); return result; }

Hello World Activity example

Example Activity implementation: export async function greet(name: string): Promise<string> { return `Hello, ${name}!`; }

ActivityInboundCallsInterceptor

ActivityInboundCallsInterceptor intercepts inbound calls to an Activity, such as the execute method. This allows you to monitor or modify activity execution at the inbound level.

Activity interceptor example - log start and completion

Example implementation of WorkflowOutboundCallsInterceptor to log Activity start and completion: ```ts import { ActivityInput, Next, WorkflowOutboundCallsInterceptor } from '@temporalio/workflow'; export class ActivityLogInterceptor implements WorkflowOutboundCallsInterceptor { constructor(public readonly workflowType: string) {} async scheduleActivity( input: ActivityInput, next: Next<WorkflowOutboundCallsInterceptor, 'scheduleActivity'> ): Promise<unknown> { console.log('Starting activity', { activityType: input.activityType }); try { return await next(input); } finally { console.log('Completed activity', { workflow: this.workflowType, activityType: input.activityType, }); } } } ```

Local Activities cancellation

Unlike regular Activities, Local Activities can be canceled even if they don't send Heartbeats. Local Activities are handled locally, and all the information needed to handle the cancellation logic is available in the same Worker process.

Local Activities billing behavior

Multiple Local Activities that run back-to-back only count as a single billable action, whereas each regular Activity counts as a billable action. However, if a specific Local Activity fails, all of them will be retried together.

When to stick with Regular Activities instead of Local Activities

Use Regular Activities instead of Local Activities if: Activities may take more than 10 seconds to complete, independent retry control is needed for each Activity, you need to avoid re-running expensive Activities when unrelated Activities fail, immediate Signal/Update handling during execution is required, or separate resource management (like rate limits) is needed for each Activity.

Idempotency key strategy for Activities

Use idempotency keys to prevent duplicate operations when Activities are retried. Combine the Workflow Run ID and Activity ID for a value that is consistent across retries but unique across Workflow Executions.

Design Activities for idempotence

Activities may execute more than once due to retries, so design them to be idempotent by producing the same result whether executed once or multiple times. This is especially important because a Worker can execute an Activity, complete it, and then crash before reporting the result to the Temporal Service. The Activity is retried even though it completed, because the Service has no record of the completion.

Activity return value serialization and size limits

All data returned from an Activity must be serializable. A Go-based Activity Definition can return either just an error or a customValue, error combination. Activity return values are subject to payload size limits: the default payload size limit is 2 MB, with a hard limit of 4 MB for any gRPC message size in the Event History. All return values are recorded in a Workflow Execution Event History, so it is recommended to use a struct type to hold all custom values.

Activity definition

An Activity is a normal function or method that executes a single, well-defined action (either short or long-running). Activities often involve interactions with the outside world, such as sending emails, making network requests, writing to a database, calling an API, querying a database, or transcoding a media file. Activities can also use a Temporal Client to interact with a Temporal Service. Activities are prone to failure, and Temporal automatically retries them based on configuration.

.NET Standalone Activities with Temporal Client

A Temporal Client in .NET can start and manage Standalone Activities directly, without involving a Workflow. This allows direct Activity execution independent of Workflow orchestration.

Standalone Activities in Go SDK client

For Standalone Activities, a Temporal Client can start and manage Standalone Activities directly without involving a Workflow.

Single parameter object recommendation for Activities

Temporal strongly encourages using a single parameter object as an argument to Activities to simplify versioning and maintainability. This allows changing what data is passed to the Activity without breaking a method signature.

Activity parameter size limits

A single argument to an Activity is limited to a maximum size of 2 MB. The total size of a gRPC message, which includes all the arguments, is limited to a maximum of 4 MB.

Activity idempotency requirement

Activity implementation code should be idempotent. This is a fundamental requirement for Activity definitions in Temporal.

Ruby Activity execute method example

class MyActivity < Temporalio::Activity::Definition def execute(input) "#{input['greeting']}, #{input['name']}!" end end

Activity Definition in Ruby SDK

In the Ruby SDK, you develop an Activity Definition by creating a class that extends Temporalio::Activity::Definition. To register a class as an Activity with a custom name, use the activity_name class method in the class definition. Otherwise, the activity name is the unqualified class name.

Activity implementation should be idempotent

A single instance of the Activity implementation may be used across multiple concurrent Activity invocations. Activity implementation code should be idempotent.

Give your agent this brain