Iterator (ITERATOR)

Takes a list and runs the modules on Item once for every entry, in order. When all entries are done, it runs the modules on Done once.

Category: Flow Control · Deployed: yes · Tool-capable: no

Ports

Port Kind Purpose

Collection (in_collection)

Input

The list to go through. It must be a JSON list, for example ["a", "b"] or [{…}, {…}]

Item (out_item)

Output

Runs once per entry, with that entry as its input

Done (out_done)

Output

Runs once, after the last entry

Properties

Field Required Meaning

Done Message (doneMessage)

Yes

The text passed to Done after the last entry — or right away when the list is empty

If Done Message is empty, the app does not let you assign the pipeline to an agent, and the module shows a warning on the canvas.

How it runs

  • The entries run one after another, in the order of the list. The next entry starts when everything on Item has finished for the current one.

  • An entry that is a text arrives on Item as plain text. Any other entry (an object, a number, a list) arrives as JSON.

  • Done gets only the Done Message. It does not get the results of the entries.

  • An empty list [] runs nothing on Item and goes straight to Done.

  • Anything that is not a JSON list stops the run with an error. This includes plain text and a single JSON object.

Use cases

  • Row by row: SQL Database → Iterator → Item → Agent, one row at a time.

  • Piece by piece: Text Splitter → Iterator → Item → the work for each piece.

  • A closing step: the per-entry work on Item, and on Done a message that the batch is finished.

Notes

  • Item runs many times, Done runs once. Putting the per-entry work on Done, or the closing step on Item, is the usual mistake.

  • Every entry costs time and money when Item contains model calls. A list of 100 entries means 100 runs of everything on Item.

  • Not the same as Loop: Iterator goes once through a list it was given. Loop repeats the same steps until a check passes.