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:

1. Developing a Task Worker, which is handled by our Task Worker SDK's.
2. Developing a WfSpec, which is handled by our WfSpec SDK's.
3. 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

Request Type	Response Type	Description
PutTaskDefRequest	TaskDef	Creates a TaskDef.

RPC GetTaskDef

Request Type	Response Type	Description
TaskDefId	TaskDef	Gets a TaskDef.

RPC GetTaskWorkerGroup

Request Type	Response Type	Description
TaskDefId	TaskWorkerGroup	Gets the registered task worker group associated with a specific TaskDef.

RPC PutExternalEventDef

Request Type	Response Type	Description
PutExternalEventDefRequest	ExternalEventDef	Creates an ExternalEventDef.

RPC GetExternalEventDef

Request Type	Response Type	Description
ExternalEventDefId	ExternalEventDef	Gets an ExternalEventDef.

RPC PutWorkflowEventDef

Request Type	Response Type	Description
PutWorkflowEventDefRequest	WorkflowEventDef	EXPERIMENTAL: Creates a WorkflowEventDef.

RPC PutWfSpec

Request Type	Response Type	Description
PutWfSpecRequest	WfSpec	Creates a WfSpec.

RPC GetWfSpec

Request Type	Response Type	Description
WfSpecId	WfSpec	Gets a WfSpec.

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

Request Type	Response Type	Description
PutUserTaskDefRequest	UserTaskDef	Creates a UserTaskDef.

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

Request Type	Response Type	Description
GetLatestUserTaskDefRequest	UserTaskDef	Returns the most recent UserTaskDef with a specific name.

RPC RunWf

Request Type	Response Type	Description
RunWfRequest	WfRun	Runs a WfSpec to create a WfRun.

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 ListUserTaskRuns

Request Type	Response Type	Description
ListUserTaskRunRequest	UserTaskRunList	Lists all UserTaskRun's for a specific WfRun. Can be useful when using a WfRun to model an entity.

RPC GetNodeRun

Request Type	Response Type	Description
NodeRunId	NodeRun	Gets a specific NodeRun.

RPC ListNodeRuns

Request Type	Response Type	Description
ListNodeRunsRequest	NodeRunList	Lists all NodeRun's for a specific WfRun.

RPC GetTaskRun

Request Type	Response Type	Description
TaskRunId	TaskRun	Gets a specific TaskRun.

RPC ListTaskRuns

Request Type	Response Type	Description
ListTaskRunsRequest	TaskRunList	Lists all TaskRun's for a specific WfRun.

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

Request Type	Response Type	Description
ListVariablesRequest	VariableList	List all Variables from a WfRun.

RPC PutExternalEvent

Request Type	Response Type	Description
PutExternalEventRequest	ExternalEvent	Post an ExternalEvent. This RPC is highly useful for

RPC GetExternalEvent

Request Type	Response Type	Description
ExternalEventId	ExternalEvent	Get a specific ExternalEvent.

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

Request Type	Response Type	Description
ListExternalEventsRequest	ExternalEventList	List ExternalEvent's for a specific WfRun.

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

Request Type	Response Type	Description
SearchTaskRunRequest	TaskRunIdList	Search for TaskRun's. This RPC is useful for finding bugs in your Task Workers.

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

Request Type	Response Type	Description
SearchExternalEventRequest	ExternalEventIdList	Search for ExternalEvent's.

RPC SearchTaskDef

Request Type	Response Type	Description
SearchTaskDefRequest	TaskDefIdList	Search for TaskDef's.

RPC SearchUserTaskDef

Request Type	Response Type	Description
SearchUserTaskDefRequest	UserTaskDefIdList	Search for UserTaskDef's.

RPC SearchWfSpec

Request Type	Response Type	Description
SearchWfSpecRequest	WfSpecIdList	Search for WfSpec's.

RPC SearchExternalEventDef

Request Type	Response Type	Description
SearchExternalEventDefRequest	ExternalEventDefIdList	Search for ExternalEventDef's.

RPC SearchTenant

Request Type	Response Type	Description
SearchTenantRequest	TenantIdList	Search for all available TenantIds for current Principal

RPC SearchPrincipal

Request Type	Response Type	Description
SearchPrincipalRequest	PrincipalIdList

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 ThreadRuns - 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

Request Type	Response Type	Description
DeleteTaskDefRequest	.google.protobuf.Empty	Deletes a TaskDef.

RPC DeleteWfSpec

Request Type	Response Type	Description
DeleteWfSpecRequest	.google.protobuf.Empty	Deletes a WfSpec.

RPC DeleteUserTaskDef

Request Type	Response Type	Description
DeleteUserTaskDefRequest	.google.protobuf.Empty	Deletes a UserTaskDef.

RPC DeleteExternalEventDef

Request Type	Response Type	Description
DeleteExternalEventDefRequest	.google.protobuf.Empty	Deletes an ExternalEventDef.

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 GetTaskDefMetricsWindow

Request Type	Response Type	Description
TaskDefMetricsQueryRequest	TaskDefMetrics	Returns TaskDef Metrics for a specific TaskDef and a specific time window.

RPC GetWfSpecMetricsWindow

