Skip to main content

LittleHorse API Reference

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

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

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

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

Happy Reading!

LittleHorse GRPC API

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

RPC PutTaskDef

Request TypeResponse TypeDescription
PutTaskDefRequestTaskDefCreates a TaskDef.

RPC GetTaskDef

Request TypeResponse TypeDescription
TaskDefIdTaskDefGets a TaskDef.

RPC GetTaskWorkerGroup

Request TypeResponse TypeDescription
TaskDefIdTaskWorkerGroupGets the registered task worker group associated with a specific TaskDef.

RPC PutExternalEventDef

Request TypeResponse TypeDescription
PutExternalEventDefRequestExternalEventDefCreates an ExternalEventDef.

RPC GetExternalEventDef

Request TypeResponse TypeDescription
ExternalEventDefIdExternalEventDefGets an ExternalEventDef.

RPC PutWorkflowEventDef

Request TypeResponse TypeDescription
PutWorkflowEventDefRequestWorkflowEventDefEXPERIMENTAL: Creates a WorkflowEventDef.

RPC PutWfSpec

Request TypeResponse TypeDescription
PutWfSpecRequestWfSpecCreates a WfSpec.

RPC GetWfSpec

Request TypeResponse TypeDescription
WfSpecIdWfSpecGets a WfSpec.

RPC GetLatestWfSpec

Request TypeResponse TypeDescription
GetLatestWfSpecRequestWfSpecReturns the latest WfSpec with a specified name (and optionally a specified Major Version).

RPC MigrateWfSpec

Request TypeResponse TypeDescription
MigrateWfSpecRequestWfSpecEXPERIMENTAL: 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 TypeResponse TypeDescription
PutUserTaskDefRequestUserTaskDefCreates a UserTaskDef.

RPC GetUserTaskDef

Request TypeResponse TypeDescription
UserTaskDefIdUserTaskDefGets 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 TypeResponse TypeDescription
GetLatestUserTaskDefRequestUserTaskDefReturns the most recent UserTaskDef with a specific name.

RPC RunWf

Request TypeResponse TypeDescription
RunWfRequestWfRunRuns a WfSpec to create a WfRun.

RPC GetWfRun

Request TypeResponse TypeDescription
WfRunIdWfRunGets a WfRun. Although useful for development and debugging, this RPC is not often used by applications.

RPC GetUserTaskRun

Request TypeResponse TypeDescription
UserTaskRunIdUserTaskRunLoads 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 TypeResponse TypeDescription
AssignUserTaskRunRequest.google.protobuf.EmptyChange 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 TypeResponse TypeDescription
CompleteUserTaskRunRequest.google.protobuf.EmptyCompletes 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 TypeResponse TypeDescription
CancelUserTaskRunRequest.google.protobuf.EmptyCancels a UserTaskRun. This will result in an EXCEPTION being propagated to the WfRun.

RPC ListUserTaskRuns

Request TypeResponse TypeDescription
ListUserTaskRunRequestUserTaskRunListLists all UserTaskRun's for a specific WfRun. Can be useful when using a WfRun to model an entity.

RPC GetNodeRun

Request TypeResponse TypeDescription
NodeRunIdNodeRunGets a specific NodeRun.

RPC ListNodeRuns

Request TypeResponse TypeDescription
ListNodeRunsRequestNodeRunListLists all NodeRun's for a specific WfRun.

RPC GetTaskRun

Request TypeResponse TypeDescription
TaskRunIdTaskRunGets a specific TaskRun.

RPC ListTaskRuns

Request TypeResponse TypeDescription
ListTaskRunsRequestTaskRunListLists all TaskRun's for a specific WfRun.

RPC GetVariable

Request TypeResponse TypeDescription
VariableIdVariableGet 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 TypeResponse TypeDescription
ListVariablesRequestVariableListList all Variables from a WfRun.

RPC PutExternalEvent

Request TypeResponse TypeDescription
PutExternalEventRequestExternalEventPost an ExternalEvent. This RPC is highly useful for

RPC GetExternalEvent

Request TypeResponse TypeDescription
ExternalEventIdExternalEventGet a specific ExternalEvent.

RPC AwaitWorkflowEvent

Request TypeResponse TypeDescription
AwaitWorkflowEventRequestWorkflowEventWaits for a WorkflowEvent to be thrown by a given WfRun. Returns immediately if a matching WorkflowEvent has already been thrown; throws a DEADLINE_EXCEEDED error if the WorkflowEvent is not thrown before the deadline specified by the client.

To specify the deadline, the client should use GRPC deadlines.

RPC ListExternalEvents

Request TypeResponse TypeDescription
ListExternalEventsRequestExternalEventListList ExternalEvent's for a specific WfRun.

RPC SearchWfRun

Request TypeResponse TypeDescription
SearchWfRunRequestWfRunIdListSearch 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 TypeResponse TypeDescription
SearchNodeRunRequestNodeRunIdListSearch for NodeRun's. This RPC is useful for monitoring and finding bugs in your workflows or Task Workers.

RPC SearchTaskRun

Request TypeResponse TypeDescription
SearchTaskRunRequestTaskRunIdListSearch for TaskRun's. This RPC is useful for finding bugs in your Task Workers.

RPC SearchUserTaskRun

Request TypeResponse TypeDescription
SearchUserTaskRunRequestUserTaskRunIdListSearch 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 TypeResponse TypeDescription
SearchVariableRequestVariableIdListSearch 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 TypeResponse TypeDescription
SearchExternalEventRequestExternalEventIdListSearch for ExternalEvent's.

RPC SearchTaskDef

Request TypeResponse TypeDescription
SearchTaskDefRequestTaskDefIdListSearch for TaskDef's.

RPC SearchUserTaskDef

Request TypeResponse TypeDescription
SearchUserTaskDefRequestUserTaskDefIdListSearch for UserTaskDef's.

RPC SearchWfSpec

Request TypeResponse TypeDescription
SearchWfSpecRequestWfSpecIdListSearch for WfSpec's.

RPC SearchExternalEventDef

Request TypeResponse TypeDescription
SearchExternalEventDefRequestExternalEventDefIdListSearch for ExternalEventDef's.

RPC SearchTenant

Request TypeResponse TypeDescription
SearchTenantRequestTenantIdListSearch for all available TenantIds for current Principal

RPC RegisterTaskWorker

Request TypeResponse TypeDescription
RegisterTaskWorkerRequestRegisterTaskWorkerResponseUsed 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 TypeResponse TypeDescription
PollTaskRequestPollTaskResponseUsed by Task Workers to listen for TaskRuns on the Task Queue. Generally, you won't use this RPC manually.

RPC ReportTask

Request TypeResponse TypeDescription
ReportTaskRun.google.protobuf.EmptyUsed by Task Workers to report the result of a TaskRun. Generally, you won't use this rpc manually.

RPC StopWfRun

Request TypeResponse TypeDescription
StopWfRunRequest.google.protobuf.EmptyMove a WfRun or a specific ThreadRun in that WfRun to the HALTED state.

RPC ResumeWfRun

Request TypeResponse TypeDescription
ResumeWfRunRequest.google.protobuf.EmptyResumes a WfRun or a specific ThreadRun of a WfRun.

RPC DeleteWfRun

Request TypeResponse TypeDescription
DeleteWfRunRequest.google.protobuf.EmptyDeletes a WfRun. The WfRun cannot be in the RUNNING state.

RPC DeleteTaskDef

Request TypeResponse TypeDescription
DeleteTaskDefRequest.google.protobuf.EmptyDeletes a TaskDef.

RPC DeleteWfSpec

Request TypeResponse TypeDescription
DeleteWfSpecRequest.google.protobuf.EmptyDeletes a WfSpec.

RPC DeleteUserTaskDef

Request TypeResponse TypeDescription
DeleteUserTaskDefRequest.google.protobuf.EmptyDeletes a UserTaskDef.

RPC DeleteExternalEventDef

Request TypeResponse TypeDescription
DeleteExternalEventDefRequest.google.protobuf.EmptyDeletes an ExternalEventDef.

RPC GetTaskDefMetricsWindow

Request TypeResponse TypeDescription
TaskDefMetricsQueryRequestTaskDefMetricsReturns TaskDef Metrics for a specific TaskDef and a specific time window.

RPC GetWfSpecMetricsWindow

Request TypeResponse TypeDescription
WfSpecMetricsQueryRequestWfSpecMetricsReturns WfSpec Metrics for a specific WfSpec and a specific time window.

RPC ListTaskDefMetrics

Request TypeResponse TypeDescription
ListTaskMetricsRequestListTaskMetricsResponseReturns a list of TaskDef Metrics Windows.

RPC ListWfSpecMetrics

Request TypeResponse TypeDescription
ListWfMetricsRequestListWfMetricsResponseReturns a list of WfSpec Metrics Windows.

RPC PutTenant

Request TypeResponse TypeDescription
PutTenantRequestTenantEXPERIMENTAL: Creates another Tenant in the LH Server.

RPC GetTenant

Request TypeResponse TypeDescription
TenantIdTenantEXPERIMENTAL: Gets a Tenant from the LH Server.

RPC PutPrincipal

Request TypeResponse TypeDescription
PutPrincipalRequestPrincipalEXPERIMENTAL: Creates an Principal.

RPC Whoami

