LittleHorse API Reference

The LittleHorse Server exposes a GRPC API to its clients. For most general usage of LittleHorse, you will not need to read the raw protobuf schema. Common LittleHorse client actions fall into three general categories:

Developing a Task Worker, which is handled by our Task Worker SDK's.
Developing a WfSpec, which is handled by our WfSpec SDK's.
Running and interacting with WfRun's, which is documented in our "Using the API" docs.

However, the highly curious reader might want to see the actual GRPC and Protobuf specification. The docs on this page are autogenerated from our actual protobuf files.

The documentation of what the specific protobuf fields mean is potentially useful for advanced Jedi Master use-cases.

Happy Reading!

LittleHorse GRPC API

The LittleHorse GRPC API is the backbone of the clients that you get in all of our SDK's. Every LHConfig object gives you a GRPC stub to access the API. Most common operations are already documented with code examples in different languages here, but we put this here for the true Jedi Masters.

RPC `PutTaskDef`

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

Request Type	Response Type	Description
ScheduleWfRequest	ScheduledWfRun	Schedule repeated WfRun based on a cron expression

RPC `SearchScheduledWfRun`

Request Type	Response Type	Description
SearchScheduledWfRunRequest	ScheduledWfRunIdList	Search for existing schedules

RPC `GetScheduledWfRun`

Request Type	Response Type	Description
ScheduledWfRunId	ScheduledWfRun	Find a specific ScheduledWfRun

RPC `GetWfRun`

Request Type	Response Type	Description
WfRunId	WfRun	Gets a WfRun. Although useful for development and debugging, this RPC is not often used by applications.

RPC `GetUserTaskRun`

Request Type	Response Type	Description
UserTaskRunId	UserTaskRun	Loads a specific UserTaskRun. It includes information about to whom the UserTask is currently assigned, history of assignments and reassignments, and any context for that UserTaskRun which is specific to the WfRun.

RPC `AssignUserTaskRun`

Request Type	Response Type	Description
AssignUserTaskRunRequest	.google.protobuf.Empty	Change the ownership of a UserTaskRun to a new userId, userGroup, or both. The action will be reflected in your next call to SearchUserTaskRun. This RPC is useful for applications that are using User Tasks to build an internal task-list and wish to administer the tasks.

RPC `CompleteUserTaskRun`

Request Type	Response Type	Description
CompleteUserTaskRunRequest	.google.protobuf.Empty	Completes a UserTaskRun. Includes the results of the UserTaskRun, the UserTaskRun Id, and the userId of the user who completes the UserTaskRun. Results in the UserTask NodeRun being completed, and unblocks the associated ThreadRun in the WfRun. This RPC is highly useful for applications built around a WfSpec that uses USER_TASK nodes.

RPC `CancelUserTaskRun`

Request Type	Response Type	Description
CancelUserTaskRunRequest	.google.protobuf.Empty	Cancels a UserTaskRun. This will result in an EXCEPTION being propagated to the WfRun.

RPC `SaveUserTaskRunProgress`

Request Type	Response Type	Description
SaveUserTaskRunProgressRequest	UserTaskRun	Saves the results of a UserTaskRun and logs who saved the content. Throws FAILED_PRECONDITION if the UserTaskRun is in the `DONE` or `CANCELLED` state. If `policy` is set to `FAIL_IF_CLAIMED_BY_OTHER`, returns `FAILED_PRECONDITION` if the `user_id` field of the `UserTaskRun` does not match the `user_id` of the request.

RPC `ListUserTaskRuns`

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

Request Type	Response Type	Description
WorkflowEventDefId	WorkflowEventDef	Get a specific WorkflowEventDef.

RPC `GetWorkflowEvent`

Request Type	Response Type	Description
WorkflowEventId	WorkflowEvent	Get a specific WorkflowEvent.

RPC `ListExternalEvents`

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

RPC `ListWorkflowEvents`

Request Type	Response Type	Description
ListWorkflowEventsRequest	WorkflowEventList	List WorkflowEvent'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 `SearchWorkflowEvent`

Request Type	Response Type	Description
SearchWorkflowEventRequest	WorkflowEventIdList	Search for WorkflowEvents'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 `SearchWorkflowEventDef`

Request Type	Response Type	Description
SearchWorkflowEventDefRequest	WorkflowEventDefIdList	Search for WorkflowEventDef'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` `ThreadRun`s - The parent `ThreadRun`, or any parent of the parent, has not handled the `Failure` yet. If that is not true, then the `ThreadRun` cannot be rescued and the request will return `FAILED_PRECONDITION`.

RPC `DeleteWfRun`

Request Type	Response Type	Description
DeleteWfRunRequest	.google.protobuf.Empty	Deletes a WfRun. The WfRun cannot be in the RUNNING state.

RPC `DeleteTaskDef`

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

Request Type	Response Type	Description
DeleteWorkflowEventDefRequest	.google.protobuf.Empty

RPC `DeletePrincipal`

Request Type	Response Type	Description
DeletePrincipalRequest	.google.protobuf.Empty	Deletes a `Principal`. Fails with `FAILED_PRECONDITION` if the specified `Principal` is the last remaining `Principal` with admin permissions. Admin permissions are defined as having the `global_acls` of `ALL_ACTIONS` over the `ACL_ALL_RESOURCES` scope.

RPC `DeleteScheduledWfRun`

Request Type	Response Type	Description
DeleteScheduledWfRunRequest	.google.protobuf.Empty	Deletes a scheduled run and prevents any further associated WfRun from being executed.

RPC `GetTaskDefMetricsWindow`

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

Request Type	Response Type	Description
PrincipalId	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	ServerVersion	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	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
`node_output`	oneof `source`	VariableAssignment.NodeOutputReference	Assign the value of a NodeOutput.
`expression`	oneof `source`	VariableAssignment.Expression	Assign the value of an Expression.

Message `VariableAssignment.Expression`

An Expression allows you to combine multiple values into one.

Field	Type	Description
`lhs`	VariableAssignment	The left-hand-side of the expression.
`operation`	VariableMutationType	The operator in the expression.
`rhs`	VariableAssignment	The right-hand-side of the expression.

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 `VariableAssignment.NodeOutputReference`

A NodeOutputReference allows you to assign a value by getting the output of a NodeRun from a specified Node. If there are multiple NodeRun's of the specified Node (for example, if there is a loop in the ThreadSpec), then the most recent NodeRun is used. Can only specify a Node that is in the same ThreadSpec.

Field	Label	Type	Description
`node_name`		string	The name of the Node to pull output from.

Message `VariableDef`

Declares a Variable.

Field	Label	Type	Description
`type`		VariableType	The Type of the variable.
`name`		string	The name of the variable.
`default_value`	optional	VariableValue	Optional default value if the variable isn't set; for example, in a ThreadRun if you start a ThreadRun or WfRun without passing a variable in, then this is used.
`masked_value`		bool	If true, the variable value will show as a masked string.

Message `VariableMutation`

A VariableMutation defines a modification made to one of a ThreadRun's variables. The LHS determines the variable that is modified; the operation determines how it is modified, and the RHS is the input to the operation.

Day-to-day users of LittleHorse generally don't interact with this structure unless they are writing their own WfSpec SDK.

