DBOS Methods & Variables
Workflow Communication Methods
getEvent
<T> Optional<T> getEvent(String workflowId, String key, Duration timeout)
Retrieve the latest value of an event published by the workflow identified by workflowId to the key key.
If the event does not yet exist, wait for it to be published, returning empty if the wait times out. If the calling workflow is cancelled while waiting, throws DBOSWorkflowCancelledException.
Parameters:
- workflowId: The identifier of the workflow whose events to retrieve.
- key: The key of the event to retrieve.
- timeout: A timeout duration. If the wait times out, an empty Optional is returned.
setEvent
void setEvent(String key, Object value)
void setEvent(String key, Object value, SerializationStrategy serialization)
Create and associate with this workflow an event with key key and value value.
If the event already exists, update its value.
setEvent can only be called from within a workflow.
Parameters:
- key: The key of the event.
- value: The value of the event. Must be serializable.
- serialization: The serialization strategy to use for this event. Defaults to
SerializationStrategy.DEFAULT, which uses the serialization format recorded for the calling workflow.
getAllEvents
Map<String, Object> getAllEvents(String workflowId)
Retrieve all events published by the workflow identified by workflowId, returned as a map of event key to deserialized value.
Parameters:
- workflowId: The identifier of the workflow whose events to retrieve.
send
void send(String destinationId, Object message, String topic)
void send(String destinationId, Object message, String topic, String idempotencyKey)
void send(String destinationId, Object message, String topic, String idempotencyKey, SerializationStrategy serialization)
Send a message to the workflow identified by destinationID.
Messages can optionally be associated with a topic.
Parameters:
- destinationId: The workflow to which to send the message.
- message: The message to send. Must be serializable.
- topic: A topic with which to associate the message. Messages are enqueued per-topic on the receiver.
- idempotencyKey: If
dbos.sendis called from outside a workflow and an idempotency key is set, the message will only be sent once no matter how many timesdbos.sendis called with this key. - serialization: The serialization strategy to use for this message. Defaults to
SerializationStrategy.DEFAULT, which inside a workflow uses the serialization format recorded for the sending workflow (for example, a workflow started with portable serialization sends portable messages), and outside a workflow uses the application's configured serializer.
sendBulk
void sendBulk(List<SendMessage> messages)
void sendBulk(List<SendMessage> messages, boolean sendToForks)
void sendBulk(List<SendMessage> messages, boolean sendToForks, SerializationStrategy serialization)
Send multiple messages to workflows in a single batch. Each message is delivered to its destination workflow independently; messages need not share the same destination.
Parameters:
- messages: A list of
SendMessagerecords describing each message to send. - sendToForks: If
true, also deliver each message to any forked copies of the destination workflow. Defaults tofalse. - serialization: The serialization strategy to use for all messages in the batch. Defaults to
SerializationStrategy.DEFAULT, which behaves as described forsend.
SendMessage
new SendMessage(String destinationId, Object message)
new SendMessage(String destinationId, Object message, String topic)
new SendMessage(String destinationId, Object message, String topic, String idempotencyKey)
A record describing a single message in a sendBulk batch.
Parameters:
- destinationId: The workflow to which to send the message.
- message: The message to send. Must be serializable.
- topic: A topic with which to associate the message.
- idempotencyKey: Idempotency key for exactly-once delivery; a message with a given key is sent only once.
recv
<T> Optional<T> recv(String topic, Duration timeout)
Receive and return a message sent to this workflow.
Can only be called from within a workflow.
Messages are dequeued first-in, first-out from a queue associated with the topic.
Calls to recv wait for the next message in the queue, returning null if the wait times out. If the workflow is cancelled while waiting, recv throws DBOSWorkflowCancelledException.
Parameters:
- topic: A topic queue on which to wait.
- timeout: A timeout duration. If the wait times out, return an empty Optional.
sleep
void sleep(Duration sleepduration)
Sleep for the given duration.
If called from within a workflow, this sleep is durable—it records its intended wake-up time in the database so if it is interrupted and recovers, it still wakes up at the intended time.
If called from outside a workflow, or from within a step, it behaves like a regular Thread.sleep.
Parameters:
- duration: The duration to sleep.
writeStream
void writeStream(String key, Object value)
void writeStream(String key, Object value, SerializationStrategy serialization)
Append a value to a named stream owned by the current workflow. Must be called from within a workflow or step. Consumers read the stream in order via readStream.
Parameters:
- key: The stream name within this workflow. A workflow may have multiple independent streams identified by different keys.
- value: A serializable value to write.
- serialization: The serialization strategy to use. Defaults to
SerializationStrategy.DEFAULT, which uses the serialization format recorded for the calling workflow. UseSerializationStrategy.PORTABLEfor cross-language consumers.
closeStream
void closeStream(String key)
Close a stream, signalling to consumers that no more values will be written. Must be called from within a workflow (not a step). After closing, readStream iterators will drain any remaining values and then stop.
Parameters:
- key: The stream key to close.
readStream
Iterator<Object> readStream(String workflowId, String key)
Read all values written to a stream by the specified workflow. Returns a blocking iterator that stops when the stream is closed or the workflow terminates. Can be called from outside the workflow — typically from a separate thread or external process.
If no workflow with the given ID exists, iterating throws DBOSNonExistentWorkflowException.
On PostgreSQL, the iterator wakes up immediately when a new value is written (via LISTEN/NOTIFY). On CockroachDB, it falls back to polling once per second.
Parameters:
- workflowId: The ID of the workflow that owns the stream.
- key: The stream key to read.
retrieveWorkflow
<T, E extends Exception> WorkflowHandle<T, E> retrieveWorkflow(String workflowId)
Retrieve the handle of a workflow.
Parameters:
- workflowId: The ID of the workflow whose handle to retrieve.
getResult
<T, E extends Exception> T getResult(String workflowId) throws E
Wait for the workflow to complete and return its result, or rethrow the exception it threw.
This is a convenience alternative to retrieveWorkflow(workflowId).getResult().
Parameters:
- workflowId: The ID of the workflow whose result to retrieve.
patch
boolean patch(String patchName)
Insert a patch marker at the current point in workflow history.
Returns true if it was successfully inserted or false if there is already a checkpoint present at this point in history.
Used to safely upgrade workflow code, see the patching tutorial for more detail.
deprecatePatch
boolean deprecatePatch(String patchName)
Safely bypass a patch marker at the current point in workflow history if present.
Always returns true.
Used to safely deprecate patches, see the patching tutorial for more detail.
Enqueueing Workflows by Name
enqueueWorkflow
<T, E extends Exception> WorkflowHandle<T, E> enqueueWorkflow(
EnqueueOptions options, Object[] args)
<T, E extends Exception> WorkflowHandle<T, E> enqueueWorkflow(
EnqueueOptions options, Object[] positionalArgs, Map<String, Object> namedArgs)
Enqueue a workflow by name, without a reference to its function, and return a handle to it.
This takes the same EnqueueOptions as DBOSClient.enqueueWorkflow and writes the same database record, so the enqueued workflow may be implemented by another process, another application sharing this system database, or an application written in another language.
Unlike startWorkflow, the options are not validated against this process's registered workflows and queues.
If no application version is set, the workflow is only dequeued by an executor running the owning application's latest version.
The enqueued workflow is owned by this application unless EnqueueOptions.withApplicationName names another one; see Sharing a System Database.
enqueueWorkflow may be called from inside a workflow, where the enqueued workflow is recorded as a child: if the calling workflow is recovered, it gets a handle to the original child rather than enqueueing a second one.
It may not be called from inside a step; doing so throws IllegalStateException.
Inside a workflow, the enqueued workflow's timeout is resolved as for startWorkflow: unless EnqueueOptions sets one, it inherits the calling workflow's timeout; withNoTimeout() declines it.
Parameters:
- options: The workflow name, queue, and other options; see
EnqueueOptions. - args / positionalArgs: The workflow's positional arguments.
- namedArgs: The workflow's named arguments, for targets that take them (for example, a Python workflow with keyword arguments). Only portable serialization carries named arguments, so passing any requires
withSerialization(SerializationStrategy.PORTABLE)on the options; otherwise the call throwsIllegalArgumentException.
Example Syntax:
var options = new EnqueueOptions("processOrder", "com.example.OrderServiceImpl", QueueName.of("orders"))
.withApplicationName("order-service");
WorkflowHandle<Object, Exception> handle =
dbos.enqueueWorkflow(options, new Object[] {"order-123"});
Workflow Management Methods
WorkflowStatus
Some workflow introspection and management methods return a WorkflowStatus.
This object has the following definition:
public record WorkflowStatus(
// The workflow ID
String workflowId,
// The workflow status: ENQUEUED, PENDING, DELAYED, SUCCESS, ERROR, CANCELLED, or MAX_RECOVERY_ATTEMPTS_EXCEEDED
WorkflowState status,
// The name of the workflow function
String workflowName,
// The class of the workflow function
String className,
// The name given to the class instance, if any
String instanceName,
// The authenticated user who initiated the workflow, if any
String authenticatedUser,
// The assumed role for the workflow execution, if any
String assumedRole,
// Roles authenticated for the workflow
List<String> authenticatedRoles,
// The deserialized workflow input
Object[] input,
// The workflow's output, if any
Object output,
// The error the workflow threw, if any
ErrorResult error,
// The ID of the executor (process) that most recently executed this workflow
String executorId,
// When the workflow was created
Instant createdAt,
// The last time the workflow status was updated
Instant updatedAt,
// The application version on which this workflow was started
String appVersion,
// The application identifier
String appId,
// The number of times this workflow has been started
Integer recoveryAttempts,
// If this workflow was enqueued, on which queue
String queueName,
// The workflow timeout duration, if any
Duration timeout,
// The absolute deadline for the workflow, if any
Instant deadline,
// When the workflow started executing (after being dequeued), if applicable
Instant startedAt,
// The deduplication ID assigned to this workflow, if any
String deduplicationId,
// The priority assigned to this workflow in its queue, if any
Integer priority,
// The queue partition key, if any
String queuePartitionKey,
// The ID of the workflow this was forked from, if any
String forkedFrom,
// The parent workflow ID if this is a child workflow, if any
String parentWorkflowId,
// Whether another workflow has been forked from this one
Boolean wasForkedFrom,
// Time until which the workflow is delayed before starting
Instant delayUntil,
// When the workflow completed (terminal states only)
Instant completedAt,
// The serialization format used for the workflow's inputs/outputs
String serialization,
// Custom key-value metadata attached to the workflow
Map<String, Object> attributes,
// The name of the schedule that started this workflow, if any
String scheduleName,
// The application that owns this workflow, or null if no application owns it
String applicationName,
// Whether this is a debounced workflow, whose deduplication ID is its debounce key
Boolean isDebounced,
// The latest a debounced workflow's start may be pushed back to, or null for no cap
Instant debounceDeadline
)
See Sharing a System Database for how applications own workflows.
listWorkflows
List<WorkflowStatus> listWorkflows(ListWorkflowsInput input)
Retrieve a list of WorkflowStatus of all workflows matching specified criteria.
ListWorkflowsInput
ListWorkflowsInput is a with-based configuration record for filtering and customizing workflow queries. All fields are optional.
with Methods:
Many filters accept either a single value or a list. Single-value overloads are provided for convenience.
withWorkflowIds
ListWorkflowsInput withWorkflowIds(String workflowId)
ListWorkflowsInput withWorkflowIds(List<String> workflowIds)
Filter by one or more workflow IDs.
withClassName
ListWorkflowsInput withClassName(String className)
Filter workflows by the class name containing the workflow function.