Building flows

A straight line

The simplest useful flow is a straight line: something comes in, an agent works on it, something comes out. This page builds one for release notes, then gives the agent a reference to follow and the flow's context.

Decide where the input comes from

A run starts with nothing, so the first question is always: what does a run work on, and who provides it? Here a person names the release. That makes the first step a human process that fills in an object.

1. Create the flow and its first step

   Create a flow called Release notes. Add a process named Pick release and set its Type to Human. Drag from Start onto it.

2. Shape what the person enters

   Press + under Pick release and name the object Release. In its settings, add two attributes: version (“The version being released, such as 4.12.0.”) and previous (“The version released before it, to compare against.”). The person now gets a form with those two fields.

3. Say who does it

   Drag a Person from the sidebar and name it Release manager, then link it to Pick release. The link ends in a filled circle: Release manager handles Pick release.

Add the agent

1. Add Draft

   Press + under Release and name the process Draft. It is an agent. Give it a prompt that names its inputs as the board does and says what good looks like:

   Write release notes for the Release, covering every pull request
   merged between the previous version's tag and the new one. Group
   them under Features, Fixes and Internal. One line each, in plain
   language a customer understands; link the pull request.

2. Add its output

   Press + under Draft and name the object Notes. It has no attributes, so the agent hands in a single value: the text of the notes.

3. Give it the code

   For the agent to read the merged pull requests, open the flow's Settings and add the repository under Repositories. Each run then works on a branch of its own in a checkout of it. See Workspaces and git.

Give it a reference

Add an object Style guide, link it to Draft, select the link and choose instrument. The agent is told it is a reference not to change. Something in the run must still provide it, such as Pick release filling it in too or a script reading it from the repository: an object nothing generates is empty in a run.

Tell the agent about the flow

In Draft's settings, tick Tell it about the flow it works in, in OPL. Its prompt then includes the whole flow as sentences, so it knows where its step fits: who will read the notes, and what happens to them next.

Check it and run it

Open OPL and read the flow back. Then press Run, fill in the release when asked, and watch Draft work.

Next, have someone approve the notes before anything is posted: People in the loop.