Field	Label	Type	Description
`lhs_name`		string	The name of the variable to mutate
`lhs_json_path`	optional	string	For JSON_ARR and JSON_OBJ variables, this allows you to optionally mutate a specific sub-field of the variable.
`operation`		VariableMutationType	Defines the operation that we are executing.
`rhs_assignment`	oneof `rhs_value`	VariableAssignment	Assigns the value to be used as the RHS of the mutation.
`literal_value`	oneof `rhs_value`	VariableValue	Use a literal value as the RHS. DEPRECATED: use rhs_assignment.literal_value instead.
`node_output`	oneof `rhs_value`	VariableMutation.NodeOutputSource	Use the output of the current node as the RHS. DEPRECATED: use rhs_assignment.node_output instead.

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

The sub-node structure for an EXTERNAL_EVENT NodeRun.

Field	Label	Type	Description
`external_event_def_id`		ExternalEventDefId	The ExternalEventDefId that we are waiting for.
`event_time`	optional	google.protobuf.Timestamp	The time that the ExternalEvent arrived. Unset if still waiting.
`external_event_id`	optional	ExternalEventId	The ExternalEventId of the ExternalEvent. Unset if still waiting.
`timed_out`		bool	Whether we had a timeout while waiting for the ExternalEvent to come.

Message `Failure`

Denotes a failure that happened during execution of a NodeRun or the outgoing edges.

Field	Label	Type	Description
`failure_name`		string	The name of the failure. LittleHorse has certain built-in failures, all named in UPPER_UNDERSCORE_CASE. Such failures correspond with the `LHStatus.ERROR`. Any Failure named in `kebab-case` is a user-defined business `EXCEPTION`, treated as an `LHStatus.EXCEPTION`.
`message`		string	The human-readable message associated with this Failure.
`content`	optional	VariableValue	A user-defined Failure can have a value; for example, in Java an Exception is an Object with arbitrary properties and behaviors. Future versions of LH will allow FailureHandler threads to accept that value as an input variable.
`was_properly_handled`		bool	A boolean denoting whether a Failure Handler ThreadRun properly handled the Failure.
`failure_handler_threadrun_id`	optional	int32	If there is a defined failure handler for the NodeRun, then this field is set to the id of the failure handler thread run.

Message `NodeRun`

A NodeRun is a running instance of a Node in a ThreadRun. Note that a NodeRun is a Getable object, meaning it can be retried from the LittleHorse grpc API.

