Find workflows that wait for a signal
The quote workflow in Write a workflow waits for an approval signal when
a quote is over 1000. Whoever approves quotes needs two answers: whether one quote waits for
approval, and which quotes wait. Status answers the first by asking that instance. A projection
over the workflow's journal answers the second, and a second projection lists every instance with
its status.
The complete programs are in samples/approvals/fsharp and samples/approvals/csharp. They compile
the quote workflow from samples/workflows unchanged, reference the projects under src/ and
Dapper 2.1.66, and need FCQRS.Workflows 7.10.0 or later for IsWaitingFor and
WorkflowJournal.InstanceOf. The C# program also needs FCQRS 7.3.0 or later for
AddKeyedTransactionalProjection.
Check one quote before approving it
Shared setup
module Quote =
open System
open System.Threading.Tasks
open FCQRS.Common
open FCQRS.Workflows
// What the workflow is started with.
type QuoteRequest = {
Customer: string
Symbol: string
Quantity: int
}
// What the workflow returns.
type Quote = {
Total: decimal
Approved: bool
Receipt: string
}
// The external systems the workflow calls. Each call gets a key that is the
// same for every attempt of one step, so a system that remembers keys can
// recognise a repeated call.
type IPriceService =
abstract Fetch: key: string * symbol: string -> Task<decimal>
type IMailer =
abstract Send:
key: string * customer: string * total: decimal -> Task<string>
// Five attempts, 200 ms apart, each allowed 30 seconds.
let private retry = {
Retry.times 5 (TimeSpan.FromSeconds 30.0) with
Schedule = FixedInterval(TimeSpan.FromMilliseconds 200.0)
}
let definition (prices: IPriceService) (mailer: IMailer) =
Workflow.define "quote" (fun (request: QuoteRequest) -> workflow {
// The price is stored once it arrives. A restart after this step
// does not call the price service again.
let! price =
activity "price" retry (fun attempt ->
prices.Fetch(attempt.IdempotencyKey, request.Symbol))
let total = price * decimal request.Quantity
// A quote over 1000 waits for a person, for at most one day.
let! approved = workflow {
if total <= 1000m then
return true
else
let! answer =
waitSignalFor<bool> "approval" (TimeSpan.FromDays 1.0)
return defaultArg answer false
}
if not approved then
return { Total = total; Approved = false; Receipt = "" }
else
let! receipt =
activity "send-quote" retry (fun attempt ->
mailer.Send(
attempt.IdempotencyKey, request.Customer, total))
return { Total = total; Approved = true; Receipt = receipt }
})
open System
open System.Data.Common
open Dapper
open Microsoft.Data.Sqlite
open Microsoft.Extensions.Configuration
open Microsoft.Extensions.Logging
open FCQRS.Actor
open FCQRS.FSharp
open FCQRS.ProjectionStorage
open FCQRS.Projections
open FCQRS.Workflows
open Quote
let connectionString = "Data Source=approvals.db"
let logging = LoggerFactory.Create(fun _ -> ())
let configuration = ConfigurationBuilder().Build()
let connection = Fcqrs.connect DBType.Sqlite connectionString
let api = Fcqrs.actor configuration logging (Some connection) "approvals"
let prices =
{ new IPriceService with
member _.Fetch(_, _) = task { return 12.5m } }
let mailer =
{ new IMailer with
member _.Send(_, _, _) = task { return "sent" } }
let quotes = Workflows.register api (definition prices mailer)
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.QuoteSystemThreadingTasksFCQRSFCQRS.CommonContains common types like Events and Commands Functionality for Write Side.
WorkflowsFcqrs_550-how-to_011-find-waiting-workflows.md_page.Quote.QuoteRequestCustomer: stringstringAn abbreviation for the CLI type . Basic Types
Symbol: stringQuantity: intintAn abbreviation for the CLI type . Basic Types
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.Quote.QuoteTotal: decimaldecimalAn abbreviation for the CLI type . Basic Types
Approved: boolboolAn abbreviation for the CLI type . Basic Types
Receipt: stringFcqrs_550-how-to_011-find-waiting-workflows.md_page.Quote.IPriceServiceFetch: IPriceService -> string * string -> Task<decimal>keysymbolSystem.Threading.Tasks.Task`1Represents an asynchronous operation that can return a value. The type of the result produced by this .
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.Quote.IMailerSend: IMailer -> string * string * decimal -> Task<string>customertotalretry: RetryPolicyFCQRS.Workflows.RetryCommon retry policies.
times: int -> TimeSpan -> RetryPolicyAt most `attempts` attempts, with backoff from one second to one minute. Each attempt fails when it has not finished within `attemptTimeout`.
System.TimeSpanRepresents a time interval.
FromSeconds: float -> TimeSpanReturns a that represents a specified number of seconds, where the specification is accurate to the nearest millisecond. A number of seconds, accurate to the nearest millisecond. is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue. -or- is . -or- is . is equal to . An object that represents .
Schedule: RetryScheduleThe wait between attempts.
FixedIntervalRe-send at a fixed interval.
FromMilliseconds: float -> TimeSpanReturns a that represents a specified number of milliseconds. A number of milliseconds. is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue. -or- is . -or- is . is equal to . An object that represents .
definition: IPriceService -> IMailer -> WorkflowDefinition<QuoteRequest,Quote>prices: IPriceServicemailer: IMailerFCQRS.Workflows.WorkflowDefines workflows.
define: string -> ('Input -> Workflow<'Result>) -> WorkflowDefinition<'Input,'Result>A workflow named `name` whose instances run `body` on their input.
request: QuoteRequestworkflow: WorkflowBuilderBuilds a workflow: `workflow { let! x = activity ... }`.
price: decimalactivity: string -> RetryPolicy -> (AttemptContext -> Task<'T>) -> Workflow<'T>Calls an external system. The call runs at least once: a crash after the call and before its result is stored repeats it, so pass `IdempotencyKey` to the external system. `name` is stored and must not change while instances are running. The policy needs an `AttemptTimeout` or a `Deadline`: an attempt with neither would wait as long as its call, also for a call that ignores its cancellation token.
attempt: AttemptContextFetch: string * string -> Task<decimal>IdempotencyKey: stringThe same for every attempt of this step, across restarts: workflow name, workflow ID, and step path. Pass it to the external system so a repeated call is recognised.
total: decimal(*): ^T1 -> ^T2 -> ^T3Overloaded multiplication operator The first parameter. The second parameter. The result of the operation. 8 * 6 // Evaluates to 48
decimal: ^T -> decimalConverts the argument to System.Decimal using a direct conversion for all primitive numeric types. For strings, the input is converted using UInt64.Parse() with InvariantCulture settings. Otherwise the operation requires an appropriate static conversion method on the input type. The input value. The converted decimal. decimal "42.23" // evaluates to 42.23M decimal 0xff // evaluates to 255M decimal -10 // evaluates to -10M
approved: bool(<=): 'T -> 'T -> boolStructural less-than-or-equal comparison The first parameter. The second parameter. The result of the comparison. 5 <= 1 // Evaluates to false 5 <= 5 // Evaluates to true [1; 5] <= [1; 6] // Evaluates to true
answer: bool optionwaitSignalFor: string -> TimeSpan -> Workflow<'T option>Waits for a signal named `name` for at most `timeout`, measured from the stored start of the step. Gives `None` when the time passes first; a signal that arrives later stays stored for the next wait.
FromDays: float -> TimeSpanReturns a that represents a specified number of days, where the specification is accurate to the nearest millisecond. A number of days, accurate to the nearest millisecond. is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue. -or- is . -or- is . is equal to . An object that represents .
defaultArg: 'T option -> 'T -> 'TUsed to specify a default value for an optional argument in the implementation of a function An option representing the argument. The default value of the argument. The argument value. If it is None, the defaultValue is returned. type Vector(x: double, y: double, ?z: double) = let z = defaultArg z 0.0 member this.X = x member this.Y = y member this.Z = z let v1 = Vector(1.0, 2.0) v1.Z // Evaluates to 0. let v2 = Vector(1.0, 2.0, 3.0) v2.Z // Evaluates to 3.0
``not``: bool -> boolNegate a logical value. Not True equals False and not False equals True The value to negate. The result of the negation. not (2 + 2 = 5) // Evaluates to true // not is a function that can be compose with other functions let fileDoesNotExist = System.IO.File.Exists >> not
receipt: stringSend: string * string * decimal -> Task<string>DataCommonDapperMicrosoftSqliteExtensionsConfigurationLoggingFCQRS.ActorFCQRS.FSharpIdiomatic-F# functional facade for FCQRS. Gives F# consumers the same one-call ergonomics the C# host-builder (HostExtensions.fs) gives C#, but with F# idioms: records-of-functions for the definitions, typed handles for the results, an explicit wiring pipeline, and plain helpers for saga side effects. It is a *pure addition* that wraps only the existing primitives (IActor.InitializeActor / SagaBuilder.initSimple / Projections.startTracked / InitializeSagaStarter / CreateCommandSubscription / Actor.api) and changes nothing in the C# interop layer or the core. open FCQRS.FSharp let api = Fcqrs.actor config loggerFactory (Some (Fcqrs.connect DBType.Sqlite conn)) "Cluster" let documents = Fcqrs.aggregate api { Name="Document"; Initial=...; Decide=...; Fold=... } let slugs = Fcqrs.aggregate api { Name="Slug"; Initial=...; Decide=...; Fold=... } let publication = Fcqrs.saga api (publicationDef documents.Factory slugs.Factory) Fcqrs.wireSagaStarters api [ publication ] let subs = Fcqrs.projection api (Projection.single 0 updateReadModel) // (Projection.multi when you must control which notifications publish) // send a command and await the matching aggregate reply: let! ev = documents.Send (Fcqrs.newCid()) (Fcqrs.aggregateId id) cmd (fun e -> ...)
FCQRS.ProjectionStorageSQL storage for journal-wide, transactional projection catch-up.
FCQRS.ProjectionsTransactional projections with a journal-wide, durable catch-up boundary.
connectionString: stringlogging: ILoggerFactoryMicrosoft.Extensions.Logging.LoggerFactoryProduces instances of classes based on the given providers.
Create: Action<ILoggingBuilder> -> ILoggerFactoryCreates new instance of configured using provided delegate. A delegate to configure the . The that was created.
configuration: IConfigurationRoot``.ctor``: unit -> unitBuild: unit -> IConfigurationRootBuilds an with keys and values from the set of providers registered in . An with keys and values from the registered providers.
connection: ConnectionFCQRS.FSharp.Fcqrsconnect: DBType -> string -> ConnectionBuild a SQLite/etc. Connection from a raw connection string of any length.
FCQRS.Actor.DBTypeRepresents the type of database connection
SqliteSQLite using Microsoft.Data.Sqlite provider
api: FCQRS.Common.IActoractor: IConfiguration -> ILoggerFactory -> Connection option -> string -> FCQRS.Common.IActorCreate the actor system from plain values (cluster name as a string).
SomeThe representation of "Value of type 'T" The input value. An option representing the value.
_: IPriceServiceFetch: string * string -> Threading.Tasks.Task<decimal>task: TaskBuilderBuilds a task using computation expression syntax.
_: IMailerSend: string * string * decimal -> Threading.Tasks.Task<string>quotes: WorkflowHandle<QuoteRequest,Quote>FCQRS.Workflows.WorkflowsRegisters workflows with an actor system.
register: FCQRS.Common.IActor -> WorkflowDefinition<'Input,'Result> -> WorkflowHandle<'Input,'Result>Registers the workflow and returns its handle. Instances that were running when the process last stopped resume as soon as this is called.
// Approves one quote. Status asks the instance, which replays its journal
// first when it is not in memory.
let approve id =
async {
let! status = quotes.Status id
if status.IsWaitingFor "approval" then
do! Workflows.signal quotes id "approval" true
return true
else
return false
}
approve: string -> Async<bool>id: stringasync: AsyncBuilderBuilds an asynchronous workflow using computation expression syntax. let sleepExample() = async { printfn "sleeping" do! Async.Sleep 10 printfn "waking up" return 6 } sleepExample() |> Async.RunSynchronously
status: WorkflowStatusquotes: WorkflowHandle<QuoteRequest,Quote>Status: string -> Async<WorkflowStatus>Where the instance is.
IsWaitingFor: string -> boolWhether the body is waiting on a step with this name, such as a signal wait, whose step is named after its signal. `false` for an instance that is not running.
FCQRS.Workflows.WorkflowsRegisters workflows with an actor system.
signal: WorkflowHandle<'Input,'Result> -> string -> string -> 'Signal -> Async<unit>Stores the signal `name` with a typed payload for the instance `id`.
// Approves one quote. StatusAsync asks the instance, which replays its journal
// first when it is not in memory.
async Task<bool> Approve(string id)
{
var status = await quotes.StatusAsync(id);
if (!status.IsWaitingFor("approval"))
return false;
await quotes.SignalAsync(id, "approval", true);
return true;
}
Status gives Running with the steps the body waits on. A signal wait's step is named after its
signal, so IsWaitingFor "approval" is true while the quote waits for this signal.
- The check tells the caller whether an approval is expected. A signal is stored even when no
wait is pending: one sent to a quote that is still fetching its price is taken when the wait
starts. One sent to a quote that has ended raises
InvalidOperationException. - The answer can be out of date when the signal arrives. A wait that times out between the two
calls ends the quote unapproved, and the signal then raises
InvalidOperationException. Catch it where the approver's request is handled. Statusasks the instance. One that is not in memory replays its journal and stays in memory until it has had no request forakka.fcqrs.workflow-idle-timeout. Ask about one ID at a time; to find the waiting quotes, use the projection below.
List the quotes that wait
A workflow stores the start and the end of each step in its journal, as WorkflowRecord events, so
a projection can read them like an aggregate's events. This one keeps a table of the quotes that
wait for approval, in the journal's database:
Shared setup
module Approvals =
open System.Data.Common
open System.Threading.Tasks
open Akka.Persistence.Query
open Dapper
open FCQRS.Workflows
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.ApprovalsSystemDataCommonThreadingTasksAkkaPersistenceQueryDapperFCQRSWorkflows// One row for each quote that waits for its approval, with the time its wait
// times out. The table is in the journal's database.
let createTable =
"create table if not exists quote_approvals (
id text primary key,
due text)"
createTable: string// One row for each quote that waits for its approval, with the time its wait
// times out. The table is in the journal's database.
public const string CreateTable =
"""
create table if not exists quote_approvals (
id text primary key,
due text)
""";
The handler adds a row when the wait starts and deletes it when the wait or the quote ends:
let private waits =
"insert or replace into quote_approvals (id, due) values (@Id, @Due)"
let private ends = "delete from quote_approvals where id = @Id"
let handle (connection: DbConnection) (transaction: DbTransaction)
(envelope: EventEnvelope) : Task =
task {
match envelope.Event with
| :? WorkflowRecord as record ->
// A workflow record does not hold its instance's ID. The
// persistence ID it is journaled under does.
let quote = WorkflowJournal.InstanceOf envelope.PersistenceId
let run (sql: string) (row: obj) =
connection.ExecuteAsync(sql, row, transaction) :> Task
match record with
// The wait for "approval" starts. Its detail is when it times
// out, and None for a wait without a timeout.
| WorkflowRecord.StepScheduled(_, "approval", _, _, detail) ->
do! run waits {| Id = quote.Id; Due = Option.toObj detail |}
// The wait ends: the signal arrived, the time ran out, or the
// quote was cancelled.
| WorkflowRecord.StepCompleted(_, "approval", _, _, _)
| WorkflowRecord.StepFailed(_, "approval", _, _, _)
// The quote ended in some other way.
| WorkflowRecord.Finished _
| WorkflowRecord.Faulted _
| WorkflowRecord.Cancelled _ ->
do! run ends {| Id = quote.Id |}
| _ -> ()
| _ -> ()
}
waits: stringends: stringhandle: DbConnection -> DbTransaction -> EventEnvelope -> Taskconnection: DbConnectionSystem.Data.Common.DbConnectionDefines the core behavior of database connections and provides a base class for database-specific connections.
transaction: DbTransactionSystem.Data.Common.DbTransactionDefines the core behavior of database transactions and provides a base class for database-specific transactions.
envelope: EventEnvelopeAkka.Persistence.Query.EventEnvelopeEvent wrapper adding meta data for the events in the result stream of query, or similar queries. The is the time the event was stored, in ticks. The value of this property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar (same as `DateTime.Now.Ticks`).
System.Threading.Tasks.TaskRepresents an asynchronous operation.
task: TaskBuilderBuilds a task using computation expression syntax.
Event: objFCQRS.Workflows.WorkflowRecordThe records a workflow instance stores. Their shape is a persistent contract. A row is journaled under the CLR name of its case, such as `FCQRS.Workflows.WorkflowRecord+StepScheduled, FCQRS.Workflows`, which a reader resolves without any registration. This type's name, namespace, and assembly are therefore part of the contract too.
record: WorkflowRecordquote: WorkflowInstanceFCQRS.Workflows.WorkflowJournalReads what a projection receives from a workflow's journal.
InstanceOf: string -> WorkflowInstanceThe instance whose journal holds an event, read from the event's persistence ID, such as `EventEnvelope.PersistenceId`. A `WorkflowRecord` does not hold its instance's ID, so a projection over workflow records reads it here. An instance journals under "<escaped workflow name>/<shard>/<escaped ID>"; this returns both parts unescaped. Raises `ArgumentException` for a persistence ID of another shape. An aggregate's persistence ID has the same shape, so match the event as a `WorkflowRecord` first.
PersistenceId: stringrun: string -> obj -> Tasksql: stringstringAn abbreviation for the CLI type . Basic Types
row: objobjAn abbreviation for the CLI type . Basic Types
ExecuteAsync: string * obj * Data.IDbTransaction * Nullable<int> * Nullable<Data.CommandType> -> Task<int>Execute a command asynchronously using Task. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
StepScheduledA step's start. `detail` is the due time of a timer or of a signal wait's timeout, in round-trip format, and the child's ID for a step that starts or waits for a child (stored since 7.7.3). Other steps store `None`.
detail: string optionId: stringDue: string | nullMicrosoft.FSharp.Core.OptionModuleContains operations for working with options. Options
toObj: 'T option -> 'T | nullConvert an option to a potentially null value. The input value. The result value, which is null if the input was None. (None: string option) |> Option.toObj // evaluates to null Some "not a null string" |> Option.toObj // evaluates to "not a null string"
StepCompletedStepFailedFinishedFaultedCancelledprivate const string Waits =
"insert or replace into quote_approvals (id, due) values (@Id, @Due)";
private const string Ends = "delete from quote_approvals where id = @Id";
public static async Task Handle(
DbConnection connection, DbTransaction transaction, EventEnvelope envelope)
{
if (envelope.Event is not WorkflowRecord record)
return;
// A workflow record does not hold its instance's ID. The
// persistence ID it is journaled under does.
var quote = WorkflowJournal.InstanceOf(envelope.PersistenceId);
switch (record)
{
// The wait for "approval" starts. Its detail is when it times
// out, and null for a wait without a timeout.
case WorkflowRecord.StepScheduled { name: "approval" } scheduled:
var row = new { quote.Id, Due = scheduled.detail?.Value };
await connection.ExecuteAsync(Waits, row, transaction);
break;
// The wait ends: the signal arrived, the time ran out, or the
// quote was cancelled.
case WorkflowRecord.StepCompleted { name: "approval" }:
case WorkflowRecord.StepFailed { name: "approval" }:
// The quote ended in some other way.
case WorkflowRecord.Finished:
case WorkflowRecord.Faulted:
case WorkflowRecord.Cancelled:
await connection.ExecuteAsync(Ends, new { quote.Id }, transaction);
break;
}
}
StepScheduledis the start of the wait. Its detail is the time the wait times out, in round-trip format. A wait without a timeout,waitSignal, storesNone.StepCompletedends the wait when the signal arrives and when the time runs out. A cancel storesStepFailedfor every pending step. The handler also deletes the row when the quote ends, so an ended quote is never listed.WorkflowJournal.InstanceOfgives the quote's ID. A record does not hold the ID of its instance. The persistence ID it is journaled under does, as<escaped workflow name>/<shard>/<escaped ID>.- The handler matches the step by its name. Step names are already persistent contracts.
Renaming the
approvalstep parks running quotes and also changes what this handler must match.
Register the handler as a transactional projection that reads only the quote workflow:
using (new SqliteConnection(connectionString)) (fun connection ->
connection.Execute Approvals.createTable |> ignore)
// The projection reads only the quote workflow's journal, and commits each
// row with its read position.
let store =
SqlProjectionStore(
ProjectionSqlDialect.Sqlite,
Func<DbConnection>(fun () -> new SqliteConnection(connectionString)))
let options = TransactionalProjectionOptions("quote-approvals", store)
options.Entities <- [ "quote" ]
let approvals = Fcqrs.transactionalProjection api options Approvals.handle
using: 'T -> ('T -> 'U) -> 'UClean up resources associated with the input object after the completion of the given function. Cleanup occurs even when an exception is raised by the protected code. The resource to be disposed after action is called. The action that accepts the resource. The resulting value. The following code appends 10 lines to test.txt, then closes the StreamWriter when finished. open System.IO using (File.AppendText "test.txt") (fun writer -> for i in 1 .. 10 do writer.WriteLine("Hello World {0}", i))
Microsoft.Data.Sqlite.SqliteConnectionRepresents a connection to a SQLite database. Connection Strings Async Limitations
connectionString: stringconnection: SqliteConnectionExecute: string * obj * Data.IDbTransaction * Nullable<int> * Nullable<Data.CommandType> -> intExecute parameterized SQL. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.ApprovalscreateTable: string(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
ignore: 'T -> unitIgnore the passed value. This is often used to throw away results of a computation. The value to ignore. ignore 55555 // Evaluates to ()
store: SqlProjectionStore``.ctor``: ProjectionSqlDialect * Func<DbConnection> -> SqlProjectionStoreUses one database for both the journal and the transactional read model.
FCQRS.ProjectionStorage.ProjectionSqlDialectDatabase SQL syntax supported by the transactional projection store.
Sqlite: ProjectionSqlDialectSQLite with a provider such as Microsoft.Data.Sqlite.
System.Func`1Encapsulates a method that has no parameters and returns a value of the type specified by the parameter. The type of the return value of the method that this delegate encapsulates. The return value of the method that this delegate encapsulates.
System.Data.Common.DbConnectionDefines the core behavior of database connections and provides a base class for database-specific connections.
options: TransactionalProjectionOptions``.ctor``: string * SqlProjectionStore -> TransactionalProjectionOptionsEntities: string seqThe entity names whose events this projection reads: an aggregate's, saga's, or workflow's name, as registered. A name selects the persistence IDs that start with it, escaped as Akka escapes a sharding region's name (Uri.EscapeDataString), and "/". The journal queries select those rows in SQL, so other entities' events are not fetched or deserialized, and the projection stores progress only for the named entities. On SQLite and SQL Server the full scan reads only the names' range of the journal's persistence-ID index, and the queries bounded by a journal number read every row above it; PostgreSQL reads other entities' rows in every query. A pass reads each persistence ID's events with a query of its own. Empty, the default, reads every entity. A pass applies the named entities' events in journal order, as without a filter.
approvals: IProjectionFCQRS.FSharp.FcqrstransactionalProjection: FCQRS.Common.IActor -> TransactionalProjectionOptions -> (DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.Task) -> IProjectionStarts a transactional projection with journal-wide CatchUpAsync support. Write the read model through the supplied connection and transaction; FCQRS commits those updates and contiguous per-persistence-ID progress together. Retain unprocessed journal history. Each pass applies events in journal order: per persistence ID in sequence order, and across persistence IDs in write order on SQLite; on PostgreSQL, SQL Server, and Oracle an event that commits late is applied in a later pass. Set `options.Entities` to read only some entities' events. On SQLite the handler runs while the transaction holds the database's single writer lock, so it must not wait for a journal write such as a workflow start; use `projection` with `Named` progress for that. See TransactionalProjectionOptions.
api: FCQRS.Common.IActorhandle: DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.Taskusing (var connection = new SqliteConnection(connectionString))
connection.Execute(Approvals.CreateTable);
// The projection reads only the quote workflow's journal, and commits each
// row with its read position.
var store = new SqlProjectionStore(
ProjectionSqlDialect.Sqlite, () => new SqliteConnection(connectionString));
var options = new TransactionalProjectionOptions("quote-approvals", store)
{
Entities = ["quote"]
};
// Keyed, so it runs beside the read model an application already projects.
var builder = Host.CreateApplicationBuilder();
builder.Logging.ClearProviders();
var fcqrs = builder.Services.AddFcqrs(connectionString, "approvals")
.AddKeyedTransactionalProjection(options, Approvals.Handle);
builder.Services.AddSingleton<IPriceService, FixedPriceService>();
builder.Services.AddSingleton<IMailer, QuietMailer>();
builder.Services.AddWorkflow<QuoteWorkflow, QuoteRequest, Quote>();
A C# host registers one projection with AddProjection or AddTransactionalProjection, and an
application often uses it for its own read model already. AddKeyedTransactionalProjection adds
this one beside it, and the program resolves it with
GetRequiredKeyedService<IProjection>("quote-approvals"). In F#, each
Fcqrs.transactionalProjection call starts another projection.
The entity name is the workflow's name, quote. Instances journal under it, so the projection
reads no other workflow's or aggregate's events. FCQRS commits each row with the projection's read
position for that instance, so a record is applied once even when the process stops in between.
The projection's name, quote-approvals, identifies that progress. A new name reads the whole
journal again. Catch up projections explains the transactional
projection.
The list is a query on the table:
// The quotes that wait for a person. The list lags the workflows by one
// projection pass.
let waiting () =
use connection = new SqliteConnection(connectionString)
connection.Query<string>("select id from quote_approvals order by id")
|> List.ofSeq
waiting: unit -> string listconnection: SqliteConnectionMicrosoft.Data.Sqlite.SqliteConnectionRepresents a connection to a SQLite database. Connection Strings Async Limitations
connectionString: stringQuery: string * obj * Data.IDbTransaction * bool * Nullable<int> * Nullable<Data.CommandType> -> 'T seqExecutes a query, returning the data typed as . The type of results to return. The connection to query on. The SQL to execute for the query. The parameters to pass, if any. The transaction to use, if any. Whether to buffer results in memory. The command timeout (in seconds). The type of command to execute. A sequence of data of the supplied type; if a basic type (int, string, etc) is queried then the data from the first column is assumed, otherwise an instance is created per row, and a direct column-name===member-name mapping is assumed (case insensitive).
stringAn abbreviation for the CLI type . Basic Types
(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
Microsoft.FSharp.Collections.ListModuleContains operations for working with values of type . Operations for collections such as lists, arrays, sets, maps and sequences. See also F# Collection Types in the F# Language Guide.
ofSeq: 'T seq -> 'T listBuilds a new list from the given enumerable object. The input sequence. The list of elements from the sequence. let inputs = seq { 1; 2; 5 } inputs |> List.ofSeq Evaluates to [ 1; 2; 5 ]. This is an O(n) operation, where n is the length of the sequence.
// The quotes that wait for a person. The list lags the workflows by one
// projection pass.
List<string> Waiting()
{
using var connection = new SqliteConnection(connectionString);
return connection
.Query<string>("select id from quote_approvals order by id")
.ToList();
}
The table lags the workflows by one projection pass. CatchUpAsync waits until the projection has
handled every record stored before the call, and the sample calls it before each query. A listed
quote can stop waiting before an approver acts on it, so approve through the check above.
List every instance and its status
The same records give each instance's status. This projection keeps one row per instance:
Shared setup
module Instances =
open System
open System.Data.Common
open System.Threading.Tasks
open Akka.Persistence.Query
open Dapper
open FCQRS.Workflows
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.InstancesSystemDataCommonThreadingTasksAkkaPersistenceQueryDapperFCQRSWorkflows// A row, as the list reads it.
[<CLIMutable>]
type Instance = {
Workflow: string
Id: string
Status: string
LastStep: string | null
}
Microsoft.FSharp.Core.CLIMutableAttributeAdding this attribute to a record type causes it to be compiled to a CLI representation with a default constructor with property getters and setters. Attributes
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.Instances.InstanceWorkflow: stringstringAn abbreviation for the CLI type . Basic Types
Id: stringStatus: stringLastStep: string | null// A row, as the list reads it.
public sealed record Instance(
string Workflow, string Id, string Status, string? LastStep);
// One row for each workflow instance: its status and the last step it
// started. The table is in the journal's database.
let createTable =
"create table if not exists workflow_instances (
workflow text not null,
id text not null,
status text not null,
last_step text,
updated text not null,
primary key (workflow, id))"
createTable: string// One row for each workflow instance: its status and the last step it
// started. The table is in the journal's database.
public const string CreateTable =
"""
create table if not exists workflow_instances (
workflow text not null,
id text not null,
status text not null,
last_step text,
updated text not null,
primary key (workflow, id))
""";
let private started =
"insert or replace into workflow_instances
(workflow, id, status, last_step, updated)
values (@Workflow, @Id, 'running', null, @At)"
let private stepped =
"update workflow_instances set last_step = @Step, updated = @At
where workflow = @Workflow and id = @Id"
let private ended =
"update workflow_instances set status = @Status, updated = @At
where workflow = @Workflow and id = @Id"
let handle (connection: DbConnection) (transaction: DbTransaction)
(envelope: EventEnvelope) : Task =
task {
match envelope.Event with
| :? WorkflowRecord as record ->
let instance = WorkflowJournal.InstanceOf envelope.PersistenceId
let run (sql: string) (at: DateTime) (fields: (string * obj) list) =
let row = DynamicParameters()
row.Add("Workflow", instance.Workflow)
row.Add("Id", instance.Id)
row.Add("At", at.ToString "O")
for name, value in fields do
row.Add(name, value)
connection.ExecuteAsync(sql, row, transaction) :> Task
match record with
| WorkflowRecord.Started(_, at, _, _) -> do! run started at []
| WorkflowRecord.StepScheduled(_, step, _, at, _) ->
do! run stepped at [ "Step", box step ]
| WorkflowRecord.Resumed(_, at) ->
do! run ended at [ "Status", box "running" ]
| WorkflowRecord.CancelRequested at ->
do! run ended at [ "Status", box "cancelling" ]
| WorkflowRecord.Finished(_, at) ->
do! run ended at [ "Status", box "finished" ]
| WorkflowRecord.Faulted(_, at) ->
do! run ended at [ "Status", box "faulted" ]
| WorkflowRecord.Cancelled at ->
do! run ended at [ "Status", box "cancelled" ]
| _ -> ()
| _ -> ()
}
started: stringstepped: stringended: stringhandle: DbConnection -> DbTransaction -> EventEnvelope -> Taskconnection: DbConnectionSystem.Data.Common.DbConnectionDefines the core behavior of database connections and provides a base class for database-specific connections.
transaction: DbTransactionSystem.Data.Common.DbTransactionDefines the core behavior of database transactions and provides a base class for database-specific transactions.
envelope: EventEnvelopeAkka.Persistence.Query.EventEnvelopeEvent wrapper adding meta data for the events in the result stream of query, or similar queries. The is the time the event was stored, in ticks. The value of this property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar (same as `DateTime.Now.Ticks`).
System.Threading.Tasks.TaskRepresents an asynchronous operation.
task: TaskBuilderBuilds a task using computation expression syntax.
Event: objFCQRS.Workflows.WorkflowRecordThe records a workflow instance stores. Their shape is a persistent contract. A row is journaled under the CLR name of its case, such as `FCQRS.Workflows.WorkflowRecord+StepScheduled, FCQRS.Workflows`, which a reader resolves without any registration. This type's name, namespace, and assembly are therefore part of the contract too.
record: WorkflowRecordinstance: WorkflowInstanceFCQRS.Workflows.WorkflowJournalReads what a projection receives from a workflow's journal.
InstanceOf: string -> WorkflowInstanceThe instance whose journal holds an event, read from the event's persistence ID, such as `EventEnvelope.PersistenceId`. A `WorkflowRecord` does not hold its instance's ID, so a projection over workflow records reads it here. An instance journals under "<escaped workflow name>/<shard>/<escaped ID>"; this returns both parts unescaped. Raises `ArgumentException` for a persistence ID of another shape. An aggregate's persistence ID has the same shape, so match the event as a `WorkflowRecord` first.
PersistenceId: stringrun: string -> DateTime -> (string * obj) list -> Tasksql: stringstringAn abbreviation for the CLI type . Basic Types
at: DateTimeSystem.DateTimeRepresents an instant in time, typically expressed as a date and time of day.
fields: (string * obj) listobjAn abbreviation for the CLI type . Basic Types
listThe type of immutable singly-linked lists. See the module for further operations related to lists. Use the constructors [] and :: (infix) to create values of this type, or the notation [1; 2; 3]. Use the values in the List module to manipulate values of this type, or pattern match against the values directly. See also F# Language Guide - Lists.
row: DynamicParameters``.ctor``: unit -> unitconstruct a dynamic parameter bag
Add: string * obj * Nullable<Data.DbType> * Nullable<Data.ParameterDirection> * Nullable<int> * Nullable<byte> * Nullable<byte> -> unitAdd a parameter to this dynamic parameter list. The name of the parameter. The value of the parameter. The type of the parameter. The in or out direction of the parameter. The size of the parameter. The precision of the parameter. The scale of the parameter.
Workflow: stringId: stringToString: string -> stringConverts the value of the current object to its equivalent string representation using the specified format and the formatting conventions of the current culture. A standard or custom date and time format string. The length of is 1, and it is not one of the format specifier characters defined for . -or- does not contain a valid custom format pattern. The date and time is outside the range of dates supported by the calendar used by the current culture. A string representation of value of the current object as specified by .
name: stringvalue: objExecuteAsync: string * obj * Data.IDbTransaction * Nullable<int> * Nullable<Data.CommandType> -> Task<int>Execute a command asynchronously using Task. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
StartedStepScheduledA step's start. `detail` is the due time of a timer or of a signal wait's timeout, in round-trip format, and the child's ID for a step that starts or waits for a child (stored since 7.7.3). Other steps store `None`.
step: stringbox: 'T -> objnullBoxes a strongly typed value. The value to box. The boxed object. let x: int = 123 let obj1 = box x // obj1 is a generic object type unbox<int> obj1 // Evaluates to 123 (int) unbox<double> obj1 // Throws System.InvalidCastException
ResumedA faulted instance was resumed: the failure of the step at `path` is set aside, and the body runs that step again, with its earlier key. Stored since 7.12.0, which earlier versions cannot read.
CancelRequestedFinishedFaultedCancelledprivate const string Started =
"""
insert or replace into workflow_instances
(workflow, id, status, last_step, updated)
values (@Workflow, @Id, 'running', null, @At)
""";
private const string Stepped =
"""
update workflow_instances set last_step = @Step, updated = @At
where workflow = @Workflow and id = @Id
""";
private const string Ended =
"""
update workflow_instances set status = @Status, updated = @At
where workflow = @Workflow and id = @Id
""";
public static async Task Handle(
DbConnection connection, DbTransaction transaction, EventEnvelope envelope)
{
if (envelope.Event is not WorkflowRecord record)
return;
var instance = WorkflowJournal.InstanceOf(envelope.PersistenceId);
Task Run(
string sql, DateTime at, string? step = null, string? status = null)
{
var row = new
{
instance.Workflow, instance.Id, At = at.ToString("O"),
Step = step, Status = status
};
return connection.ExecuteAsync(sql, row, transaction);
}
switch (record)
{
case WorkflowRecord.Started started:
await Run(Started, started.at);
break;
case WorkflowRecord.StepScheduled scheduled:
await Run(Stepped, scheduled.at, step: scheduled.name);
break;
case WorkflowRecord.Resumed resumed:
await Run(Ended, resumed.at, status: "running");
break;
case WorkflowRecord.CancelRequested requested:
await Run(Ended, requested.at, status: "cancelling");
break;
case WorkflowRecord.Finished finished:
await Run(Ended, finished.at, status: "finished");
break;
case WorkflowRecord.Faulted faulted:
await Run(Ended, faulted.at, status: "faulted");
break;
case WorkflowRecord.Cancelled cancelled:
await Run(Ended, cancelled.at, status: "cancelled");
break;
}
}
Started adds the row, StepScheduled records the step the instance started last, and
Resumed, CancelRequested, Finished, Faulted, and Cancelled set the status. WorkflowJournal.InstanceOf
gives the workflow name too, so one projection can list several workflows: name each one in
Entities.
Register it as a second projection, with its own name:
using (new SqliteConnection(connectionString)) (fun connection ->
connection.Execute Instances.createTable |> ignore)
// A second projection, with its own name and progress.
let instanceOptions =
TransactionalProjectionOptions("workflow-instances", store)
instanceOptions.Entities <- [ "quote" ]
let instances =
Fcqrs.transactionalProjection api instanceOptions Instances.handle
let listInstances () =
use connection = new SqliteConnection(connectionString)
connection.Query<Instances.Instance>(
"select workflow, id, status, last_step as LastStep
from workflow_instances order by workflow, id")
|> List.ofSeq
using: 'T -> ('T -> 'U) -> 'UClean up resources associated with the input object after the completion of the given function. Cleanup occurs even when an exception is raised by the protected code. The resource to be disposed after action is called. The action that accepts the resource. The resulting value. The following code appends 10 lines to test.txt, then closes the StreamWriter when finished. open System.IO using (File.AppendText "test.txt") (fun writer -> for i in 1 .. 10 do writer.WriteLine("Hello World {0}", i))
Microsoft.Data.Sqlite.SqliteConnectionRepresents a connection to a SQLite database. Connection Strings Async Limitations
connectionString: stringconnection: SqliteConnectionExecute: string * obj * Data.IDbTransaction * Nullable<int> * Nullable<Data.CommandType> -> intExecute parameterized SQL. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.InstancescreateTable: string(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
ignore: 'T -> unitIgnore the passed value. This is often used to throw away results of a computation. The value to ignore. ignore 55555 // Evaluates to ()
instanceOptions: TransactionalProjectionOptions``.ctor``: string * SqlProjectionStore -> TransactionalProjectionOptionsstore: SqlProjectionStoreEntities: string seqThe entity names whose events this projection reads: an aggregate's, saga's, or workflow's name, as registered. A name selects the persistence IDs that start with it, escaped as Akka escapes a sharding region's name (Uri.EscapeDataString), and "/". The journal queries select those rows in SQL, so other entities' events are not fetched or deserialized, and the projection stores progress only for the named entities. On SQLite and SQL Server the full scan reads only the names' range of the journal's persistence-ID index, and the queries bounded by a journal number read every row above it; PostgreSQL reads other entities' rows in every query. A pass reads each persistence ID's events with a query of its own. Empty, the default, reads every entity. A pass applies the named entities' events in journal order, as without a filter.
instances: IProjectionFCQRS.FSharp.FcqrstransactionalProjection: FCQRS.Common.IActor -> TransactionalProjectionOptions -> (DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.Task) -> IProjectionStarts a transactional projection with journal-wide CatchUpAsync support. Write the read model through the supplied connection and transaction; FCQRS commits those updates and contiguous per-persistence-ID progress together. Retain unprocessed journal history. Each pass applies events in journal order: per persistence ID in sequence order, and across persistence IDs in write order on SQLite; on PostgreSQL, SQL Server, and Oracle an event that commits late is applied in a later pass. Set `options.Entities` to read only some entities' events. On SQLite the handler runs while the transaction holds the database's single writer lock, so it must not wait for a journal write such as a workflow start; use `projection` with `Named` progress for that. See TransactionalProjectionOptions.
api: FCQRS.Common.IActorhandle: DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.TasklistInstances: unit -> Instances.Instance listQuery: string * obj * Data.IDbTransaction * bool * Nullable<int> * Nullable<Data.CommandType> -> 'T seqExecutes a query, returning the data typed as . The type of results to return. The connection to query on. The SQL to execute for the query. The parameters to pass, if any. The transaction to use, if any. Whether to buffer results in memory. The command timeout (in seconds). The type of command to execute. A sequence of data of the supplied type; if a basic type (int, string, etc) is queried then the data from the first column is assumed, otherwise an instance is created per row, and a direct column-name===member-name mapping is assumed (case insensitive).
Fcqrs_550-how-to_011-find-waiting-workflows.md_page.Instances.InstanceMicrosoft.FSharp.Collections.ListModuleContains operations for working with values of type . Operations for collections such as lists, arrays, sets, maps and sequences. See also F# Collection Types in the F# Language Guide.
ofSeq: 'T seq -> 'T listBuilds a new list from the given enumerable object. The input sequence. The list of elements from the sequence. let inputs = seq { 1; 2; 5 } inputs |> List.ofSeq Evaluates to [ 1; 2; 5 ]. This is an O(n) operation, where n is the length of the sequence.
using (var connection = new SqliteConnection(connectionString))
connection.Execute(Instances.CreateTable);
// A second projection, with its own name and progress.
var instanceOptions =
new TransactionalProjectionOptions("workflow-instances", store)
{
Entities = ["quote"]
};
fcqrs.AddKeyedTransactionalProjection(instanceOptions, Instances.Handle);
List<Instance> ListInstances()
{
using var connection = new SqliteConnection(connectionString);
return connection
.Query<Instance>(
"""
select workflow, id, status, last_step as LastStep
from workflow_instances order by workflow, id
""")
.ToList();
}
- A parked instance is listed as
running. An instance is parked when its journal does not match its code. That is decided when the instance replays and is not stored, so no record tells the projection.StatusreportsParkedwith the reason, thefcqrs.workflow.parkedgauge counts the parked instances in memory, and each one logs an error in theFCQRS.Workflowscategory. See Observe your system. - A
runningrow survives a stop. An instance that was running when the process stopped resumes when its workflow is registered at the next start, and its row goes on from there. Nothing restarts afaultedorcancelledinstance by itself.Resumecontinues a faulted one at its failed step, and itsResumedrecord sets the row back torunning. A start withWorkflowIdReuse.AfterFailurebegins a new run under the ID, and the run'sStartedrecord does the same.
Run the sample
dotnet run --project samples/approvals/fsharp -c Release
The program starts three quotes, waits until two of them have reached the approval, approves two, and lists the instances:
waiting for approval: [q-2; q-3]
approve q-1: false
approve q-2: true
q-2: quote of 1250.0 sent to Ada
waiting for approval: [q-3]
quote q-1: finished (last step send-quote)
quote q-2: finished (last step send-quote)
quote q-3: running (last step approval)
q-1costs 125, so it ended without a wait, and the check refused to approve it.q-2left the list when its wait completed.q-3waits until it is approved or its day runs out. Each run of the sample deletes its database first, so the output is the same every time.
Use samples/approvals/csharp for the C# program.
Record the request in a step
When the request for approval is a business fact, such as a task in another system or an email to the approver, send it from an activity just before the wait. The activity runs at least once, so the system it calls must honour its idempotency key. The body does not know its own workflow ID, so put the ID that the approver signals, such as a quote number, in the workflow's input.
Adding that step to a workflow whose instances are running changes the steps those instances stored. Follow Change a workflow while instances are running.
Next: Apply only the newest change uses signals to apply only the newest of the changes that arrive while one is applied.