LittleHorse API Reference
The LittleHorse Server exposes a GRPC API to its clients. For most general usage of LittleHorse, you will not need to
read the raw protobuf schema. Common LittleHorse client actions fall into three general categories:
- Developing a Task Worker, which is handled by our Task Worker SDK's.
- Developing a WfSpec, which is handled by our
WfSpec
SDK's.
- Running and interacting with
WfRun
's, which is documented in our "Using the API" docs.
However, the highly curious reader might want to see the actual GRPC and Protobuf specification. The docs on this page
are autogenerated from our actual protobuf files.
The documentation of what the specific protobuf fields mean is potentially useful for advanced Jedi Master use-cases.
Happy Reading!
LittleHorse GRPC API
The LittleHorse GRPC API is the backbone of the clients that you get in all of our SDK's. Every LHConfig
object
gives you a GRPC stub to access the API. Most common operations are already documented with code examples in different
languages here, but we put this here for the true Jedi Masters.
RPC PutTaskDef
RPC GetTaskDef
RPC GetTaskWorkerGroup
Request Type | Response Type | Description |
---|
TaskDefId | TaskWorkerGroup | Gets the registered task worker group associated with a specific TaskDef. |
RPC PutExternalEventDef
RPC GetExternalEventDef
RPC PutWorkflowEventDef
RPC PutWfSpec
RPC GetWfSpec
RPC GetLatestWfSpec
Request Type | Response Type | Description |
---|
GetLatestWfSpecRequest | WfSpec | Returns the latest WfSpec with a specified name (and optionally a specified Major Version). |
RPC MigrateWfSpec
Request Type | Response Type | Description |
---|
MigrateWfSpecRequest | WfSpec | EXPERIMENTAL: Migrates all WfRun's from one version of a WfSpec onto a newer version of the same WfSpec. This is useful for long-running WfRun's (eg. a 60-day marketing campaign) where you must update WfRun's that are in the RUNNING state rather than allowing them to run to completion.
As of 0.7.2, this feature is only partially implemented. |
RPC PutUserTaskDef
RPC GetUserTaskDef
Request Type | Response Type | Description |
---|
UserTaskDefId | UserTaskDef | Gets a specific UserTaskDef.
This RPC is highly useful for applications built around User Tasks. For example, a UI that dynamically displays form fields based on the User Task might first receive a UserTaskRun, then use that UserTaskRun to look up the UserTaskDef. The frontend would inspect the UserTaskDef and display a form field on the browser page for each field in the UserTaskDef. |
RPC GetLatestUserTaskDef
RPC RunWf
Request Type | Response Type | Description |
---|
RunWfRequest | WfRun | Runs a WfSpec to create a WfRun. |
RPC ScheduleWf
RPC SearchScheduledWfRun
RPC GetScheduledWfRun
RPC GetWfRun
Request Type | Response Type | Description |
---|
WfRunId | WfRun | Gets a WfRun. Although useful for development and debugging, this RPC is not often used by applications. |
RPC GetUserTaskRun
Request Type | Response Type | Description |
---|
UserTaskRunId | UserTaskRun | Loads a specific UserTaskRun. It includes information about to whom the UserTask is currently assigned, history of assignments and reassignments, and any context for that UserTaskRun which is specific to the WfRun. |
RPC AssignUserTaskRun
Request Type | Response Type | Description |
---|
AssignUserTaskRunRequest | .google.protobuf.Empty | Change the ownership of a UserTaskRun to a new userId, userGroup, or both. The action will be reflected in your next call to SearchUserTaskRun. This RPC is useful for applications that are using User Tasks to build an internal task-list and wish to administer the tasks. |
RPC CompleteUserTaskRun
Request Type | Response Type | Description |
---|
CompleteUserTaskRunRequest | .google.protobuf.Empty | Completes a UserTaskRun. Includes the results of the UserTaskRun, the UserTaskRun Id, and the userId of the user who completes the UserTaskRun. Results in the UserTask NodeRun being completed, and unblocks the associated ThreadRun in the WfRun.
This RPC is highly useful for applications built around a WfSpec that uses USER_TASK nodes. |
RPC CancelUserTaskRun
Request Type | Response Type | Description |
---|
CancelUserTaskRunRequest | .google.protobuf.Empty | Cancels a UserTaskRun. This will result in an EXCEPTION being propagated to the WfRun. |
RPC SaveUserTaskRunProgress
Request Type | Response Type | Description |
---|
SaveUserTaskRunProgressRequest | UserTaskRun | Saves the results of a UserTaskRun and logs who saved the content.
Throws FAILED_PRECONDITION if the UserTaskRun is in the DONE or CANCELLED state. If policy is set to FAIL_IF_CLAIMED_BY_OTHER , returns FAILED_PRECONDITION if the user_id field of the UserTaskRun does not match the user_id of the request. |
RPC ListUserTaskRuns
RPC GetNodeRun
RPC ListNodeRuns
RPC GetTaskRun
RPC ListTaskRuns
RPC GetVariable
Request Type | Response Type | Description |
---|
VariableId | Variable | Get the value of a specific Variable. When using a WfRun to model an entity, this RPC is useful for retrieving information. It is equivalent to looking up the value of a column for a specific row in a SQL table. |
RPC ListVariables
RPC PutExternalEvent
RPC GetExternalEvent
RPC AwaitWorkflowEvent
Request Type | Response Type | Description |
---|
AwaitWorkflowEventRequest | WorkflowEvent | Waits for a WorkflowEvent to be thrown by a given WfRun. Returns immediately if a matching WorkflowEvent has already been thrown; throws a DEADLINE_EXCEEDED error if the WorkflowEvent is not thrown before the deadline specified by the client.
To specify the deadline, the client should use GRPC deadlines. |
RPC ListExternalEvents
RPC SearchWfRun
Request Type | Response Type | Description |
---|
SearchWfRunRequest | WfRunIdList | Search for WfRun's. This RPC is highly useful for applications that store data in LittleHorse and need to find a specific WfRun based on certain indexed fields. |
RPC SearchNodeRun
Request Type | Response Type | Description |
---|
SearchNodeRunRequest | NodeRunIdList | Search for NodeRun's. This RPC is useful for monitoring and finding bugs in your workflows or Task Workers. |
RPC SearchTaskRun
RPC SearchUserTaskRun
Request Type | Response Type | Description |
---|
SearchUserTaskRunRequest | UserTaskRunIdList | Search for UserTaskRun's. This RPC is highly useful for applications that connect human end-users to LittleHorse: it enables you to find all tasks assigned to a specific person or group of people. |
RPC SearchVariable
Request Type | Response Type | Description |
---|
SearchVariableRequest | VariableIdList | Search for Variable's. This RPC is highly useful for applications that store data in LittleHorse and need to find a specific WfRun based on certain indexed fields. |
RPC SearchExternalEvent
RPC SearchTaskDef
RPC SearchUserTaskDef
RPC SearchWfSpec
RPC SearchExternalEventDef
RPC SearchTenant
RPC SearchPrincipal
RPC RegisterTaskWorker
Request Type | Response Type | Description |
---|
RegisterTaskWorkerRequest | RegisterTaskWorkerResponse | Used by the Task Worker to: 1. Tell the LH Server that the Task Worker has joined the Task Worker Group. 2. Receive the assignemnt of LH Server's to poll from. Generally, you won't use this request manually. |
RPC PollTask
Request Type | Response Type | Description |
---|
PollTaskRequest | PollTaskResponse | Used by Task Workers to listen for TaskRuns on the Task Queue. Generally, you won't use this RPC manually. |
RPC ReportTask
Request Type | Response Type | Description |
---|
ReportTaskRun | .google.protobuf.Empty | Used by Task Workers to report the result of a TaskRun. Generally, you won't use this rpc manually. |
RPC StopWfRun
Request Type | Response Type | Description |
---|
StopWfRunRequest | .google.protobuf.Empty | Move a WfRun or a specific ThreadRun in that WfRun to the HALTED state. |
RPC ResumeWfRun
Request Type | Response Type | Description |
---|
ResumeWfRunRequest | .google.protobuf.Empty | Resumes a WfRun or a specific ThreadRun of a WfRun. |
RPC RescueThreadRun
Request Type | Response Type | Description |
---|
RescueThreadRunRequest | WfRun | Rescues a failed ThreadRun (in the ERROR state only) by restarting it from the point of failure. Useful if a bug in Task Worker implementation caused a WfRun to fail and you did not have a FailureHandler for that NodeRun.
The specified ThreadRun must be in a state where it's latest NodeRun is: - In the ERROR state. - Has no FailureHandler ThreadRun s - The parent ThreadRun , or any parent of the parent, has not handled the Failure yet.
If that is not true, then the ThreadRun cannot be rescued and the request will return FAILED_PRECONDITION . |
RPC DeleteWfRun
Request Type | Response Type | Description |
---|
DeleteWfRunRequest | .google.protobuf.Empty | Deletes a WfRun. The WfRun cannot be in the RUNNING state. |
RPC DeleteTaskDef
RPC DeleteWfSpec
RPC DeleteUserTaskDef
RPC DeleteExternalEventDef
RPC DeletePrincipal
Request Type | Response Type | Description |
---|
DeletePrincipalRequest | .google.protobuf.Empty | Deletes a Principal . Fails with FAILED_PRECONDITION if the specified Principal is the last remaining Principal with admin permissions. Admin permissions are defined as having the global_acls of ALL_ACTIONS over the ACL_ALL_RESOURCES scope. |
RPC DeleteScheduledWfRun
Request Type | Response Type | Description |
---|
DeleteScheduledWfRunRequest | .google.protobuf.Empty | Deletes a scheduled run and prevents any further associated WfRun from being executed. |
RPC GetTaskDefMetricsWindow
RPC GetWfSpecMetricsWindow
RPC ListTaskDefMetrics
RPC ListWfSpecMetrics
RPC PutTenant
Request Type | Response Type | Description |
---|
PutTenantRequest | Tenant | EXPERIMENTAL: Creates another Tenant in the LH Server. |
RPC GetTenant
Request Type | Response Type | Description |
---|
TenantId | Tenant | EXPERIMENTAL: Gets a Tenant from the LH Server. |
RPC PutPrincipal
RPC Whoami
Request Type | Response Type | Description |
---|
.google.protobuf.Empty | Principal | Returns the Principal of the caller. |
RPC GetServerVersion
Request Type | Response Type | Description |
---|
.google.protobuf.Empty | ServerVersionResponse | Gets the version of the LH Server. |
LittleHorse Protobuf Schemas
This section contains the exact schemas for every object in our public API.
Message DeletePrincipalRequest
Deletes a Principal
. Fails with FAILED_PRECONDITION
if the specified Principal
is the last
admin Principal
.
Field | Label | Type | Description |
---|
id | | PrincipalId | The ID of the Principal to delete. |
Message Principal
A Principal represents the identity of a client of LittleHorse, whether human or
machine. The ACL's on the Principal control what actions the client is allowed
to take.
A Principal is not scoped to a Tenant; rather, a Principal is scoped to the Cluster
and may have access to one or more Tenants.
Field | Label | Type | Description |
---|
id | | PrincipalId | The ID of the Principal. In OAuth for human users, this is the user_id. In OAuth for machine clients, this is the Client ID.
mTLS for Principal identification is not yet implemented. |
created_at | | google.protobuf.Timestamp | The time at which the Principal was created. |
per_tenant_acls | map | Principal.PerTenantAclsEntry | Maps a Tenant ID to a list of ACL's that the Principal has permission to execute within that Tenant. |
global_acls | | ServerACLs | Sets permissions that this Principal has for any Tenant in the LH Cluster. |
Message Principal.PerTenantAclsEntry
Message PutPrincipalRequest
Creates or updates a Principal. If this request would remove admin privileges from the
last admin principal (i.e. ALL_ACTIONS
over ACL_ALL_RESOURCES
in the global_acls
),
then the RPC throws FAILED_PRECONDITION
.
Field | Label | Type | Description |
---|
id | | string | The ID of the Principal that we are creating. |
per_tenant_acls | map | PutPrincipalRequest.PerTenantAclsEntry | The per-tenant ACL's for the Principal |
global_acls | | ServerACLs | The ACL's for the principal in all tenants |
overwrite | | bool | If this is set to false and a Principal with the same id already exists and has different ACL's configured, then the RPC throws ALREADY_EXISTS .
If this is set to true , then the RPC will override hte |
Message PutPrincipalRequest.PerTenantAclsEntry
Message PutTenantRequest
Field | Label | Type | Description |
---|
id | | string | |
Message ServerACL
Represents a specific set of permissions over a specific set of objects
in a Tenant. This is a positive permission.
Field | Label | Type | Description |
---|
resources | repeated | ACLResource | The resource types over which permission is granted. |
allowed_actions | repeated | ACLAction | The actions that are permitted. |
name | oneof resource_filter | string | If set, then only the resources with this exact name are allowed. For example, the READ and RUN allowed_actions over ACL_TASK with name == my-task allows a Task Worker to only execute the my-task TaskDef.
If name and prefix are unset, then the ACL applies to all resources of the specified types. |
prefix | oneof resource_filter | string | If set, then only the resources whose names match this prefix are allowed.
If name and prefix are unset, then the ACL applies to all resources of the specified types. |
Message ServerACLs
List of ACL's for LittleHorse
Field | Label | Type | Description |
---|
acls | repeated | ServerACL | The associated ACL's |
Message Tenant
A Tenant is a logically isolated environment within LittleHorse. All workflows and
associated data (WfSpec, WfRun, TaskDef, TaskRun, NodeRun, etc) are scoped to within
a Tenant.
Future versions will include quotas on a per-Tenant basis.
Field | Label | Type | Description |
---|
id | | TenantId | The ID of the Tenant. |
created_at | | google.protobuf.Timestamp | The time at which the Tenant was created. |
Message ExponentialBackoffRetryPolicy
Defines an Exponential backoff policy for TaskRun retries. The delay for a retry
attempt N
is defined as:
min(base_interval_ms * (multiplier ^(N-1)), max_delay_ms)
Note that timers in LittleHorse have a resolution of about 500-1000 milliseconds,
so timing is not exact.
Field | Label | Type | Description |
---|
base_interval_ms | | int32 | Base delay in ms for the first retry. Note that in LittleHorse, timers have a resolution of 500-1000 milliseconds. Must be greater than zero. |
max_delay_ms | | int64 | Maximum delay in milliseconds between retries. |
multiplier | | float | The multiplier to use in calculating the retry backoff policy. We recommend starting with 2.0. Must be at least 1.0. |
Message TaskNode
Defines a TaskRun execution. Used in a Node and also in the UserTask Trigger Actions.
Field | Label | Type | Description |
---|
task_def_id | oneof task_to_execute | TaskDefId | |
dynamic_task | oneof task_to_execute | VariableAssignment | |
timeout_seconds | | int32 | How long until LittleHorse determines that the Task Worker had a technical ERROR if the worker does not yet reply to the Server. This is determined on a per-Attempt basis. |
retries | | int32 | Configures the amount of retries allowed on this TaskNode.
Retryable errors include: - TASK_TIMEOUT: the TaskRun was started but the scheduler didn't hear back from the Task Worker in time. - TASK_FAILED: the Task Worker reported an unexpected technical ERROR when executing the Task Function.
Other result codes are not retryable (including TASK_OUTPUT_SERIALIZING_ERROR, TASK_INPUT_VAR_SUB_ERROR, and TASK_EXCEPTION). |
exponential_backoff | optional | ExponentialBackoffRetryPolicy | If this field is set, then retries will use Exponential Backoff. |
variables | repeated | VariableAssignment | Input variables into the TaskDef. |
Message UTActionTrigger
A UTActionTrigger triggers an action upon certain lifecycle hooks
in a User Task. Actions include:
- re-assign the User Task Run
- cancel the User Task Run
- execute a Reminder Task
Hooks include:
- Upon creation of the UserTaskRun
- Upon rescheduling the UserTaskRun
Message UTActionTrigger.UTACancel
A UserTaskAction that causes a UserTaskRun to be CANCELLED when it fires.
Message UTActionTrigger.UTAReassign
A UserTaskAction that causes a UserTaskRun to be reassigned when it fires.
Field | Label | Type | Description |
---|
user_id | optional | VariableAssignment | A variable assignment that resolves to a STR representing the new user_id. If not set, the user_id of the UserTaskRun will be un-set. |
user_group | optional | VariableAssignment | A variable assignment that resolves to a STR representing the new user_group. If not set, the user_group of the UserTaskRun will be un-set. |
Message UTActionTrigger.UTATask
A UserTaskAction that causes a TaskRun to be scheduled when it fires.
Field | Label | Type | Description |
---|
task | | TaskNode | The specification of the Task to schedule. |
mutations | repeated | VariableMutation | EXPERIMENTAL: Any variables in the ThreadRun which we should mutate. |
Message VariableAssignment
A VariableAssignment is used within a WfSpec to determine how a value should be
assigned in the context of a specific WfRun. For example, in a TASK node, you
use a VariableAssignment for each input parameter to determine how the value
is set.
Note that the VariableAssignment is normally handled by the SDK; you shouldn't
have to worry about this in daily LittleHorse usage.
Field | Label | Type | Description |
---|
json_path | optional | string | If you provide a variable_name and the specified variable is JSON_OBJ or JSON_ARR type, then you may also provide a json_path which makes the VariableAssignment resolve to the specified field. |
variable_name | oneof source | string | Assign the value from a variable. |
literal_value | oneof source | VariableValue | Assign a literal value |
format_string | oneof source | VariableAssignment.FormatString | Assign a format string |
A FormatString formats a template String with values from the WfRun.
Field | Label | Type | Description |
---|
format | | VariableAssignment | A VariableAssignment which must resolve to a String that has format args. A valid string is "This is a format string with three args: 0, 1, 2" |
args | repeated | VariableAssignment | VariableAssignments which fill out the args. |
Message VariableDef
Declares a Variable.
Field | Label | Type | Description |
---|
type | | VariableType | The Type of the variable. |
name | | string | The name of the variable. |
default_value | optional | VariableValue | Optional default value if the variable isn't set; for example, in a ThreadRun if you start a ThreadRun or WfRun without passing a variable in, then this is used. |
masked_value | | bool | If true, the variable value will show as a masked string. |
Message VariableMutation
A VariableMutation defines a modification made to one of a ThreadRun's variables.
The LHS determines the variable that is modified; the operation determines how
it is modified, and the RHS is the input to the operation.
Day-to-day users of LittleHorse generally don't interact with this structure unless
they are writing their own WfSpec SDK.
Field | Label | Type | Description |
---|
lhs_name | | string | The name of the variable to mutate |
lhs_json_path | optional | string | For JSON_ARR and JSON_OBJ variables, this allows you to optionally mutate a specific sub-field of the variable. |
operation | | VariableMutationType | Defines the operation that we are executing. |
source_variable | oneof rhs_value | VariableAssignment | Set the source_variable as the RHS to use another variable from the workflow to as the RHS/ |
literal_value | oneof rhs_value | VariableValue | Use a literal value as the RHS. |
node_output | oneof rhs_value | VariableMutation.NodeOutputSource | Use the output of the current node as the RHS. |
Message VariableMutation.NodeOutputSource
Specifies to use the output of a NodeRun as the RHS.
Field | Label | Type | Description |
---|
jsonpath | optional | string | Use this specific field from a JSON output |
Message ExternalEvent
An ExternalEvent represents A Thing That Happened outside the context of a WfRun.
Generally, an ExternalEvent is used to represent a document getting signed, an incident
being resolved, an order being fulfilled, etc.
ExternalEvent's are created via the 'rpc PutExternalEvent'
For more context on ExternalEvents, check our documentation here:
https://littlehorse.dev/docs/concepts/external-events
Field | Label | Type | Description |
---|
id | | ExternalEventId | The ID of the ExternalEvent. This contains WfRunId, ExternalEventDefId, and a unique guid which can be used for idempotency of the PutExternalEvent rpc call. |
created_at | | google.protobuf.Timestamp | The time the ExternalEvent was registered with LittleHorse. |
content | | VariableValue | The payload of this ExternalEvent. |
thread_run_number | optional | int32 | If the ExternalEvent was claimed by a specific ThreadRun (via Interrupt or EXTERNAL_EVENT Node), this is set to the number of the relevant ThreadRun. |
node_run_position | optional | int32 | If the ExternalEvent was claimed by a specific ThreadRun (via EXTERNAL_EVENT Node; note that in the case of an Interrupt the node_run_position will never be set), this is set to the number of the relevant NodeRun. |
claimed | | bool | Whether the ExternalEvent has been claimed by a WfRun. |
Message ExternalEventDef
The ExternalEventDef defines the blueprint for an ExternalEvent.
Field | Label | Type | Description |
---|
id | | ExternalEventDefId | The id of the ExternalEventDef. |
created_at | | google.protobuf.Timestamp | When the ExternalEventDef was created. |
retention_policy | | ExternalEventRetentionPolicy | The retention policy for ExternalEvent's of this ExternalEventDef. This applies to the ExternalEvent only before it is matched with a WfRun. |
Message ExternalEventRetentionPolicy
Policy to determine how long an ExternalEvent is retained after creation if it
is not yet claimed by a WfRun. Note that once a WfRun has been matched with the
ExternalEvent, the ExternalEvent is deleted if/when that WfRun is deleted.
If not set, then ExternalEvent's are not deleted if they are not matched with
a WfRun.
A future version of LittleHorse will allow changing the retention_policy, which
will trigger a cleanup of old ExternalEvent
s.
Field | Label | Type | Description |
---|
seconds_after_put | oneof ext_evt_gc_policy | int64 | Delete such an ExternalEvent X seconds after it has been registered if it has not yet been claimed by a WfRun. |
Message EntrypointRun
The sub-node structure for an ENTRYPOINT NodeRun. Currently Empty.
Message ExitRun
The sub-node structure for an EXIT NodeRun. Currently Empty, will contain info
about ThreadRun Outputs once those are added in the future.
Message ExternalEventNodeRun
The sub-node structure for an EXTERNAL_EVENT NodeRun.
Field | Label | Type | Description |
---|
external_event_def_id | | ExternalEventDefId | The ExternalEventDefId that we are waiting for. |
event_time | optional | google.protobuf.Timestamp | The time that the ExternalEvent arrived. Unset if still waiting. |
external_event_id | optional | ExternalEventId | The ExternalEventId of the ExternalEvent. Unset if still waiting. |
timed_out | | bool | Whether we had a timeout while waiting for the ExternalEvent to come. |
Message Failure
Denotes a failure that happened during execution of a NodeRun or the outgoing
edges.
Field | Label | Type | Description |
---|
failure_name | | string | The name of the failure. LittleHorse has certain built-in failures, all named in UPPER_UNDERSCORE_CASE. Such failures correspond with the LHStatus.ERROR .
Any Failure named in kebab-case is a user-defined business EXCEPTION , treated as an LHStatus.EXCEPTION . |
message | | string | The human-readable message associated with this Failure. |
content | optional | VariableValue | A user-defined Failure can have a value; for example, in Java an Exception is an Object with arbitrary properties and behaviors.
Future versions of LH will allow FailureHandler threads to accept that value as an input variable. |
was_properly_handled | | bool | A boolean denoting whether a Failure Handler ThreadRun properly handled the Failure. |
failure_handler_threadrun_id | optional | int32 | If there is a defined failure handler for the NodeRun, then this field is set to the id of the failure handler thread run. |
Message NodeRun
A NodeRun is a running instance of a Node in a ThreadRun. Note that a NodeRun
is a Getable object, meaning it can be retried from the LittleHorse grpc API.
Field | Label | Type | Description |
---|
id | | NodeRunId | The ID of the NodeRun. Note that the NodeRunId contains the WfRunId, the ThreadRun's number, and the position of the NodeRun within that ThreadRun. |
wf_spec_id | | WfSpecId | The ID of the WfSpec that this NodeRun is from. This is not always the same as the ThreadRun it belongs to because of the upcoming WfSpec Version Migration feature. |
failure_handler_ids | repeated | int32 | A list of all ThreadRun's that ran to handle a failure thrown by this NodeRun. |
status | | LHStatus | The status of this NodeRun. |
arrival_time | | google.protobuf.Timestamp | The time the ThreadRun arrived at this NodeRun. |
end_time | optional | google.protobuf.Timestamp | The time the NodeRun was terminated (failed or completed). |
thread_spec_name | | string | The name of the ThreadSpec to which this NodeRun belongs. |
node_name | | string | The name of the Node in the ThreadSpec that this NodeRun belongs to. |
error_message | optional | string | A human-readable error message intended to help developers diagnose WfSpec problems. |
failures | repeated | Failure | A list of Failures thrown by this NodeRun. |
task | oneof node_type | TaskNodeRun | Denotes a TASK node, which runs a TaskRun. |
external_event | oneof node_type | ExternalEventNodeRun | An EXTERNAL_EVENT node blocks until an ExternalEvent arrives. |
entrypoint | oneof node_type | EntrypointRun | An ENTRYPOINT node is the first thing that runs in a ThreadRun. |
exit | oneof node_type | ExitRun | An EXIT node completes a ThreadRun. |
start_thread | oneof node_type | StartThreadRun | A START_THREAD node starts a child ThreadRun. |
wait_threads | oneof node_type | WaitForThreadsRun | A WAIT_THREADS node waits for one or more child ThreadRun's to complete. |
sleep | oneof node_type | SleepNodeRun | A SLEEP node makes the ThreadRun block for a certain amount of time. |
user_task | oneof node_type | UserTaskNodeRun | A USER_TASK node waits until a human executes some work and reports the result. |
start_multiple_threads | oneof node_type | StartMultipleThreadsRun | A START_MULTIPLE_THREADS node iterates over a JSON_ARR variable and spawns a child ThreadRun for each element in the list. |
throw_event | oneof node_type | ThrowEventNodeRun | |
Message SleepNodeRun
The sub-node structure for a SLEEP NodeRun.
Field | Label | Type | Description |
---|
maturation_time | | google.protobuf.Timestamp | The time at which the NodeRun is SCHEDULED TO wake up. In rare cases, if the LH Server is back-pressuring clients due to extreme load, the timer event which marks the sleep node as "matured" may come in slightly late. |
matured | | bool | Whether the SleepNodeRun has been matured. |
Message StartMultipleThreadsRun
The sub-node structure for a START_MULTIPLE_THREADS NodeRun.
Note: the output of this NodeRun, which can be used to mutate Variables,
is a JSON_ARR variable containing the ID's of all the child threadRuns.
Field | Label | Type | Description |
---|
thread_spec_name | | string | The thread_spec_name of the child thread_runs. |
child_thread_ids | repeated | int32 | The list of all created child ThreadRun's |
Message StartThreadRun
The sub-node structure for a START_THREAD NodeRun.
Field | Label | Type | Description |
---|
child_thread_id | optional | int32 | Contains the thread_run_number of the created Child ThreadRun, if it has been created already. |
thread_spec_name | | string | The thread_spec_name of the child thread_run. |
Message TaskNodeRun
The sub-node structure for a TASK NodeRun.
Field | Label | Type | Description |
---|
task_run_id | optional | TaskRunId | The ID of the TaskRun. Note that if the ThreadRun was halted when it arrived at this TASK Node, then the task_run_id will be unset. |
Message ThrowEventNodeRun
Message UserTaskNodeRun
The sub-node structure for a USER_TASK NodeRun.
Field | Label | Type | Description |
---|
user_task_run_id | optional | UserTaskRunId | The ID of the UserTaskRun. Note that if the ThreadRun was halted when it arrived at this USER_TASK node, then the user_task_run_id will be unset. |
Message WaitForThreadsRun
The sub-node structure for a WAIT_FOR_THREADS NodeRun.
Message WaitForThreadsRun.WaitForThread
A 'WaitForThread' structure defines a thread that is being waited for.
Field | Label | Type | Description |
---|
thread_end_time | optional | google.protobuf.Timestamp | The time at which the ThreadRun ended (successfully or not). Not set if the ThreadRun is still RUNNING, HALTED, or HALTING. |
thread_status | | LHStatus | The current status of the ThreadRun being waited for. |
thread_run_number | | int32 | The number of the ThreadRun being waited for. |
waiting_status | | WaitForThreadsRun.WaitingThreadStatus | The "waiting status" of this specific thread: whether it's still running, already done, handling a failure, or completely failed. |
failure_handler_thread_run_id | optional | int32 | If there is a failure on the ThreadRun, and we have a failure handler defined for it, then we will start a failure handler for this threadrun. This field is the id of that threadRun. |
Message ExternalEventDefId
ID for ExternalEventDef
Field | Label | Type | Description |
---|
name | | string | ExternalEventDef's are uniquedly identified by their name. |
Message ExternalEventId
ID for an ExternalEvent.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | WfRunId for the ExternalEvent. Note that every ExternalEvent is associated with a WfRun. |
external_event_def_id | | ExternalEventDefId | The ExternalEventDef for this ExternalEvent. |
guid | | string | A unique guid allowing for distinguishing this ExternalEvent from other events of the same ExternalEventDef and WfRun. |
Message NodeRunId
ID for a NodeRun.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | ID of the WfRun for this NodeRun. Note that every NodeRun is associated with a WfRun. |
thread_run_number | | int32 | ThreadRun of this NodeRun. Note that each NodeRun belongs to a ThreadRun. |
position | | int32 | Position of this NodeRun within its ThreadRun. |
Message PrincipalId
ID for a Principal.
Field | Label | Type | Description |
---|
id | | string | The id of this principal. In OAuth, this is the OAuth Client ID (for machine principals) or the OAuth User Id (for human principals). |
Message ScheduledWfRunId
ID for a ScheduledWfRun
Field | Label | Type | Description |
---|
id | | string | |
Message TaskDefId
ID for a TaskDef.
Field | Label | Type | Description |
---|
name | | string | TaskDef's are uniquely identified by their name. |
Message TaskDefMetricsId
ID for a specific window of TaskDef metrics.
Field | Label | Type | Description |
---|
window_start | | google.protobuf.Timestamp | The timestamp at which this metrics window starts. |
window_type | | MetricsWindowLength | The length of this window. |
task_def_id | | TaskDefId | The TaskDefId that this metrics window reports on. |
Message TaskRunId
ID for a TaskRun.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | WfRunId for this TaskRun. Note that every TaskRun is associated with a WfRun. |
task_guid | | string | Unique identifier for this TaskRun. Unique among the WfRun. |
Message TaskWorkerGroupId
ID for a TaskWorkerGroup.
Field | Label | Type | Description |
---|
task_def_id | | TaskDefId | TaskWorkerGroups are uniquely identified by their TaskDefId. |
Message TenantId
ID for a Tenant.
Field | Label | Type | Description |
---|
id | | string | The Tenant ID. |
Message UserTaskDefId
ID for a UserTaskDef
Field | Label | Type | Description |
---|
name | | string | The name of a UserTaskDef |
version | | int32 | Note that UserTaskDef's use simple versioning. |
Message UserTaskRunId
ID for a UserTaskRun
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | WfRunId for this UserTaskRun. Note that every UserTaskRun is associated with a WfRun. |
user_task_guid | | string | Unique identifier for this UserTaskRun. |
Message VariableId
Id for a Variable.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | WfRunId for the variable. Note that every Variable is associated with a WfRun. |
thread_run_number | | int32 | Each Variable is owned by a specific ThreadRun inside the WfRun it belongs to. This is that ThreadRun's number. |
name | | string | The name of the variable. |
Message WfRunId
ID for a WfRun
Field | Label | Type | Description |
---|
id | | string | The ID for this WfRun instance. |
parent_wf_run_id | optional | WfRunId | A WfRun may have a parent WfRun. If so, this field is set to the parent's ID. |
Message WfSpecId
The ID of a WfSpec.
Field | Label | Type | Description |
---|
name | | string | Name of the WfSpec. |
major_version | | int32 | Major Version of a WfSpec.
Note that WfSpec's are versioned. Creating a new WfSpec with the same name and no breaking changes to the public Variables API results in a new WfSpec being created with the same MajorVersion and a new revision. Creating a WfSpec with a breaking change to the public Variables API results in a new WfSpec being created with the same name, an incremented major_version, and revision = 0. |
revision | | int32 | Revision of a WfSpec.
Note that WfSpec's are versioned. Creating a new WfSpec with the same name and no breaking changes to the public Variables API results in a new WfSpec being created with the same MajorVersion and a new revision. Creating a WfSpec with a breaking change to the public Variables API results in a new WfSpec being created with the same name, an incremented major_version, and revision = 0. |
Message WfSpecMetricsId
ID for a specific window of WfSpec metrics.
Field | Label | Type | Description |
---|
window_start | | google.protobuf.Timestamp | The timestamp at which this metrics window starts. |
window_type | | MetricsWindowLength | The length of this window. |
wf_spec_id | | WfSpecId | The WfSpecId that this metrics window reports on. |
Message WorkflowEventDefId
ID for a WorkflowEventDef.
Field | Label | Type | Description |
---|
name | | string | The name of the WorkflowEventDef |
Message WorkflowEventId
An ID for a WorkflowEvent.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The Id of the WfRun that threw the event. |
workflow_event_def_id | | WorkflowEventDefId | The ID of the WorkflowEventDef that this WorkflowEvent is a member of. |
number | | int32 | A sequence number that makes the WorkflowEventId unique among all WorkflowEvent's of the same type thrown by the WfRun. This field starts at zero and is incremented every time a WorkflowEvent of the same type is thrown by the same WfRun. |
Message ScheduledWfRun
A ScheduledWfRun
is an object in the LittleHorse API that triggers a WfRun
to be started
on a cron schedule.
Field | Label | Type | Description |
---|
id | | ScheduledWfRunId | Unique id for this ScheduledWfRun. |
wf_spec_id | | WfSpecId | WfSpec used to run a workflow on a schedule. |
variables | map | ScheduledWfRun.VariablesEntry | A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun. |
parent_wf_run_id | optional | WfRunId | Parent WfRunId associated with all the generated WfRuns |
cron_expression | | string | UNIX expression used to specify the schedule for executing WfRuns |
created_at | | google.protobuf.Timestamp | Creation time for this ScheduledWfRun |
Message ScheduledWfRun.VariablesEntry
Message AwaitWorkflowEventRequest
Request to await until a WorkflowEvent of a certain WorkflowEventDef on a certain WfRun
is thrown. Relies upon native GRPC deadlines to configure timeouts.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The ID of the WfRun which must throw the WorkflowEvent. |
event_def_ids | repeated | WorkflowEventDefId | The IDs of the WorkflowEventDef that must be thrown. The request will return the first matching WorkflowEvent is thrown. If event_def_ids is empty, then the request will return the first WorkflowEvent thrown by the WfRun. |
workflow_events_to_ignore | repeated | WorkflowEventId | Since a single WfRun may throw multiple WorkflowEvent's with the same WorkflowEventDefId, it is necessary to provide a client the ability to "ignore" WorkflowEvent's that have already been 'awaited'. Any WorkflowEvent specified by this field is ignored by the rpc. |
Message DeleteExternalEventDefRequest
Deletes an ExternalEventDef
Message DeleteExternalEventRequest
Deletes an ExternalEvent.
Field | Label | Type | Description |
---|
id | | ExternalEventId | The ID of the ExternalEvent to delete. |
Message DeleteScheduledWfRunRequest
Delete an existing ScheduledWfRun, returns INVALID_ARGUMENT if object does not exist
Field | Label | Type | Description |
---|
id | | ScheduledWfRunId | Id of the ScheduledWfRun to be deleted |
Message DeleteTaskDefRequest
Deletes a TaskDef.
Field | Label | Type | Description |
---|
id | | TaskDefId | The ID of the TaskDef to delete. |
Message DeleteUserTaskDefRequest
Deletes a UserTaskDef.
Field | Label | Type | Description |
---|
id | | UserTaskDefId | The ID of the UserTaskDef to delete. |
Message DeleteWfRunRequest
Deletes a WfRun.
Field | Label | Type | Description |
---|
id | | WfRunId | The ID of the WfRun to delete. |
Message DeleteWfSpecRequest
Deletes a WfSpec
Field | Label | Type | Description |
---|
id | | WfSpecId | The ID of the WfSpec to delete |
Message ExternalEventDefIdList
List of ExternalEventDef Id's.
Field | Label | Type | Description |
---|
results | repeated | ExternalEventDefId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message ExternalEventIdList
List of ExternalEvent Id's
Field | Label | Type | Description |
---|
results | repeated | ExternalEventId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message ExternalEventList
A list of ExternalEvents.
Field | Label | Type | Description |
---|
results | repeated | ExternalEvent | A list of ExternalEvent objects. |
Message GetLatestUserTaskDefRequest
Returns the UserTaskDef with a given name and the highest version number.
Field | Label | Type | Description |
---|
name | | string | The name of the UserTaskDef to search for. |
Message GetLatestWfSpecRequest
Get the latest WfSpec with a given name and optionally majorVersion
Field | Label | Type | Description |
---|
name | | string | The name of the WfSpec to get. This is required. |
major_version | optional | int32 | Optionally get only WfSpec's that have the same major version. This can be useful if you want to guarantee that there have been no breaking changes to the API of the WfSpec, for example, to ensure that there have been no changes to searchable variables or required input variables. |
Message LHHostInfo
Information about a specific LH Server to contact.
Field | Label | Type | Description |
---|
host | | string | The host on the server |
port | | int32 | The port for the specified listener. |
Message ListExternalEventsRequest
List all ExternalEvents for a specific WfRunId. Note that List Requests return actual
ExternalEvent objects, not ExternalEventId's.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The WfRunId for whom we list ExternalEvent's. |
Message ListNodeRunsRequest
List all NodeRun's for a given WfRun. Note that List requests return actual NodeRun Objects,
not NodeRunId's.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The WfRun for whom we list NodeRun's. |
thread_run_number | optional | int32 | Optionally specify the thread run number to filter NodeRun's by. |
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
Message ListTaskMetricsRequest
Query to retrieve TaskDef Metrics over a period of time.
Field | Label | Type | Description |
---|
task_def_id | | TaskDefId | TaskDef id for whichwe retrieve metrics. |
last_window_start | | google.protobuf.Timestamp | This parameter is a timestamp that is used to determine the last window returned. The server will then return num_windows worth of data from before this timestamp. |
window_length | | MetricsWindowLength | Window size |
num_windows | | int32 | Number of windows to retrieve. |
Message ListTaskMetricsResponse
A list of TaskDef Metrics WIndows
Field | Label | Type | Description |
---|
results | repeated | TaskDefMetrics | List of TaskDef Metrics Windows |
Message ListTaskRunsRequest
List TaskRun's for a specific WfRun
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The WfRun for which to list TaskRun's |
Message ListUserTaskRunRequest
List UserTaskRun's for a specific WfRun
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The WfRun for which to list UserTaskRuns |
Message ListVariablesRequest
List all Variables for a specific WfRun. Note that List requests return actual Variable Objects,
not VariableId's.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The WfRun for whom we will list Variables. |
Message ListWfMetricsRequest
Query to retrieve WfSpec Metrics over a period of time.
Field | Label | Type | Description |
---|
wf_spec_id | | WfSpecId | WfSpecId of metrics to get. |
last_window_start | | google.protobuf.Timestamp | This parameter is a timestamp that is used to determine the last window returned. The server will then return num_windows worth of data from before this timestamp. |
window_length | | MetricsWindowLength | The window size |
num_windows | | int32 | Number of windows to retrieve |
Message ListWfMetricsResponse
A list of WfSpec Metrics Windows
Field | Label | Type | Description |
---|
results | repeated | WfSpecMetrics | List of WfSpec Metrics Windows |
Message MigrateWfSpecRequest
EXPERIMENTAL: migrate live WfRun's from one version of a WfSpec to another.
Message NodeRunIdList
List of NodeRun Id's.
Field | Label | Type | Description |
---|
results | repeated | NodeRunId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message NodeRunList
A list of NodeRun Objects.
Field | Label | Type | Description |
---|
results | repeated | NodeRun | A list of NodeRun Objects. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message PollTaskRequest
Request sent by the Task Worker SDK to tell the Server that the Task Worker is ready
to execute a TaskRun. Generally used only by the Task Worker SDK.
Field | Label | Type | Description |
---|
task_def_id | | TaskDefId | Is the TaskDefId that the Task Worker wants to execute. |
client_id | | string | Is the ID of the Task Worker. |
task_worker_version | optional | string | Optionally specifies the version of the Task Worker, so that it can be recorded for debugging purposes on the TaskRun itself. |
Message PollTaskResponse
Response from the server for PollTaskRequest.
Field | Label | Type | Description |
---|
result | optional | ScheduledTask | If possible, a ScheduledTask is returned. |
Message PrincipalIdList
Field | Label | Type | Description |
---|
results | repeated | PrincipalId | The resulting object id's. |
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
Message PutExternalEventDefRequest
Field to create an ExternalEventDef.
Field | Label | Type | Description |
---|
name | | string | The name of the resulting ExternalEventDef. |
retention_policy | | ExternalEventRetentionPolicy | Policy to determine how long an ExternalEvent is retained after creation if it is not yet claimed by a WfRun. Note that once a WfRun has been matched with the ExternalEvent, the ExternalEvent is deleted if/when that WfRun is deleted. If not set, then ExternalEvent's are not deleted if they are not matched with a WfRun.
A future version of LittleHorse will allow changing the retention_policy, which will trigger a cleanup of old ExternalEvent s. |
Message PutExternalEventRequest
Request used to create an ExternalEvent.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The ID of the WfRun that this Event is sent to. |
external_event_def_id | | ExternalEventDefId | The ID of the ExternalEventDef that this event implements. |
guid | optional | string | Note that an ExternalEventDefId is a three-part ID: 1. WfRunId 2. ExternalEventDef Name 3. A guid The guid from part 3) can be optionally provided to the PutExternalEventRequest in order to make it idempotent. It is a best practice to do so. |
content | | VariableValue | The content of this event. |
thread_run_number | optional | int32 | Optionally specify that this ExternalEvent may only be claimed by a specific ThreadRun. |
node_run_position | optional | int32 | Optionally specify that this ExternalEvent may only be claimed by a specific NodeRun. In order for this to be set, you must also set thread_run_number. |
Message PutTaskDefRequest
Creates a TaskDef.
Field | Label | Type | Description |
---|
name | | string | The name of the TaskDef to create. |
input_vars | repeated | VariableDef | Variables required to execute the TaskDef. Normally, these are automatically generated by the Task Worker SDK. |
output_schema | optional | TaskDefOutputSchema | Schema that validates the TaskDef's output |
Message PutUserTaskDefRequest
Creates a UserTaskDef.
Field | Label | Type | Description |
---|
name | | string | The name of the UserTaskDef to create. |
fields | repeated | UserTaskField | The fields that should be presented to the user on the screen in order to fill out the User Task. Note that these fields also define a data contract for the result of the UserTaskDef. |
description | optional | string | Optional metadata field to store user-defined data. Does not impact workflow execution. Fine to store up to a few KB of text here. |
Message PutWfSpecRequest
Creates a WfSpec. Generally, this request is generated by the Workflow object in
our various SDK's.
Field | Label | Type | Description |
---|
name | | string | The name of the resulting WfSpec. |
thread_specs | map | PutWfSpecRequest.ThreadSpecsEntry | Map from name the ThreadSpec. |
entrypoint_thread_name | | string | The name of the ThreadSpec to be used as the workflow entrypoint. |
retention_policy | optional | WorkflowRetentionPolicy | Optional policy to determine how long a WfRun is retained in the data store after it is completed or terminated. |
parent_wf_spec | optional | WfSpec.ParentWfSpecReference | Parent WfSpec Reference. If this is set, then all WfRun's for this WfSpec MUST be Child WfRun's of the specified WfSpec. |
allowed_updates | | AllowedUpdateType | Configures the behavior of this individual request. Can be used to prevent breaking changes to the WfSpec, prevent any changes to the WfSpec, or allow all changes to the WfSpec. |
Message PutWfSpecRequest.ThreadSpecsEntry
Message PutWorkflowEventDefRequest
EXPERIMENTAL: Creates a WorkflowEventDef
Message RegisterTaskWorkerRequest
Message used by Task Worker to register itself to the server and ask for assignments of
servers to poll.
Used by the Task Worker SDK; generally, you shouldn't have to touch this manually.
Field | Label | Type | Description |
---|
task_worker_id | | string | Is the ID of the Task Worker. |
task_def_id | | TaskDefId | The TaskDef the worker wants to poll for. |
Message RegisterTaskWorkerResponse
Response containing list of Servers that the Task Worker should connect to and start polling from.
Only used internally by the Task Worker SDK.
Field | Label | Type | Description |
---|
your_hosts | repeated | LHHostInfo | The list of LH Server hosts that the Task Worker should start polling. |
is_cluster_healthy | optional | bool | Whether the LH Cluster is healthy. |
Message ReportTaskRun
Request used by the Task Worker SDK to report the result of a TaskRun execution.
Field | Label | Type | Description |
---|
task_run_id | | TaskRunId | ID of the TaskRun |
time | | google.protobuf.Timestamp | When the TaskRun was executed |
status | | TaskStatus | Status of the TaskRun |
log_output | optional | VariableValue | Optional information for logging or exceptions |
attempt_number | | int32 | Attempt number of the TaskRun |
output | oneof result | VariableValue | Successfully completed task |
error | oneof result | LHTaskError | Technical error |
exception | oneof result | LHTaskException | Business exception |
Message RescueThreadRunRequest
The request used to rescue a failed ThreadRun at a specific NodeRun.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | The id of the WfRun which we are going to rescue. |
thread_run_number | | int32 | The number of the failed ThreadRun that we will rescue. The specified ThreadRun must be in a state where it's latest NodeRun is: - In the ERROR state. - Has no FailureHandler ThreadRun s - The parent ThreadRun , or any parent of the parent, has not handled the Failure yet.
If that is not true, then the ThreadRun cannot be rescued and the request will return FAILED_PRECONDITION . |
skip_current_node | | bool | If set to true , then the ThreadRun will skip past the Node of the current failed NodeRun and advance according to the outgoing edges. If set to false , then the ThreadRun will schedule another NodeRun for the current Node |
Message ResumeWfRunRequest
Resume a WfRun.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | Is the WfRunId |
thread_run_number | | int32 | The number of the ThreadRun to resume. Note that resuming the entrypoint ThreadRun (which always has number 0 ) causes the whole WfRun to resume. If you do not manually set the thread_run_number field, it defaults to zero, so resuming the entire WfRun is the default behavior. |
Message RunWfRequest
Create a Workflow Run.
Field | Label | Type | Description |
---|
wf_spec_name | | string | The name of the WfSpec to run. |
major_version | optional | int32 | Optionally specify the major version of the WfSpec to run. This guarantees that the "signature" of the WfSpec (i.e. the required input variables, and searchable variables) will not change for this app. |
revision | optional | int32 | Optionally specify the specific revision of the WfSpec to run. It is not recommended to use this in practice, as the WfSpec logic should be de-coupled from the applications that run WfRun's. |
variables | map | RunWfRequest.VariablesEntry | A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun. |
id | optional | string | You can optionally specify the ID of this WfRun. This is a recommended best practice as it also makes your request idempotent and allows you to easily find the WfRun at a later time. |
parent_wf_run_id | optional | WfRunId | |
Message RunWfRequest.VariablesEntry
Message ScheduleWfRequest
Schedule WfRuns based on a specific cron UNIX expression
Field | Label | Type | Description |
---|
id | optional | string | Specific ID |
wf_spec_name | | string | The name of the WfSpec to run. |
major_version | optional | int32 | Optionally specify the major version of the WfSpec to run. This guarantees that the "signature" of the WfSpec (i.e. the required input variables, and searchable variables) will not change for this app. |
revision | optional | int32 | Optionally specify the specific revision of the WfSpec to run. It is not recommended to use this in practice, as the WfSpec logic should be de-coupled from the applications that run WfRun's. |
variables | map | ScheduleWfRequest.VariablesEntry | A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun. |
parent_wf_run_id | optional | WfRunId | Parent WfRunId associated with all the generated WfRuns |
cron_expression | | string | UNIX expression used to specify the schedule for executing WfRuns |
Message ScheduleWfRequest.VariablesEntry
Message ScheduledTask
Message sent by server to Task Worker SDK specifying a specific TaskRun to be executed.
This is used and handled internally by the Task Worker SDK.
Field | Label | Type | Description |
---|
task_run_id | | TaskRunId | Id of the TaskRun to execute. |
task_def_id | | TaskDefId | ID of the TaskDef to which the TaskRun belongs. |
attempt_number | | int32 | Attempt number of the TaskRun, zero indexed. attempt_number of 0 means this is the first attempt; 1 means this is the first retry, etc. |
variables | repeated | VarNameAndVal | Input variables for this TaskRun. |
created_at | | google.protobuf.Timestamp | |
source | | TaskRunSource | Source of the TaskRun. Currently, there are two options: 1. A TASK node 2. A reminder task scheduled by a trigger on a User Task. |
Message ScheduledWfRunIdList
List of ScheduledWfRun
Field | Label | Type | Description |
---|
results | repeated | ScheduledWfRunId | A list of ScheduledWfRun Objects |
Message SearchExternalEventDefRequest
Search for ExternalEventDefs based on certain criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
prefix | optional | string | Optionally search only for ExternalEventDef's whose name starts with this prefix. |
Message SearchExternalEventRequest
Search for ExternalEvents based on certain criteria.
Required field ExternalEventDefId specifies which ExternalEventDef
to search for ExternalEvents under.
At this time, it is not possible to make a search for all ExternalEvents.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
earliest_start | optional | google.protobuf.Timestamp | Specifies to return only ExternalEvents created after this time |
latest_start | optional | google.protobuf.Timestamp | Specifies to return only ExternalEvents created before this time |
external_event_def_id | | ExternalEventDefId | Search for ExternalEvents by their ExternalEventDefId
* Note: If ExternalEventDefId is not provided or does not exist, gRPC status code 'INVALID_ARGUMENT' will be returned. |
is_claimed | optional | bool | Optionally search for only ExternalEvents that are claimed or not. |
Message SearchNodeRunRequest
Search for NodeRun's by certain criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
earliest_start | optional | google.protobuf.Timestamp | Only return NodeRun's created after this time. |
latest_start | optional | google.protobuf.Timestamp | Only return NodeRun's created before this time. |
node_type | | SearchNodeRunRequest.NodeType | Specifies the type of NodeRun to search for. |
status | | LHStatus | Specifies the status of NodeRun to search for. |
Message SearchPrincipalRequest
Search for Principals based on certain criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
earliest_start | optional | google.protobuf.Timestamp | Specifies to return only Principals's created after this time |
latest_start | optional | google.protobuf.Timestamp | Specifies to return only Principals's created before this time |
isAdmin | oneof principal_criteria | bool | List only Principals that are admins |
tenantId | oneof principal_criteria | string | List Principals associated with this Tenant ID |
Message SearchScheduledWfRunRequest
Search filters for ScheduledWfRun's
Field | Label | Type | Description |
---|
wf_spec_name | | string | The name of the WfSpec to filter |
major_version | optional | int32 | The major version of the WfSpec to filter |
revision | optional | int32 | The revision number of the WfSpec to filter |
Message SearchTaskDefRequest
Search for TaskDef's based on certain criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
prefix | optional | string | Optionally specify to only return TaskDef's with a specific prefix. |
Message SearchTaskRunRequest
Searches for TaskRuns by various criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
task_def_name | | string | Specifies the TaskDef of TaskRun's to return. This is required. |
status | optional | TaskStatus | Specifies to only return TaskRun's matching this status. |
earliest_start | optional | google.protobuf.Timestamp | Specifies to only return TaskRun's that were scheduled after this time. |
latest_start | optional | google.protobuf.Timestamp | Specifies to only return TaskRun's that were scheduled before this time. |
Message SearchTenantRequest
Search for all available TenantIds for current Principal
Field | Label | Type | Description |
---|
limit | optional | int32 | Maximum results to return in one request. |
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
Message SearchUserTaskDefRequest
Search for UserTaskDef's.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
prefix | oneof user_task_def_criteria | string | Return all UserTaskDef's with a specific prefix. |
name | oneof user_task_def_criteria | string | Return all UserTaskDef's with a specific name. |
Message SearchUserTaskRunRequest
Search for UserTaskRun's matching certain criteria. The attributes are additive,
you may specify any combination of fields in this request. Only UserTaskRun's
matching all criteria will be returned.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
status | optional | UserTaskRunStatus | Status of UserTaskRun's to return. |
user_task_def_name | optional | string | UserTaskDef name to search for. |
user_id | optional | string | Search for UserTaskRun's assigned to this user id. |
user_group | optional | string | Search for UserTaskRun's assigned to this user group. |
earliest_start | optional | google.protobuf.Timestamp | Search for UserTaskRun's that were created after this time. |
latest_start | optional | google.protobuf.Timestamp | Search for UserTaskRun's that were created before this time. |
Message SearchVariableRequest
Search for Variables by their value. This request is also highly useful to search for
WfRun's based on the value of Variable's that are not in the Entrypoint ThreadRun,
and also when you are using LittleHorse as a data store and need to perform a search.
You may only search for a Variable that has an index specified on it. This may be done
via th .searchable()
method on our SDK's.
Note that we do not yet support searching JSON_OBJ or JSON_ARR fields, but you may
still mark those fields as searchable. We will soon add the ability to query those
fields via the indices.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
value | | VariableValue | Specifies the value that the variable must be. Exact match is required. |
wf_spec_major_version | optional | int32 | Specifies major version of the WfSpec for the associated WfRun. |
wf_spec_revision | optional | int32 | Specifies the revision of the WfSpec for the associated WfRun. |
var_name | | string | Specifies the name of the variable to search for. This is required. |
wf_spec_name | | string | Specifies the name of the WfSpec for the associated WfRun's. This is required. |
Message SearchWfRunRequest
A request used to retrieve a list of WfRunId's by certain criteria.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
wf_spec_name | | string | The WfSpec whose WfRun's we are searching for. This is required. |
wf_spec_major_version | optional | int32 | Specifies to return only WfRun's from this WfSpec Major Version. |
wf_spec_revision | optional | int32 | Specifies to return only WfRun's from this WfSpec Revision. Can only be set if wf_spec_major_version is also set. |
status | optional | LHStatus | Specifies to return only WfRun's matching this status. |
earliest_start | optional | google.protobuf.Timestamp | Specifies to return only WfRun's that started after this time |
latest_start | optional | google.protobuf.Timestamp | Specifies to return only WfRun's that started before this time |
variable_filters | repeated | VariableMatch | Allows filtering WfRun's based on the value of the Variables. This ONLY works for the Variables in the entrypiont threadrun (that is, variables where the threadRunNumber == 0). |
Message SearchWfSpecRequest
Search for WfSpec's.
Field | Label | Type | Description |
---|
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
limit | optional | int32 | Maximum results to return in one request. |
name | oneof wf_spec_criteria | string | Return WfSpec's with a specific name. |
prefix | oneof wf_spec_criteria | string | Return WfSpec's with a specific prefix. |
task_def_name | oneof wf_spec_criteria | string | Return all WfSpec's that make use of a given TaskDef. |
Message ServerVersionResponse
The version of the LH Server according to Semantic Versioning
Field | Label | Type | Description |
---|
major_version | | int32 | Server Major Version |
minor_version | | int32 | Server Minor Version |
patch_version | | int32 | Server Patch Version |
pre_release_identifier | optional | string | Prerelease Identifier. If this is set, then the server is NOT a production release but rather a release candidate or experimental pre-release. |
Message StopWfRunRequest
Message to HALT a WfRun.
Field | Label | Type | Description |
---|
wf_run_id | | WfRunId | Is the WfRunId |
thread_run_number | | int32 | The number of the ThreadRun to halt. Note that halting the entrypoint ThreadRun (which always has number 0 ) causes the whole WfRun to halt. If you do not manually set the thread_run_number field, it defaults to zero, so stopping the entire WfRun is the default behavior. |
Message TaskDefIdList
List of TaskDef Id's.
Field | Label | Type | Description |
---|
results | repeated | TaskDefId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message TaskDefMetrics
Metrics for a TaskDef in a certain time period.
Field | Label | Type | Description |
---|
task_def_id | | TaskDefId | TaskDef that the metrics apply to. |
window_start | | google.protobuf.Timestamp | When the window started. |
type | | MetricsWindowLength | Length of the window. |
schedule_to_start_max | | int64 | Longest time that a TaskRun was in the TASK_SCHEDULED state |
schedule_to_start_avg | | int64 | Average time that a TaskRun was in the TASK_SCHEDULED state |
start_to_complete_max | | int64 | Longest time between a TaskRun being started and completed |
start_to_complete_avg | | int64 | Average time between a TaskRun being started and completed |
total_completed | | int64 | Total number of TaskRun's that reached the TASK_SUCCESS state |
total_errored | | int64 | Total number of TaskRun's that reached the TASK_ERROR state |
total_started | | int64 | Total number of TaskRun's that transitioned to the TASK_RUNNING state |
total_scheduled | | int64 | Total number of TaskRun's that were scheduled |
Message TaskDefMetricsQueryRequest
Query to retrieve a specific TaskDef Metrics Window.
Field | Label | Type | Description |
---|
window_start | | google.protobuf.Timestamp | Return the window containing this timestamp. The window start is not guaranteed to align perfectly with the request. |
window_type | | MetricsWindowLength | The window size |
task_def_name | optional | string | The name of the specific TaskDef for which we are calculating metrics. |
Message TaskRunIdList
List of TaskRun ID's.
Field | Label | Type | Description |
---|
results | repeated | TaskRunId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message TaskRunList
A list of TaskRun's
Field | Label | Type | Description |
---|
results | repeated | TaskRun | A list of TaskRun Objects |
Message TaskWorkerGroup
Describes all workers registered for a specific TaskDef.
Field | Label | Type | Description |
---|
id | | TaskWorkerGroupId | Identifier for the group. |
created_at | | google.protobuf.Timestamp | Timestamp indicating when the worker group was initially registered. |
task_workers | map | TaskWorkerGroup.TaskWorkersEntry | Metadata grouped by ClientId string. |
Message TaskWorkerGroup.TaskWorkersEntry
Message TaskWorkerHeartBeatRequest
Message used by Task Worker to register itself to the server and ask for assignments of
servers to poll.
Used by the Task Worker SDK; generally, you shouldn't have to touch this manually.
Field | Label | Type | Description |
---|
client_id | | string | |
task_def_id | | TaskDefId | |
listener_name | | string | |
Describes a specific task worker
Field | Label | Type | Description |
---|
task_worker_id | | string | User-defined identifier for the worker. |
latest_heartbeat | | google.protobuf.Timestamp | Timestamp indicating the last heartbeat sent by the worker. |
hosts | repeated | LHHostInfo | The host(s) where the worker is polling tasks |
Message TenantIdList
Field | Label | Type | Description |
---|
results | repeated | TenantId | The resulting object id's. |
bookmark | optional | bytes | Bookmark for cursor-based pagination; pass if applicable. |
Message UserTaskDefIdList
List of UserTaskDef Id's.
Field | Label | Type | Description |
---|
results | repeated | UserTaskDefId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message UserTaskRunIdList
A list of UserTaskRun Id's
Field | Label | Type | Description |
---|
results | repeated | UserTaskRunId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message UserTaskRunList
List of UserTaskRuns
Field | Label | Type | Description |
---|
results | repeated | UserTaskRun | A list of UserTaskRun Objects |
Message VariableIdList
This is a list of Variable ID's.
Field | Label | Type | Description |
---|
results | repeated | VariableId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message VariableList
A list of Variables.
Field | Label | Type | Description |
---|
results | repeated | Variable | A list of Variable objects. |
Message VariableMatch
Used by a SearchWfRunRequest to filter WfRun's and only return those whose Variable's
match a certain filter.
Field | Label | Type | Description |
---|
var_name | | string | The name of the variable to inspect. |
value | | VariableValue | The value that the Variable must have in order to satisfy this VariableMatch |
Message WfRunIdList
List of WfRun Id's
Field | Label | Type | Description |
---|
results | repeated | WfRunId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message WfSpecIdList
List of WfSpec Id's.
Field | Label | Type | Description |
---|
results | repeated | WfSpecId | The resulting object id's. |
bookmark | optional | bytes | The bookmark can be used for cursor-based pagination. If it is null, the server has returned all results. If it is set, you can pass it into your next request to resume searching where your previous request left off. |
Message WfSpecMetrics
Metrics for a WfSpec in a specific time window
Field | Label | Type | Description |
---|
wf_spec_id | | WfSpecId | The WfSpecId that these metrics analyze |
window_start | | google.protobuf.Timestamp | The time that the window started |
type | | MetricsWindowLength | The length of the window |
total_started | | int64 | Total number of WfRun's created for this WfSpec |
total_completed | | int64 | Total number of WfRun's that reached the COMPLETED state |
total_errored | | int64 | Total number of WfRun's that reached the ERROR state |
start_to_complete_max | | int64 | Longest time between a WfRun being started and reaching the COMPLETED state |
start_to_complete_avg | | int64 | Average time that a WfRun took to reach the COMPLETED state |
Message WfSpecMetricsQueryRequest
Query to retrieve a specific WfSpec Metrics Window.
Field | Label | Type | Description |
---|
wf_spec_id | | WfSpecId | WfSpecId of metrics to get. |
window_start | | google.protobuf.Timestamp | Return the window containing this timestamp. The window start is not guaranteed to align perfectly with the request. |
window_length | | MetricsWindowLength | The window size |
Message TaskDef
A TaskDef defines a blueprint for a TaskRun that can be dispatched to Task Workers.
Field | Label | Type | Description |
---|
id | | TaskDefId | The ID of this TaskDef. |
input_vars | repeated | VariableDef | The input variables required to execute this TaskDef. |
created_at | | google.protobuf.Timestamp | The time at which this TaskDef was created. |
schema_output | optional | TaskDefOutputSchema | Schema that validates the TaskDef's output |
Message TaskDefOutputSchema
Schema that validates the TaskDef's output
Field | Label | Type | Description |
---|
value_def | | VariableDef | The definition for the output content |
Message LHTaskError
Message denoting a TaskRun failed for technical reasons.
Field | Label | Type | Description |
---|
type | | LHErrorType | The technical error code. |
message | | string | Human readable message for debugging. |
Message LHTaskException
Message denoting a TaskRun's execution signaled that something went wrong in the
business process, throwing a littlehorse 'EXCEPTION'.
Field | Label | Type | Description |
---|
name | | string | The user-defined Failure name, for example, "credit-card-declined" |
message | | string | Human readadble description of the failure. |
content | | VariableValue | |
Message TaskAttempt
A single time that a TaskRun was scheduled for execution on a Task Queue.
Field | Label | Type | Description |
---|
log_output | optional | VariableValue | Optional information provided by the Task Worker SDK for debugging. Usually, if set it contains a stacktrace or it contains information logged via WorkerContext#log() . |
schedule_time | optional | google.protobuf.Timestamp | The time the TaskAttempt was scheduled on the Task Queue. Not set for a TaskAttempt that is in the TASK_PENDING status; for example, when waiting between retries with exponential backoff. |
start_time | optional | google.protobuf.Timestamp | The time the TaskAttempt was pulled off the queue and sent to a TaskWorker. |
end_time | optional | google.protobuf.Timestamp | The time the TaskAttempt was finished (either completed, reported as failed, or timed out) |
task_worker_id | | string | EXPERIMENTAL: the ID of the Task Worker who executed this TaskRun. |
task_worker_version | optional | string | The version of the Task Worker that executed the TaskAttempt. |
status | | TaskStatus | The status of this TaskAttempt. |
output | oneof result | VariableValue | Denotes the Task Function executed properly and returned an output. |
error | oneof result | LHTaskError | An unexpected technical error was encountered. May or may not be retriable. |
exception | oneof result | LHTaskException | The Task Function encountered a business problem and threw a technical exception. |
masked_value | | bool | Indicates whether the result of the attempt field has been masked |
Message TaskNodeReference
Reference to a NodeRun of type TASK which caused a TaskRun to be scheduled.
Field | Label | Type | Description |
---|
node_run_id | | NodeRunId | The ID of the NodeRun which caused this TASK to be scheduled. |
Message TaskRun
A TaskRun resents a single instance of a TaskDef being executed.
Field | Label | Type | Description |
---|
id | | TaskRunId | The ID of the TaskRun. Note that the TaskRunId contains the WfRunId. |
task_def_id | | TaskDefId | The ID of the TaskDef being executed. |
attempts | repeated | TaskAttempt | All attempts scheduled for this TaskRun. A TaskAttempt represents an occurrence of the TaskRun being put on a Task Queue to be executed by the Task Workers. |
input_variables | repeated | VarNameAndVal | The input variables to pass into this TaskRun. Note that this is a list and not a map, because ordering matters. Depending on the language implementation, not every LittleHorse Task Worker SDK has the ability to determine the names of the variables from the method signature, so we provide both names and ordering. |
source | | TaskRunSource | The source (in the WfRun) that caused this TaskRun to be created. Currently, this can be either a TASK node, or a User Task Action Task Trigger in a USER_TASK node (such as a task used to send reminders). |
scheduled_at | | google.protobuf.Timestamp | When the TaskRun was scheduled. |
status | | TaskStatus | The status of the TaskRun. |
timeout_seconds | | int32 | The timeout before LH considers a TaskAttempt to be timed out. |
total_attempts | | int32 | The maximum number of attempts that may be scheduled for this TaskRun. NOTE: setting total_attempts to 1 means that there are no retries. |
exponential_backoff | optional | ExponentialBackoffRetryPolicy | Optional backoff policy . |
Message TaskRunSource
The source of a TaskRun; i.e. why it was scheduled.
Field | Label | Type | Description |
---|
task_node | oneof task_run_source | TaskNodeReference | Reference to a NodeRun of type TASK which scheduled this TaskRun. |
user_task_trigger | oneof task_run_source | UserTaskTriggerReference | Reference to the specific UserTaskRun trigger action which scheduled this TaskRun |
wf_spec_id | optional | WfSpecId | The ID of the WfSpec that is being executed. Always set in ScheduledTask.source so that the WorkerContext can know this information. |
Message VarNameAndVal
A key-value pair of variable name and value.
Field | Label | Type | Description |
---|
var_name | | string | The variable name. |
value | | VariableValue | The value of the variable for this TaskRun. |
masked | | bool | Indicates whether the content of the value field has been masked |
Message AssignUserTaskRunRequest
Re-Assigns a UserTaskRun to a specific userId or userGroup.
Field | Label | Type | Description |
---|
user_task_run_id | | UserTaskRunId | The UserTaskRun to assign to a new user_id or user_group. |
override_claim | | bool | If override_claim is set to false and the UserTaskRun is already assigned to a user_id, then the request throws a FAILED_PRECONDITION error. If set to true, then the old claim is overriden and the UserTaskRun is assigned to the new user. |
user_group | optional | string | The new user_group to which the UserTaskRun is assigned. If not set, then the user_group of the UserTaskRun is actively unset by this request. At least one of the user_group and user_id must be set. |
user_id | optional | string | The new user_id to which the UserTaskRun is assigned. If not set, then the user_id of the UserTaskRun is actively unset by this request. At least one of the user_group and user_id must be set. |
Message CancelUserTaskRunRequest
Cancels a UserTaskRun.
Field | Label | Type | Description |
---|
user_task_run_id | | UserTaskRunId | The id of the UserTaskRun to cancel. |
Message CompleteUserTaskRunRequest
Completes a UserTaskRun with provided values.
Field | Label | Type | Description |
---|
user_task_run_id | | UserTaskRunId | The id of UserTaskRun to complete. |
results | map | CompleteUserTaskRunRequest.ResultsEntry | A map from UserTaskField.name to a VariableValue containing the results of the user filling out the form. |
user_id | | string | The ID of the user who executed the task. |
Message CompleteUserTaskRunRequest.ResultsEntry
Message SaveUserTaskRunProgressRequest
Saves the results of a UserTaskRun and logs who saved the content.
Throws FAILED_PRECONDITION if the UserTaskRun is in the DONE
or CANCELLED
state.
If policy
is set to FAIL_IF_CLAIMED_BY_OTHER
, returns FAILED_PRECONDITION
if the
user_id
field of the UserTaskRun
does not match the user_id
of the request.
Message SaveUserTaskRunProgressRequest.ResultsEntry
Message UserTaskDef
UserTaskDef is the metadata blueprint for UserTaskRuns.
Field | Label | Type | Description |
---|
name | | string | The name of the UserTaskDef |
version | | int32 | The version of the UserTaskDef . Only simple versioning is supported. |
description | optional | string | Metadata field that does not impact WfRun execution. Useful for providing context on the UserTaskRun, for example when displaying it on a general-purpose task manager application. |
fields | repeated | UserTaskField | These are the fields comprise the User Task. A User Task Manager application, or any application used to complete a UserTaskRun, should inspect these fields and display form entries for each one. |
created_at | | google.protobuf.Timestamp | The time the UserTaskRun was created. |
Message UserTaskEvent
This is an event stored in the audit log of a UserTaskRun
purely for observability
purposes.
Message UserTaskEvent.UTEAssigned
Message denoting that the UserTaskRun was assigned.
Field | Label | Type | Description |
---|
old_user_id | optional | string | The user_id before the ownership change, if set. |
old_user_group | optional | string | The user_group before the ownership change, if set. |
new_user_id | optional | string | The user_id after the ownership change, if set. |
new_user_group | optional | string | The user_group after the ownership change, if set. |
Message UserTaskEvent.UTECancelled
Empty message used to denote that the UserTaskRun
was cancelled.
Field | Label | Type | Description |
---|
message | | string | |
Message UserTaskEvent.UTESaved
Message to denote that the UserTaskRun
was saved.
Message UserTaskEvent.UTESaved.ResultsEntry
Message UserTaskEvent.UTETaskExecuted
Message to denote that a TaskRun
was scheduled by a trigger for this UserTaskRun.
Field | Label | Type | Description |
---|
task_run | | TaskRunId | The TaskRunId of the scheduled TaskRun |
Message UserTaskField
A UserTaskField is a specific field of data to be entered into a UserTaskRun.
Field | Label | Type | Description |
---|
name | | string | The name of the field. When a UserTaskRun is completed, the NodeOutput is a single-level JSON_OBJ. Each key is the name of the field. Must be unique. |
type | | VariableType | The type of the output. Must be a primitive type (STR, BOOL, INT, DOUBLE). |
description | optional | string | Optional description which can be displayed by the User Task UI application. Does not affect WfRun execution. |
display_name | | string | The name to be displayed by the User Task UI application. Does not affect WfRun execution. |
required | | bool | Whether this field is required for UserTaskRun completion. |
Message UserTaskRun
A UserTaskRun is a running instance of a UserTaskDef. It is created when a
ThreadRun arrives at a Node of type USER_TASK
.
Field | Label | Type | Description |
---|
id | | UserTaskRunId | The ID of the UserTaskRun. |
user_task_def_id | | UserTaskDefId | The ID of the UserTaskDef that this UserTaskRun comes from. |
user_group | optional | string | Denotes the UserTaskRun as belonging to a specific User Group.
The user_group does not refer to a group that is stored in LittleHorse; rather, it is the responsibility of the application to keep track of user/group identity and ensure that the user_group does indeed exist.
Either user_id or user_group or both are set at any time. |
user_id | optional | string | Denotes the UserTaskRun as assigned to a specific User ID. If this is set, then the UserTaskRun is either in the ASSIGNED, DONE, or CANCELLED status.
The user_id does not refer to a User that is stored in LittleHorse; rather, it is the responsibility of the application to keep track of user identity and ensure that the user_id does indeed exist.
Either user_id or user_group or both are set at any time. |
results | map | UserTaskRun.ResultsEntry | The results of the UserTaskRun. Empty if the UserTaskRun has not yet been completed. Each key in this map is the name of a corresponding UserTaskField on the UserTaskDef. |
status | | UserTaskRunStatus | Status of the UserTaskRun. Can be UNASSIGNED, ASSIGNED, DONE, or CANCELLED. |
events | repeated | UserTaskEvent | A list of events that have happened. Used for auditing information. |
notes | optional | string | Notes about this UserTaskRun that are specific to the WfRun. These notes are set by the WfSpec based on variables inside the specific WfRun and are intended to be displayed on the User Task Manager application. They do not affect WfRun execution. |
scheduled_time | | google.protobuf.Timestamp | The time that the UserTaskRun was created/scheduled. |
node_run_id | | NodeRunId | The NodeRun with which the UserTaskRun is associated. |
epoch | | int32 | Current observed epoch of the UserTaskRun, related to the number of times it has been updated or re-assigned. Used internally to implement automated reassignment and reminder tasks. |
Message UserTaskRun.ResultsEntry
Message UserTaskTriggerReference
All TaskRun's have a "trigger reference" which refers to the WfRun Element that
caused the TaskRun to be scheduled. For example, a TaskRun on a regular TASK_NODE
has a TaskNodeReference.
The UserTaskTriggerReference serves as the "Trigger Reference" for a TaskRun that
was scheduled by a lifecycle hook on a UserTaskRun (eg. a reminder task).
The UserTaskTriggerReference is most useful in the WorkerContext of the Task Worker
SDK, which allows the Task Method to determine where the TaskRun comes from.
Field | Label | Type | Description |
---|
node_run_id | | NodeRunId | Is the NodeRun that the UserTaskRun belongs to. |
user_task_event_number | | int32 | Is the index in the events field of the UserTaskRun that the TaskRun corresponds to. |
user_id | optional | string | Is the user_id that the UserTaskRun is assigned to. Unset if UserTaskRun is not asigned to a specific user_id. |
user_group | optional | string | Is the user_id that the UserTaskRun is assigned to. Unset if UserTaskRun is not asigned to a specific user_id. |
Message Variable
A Variable is an instance of a variable assigned to a WfRun.
Field | Label | Type | Description |
---|
id | | VariableId | ID of this Variable. Note that the VariableId contains the relevant WfRunId inside it, the threadRunNumber, and the name of the Variabe. |
value | | VariableValue | The value of this Variable. |
created_at | | google.protobuf.Timestamp | When the Variable was created. |
wf_spec_id | | WfSpecId | The ID of the WfSpec that this Variable belongs to. |
masked | | bool | Marks a variable to show masked values |
Message VariableValue
VariableValue is a structure containing a value in LittleHorse. It can be
used to pass input variables into a WfRun/ThreadRun/TaskRun/etc, as output
from a TaskRun, as the value of a WfRun's Variable, etc.
Field | Label | Type | Description |
---|
json_obj | oneof value | string | A String representing a serialized json object. |
json_arr | oneof value | string | A String representing a serialized json list. |
double | oneof value | double | A 64-bit floating point number. |
bool | oneof value | bool | A boolean. |
str | oneof value | string | A string. |
int | oneof value | int64 | The INT variable type is stored as a 64-bit integer. The INT can be cast to a DOUBLE . |
bytes | oneof value | bytes | An arbitrary String of bytes. |
Message FailureBeingHandled
Points to the Failure that is currently being handled in the ThreadRun.
Field | Label | Type | Description |
---|
thread_run_number | | int32 | The thread run number. |
node_run_position | | int32 | The position of the NodeRun causing the failure. |
failure_number | | int32 | The number of the failure. |
Message HandlingFailureHaltReason
A Halt Reason denoting that a ThreadRun is halted while a Failure Handler is being run.
Field | Label | Type | Description |
---|
handler_thread_id | | int32 | The ID of the Failure Handler ThreadRun. |
Message Interrupted
A Halt Reason denoting that a ThreadRun is halted because it is waiting for the
interrupt handler threadRun to run.
Field | Label | Type | Description |
---|
interrupt_thread_id | | int32 | The ID of the Interrupt Handler ThreadRun. |
Message ManualHalt
A Halt Reason denoting that a ThreadRun was halted manually, via the rpc StopWfRun
request.
Field | Label | Type | Description |
---|
meaning_of_life | | bool | Nothing to store. |
Message ParentHalted
A Halt Reason denoting that a ThreadRun is halted because its parent is also HALTED.
Field | Label | Type | Description |
---|
parent_thread_id | | int32 | The ID of the halted parent. |
Message PendingFailureHandler
Represents a Failure Handler that is pending to be run.
Field | Label | Type | Description |
---|
failed_thread_run | | int32 | The ThreadRun that failed. |
handler_spec_name | | string | The name of the ThreadSpec to run to handle the failure. |
Message PendingFailureHandlerHaltReason
A Halt Reason denoting that a ThreadRun is halted while a Failure Handler is enqueued to be
run.
Field | Label | Type | Description |
---|
node_run_position | | int32 | The position of the NodeRun which threw the failure. |
Message PendingInterrupt
Represents an ExternalEvent that has a registered Interrupt Handler for it
and which is pending to be sent to the relevant ThreadRun's.
Field | Label | Type | Description |
---|
external_event_id | | ExternalEventId | The ID of the ExternalEvent triggering the Interrupt. |
handler_spec_name | | string | The name of the ThreadSpec to run to handle the Interrupt. |
interrupted_thread_id | | int32 | The ID of the ThreadRun to interrupt. Must wait for this ThreadRun to be HALTED before running the Interrupt Handler. |
Message PendingInterruptHaltReason
A Halt Reason denoting that a ThreadRun is halted while waiting for an Interrupt handler
to be run.
Field | Label | Type | Description |
---|
external_event_id | | ExternalEventId | The ExternalEventId that caused the Interrupt. |
Message ThreadHaltReason
Denotes a reason why a ThreadRun is halted. See ThreadRun.halt_reasons
for context.
Message ThreadRun
A ThreadRun is a running thread of execution within a WfRun.
Field | Label | Type | Description |
---|
wf_spec_id | | WfSpecId | The current WfSpecId of this ThreadRun. This must be set explicitly because during a WfSpec Version Migration, it is possible for different ThreadSpec's to have different WfSpec versions. |
number | | int32 | The number of the ThreadRun. This is an auto-incremented integer corresponding to the chronological ordering of when the ThreadRun's were created. If you have not configured any retention policy for the ThreadRun's (i.e. never clean them up), then this also corresponds to the position of the ThreadRun in the WfRun's thread_runs list. |
status | | LHStatus | The status of the ThreadRun. |
thread_spec_name | | string | The name of the ThreadSpec being run. |
start_time | | google.protobuf.Timestamp | The time the ThreadRun was started. |
end_time | optional | google.protobuf.Timestamp | The time the ThreadRun was completed or failed. Unset if still active. |
error_message | optional | string | Human-readable error message detailing what went wrong in the case of a failure. |
child_thread_ids | repeated | int32 | List of thread_run_number's for all child thread_runs. |
parent_thread_id | optional | int32 | Set for every ThreadRun except the ENTRYPOINT. This is the id of the parent thread. |
halt_reasons | repeated | ThreadHaltReason | If the ThreadRun is HALTED, this contains a list of every reason for which the ThreadRun is HALTED. Once every reason is "resolved" (and thus removed from the list), then the ThreadRun will return to the RUNNING state. |
interrupt_trigger_id | optional | ExternalEventId | If this ThreadRun is of type INTERRUPT_HANDLER, this field is set to the ID of the ExternalEvent that caused the Interrupt. |
failure_being_handled | optional | FailureBeingHandled | If this ThreadRun is of type FAILURE_HANDLER, this field is set to the exact Failure that is being handled by this ThreadRun. |
current_node_position | | int32 | This is the current position of the current NodeRun being run. This is an auto-incremented field that gets incremented every time we run a new NodeRun. |
handled_failed_children | repeated | int32 | List of every child ThreadRun which both a) failed, and b) was properly handled by a Failure Handler.
This is important because at the EXIT node, if a Child ThreadRun was discovered to have failed, then this ThreadRun (the parent) also fails with the same failure as the child. If, however, a Failure Handler had previously "handled" the Child Failure, that ThreadRun's number is appended to this list, and then the EXIT node ignores that ThreadRun. |
type | | ThreadType | The Type of this ThreadRun. |
Message WfRun
A WfRun is a running instance of a WfSpec.
Field | Label | Type | Description |
---|
id | | WfRunId | The ID of the WfRun. |
wf_spec_id | | WfSpecId | The ID of the WfSpec that this WfRun belongs to. |
old_wf_spec_versions | repeated | WfSpecId | When a WfRun is migrated from an old verison of a WfSpec to a newer one, we add the old WfSpecId to this list for historical auditing and debugging purposes. |
status | | LHStatus | The status of this WfRun. |
greatest_threadrun_number | | int32 | The ID number of the greatest ThreadRUn in this WfRun. The total number of ThreadRuns is given by greatest_thread_run_number + 1.
Introduced now since with ThreadRun-level retention, we can't rely upon thread_runs.size() to determine the number of ThreadRuns, as a ThreadRun is removed from the thread_runs list once its retention period expires. |
start_time | | google.protobuf.Timestamp | The time the WfRun was started. |
end_time | optional | google.protobuf.Timestamp | The time the WfRun failed or completed. |
thread_runs | repeated | ThreadRun | A list of all active ThreadRun's and terminated ThreadRun's whose retention periods have not yet expired. |
pending_interrupts | repeated | PendingInterrupt | A list of Interrupt events that will fire once their appropriate ThreadRun's finish halting. |
pending_failures | repeated | PendingFailureHandler | A list of pending failure handlers which will fire once their appropriate ThreadRun's finish halting. |
Message Edge
The Edge is the line in the workflow that connects one Node to another.
Field | Label | Type | Description |
---|
sink_node_name | | string | The name of the Node that the Edge points to. |
condition | optional | EdgeCondition | The Condition on which this Edge will be traversed. When choosing an Edge to travel after the completion of a NodeRun, the Edges are evaluated in order. The first one to either have no condition or have a condition which evaluates to true is taken. |
variable_mutations | repeated | VariableMutation | Ordered list of Variable Mutations to execute when traversing this Edge. |
Message EdgeCondition
This is a boolean expression used to evaluate whether an Edge is valid.
Message EntrypointNode
Defines the beginning of the ThreadRun execution.
Output is NULL
Message ExitNode
Defines the end of the ThreadRun execution.
Field | Label | Type | Description |
---|
failure_def | optional | FailureDef | If set, this ExitNode throws the specified Failure upon arrival. Note that Failures are propagated up to the parent ThreadRun (or cause the entire WfRun to fail if sent by the entrypoint ThreadRun).
If this is not set, then a ThreadRun arriving at this Exit Node will be COMPLETED. |
Message ExternalEventNode
An ExternalEventNode causes the WfRun to stop and wait for an ExternalEvent
to arrive before continuing onwards.
The output is just the content of the ExternalEvent.
Field | Label | Type | Description |
---|
external_event_def_id | | ExternalEventDefId | The ID of the ExternalEventDef that we are waiting for. |
timeout_seconds | | VariableAssignment | Determines the maximum amount of time that the NodeRun will wait for the ExternalEvent to arrive. |
Message FailureDef
Defines a Failure that can be thrown.
Field | Label | Type | Description |
---|
failure_name | | string | The code for the failure. If in UPPER_CASE, it must be one of the LHErrorType enums, and represents an ERROR. If it is in kebab-case, then it is a user-defined EXCEPTION. |
message | | string | Human-readable message denoting why the Failure occurred. |
content | optional | VariableAssignment | If specified, the thrown Failure will have this content. |
Message FailureHandlerDef
Specifies a Failure Handler which can run in case of a certain Failure to allow
the ThreadRun to run compensatory logic and gracefully continue rather than
failing immediately.
Field | Label | Type | Description |
---|
handler_spec_name | | string | The name of the ThreadSpec to run as a |
specific_failure | oneof failure_to_catch | string | Specifies that this FailureHandlerDef will be triggered for a Failure with this exact name.
If this and specific_failure are both unset, then any failure is caught. |
any_failure_of_type | oneof failure_to_catch | FailureHandlerDef.LHFailureType | Specifies that this FailureHandlerDef will be triggered for any failure matching this type (ERROR or EXCEPTION). |
Message InterruptDef
Defines an Interrupt for a ThreadSpec. An Interrupt means that when an ExternalEvent
of a certain type is registered to the WfRun, then the affected ThreadRun is HALTED
and a handler ThreadRun is run as an interrupt handler. The interrupted ThreadRun
is resumed once the interrupt handler completes.
Field | Label | Type | Description |
---|
external_event_def_id | | ExternalEventDefId | The ID of the ExternalEventDef which triggers an Interrupt for this ThreadSpec. Note that as of 0.9.0, you cannot use an ExternalEventDefId for both an InterruptDef and an ExternalEventNode in the same WfSpec. |
handler_spec_name | | string | The name of the ThreadSpec that we run as the interrupt handler. |
Message JsonIndex
Defines an index to make a JSON_OBJ or JSON_ARR variable searchable over a specific
JSON Path.
Field | Label | Type | Description |
---|
field_path | | string | Denotes the path in JSONPath format (according to the Java Jayway library) that has a field we should index. |
field_type | | VariableType | Is the type of the field we are indexing. |
Message Node
A Node is a step in a ThreadRun.
Field | Label | Type | Description |
---|
outgoing_edges | repeated | Edge | Defines the flow of execution and determines where the ThreadRun goes next. |
failure_handlers | repeated | FailureHandlerDef | Specifies handlers for failures (EXCEPTION or ERROR or both) which might be thrown by the NodeRun. If a Failure is thrown by the Node execution, then the first matching Failure Handler (if present) is run. If there is a matching Failure Handler and it runs to completion, then the ThreadRun advances from the Node; else, it fails. |
entrypoint | oneof node | EntrypointNode | Creates an EntrypointRun. Every ThreadRun has one Entrypoint node. |
exit | oneof node | ExitNode | Creates an `ExitRun``. Every ThreadSpec has at least one Exit Node. |
task | oneof node | TaskNode | Creates a TaskNodeRUn |
external_event | oneof node | ExternalEventNode | Creates an ExternalEventNodeRun |
start_thread | oneof node | StartThreadNode | Creates a StartThreadNodeRun |
wait_for_threads | oneof node | WaitForThreadsNode | Creates a WaitForThreadsNodeRun |
nop | oneof node | NopNode | Creates a NopNodeRun |
sleep | oneof node | SleepNode | Creates a SleepNodeRun |
user_task | oneof node | UserTaskNode | Creates a UserTaskNodeRun |
start_multiple_threads | oneof node | StartMultipleThreadsNode | Creates a StartMultipleThreadsNodeRun |
throw_event | oneof node | ThrowEventNode | Creates a ThrowEventNodeRun |
Message NodeMigration
EXPERIMENTAL: Specification for migrating a WfRun from a Node in one WfSpec
to a Node in another WfSpec version.
Field | Label | Type | Description |
---|
new_node_name | | string | The name of the Node on the new WfSpec to move to. |
Message NopNode
NOP node has no operations and is used for conditional branching.
Message SleepNode
Sleep Node causes the WfRun to wait a specified time and then resume.
There is no output.
Field | Label | Type | Description |
---|
raw_seconds | oneof sleep_length | VariableAssignment | Sleeps the specified number of seconds. |
timestamp | oneof sleep_length | VariableAssignment | Sleeps until the long timestamp (epoch millis) specified here. |
iso_date | oneof sleep_length | VariableAssignment | Sleeps until the ISO-formatted date specified here. |
Message StartMultipleThreadsNode
Iterates over a JSON_ARR and starts a Child ThreadRun for each element in the
list.
Returns a JSON_ARR containing the thread_run_number of each spawned child.
Field | Label | Type | Description |
---|
thread_spec_name | | string | The name of the ThreadSpec to spawn. |
variables | map | StartMultipleThreadsNode.VariablesEntry | Variables which are passed into the child ThreadRuns. These assignments are the same for all spawned threads. |
iterable | | VariableAssignment | Assignment that resolves to a JSON_ARR. For each element in the list, a child ThreadRun is started. The reserved INPUT variable for each Child is set to the corresponding item in the list. |
Message StartMultipleThreadsNode.VariablesEntry
Message StartThreadNode
Starts a Child ThreadRun with a specific ThreadSpec.
Field | Label | Type | Description |
---|
thread_spec_name | | string | The name of the ThreadSpec to spawn. |
variables | map | StartThreadNode.VariablesEntry | The input variables to pass into the Child ThreadRun. |
Message StartThreadNode.VariablesEntry
Message ThreadRetentionPolicy
ThreadRetentionPolicy specifies how long to keep record of a ThreadRun and its associated
NodeRun's and TaskRun's and Variables after the ThreadRun has been completed.
Field | Label | Type | Description |
---|
seconds_after_thread_termination | oneof thread_gc_policy | int64 | Delete associated ThreadRun's X seconds after they terminate, regardless of status. |
Message ThreadSpec
Defines a blueprint for a ThreadRun, which is a thread of execution inside a
WfRun.
Field | Label | Type | Description |
---|
nodes | map | ThreadSpec.NodesEntry | The Nodes inside this ThreadSpec. Maps from name to Node. |
variable_defs | repeated | ThreadVarDef | Defines Variables that are local to ThreadRun's of this ThreadSpec. |
interrupt_defs | repeated | InterruptDef | Defines all interrupts for this ThreadSpec. |
retention_policy | optional | ThreadRetentionPolicy | Optional retention policy to clean up ThreadRun's of this ThreadSpec after they have been completed. This is important for long-lived WfRun's that could have hundreds of ThreadRun's, because a ThreadRun has a record inside the WfRun itself. |
Message ThreadSpec.NodesEntry
Field | Label | Type | Description |
---|
key | | string | |
value | | Node | |
Message ThreadSpecMigration
EXPERIMENTAL: Specification for how to migrate a ThreadRun of a specific ThreadSpec
from one WfSpec to another WfSpec version.
Field | Label | Type | Description |
---|
new_thread_spec_name | | string | The name of the ThreadSpec in the new WfSpec that this ThreadSpec should migrate to. |
node_migrations | map | ThreadSpecMigration.NodeMigrationsEntry | Map from name of the nodes on the current ThreadSpec to the migration to perform on it to move it to a new WfSpec. |
Message ThreadSpecMigration.NodeMigrationsEntry
Message ThreadVarDef
Denotes a variable declaration at the ThreadSpec level.
Field | Label | Type | Description |
---|
var_def | | VariableDef | Is the actual VariableDefinition containing name and type. |
required | | bool | Whether the variable is required as input to the threadRun. |
searchable | | bool | Whether this variable has an index configured. |
json_indexes | repeated | JsonIndex | Valid for JSON_OBJ and JSON_ARR variables only. List of JSON fields to index. |
access_level | | WfRunVariableAccessLevel | The Access Level of this variable. |
Message ThrowEventNode
A SubNode that throws a WorkflowEvent of a specific type. There is no output.
Field | Label | Type | Description |
---|
event_def_id | | WorkflowEventDefId | The WorkflowEventDefId of the WorkflowEvent that is thrown |
content | | VariableAssignment | A VariableAssignment defining the content of the WorkflowEvent that is thrown |
Message UserTaskNode
The UserTaskNode creates a UserTaskRun, which is used to get input from a human
user into the workflow.
The output is a JSON_OBJ variable with one key/value pair for each UserTaskField.
Field | Label | Type | Description |
---|
user_task_def_name | | string | Denotes the name of the UserTaskDef that should create the UserTaskRun . |
user_group | optional | VariableAssignment | Denotes the user_group to which the UserTaskRun is assigned upon creation. |
user_id | optional | VariableAssignment | Denotes the user_id to which the UserTaskRun is assigned upon creation. |
actions | repeated | UTActionTrigger | Specifies a list of actions that happen on various time-based triggers. Actions include reassigning the UserTaskRun, cancelling the UserTaskRun, or executing a "reminder" TaskRun. |
user_task_def_version | optional | int32 | If set, then the UserTaskRun will always have this specific version of the UserTaskDef. Otherwise, the UserTaskRun will have the latest version. |
notes | optional | VariableAssignment | Specifies the value to be displayed on the notes field of the UserTaskRun. |
on_cancellation_exception_name | optional | VariableAssignment | Specifies the name of the exception thrown when the User Task is canceled. If not set, then the cancellation or timeout of a User Task Run throws an ERROR rather than an EXCEPTION. |
Message WaitForThreadsNode
Specifies that a ThreadRun will wait for certain specified Child ThreadRun's to
complete or fail before the WfRun continues. If one of the Child ThreadRun's
throws a Failure that is not caught by the per_thread_failure_handlers
,
then the Child ThreadRun's Failure is thrown by the WaitForThreadsRun.
No output.
Field | Label | Type | Description |
---|
threads | oneof threads_to_wait_for | WaitForThreadsNode.ThreadsToWaitFor | Specifies that the WaitForThreadsRun will wait for the threads specified here. |
thread_list | oneof threads_to_wait_for | VariableAssignment | Specifies that the WaitForThreadsRun will wait for a list of ThreadRun's contained in the JSON_ARR value specified here. Each element in the list must be an INT representing the number of a ThreadRun that we're waiting for. |
per_thread_failure_handlers | repeated | FailureHandlerDef | If any of the child ThreadRun's that we are waiting for throw a Failure, we will evaluate it against these FailureHandlerDef's and run the first matching FailureHandler (if any). The FailureHandler will be a child of the child, which means that it has access to all of the variables in the scope of the failed Child ThreadRun.
This is different from Node-level Failure Handlers, which would be siblings of the ThreadRuns that we're waiting for, and would run only when the overall nodeRun has failed. |
Message WaitForThreadsNode.ThreadToWaitFor
Field | Label | Type | Description |
---|
thread_run_number | | VariableAssignment | Causes the WaitForThreadsNodeRun to wait for the ThreadRun whose number matches the value specified here. Must resolve to an INT. |
Message WaitForThreadsNode.ThreadsToWaitFor
Message WfSpec
A WfSpec
defines the logic for a workflow in LittleHorse. It is a metadata object
and is a blueprint for a WfRun
execution.
Field | Label | Type | Description |
---|
id | | WfSpecId | The ID of the WfSpec . Note that this ID is versioned with both a major version and a minor revision. Creating new WfSpec's with the same name and different specifications results in a completely new WfSpec object whose id.name is the same but with different version. |
created_at | | google.protobuf.Timestamp | The timestamp at which the WfSpec was created. |
frozen_variables | repeated | ThreadVarDef | Variables whose types cannot be changed without causing a Breaking Change between the versions. |
status | | MetadataStatus | The Status of the WfSpec . Currently, only ACTIVE exists. This field will be used in the future when de-commissioning a WfSpec gracefully. |
thread_specs | map | WfSpec.ThreadSpecsEntry | The various ThreadSpec's in this WfSpec . Each ThreadSpec defines a blueprint for a parallel thread of execution (a ThreadRun ). They are referred to by their names. |
entrypoint_thread_name | | string | The name of the ENTRYPOINT ThreadSpec. The Entrypoint is the ThreadSpec for the Entrypoint ThreadRun, which is the ThreadRun that is created upon starting the WfRun . |
retention_policy | optional | WorkflowRetentionPolicy | Optional policy that configures cleaning up old WfRun 's after they are completed or failed. Recommended for production settings to avoid running out of disk space; unless you are using a WfRun as a data record, in which case the application should clean up WfRun 's as appropriate. |
migration | optional | WfSpecVersionMigration | EXPERIMENTAL: ongoing migration from one version of a WfSpec to another. |
parent_wf_spec | optional | WfSpec.ParentWfSpecReference | Reference to the parent WfSpec. If this is set, all WfRun's for this WfSpec must be the child of a WfRun belonging to the referenced WfSpec. |
Message WfSpec.ParentWfSpecReference
Reference to another WfSpec. If a WfSpec has a ParentWfSpecReference, then all
WfRun's for that WfSpec MUST be the child of a WfRun of the provided WfSpec; meaning
that the RunWf RPC must provide a parent_wf_run_id
that belongs to the specified
WfSpec.
Currently, only reference by names is supported.
Field | Label | Type | Description |
---|
wf_spec_name | | string | Name of the Parent WfSpec |
wf_spec_major_version | | int32 | FOR NOW: no validation of variables on parent. In the future we will pass wf_spec_major_version, but we should probably examine the rules for evolution in the future. |
Message WfSpec.ThreadSpecsEntry
Message WfSpecVersionMigration
EXPERIMENTAL: Specification for how to migrate an in-flight WfRun from one WfSpec
to another WfSpec version.
Field | Label | Type | Description |
---|
new_major_version | | int32 | The major version of the WfSpec that we are migrating to. |
new_revision | | int32 | The revision of the WfSpec that we are migrating to. |
thread_spec_migrations | map | WfSpecVersionMigration.ThreadSpecMigrationsEntry | Map from ThreadSpec name to a specifier determining how to migrate ThreadRun's to the new version of the WfSpec. |
Message WfSpecVersionMigration.ThreadSpecMigrationsEntry
Message WorkflowRetentionPolicy
A WorkflowRetentionPolicy configures how long a WfRun is retained in the data store before
being deleted after it is completed or failed.
Field | Label | Type | Description |
---|
seconds_after_wf_termination | oneof wf_gc_policy | int64 | Delete all WfRun's X seconds after they terminate, regardless of status. |
Message WorkflowEvent
A WorkflowEvent represents a "Thing That Happened" INSIDE a WfRun. It is DIFFERENT from
an ExternalEvent, because an ExternalEvent represents something that happened OUTSIDE the WfRun,
and is used to send information to the WfRun.
In contrast, a WorkflowEvent is thrown by the WfRun and is used to send information to the outside
world.
Field | Label | Type | Description |
---|
id | | WorkflowEventId | The ID of the WorkflowEvent. Contains WfRunId and WorkflowEventDefId. |
content | | VariableValue | The content of the WorkflowEvent. |
created_at | | google.protobuf.Timestamp | The time that the WorkflowEvent was created. |
Message WorkflowEventDef
LittleHorse Enums
This section contains the enums defined by the LittleHorse API.
Enum ACLAction
Describes an Action that can be taken over a specific set of resources.
Name | Number | Description |
---|
READ | 0 | Allows all RPC's that start with Get , List , and Search in relation to the metadata (eg. TaskDef for ACL_TASK ) or run data (eg. TaskRun for ACL_TASK ) |
RUN | 1 | Allows RPC's that are needed for mutating the runs of the resource. For example, RUN over ACL_TASK allows the ReportTask and PollTask RPC's, and RUN over ACL_WORKFLOW allows the RunWf , DeleteWfRun , StopWfRun , and ResumeWfRun RPC's. |
WRITE_METADATA | 2 | Allows mutating metadata. For example, WRITE_METADATA over ACL_WORKFLOW allows mutating WfSpec s, and WRITE_METADATA over ACL_TASK allows mutating TaskDef s. |
ALL_ACTIONS | 3 | Allows all actions related to a resource. |
Enum ACLResource
Defines a resource type for ACL's.
Name | Number | Description |
---|
ACL_WORKFLOW | 0 | Refers to WfSpec and WfRun |
ACL_TASK | 1 | Refers to TaskDef and TaskRun |
ACL_EXTERNAL_EVENT | 2 | Refers to ExternalEventDef and ExternalEvent |
ACL_USER_TASK | 3 | Refers to UserTaskDef and UserTaskRun |
ACL_PRINCIPAL | 4 | Refers to the Principal resource. Currently, the ACL_PRINCIPAL permission is only valid in the global_acls field of the Principal . A Principal who only has access to a specific Tenant cannot create othe Principals because a Principal is scoped to the Cluster, and not to a Tenant. |
ACL_TENANT | 5 | Refers to the Tenant resource. The ACL_TENANT permission is only valid in the global_acls field of the Principal . This is because the Tenant resource is cluste-rscoped. |
ACL_ALL_RESOURCES | 6 | Refers to all resources. In the global_acls field, this includes Principal and Tenant resources. In the per_tenant_acls field, this does not include Principal and Tenant since those are cluster-scoped resources. |
ACL_TASK_WORKER_GROUP | 7 | Refers to the TaskWorkerGroup associated with a TaskDef |
Enum LHErrorType
This enum is all of the types of technical failure that can occur in a WfRun.
Name | Number | Description |
---|
CHILD_FAILURE | 0 | A child ThreadRun failed with a technical ERROR. |
VAR_SUB_ERROR | 1 | Failed substituting input variables into a NodeRun. |
VAR_MUTATION_ERROR | 2 | Failed mutating variables after a NodeRun successfully completed. |
USER_TASK_CANCELLED | 3 | A UserTaskRun was cancelled (EVOLVING: this will become a Business EXCEPTION) |
TIMEOUT | 4 | A NodeRun failed due to a timeout. |
TASK_FAILURE | 5 | A TaskRun failed due to an unexpected error. |
VAR_ERROR | 6 | Wrapper for VAR_SUB_ERROR and VAR_MUTATION_ERROR |
TASK_ERROR | 7 | Wrapper for TASK_FALIURE and TIMEOUT |
INTERNAL_ERROR | 8 | An unexpected LittleHorse Internal error occurred. This is not expected to happen. |
Enum LHStatus
Status used for WfRun, ThreadRun, and NodeRun
Name | Number | Description |
---|
STARTING | 0 | The entity is starting. |
RUNNING | 1 | The entity is running. |
COMPLETED | 2 | The entity is completed. This is a terminal state. |
HALTING | 3 | The entity will move to HALTED as soon as all preconditions for halting are satisfied. |
HALTED | 4 | The entity is halted, either by user intervention or by the workflow scheduler. |
ERROR | 5 | The entity has failed due to a technical failure, such as a type conversion error, a task timeout due to network failure, or a task worker crash. |
EXCEPTION | 6 | The entity has failed due to a business exception defined by the user. |
Status of a Metadata Object, such as WfSpec or TaskDef
Name | Number | Description |
---|
ACTIVE | 0 | ACTIVE means the object can be used. |
ARCHIVED | 1 | An ARCHIVED WfSpec can no longer be used to create new WfRun's, but existing WfRun's will be allowed to run to completion. |
TERMINATING | 2 | A TERMINATING WfSpec is actively deleting all running WfRun's, and will self-destruct once all of its child WfRun's are terminated. |
Enum MetricsWindowLength
Metrics
Name | Number | Description |
---|
MINUTES_5 | 0 | |
HOURS_2 | 1 | |
DAYS_1 | 2 | |
Enum TaskStatus
Status of a TaskRun.
Name | Number | Description |
---|
TASK_SCHEDULED | 0 | Scheduled in the Task Queue but not yet picked up by a Task Worker. |
TASK_RUNNING | 1 | Picked up by a Task Worker, but not yet reported or timed out. |
TASK_SUCCESS | 2 | Successfully completed. |
TASK_FAILED | 3 | Task Worker reported a technical failure while attempting to execute the TaskRun |
TASK_TIMEOUT | 4 | Task Worker did not report a result in time. |
TASK_OUTPUT_SERIALIZING_ERROR | 5 | Task Worker reported that it was unable to serialize the output of the TaskRun. |
TASK_INPUT_VAR_SUB_ERROR | 6 | Task Worker was unable to deserialize the input variables into appropriate language-specific objects to pass into the Task Function |
TASK_EXCEPTION | 8 | Task Function business logic determined that there was a business exception. |
TASK_PENDING | 9 | Refers to a TaskAttempt that is not yet scheduled. This happens when using retries with an ExponentialBackoffRetryPolicy: the TaskAttempt isn't supposed to be scheduled until it "matures", but it does already exist. |
Enum VariableType
Type of a Varaible in LittleHorse. Corresponds to the possible value type's of a
VariableValue.
Name | Number | Description |
---|
JSON_OBJ | 0 | An object represented as a json string.
|
The JSON_OBJ
variable allows you to store complex objects in the JSON format. When using the Java and GoLang SDK's, the JSON_OBJ
variable type is often used transparently to the user. For example, the Java Task Worker SDK can inspect your method signature and automatically deserialize an input variable into a POJO. |
| JSON_ARR | 1 | The JSON_ARR
variable allows you to store collections of objects as a JSON array. The behavior is similar to the JSON_OBJ
variable type. |
| DOUBLE | 2 | The DOUBLE
variable type is a 64-bit floating point number. It can be cast to an INT
. |
| BOOL | 3 | Boolean denotes a simple boolean switch. |
| STR | 4 | The STR
variable type is stored as a String. INT
, DOUBLE
, and BOOL
variables can be cast to a STR
. |
| INT | 5 | The INT
variable type is stored as a 64-bit integer. The INT
can be cast to a DOUBLE
. |
| BYTES | 6 | The BYTES
variable type allows you to store an arbitrary byte string. |
Enum Comparator
Operator for comparing two values to create a boolean expression.
Name | Number | Description |
---|
LESS_THAN | 0 | Equivalent to < . Only valid for primitive types (no JSON_OBJ or JSON_ARR). |
GREATER_THAN | 1 | Equivalent to > . Only valid for primitive types (no JSON_OBJ or JSON_ARR). |
LESS_THAN_EQ | 2 | Equivalent to <= . Only valid for primitive types (no JSON_OBJ or JSON_ARR). |
GREATER_THAN_EQ | 3 | Equivalent to >= . Only valid for primitive types (no JSON_OBJ or JSON_ARR). |
EQUALS | 4 | This is valid for any variable type, and is similar to .equals() in Java. |
One note: if the RHS is a different type from the LHS, then LittleHorse will try to cast the RHS to the same type as the LHS. If the cast fails, then the ThreadRun fails with a VAR_SUB_ERROR. |
| NOT_EQUALS | 5 | This is the inverse of EQUALS
|
| IN | 6 | Only valid if the RHS is a JSON_OBJ or JSON_ARR. Valid for any type on the LHS.
For the JSON_OBJ type, this returns true if the LHS is equal to a KEY in the RHS. For the JSON_ARR type, it returns true if one of the elements of the RHS is equal to the LHS. |
| NOT_IN | 7 | The inverse of IN. |
Enum UTActionTrigger.UTHook
Enumerates the different lifecycle hooks that can cause the timer to start running.
Name | Number | Description |
---|
ON_ARRIVAL | 0 | The hook should be scheduled delay_seconds after the UserTaskRun is created. This hook only causes the action to be scheduled once. |
ON_TASK_ASSIGNED | 1 | The hook should be scheduled delay_seconds after the ownership of the UserTaskRun changes. This hook causes the Action to be scheduled one or more times. The first time is scheduled when the UserTaskRun is created, since we treat the change from "UserTaskRun is nonexistent" to "UserTaskRun is owned by a userId or userGroup" as a change in ownership. |
Enum VariableMutationType
Enumerates the available operations to mutate a variable in a WfRun.
Name | Number | Description |
---|
ASSIGN | 0 | Set the variable specified by the LHS to the value of the RHS. |
ADD | 1 | Add the RHS to the LHS. |
EXTEND | 2 | Append the RHS to the LHS (valid if the LHS is a STR or JSON_ARR) |
SUBTRACT | 3 | Subtract the RHS from the LHS (both must be INT or DOUBLE) |
MULTIPLY | 4 | Multiply the LHS by the RHS (both must be INT or DOUBLE) |
DIVIDE | 5 | Divide the LHS by the RHS (both must be INT or DOUBLE) |
REMOVE_IF_PRESENT | 6 | Remove any occurrences of RHS from LHS (LHS must be JSON_ARR) |
REMOVE_INDEX | 7 | Remove item at index RHS from LHS (LHS must be JSON_ARR) |
REMOVE_KEY | 8 | Remove the key specified by RHS from the LHS (LHS must be JSON_OBJ) |
Enum WaitForThreadsRun.WaitingThreadStatus
The status of a single ThreadRun that we are waiting for.
Name | Number | Description |
---|
THREAD_IN_PROGRESS | 0 | The ThreadRun is in progress (i.e. not COMPLETED nor EXCEPTION nor ERROR) |
THREAD_HANDLING_FAILURE | 1 | The ThreadRun failed with some failure, and the FailureHandler is running for that Failure. |
THREAD_COMPLETED_OR_FAILURE_HANDLED | 2 | We can mark this ThreadRun as "already waited for", meaning that either: 1. It completed successfully, OR 2. It failed, and the Failure Handler successfully completed |
THREAD_UNSUCCESSFUL | 3 | The ThreadRun did not complete successfully, and there wasn't a successful run of a Failure Handler for the Failure that was thrown. |
Enum AllowedUpdateType
This enum controls the behavior of a PutWfSpecRequest when a WfSpec with the same
name previously exists.
Name | Number | Description |
---|
ALL_UPDATES | 0 | Allows any update: both minor (revsion) changes and breaking (majorVersion) changes are accepted |
MINOR_REVISION_UPDATES | 1 | Allows only backwards-compatible changes that do not change the required input variables or the searchable variables in the WfSpec. |
NO_UPDATES | 2 | Rejects any changes to the WfSpec. |
Enum SearchNodeRunRequest.NodeType
This enum denotes the type of a NodeRun.
Name | Number | Description |
---|
TASK | 0 | TASK node schedules a TaskRun |
EXTERNAL_EVENT | 1 | EXTERNAL_EVENT blocks the ThreadRun until a specified ExternalEvent arrives |
ENTRYPOINT | 2 | ENTRYPOINT kicks off a ThreadRun |
EXIT | 3 | EXIT completes a ThreadRun |
START_THREAD | 4 | START_THREAD creates a Child ThreadRun |
WAIT_THREADS | 5 | WAIT_THREADS waits for one or more child ThreadRuns to complete |
SLEEP | 6 | SLEEP makes the ThreadRun sleep for a specified time |
USER_TASK | 7 | USER_TASK creates a UserTaskRun and blocks until the UserTaskRun is completed. |
START_MULTIPLE_THREADS | 8 | START_MULTIPLE_THREADS iterates over a list and starts a Child Thread for each item |
Enum SaveUserTaskRunProgressRequest.SaveUserTaskRunAssignmentPolicy
Configures how to handle UserTaskRun
ownership when saving it.
Name | Number | Description |
---|
FAIL_IF_CLAIMED_BY_OTHER | 0 | If the UserTaskRun is already assigned to a user_id, then the request throws a FAILED_PRECONDITION error. |
IGNORE_CLAIM | 1 | If the UserTaskRun is already assigned to a user_id, then the request will leave the UserTaskRun assigned to the current user but still update the results and log in the events who updated the results. |
Enum UserTaskRunStatus
The status that a UserTaskRun can be in.
Name | Number | Description |
---|
UNASSIGNED | 0 | Not assigned to a specific user yet. |
ASSIGNED | 1 | Assigned to a specific user, but not completed or cancelled yet. |
DONE | 3 | Done. |
CANCELLED | 4 | Cancelled. |
Enum ThreadType
The type of a ThreadRUn.
Name | Number | Description |
---|
ENTRYPOINT | 0 | The ENTRYPOINT ThreadRun. Exactly one per WfRun. Always has number == 0. |
CHILD | 1 | A ThreadRun explicitly created by another ThreadRun via a START_THREAD or START_MULTIPLE_THREADS NodeRun. |
INTERRUPT | 2 | A ThreadRun that was created to handle an Interrupt. |
FAILURE_HANDLER | 3 | A ThreadRun that was created to handle a Failure. |
Enum FailureHandlerDef.LHFailureType
Specifies a type of Failure
Name | Number | Description |
---|
FAILURE_TYPE_ERROR | 0 | FAILURE_TYPE_ERROR specifies any technical ERROR . |
FAILURE_TYPE_EXCEPTION | 1 | Specifies a user-defined, business-related EXCEPTION . |
Enum WfRunVariableAccessLevel
Determines the Access Level for a Variable in a ThreadSpec/WfSpec.
Name | Number | Description |
---|
PUBLIC_VAR | 0 | A PUBLIC_VAR can be accessed (read + mutated) by child WfRun 's. |
PRIVATE_VAR | 1 | A PRIVATE_VAR cannot be accessed by a child WfRun . |
INHERITED_VAR | 2 | An INHERITED_VAR is inherited from the parent WfRun . Only valid in a WfSpec that has a parent. Also can only be declared in the Entrypoint Thread. |