Field	Label	Type	Description
`id`		NodeRunId	The ID of the NodeRun. Note that the NodeRunId contains the WfRunId, the ThreadRun's number, and the position of the NodeRun within that ThreadRun.
`wf_spec_id`		WfSpecId	The ID of the WfSpec that this NodeRun is from. This is not always the same as the ThreadRun it belongs to because of the upcoming WfSpec Version Migration feature.
`failure_handler_ids`	repeated	int32	A list of all ThreadRun's that ran to handle a failure thrown by this NodeRun.
`status`		LHStatus	The status of this NodeRun.
`arrival_time`		google.protobuf.Timestamp	The time the ThreadRun arrived at this NodeRun.
`end_time`	optional	google.protobuf.Timestamp	The time the NodeRun was terminated (failed or completed).
`thread_spec_name`		string	The name of the ThreadSpec to which this NodeRun belongs.
`node_name`		string	The name of the Node in the ThreadSpec that this NodeRun belongs to.
`error_message`	optional	string	A human-readable error message intended to help developers diagnose WfSpec problems.
`failures`	repeated	Failure	A list of Failures thrown by this NodeRun.
`task`	oneof `node_type`	TaskNodeRun	Denotes a TASK node, which runs a TaskRun.
`external_event`	oneof `node_type`	ExternalEventNodeRun	An EXTERNAL_EVENT node blocks until an ExternalEvent arrives.
`entrypoint`	oneof `node_type`	EntrypointRun	An ENTRYPOINT node is the first thing that runs in a ThreadRun.
`exit`	oneof `node_type`	ExitRun	An EXIT node completes a ThreadRun.
`start_thread`	oneof `node_type`	StartThreadRun	A START_THREAD node starts a child ThreadRun.
`wait_threads`	oneof `node_type`	WaitForThreadsRun	A WAIT_THREADS node waits for one or more child ThreadRun's to complete.
`sleep`	oneof `node_type`	SleepNodeRun	A SLEEP node makes the ThreadRun block for a certain amount of time.
`user_task`	oneof `node_type`	UserTaskNodeRun	A USER_TASK node waits until a human executes some work and reports the result.
`start_multiple_threads`	oneof `node_type`	StartMultipleThreadsRun	A START_MULTIPLE_THREADS node iterates over a JSON_ARR variable and spawns a child ThreadRun for each element in the list.
`throw_event`	oneof `node_type`	ThrowEventNodeRun	A THROW_EVENT node throws a WorkflowEvent of a specified WorkflowEventDef.
`wait_for_condition`	oneof `node_type`	WaitForConditionRun	A WAIT_FOR_CONDITION node blocks the ThreadRun until the specified condition evaluates to True.

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`

The sub-node structure for a THROW_EVENT NodeRun.

Field	Label	Type	Description
`workflow_event_id`		WorkflowEventId	The ID of the `WorkflowEvent` that was thrown by this `ThrowEventNodeRun`.

Message `UserTaskNodeRun`

The sub-node structure for a USER_TASK NodeRun.

Field	Label	Type	Description
`user_task_run_id`	optional	UserTaskRunId	The ID of the UserTaskRun. Note that if the ThreadRun was halted when it arrived at this USER_TASK node, then the user_task_run_id will be unset.

Message `WaitForConditionRun`

The sub-node structure for a WAIT_FOR_CONDITION NodeRun

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	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	Type	Description
`wf_run_id`	WfRunId	ID of the WfRun for this NodeRun. Note that every NodeRun is associated with a WfRun.
`thread_run_number`	int32	ThreadRun of this NodeRun. Note that each NodeRun belongs to a ThreadRun.
`position`	int32	Position of this NodeRun within its ThreadRun.

Message `PrincipalId`

ID for a Principal.

Field	Label	Type	Description
`id`		string	The id of this principal. In OAuth, this is the OAuth Client ID (for machine principals) or the OAuth User Id (for human principals).

Message `ScheduledWfRunId`

ID for a ScheduledWfRun

Field	Label	Type	Description
`id`		string

Message `TaskDefId`

ID for a TaskDef.

Field	Label	Type	Description
`name`		string	TaskDef's are uniquely identified by their name.

Message `TaskDefMetricsId`

ID for a specific window of TaskDef metrics.

Field	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	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	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	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	Type	Description
`wf_run_id`	WfRunId	The Id of the WfRun that threw the event.
`workflow_event_def_id`	WorkflowEventDefId	The ID of the WorkflowEventDef that this WorkflowEvent is a member of.
`number`	int32	A sequence number that makes the WorkflowEventId unique among all WorkflowEvent's of the same type thrown by the WfRun. This field starts at zero and is incremented every time a WorkflowEvent of the same type is thrown by the same WfRun.

Message `ScheduledWfRun`

A ScheduledWfRun is an object in the LittleHorse API that triggers a WfRun to be started on a cron schedule.

Field	Label	Type	Description
`id`		ScheduledWfRunId	Unique id for this ScheduledWfRun.
`wf_spec_id`		WfSpecId	WfSpec used to run a workflow on a schedule.
`variables`	map	ScheduledWfRun.VariablesEntry	A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun.
`parent_wf_run_id`	optional	WfRunId	Parent WfRunId associated with all the generated WfRuns
`cron_expression`		string	UNIX expression used to specify the schedule for executing WfRuns
`created_at`		google.protobuf.Timestamp	Creation time for this ScheduledWfRun

Message `ScheduledWfRun.VariablesEntry`

Field	Label	Type	Description
`key`		string
`value`		VariableValue

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

Delete an existing ScheduledWfRun, returns INVALID_ARGUMENT if object does not exist

Field	Label	Type	Description
`id`		ScheduledWfRunId	Id of the `ScheduledWfRun` to be deleted

Message `DeleteTaskDefRequest`

Deletes a TaskDef.

Field	Label	Type	Description
`id`		TaskDefId	The ID of the TaskDef to delete.

Message `DeleteUserTaskDefRequest`

Deletes a UserTaskDef.

Field	Label	Type	Description
`id`		UserTaskDefId	The ID of the UserTaskDef to delete.

Message `DeleteWfRunRequest`

Deletes a WfRun.

Field	Label	Type	Description
`id`		WfRunId	The ID of the WfRun to delete.

Message `DeleteWfSpecRequest`

Deletes a WfSpec

Field	Label	Type	Description
`id`		WfSpecId	The ID of the WfSpec to delete

Message `DeleteWorkflowEventDefRequest`

Deletes an WorkflowEventDef

Field	Label	Type	Description
`id`		WorkflowEventDefId	The ID of the WorkflowEventDef 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	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	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 `ListWorkflowEventsRequest`

List all WorkflowEvents for a specific WfRunId. Note that List Requests return actual WorkflowEvent objects, not WorkflowEventId's.

Field	Label	Type	Description
`wf_run_id`		WfRunId	The WfRunId for whom we list WorkflowEvent's.

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 `ExternalEvent`s.

Message `PutExternalEventRequest`

Request used to create an ExternalEvent.

Field	Label	Type	Description
`wf_run_id`		WfRunId	The ID of the WfRun that this Event is sent to.
`external_event_def_id`		ExternalEventDefId	The ID of the ExternalEventDef that this event implements.
`guid`	optional	string	Note that an ExternalEventDefId is a three-part ID: 1. WfRunId 2. ExternalEventDef Name 3. A guid The guid from part 3) can be optionally provided to the PutExternalEventRequest in order to make it idempotent. It is a best practice to do so.
`content`		VariableValue	The content of this event.
`thread_run_number`	optional	int32	Optionally specify that this ExternalEvent may only be claimed by a specific ThreadRun.
`node_run_position`	optional	int32	Optionally specify that this ExternalEvent may only be claimed by a specific NodeRun. In order for this to be set, you must also set thread_run_number.

Message `PutTaskDefRequest`

Creates a TaskDef.

Field	Label	Type	Description
`name`		string	The name of the TaskDef to create.
`input_vars`	repeated	VariableDef	Variables required to execute the TaskDef. Normally, these are automatically generated by the Task Worker SDK.
`output_schema`	optional	TaskDefOutputSchema	Schema that validates the TaskDef's output

Message `PutUserTaskDefRequest`

Creates a UserTaskDef.

Field	Label	Type	Description
`name`		string	The name of the UserTaskDef to create.
`fields`	repeated	UserTaskField	The fields that should be presented to the user on the screen in order to fill out the User Task. Note that these fields also define a data contract for the result of the UserTaskDef.
`description`	optional	string	Optional metadata field to store user-defined data. Does not impact workflow execution. Fine to store up to a few KB of text here.

Message `PutWfSpecRequest`

Creates a WfSpec. Generally, this request is generated by the Workflow object in our various SDK's.

Field	Label	Type	Description
`name`		string	The name of the resulting WfSpec.
`thread_specs`	map	PutWfSpecRequest.ThreadSpecsEntry	Map from name the ThreadSpec.
`entrypoint_thread_name`		string	The name of the ThreadSpec to be used as the workflow entrypoint.
`retention_policy`	optional	WorkflowRetentionPolicy	Optional policy to determine how long a WfRun is retained in the data store after it is completed or terminated.
`parent_wf_spec`	optional	WfSpec.ParentWfSpecReference	Parent WfSpec Reference. If this is set, then all WfRun's for this WfSpec MUST be Child WfRun's of the specified WfSpec.
`allowed_updates`		AllowedUpdateType	Configures the behavior of this individual request. Can be used to prevent breaking changes to the WfSpec, prevent any changes to the WfSpec, or allow all changes to the WfSpec.

Message `PutWfSpecRequest.ThreadSpecsEntry`

Field	Label	Type	Description
`key`		string
`value`		ThreadSpec

Message `PutWorkflowEventDefRequest`

Creates a WorkflowEventDef

Field	Label	Type	Description
`name`		string	The name of the resulting WorkflowEventDef.
`type`		VariableType	The type of 'content' thrown with a WorkflowEvent based on this WorkflowEventDef.

Message `RegisterTaskWorkerRequest`

Message used by Task Worker to register itself to the server and ask for assignments of servers to poll.

Used by the Task Worker SDK; generally, you shouldn't have to touch this manually.

Field	Label	Type	Description
`task_worker_id`		string	Is the ID of the Task Worker.
`task_def_id`		TaskDefId	The TaskDef the worker wants to poll for.

Message `RegisterTaskWorkerResponse`

Response containing list of Servers that the Task Worker should connect to and start polling from. Only used internally by the Task Worker SDK.

Field	Label	Type	Description
`your_hosts`	repeated	LHHostInfo	The list of LH Server hosts that the Task Worker should start polling.
`is_cluster_healthy`	optional	bool	Whether the LH Cluster is healthy.

Message `ReportTaskRun`

Request used by the Task Worker SDK to report the result of a TaskRun execution.

Field	Label	Type	Description
`task_run_id`		TaskRunId	ID of the TaskRun
`time`		google.protobuf.Timestamp	When the TaskRun was executed
`status`		TaskStatus	Status of the TaskRun
`log_output`	optional	VariableValue	Optional information for logging or exceptions
`attempt_number`		int32	Attempt number of the TaskRun
`output`	oneof `result`	VariableValue	Successfully completed task
`error`	oneof `result`	LHTaskError	Technical error
`exception`	oneof `result`	LHTaskException	Business exception

Message `RescueThreadRunRequest`

The request used to rescue a failed ThreadRun at a specific NodeRun.

Field	Type	Description
`wf_run_id`	WfRunId	The id of the `WfRun` which we are going to rescue.
`thread_run_number`	int32	The number of the failed `ThreadRun` that we will rescue. The specified `ThreadRun` must be in a state where it's latest `NodeRun` is: - In the `ERROR` state. - Has no `FailureHandler` `ThreadRun`s - The parent `ThreadRun`, or any parent of the parent, has not handled the `Failure` yet. If that is not true, then the `ThreadRun` cannot be rescued and the request will return `FAILED_PRECONDITION`.
`skip_current_node`	bool	If set to `true`, then the ThreadRun will skip past the `Node` of the current failed `NodeRun` and advance according to the outgoing edges. If set to `false`, then the `ThreadRun` will schedule another `NodeRun` for the current `Node`

Message `ResumeWfRunRequest`

Resume a WfRun.

Field	Label	Type	Description
`wf_run_id`		WfRunId	Is the WfRunId
`thread_run_number`		int32	The number of the ThreadRun to resume. Note that resuming the entrypoint ThreadRun (which always has number `0`) causes the whole WfRun to resume. If you do not manually set the thread_run_number field, it defaults to zero, so resuming the entire WfRun is the default behavior.

Message `RunWfRequest`

Create a Workflow Run.

Field	Label	Type	Description
`wf_spec_name`		string	The name of the WfSpec to run.
`major_version`	optional	int32	Optionally specify the major version of the WfSpec to run. This guarantees that the "signature" of the WfSpec (i.e. the required input variables, and searchable variables) will not change for this app.
`revision`	optional	int32	Optionally specify the specific revision of the WfSpec to run. It is not recommended to use this in practice, as the WfSpec logic should be de-coupled from the applications that run WfRun's.
`variables`	map	RunWfRequest.VariablesEntry	A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun.
`id`	optional	string	You can optionally specify the ID of this WfRun. This is a recommended best practice as it also makes your request idempotent and allows you to easily find the WfRun at a later time.
`parent_wf_run_id`	optional	WfRunId

Message `RunWfRequest.VariablesEntry`

Field	Label	Type	Description
`key`		string
`value`		VariableValue

Message `ScheduleWfRequest`

Schedule WfRuns based on a specific cron UNIX expression

Field	Label	Type	Description
`id`	optional	string	Specific ID
`wf_spec_name`		string	The name of the WfSpec to run.
`major_version`	optional	int32	Optionally specify the major version of the WfSpec to run. This guarantees that the "signature" of the WfSpec (i.e. the required input variables, and searchable variables) will not change for this app.
`revision`	optional	int32	Optionally specify the specific revision of the WfSpec to run. It is not recommended to use this in practice, as the WfSpec logic should be de-coupled from the applications that run WfRun's.
`variables`	map	ScheduleWfRequest.VariablesEntry	A map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun.
`parent_wf_run_id`	optional	WfRunId	Parent WfRunId associated with all the generated WfRuns
`cron_expression`		string	UNIX expression used to specify the schedule for executing WfRuns

Message `ScheduleWfRequest.VariablesEntry`

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

List of ScheduledWfRun

Field	Label	Type	Description
`results`	repeated	ScheduledWfRunId	A list of ScheduledWfRun Objects

Message `SearchExternalEventDefRequest`

Search for ExternalEventDefs based on certain criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`prefix`	optional	string	Optionally search only for ExternalEventDef's whose name starts with this prefix.

Message `SearchExternalEventRequest`

Search for ExternalEvents based on certain criteria.

Required field ExternalEventDefId specifies which ExternalEventDef to search for ExternalEvents under.

At this time, it is not possible to make a search for all ExternalEvents.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`earliest_start`	optional	google.protobuf.Timestamp	Specifies to return only ExternalEvents created after this time
`latest_start`	optional	google.protobuf.Timestamp	Specifies to return only ExternalEvents created before this time
`external_event_def_id`		ExternalEventDefId	Search for ExternalEvents by their ExternalEventDefId * Note: If ExternalEventDefId is not provided or does not exist, gRPC status code 'INVALID_ARGUMENT' will be returned.
`is_claimed`	optional	bool	Optionally search for only ExternalEvents that are claimed or not.

Message `SearchNodeRunRequest`

Search for NodeRun's by certain criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`earliest_start`	optional	google.protobuf.Timestamp	Only return NodeRun's created after this time.
`latest_start`	optional	google.protobuf.Timestamp	Only return NodeRun's created before this time.
`node_type`		SearchNodeRunRequest.NodeType	Specifies the type of NodeRun to search for.
`status`		LHStatus	Specifies the status of NodeRun to search for.

Message `SearchPrincipalRequest`

Search for Principals based on certain criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`earliest_start`	optional	google.protobuf.Timestamp	Specifies to return only Principals's created after this time
`latest_start`	optional	google.protobuf.Timestamp	Specifies to return only Principals's created before this time
`isAdmin`	oneof `principal_criteria`	bool	List only Principals that are admins
`tenantId`	oneof `principal_criteria`	string	List Principals associated with this Tenant ID

Message `SearchScheduledWfRunRequest`

Search filters for ScheduledWfRun's

Field	Label	Type	Description
`wf_spec_name`		string	The name of the WfSpec to filter
`major_version`	optional	int32	The major version of the WfSpec to filter
`revision`	optional	int32	The revision number of the WfSpec to filter

Message `SearchTaskDefRequest`

Search for TaskDef's based on certain criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`prefix`	optional	string	Optionally specify to only return TaskDef's with a specific prefix.

Message `SearchTaskRunRequest`

Searches for TaskRuns by various criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`task_def_name`		string	Specifies the TaskDef of TaskRun's to return. This is required.
`status`	optional	TaskStatus	Specifies to only return TaskRun's matching this status.
`earliest_start`	optional	google.protobuf.Timestamp	Specifies to only return TaskRun's that were scheduled after this time.
`latest_start`	optional	google.protobuf.Timestamp	Specifies to only return TaskRun's that were scheduled before this time.

Message `SearchTenantRequest`

Search for all available TenantIds for current Principal

Field	Label	Type	Description
`limit`	optional	int32	Maximum results to return in one request.
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.

Message `SearchUserTaskDefRequest`

Search for UserTaskDef's.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`prefix`	oneof `user_task_def_criteria`	string	Return all UserTaskDef's with a specific prefix.
`name`	oneof `user_task_def_criteria`	string	Return all UserTaskDef's with a specific name.

Message `SearchUserTaskRunRequest`

Search for UserTaskRun's matching certain criteria. The attributes are additive, you may specify any combination of fields in this request. Only UserTaskRun's matching all criteria will be returned.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`status`	optional	UserTaskRunStatus	Status of UserTaskRun's to return.
`user_task_def_name`	optional	string	UserTaskDef name to search for.
`user_id`	optional	string	Search for UserTaskRun's assigned to this user id.
`user_group`	optional	string	Search for UserTaskRun's assigned to this user group.
`earliest_start`	optional	google.protobuf.Timestamp	Search for UserTaskRun's that were created after this time.
`latest_start`	optional	google.protobuf.Timestamp	Search for UserTaskRun's that were created before this time.

Message `SearchVariableRequest`

Search for Variables by their value. This request is also highly useful to search for WfRun's based on the value of Variable's that are not in the Entrypoint ThreadRun, and also when you are using LittleHorse as a data store and need to perform a search.

You may only search for a Variable that has an index specified on it. This may be done via th .searchable() method on our SDK's.

Note that we do not yet support searching JSON_OBJ or JSON_ARR fields, but you may still mark those fields as searchable. We will soon add the ability to query those fields via the indices.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`value`		VariableValue	Specifies the value that the variable must be. Exact match is required.
`wf_spec_major_version`	optional	int32	Specifies major version of the WfSpec for the associated WfRun.
`wf_spec_revision`	optional	int32	Specifies the revision of the WfSpec for the associated WfRun.
`var_name`		string	Specifies the name of the variable to search for. This is required.
`wf_spec_name`		string	Specifies the name of the WfSpec for the associated WfRun's. This is required.

Message `SearchWfRunRequest`

A request used to retrieve a list of WfRunId's by certain criteria.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`wf_spec_name`		string	The WfSpec whose WfRun's we are searching for. This is required.
`wf_spec_major_version`	optional	int32	Specifies to return only WfRun's from this WfSpec Major Version.
`wf_spec_revision`	optional	int32	Specifies to return only WfRun's from this WfSpec Revision. Can only be set if wf_spec_major_version is also set.
`status`	optional	LHStatus	Specifies to return only WfRun's matching this status.
`earliest_start`	optional	google.protobuf.Timestamp	Specifies to return only WfRun's that started after this time
`latest_start`	optional	google.protobuf.Timestamp	Specifies to return only WfRun's that started before this time
`variable_filters`	repeated	VariableMatch	Allows filtering WfRun's based on the value of the Variables. This ONLY works for the Variables in the entrypiont threadrun (that is, variables where the threadRunNumber == 0).

Message `SearchWfSpecRequest`

Search for WfSpec's.

Field	Label	Type	Description
`bookmark`	optional	bytes	Bookmark for cursor-based pagination; pass if applicable.
`limit`	optional	int32	Maximum results to return in one request.
`name`	oneof `wf_spec_criteria`	string	Return WfSpec's with a specific name.
`prefix`	oneof `wf_spec_criteria`	string	Return WfSpec's with a specific prefix.
`task_def_name`	oneof `wf_spec_criteria`	string	Return all WfSpec's that make use of a given TaskDef.

Message `SearchWorkflowEventDefRequest`

Search for WorkflowEventDefs 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 WorkflowEventDef's whose name starts with this prefix.

Message `SearchWorkflowEventRequest`

Search for WorkflowEvents based on certain criteria.

Required field WorkflowEventDefId specifies which WorkflowEventDef to search for WorkflowEvents under.

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 WorkflowEvent created after this time
`latest_start`	optional	google.protobuf.Timestamp	Specifies to return only WorkflowEvent created before this time
`workflow_event_def_id`		WorkflowEventDefId	Search for WorkflowEvents by their WorkflowEventDefId * Note: If WorkflowEventDefId is not provided or does not exist, gRPC status code 'INVALID_ARGUMENT' will be returned.

Message `ServerVersion`

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

List of WorkflowEventDef Id's.

Field	Label	Type	Description
`results`	repeated	WorkflowEventDefId	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 `WorkflowEventIdList`

List of WorkflowEvent Id's

Field	Label	Type	Description
`results`	repeated	WorkflowEventId	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 `WorkflowEventList`

A list of WorkflowEvents.

Field	Label	Type	Description
`results`	repeated	WorkflowEvent	A list of WorkflowEvent objects.

Message `TaskDef`

A TaskDef defines a blueprint for a TaskRun that can be dispatched to Task Workers.

Field	Label	Type	Description
`id`		TaskDefId	The ID of this TaskDef.
`input_vars`	repeated	VariableDef	The input variables required to execute this TaskDef.
`created_at`		google.protobuf.Timestamp	The time at which this TaskDef was created.
`schema_output`	optional	TaskDefOutputSchema	Schema that validates the TaskDef's output

Message `TaskDefOutputSchema`

Schema that validates the TaskDef's output

Field	Label	Type	Description
`value_def`		VariableDef	The definition for the output content

Message `LHTaskError`

Message denoting a TaskRun failed for technical reasons.

Field	Label	Type	Description
`type`		LHErrorType	The technical error code.
`message`		string	Human readable message for debugging.

Message `LHTaskException`

Message denoting a TaskRun's execution signaled that something went wrong in the business process, throwing a littlehorse 'EXCEPTION'.

Field	Type	Description
`name`	string	The user-defined Failure name, for example, "credit-card-declined"
`message`	string	Human readadble description of the failure.
`content`	VariableValue

Message `TaskAttempt`

A single time that a TaskRun was scheduled for execution on a Task Queue.

Field	Label	Type	Description
`log_output`	optional	VariableValue	Optional information provided by the Task Worker SDK for debugging. Usually, if set it contains a stacktrace or it contains information logged via `WorkerContext#log()`.
`schedule_time`	optional	google.protobuf.Timestamp	The time the TaskAttempt was scheduled on the Task Queue. Not set for a TaskAttempt that is in the TASK_PENDING status; for example, when waiting between retries with exponential backoff.
`start_time`	optional	google.protobuf.Timestamp	The time the TaskAttempt was pulled off the queue and sent to a TaskWorker.
`end_time`	optional	google.protobuf.Timestamp	The time the TaskAttempt was finished (either completed, reported as failed, or timed out)
`task_worker_id`		string	EXPERIMENTAL: the ID of the Task Worker who executed this TaskRun.
`task_worker_version`	optional	string	The version of the Task Worker that executed the TaskAttempt.
`status`		TaskStatus	The status of this TaskAttempt.
`output`	oneof `result`	VariableValue	Denotes the Task Function executed properly and returned an output.
`error`	oneof `result`	LHTaskError	An unexpected technical error was encountered. May or may not be retriable.
`exception`	oneof `result`	LHTaskException	The Task Function encountered a business problem and threw a technical exception.
`masked_value`		bool	Indicates whether the result of the attempt field has been masked

