> ## Documentation Index > Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt > Use this file to discover all available pages before exploring further. # Interaction rules > Ask the person storing a new document a question, and pass their answer into the workflow that starts — criteria, prompt, outcome, and how the answer reaches the workflow. ## What an interaction rule does A workflow trigger decides whether a workflow starts. An **interaction rule** decides what to ask first. When someone uploads a new document that matches the rule's criteria, they see a question before the document is stored. Their answer travels with the document's `document.created` event, and the workflow named in the rule starts with that answer already in its variables. The workflow can also test the answer in its trigger filter, so one answer can decide whether it starts at all. Nothing happens until a rule exists and is enabled. A tenant with no rules uploads documents exactly as before. ## Prerequisites To open the section you need `interaction-rules.view` and `workflow-engine.view`. To create, edit, or delete a rule you need `interaction-rules.manage`. `interaction-rules.admin` grants both. A user with view access alone can open a rule but not change it. Interaction rules are part of the workflow engine, which is switched on per tenant. Where it is off, the **Workflow** settings — interaction rules included — do not appear; confirm it is switched on for your tenant before you begin. Once your user groups have features assigned under **Settings → Admin Settings → Access → User Group Access**, one of them also needs the **Workflow** feature; without it the section stays hidden, even with the permissions above. Interaction rules depend on document events reaching the Workflow Engine. If the installation does not deliver document events, no question is asked and an enabled rule cannot be saved. On an installation that cannot store rules, the section shows *Interaction rules are not available on this installation*. Publish the workflow before you write the rule. The workflow has to be: * anchored to documents, with a `document.created` trigger; * scoped to every document type the rule's criteria can match; * reading each variable the rule maps, as `$instance.`. The rule editor checks these when you save an enabled rule, and refuses the save until they hold. ## Where rules live Open **Settings → Admin Settings → Workflow → Interaction rules**. The list shows each rule's name, trigger point, workflow, order, and whether it is enabled. Rules are evaluated per **trigger point**, lowest order first, and every matching rule asks its question in that order. Give each rule its own order. The order of rules that share one is not defined — not the order they were created in — yet it decides which question is asked first, which answer a workflow's filter reads, and which rule wins a variable name two rules map. ## Build a rule Choose **New interaction rule**. The editor has four tabs. ### General | Field | What it does | | - | - | | **Name** | Identifies the rule in the list. Up to 200 characters, and unique among rules that have not been deleted | | **Description** | Optional note about why the rule exists. Up to 1000 characters | | **Trigger point** | Where the rule is evaluated. **Document upload** is the only point today: the rule is judged before a new uploaded document is stored | | **Order** | Evaluation order within the trigger point, lowest first. New rules start at 100, so change it whenever a trigger point has more than one rule | | **Enabled** | A disabled rule is never evaluated, and is not checked against its workflow when saved | ### Criteria The criteria tree is the same editor as [retention policy criteria](/retention/policies#matching-criteria): rule types combined with **AND**, **OR**, and **NOT** groups, editable in the **Visual Editor** or the **JSON View**. The trigger point decides which rule types it can offer. A document upload is judged **before the document exists**, so the editor only offers what an upload knows: | Available at document upload | Not available | | - | - | | Document type, document type group, all documents | Stored date — the document has not been stored yet | | Keyword conditions, including *is empty* and *is not empty* | Activity conditions — the document has no history yet | | Date conditions on the document date, as typed into the upload form | | The Criteria tab of an interaction rule with the Rule Type menu open, listing Document Type, Document Type Group, Keyword Condition, Date Condition, and All Documents. A rule whose criteria contain a condition the trigger point cannot evaluate — pasted into the JSON view, for example — is refused on save. ### Prompt | Field | What it does | | - | - | | **Title** | The question. Required, up to 200 characters | | **Message** | Optional explanation below the title, up to 2000 characters | | **Choices** | One button per choice, between one and six. New rules start with Yes and No | | **Allow cancel** | Shows a Cancel button, so the person can skip storing the document. Off by default | Each choice has a **label**, a **value**, and a style (primary, secondary, or destructive), and label and value are each up to 100 characters. The distinction matters: the **label is what the person reads**, and the **value is what the workflow receives**. Keep values stable and machine-friendly (`yes`, `no`, `later`) and put the wording in the label — rewording a label then leaves your workflow conditions untouched. Two choices cannot share a value, even with different capitalisation. ### Outcome | Field | What it does | | - | - | | **Workflow** | The definition the answer feeds. Only published document workflows with a `document.created` trigger are listed. The latest published version always starts | | **Answer to variables** | Workflow variables that receive the answer | Each mapping row names a workflow variable and what it **receives**: the **choice value** or the **choice label**. An enabled rule needs at least one row, and a rule can map up to 50. Variable names use letters, digits, and underscores, and cannot start with a digit. The names of JavaScript's built-in object members, such as `constructor`, `toString`, and `valueOf`, are rejected, because a rule that maps one would break the interaction rule screens in settings. ## What the person uploading sees The question appears on the **Upload** page, including uploads started from Caseflow and the Office add-in. 1. They pick a document type and fill in keywords as usual. 2. On upload, the file is transferred, and the enabled rules are evaluated against what they are about to store — document type, keyword values, and document date. 3. If the file matches documents already stored, they are asked first whether it is a new document or a new revision. A new revision is stored without any question. 4. Every matching rule shows its prompt, in order. The dialog names the file and shows one button per choice. 5. The document is stored, and the answers travel with it. When **Allow cancel** is on, cancelling skips that one document: nothing is stored, and the rest of an **Upload all** batch continues. When it is off, the dialog cannot be closed without choosing. A document stored some other way — by an integration, a form, or a script — is never asked, and is stored as though no rule matched. ## How the answer reaches the workflow The new document raises its normal `document.created` event, and the answers ride along. A new revision raises `document.updated` and never carries one. For the workflow named in the rule's outcome: * The trigger filter can read `$interaction.value`, `$interaction.label`, `$interaction.ruleId`, and `$interaction.variables.`. * `$interaction` is **null** when no answered rule named this definition, so a filter of `$interaction.value == "yes"` starts the workflow only on that answer, and never on an ordinary upload. Test for the answer you want — `!= "no"` also matches every document nobody was asked about. * The instance starts with the rule's mapped variables already set, as text, readable as `$instance.`. * The filter editor suggests these references on a `document.created` trigger, the only event that carries an answer, and marks them as unknown on any other. It cannot know the variable names a rule maps, so it also marks `$interaction.variables.` as unknown. The filter still saves and publishes — check that name against the rule's outcome yourself. When two answered rules feed the same workflow, its filter's `$interaction` is the earlier rule's answer, while the instance receives the variables of both. Where both map the same variable name, the earlier rule in evaluation order wins. A rule's outcome names a workflow, but the workflow's own trigger and filter still decide whether it starts. A brand-new document normally has no instance of that workflow yet. The exception is a workflow that something else — another of its triggers, or a `Workflow.Start` step in another workflow — has already started for the new document before its `document.created` event is handled. Only one instance of a workflow runs per document at a time, so the answer then starts nothing. ## Change and remove rules * A rule is saved against the version you opened. If someone else saved it meanwhile, the editor says *Someone else changed this rule* and offers to reload; reloading discards your edits, and a failed reload keeps them. * A deleted rule stops applying immediately. If someone is answering its question at that moment, storing their document is refused. The upload then checks the rules once more and asks again every question that now applies, including the ones already answered; when no rule applies any more, the document is stored without an answer. The same happens when a rule is disabled, or changed so that an answer no longer fits it. * Every change to a rule is recorded in the configuration audit log. * Disabling a rule is the reversible way to stop asking a question while you re-word it. Deleting a rule cannot be undone from the settings screen. ## Where to read next A worked example: react to a document type with an empty keyword, ask the uploader, and create a Caseflow object on yes. The trigger-filter references an interaction answer exposes, and how mapped variables are read. Trigger types, scope, and the gates an event passes before an instance starts.