Click or drag to resize


This section describes the primary Cadence workflow concepts and terminology. You should take the time to skim over these terms to give you come context as you dive further in.


Workflow implementations are typically organized into workflows that make decisions determining what's do be done and activities that actually perform the work. For example, workflows may decide to read/write something to a database or call an external service and then then workflow will call an activity to actually perform the operation.

You can think of a workflow as the decider and activities as the primary way for workflows to interact with the outside world, which a workflow should never do directly.

Child Workflow

These are workflows that were started in the context of another workflow.

Client Stub

Stubs provide a way define workflows and activities using an interface such that you'll be able to start and interact with workflows and activities using strongly typed methods that will be verified by the .NET compiler when building your code.

This capability was pioneered by Uber with their Java API and we were strongly encouraged to go this route for .NET (which was an easy decision since it's obviously better). The Go Cadence client does not implement stubs.


A Cadence cluster is designed to support multi-tenant deployments. Cadence handles workflow and activity state as well as the assignment of work to tenant supplied workers. Cadence organizes workflows and activities into domains. Every domain has a name as well as a handful configuration settings. Typical deployments will assign workflows and activities by the organization managing these or also by the operation category.

For a Cadence cluster supporting multiple teams you could create a domain named for each team. If these teams need to run test workflows, you could create new domains with the team name plus -test. Cadence domain capacity is close to being unconstrained, so you could even create separate domains for each of your developers if needed.

External Workflow

These are top-level workflows that were not started as a child workflow.


The workflow and activities you develop will need to be hosted in a workflow service that you'll write. This can be a simple as a Console application that registers the workflows and activities it implements with the Cadence cluster. You'll need to specify the domain where the workflows and activities will be hosted by Cadence and also a task queue string.

Cadence uses the task queue you specify to identify all instances of a workflow service running such that work can be distributed to across these services.

Important note Important

All instances of your workflow should implement exact same workflows and activities because Cadence doesn't track exactly which workflows and activities are exposed by each worker instance. Cadence assumes that all service instances registered with same task queue can execute any of the registered workflows and activities.

For example, say you have workflow-A and workflow-B running on server-0 and then workflow-B and workflow-C running on server-1, and both of these registered with task lisk MYTASKS. Then you execute workflow A. Cadence may attempt execute it on server-1 but this will fail, because workflow-A isn't implemented there. Cadence is smart and will retry by selecting another worker registered for MYTASKS until it finds a worker that can handle it (or the workflow times out).

So Cadence will typically recover and execte the workflow or activity but recognize that there may be some delay. You should also keep this in the back of your mind when you're thinking about how workflow services should be upgraded (e.g. all at once, rolling update,...)

Event History

Cadence tracks workflow and activity executions such that the past decisions and workflow state is durably persisted to the cluster database. This is the secret that allows developers to author workflows as basic code when under the covers, the workflow is essentially a state machine.


Started workflows can be queried synchronously by client applications to retrieve information about the current state of the workflow. This is a read-only operation and a query must never modify workflow state.

Run ID

Cadence assigns a UUID to each execution of a workflow so they can be uniquely identified. This differs from the workflow ID which is essentially the name of the workflow. For example, you could start a workflow managing a user's junk email folder with a workflow ID like Then you could manage, query, or signal the workflow using this stable name. Cadence will assign a UUID as the run ID and if the workflow restarts itself, the new run will retain the same workflow ID, but will be assigned a new run ID.


Signals provides a convienent way to inform a workflow that something external happened. Signals may include arbitrary parameters but signals don't return a result. Signals are delivered asynchronously, meaning the caller may see the signal method return before the workflow actually received the signal.

Workflow signal methods will typically use a WorkflowQueueT to interact with the workflow decision logic.

Task Token

Cadence supports external activity completion. This is a less convienent an alternative to signalling. You can take advantage of this by starting an activity that instead of completing the operation itself, obtains a task token from Cadence and then signals Cadence that the activity will be completed externally.

Before the activity returns, it will need to put the token somewhere (like a database) and then you'll have an external service waiting for something to happen that indicates that activity can be completed and then use the task token to complete the activity, specifying the return value if necessary.

Tip Tip

External activity completion implementions are generally more difficulit to code because you need to worry about saving the token somewhere and you also need to code an external service that may need to do activity heartbeating.

We recommend that you use signals for most situations.


This is an application or service that implements one or more workflows and/or activities. When a worker or worker service starts, it will register its workflows and activities with Cadence. Then Cadence will assign workflows and activities to each worker service as it sees fit.

Your workflow and activity code will be executed as required with Cadence recording state as the workflow progresses as well as the results returned by the activities and workflow.


Essentially, a workflow is a method that runs some logic and optionally returns a result. The method is written in C# or some other compatible .NET language. Workflows always interact with the external world via activities. Workflows use activities to query external state so that can impact decisions made by the workflow and workflows also use activities to impact the outside world by writting to a database, sending an email, etc.

Workflows can be configured to run for very long times. Years and perhaps even centuries. Cadence ensures that the state of an executing workflow will be durably persisted such that the workflow can be reassigned to a different worker in response to server failures, load-balancing, etc.

Workflow Execution

A WorkflowExecution is used to identify an instance of a workflow. This included the workflow and run IDs and may reference a workflow that's still in progress or a completed workflow.

Workflow ID

A workflow ID is essentially the name of the workflow. This is an arbitrary string. It's often handy to set this to some kind of business identifier like the name of the entity the workflow is handling.

Note Note

A Workflow IDs uniquely identify workflows within a Cadence domain.

See Also