Message `TaskNodeReference`

Reference to a NodeRun of type TASK which caused a TaskRun to be scheduled.

Field	Label	Type	Description
`node_run_id`		NodeRunId	The ID of the NodeRun which caused this TASK to be scheduled.

Message `TaskRun`

A TaskRun resents a single instance of a TaskDef being executed.

Field	Label	Type	Description
`id`		TaskRunId	The ID of the TaskRun. Note that the TaskRunId contains the WfRunId.
`task_def_id`		TaskDefId	The ID of the TaskDef being executed.
`attempts`	repeated	TaskAttempt	All attempts scheduled for this TaskRun. A TaskAttempt represents an occurrence of the TaskRun being put on a Task Queue to be executed by the Task Workers.
`input_variables`	repeated	VarNameAndVal	The input variables to pass into this TaskRun. Note that this is a list and not a map, because ordering matters. Depending on the language implementation, not every LittleHorse Task Worker SDK has the ability to determine the names of the variables from the method signature, so we provide both names and ordering.
`source`		TaskRunSource	The source (in the WfRun) that caused this TaskRun to be created. Currently, this can be either a TASK node, or a User Task Action Task Trigger in a USER_TASK node (such as a task used to send reminders).
`scheduled_at`		google.protobuf.Timestamp	When the TaskRun was scheduled.
`status`		TaskStatus	The status of the TaskRun.
`timeout_seconds`		int32	The timeout before LH considers a TaskAttempt to be timed out.
`total_attempts`		int32	The maximum number of attempts that may be scheduled for this TaskRun. NOTE: setting total_attempts to 1 means that there are no retries.
`exponential_backoff`	optional	ExponentialBackoffRetryPolicy	Optional backoff policy .