Request TypeResponse TypeDescription
.google.protobuf.EmptyPrincipalReturns the Principal of the caller.

RPC GetServerVersion

Request TypeResponse TypeDescription
.google.protobuf.EmptyServerVersionResponseGets the version of the LH Server.

LittleHorse Protobuf Schemas

This section contains the exact schemas for every object in our public API.

Message DeletePrincipalRequest

FieldLabelTypeDescription
idstring

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.

FieldLabelTypeDescription
idPrincipalIdThe 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_atgoogle.protobuf.TimestampThe time at which the Principal was created.
per_tenant_aclsmapPrincipal.PerTenantAclsEntryMaps a Tenant ID to a list of ACL's that the Principal has permission to execute within that Tenant.
global_aclsServerACLsSets permissions that this Principal has for any Tenant in the LH Cluster.

Message Principal.PerTenantAclsEntry

FieldLabelTypeDescription
keystring
valueServerACLs

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.

FieldLabelTypeDescription
idstringThe ID of the Principal that we are creating.
per_tenant_aclsmapPutPrincipalRequest.PerTenantAclsEntryThe per-tenant ACL's for the Principal
global_aclsServerACLsThe ACL's for the principal in all tenants
overwriteboolIf 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

FieldLabelTypeDescription
keystring
valueServerACLs

Message PutTenantRequest

FieldLabelTypeDescription
idstring

Message ServerACL

Represents a specific set of permissions over a specific set of objects in a Tenant. This is a positive permission.

FieldLabelTypeDescription
resourcesrepeatedACLResourceThe resource types over which permission is granted.
allowed_actionsrepeatedACLActionThe actions that are permitted.
nameoneof resource_filterstringIf 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.
prefixoneof resource_filterstringIf 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

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

FieldLabelTypeDescription
idTenantIdThe ID of the Tenant.
created_atgoogle.protobuf.TimestampThe 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.

FieldLabelTypeDescription
base_interval_msint32Base 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_msint64Maximum delay in milliseconds between retries.
multiplierfloatThe 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.

FieldLabelTypeDescription
task_def_idoneof task_to_executeTaskDefId
dynamic_taskoneof task_to_executeVariableAssignment
timeout_secondsint32How 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.
retriesint32Configures 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_backoffoptionalExponentialBackoffRetryPolicyIf this field is set, then retries will use Exponential Backoff.
variablesrepeatedVariableAssignmentInput 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
FieldLabelTypeDescription
taskoneof actionUTActionTrigger.UTATask
canceloneof actionUTActionTrigger.UTACancel
reassignoneof actionUTActionTrigger.UTAReassignlater on, might enable scheduling entire ThreadRuns
delay_secondsVariableAssignmentThe Action is triggered some time after the Hook matures. The delay is controlled by this field.
hookUTActionTrigger.UTHookThe 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.

FieldLabelTypeDescription
user_idoptionalVariableAssignmentA 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_groupoptionalVariableAssignmentA 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.

FieldLabelTypeDescription
taskTaskNodeThe specification of the Task to schedule.
mutationsrepeatedVariableMutationEXPERIMENTAL: 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.

FieldLabelTypeDescription
json_pathoptionalstringIf 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_nameoneof sourcestringAssign the value from a variable.
literal_valueoneof sourceVariableValueAssign a literal value
format_stringoneof sourceVariableAssignment.FormatStringAssign a format string

Message VariableAssignment.FormatString

A FormatString formats a template String with values from the WfRun.

FieldLabelTypeDescription
formatVariableAssignmentA 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"
argsrepeatedVariableAssignmentVariableAssignments which fill out the args.

Message VariableDef

Declares a Variable.

FieldLabelTypeDescription
typeVariableTypeThe Type of the variable.
namestringThe name of the variable.
default_valueoptionalVariableValueOptional default value if the variable isn't set; for example, in a ThreadRun if you start a ThreadRun or WfRun without passing a variable in, then this is used.

Message VariableMutation

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

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

FieldLabelTypeDescription
lhs_namestringThe name of the variable to mutate
lhs_json_pathoptionalstringFor JSON_ARR and JSON_OBJ variables, this allows you to optionally mutate a specific sub-field of the variable.
operationVariableMutationTypeDefines the operation that we are executing.
source_variableoneof rhs_valueVariableAssignmentSet the source_variable as the RHS to use another variable from the workflow to as the RHS/
literal_valueoneof rhs_valueVariableValueUse a literal value as the RHS.
node_outputoneof rhs_valueVariableMutation.NodeOutputSourceUse the output of the current node as the RHS.

Message VariableMutation.NodeOutputSource

Specifies to use the output of a NodeRun as the RHS.

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

FieldLabelTypeDescription
idExternalEventIdThe ID of the ExternalEvent. This contains WfRunId, ExternalEventDefId, and a unique guid which can be used for idempotency of the PutExternalEvent rpc call.
created_atgoogle.protobuf.TimestampThe time the ExternalEvent was registered with LittleHorse.
contentVariableValueThe payload of this ExternalEvent.
thread_run_numberoptionalint32If 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_positionoptionalint32If 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.
claimedboolWhether the ExternalEvent has been claimed by a WfRun.

Message ExternalEventDef

The ExternalEventDef defines the blueprint for an ExternalEvent.

FieldLabelTypeDescription
idExternalEventDefIdThe id of the ExternalEventDef.
created_atgoogle.protobuf.TimestampWhen the ExternalEventDef was created.
retention_policyExternalEventRetentionPolicyThe 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.

FieldLabelTypeDescription
seconds_after_putoneof ext_evt_gc_policyint64Delete such an ExternalEvent X seconds after it has been registered if it has not yet been claimed by a WfRun.

Message EntrypointRun

The sub-node structure for an ENTRYPOINT NodeRun. Currently Empty.

Message ExitRun

The sub-node structure for an EXIT NodeRun. Currently Empty, will contain info about ThreadRun Outputs once those are added in the future.

Message ExternalEventRun

The sub-node structure for an EXTERNAL_EVENT NodeRun.

FieldLabelTypeDescription
external_event_def_idExternalEventDefIdThe ExternalEventDefId that we are waiting for.
event_timeoptionalgoogle.protobuf.TimestampThe time that the ExternalEvent arrived. Unset if still waiting.
external_event_idoptionalExternalEventIdThe ExternalEventId of the ExternalEvent. Unset if still waiting.
timed_outboolWhether 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.

FieldLabelTypeDescription
failure_namestringThe 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.
messagestringThe human-readable message associated with this Failure.
contentoptionalVariableValueA 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_handledboolA boolean denoting whether a Failure Handler ThreadRun properly handled the Failure.
failure_handler_threadrun_idoptionalint32If 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.

FieldLabelTypeDescription
idNodeRunIdThe 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_idWfSpecIdThe 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_idsrepeatedint32A list of all ThreadRun's that ran to handle a failure thrown by this NodeRun.
statusLHStatusThe status of this NodeRun.
arrival_timegoogle.protobuf.TimestampThe time the ThreadRun arrived at this NodeRun.
end_timeoptionalgoogle.protobuf.TimestampThe time the NodeRun was terminated (failed or completed).
thread_spec_namestringThe name of the ThreadSpec to which this NodeRun belongs.
node_namestringThe name of the Node in the ThreadSpec that this NodeRun belongs to.
error_messageoptionalstringA human-readable error message intended to help developers diagnose WfSpec problems.
failuresrepeatedFailureA list of Failures thrown by this NodeRun.
taskoneof node_typeTaskNodeRunDenotes a TASK node, which runs a TaskRun.
external_eventoneof node_typeExternalEventRunAn EXTERNAL_EVENT node blocks until an ExternalEvent arrives.
entrypointoneof node_typeEntrypointRunAn ENTRYPOINT node is the first thing that runs in a ThreadRun.
exitoneof node_typeExitRunAn EXIT node completes a ThreadRun.
start_threadoneof node_typeStartThreadRunA START_THREAD node starts a child ThreadRun.
wait_threadsoneof node_typeWaitForThreadsRunA WAIT_THREADS node waits for one or more child ThreadRun's to complete.
sleeponeof node_typeSleepNodeRunA SLEEP node makes the ThreadRun block for a certain amount of time.
user_taskoneof node_typeUserTaskNodeRunA USER_TASK node waits until a human executes some work and reports the result.
start_multiple_threadsoneof node_typeStartMultipleThreadsRunA START_MULTIPLE_THREADS node iterates over a JSON_ARR variable and spawns a child ThreadRun for each element in the list.
throw_eventoneof node_typeThrowEventNodeRun

Message SleepNodeRun

The sub-node structure for a SLEEP NodeRun.

FieldLabelTypeDescription
maturation_timegoogle.protobuf.TimestampThe 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.
maturedboolWhether 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.

FieldLabelTypeDescription
thread_spec_namestringThe thread_spec_name of the child thread_runs.
child_thread_idsrepeatedint32The list of all created child ThreadRun's

Message StartThreadRun

The sub-node structure for a START_THREAD NodeRun.

FieldLabelTypeDescription
child_thread_idoptionalint32Contains the thread_run_number of the created Child ThreadRun, if it has been created already.
thread_spec_namestringThe thread_spec_name of the child thread_run.

Message TaskNodeRun

The sub-node structure for a TASK NodeRun.

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

