Safe Haskell	None
Language	Haskell2010

Temporal.Client.Schedule

Description

A Schedule contains instructions for starting a Workflow Execution at specific times. Schedules provide a more flexible and user-friendly approach than Temporal Cron Jobs.

How to enable Schedules

A Schedule has an identity and is independent of a Workflow Execution. This differs from a Temporal Cron Job, which relies on a cron schedule as a property of the Workflow Execution.

Action

The Action of a Schedule is where the Workflow Execution properties are established, such as Workflow Type, Task Queue, parameters, and timeouts.

Workflow Executions started by a Schedule have the following additional properties:

The Action's timestamp is appended to the Workflow Id.
The TemporalScheduledStartTime Search Attribute is added to the Workflow Execution. The value is the Action's timestamp.
The TemporalScheduledById Search Attribute is added to the Workflow Execution. The value is the Schedule Id.
The Schedule Spec describes when the Action is taken. There are two kinds of Schedule Spec:
A simple interval, like "every 30 minutes" (aligned to start at the Unix epoch, and optionally including a phase offset).
A calendar-based expression, similar to the "cron expressions" supported by lots of software, including the older Temporal Cron feature.

The following calendar JSON fields are available:

year
month
dayOfMonth
dayOfWeek
hour
minute
second
comment

Each field can contain a comma-separated list of ranges (or the * wildcard), and each range can include a slash followed by a skip value. The hour, minute, and second fields default to 0 while the others default to *, so you can describe many useful specs with only a few fields.

For month, names of months may be used instead of integers (case-insensitive, abbreviations permitted). For dayOfWeek, day-of-week names may be used.

The comment field is optional and can be used to include a free-form description of the intent of the calendar spec, useful for complicated specs.

No matter which form you supply, calendar and interval specs are converted to canonical representations. What you see when you "describe" or "list" a Schedule might not look exactly like what you entered, but it has the same meaning.

Other Spec features

Multiple intervals/calendar expressions

A Spec can have combinations of multiple intervals and/or calendar expressions to define a specific Schedule.

Time bounds

Provide an absolute start or end time (or both) with a Spec to ensure that no actions are taken before the start time or after the end time.

Exclusions

A Spec can contain exclusions in the form of zero or more calendar expressions. This can be used to express scheduling like "each Monday at noon except for holidays. You'll have to provide your own set of exclusions and include it in each schedule; there are no pre-defined sets. (This feature isn't currently exposed in tctl or the Temporal Web UI.)

Jitter

If given, a random offset between zero and the maximum jitter is added to each Action time (but bounded by the time until the next scheduled Action).

Time zones

By default, calendar-based expressions are interpreted in UTC. Temporal recommends using UTC to avoid various surprising properties of time zones. If you don't want to use UTC, you can provide the name of a time zone. The time zone definition is loaded on the Temporal Server Worker Service from either disk or the fallback embedded in the binary.