Message `TaskRunSource`

The source of a TaskRun; i.e. why it was scheduled.

Field	Label	Type	Description
`task_node`	oneof `task_run_source`	TaskNodeReference	Reference to a NodeRun of type TASK which scheduled this TaskRun.
`user_task_trigger`	oneof `task_run_source`	UserTaskTriggerReference	Reference to the specific UserTaskRun trigger action which scheduled this TaskRun
`wf_spec_id`	optional	WfSpecId	The ID of the WfSpec that is being executed. Always set in ScheduledTask.source so that the WorkerContext can know this information.

Message `VarNameAndVal`

A key-value pair of variable name and value.

Field	Type	Description
`var_name`	string	The variable name.
`value`	VariableValue	The value of the variable for this TaskRun.
`masked`	bool	Indicates whether the content of the `value` field has been masked

Message `AssignUserTaskRunRequest`

Re-Assigns a UserTaskRun to a specific userId or userGroup.

Field	Label	Type	Description
`user_task_run_id`		UserTaskRunId	The UserTaskRun to assign to a new user_id or user_group.
`override_claim`		bool	If override_claim is set to false and the UserTaskRun is already assigned to a user_id, then the request throws a FAILED_PRECONDITION error. If set to true, then the old claim is overriden and the UserTaskRun is assigned to the new user.
`user_group`	optional	string	The new user_group to which the UserTaskRun is assigned. If not set, then the user_group of the UserTaskRun is actively unset by this request. At least one of the user_group and user_id must be set.
`user_id`	optional	string	The new user_id to which the UserTaskRun is assigned. If not set, then the user_id of the UserTaskRun is actively unset by this request. At least one of the user_group and user_id must be set.