FieldLabelTypeDescription
workflow_event_idWorkflowEventId

Message UserTaskNodeRun

The sub-node structure for a USER_TASK NodeRun.

FieldLabelTypeDescription
user_task_run_idoptionalUserTaskRunIdThe ID of the UserTaskRun. Note that if the ThreadRun was halted when it arrived at this USER_TASK node, then the user_task_run_id will be unset.

Message WaitForThreadsRun

The sub-node structure for a WAIT_FOR_THREADS NodeRun.

FieldLabelTypeDescription
threadsrepeatedWaitForThreadsRun.WaitForThreadThe threads that are being waited for.

Message WaitForThreadsRun.WaitForThread

A 'WaitForThread' structure defines a thread that is being waited for.

FieldLabelTypeDescription
thread_end_timeoptionalgoogle.protobuf.TimestampThe time at which the ThreadRun ended (successfully or not). Not set if the ThreadRun is still RUNNING, HALTED, or HALTING.
thread_statusLHStatusThe current status of the ThreadRun being waited for.
thread_run_numberint32The number of the ThreadRun being waited for.
waiting_statusWaitForThreadsRun.WaitingThreadStatusThe "waiting status" of this specific thread: whether it's still running, already done, handling a failure, or completely failed.
failure_handler_thread_run_idoptionalint32If 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

FieldLabelTypeDescription
namestringExternalEventDef's are uniquedly identified by their name.

Message ExternalEventId

ID for an ExternalEvent.

FieldLabelTypeDescription
wf_run_idWfRunIdWfRunId for the ExternalEvent. Note that every ExternalEvent is associated with a WfRun.
external_event_def_idExternalEventDefIdThe ExternalEventDef for this ExternalEvent.
guidstringA unique guid allowing for distinguishing this ExternalEvent from other events of the same ExternalEventDef and WfRun.

Message NodeRunId

ID for a NodeRun.

FieldLabelTypeDescription
wf_run_idWfRunIdID of the WfRun for this NodeRun. Note that every NodeRun is associated with a WfRun.
thread_run_numberint32ThreadRun of this NodeRun. Note that each NodeRun belongs to a ThreadRun.
positionint32Position of this NodeRun within its ThreadRun.

Message PrincipalId

ID for a Principal.

FieldLabelTypeDescription
idstringThe id of this principal. In OAuth, this is the OAuth Client ID (for machine principals) or the OAuth User Id (for human principals).

Message TaskDefId

ID for a TaskDef.

FieldLabelTypeDescription
namestringTaskDef's are uniquely identified by their name.

Message TaskDefMetricsId

ID for a specific window of TaskDef metrics.

FieldLabelTypeDescription
window_startgoogle.protobuf.TimestampThe timestamp at which this metrics window starts.
window_typeMetricsWindowLengthThe length of this window.
task_def_idTaskDefIdThe TaskDefId that this metrics window reports on.

Message TaskRunId

ID for a TaskRun.

FieldLabelTypeDescription
wf_run_idWfRunIdWfRunId for this TaskRun. Note that every TaskRun is associated with a WfRun.
task_guidstringUnique identifier for this TaskRun. Unique among the WfRun.

Message TaskWorkerGroupId

ID for a TaskWorkerGroup.

FieldLabelTypeDescription
task_def_idTaskDefIdTaskWorkerGroups are uniquely identified by their TaskDefId.

Message TenantId

ID for a Tenant.

FieldLabelTypeDescription
idstringThe Tenant ID.

Message UserTaskDefId

ID for a UserTaskDef

FieldLabelTypeDescription
namestringThe name of a UserTaskDef
versionint32Note that UserTaskDef's use simple versioning.

Message UserTaskRunId

ID for a UserTaskRun

FieldLabelTypeDescription
wf_run_idWfRunIdWfRunId for this UserTaskRun. Note that every UserTaskRun is associated with a WfRun.
user_task_guidstringUnique identifier for this UserTaskRun.

Message VariableId

Id for a Variable.

FieldLabelTypeDescription
wf_run_idWfRunIdWfRunId for the variable. Note that every Variable is associated with a WfRun.
thread_run_numberint32Each Variable is owned by a specific ThreadRun inside the WfRun it belongs to. This is that ThreadRun's number.
namestringThe name of the variable.

Message WfRunId

ID for a WfRun

FieldLabelTypeDescription
idstringThe ID for this WfRun instance.
parent_wf_run_idoptionalWfRunIdA WfRun may have a parent WfRun. If so, this field is set to the parent's ID.

Message WfSpecId

The ID of a WfSpec.

FieldLabelTypeDescription
namestringName of the WfSpec.
major_versionint32Major 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.
revisionint32Revision 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.

FieldLabelTypeDescription
window_startgoogle.protobuf.TimestampThe timestamp at which this metrics window starts.
window_typeMetricsWindowLengthThe length of this window.
wf_spec_idWfSpecIdThe WfSpecId that this metrics window reports on.

Message WorkflowEventDefId

ID for a WorkflowEventDef.

FieldLabelTypeDescription
namestringThe name of the WorkflowEventDef

Message WorkflowEventId

An ID for a WorkflowEvent.

FieldLabelTypeDescription
wf_run_idWfRunIdThe Id of the WfRun that threw the event.
workflow_event_def_idWorkflowEventDefIdThe ID of the WorkflowEventDef that this WorkflowEvent is a member of.
numberint32A sequence number that makes the WorkflowEventId unique among all WorkflowEvent's of the same type thrown by the WfRun. This field starts at zero and is incremented every time a WorkflowEvent of the same type is thrown by the same WfRun.

Message AwaitWorkflowEventRequest

Request to await until a WorkflowEvent of a certain WorkflowEventDef on a certain WfRun is thrown. Relies upon native GRPC deadlines to configure timeouts.

FieldLabelTypeDescription
wf_run_idWfRunIdThe ID of the WfRun which must throw the WorkflowEvent.
event_def_idsrepeatedWorkflowEventDefIdThe IDs of the WorkflowEventDef that must be thrown. The request will return the first matching WorkflowEvent is thrown. If event_def_ids is empty, then the request will return the first WorkflowEvent thrown by the WfRun.
workflow_events_to_ignorerepeatedWorkflowEventIdSince 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

FieldLabelTypeDescription
idExternalEventDefIdThe ID of the ExternalEventDef to delete.

Message DeleteExternalEventRequest

Deletes an ExternalEvent.

FieldLabelTypeDescription
idExternalEventIdThe ID of the ExternalEvent to delete.

Message DeleteTaskDefRequest

Deletes a TaskDef.

FieldLabelTypeDescription
idTaskDefIdThe ID of the TaskDef to delete.

Message DeleteUserTaskDefRequest

Deletes a UserTaskDef.

FieldLabelTypeDescription
idUserTaskDefIdThe ID of the UserTaskDef to delete.

Message DeleteWfRunRequest

Deletes a WfRun.

FieldLabelTypeDescription
idWfRunIdThe ID of the WfRun to delete.

Message DeleteWfSpecRequest

Deletes a WfSpec

FieldLabelTypeDescription
idWfSpecIdThe ID of the WfSpec to delete

Message ExternalEventDefIdList

List of ExternalEventDef Id's.

FieldLabelTypeDescription
resultsrepeatedExternalEventDefIdThe resulting object id's.
bookmarkoptionalbytesThe 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

FieldLabelTypeDescription
resultsrepeatedExternalEventIdThe resulting object id's.
bookmarkoptionalbytesThe 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.

FieldLabelTypeDescription
resultsrepeatedExternalEventA list of ExternalEvent objects.

Message GetLatestUserTaskDefRequest

Returns the UserTaskDef with a given name and the highest version number.

FieldLabelTypeDescription
namestringThe name of the UserTaskDef to search for.

Message GetLatestWfSpecRequest

Get the latest WfSpec with a given name and optionally majorVersion

FieldLabelTypeDescription
namestringThe name of the WfSpec to get. This is required.
major_versionoptionalint32Optionally 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.

FieldLabelTypeDescription
hoststringThe host on the server
portint32The 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.

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

FieldLabelTypeDescription
wf_run_idWfRunIdThe WfRun for whom we list NodeRun's.
thread_run_numberoptionalint32Optionally specify the thread run number to filter NodeRun's by.
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.

Message ListTaskMetricsRequest

Query to retrieve TaskDef Metrics over a period of time.

FieldLabelTypeDescription
task_def_idTaskDefIdTaskDef id for whichwe retrieve metrics.
last_window_startgoogle.protobuf.TimestampThis 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_lengthMetricsWindowLengthWindow size
num_windowsint32Number of windows to retrieve.

Message ListTaskMetricsResponse

A list of TaskDef Metrics WIndows

FieldLabelTypeDescription
resultsrepeatedTaskDefMetricsList of TaskDef Metrics Windows

Message ListTaskRunsRequest

List TaskRun's for a specific WfRun

FieldLabelTypeDescription
wf_run_idWfRunIdThe WfRun for which to list TaskRun's

Message ListUserTaskRunRequest

List UserTaskRun's for a specific WfRun

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

FieldLabelTypeDescription
wf_run_idWfRunIdThe WfRun for whom we will list Variables.

Message ListWfMetricsRequest

Query to retrieve WfSpec Metrics over a period of time.