For more operational control, embed the contents of the time zone database file in the Schedule Spec itself. (Note: this isn't currently exposed in tctl or the web UI.)

Pause

A Schedule can be Paused. When a Schedule is Paused, the Spec has no effect. However, you can still force manual actions by using the tctl schedule trigger command.

To assist communication among developers and operators, a “notes” field can be updated on pause or resume to store an explanation for the current state.

Backfill

A Schedule can be Backfilled. When a Schedule is Backfilled, all the Actions that would have been taken over a specified time period are taken now (in parallel if the AllowAll Overlap Policy is used; sequentially if BufferAll is used). You might use this to fill in runs from a time period when the Schedule was paused due to an external condition that's now resolved, or a period before the Schedule was created.

Limit number of Actions

A Schedule can be limited to a certain number of scheduled Actions (that is, not trigger immediately). After that it will act as if it were paused.

Policies

A Schedule supports a set of Policies that enable customizing behavior.

Overlap Policy

The Overlap Policy controls what happens when it is time to start a Workflow Execution but a previously started Workflow Execution is still running. The following options are available:

Skip: Default. Nothing happens; the Workflow Execution is not started. BufferOne: Starts the Workflow Execution as soon as the current one completes. The buffer is limited to one. If another Workflow Execution is supposed to start, but one is already in the buffer, only the one in the buffer eventually starts. BufferAll: Allows an unlimited number of Workflows to buffer. They are started sequentially. CancelOther: Cancels the running Workflow Execution, and then starts the new one after the old one completes cancellation. TerminateOther: Terminates the running Workflow Execution and starts the new one immediately. AllowAll Starts any number of concurrent Workflow Executions. With this policy (and only this policy), more than one Workflow Execution, started by the Schedule, can run simultaneously. Catchup Window The Temporal Cluster might be down or unavailable at the time when a Schedule should take an Action. When it comes back up, the Catchup Window controls which missed Actions should be taken at that point. The default is one minute, which means that the Schedule attempts to take any Actions that wouldn't be more than one minute late. An outage that lasts longer than the Catchup Window could lead to missed Actions. (But you can always Backfill.)

Pause-on-failure

If this policy is set, a Workflow Execution started by a Schedule that ends with a failure or timeout (but not Cancellation or Termination) causes the Schedule to automatically pause.

Note that with the AllowAll Overlap Policy, this pause might not apply to the next Workflow Execution, because the next Workflow Execution might have started before the failed one finished. It applies only to Workflow Executions that were scheduled to start after the failed one finished.

Last completion result

A Workflow started by a Schedule can obtain the completion result from the most recent successful run. (How you do this depends on the SDK you're using.)

For overlap policies that don't allow overlap, “the most recent successful run” is straightforward to define. For the AllowAll policy, it refers to the run that completed most recently, at the time that the run in question is started. Consider the following overlapping runs:

time -------------------------------------------->
 A     |----------------------|
 B               |-------|
 C                          |---------------|
 D                                |--------------T

If D asks for the last completion result at time T, it gets the result of A. Not B, even though B started more recently, because A completed later. And not C, even though C completed after A, because the result for D is captured when D is started, not when it's queried.

Failures and timeouts do not affect the last completion result.

Last failure A Workflow started by a Schedule can obtain the details of the failure of the most recent run that ended at the time when the Workflow in question was started. Unlike last completion result, a successful run does reset the last failure.

Limitations Internally, a Schedule is implemented as a Workflow. If you're using Advanced Visibility (Elasticsearch), these Workflow Executions are hidden from normal views. If you're using Standard Visibility, they are visible, though there's no need to interact with them directly.

Synopsis

mkScheduleClient :: Client -> Namespace -> ScheduleClient
data ScheduleClient
data CreateScheduleRequest = CreateScheduleRequest {
- scheduleId :: !ScheduleId
- schedule :: !Schedule
- initialPatch :: !(Maybe SchedulePatch)
- memo :: !(Map Text Payload)
- requestId :: !Text
- searchAttributes :: !(Map SearchAttributeKey SearchAttributeType)
}
createSchedule :: MonadIO m => ScheduleClient -> CreateScheduleRequest -> m ByteString
deleteSchedule :: MonadIO m => ScheduleClient -> ScheduleId -> m ()
listSchedules :: forall (m :: Type -> Type). MonadIO m => ScheduleClient -> ListSchedulesOptions -> ConduitT () (Vector ScheduleListEntry) m ()
data ScheduleListInfo = ScheduleListInfo {
- spec :: !(Maybe ScheduleSpec)
- workflowType :: !WorkflowType
- notes :: !Text
- paused :: !Bool
- recentActions :: ![ScheduleActionResult]
- futureActionTimes :: ![SystemTime]
}
data ScheduleListEntry = ScheduleListEntry {
- scheduleId :: !ScheduleId
- memo :: !(Map Text Payload)
- searchAttributes :: !(Map SearchAttributeKey SearchAttributeType)
- info :: !(Maybe ScheduleListInfo)
}
data ScheduleActionResult = ScheduleActionResult {
- scheduleTime :: !SystemTime
- actualTime :: !SystemTime
- startWorkflowResult :: !WorkflowExecution
}
data ListSchedulesOptions = ListSchedulesOptions {
- maximumPageSize :: Int32
}
data ListScheduleMatchingTimesOptions = ListScheduleMatchingTimesOptions {
- scheduleId :: !ScheduleId
- startTime :: !SystemTime
- endTime :: !SystemTime
}
listScheduleMatchingTimes :: MonadIO m => ScheduleClient -> ListScheduleMatchingTimesOptions -> m (Vector SystemTime)
describeSchedule :: MonadIO m => ScheduleClient -> ScheduleId -> m DescribeScheduleResponse
data DescribeScheduleResponse = DescribeScheduleResponse {
- schedule :: !Schedule
- info :: !ScheduleInfo
- memo :: !(Map Text Payload)
- searchAttributes :: !(Map SearchAttributeKey SearchAttributeType)
- conflictToken :: !ByteString
}
patchSchedule :: MonadIO m => ScheduleClient -> ScheduleId -> SchedulePatch -> m ()
data SchedulePatch = SchedulePatch {
- triggerImmediately :: !(Maybe TriggerImmediatelyRequest)
- backfillRequest :: ![BackfillRequest]
- pauseState :: !(Maybe PauseState)
- requestId :: !Text
}
updateSchedule :: MonadIO m => ScheduleClient -> ScheduleId -> UpdateScheduleRequest -> m ()
data UpdateScheduleRequest = UpdateScheduleRequest {
- schedule :: !Schedule
- conflictToken :: !(Maybe ByteString)
- requestId :: !Text
}
newtype ScheduleId = ScheduleId {
- rawScheduleId :: Text
}
scheduleSpec :: ScheduleSpec
data ScheduleSpec = ScheduleSpec {
- structuredCalendar :: [StructuredCalendarSpec]
- cronString :: [Text]
- calendar :: [CalendarSpec]
- interval :: [IntervalSpec]
- excludeCalendar :: [CalendarSpec]
- excludeStructuredCalendar :: [StructuredCalendarSpec]
- startTime :: Maybe SystemTime
- endTime :: Maybe SystemTime
- jitter :: Maybe Duration
- timezoneName :: Text
- timezoneData :: Maybe ByteString
}
data Schedule = Schedule {
- spec :: !ScheduleSpec
- action :: !ScheduleAction
- policies :: !SchedulePolicies
- state :: !ScheduleState
}
data TriggerImmediatelyRequest = TriggerImmediatelyRequest {
- overlapPolicy :: !OverlapPolicy
}
data BackfillRequest = BackfillRequest {
- startTime :: !SystemTime
- endTime :: !SystemTime
- overlapPolicy :: !OverlapPolicy
}
data StructuredCalendarSpec = StructuredCalendarSpec {
- second :: [Range]
- minute :: [Range]
- hour :: [Range]
- dayOfMonth :: [Range]
- month :: [Range]
- year :: [Range]
- dayOfWeek :: [Range]
- comment :: Text
}
structuredCalendarSpec :: StructuredCalendarSpec
calendarSpec :: CalendarSpec
data CalendarSpec = CalendarSpec {
- second :: !Text
- minute :: !Text
- hour :: !Text
- dayOfMonth :: !Text
- month :: !Text
- year :: !Text
- dayOfWeek :: !Text
- comment :: !Text
}
data IntervalSpec = IntervalSpec {
- interval :: !Duration
- phase :: !(Maybe Duration)
}
data WorkflowExecution = WorkflowExecution {
- workflowId :: !WorkflowId
- runId :: !RunId
}
data ScheduleInfo = ScheduleInfo {
- actionCount :: !Int64
- missedCatchupWindow :: !Int64
- overlapSkipped :: !Int64
- runningWorkflows :: [WorkflowExecution]
- recentActions :: [ScheduleActionResult]
- futureActionTimes :: [SystemTime]
- createTime :: !(Maybe SystemTime)
- updateTime :: !(Maybe SystemTime)
- invalidScheduleError :: !Text
}
mkScheduleAction :: forall wf (m :: Type -> Type). (MonadIO m, WorkflowRef wf) => wf -> WorkflowId -> StartWorkflowOptions -> WorkflowArgs wf :->: m ScheduleAction
data ScheduleAction
- = StartWorkflow NewWorkflowExecutionInfo
- | ScheduleActionUnrecognized
data SchedulePolicies = SchedulePolicies {
- overlapPolicy :: !OverlapPolicy
- catchupWindow :: !(Maybe Duration)
- pauseOnFailure :: !Bool
}
data ScheduleState = ScheduleState {
- notes :: !Text
- paused :: !Bool
- limitedActions :: !Bool
- remainingActions :: !Int64
}
data OverlapPolicy
- = Unspecified
- | Skip
- | BufferOne
- | BufferAll
- | CancelOther
- | TerminateOther
- | AllowAll
- | OverlapPolicyUnrecognized
data Range = Range {
- start :: !Int32
- end :: !Int32
- step :: !Int32
}
module Temporal.Duration

Documentation

mkScheduleClient :: Client -> Namespace -> ScheduleClient Source #

data ScheduleClient Source #

Instances

Instances details

HasField "identity" ScheduleClient Text Source #
Instance details Defined in Temporal.Client.Schedule Methods getField :: ScheduleClient -> Text #

data CreateScheduleRequest Source #

Constructors

CreateScheduleRequest

Fields

scheduleId :: !ScheduleId
The id of the new schedule.
schedule :: !Schedule
The schedule spec, policies, action, and initial state.
initialPatch :: !(Maybe SchedulePatch)
Optional initial patch (e.g. to run the action once immediately).
memo :: !(Map Text Payload)
Memo attached to the schedule itself.
requestId :: !Text
A unique identifier for this create request for idempotence. Typically UUIDv4.
searchAttributes :: !(Map SearchAttributeKey SearchAttributeType)
Search attributes attached to the schedule itself.

Instances

Instances details

Generic CreateScheduleRequest Source #

Instance details

ScheduleListInfo
Fields spec :: !(Maybe ScheduleSpec) workflowType :: !WorkflowType notes :: !Text paused :: !Bool recentActions :: ![ScheduleActionResult] futureActionTimes :: ![SystemTime]

ScheduleListEntry
Fields scheduleId :: !ScheduleId memo :: !(Map Text Payload) searchAttributes :: !(Map SearchAttributeKey SearchAttributeType) info :: !(Maybe ScheduleListInfo)

ScheduleActionResult
Fields scheduleTime :: !SystemTime actualTime :: !SystemTime startWorkflowResult :: !WorkflowExecution

ListScheduleMatchingTimesOptions
Fields scheduleId :: !ScheduleId startTime :: !SystemTime endTime :: !SystemTime

FromJSON ScheduleId Source #
Instance details Defined in Temporal.Common Methods parseJSON :: Value -> Parser ScheduleId # parseJSONList :: Value -> Parser [ScheduleId] # omittedField :: Maybe ScheduleId #
ToJSON ScheduleId Source #
Instance details Defined in Temporal.Common Methods toJSON :: ScheduleId -> Value # toEncoding :: ScheduleId -> Encoding # toJSONList :: [ScheduleId] -> Value # toEncodingList :: [ScheduleId] -> Encoding # omitField :: ScheduleId -> Bool #
IsString ScheduleId Source #
Instance details Defined in Temporal.Common Methods fromString :: String -> ScheduleId #
Show ScheduleId Source #
Instance details Defined in Temporal.Common Methods showsPrec :: Int -> ScheduleId -> ShowS # show :: ScheduleId -> String # showList :: [ScheduleId] -> ShowS #
Eq ScheduleId Source #
Instance details Defined in Temporal.Common Methods (==) :: ScheduleId -> ScheduleId -> Bool # (/=) :: ScheduleId -> ScheduleId -> Bool #
Ord ScheduleId Source #
Instance details Defined in Temporal.Common Methods compare :: ScheduleId -> ScheduleId -> Ordering # (<) :: ScheduleId -> ScheduleId -> Bool # (<=) :: ScheduleId -> ScheduleId -> Bool # (>) :: ScheduleId -> ScheduleId -> Bool # (>=) :: ScheduleId -> ScheduleId -> Bool # max :: ScheduleId -> ScheduleId -> ScheduleId # min :: ScheduleId -> ScheduleId -> ScheduleId #
Hashable ScheduleId Source #
Instance details Defined in Temporal.Common Methods hashWithSalt :: Int -> ScheduleId -> Int # hash :: ScheduleId -> Int #
Lift ScheduleId Source #
Instance details Defined in Temporal.Common Methods lift :: Quote m => ScheduleId -> m Exp # liftTyped :: forall (m :: Type -> Type). Quote m => ScheduleId -> Code m ScheduleId #

Schedule
Fields spec :: !ScheduleSpec action :: !ScheduleAction policies :: !SchedulePolicies state :: !ScheduleState

TriggerImmediatelyRequest
Fields overlapPolicy :: !OverlapPolicy

BackfillRequest
Fields startTime :: !SystemTime Start of time range to evaluate schedule in. endTime :: !SystemTime End of time range to evaluate schedule in. overlapPolicy :: !OverlapPolicy Override overlap policy for this request.

StructuredCalendarSpec
Fields second :: [Range] Match seconds (0-59) minute :: [Range] Match minutes (0-59) hour :: [Range] Match hours (0-23) dayOfMonth :: [Range] Match days of the month (1-31) month :: [Range] Match months (1-12) year :: [Range] Match years. dayOfWeek :: [Range] Match days of the week (0-6; 0 is Sunday). comment :: Text Free-form comment describing the intention of this spec.

IntervalSpec
Fields interval :: !Duration phase :: !(Maybe Duration)

WorkflowExecution
Fields workflowId :: !WorkflowId runId :: !RunId

:: forall wf (m :: Type -> Type). (MonadIO m, WorkflowRef wf)
=> wf
-> WorkflowId	Unlike other uses of WorkflowId, this will be used as a prefix for the actual workflow id, which will be unique.
-> StartWorkflowOptions	All fields of `StartWorkflowOptions` are valid except for the workflow id reuse policy and cron string. The workflow id will generally have a timestamp appended for uniqueness.
-> WorkflowArgs wf :->: m ScheduleAction

StartWorkflow NewWorkflowExecutionInfo
ScheduleActionUnrecognized

Show ScheduleAction Source #
Instance details Defined in Temporal.Client.Schedule Methods showsPrec :: Int -> ScheduleAction -> ShowS # show :: ScheduleAction -> String # showList :: [ScheduleAction] -> ShowS #
Eq ScheduleAction Source #
Instance details Defined in Temporal.Client.Schedule Methods (==) :: ScheduleAction -> ScheduleAction -> Bool # (/=) :: ScheduleAction -> ScheduleAction -> Bool #
Ord ScheduleAction Source #
Instance details Defined in Temporal.Client.Schedule Methods compare :: ScheduleAction -> ScheduleAction -> Ordering # (<) :: ScheduleAction -> ScheduleAction -> Bool # (<=) :: ScheduleAction -> ScheduleAction -> Bool # (>) :: ScheduleAction -> ScheduleAction -> Bool # (>=) :: ScheduleAction -> ScheduleAction -> Bool # max :: ScheduleAction -> ScheduleAction -> ScheduleAction # min :: ScheduleAction -> ScheduleAction -> ScheduleAction #

Unspecified
Skip	Skip (default) means don't start anything. When the workflow completes, the next scheduled event after that time will be considered.
BufferOne	BufferOne means start the workflow again soon as the current one completes, but only buffer one start in this way. If another start is supposed to happen when the workflow is running, and one is already buffered, then only the first one will be started after the running workflow finishes.
BufferAll	BufferAll means buffer up any number of starts to all happen sequentially, immediately after the running workflow completes.
CancelOther	CancelOther means that if there is another workflow running, cancel it, and start the new one after the old one completes cancellation.
TerminateOther	TerminateOther means that if there is another workflow running, terminate it and start the new one immediately.
AllowAll	AllowAll means start any number of concurrent workflows. Note that with this policy, last completion result and last failure will not be available since workflows are not sequential.
OverlapPolicyUnrecognized

Range
Fields start :: !Int32 Start of range (inclusive). end :: !Int32 End of range (inclusive). step :: !Int32 Step (optional, default 1).