Basics
Workflows are a sequence of actions that are triggered by events, configured by the user and executed asynchronously. Each action can have inputs and outputs.
The simplest workflow has no actions and does nothing.
local Workflow = require "porla.Workflow"
return Workflow:new{
on = "TorrentAdded"
actions = {}
}
Events
There are a few events you can use that will trigger a workflow.
TorrentAdded
- the workflow will run for each torrent that is added to the session.TorrentFinished
- the workflow will run for each torrent that finishes downloading.
Inputs
Action inputs Lua tables that the user provides. For the Log action the input
is a table with a single message
key.
Log:new{
message = "Some log message"
}
Inputs can be more advanced as well, and many inputs that take a value can also take a function that returns a value in order for the action to be configured by the context.
Context
A workflow is associated with a context that provides state for the currently executing workflow instance. The context is a Lua table with some pre-defined properties.
The actions
property, for example, is an array of all previous action outputs
and can be accessed by subsequent actions.
Further, each event may set specific context properties - such as the various
torrent events. These set the torrent
context, which allows you to query for
torrent information.
For example, accessing the torrent
context requires you to use a function
when rendering a log message. This function gets passed the context and should
return a string with the message to be rendered.
Log:new{
message = function(ctx)
return string.format("%s", ctx.torrent.name)
end
}
Outputs
Some actions produce output. These outputs can be accessed in the actions
context property. This property is an array of Lua objects. Refer to each
actions own documentation to see the output they produce.
For example, combining the Exec
and Log
action to log the output of the
process.
Exec:new{
file = "/usr/bin/curl",
args = {"http://ip-api.com/json/"}
},
Log:new{
message = function(ctx)
return string.format("IP-API output: %s", ctx.actions[1].std_out)
end
}
Remember that Lua arrays generally start at index 1, which is also true for
the actions
output array.