FieldLabelTypeDescription
wf_spec_idWfSpecIdWfSpecId of metrics to get.
last_window_startgoogle.protobuf.TimestampThis 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_lengthMetricsWindowLengthThe window size
num_windowsint32Number of windows to retrieve

Message ListWfMetricsResponse

A list of WfSpec Metrics Windows

FieldLabelTypeDescription
resultsrepeatedWfSpecMetricsList of WfSpec Metrics Windows

Message MigrateWfSpecRequest

EXPERIMENTAL: migrate live WfRun's from one version of a WfSpec to another.

FieldLabelTypeDescription
old_wf_specWfSpecId
migrationWfSpecVersionMigration

Message NodeRunIdList

List of NodeRun Id's.

FieldLabelTypeDescription
resultsrepeatedNodeRunIdThe resulting object id's.
bookmarkoptionalbytesThe 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.

FieldLabelTypeDescription
resultsrepeatedNodeRunA list of NodeRun Objects.
bookmarkoptionalbytesThe 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.

FieldLabelTypeDescription
task_def_idTaskDefIdIs the TaskDefId that the Task Worker wants to execute.
client_idstringIs the ID of the Task Worker.
task_worker_versionoptionalstringOptionally 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.

FieldLabelTypeDescription
resultoptionalScheduledTaskIf possible, a ScheduledTask is returned.

Message PutExternalEventDefRequest

Field to create an ExternalEventDef.

FieldLabelTypeDescription
namestringThe name of the resulting ExternalEventDef.
retention_policyExternalEventRetentionPolicyPolicy to determine how long an ExternalEvent is retained after creation if it is not yet claimed by a WfRun. Note that once a WfRun has been matched with the ExternalEvent, the ExternalEvent is deleted if/when that WfRun is deleted. If not set, then ExternalEvent's are not deleted if they are not matched with a WfRun.

A future version of LittleHorse will allow changing the retention_policy, which will trigger a cleanup of old ExternalEvents.

Message PutExternalEventRequest

Request used to create an ExternalEvent.

FieldLabelTypeDescription
wf_run_idWfRunIdThe ID of the WfRun that this Event is sent to.
external_event_def_idExternalEventDefIdThe ID of the ExternalEventDef that this event implements.
guidoptionalstringNote 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.
contentVariableValueThe content of this event.
thread_run_numberoptionalint32Optionally specify that this ExternalEvent may only be claimed by a specific ThreadRun.
node_run_positionoptionalint32Optionally 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.

FieldLabelTypeDescription
namestringThe name of the TaskDef to create.
input_varsrepeatedVariableDefVariables required to execute the TaskDef. Normally, these are automatically generated by the Task Worker SDK.

Message PutUserTaskDefRequest

Creates a UserTaskDef.

FieldLabelTypeDescription
namestringThe name of the UserTaskDef to create.
fieldsrepeatedUserTaskFieldThe 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.
descriptionoptionalstringOptional 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.

FieldLabelTypeDescription
namestringThe name of the resulting WfSpec.
thread_specsmapPutWfSpecRequest.ThreadSpecsEntryMap from name the ThreadSpec.
entrypoint_thread_namestringThe name of the ThreadSpec to be used as the workflow entrypoint.
retention_policyoptionalWorkflowRetentionPolicyOptional policy to determine how long a WfRun is retained in the data store after it is completed or terminated.
parent_wf_specoptionalWfSpec.ParentWfSpecReferenceParent WfSpec Reference. If this is set, then all WfRun's for this WfSpec MUST be Child WfRun's of the specified WfSpec.
allowed_updatesAllowedUpdateTypeConfigures 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

FieldLabelTypeDescription
keystring
valueThreadSpec

Message PutWorkflowEventDefRequest

EXPERIMENTAL: Creates a WorkflowEventDef

FieldLabelTypeDescription
namestring
typeVariableType

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.

FieldLabelTypeDescription
task_worker_idstringIs the ID of the Task Worker.
task_def_idTaskDefIdThe TaskDef the worker wants to poll for.
listener_namestringThe listener that the worker is polling on. Used by the server to determine which advertised hosts to return.

Message RegisterTaskWorkerResponse

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

FieldLabelTypeDescription
your_hostsrepeatedLHHostInfoThe list of LH Server hosts that the Task Worker should start polling.
is_cluster_healthyoptionalboolWhether the LH Cluster is healthy.

Message ReportTaskRun

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

FieldLabelTypeDescription
task_run_idTaskRunIdID of the TaskRun
timegoogle.protobuf.TimestampWhen the TaskRun was executed
statusTaskStatusStatus of the TaskRun
log_outputoptionalVariableValueOptional information for logging or exceptions
attempt_numberint32Attempt number of the TaskRun
outputoneof resultVariableValueSuccessfully completed task
erroroneof resultLHTaskErrorTechnical error
exceptiononeof resultLHTaskExceptionBusiness exception

Message ResumeWfRunRequest

Resume a WfRun.

FieldLabelTypeDescription
wf_run_idWfRunIdIs the WfRunId
thread_run_numberint32The 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.

FieldLabelTypeDescription
wf_spec_namestringThe name of the WfSpec to run.
major_versionoptionalint32Optionally 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.
revisionoptionalint32Optionally 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.
variablesmapRunWfRequest.VariablesEntryA map from Variable Name to Values for those variables. The provided variables are passed as input to the Entrypoint ThreadRun.
idoptionalstringYou 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_idoptionalWfRunId

Message RunWfRequest.VariablesEntry

FieldLabelTypeDescription
keystring
valueVariableValue

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.

FieldLabelTypeDescription
task_run_idTaskRunIdId of the TaskRun to execute.
task_def_idTaskDefIdID of the TaskDef to which the TaskRun belongs.
attempt_numberint32Attempt number of the TaskRun, zero indexed. attempt_number of 0 means this is the first attempt; 1 means this is the first retry, etc.
variablesrepeatedVarNameAndValInput variables for this TaskRun.
created_atgoogle.protobuf.Timestamp
sourceTaskRunSourceSource of the TaskRun. Currently, there are two options: 1. A TASK node 2. A reminder task scheduled by a trigger on a User Task.

Message SearchExternalEventDefRequest

Search for ExternalEventDef's.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
prefixoptionalstringOptionally search only for ExternalEventDef's whose name starts with this prefix.

Message SearchExternalEventRequest

EVOLVING: Search for ExternalEvent's.

Currently, this request allows you to search for ExternalEvent's based on either:

  1. A WfRunId
  2. An ExternalEventDefName and status.

This specific RPC is under discussions for a Refactor and will soon experience breaking changes. It is recommended for applications needing to search by WfRunId to instead use the rpc ListExternalEvents call, as we plan to remove the 'by WfRunId' option from this request.

Specifically, we plan to remove the "by wfRunId" option (which is redundant with the ListExternalEvents request), and "flatten" the "ByExtEvtDefNameAndStatusRequest" fields into the main message.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
wf_run_idoneof ext_evt_criteriaWfRunId
external_event_def_name_and_statusoneof ext_evt_criteriaSearchExternalEventRequest.ByExtEvtDefNameAndStatusRequest

Message SearchExternalEventRequest.ByExtEvtDefNameAndStatusRequest

EVOLVING: message encapsulating criteria to search for ExternalEvent's by their status and ExternalEventDefName.

FieldLabelTypeDescription
external_event_def_namestring
is_claimedoptionalbool

Message SearchNodeRunRequest

Search for NodeRun's by certain criteria.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
earliest_startoptionalgoogle.protobuf.TimestampOnly return NodeRun's created after this time.
latest_startoptionalgoogle.protobuf.TimestampOnly return NodeRun's created before this time.
node_typeSearchNodeRunRequest.NodeTypeSpecifies the type of NodeRun to search for.
statusLHStatusSpecifies the status of NodeRun to search for.

Message SearchTaskDefRequest

Search for TaskDef's based on certain criteria.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
prefixoptionalstringOptionally specify to only return TaskDef's with a specific prefix.

Message SearchTaskRunRequest

Searches for TaskRuns by various criteria.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
task_def_namestringSpecifies the TaskDef of TaskRun's to return. This is required.
statusoptionalTaskStatusSpecifies to only return TaskRun's matching this status.
earliest_startoptionalgoogle.protobuf.TimestampSpecifies to only return TaskRun's that were scheduled after this time.
latest_startoptionalgoogle.protobuf.TimestampSpecifies to only return TaskRun's that were scheduled before this time.

Message SearchTenantRequest

Search for all available TenantIds for current Principal

FieldLabelTypeDescription
limitoptionalint32Maximum results to return in one request.
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.

Message SearchUserTaskDefRequest

