Each workflow instance maintains state to capture the progress of the work between steps. The input and output state data for every step is schematized – it has an expected structure.
If you are familiar with database applications, you might think of each workflow request being associated with a "structured database row" that gradually gets filled in as the workflow process is executed. For example, an expense report approval workflow might have structured state like this:
Input: EmployeeName, ExpenseDate, ExpenseReceipt
Step 1 (“Get Details”): ExpenseTotal, LineItems, Taxes
Step 2 (“Categorization”): ExpenseCategory
Step 3 (“Approval/Rejection”): ApprovalDecision
Each workflow instance is represented by a “row” with 8 properties (EmployeeName, ExpenseDate, ExpenseReceipt, ExpenseTotal, LineItems, Taxes, ExpenseCategory, ApprovalDecision)
When you open Work Items in the Run section of the left pane, you will see a familiar tabular view of all the work items (workflow instances). The AI Task column is the current step's live chip — Working, Waiting, Waiting for tool, and the rest — not the work item's Status. See What Working, Waiting, and Waiting for tool mean. If you move the mouse over a column header, you will see a column menu (“three vertical dots”). Choose Column properties to see and change the definition of that state property, Add column to add a new property, or Delete column to remove one. Built-in columns such as Name and Status cannot be deleted. To filter, add, download, or act on work items from this list, see How to work with your work items list.
Once you have filtered this tabular view down to the rows you care about, you can save that view as a named report and reopen or share it later. See How to save a report from your work items.
The “schema” or structure of each of these properties is important because it provides important control information to the AI agent. “ExpenseReceipt” is not just any arbitrary data. You may know it will be a link to a file. You might know that you expect it to be a PDF file. You might know that it contains receipts for expenses in USD. Now, when your AI agent needs to look at and understand a receipt in Step 1, it can do a better job because it knows to expect a PDF file with expenses in a particular currency.
Likewise, the ExpenseCategory may not be arbitrary. Your company may have six specific categories and listing those makes the structure much more specific. Now when your AI agent needs to categorize the expense in Step 2, it will only choose from one of the enumerated categories.
More schematization leads to greater AI reliability
Schematization Elements
Every state property has these different elements of schematization:
Name: always pick a semantically meaningful name for the property. Obscure “internal” names (eg: “Property_123”) cannot be interpreted by the AI agents. On the other hand, a name that appropriately captures what it is supposed to represent (eg: “EmployeeName”) helps steer the work of the AI agent.
Description: The property description is also very important as it is a longer and more detailed way to describe the data that will be persisted in an instance of this property. The description can serve to specialize input properties (eg: “This is a PDF file of 3 or less pages, representing an invoice from one of our Malaysian customers”). It can also serve to constrain the work of the AI agent when it computes and persists output properties (eg: “This property holds the email address of our team sales rep for this customer”).
Type: Just as in a database or project system, each property can have a type (Number, Text, File, Image, etc.). Thunk.AI supports a growing number of property types. By choosing the most appropriate type, the thunk designer steers the AI agents with additional information, controls the updates of the AI agents to fit the type, and influences the UI presentation of data based on the type. A special kind of type is a List type. If a property is specified to be a List of Text, then the state maintained can be more complex with a nested list maintained for this property. When several properties or tools share the same object shape, you can define that shape once as a Structure Type and reuse it everywhere; see Structure Types and the Type Library.
Type Constraints: based on the choice of the type, further type constraints can be specified. For example, a Number can be constrained with min and max values. It is very common for Text to be constrained with a fixed enumeration of allowed values.
Required: There are two Required settings, and they do different things.
Required on the property itself applies when a work item is created. A request that arrives by email, through a webhook, or from the shared form becomes a work item only when every Required input has a value. It does not make a workflow step fill the property in. Most workflows have at least one input they cannot start without, so mark those inputs Required.
Required to start and Required to finish apply to one step. In a step's AI Instructions, each property under Input properties can be marked Required to start, and each property under Output properties can be marked Required to finish. When a Required to start input is empty, the step does not run; it waits for a person. When the AI agent finishes its work with a Required to finish output still empty, the step does not finish; it waits for a person, with a note naming the missing property. A Yes/No output set to No counts as filled in; one left unset does not.
Choosing which inputs are required
Look at each input of the workflow and ask whether the work can begin without it. The document to process, the request to answer, or the person who asked usually cannot be missing, so mark them Required. Leave an input optional only when the workflow has a sensible thing to do without it, such as a note from the requester or a reference number that is not always known.
When a request arrives by email, through a webhook, or from the shared form, the AI agent that turns it into a work item has to fill in every Required input. If one is missing, no work item is created. If every input is optional, an incomplete request becomes a work item anyway, and the problem shows up steps later as a confusing result instead of at the start.
When you write tests for the workflow, include a case that leaves out a required input. See Test plan design.
Choosing which outputs are required
For each step, look at its output properties and ask whether the work that follows can go on without each one. A decision the next step acts on, a value a report or a person relies on, or a Yes/No that routes the work item usually cannot be missing, so mark it Required to finish on that step. Marking the property itself Required does not do this: that setting is checked only when a work item is created.
Required to finish always applies. When a value is needed only in some cases, such as a filing deadline that exists only for an escalated case, leave it optional and use a Step Finish Condition instead. See Run a step only when a condition matches.
Choosing a property type
Choose the most specific type that fits what the property's description says it holds. Use Calendar Date for a date where the time of day does not matter, such as a deadline or a birthday, and Date Time when it does. Use URL for a link to a web page, File for a document, Image for a photo or screenshot, Address for a street or postal address, Location for map coordinates, and Country when the value is specifically a country.
Text is the most permissive type, and it is the right choice whenever no more specific type fits. An email address or a phone number has no dedicated type, so Text is correct for it. Number is for quantities; an identifier that happens to contain digits, such as a ZIP code, is Text. Yes/No is for exactly two possible values.
When the description says the property holds several values — "a list of URLs", "the tags for this request" — make it a list of that type rather than a single value.
The description, not the name, says what the property holds, so make the two agree: a property described as "a link to the customer's dashboard" should be a URL, whatever it is called.