Glossary

Activity

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 Temporal 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 Temporal client does not implement stubs.

External Workflow

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

Event History

Temporal 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.

Namespace

Temporal is is a multi tenant service. The unit of isolation is called a namespace. Each namespace acts as a namespace for task queue names as well as workflow Ids. For example, when a workflow is started, it is started in a specific namespace. Temporal guarantees a unique workflow Id within a namespace, and supports running workflow executions to use the same workflow Id if they are in different namespaces.

Various configuration options like retention period or archival destination are configured per namespace as well through a special CRUD API or through the Temporal CLI. In the multi-cluster deployment, namespace is a unit of fail-over. Each namespace can only be active on a single Temporal cluster at a time. However, different namespaces can be active in different clusters and can fail-over independently.

Query

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

Temporal 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 jeff@lilltek.com-JUNK. Then you could manage, query, or signal the workflow using this stable name. Temporal 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.

Signal

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.

TaskQueue

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 Temporal cluster. You'll need to specify the namespace where the workflows and activities will be hosted by Temporal and also a task queue string.

Temporal 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

All instances of your workflow should implement exact same workflows and activities because Temporal doesn't track exactly which workflows and activities are exposed by each workflow service instance. Temporal assumes that all worker 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. Temporal may attempt execute it on server-1 but this will fail, because workflow-A isn't implemented there. Temporal 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 Temporal 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,...)

Task Token

Temporal 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 Temporal and then signals Temporal 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
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.

Worker/Service

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 Temporal will assign workflows and activities to each worker service as it sees fit.

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

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. Temporal 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
A Workflow IDs uniquely identify workflows within a Temporal namespace.