Search for UserTaskDef's.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
prefixoneof user_task_def_criteriastringReturn all UserTaskDef's with a specific prefix.
nameoneof user_task_def_criteriastringReturn 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.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
statusoptionalUserTaskRunStatusStatus of UserTaskRun's to return.
user_task_def_nameoptionalstringUserTaskDef name to search for.
user_idoptionalstringSearch for UserTaskRun's assigned to this user id.
user_groupoptionalstringSearch for UserTaskRun's assigned to this user group.
earliest_startoptionalgoogle.protobuf.TimestampSearch for UserTaskRun's that were created after this time.
latest_startoptionalgoogle.protobuf.TimestampSearch 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.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
valueVariableValueSpecifies the value that the variable must be. Exact match is required.
wf_spec_major_versionoptionalint32Specifies major version of the WfSpec for the associated WfRun.
wf_spec_revisionoptionalint32Specifies the revision of the WfSpec for the associated WfRun.
var_namestringSpecifies the name of the variable to search for. This is required.
wf_spec_namestringSpecifies 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.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
wf_spec_namestringThe WfSpec whose WfRun's we are searching for. This is required.
wf_spec_major_versionoptionalint32Specifies to return only WfRun's from this WfSpec Major Version.
wf_spec_revisionoptionalint32Specifies to return only WfRun's from this WfSpec Revision. Can only be set if wf_spec_major_version is also set.
statusoptionalLHStatusSpecifies to return only WfRun's matching this status.
earliest_startoptionalgoogle.protobuf.TimestampSpecifies to return only WfRun's that started after this time
latest_startoptionalgoogle.protobuf.TimestampSpecifies to return only WfRun's that started before this time
variable_filtersrepeatedVariableMatchAllows 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.

FieldLabelTypeDescription
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.
limitoptionalint32Maximum results to return in one request.
nameoneof wf_spec_criteriastringReturn WfSpec's with a specific name.
prefixoneof wf_spec_criteriastringReturn WfSpec's with a specific prefix.
task_def_nameoneof wf_spec_criteriastringReturn all WfSpec's that make use of a given TaskDef.

Message ServerVersionResponse

The version of the LH Server according to Semantic Versioning

FieldLabelTypeDescription
major_versionint32Server Major Version
minor_versionint32Server Minor Version
patch_versionint32Server Patch Version
pre_release_identifieroptionalstringPrerelease 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.

FieldLabelTypeDescription
wf_run_idWfRunIdIs the WfRunId
thread_run_numberint32The 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.

FieldLabelTypeDescription
resultsrepeatedTaskDefIdThe resulting object id's.
bookmarkoptionalbytesThe 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.

FieldLabelTypeDescription
task_def_idTaskDefIdTaskDef that the metrics apply to.
window_startgoogle.protobuf.TimestampWhen the window started.
typeMetricsWindowLengthLength of the window.
schedule_to_start_maxint64Longest time that a TaskRun was in the TASK_SCHEDULED state
schedule_to_start_avgint64Average time that a TaskRun was in the TASK_SCHEDULED state
start_to_complete_maxint64Longest time between a TaskRun being started and completed
start_to_complete_avgint64Average time between a TaskRun being started and completed
total_completedint64Total number of TaskRun's that reached the TASK_SUCCESS state
total_erroredint64Total number of TaskRun's that reached the TASK_ERROR state
total_startedint64Total number of TaskRun's that transitioned to the TASK_RUNNING state
total_scheduledint64Total number of TaskRun's that were scheduled

Message TaskDefMetricsQueryRequest

Query to retrieve a specific TaskDef Metrics Window.

FieldLabelTypeDescription
window_startgoogle.protobuf.TimestampReturn the window containing this timestamp. The window start is not guaranteed to align perfectly with the request.
window_typeMetricsWindowLengthThe window size
task_def_nameoptionalstringThe name of the specific TaskDef for which we are calculating metrics.

Message TaskRunIdList

List of TaskRun ID's.

FieldLabelTypeDescription
resultsrepeatedTaskRunIdThe resulting object id's.
bookmarkoptionalbytesThe 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

FieldLabelTypeDescription
resultsrepeatedTaskRunA list of TaskRun Objects

Message TaskWorkerGroup

Describes all workers registered for a specific TaskDef.

FieldLabelTypeDescription
idTaskWorkerGroupIdIdentifier for the group.
created_atgoogle.protobuf.TimestampTimestamp indicating when the worker group was initially registered.
task_workersmapTaskWorkerGroup.TaskWorkersEntryMetadata grouped by ClientId string.

Message TaskWorkerGroup.TaskWorkersEntry

FieldLabelTypeDescription
keystring
valueTaskWorkerMetadata

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.

FieldLabelTypeDescription
client_idstring
task_def_idTaskDefId
listener_namestring

Message TaskWorkerMetadata

Describes a specific task worker

FieldLabelTypeDescription
task_worker_idstringUser-defined identifier for the worker.
latest_heartbeatgoogle.protobuf.TimestampTimestamp indicating the last heartbeat sent by the worker.
hostsrepeatedLHHostInfoThe host(s) where the worker is polling tasks

Message TenantIdList

FieldLabelTypeDescription
resultsrepeatedTenantIdThe resulting object id's.
bookmarkoptionalbytesBookmark for cursor-based pagination; pass if applicable.

Message UserTaskDefIdList

List of UserTaskDef Id's.

FieldLabelTypeDescription
resultsrepeatedUserTaskDefIdThe resulting object id's.
bookmarkoptionalbytesThe 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

FieldLabelTypeDescription
resultsrepeatedUserTaskRunIdThe resulting object id's.
bookmarkoptionalbytesThe 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

FieldLabelTypeDescription
resultsrepeatedUserTaskRunA list of UserTaskRun Objects

Message VariableIdList

This is a list of Variable ID's.

FieldLabelTypeDescription
resultsrepeatedVariableIdThe resulting object id's.
bookmarkoptionalbytesThe 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.

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

FieldLabelTypeDescription
var_namestringThe name of the variable to inspect.
valueVariableValueThe value that the Variable must have in order to satisfy this VariableMatch

Message WfRunIdList

List of WfRun Id's

FieldLabelTypeDescription
resultsrepeatedWfRunIdThe resulting object id's.
bookmarkoptionalbytesThe 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.

FieldLabelTypeDescription
resultsrepeatedWfSpecIdThe resulting object id's.
bookmarkoptionalbytesThe 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

FieldLabelTypeDescription
wf_spec_idWfSpecIdThe WfSpecId that these metrics analyze
window_startgoogle.protobuf.TimestampThe time that the window started
typeMetricsWindowLengthThe length of the window
total_startedint64Total number of WfRun's created for this WfSpec
total_completedint64Total number of WfRun's that reached the COMPLETED state
total_erroredint64Total number of WfRun's that reached the ERROR state
start_to_complete_maxint64Longest time between a WfRun being started and reaching the COMPLETED state
start_to_complete_avgint64Average time that a WfRun took to reach the COMPLETED state

Message WfSpecMetricsQueryRequest

Query to retrieve a specific WfSpec Metrics Window.

FieldLabelTypeDescription
wf_spec_idWfSpecIdWfSpecId of metrics to get.
window_startgoogle.protobuf.TimestampReturn the window containing this timestamp. The window start is not guaranteed to align perfectly with the request.
window_lengthMetricsWindowLengthThe window size

Message TaskDef

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

FieldLabelTypeDescription
idTaskDefIdThe ID of this TaskDef.
input_varsrepeatedVariableDefThe input variables required to execute this TaskDef.
created_atgoogle.protobuf.TimestampThe time at which this TaskDef was created.

Message LHTaskError

Message denoting a TaskRun failed for technical reasons.

FieldLabelTypeDescription
typeLHErrorTypeThe technical error code.
messagestringHuman 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'.

FieldLabelTypeDescription
namestringThe user-defined Failure name, for example, "credit-card-declined"
messagestringHuman readadble description of the failure.
contentVariableValue

Message TaskAttempt

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

FieldLabelTypeDescription
log_outputoptionalVariableValueOptional 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_timeoptionalgoogle.protobuf.TimestampThe 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_timeoptionalgoogle.protobuf.TimestampThe time the TaskAttempt was pulled off the queue and sent to a TaskWorker.
end_timeoptionalgoogle.protobuf.TimestampThe time the TaskAttempt was finished (either completed, reported as failed, or timed out)
task_worker_idstringEXPERIMENTAL: the ID of the Task Worker who executed this TaskRun.
task_worker_versionoptionalstringThe version of the Task Worker that executed the TaskAttempt.
statusTaskStatusThe status of this TaskAttempt.
outputoneof resultVariableValueDenotes the Task Function executed properly and returned an output.
erroroneof resultLHTaskErrorAn unexpected technical error was encountered. May or may not be retriable.
exceptiononeof resultLHTaskExceptionThe Task Function encountered a business problem and threw a technical exception.

Message TaskNodeReference

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

FieldLabelTypeDescription
node_run_idNodeRunIdThe ID of the NodeRun which caused this TASK to be scheduled.

Message TaskRun

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

FieldLabelTypeDescription
idTaskRunIdThe ID of the TaskRun. Note that the TaskRunId contains the WfRunId.
task_def_idTaskDefIdThe ID of the TaskDef being executed.
attemptsrepeatedTaskAttemptAll 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_variablesrepeatedVarNameAndValThe 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.
sourceTaskRunSourceThe 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_atgoogle.protobuf.TimestampWhen the TaskRun was scheduled.
statusTaskStatusThe status of the TaskRun.
timeout_secondsint32The timeout before LH considers a TaskAttempt to be timed out.
total_attemptsint32The maximum number of attempts that may be scheduled for this TaskRun. NOTE: setting total_attempts to 1 means that there are no retries.
exponential_backoffoptionalExponentialBackoffRetryPolicyOptional backoff policy .

Message TaskRunSource

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

