Temporal Workflows
Our Docs modernization effort is underway. New documentation will co-exist alongside our current docs content. We're rebuilding the docs for better organization and engagement so you can find what you need to know with clear unambiguous communication.
- This page has not been reviewed for SEO but contains minor enhancements
- This page is revised
Temporal Workflows are the core conceptual element of the Temporal system. They represent a workflow process tailored to your business logic. In Temporal, workflows play two distinct and useful roles.
In the real world, workflows are a sequence of steps or tasks carried out to complete a procedure or reach a goal. They're used in business operations, project management, and software development to build processes. Temporal Workflows follow this pattern, allowing you to write your application code as steps and tasks to complete a process reliably and visibly.
Temporal Workflows' second pattern support event-driven design. They let you model event-driven entities. An entity Workflow might represent a customer, a subscription, or other long running existence. These can persist for a substantial time, whether days, months, or years. Interactions with a running entity Workflow might signal it to start or stop a process, query its current state, or update its information. The Workflow code that responds to these interactions are called Handlers.
- In our documentation, uppercase Workflow refers to elements of the Temporal framework.
- Lowercase workflow describes the steps and tasks that make up a process.
Workflows
Workflows are the core abstraction for Temporal Durable Execution. They are created using the following elements:
- A Workflow Definition is code written in your preferred programming language. This is the code that defines your Workflow and runs when your Workflow is executed. Depending on the language, it is either a function or method, but unlike other functions or methods in that language, it has the benefit of Durable Execution. A Workflow Definition outlines the end-to-end steps, constraints, and tasks needed to achieve a goal within a Temporal application.
- A Workflow Handler is code that lives within a Workflow Definition to process Workflow interaction events. These are also called "message handlers" and can be named for the type of interaction it processes: Signal handler, Update handler, or Query handler.
- A Workflow Type is a name. It identifies a specific Workflow Definition. Although details vary by programming language, a Workflow Type is normally the name of the class, method, or function of your Workflow Definition. As a developer, you can choose a different and possibly more descriptive name if needed. Temporal needs this name to run and control a Workflow.
- A Workflow Execution is a record of a running, completed, or terminated Workflow. This record's information includes the Workflow’s state, History, and other details that enable Temporal to ensure durable execution. It’s the primary unit of tracking and control in Temporal applications. A Workflow Execution can be started by a client application or by a Schedule. It has an input payload, a Workflow Type to run, and a Workflow Run ID assigned by the Temporal System.
- A Workflow Run Id is a globally unique, platform-level identifier for a single Workflow Execution. It provides a Service-level 'name' for each Workflow Execution, although it may change during a Workflow Retry.
The Temporal Service manages and oversees Workflow Executions. It uses Workflow Executions to manage Workflow state and invoke Workflow Definition code to ensure durability and reliability in real world deployment.
The Service coordinates an Execution's run by issuing Tasks, which are picked up by Temporal Workers. Tasks are representations of part of the Execution and are sourced from the Workflow's definition. Workers monitor Temporal Task Queues (this is called "polling"), select available Workflow Tasks, and run those Tasks on Worker processes. These processes invoke your Workflow Definitions, producing the actual code execution that moves your applications forward.
The Temporal Service controls this process, ensuring our core promise of durability and reliability. The Service doesn't execute your Workflow Definition code itself. Instead, your Workflow Definition code runs on your machines, written in the language or languages you choose, compiled with our SDKs.
The following image shows where these pieces live and how they connect:
- A Workflow Execution lives entirely on the Temporal Service.
- A Workflow Definition and its handlers live within Temporal Workers.
This section of the Temporal Encyclopedia introduces Workflows in depth. Here, you'll find all the technical material you need to understand how Workflows are defined and used.