Request Type	Response Type	Description
WfSpecMetricsQueryRequest	WfSpecMetrics	Returns WfSpec Metrics for a specific WfSpec and a specific time window.

RPC ListTaskDefMetrics

Request Type	Response Type	Description
ListTaskMetricsRequest	ListTaskMetricsResponse	Returns a list of TaskDef Metrics Windows.

RPC ListWfSpecMetrics

Request Type	Response Type	Description
ListWfMetricsRequest	ListWfMetricsResponse	Returns a list of WfSpec Metrics Windows.

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

Request Type	Response Type	Description
PutPrincipalRequest	Principal	EXPERIMENTAL: Creates an Principal.

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

Field	Label	Type	Description
key		string
value		ServerACLs

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

Field	Label	Type	Description
key		string
value		ServerACLs

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

Field	Label	Type	Description
task	oneof action	UTActionTrigger.UTATask
cancel	oneof action	UTActionTrigger.UTACancel
reassign	oneof action	UTActionTrigger.UTAReassign	later on, might enable scheduling entire ThreadRuns
delay_seconds		VariableAssignment	The Action is triggered some time after the Hook matures. The delay is controlled by this field.
hook		UTActionTrigger.UTHook	The hook on which this UserTaskAction is scheduled.

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

Message VariableAssignment.FormatString

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.

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 ExternalEvents.

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 ExternalEventRun

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	ExternalEventRun	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

Field	Label	Type	Description
workflow_event_id		WorkflowEventId

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.

Field	Label	Type	Description
threads	repeated	WaitForThreadsRun.WaitForThread	The threads that are being waited for.

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 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 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

Field	Label	Type	Description
id		ExternalEventDefId	The ID of the ExternalEventDef to delete.

Message DeleteExternalEventRequest

Deletes an ExternalEvent.

Field	Label	Type	Description
id		ExternalEventId	The ID of the ExternalEvent to delete.

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.

Field	Label	Type	Description
old_wf_spec		WfSpecId
migration		WfSpecVersionMigration

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 ExternalEvents.

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.

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

Field	Label	Type	Description
key		string
value		ThreadSpec

Message PutWorkflowEventDefRequest

EXPERIMENTAL: Creates a WorkflowEventDef

Field	Label	Type	Description
name		string
type		VariableType

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.
listener_name		string	The listener that the worker is polling on. Used by the server to determine which advertised hosts to return.

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 ThreadRuns - 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

Field	Label	Type	Description
key		string
value		VariableValue

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 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 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

Field	Label	Type	Description
key		string
value		TaskWorkerMetadata

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

Message TaskWorkerMetadata

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.

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.

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.

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

Field	Label	Type	Description
key		string
value		VariableValue

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.

Field	Label	Type	Description
time		google.protobuf.Timestamp	the time the event occurred.
task_executed	oneof event	UserTaskEvent.UTETaskExecuted	Denotes that a TaskRun was scheduled via a trigger.
assigned	oneof event	UserTaskEvent.UTEAssigned	Denotes that the UserTaskRun was assigned.
cancelled	oneof event	UserTaskEvent.UTECancelled	Denotes that the UserTaskRun was cancelled. TODO: Add "save user task" and "complete user task" to the audit log

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.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

Field	Label	Type	Description
key		string
value		VariableValue

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.

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	A 64-bit integer.
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.

Field	Label	Type	Description
parent_halted	oneof reason	ParentHalted	Parent threadRun halted.
interrupted	oneof reason	Interrupted	Handling an Interrupt.
pending_interrupt	oneof reason	PendingInterruptHaltReason	Waiting to handle Interrupt.
pending_failure	oneof reason	PendingFailureHandlerHaltReason	Waiting to handle a failure.
handling_failure	oneof reason	HandlingFailureHaltReason	Handling a failure.
manual_halt	oneof reason	ManualHalt	Manually stopped the WfRun.

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.

Field	Label	Type	Description
comparator		Comparator	The Operator used to evaluate the left versus the right.
left		VariableAssignment	The left side of the boolean expression.
right		VariableAssignment	The right side of the Boolean Expression.

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 ExternalEventRun
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

Field	Label	Type	Description
key		string
value		VariableAssignment

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

Field	Label	Type	Description
key		string
value		VariableAssignment

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

Field	Label	Type	Description
key		string
value		NodeMigration

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

Field	Label	Type	Description
threads	repeated	WaitForThreadsNode.ThreadToWaitFor	Wait for one or more ThreadRun's

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

Field	Label	Type	Description
key		string
value		ThreadSpec

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

Field	Label	Type	Description
key		string
value		ThreadSpecMigration

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

Field	Label	Type	Description
id		WorkflowEventDefId
created_at		google.protobuf.Timestamp
type		VariableType

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 WfSpecs, and WRITE_METADATA over ACL_TASK allows mutating TaskDefs.
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
RUNNING	1
COMPLETED	2
HALTING	3
HALTED	4
ERROR	5
EXCEPTION	6

Enum MetadataStatus

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.
JSON_ARR	1	A list represented as a json array string.
DOUBLE	2	A 64-bit floating point number.
BOOL	3	A boolean
STR	4	A string
INT	5	A 64-bit integer
BYTES	6	A byte array

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 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.