FieldLabelTypeDescription
task_nodeoneof task_run_sourceTaskNodeReferenceReference to a NodeRun of type TASK which scheduled this TaskRun.
user_task_triggeroneof task_run_sourceUserTaskTriggerReferenceReference to the specific UserTaskRun trigger action which scheduled this TaskRun
wf_spec_idoptionalWfSpecIdThe 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.

FieldLabelTypeDescription
var_namestringThe variable name.
valueVariableValueThe value of the variable for this TaskRun.

Message AssignUserTaskRunRequest

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

FieldLabelTypeDescription
user_task_run_idUserTaskRunIdThe UserTaskRun to assign to a new user_id or user_group.
override_claimboolIf 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_groupoptionalstringThe 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_idoptionalstringThe 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.

FieldLabelTypeDescription
user_task_run_idUserTaskRunIdThe id of the UserTaskRun to cancel.

Message CompleteUserTaskRunRequest

Completes a UserTaskRun with provided values.

FieldLabelTypeDescription
user_task_run_idUserTaskRunIdThe id of UserTaskRun to complete.
resultsmapCompleteUserTaskRunRequest.ResultsEntryA map from UserTaskField.name to a VariableValue containing the results of the user filling out the form.
user_idstringThe ID of the user who executed the task.

Message CompleteUserTaskRunRequest.ResultsEntry

FieldLabelTypeDescription
keystring
valueVariableValue

Message UserTaskDef

UserTaskDef is the metadata blueprint for UserTaskRuns.

FieldLabelTypeDescription
namestringThe name of the UserTaskDef
versionint32The version of the UserTaskDef. Only simple versioning is supported.
descriptionoptionalstringMetadata 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.
fieldsrepeatedUserTaskFieldThese 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_atgoogle.protobuf.TimestampThe time the UserTaskRun was created.

Message UserTaskEvent

This is an event stored in the audit log of a UserTaskRun purely for observability purposes.

FieldLabelTypeDescription
timegoogle.protobuf.Timestampthe time the event occurred.
task_executedoneof eventUserTaskEvent.UTETaskExecutedDenotes that a TaskRun was scheduled via a trigger.
assignedoneof eventUserTaskEvent.UTEAssignedDenotes that the UserTaskRun was assigned.
cancelledoneof eventUserTaskEvent.UTECancelledDenotes that the UserTaskRun was cancelled.

TODO: Add "save user task" and "complete user task" to the audit log

Message UserTaskEvent.UTEAssigned

Message denoting that the UserTaskRun was assigned.

FieldLabelTypeDescription
old_user_idoptionalstringThe user_id before the ownership change, if set.
old_user_groupoptionalstringThe user_group before the ownership change, if set.
new_user_idoptionalstringThe user_id after the ownership change, if set.
new_user_groupoptionalstringThe user_group after the ownership change, if set.

Message UserTaskEvent.UTECancelled

Empty message used to denote that the UserTaskRun was cancelled.

FieldLabelTypeDescription
messagestring

Message UserTaskEvent.UTETaskExecuted

Message to denote that a TaskRun was scheduled by a trigger for this UserTaskRun.

FieldLabelTypeDescription
task_runTaskRunIdThe TaskRunId of the scheduled TaskRun

Message UserTaskField

A UserTaskField is a specific field of data to be entered into a UserTaskRun.

FieldLabelTypeDescription
namestringThe 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.
typeVariableTypeThe type of the output. Must be a primitive type (STR, BOOL, INT, DOUBLE).
descriptionoptionalstringOptional description which can be displayed by the User Task UI application. Does not affect WfRun execution.
display_namestringThe name to be displayed by the User Task UI application. Does not affect WfRun execution.
requiredboolWhether 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.

FieldLabelTypeDescription
idUserTaskRunIdThe ID of the UserTaskRun.
user_task_def_idUserTaskDefIdThe ID of the UserTaskDef that this UserTaskRun comes from.
user_groupoptionalstringDenotes 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_idoptionalstringDenotes 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.
resultsmapUserTaskRun.ResultsEntryThe 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.
statusUserTaskRunStatusStatus of the UserTaskRun. Can be UNASSIGNED, ASSIGNED, DONE, or CANCELLED.
eventsrepeatedUserTaskEventA list of events that have happened. Used for auditing information.
notesoptionalstringNotes 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_timegoogle.protobuf.TimestampThe time that the UserTaskRun was created/scheduled.
node_run_idNodeRunIdThe NodeRun with which the UserTaskRun is associated.
epochint32Current 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

FieldLabelTypeDescription
keystring
valueVariableValue

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.

FieldLabelTypeDescription
node_run_idNodeRunIdIs the NodeRun that the UserTaskRun belongs to.
user_task_event_numberint32Is the index in the events field of the UserTaskRun that the TaskRun corresponds to.
user_idoptionalstringIs the user_id that the UserTaskRun is assigned to. Unset if UserTaskRun is not asigned to a specific user_id.
user_groupoptionalstringIs the user_id that the UserTaskRun is assigned to. Unset if UserTaskRun is not asigned to a specific user_id.

Message Variable

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

FieldLabelTypeDescription
idVariableIdID of this Variable. Note that the VariableId contains the relevant WfRunId inside it, the threadRunNumber, and the name of the Variabe.
valueVariableValueThe value of this Variable.
created_atgoogle.protobuf.TimestampWhen the Variable was created.
wf_spec_idWfSpecIdThe ID of the WfSpec that this Variable belongs to.

Message VariableValue

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

FieldLabelTypeDescription
json_objoneof valuestringA String representing a serialized json object.
json_arroneof valuestringA String representing a serialized json list.
doubleoneof valuedoubleA 64-bit floating point number.
booloneof valueboolA boolean.
stroneof valuestringA string.
intoneof valueint64A 64-bit integer.
bytesoneof valuebytesAn arbitrary String of bytes.

Message FailureBeingHandled

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

FieldLabelTypeDescription
thread_run_numberint32The thread run number.
node_run_positionint32The position of the NodeRun causing the failure.
failure_numberint32The number of the failure.

Message HandlingFailureHaltReason

A Halt Reason denoting that a ThreadRun is halted while a Failure Handler is being run.

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

FieldLabelTypeDescription
interrupt_thread_idint32The ID of the Interrupt Handler ThreadRun.

Message ManualHalt

A Halt Reason denoting that a ThreadRun was halted manually, via the rpc StopWfRun request.

FieldLabelTypeDescription
meaning_of_lifeboolNothing to store.

Message ParentHalted

A Halt Reason denoting that a ThreadRun is halted because its parent is also HALTED.

FieldLabelTypeDescription
parent_thread_idint32The ID of the halted parent.

Message PendingFailureHandler

Represents a Failure Handler that is pending to be run.

FieldLabelTypeDescription
failed_thread_runint32The ThreadRun that failed.
handler_spec_namestringThe 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.

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

FieldLabelTypeDescription
external_event_idExternalEventIdThe ID of the ExternalEvent triggering the Interrupt.
handler_spec_namestringThe name of the ThreadSpec to run to handle the Interrupt.
interrupted_thread_idint32The 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.

FieldLabelTypeDescription
external_event_idExternalEventIdThe ExternalEventId that caused the Interrupt.

Message ThreadHaltReason

Denotes a reason why a ThreadRun is halted. See ThreadRun.halt_reasons for context.

FieldLabelTypeDescription
parent_haltedoneof reasonParentHaltedParent threadRun halted.
interruptedoneof reasonInterruptedHandling an Interrupt.
pending_interruptoneof reasonPendingInterruptHaltReasonWaiting to handle Interrupt.
pending_failureoneof reasonPendingFailureHandlerHaltReasonWaiting to handle a failure.
handling_failureoneof reasonHandlingFailureHaltReasonHandling a failure.
manual_haltoneof reasonManualHaltManually stopped the WfRun.

Message ThreadRun

A ThreadRun is a running thread of execution within a WfRun.

FieldLabelTypeDescription
wf_spec_idWfSpecIdThe 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.
numberint32The 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.
statusLHStatusThe status of the ThreadRun.
thread_spec_namestringThe name of the ThreadSpec being run.
start_timegoogle.protobuf.TimestampThe time the ThreadRun was started.
end_timeoptionalgoogle.protobuf.TimestampThe time the ThreadRun was completed or failed. Unset if still active.
error_messageoptionalstringHuman-readable error message detailing what went wrong in the case of a failure.
child_thread_idsrepeatedint32List of thread_run_number's for all child thread_runs.
parent_thread_idoptionalint32Set for every ThreadRun except the ENTRYPOINT. This is the id of the parent thread.
halt_reasonsrepeatedThreadHaltReasonIf 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_idoptionalExternalEventIdIf this ThreadRun is of type INTERRUPT_HANDLER, this field is set to the ID of the ExternalEvent that caused the Interrupt.
failure_being_handledoptionalFailureBeingHandledIf this ThreadRun is of type FAILURE_HANDLER, this field is set to the exact Failure that is being handled by this ThreadRun.
current_node_positionint32This 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_childrenrepeatedint32List 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.
typeThreadTypeThe Type of this ThreadRun.

Message WfRun

A WfRun is a running instance of a WfSpec.

