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.
These are workflows that were started in the context of another workflow.
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.
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.
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.
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 firstname.lastname@example.org-JUNK. 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.
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.
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.
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.
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.