Message `CancelUserTaskRunRequest`

Cancels a UserTaskRun.

Field	Label	Type	Description
`user_task_run_id`		UserTaskRunId	The id of the UserTaskRun to cancel.

Message `CompleteUserTaskRunRequest`

Completes a UserTaskRun with provided values.

Field	Label	Type	Description
`user_task_run_id`		UserTaskRunId	The id of UserTaskRun to complete.
`results`	map	CompleteUserTaskRunRequest.ResultsEntry	A map from UserTaskField.name to a VariableValue containing the results of the user filling out the form.
`user_id`		string	The ID of the user who executed the task.

Message `CompleteUserTaskRunRequest.ResultsEntry`

Field	Label	Type	Description
`key`		string
`value`		VariableValue

Message `SaveUserTaskRunProgressRequest`

Saves the results of a UserTaskRun and logs who saved the content.

Throws FAILED_PRECONDITION if the UserTaskRun is in the DONE or CANCELLED state.

If policy is set to FAIL_IF_CLAIMED_BY_OTHER, returns FAILED_PRECONDITION if the user_id field of the UserTaskRun does not match the user_id of the request.

Field	Label	Type	Description
`user_task_run_id`		UserTaskRunId	The id of UserTaskRun to save.
`results`	map	SaveUserTaskRunProgressRequest.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 saved the task.
`policy`		SaveUserTaskRunProgressRequest.SaveUserTaskRunAssignmentPolicy	Configures how to handle `UserTaskRun` ownership when saving it.