FieldLabelTypeDescription
idWfRunIdThe ID of the WfRun.
wf_spec_idWfSpecIdThe ID of the WfSpec that this WfRun belongs to.
old_wf_spec_versionsrepeatedWfSpecIdWhen 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.
statusLHStatusThe status of this WfRun.
greatest_threadrun_numberint32The 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_timegoogle.protobuf.TimestampThe time the WfRun was started.
end_timeoptionalgoogle.protobuf.TimestampThe time the WfRun failed or completed.
thread_runsrepeatedThreadRunA list of all active ThreadRun's and terminated ThreadRun's whose retention periods have not yet expired.
pending_interruptsrepeatedPendingInterruptA list of Interrupt events that will fire once their appropriate ThreadRun's finish halting.
pending_failuresrepeatedPendingFailureHandlerA 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.

FieldLabelTypeDescription
sink_node_namestringThe name of the Node that the Edge points to.
conditionoptionalEdgeConditionThe 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_mutationsrepeatedVariableMutationOrdered 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.

FieldLabelTypeDescription
comparatorComparatorThe Operator used to evaluate the left versus the right.
leftVariableAssignmentThe left side of the boolean expression.
rightVariableAssignmentThe 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.

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

FieldLabelTypeDescription
external_event_def_idExternalEventDefIdThe ID of the ExternalEventDef that we are waiting for.
timeout_secondsVariableAssignmentDetermines the maximum amount of time that the NodeRun will wait for the ExternalEvent to arrive.

Message FailureDef

Defines a Failure that can be thrown.

FieldLabelTypeDescription
failure_namestringThe 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.
messagestringHuman-readable message denoting why the Failure occurred.
contentoptionalVariableAssignmentIf 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.

FieldLabelTypeDescription
handler_spec_namestringThe name of the ThreadSpec to run as a
specific_failureoneof failure_to_catchstringSpecifies 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_typeoneof failure_to_catchFailureHandlerDef.LHFailureTypeSpecifies 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.

FieldLabelTypeDescription
external_event_def_idExternalEventDefIdThe 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_namestringThe 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.

FieldLabelTypeDescription
field_pathstringDenotes the path in JSONPath format (according to the Java Jayway library) that has a field we should index.
field_typeVariableTypeIs the type of the field we are indexing.

Message Node

A Node is a step in a ThreadRun.

