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.

Java

LittleHorseBlockingStub client = ...;

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

Go

config := littlehorse.NewConfigFromEnv()
client, _ := config.GetGrpcClient()

result, err := (*client).RunWf(context.Background(), &lhproto.RunWfRequest{
    WfSpecName: "some-wf-spec",
})

Python

config = LHConfig()
stub = config.stub()
stub.RunWf(RunWfRequest(wf_spec_name="some-wf-spec"))

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.

Java

LittleHorseBlockingStub client = ...;

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

Go

config := littlehorse.NewConfigFromEnv()
client, _ := config.GetGrpcClient()

var version int32
version = 2

result, err := (*client).RunWf(context.Background(), &lhproto.RunWfRequest{
    WfSpecName:   "some-wf-spec",
    MajorVersion: &version,
})

Python

config = LHConfig()
stub = config.stub()
stub.RunWf(RunWfRequest(wf_spec_name="some-wf-spec", majorVersion=2))

Pinning the Revision

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

Java

LittleHorseBlockingStub client = ...;

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

Go

config := littlehorse.NewConfigFromEnv()
client, _ := config.GetGrpcClient()

var version int32
version = 2
var revision int32
revision = 1

result, err := (*client).RunWf(context.Background(), &lhproto.RunWfRequest{
    WfSpecName:   "some-wf-spec",
    MajorVersion: &version,
    Revision:     &revision,
})

Python

config = LHConfig()
stub = config.stub()
stub.RunWf(RunWfRequest(wf_spec_name="some-wf-spec", majorVersion=2, revision=1))

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.

Java

LittleHorseBlockingStub client = ...;

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

Go

config := littlehorse.NewConfigFromEnv()
client, _ := config.GetGrpcClient()

var wfRunId string
wfRunId = "my-wfrun-id"

result, err := (*client).RunWf(context.Background(), &lhproto.RunWfRequest{
    WfSpecName: "some-wf-spec",
    Id:         &wfRunId,
})

Python

config = LHConfig()
stub = config.stub()
stub.RunWf(RunWfRequest(wf_spec_name="some-wf-spec", id="my-wfrun-id"))

Parameters

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

Java

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());

Go

The Go SDK has a useful littlehorse.InterfaceToVarVal() function which converts an arbitrary Go interface into a VariableValue.

config := littlehorse.NewConfigFromEnv()
client, _ := config.GetGrpcClient()

var wfRunId string
wfRunId = "my-wfrun-id"

stringVar, err := littlehorse.InterfaceToVarVal("some-string")
intVar, err := littlehorse.InterfaceToVarVal(1234)

result, err := (*client).RunWf(context.Background(), &lhproto.RunWfRequest{
	WfSpecName: "some-wf-spec",
	Variables: map[string]*lhproto.VariableValue{
		"my-string-var": stringVar,
		"my-int-var": intVar,
	},
})

Python

In python you can use littlehorse.to_variable_value() utility.

config = LHConfig()
stub = config.stub()
request = RunWfRequest(
    wf_spec_name="some-wf-spec",
    id="my-wfrun-id",
    variables={
        "my-string-var": littlehorse.to_variable_value("ABCD"),
        "my-int-var": littlehorse.to_variable_value(1234),
    },
)
stub.RunWf(request)