Message `SaveUserTaskRunProgressRequest.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.
`saved`	oneof `event`	UserTaskEvent.UTESaved	Denotes that the `UserTaskRun` was saved.

Message `UserTaskEvent.UTEAssigned`

Message denoting that the UserTaskRun was assigned.

Field	Label	Type	Description
`old_user_id`	optional	string	The user_id before the ownership change, if set.
`old_user_group`	optional	string	The user_group before the ownership change, if set.
`new_user_id`	optional	string	The user_id after the ownership change, if set.
`new_user_group`	optional	string	The user_group after the ownership change, if set.

Message `UserTaskEvent.UTECancelled`

Empty message used to denote that the UserTaskRun was cancelled.

Field	Label	Type	Description
`message`		string

Message `UserTaskEvent.UTESaved`

Message to denote that the UserTaskRun was saved.

Field	Label	Type	Description
`user_id`		string	The user_id of the user who saved the UserTaskRun.
`results`	map	UserTaskEvent.UTESaved.ResultsEntry	The results that were saved.

Message `UserTaskEvent.UTESaved.ResultsEntry`

Field	Label	Type	Description
`key`		string
`value`		VariableValue

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_group that the UserTaskRun is assigned to. Unset if UserTaskRun is not asigned to a specific user_group.

Message `Variable`

A Variable is an instance of a variable assigned to a WfRun.

Field	Type	Description
`id`	VariableId	ID of this Variable. Note that the VariableId contains the relevant WfRunId inside it, the threadRunNumber, and the name of the Variabe.
`value`	VariableValue	The value of this Variable.
`created_at`	google.protobuf.Timestamp	When the Variable was created.
`wf_spec_id`	WfSpecId	The ID of the WfSpec that this Variable belongs to.
`masked`	bool	Marks a variable to show masked values

Message `VariableValue`

VariableValue is a structure containing a value in LittleHorse. It can be used to pass input variables into a WfRun/ThreadRun/TaskRun/etc, as output from a TaskRun, as the value of a WfRun's Variable, etc.

Field	Label	Type	Description
`json_obj`	oneof `value`	string	A String representing a serialized json object.
`json_arr`	oneof `value`	string	A String representing a serialized json list.
`double`	oneof `value`	double	A 64-bit floating point number.
`bool`	oneof `value`	bool	A boolean.
`str`	oneof `value`	string	A string.
`int`	oneof `value`	int64	The `INT` variable type is stored as a 64-bit integer. The `INT` can be cast to a `DOUBLE`.
`bytes`	oneof `value`	bytes	An arbitrary String of bytes.

Message `FailureBeingHandled`

Points to the Failure that is currently being handled in the ThreadRun.

Field	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	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	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 ExternalEventNodeRun
`start_thread`	oneof `node`	StartThreadNode	Creates a StartThreadNodeRun
`wait_for_threads`	oneof `node`	WaitForThreadsNode	Creates a WaitForThreadsNodeRun
`nop`	oneof `node`	NopNode	Creates a NopNodeRun
`sleep`	oneof `node`	SleepNode	Creates a SleepNodeRun
`user_task`	oneof `node`	UserTaskNode	Creates a UserTaskNodeRun
`start_multiple_threads`	oneof `node`	StartMultipleThreadsNode	Creates a StartMultipleThreadsNodeRun
`throw_event`	oneof `node`	ThrowEventNode	Creates a ThrowEventNodeRun
`wait_for_condition`	oneof `node`	WaitForConditionNode	Creates a WaitForConditionRun

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

A SubNode that blocks until a condition is satisfied in the WfRun. There is no output.

Field	Label	Type	Description
`condition`		EdgeCondition	The condition that this node will block for.

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	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.
`node_run_id`	NodeRunId	The NodeRun with which the WorkflowEvent is associated.

Message `WorkflowEventDef`

The WorkflowEventDef defines the blueprint for a WorkflowEvent.

Field	Type	Description
`id`	WorkflowEventDefId	The ID of the WorkflowEventDef. Contains the name of the WorkflowEventDef.
`created_at`	google.protobuf.Timestamp	The time that the WorkflowEventDef was created at.
`type`	VariableType	The type of 'content' thrown with a WorkflowEvent based on this WorkflowEventDef.

LittleHorse Enums

This section contains the enums defined by the LittleHorse API.

Enum ACLAction

Describes an Action that can be taken over a specific set of resources.

Name	Number	Description
READ	0	Allows all RPC's that start with `Get`, `List`, and `Search` in relation to the metadata (eg. `TaskDef` for `ACL_TASK`) or run data (eg. `TaskRun` for `ACL_TASK`)
RUN	1	Allows RPC's that are needed for mutating the runs of the resource. For example, `RUN` over `ACL_TASK` allows the `ReportTask` and `PollTask` RPC's, and `RUN` over `ACL_WORKFLOW` allows the `RunWf`, `DeleteWfRun`, `StopWfRun`, and `ResumeWfRun` RPC's.
WRITE_METADATA	2	Allows mutating metadata. For example, `WRITE_METADATA` over `ACL_WORKFLOW` allows mutating `WfSpec`s, and `WRITE_METADATA` over `ACL_TASK` allows mutating `TaskDef`s.
ALL_ACTIONS	3	Allows all actions related to a resource.

Enum ACLResource

Defines a resource type for ACL's.

Name	Number	Description
ACL_WORKFLOW	0	Refers to `WfSpec` and `WfRun`
ACL_TASK	1	Refers to `TaskDef` and `TaskRun`
ACL_EXTERNAL_EVENT	2	Refers to `ExternalEventDef` and `ExternalEvent`
ACL_USER_TASK	3	Refers to `UserTaskDef` and `UserTaskRun`
ACL_PRINCIPAL	4	Refers to the `Principal` resource. Currently, the `ACL_PRINCIPAL` permission is only valid in the `global_acls` field of the `Principal`. A `Principal` who only has access to a specific Tenant cannot create othe Principals because a Principal is scoped to the Cluster, and not to a Tenant.
ACL_TENANT	5	Refers to the `Tenant` resource. The `ACL_TENANT` permission is only valid in the `global_acls` field of the `Principal`. This is because the `Tenant` resource is cluster-scoped.
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
ACL_WORKFLOW_EVENT	8	Refers to `WorkflowEventDef` and `WorkflowEvent`

Enum LHErrorType

This enum is all of the types of technical failure that can occur in a WfRun.

Name	Number	Description
CHILD_FAILURE	0	A child ThreadRun failed with a technical ERROR.
VAR_SUB_ERROR	1	Failed substituting input variables into a NodeRun.
VAR_MUTATION_ERROR	2	Failed mutating variables after a NodeRun successfully completed.
USER_TASK_CANCELLED	3	A UserTaskRun was cancelled (EVOLVING: this will become a Business EXCEPTION)
TIMEOUT	4	A NodeRun failed due to a timeout.
TASK_FAILURE	5	A TaskRun failed due to an unexpected error.
VAR_ERROR	6	Wrapper for VAR_SUB_ERROR and VAR_MUTATION_ERROR
TASK_ERROR	7	Wrapper for TASK_FALIURE and TIMEOUT
INTERNAL_ERROR	8	An unexpected LittleHorse Internal error occurred. This is not expected to happen.

Enum LHStatus

Status used for WfRun, ThreadRun, and NodeRun

Name	Number	Description
STARTING	0	The entity is starting.
RUNNING	1	The entity is running.
COMPLETED	2	The entity is completed. This is a terminal state.
HALTING	3	The entity will move to `HALTED` as soon as all preconditions for halting are satisfied.
HALTED	4	The entity is halted, either by user intervention or by the workflow scheduler.
ERROR	5	The entity has failed due to a technical failure, such as a type conversion error, a task timeout due to network failure, or a task worker crash.
EXCEPTION	6	The entity has failed due to a business exception defined by the user.

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.

The JSON_OBJ variable allows you to store complex objects in the JSON format. When using the Java and GoLang SDK's, the JSON_OBJ variable type is often used transparently to the user. For example, the Java Task Worker SDK can inspect your method signature and automatically deserialize an input variable into a POJO. | | JSON_ARR | 1 | The JSON_ARR variable allows you to store collections of objects as a JSON array. The behavior is similar to the JSON_OBJ variable type. | | DOUBLE | 2 | The DOUBLE variable type is a 64-bit floating point number. It can be cast to an INT. | | BOOL | 3 | Boolean denotes a simple boolean switch. | | STR | 4 | The STR variable type is stored as a String. INT, DOUBLE, and BOOL variables can be cast to a STR. | | INT | 5 | The INT variable type is stored as a 64-bit integer. The INT can be cast to a DOUBLE. | | BYTES | 6 | The BYTES variable type allows you to store an arbitrary byte string. |

Enum Comparator

Operator for comparing two values to create a boolean expression.

Name	Number	Description
LESS_THAN	0	Equivalent to `<`. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
GREATER_THAN	1	Equivalent to `>`. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
LESS_THAN_EQ	2	Equivalent to `<=`. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
GREATER_THAN_EQ	3	Equivalent to `>=`. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
EQUALS	4	This is valid for any variable type, and is similar to .equals() in Java.

One note: if the RHS is a different type from the LHS, then LittleHorse will try to cast the RHS to the same type as the LHS. If the cast fails, then the ThreadRun fails with a VAR_SUB_ERROR. | | NOT_EQUALS | 5 | This is the inverse of EQUALS | | IN | 6 | Only valid if the RHS is a JSON_OBJ or JSON_ARR. Valid for any type on the LHS.

For the JSON_OBJ type, this returns true if the LHS is equal to a KEY in the RHS. For the JSON_ARR type, it returns true if one of the elements of the RHS is equal to the LHS. | | NOT_IN | 7 | The inverse of IN. |

Enum UTActionTrigger.UTHook

Enumerates the different lifecycle hooks that can cause the timer to start running.

Name	Number	Description
ON_ARRIVAL	0	The hook should be scheduled `delay_seconds` after the UserTaskRun is created. This hook only causes the action to be scheduled once.
ON_TASK_ASSIGNED	1	The hook should be scheduled `delay_seconds` after the ownership of the UserTaskRun changes. This hook causes the Action to be scheduled one or more times. The first time is scheduled when the UserTaskRun is created, since we treat the change from "UserTaskRun is nonexistent" to "UserTaskRun is owned by a userId or userGroup" as a change in ownership.

Enum VariableMutationType

Enumerates the available operations to mutate a variable in a WfRun.

Name	Number	Description
ASSIGN	0	Set the variable specified by the LHS to the value of the RHS.
ADD	1	Add the RHS to the LHS.
EXTEND	2	Append the RHS to the LHS (valid if the LHS is a STR or JSON_ARR)
SUBTRACT	3	Subtract the RHS from the LHS (both must be INT or DOUBLE)
MULTIPLY	4	Multiply the LHS by the RHS (both must be INT or DOUBLE)
DIVIDE	5	Divide the LHS by the RHS (both must be INT or DOUBLE)
REMOVE_IF_PRESENT	6	Remove any occurrences of RHS from LHS (LHS must be JSON_ARR)
REMOVE_INDEX	7	Remove item at index RHS from LHS (LHS must be JSON_ARR)
REMOVE_KEY	8	Remove the key specified by RHS from the LHS (LHS must be JSON_OBJ)

Enum WaitForThreadsRun.WaitingThreadStatus

The status of a single ThreadRun that we are waiting for.

Name	Number	Description
THREAD_IN_PROGRESS	0	The ThreadRun is in progress (i.e. not COMPLETED nor EXCEPTION nor ERROR)
THREAD_HANDLING_FAILURE	1	The ThreadRun failed with some failure, and the FailureHandler is running for that Failure.
THREAD_COMPLETED_OR_FAILURE_HANDLED	2	We can mark this ThreadRun as "already waited for", meaning that either: 1. It completed successfully, OR 2. It failed, and the Failure Handler successfully completed
THREAD_UNSUCCESSFUL	3	The ThreadRun did not complete successfully, and there wasn't a successful run of a Failure Handler for the Failure that was thrown.

Enum AllowedUpdateType

This enum controls the behavior of a PutWfSpecRequest when a WfSpec with the same name previously exists.

Name	Number	Description
ALL_UPDATES	0	Allows any update: both minor (revsion) changes and breaking (majorVersion) changes are accepted
MINOR_REVISION_UPDATES	1	Allows only backwards-compatible changes that do not change the required input variables or the searchable variables in the WfSpec.
NO_UPDATES	2	Rejects any changes to the WfSpec.

Enum SearchNodeRunRequest.NodeType

This enum denotes the type of a NodeRun.

Name	Number	Description
TASK	0	TASK node schedules a TaskRun
EXTERNAL_EVENT	1	EXTERNAL_EVENT blocks the ThreadRun until a specified ExternalEvent arrives
ENTRYPOINT	2	ENTRYPOINT kicks off a ThreadRun
EXIT	3	EXIT completes a ThreadRun
START_THREAD	4	START_THREAD creates a Child ThreadRun
WAIT_THREADS	5	WAIT_THREADS waits for one or more child ThreadRuns to complete
SLEEP	6	SLEEP makes the ThreadRun sleep for a specified time
USER_TASK	7	USER_TASK creates a UserTaskRun and blocks until the UserTaskRun is completed.
START_MULTIPLE_THREADS	8	START_MULTIPLE_THREADS iterates over a list and starts a Child Thread for each item

Enum SaveUserTaskRunProgressRequest.SaveUserTaskRunAssignmentPolicy

Configures how to handle UserTaskRun ownership when saving it.

Name	Number	Description
FAIL_IF_CLAIMED_BY_OTHER	0	If the UserTaskRun is already assigned to a user_id, then the request throws a FAILED_PRECONDITION error.
IGNORE_CLAIM	1	If the UserTaskRun is already assigned to a user_id, then the request will leave the `UserTaskRun` assigned to the current user but still update the `results` and log in the `events` who updated the results.

Enum UserTaskRunStatus

The status that a UserTaskRun can be in.

Name	Number	Description
UNASSIGNED	0	Not assigned to a specific user yet.
ASSIGNED	1	Assigned to a specific user, but not completed or cancelled yet.
DONE	3	Done.
CANCELLED	4	Cancelled.

Enum ThreadType

The type of a ThreadRUn.

Name	Number	Description
ENTRYPOINT	0	The ENTRYPOINT ThreadRun. Exactly one per WfRun. Always has number == 0.
CHILD	1	A ThreadRun explicitly created by another ThreadRun via a START_THREAD or START_MULTIPLE_THREADS NodeRun.
INTERRUPT	2	A ThreadRun that was created to handle an Interrupt.
FAILURE_HANDLER	3	A ThreadRun that was created to handle a Failure.

Enum FailureHandlerDef.LHFailureType

Specifies a type of Failure

Name	Number	Description
FAILURE_TYPE_ERROR	0	FAILURE_TYPE_ERROR specifies any technical `ERROR`.
FAILURE_TYPE_EXCEPTION	1	Specifies a user-defined, business-related `EXCEPTION`.

Enum WfRunVariableAccessLevel

Determines the Access Level for a Variable in a ThreadSpec/WfSpec.

Name	Number	Description
PUBLIC_VAR	0	A `PUBLIC_VAR` can be accessed (read + mutated) by child `WfRun`'s.
PRIVATE_VAR	1	A `PRIVATE_VAR` cannot be accessed by a child `WfRun`.
INHERITED_VAR	2	An `INHERITED_VAR` is inherited from the parent `WfRun`. Only valid in a `WfSpec` that has a parent. Also can only be declared in the Entrypoint Thread.

LittleHorse GRPC API
LittleHorse Protobuf Schemas
LittleHorse Enums

LittleHorse GRPC API​

RPC PutTaskDef​

RPC GetTaskDef​

RPC GetTaskWorkerGroup​

RPC PutExternalEventDef​

RPC GetExternalEventDef​

RPC PutWorkflowEventDef​

RPC PutWfSpec​

RPC GetWfSpec​

RPC GetLatestWfSpec​

RPC MigrateWfSpec​

RPC PutUserTaskDef​

RPC GetUserTaskDef​

RPC GetLatestUserTaskDef​

RPC RunWf​

RPC ScheduleWf​

RPC SearchScheduledWfRun​

RPC GetScheduledWfRun​

RPC GetWfRun​

RPC GetUserTaskRun​

RPC AssignUserTaskRun​

RPC CompleteUserTaskRun​

RPC CancelUserTaskRun​

RPC SaveUserTaskRunProgress​

RPC ListUserTaskRuns​

RPC GetNodeRun​

RPC ListNodeRuns​

RPC GetTaskRun​

RPC ListTaskRuns​

RPC GetVariable​

RPC ListVariables​

RPC PutExternalEvent​

RPC GetExternalEvent​

RPC AwaitWorkflowEvent​

RPC GetWorkflowEventDef​

RPC GetWorkflowEvent​

RPC ListExternalEvents​

RPC ListWorkflowEvents​

RPC SearchWfRun​

RPC SearchNodeRun​

RPC SearchTaskRun​

RPC SearchUserTaskRun​

RPC SearchVariable​

RPC SearchExternalEvent​

RPC SearchWorkflowEvent​

RPC SearchTaskDef​

RPC SearchUserTaskDef​

RPC SearchWfSpec​

RPC SearchExternalEventDef​

RPC SearchWorkflowEventDef​

RPC SearchTenant​

RPC SearchPrincipal​

RPC RegisterTaskWorker​

RPC PollTask​

RPC ReportTask​

RPC StopWfRun​

RPC ResumeWfRun​

RPC RescueThreadRun​

RPC DeleteWfRun​

RPC DeleteTaskDef​

RPC DeleteWfSpec​

RPC DeleteUserTaskDef​

RPC DeleteExternalEventDef​

RPC DeleteWorkflowEventDef​

RPC DeletePrincipal​

RPC DeleteScheduledWfRun​

RPC GetTaskDefMetricsWindow​

RPC GetWfSpecMetricsWindow​

RPC ListTaskDefMetrics​

RPC ListWfSpecMetrics​

RPC PutTenant​

RPC GetTenant​

RPC PutPrincipal​

RPC GetPrincipal​

RPC Whoami​

RPC GetServerVersion​

LittleHorse Protobuf Schemas​

Message DeletePrincipalRequest​

Message Principal​

Message Principal.PerTenantAclsEntry​