FieldLabelTypeDescription
outgoing_edgesrepeatedEdgeDefines the flow of execution and determines where the ThreadRun goes next.
failure_handlersrepeatedFailureHandlerDefSpecifies 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.
entrypointoneof nodeEntrypointNodeCreates an EntrypointRun. Every ThreadRun has one Entrypoint node.
exitoneof nodeExitNodeCreates an `ExitRun``. Every ThreadSpec has at least one Exit Node.
taskoneof nodeTaskNodeCreates a TaskNodeRUn
external_eventoneof nodeExternalEventNodeCreates an ExternalEventRun
start_threadoneof nodeStartThreadNodeCreates a StartThreadNodeRun
wait_for_threadsoneof nodeWaitForThreadsNodeCreates a WaitForThreadsNodeRun
noponeof nodeNopNodeCreates a NopNodeRun
sleeponeof nodeSleepNodeCreates a SleepNodeRun
user_taskoneof nodeUserTaskNodeCreates a UserTaskNodeRun
start_multiple_threadsoneof nodeStartMultipleThreadsNodeCreates a StartMultipleThreadsNodeRun
throw_eventoneof nodeThrowEventNodeCreates a ThrowEventNodeRun

Message NodeMigration

EXPERIMENTAL: Specification for migrating a WfRun from a Node in one WfSpec to a Node in another WfSpec version.

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

FieldLabelTypeDescription
raw_secondsoneof sleep_lengthVariableAssignmentSleeps the specified number of seconds.
timestamponeof sleep_lengthVariableAssignmentSleeps until the long timestamp (epoch millis) specified here.
iso_dateoneof sleep_lengthVariableAssignmentSleeps 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.

FieldLabelTypeDescription
thread_spec_namestringThe name of the ThreadSpec to spawn.
variablesmapStartMultipleThreadsNode.VariablesEntryVariables which are passed into the child ThreadRuns. These assignments are the same for all spawned threads.
iterableVariableAssignmentAssignment 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

FieldLabelTypeDescription
keystring
valueVariableAssignment

Message StartThreadNode

Starts a Child ThreadRun with a specific ThreadSpec.

FieldLabelTypeDescription
thread_spec_namestringThe name of the ThreadSpec to spawn.
variablesmapStartThreadNode.VariablesEntryThe input variables to pass into the Child ThreadRun.

Message StartThreadNode.VariablesEntry

FieldLabelTypeDescription
keystring
valueVariableAssignment

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.

FieldLabelTypeDescription
seconds_after_thread_terminationoneof thread_gc_policyint64Delete 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.

FieldLabelTypeDescription
nodesmapThreadSpec.NodesEntryThe Nodes inside this ThreadSpec. Maps from name to Node.
variable_defsrepeatedThreadVarDefDefines Variables that are local to ThreadRun's of this ThreadSpec.
interrupt_defsrepeatedInterruptDefDefines all interrupts for this ThreadSpec.
retention_policyoptionalThreadRetentionPolicyOptional 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

FieldLabelTypeDescription
keystring
valueNode

Message ThreadSpecMigration

EXPERIMENTAL: Specification for how to migrate a ThreadRun of a specific ThreadSpec from one WfSpec to another WfSpec version.

FieldLabelTypeDescription
new_thread_spec_namestringThe name of the ThreadSpec in the new WfSpec that this ThreadSpec should migrate to.
node_migrationsmapThreadSpecMigration.NodeMigrationsEntryMap 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

FieldLabelTypeDescription
keystring
valueNodeMigration

Message ThreadVarDef

Denotes a variable declaration at the ThreadSpec level.

FieldLabelTypeDescription
var_defVariableDefIs the actual VariableDefinition containing name and type.
requiredboolWhether the variable is required as input to the threadRun.
searchableboolWhether this variable has an index configured.
json_indexesrepeatedJsonIndexValid for JSON_OBJ and JSON_ARR variables only. List of JSON fields to index.
access_levelWfRunVariableAccessLevelThe Access Level of this variable.

Message ThrowEventNode

A SubNode that throws a WorkflowEvent of a specific type. There is no output.

FieldLabelTypeDescription
event_def_idWorkflowEventDefIdThe WorkflowEventDefId of the WorkflowEvent that is thrown
contentVariableAssignmentA 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.

FieldLabelTypeDescription
user_task_def_namestringDenotes the name of the UserTaskDef that should create the UserTaskRun.
user_groupoptionalVariableAssignmentDenotes the user_group to which the UserTaskRun is assigned upon creation.
user_idoptionalVariableAssignmentDenotes the user_id to which the UserTaskRun is assigned upon creation.
actionsrepeatedUTActionTriggerSpecifies 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_versionoptionalint32If set, then the UserTaskRun will always have this specific version of the UserTaskDef. Otherwise, the UserTaskRun will have the latest version.
notesoptionalVariableAssignmentSpecifies the value to be displayed on the notes field of the UserTaskRun.
on_cancellation_exception_nameoptionalVariableAssignmentSpecifies the name of the exception thrown when the User Task is canceled. If not set, then the cancellation or timeout of a User Task Run throws an ERROR rather than an EXCEPTION.

Message WaitForThreadsNode

Specifies that a ThreadRun will wait for certain specified Child ThreadRun's to complete or fail before the WfRun continues. If one of the Child ThreadRun's throws a Failure that is not caught by the per_thread_failure_handlers, then the Child ThreadRun's Failure is thrown by the WaitForThreadsRun.

No output.

FieldLabelTypeDescription
threadsoneof threads_to_wait_forWaitForThreadsNode.ThreadsToWaitForSpecifies that the WaitForThreadsRun will wait for the threads specified here.
thread_listoneof threads_to_wait_forVariableAssignmentSpecifies 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_handlersrepeatedFailureHandlerDefIf 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

FieldLabelTypeDescription
thread_run_numberVariableAssignmentCauses the WaitForThreadsNodeRun to wait for the ThreadRun whose number matches the value specified here. Must resolve to an INT.

Message WaitForThreadsNode.ThreadsToWaitFor

FieldLabelTypeDescription
threadsrepeatedWaitForThreadsNode.ThreadToWaitForWait 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.

FieldLabelTypeDescription
idWfSpecIdThe 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_atgoogle.protobuf.TimestampThe timestamp at which the WfSpec was created.
frozen_variablesrepeatedThreadVarDefVariables whose types cannot be changed without causing a Breaking Change between the versions.
statusMetadataStatusThe Status of the WfSpec. Currently, only ACTIVE exists. This field will be used in the future when de-commissioning a WfSpec gracefully.
thread_specsmapWfSpec.ThreadSpecsEntryThe 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_namestringThe 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_policyoptionalWorkflowRetentionPolicyOptional 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.
migrationoptionalWfSpecVersionMigrationEXPERIMENTAL: ongoing migration from one version of a WfSpec to another.
parent_wf_specoptionalWfSpec.ParentWfSpecReferenceReference 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.

FieldLabelTypeDescription
wf_spec_namestringName of the Parent WfSpec
wf_spec_major_versionint32FOR 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

FieldLabelTypeDescription
keystring
valueThreadSpec

Message WfSpecVersionMigration

EXPERIMENTAL: Specification for how to migrate an in-flight WfRun from one WfSpec to another WfSpec version.

FieldLabelTypeDescription
new_major_versionint32The major version of the WfSpec that we are migrating to.
new_revisionint32The revision of the WfSpec that we are migrating to.
thread_spec_migrationsmapWfSpecVersionMigration.ThreadSpecMigrationsEntryMap from ThreadSpec name to a specifier determining how to migrate ThreadRun's to the new version of the WfSpec.

Message WfSpecVersionMigration.ThreadSpecMigrationsEntry

FieldLabelTypeDescription
keystring
valueThreadSpecMigration

Message WorkflowRetentionPolicy

A WorkflowRetentionPolicy configures how long a WfRun is retained in the data store before being deleted after it is completed or failed.

FieldLabelTypeDescription
seconds_after_wf_terminationoneof wf_gc_policyint64Delete 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.

FieldLabelTypeDescription
idWorkflowEventIdThe ID of the WorkflowEvent. Contains WfRunId and WorkflowEventDefId.
contentVariableValueThe content of the WorkflowEvent.
created_atgoogle.protobuf.TimestampThe time that the WorkflowEvent was created.

Message WorkflowEventDef

FieldLabelTypeDescription
idWorkflowEventDefId
created_atgoogle.protobuf.Timestamp
typeVariableType

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.

NameNumberDescription
READ0Allows 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)
RUN1Allows 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_METADATA2Allows mutating metadata. For example, WRITE_METADATA over ACL_WORKFLOW allows mutating WfSpecs, and WRITE_METADATA over ACL_TASK allows mutating TaskDefs.
ALL_ACTIONS3Allows all actions related to a resource.

Enum ACLResource

Defines a resource type for ACL's.

NameNumberDescription
ACL_WORKFLOW0Refers to WfSpec and WfRun
ACL_TASK1Refers to TaskDef and TaskRun
ACL_EXTERNAL_EVENT2Refers to ExternalEventDef and ExternalEvent
ACL_USER_TASK3Refers to UserTaskDef and UserTaskRun
ACL_PRINCIPAL4Refers 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_TENANT5Refers to the Tenant resource. The ACL_TENANT permission is only valid in the global_acls field of the Principal. This is because the Tenant resource is cluste-rscoped.
ACL_ALL_RESOURCES6Refers 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_GROUP7Refers to the TaskWorkerGroup associated with a TaskDef

Enum LHErrorType

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

NameNumberDescription
CHILD_FAILURE0A child ThreadRun failed with a technical ERROR.
VAR_SUB_ERROR1Failed substituting input variables into a NodeRun.
VAR_MUTATION_ERROR2Failed mutating variables after a NodeRun successfully completed.
USER_TASK_CANCELLED3A UserTaskRun was cancelled (EVOLVING: this will become a Business EXCEPTION)
TIMEOUT4A NodeRun failed due to a timeout.
TASK_FAILURE5A TaskRun failed due to an unexpected error.
VAR_ERROR6Wrapper for VAR_SUB_ERROR and VAR_MUTATION_ERROR
TASK_ERROR7Wrapper for TASK_FALIURE and TIMEOUT
INTERNAL_ERROR8An unexpected LittleHorse Internal error occurred. This is not expected to happen.

Enum LHStatus

Status used for WfRun, ThreadRun, and NodeRun

NameNumberDescription
STARTING0
RUNNING1
COMPLETED2
HALTING3
HALTED4
ERROR5
EXCEPTION6

Enum MetadataStatus

Status of a Metadata Object, such as WfSpec or TaskDef

NameNumberDescription
ACTIVE0ACTIVE means the object can be used.
ARCHIVED1An ARCHIVED WfSpec can no longer be used to create new WfRun's, but existing WfRun's will be allowed to run to completion.
TERMINATING2A 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

NameNumberDescription
MINUTES_50
HOURS_21
DAYS_12

Enum TaskStatus

Status of a TaskRun.

NameNumberDescription
TASK_SCHEDULED0Scheduled in the Task Queue but not yet picked up by a Task Worker.
TASK_RUNNING1Picked up by a Task Worker, but not yet reported or timed out.
TASK_SUCCESS2Successfully completed.
TASK_FAILED3Task Worker reported a technical failure while attempting to execute the TaskRun
TASK_TIMEOUT4Task Worker did not report a result in time.
TASK_OUTPUT_SERIALIZING_ERROR5Task Worker reported that it was unable to serialize the output of the TaskRun.
TASK_INPUT_VAR_SUB_ERROR6Task Worker was unable to deserialize the input variables into appropriate language-specific objects to pass into the Task Function
TASK_EXCEPTION8Task Function business logic determined that there was a business exception.
TASK_PENDING9Refers 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.

NameNumberDescription
JSON_OBJ0An object represented as a json string.
JSON_ARR1A list represented as a json array string.
DOUBLE2A 64-bit floating point number.
BOOL3A boolean
STR4A string
INT5A 64-bit integer
BYTES6A byte array

Enum Comparator

Operator for comparing two values to create a boolean expression.

NameNumberDescription
LESS_THAN0Equivalent to <. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
GREATER_THAN1Equivalent to >. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
LESS_THAN_EQ2Equivalent to <=. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
GREATER_THAN_EQ3Equivalent to >=. Only valid for primitive types (no JSON_OBJ or JSON_ARR).
EQUALS4This 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.

NameNumberDescription
ON_ARRIVAL0The hook should be scheduled delay_seconds after the UserTaskRun is created. This hook only causes the action to be scheduled once.
ON_TASK_ASSIGNED1The 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.

NameNumberDescription
ASSIGN0Set the variable specified by the LHS to the value of the RHS.
ADD1Add the RHS to the LHS.
EXTEND2Append the RHS to the LHS (valid if the LHS is a STR or JSON_ARR)
SUBTRACT3Subtract the RHS from the LHS (both must be INT or DOUBLE)
MULTIPLY4Multiply the LHS by the RHS (both must be INT or DOUBLE)
DIVIDE5Divide the LHS by the RHS (both must be INT or DOUBLE)
REMOVE_IF_PRESENT6Remove any occurrences of RHS from LHS (LHS must be JSON_ARR)
REMOVE_INDEX7Remove item at index RHS from LHS (LHS must be JSON_ARR)
REMOVE_KEY8Remove 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.

NameNumberDescription
THREAD_IN_PROGRESS0The ThreadRun is in progress (i.e. not COMPLETED nor EXCEPTION nor ERROR)
THREAD_HANDLING_FAILURE1The ThreadRun failed with some failure, and the FailureHandler is running for that Failure.
THREAD_COMPLETED_OR_FAILURE_HANDLED2We 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_UNSUCCESSFUL3The 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.

NameNumberDescription
ALL_UPDATES0Allows any update: both minor (revsion) changes and breaking (majorVersion) changes are accepted
MINOR_REVISION_UPDATES1Allows only backwards-compatible changes that do not change the required input variables or the searchable variables in the WfSpec.
NO_UPDATES2Rejects any changes to the WfSpec.

Enum SearchNodeRunRequest.NodeType

This enum denotes the type of a NodeRun.

NameNumberDescription
TASK0TASK node schedules a TaskRun
EXTERNAL_EVENT1EXTERNAL_EVENT blocks the ThreadRun until a specified ExternalEvent arrives
ENTRYPOINT2ENTRYPOINT kicks off a ThreadRun
EXIT3EXIT completes a ThreadRun
START_THREAD4START_THREAD creates a Child ThreadRun
WAIT_THREADS5WAIT_THREADS waits for one or more child ThreadRuns to complete
SLEEP6SLEEP makes the ThreadRun sleep for a specified time
USER_TASK7USER_TASK creates a UserTaskRun and blocks until the UserTaskRun is completed.
START_MULTIPLE_THREADS8START_MULTIPLE_THREADS iterates over a list and starts a Child Thread for each item

Enum UserTaskRunStatus

The status that a UserTaskRun can be in.

NameNumberDescription
UNASSIGNED0Not assigned to a specific user yet.
ASSIGNED1Assigned to a specific user, but not completed or cancelled yet.
DONE3Done.
CANCELLED4Cancelled.

Enum ThreadType

The type of a ThreadRUn.

NameNumberDescription
ENTRYPOINT0The ENTRYPOINT ThreadRun. Exactly one per WfRun. Always has number == 0.
CHILD1A ThreadRun explicitly created by another ThreadRun via a START_THREAD or START_MULTIPLE_THREADS NodeRun.
INTERRUPT2A ThreadRun that was created to handle an Interrupt.
FAILURE_HANDLER3A ThreadRun that was created to handle a Failure.

Enum FailureHandlerDef.LHFailureType

Specifies a type of Failure

NameNumberDescription
FAILURE_TYPE_ERROR0FAILURE_TYPE_ERROR specifies any technical ERROR.
FAILURE_TYPE_EXCEPTION1Specifies a user-defined, business-related EXCEPTION.

Enum WfRunVariableAccessLevel

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

NameNumberDescription
PUBLIC_VAR0A PUBLIC_VAR can be accessed (read + mutated) by child WfRun's.
PRIVATE_VAR1A PRIVATE_VAR cannot be accessed by a child WfRun.
INHERITED_VAR2An 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.