Skip to main content

Running a Workflow

You can run a WfSpec, thus creating a WfRun, in two ways:

  1. Using a grpc client in an SDK of your choice.
  2. Using lhctl.

For a tutorial on running a WfSpec to create a WfRun using lhctl, see the lhctl docs.

Simple

The most basic way to run a WfRun is as follows. This will run the latest version of the WfSpec with the provided name.

LittleHorseBlockingStub client = ...;

WfRun result = client.runWf(RunWfRequest.newBuilder().setWfSpecName("some-wf-spec").build());

Pinning to a Major Version

As a consumer of a WfSpec, an application may wish to pin to a specific majorVersion in order to allow the owner of the WfSpec to evolve the WfSpec in a compatible manner (i.e. without changing the exposed input variables or searchable variables). You can do this by providing the majorVersion flag. When you run a WfSpec and specify the majorVersion, the resulting WfRun will be a member of the WfSpec with the provided name and majorVersion and the latest revision that is still compatible with that majorVersion.

LittleHorseBlockingStub client = ...;

WfRun result = client.runWf(RunWfRequest.newBuilder()
.setWfSpecName("some-wf-spec")
.setMajorVersion(2)
.build());

Pinning the Revision

You can also pin the exact revision as follows, thus guaranteeing the exact WfSpec that is run:

LittleHorseBlockingStub client = ...;

WfRun result = client.runWf(RunWfRequest.newBuilder()
.setWfSpecName("some-wf-spec")
.setMajorVersion(2)
.setRevision(1)
.build());

Passing the ID

You can pass the wfRunId in the RunWfRequest to pre-specify the ID of a WfRun. We recommend you always do this as a best practice because:

  1. This makes your requests idempotent and safe to retry, because LittleHorse guarantees that only one WfRun can exist with a given ID.
  2. Specifying an ID makes it easier to correlate ExternalEvents or records in a database.

To do so, just set the Id field in the RunWfRequest proto.

LittleHorseBlockingStub client = ...;

WfRun result = client.runWf(RunWfRequest.newBuilder()
.setWfSpecName("some-wf-spec")
.setId("my-wfrun-id")
.build());

Parameters

You can pass variables into a WfRun. To do so, set the variables field on the RunWfRequest.

In Java, the LHLibUtil#objToVarVal method is a useful convenience function to convert any object into a VariableValue.

LittleHorseBlockingStub client = ...;

WfRun result = client.runWf(RunWfRequest.newBuilder()
.setWfSpecName("some-wf-spec")
.putVariables("my-int-var", LHLibUtil.objToVarVal(1234))
.putVariables("my-str-var", LHLibUtil.objToVarVal("asdf"))
.build());

Scheduling

You can schedule WfRuns using Cron expressions.

LittleHorseBlockingStub client = ...;

ScheduledWfRun result = client.scheduleWf(ScheduleWfRequest.newBuilder()
.setWfSpecName("some-wf-spec")
.setMajorVersion(0)
.setRevision(2)
.setCronExpression("5 4 * * *")
.putVariables("my-int-var", LHLibUtil.objToVarVal(1234))
.build());

Note that you are not required to pick a WfSpec version; if you don't, the most current version will be used for every run.