User Input Views

Multi-stage request and approval processes with their own stages, field visibility rules, reminders and reference numbers.

Overview of User Input Views

A User Input View (UIV) is a form over one of your datastores that turns each submission into a request and walks it through a series of approval stages. Use one whenever somebody submits something and one or more other people then have to approve it, decline it or ask for more information.

The person submitting needs no account if you allow it, and neither do the approvers: each approver is e-mailed a link that lets them act on that one request at that one stage.

Where to find it

Architect Panel → Forms:

User Input Views — build forms, their stages and their e-mails
Process Inspector — read how every approval process is configured, without editing anything
Application Periods — dated windows during which a form accepts applications
Shortlisting — decide who goes forward from a closed application round

Admin Panel → Processes:

Expiring Soon — requests that are about to time out
Process Inspector — the same read-only view, for administrators who are not architects
Shortlisting — the round console, for co-ordinators

The three Admin Panel tiles are visible to nobody until you grant each one to a security group. See Admin Panel.

How a request travels

Stage 1 is the form itself. The platform calls it Initial Request. You never create it; the stages you add are numbered 2 and upwards.
Submission writes the record to the datastore and sends the requester a confirmation e-mail, if you have switched that e-mail on. On a view with stages, the automatically written confirmation includes a link where the requester can track the request or cancel it.
The request arrives at its first stage. Each stage has a Stage Action that runs on arrival: usually Send E-mail, which e-mails the approver a link to the decision page. A stage can instead start an identity check or require compliance checks first.
The approver decides. Approve, decline, transfer to another stage or request more information, depending on which buttons you enabled for that stage.
Approval at the last stage completes the request. The Process Complete Action then runs.

A request can also end because the requester cancelled it, or because a stage time-out declined it. Each outcome has its own tab on the request list, so declined, cancelled and timed-out requests are never counted together.

Who may submit: the security level

Level 1: anyone, signed in or not. The only level suitable for a public form. Consider reCAPTCHA (v2 Checkbox, v2 Invisible or v3).
Level 2: anyone who is signed in.
Level 3: signed-in users whose security groups have access to the datastore. The datastore permissions decide.

What you can build on top

Stages, fields and buttons: which fields each stage shows or lets the approver change, and which actions the approver has. See User Input Views.
Time-outs and reminders: chase an approver, chase a requester who has not supplied information, and decline, move or complete a request that has waited too long.
Answer flags: notice a particular answer, tell somebody, and optionally hold the request. See Answer Flags.
Application windows: accept applications only between two dates, queue them and shortlist when the round closes. See Application Windows & Shortlisting.
Running the requests: the request list and its tabs, a request's progress page, Expiring Soon and the approver's own list of links. See Managing Requests.

The timed work is done by scheduled tasks

Time-outs, approver reminders, information-request reminders, delayed stage e-mails and the closing of application windows are each done by a background task, and every one of those tasks ships switched off. A stage can carry a perfectly good time-out that never fires. Enable the tasks you rely on under Architect Panel → Automation → Tasks (see Tasks). The Process Inspector warns at the top of a process when a task it depends on is missing or switched off.

Worked example

A facilities team builds a Building Access Request over a datastore called access requests. The form is security level 2 so staff sign in, and the reference prefix is BA-. Stage 2, Line Manager Approval, e-mails the address held in the form's manager e-mail field. Stage 3, Security Office, e-mails a static mailbox and offers Approve, Decline and Request More Information. Stage 2 has a five-day time-out that declines, with a reminder after three days. The team enables the time-out and reminder tasks, opens the Process Inspector to confirm that neither task is reported as switched off, and grants Expiring Soon to the facilities security group so they can chase managers before requests lapse.

Recommendations

Build the datastore first. A view can only show fields that already exist on it.
Pick the security level deliberately. Level 1 is public; use it only for forms that are meant to be.
Enable the tasks you depend on and check the Process Inspector afterwards.
Grant the Processes tiles to the groups who run the requests day to day.
Use a reference prefix so requests are recognisable in e-mail subjects.

Creating a New User Input View

A user input view is built on a builder page that belongs to one datastore. The left half creates a new view; the right half lists the views that already exist over that datastore, with a button for each part of their configuration.

Where to find it

Architect Panel → Data:

Datastores — the datastore, then Table Designer, then the User Input Views button under its field list

Architect Panel → Forms:

User Input Views — the Forms entry for user input views

Before you start

Create the datastore and every field the form will collect. The builder lists the datastore's fields as they are when the page opens, and the stages you add later can only use fields that exist. Hidden system fields are not offered.

Creating the view

Open the builder for the datastore. The page is headed User Input Views and shows the datastore's table name.
Enter a View Name under Create New View. It is required, and it is what approvers and requesters see in headings and in automatically written e-mail subjects.
Choose the Fields to Show. Every field starts ticked. Untick one and choose what happens to it instead: Remove from form, Obtain value dynamically using key (the field's row name, supplied by whatever page embeds the form) or Manually specify a fixed value, which reveals the field so you can set the value every submission will carry.
Fill in the view's settings below the field list. These come from the view's own record, so new settings appear here as the platform gains them. The ones that matter most:
- Security level (1 anyone, 2 signed in, 3 datastore permission) and the reCAPTCHA mode.
- Reference number prefix and submit button text.
- HTML shown above and below the form.
- E-mail Address: how the requester's address is found, which every requester e-mail depends on. It is required.
- Success action: what the requester sees after submitting. See Submission Success Actions.
- Process Complete Action: required. Send an e-mail, run a custom function, or do nothing when the last stage approves.
- Re-apply when declined: offers a declined requester an Apply again with my details pre-filled link, in the automatically written declined e-mail and on their tracking page. It needs an authkey field on the datastore. It is not offered after a time-out, and the tracking page does not offer it after a shortlisting decline.
- Intake bindings: the fields that switch on application windows and capacity. Leave them blank unless you are setting those up; see Application Windows & Shortlisting.
Optionally pick Copy Stages/Stage Actions to start from an existing process. It copies the stages and each stage's action buttons. It does not copy stage field assignments, visibility, e-mail settings or flag rules.
Press Save User Input. The page refreshes and the new view appears under Existing Views.

The Existing Views panel

Each view shows its name, who created it and when, the field list, and a coloured status box: green when the view matches the datastore, blue when fields are missing or unassigned, red when it refers to deleted fields. Then, line by line:

Edit User Input View: edit the settings you entered at creation.
Multi-stage with Manage Stages: add and edit stages.
Once stages exist: Distributed Fields with Manage Stage Fields, Stage Field Visibility (Automatic or Manual) with Manage Field Visibility, Standard E-mails/Notifications and Additional E-mails/Notifications with Manage Settings, and Initial Stage Assignment with Manage Assignment.
Flag Rules (None, or a count of rules) with Manage Flag Rules.
View Form opens the live form in a new tab; View Requests opens the request list.

Standard E-mails/Notifications opens the six requester e-mail settings in one window: confirmation, approved/progress, completion, declined, request for more information and cancellation. Switch each on and optionally choose a template; with no template the platform writes the e-mail itself.

When the datastore changes

Adding a field to the datastore does not add it to existing views. The status box lists it under Missing fields with an Add Missing Fields to User Input View button. Deleting a field leaves the view pointing at it; Remove Deleted Fields from User Input View removes it from the view and from every stage field list.

Worked example

An IT team creates a datastore called equipment loans with fields for the borrower's name and e-mail, the item, the dates and a manager e-mail. On the builder they name the view Equipment Loan Request, untick a source field and give it the fixed value web, set security level 2, prefix EQ-, and point E-mail Address at the borrower's e-mail field. They choose Copy Stages/Stage Actions to start from their existing Stationery Request process, save, then use Manage Stage Fields to decide what the manager sees at stage 2.

Recommendations

Name views for the people reading them. The view name is in every automatic e-mail subject.
Set E-mail Address carefully. A wrong field there breaks every requester e-mail.
Use fixed values rather than visible fields for anything the requester should not choose.
Act on a blue or red status box straight away; a view out of step with its datastore misbehaves quietly.
Check the result in the Process Inspector once the stages are in place.

Configuring Stages

Stages are the checkpoints a request passes through after it is submitted. Each stage decides what happens when a request arrives (usually e-mailing an approver), what the approver can do, and what happens if nobody acts in time.

Where to find it

Architect Panel → Forms:

User Input Views — Manage Stages and Initial Stage Assignment on the view
Process Inspector — check each stage reads the way you intended

Stage numbers

Stage 1 is the form being submitted. The platform names it Initial Request and it has no row of its own, so the first stage you add is number 2. Requests move through stages in number order, and every setting that names a stage (a time-out that moves a request, a flag rule, a transfer button, an intake confirm stage) uses these numbers. Renumbering a stage therefore changes what those settings point at; check them afterwards.

Adding a stage

On the builder, press Manage Stages beside Multi-stage. The list shows only this view's stages.
Add a row with the stage number and a stage name. The name appears on the progress bar, in tab names on the request list, and in automatically written approver e-mail subjects.
Choose the Stage Action (below) and fill in its fields.
Optionally set the stage's time-out, approver reminders and reminders while waiting for information. Each has its own article in this section.
Optionally add HTML to show above and below the request on the approver's page, for instructions such as what to check before approving.
Save, then set the buttons for the stage on the Form Stage Actions screen (see Stage Actions and Status Transitions).

The Stage Action: what happens on arrival

Send E-mail

E-mails the approver a link to the decision page. You choose who receives it (a field on the form, a static address, the original requester's address, the address of whoever is signed in, or a custom function your developer has provided), the e-mail account it is sent from, and optionally a template; with no template the platform writes the e-mail. The action can also name a separate template for the progress e-mail the requester receives when the request reaches this stage.

Delay E-mail holds the approver e-mail back until a date field on the form is reached or a set number of minutes, hours, days, weeks, months or years after the request arrives. See Delayed Stage E-mails.

Verify Identity

Starts an identity verification when the request arrives and holds the stage: the approver's buttons are withdrawn until the check passes. Choose the Verification type and Who Is Verified: an e-mail address held on the request (name the field in E-mail Field Row Name) or the signed-in user actioning the stage. No approver e-mail is sent by this action. Verification types are covered in User Verification.

Require Compliance

Brings the record's requirement checks up to date when the request arrives and withholds every approver action until they are satisfied. Set This Record Is A to the kind the requirement types apply to. To check a linked record as well, set all three of Also Check (Field), Also Check (Datastore) and Also Check (Kind); with any of the three missing the link is ignored and fewer records are checked. Requirement types themselves are configured elsewhere in the platform. Configure them and confirm they read correctly on a few live records before pointing a stage at this action: a stage set to it holds every request until its checks pass.

Where a request starts: Initial Stage Assignment

By default a new request goes to stage 2. Manage Assignment lets you name a fixed stage instead, or route by answer: a list of field, comparison and value rules each naming a stage, where the first rule that matches decides. An answer flag that names a stage overrides this; see Answer Flags.

What goes wrong

A Send E-mail stage with no account to send from cannot e-mail anybody. Name the account explicitly.
A recipient field that is empty on the record leaves the approver un-notified. Check the E-mail Correspondence on the request's progress page.
Settings that read Yes but were never filled in do nothing. The Process Inspector shows these in amber.

Worked example

A work-experience programme runs three stages after the application. Stage 2, Parent/Guardian Approval, sends an e-mail to the parent's address field on the form. Stage 3, Placement Supervisor, sends to an address held against the chosen placement. Stage 4, Certificate, shows the student a download page and is completed automatically by a time-out six weeks later. Initial Stage Assignment routes applicants aged 18 or over straight to stage 3 by testing the age field.

Recommendations

Leave gaps sparingly. Numbers are referenced elsewhere, so plan them before you build.
Always name the sending account on Send E-mail stages.
Configure compliance data before the gate. Require Compliance holds everything until it is satisfied.
Review every stage in the Process Inspector after changing it.

Stage Email Reminders

Approver reminders e-mail the person a stage is waiting on when they have not acted. They are set per stage, and a stage can carry several, each with its own delay and template, so you can send a gentle nudge first and a firmer one later.

Where to find it

Architect Panel → Forms:

User Input Views — Manage Stages on the view, then the stage's e-mail reminder setting
Process Inspector — the stage's Timing panel, under Reminder e-mails

Architect Panel → Automation:

Tasks — the approver reminder task, which must be enabled

How a reminder is decided

The clock starts when the request arrives at the stage, not when the form was first submitted. A request that took a week to clear stage 2 gets a fresh clock at stage 3.
Each reminder is sent once per request, per stage. Several reminders on one stage are separate entries, each sent once when its own delay has passed.
Only waiting requests are chased. A request that has been decided, moved on, or sent back to the requester for information is not reminded.
Paused requests are skipped. A request whose time-out has been paused (from Expiring Soon, or by a rollback) is not reminded until the pause ends.
A delayed approver e-mail comes first. If the stage holds back its first e-mail, no reminder is sent until that e-mail has actually gone out. The reminder's delay still counts from arrival, so a reminder already due follows the delayed e-mail on the next run.
The stage must use Send E-mail. Reminders go to the same recipient, from the same account, as the stage's own e-mail.

Setting up reminders on a stage

Open the stage from Manage Stages and switch its e-mail reminder setting on.
Add a reminder entry. Choose the unit (seconds, minutes, hours, days, weeks, months or years) and the number of units.
Optionally pick an e-mail template. With none, the platform writes the reminder itself.
Add further entries for later reminders, each with a longer delay.
Save, then confirm the approver reminder task is enabled under Automation → Tasks. The Process Inspector names the task and says whether it is switched off.

What the reminder says

The automatically written reminder carries a fresh link to the decision page. If the stage also has a time-out, it tells the approver the date by which they must respond and what will happen then: declined, or moved to a named stage.

In your own template, put ##AMDATA/AUTHURL## where the decision link belongs; without it the approver has nothing to click. Any field on the request can be inserted with ##AMDATA_rowname## (the field's row name), and ##AMDATA/ALL## inserts the request's details as a block.

What goes wrong

Nothing is ever sent. The task is switched off, or the setting was switched on and no entry was added. The Process Inspector reports both.
A reminder template with no link. The approver is nudged but cannot act from the e-mail. Add ##AMDATA/AUTHURL##.
Reminders after a time-out. They cannot happen: a timed-out request is no longer waiting. Set reminders well inside the time-out.
Turning on a task in preview mode does not make it safe. A scheduled run always sends. Use the Preview button on the Tasks screen to see what would be sent first.

Worked example

A purchase approval has a Finance Review stage with a seven-day time-out that declines. Finance asks for a polite reminder at two days and a firmer one at five. The architect adds two reminder entries to the stage: two days with a short template, and five days with no template, so the automatic wording, which states the decline date, is used. They preview the reminder task on the Tasks screen, see two requests that would be reminded, enable the task, and check the Process Inspector no longer reports it as switched off.

Recommendations

Remind at about half the time-out, so the approver has time to act.
Use two entries, not one long delay, where approvers are often away.
Always include the decision link in a custom reminder template.
Preview before enabling the task on a live system.

Stage Information Request Reminders

When an approver needs something from the requester, they can send the request back with a question instead of deciding. The request then waits on the requester, and the platform can chase them with reminders of their own, separate from the reminders that chase approvers.

Where to find it

Architect Panel → Forms:

User Input Views — the Request More Information button on a stage, the request-for-more-information e-mail, and the stage's reminders while waiting for information
Process Inspector — the Asking for more panel and each stage's Timing panel

Architect Panel → Automation:

Tasks — User Input View - Info Request Reminders, which must be enabled

How asking for information works

The approver presses Request More Information (or whatever you named the button) and writes what they need. If you allowed it, they can attach files.
The requester is e-mailed the question and a link to answer it, using the view's request-for-more-information e-mail.
The request waits. Its status becomes Waiting For Information, and the approver's own link now answers You have already submitted a request for more information.
The requester answers through the link. The stage does not move: the approver is e-mailed that the information has been provided, with a fresh link, and makes the decision.

Setting it up

Switch on the request-for-more-information e-mail under Standard E-mails/Notifications on the builder. If it is off, the approver's request fails with a message that the feature has not been configured, although the request for information is still recorded.
Enable the button on the stage's Form Stage Actions screen: switch on Request More Information, set the Button Text, and choose File Attachments: Off, Request Only (the approver can attach) or Both Request and Response (the requester can attach to their answer too).
Add reminders on the stage's reminders-while-waiting-for-information setting. Each entry has a unit (seconds to years), a number and an optional template.
Enable the task User Input View - Info Request Reminders. It ships switched off, and until it runs no reminder is ever sent however the stage is set.

How the reminders behave

The clock starts when the information was requested.
They go to the requester, at the address the view's E-mail Address setting finds, from the account the stage sends from. The stage must use the Send E-mail action.
Each entry is sent once per request and stage, so three entries give three reminders.
Files the approver attached are attached again to each reminder.
The automatic wording repeats the question and the link. In your own template use ##AMDATA/AUTHURL## for the answer link.

A stage time-out also covers this wait. If the stage times out, a request still waiting on its requester is declined or moved like one waiting on an approver. See Stage Time-outs and the Complete Request Action.

When the answer arrives another way

If the requester replies by phone or e-mail, or the information is no longer needed, open the request's progress page and use Close Information Request. Record what was received, or why the request is being closed, and leave E-mail the approver ticked to send them a fresh link. The note is stamped with your name, the stage stays where it is, and the decision stays with the approver. You need Edit Existing on the datastore. See Managing Requests.

Worked example

A supplier onboarding form asks Procurement to approve at stage 3. Procurement often needs a missing insurance certificate, so the stage's Request More Information is on with File Attachments set to Both Request and Response. The stage has two information reminders, at three and seven days, and a fourteen-day time-out that declines. When a supplier e-mails the certificate to a buyer instead of using the link, the buyer uploads it to the record, closes the information request with a note, and Procurement receives a fresh link to approve.

Recommendations

Configure the e-mail before the button. Otherwise the approver's request fails.
Chase requesters sooner than approvers. They submitted and moved on.
Pair reminders with a time-out so silent requests do not stay open for ever.
Use Close Information Request rather than rolling the stage back when an answer arrives outside the form.

Stage Fields and Visibility Rules

Two screens decide what each person in a process sees. Stage field assignment says which fields are filled in at which stage; the visibility override says whether a field filled in earlier is shown, hidden or editable again at each later stage.

Where to find it

Architect Panel → Forms:

User Input Views — Manage Stage Fields and Manage Field Visibility on the view (shown once it has stages)
Process Inspector — each stage's Fields shown at this stage table

Assigning fields to stages

Manage Stage Fields opens Form Stage Field Assignment. It needs at least one stage; with none it says You haven't set up any stages yet.

The User Input View Developer tree on the left has one branch per stage, starting with stage 1, the form itself. Available Fields on the right lists the view's fields.
Drag each field into the stage where it should be filled in. Stage 1 is what the requester completes; a field placed at stage 3 is completed by the stage 3 approver.
Order fields within a stage as you want them drawn.
Press Save Form Stage Information.

Until any field is assigned, the builder shows Distributed Fields: No and every field is drawn on the form. Once you assign fields, a field that is not assigned anywhere is listed under Unassigned Fields in the view's status box and is not drawn.

Showing earlier answers at later stages

Manage Field Visibility opens Form Stage Field Visibility Override: a grid of fields down the side and stages across the top.

Blue pencil: the stage the field is assigned to. It is editable there; you cannot change that here.
Grey crossed eye: a stage before the field is filled in. Nothing to show.
Eye: at a later stage, the field is shown to that stage's approver, read-only. Click to switch it to hidden.
Pencil beside the eye: also let that later stage change the value.

Press Save Visibility Information. The builder then shows Stage Field Visibility: Manual; with no overrides saved it reads Automatic, and later stages see what earlier stages filled in.

What these screens do not do

Whether a field is required comes from the field's own definition on the datastore, not from the stage. There is no per-stage required setting.
Questions asked when an approver presses a button, such as a decline reason, are not datastore fields. They are set on the Form Stage Actions screen, stored against the decision rather than on the record, and listed in the Process Inspector under Also asked for.
Hiding a field here is not access control. Anyone who can open the record in the datastore can still read it. Use field permissions for that.

What goes wrong

A field missing from every stage after you start assigning is never collected. Check the Unassigned Fields list.
A field that a later setting depends on is not drawn. An intake start-date field, a flag rule's field or a delayed e-mail's date field must be on a stage, or the submission never carries it. The Process Inspector checks the intake case.
A field deleted from the datastore shows as DELETED FIELD; use Remove Deleted Fields from User Input View on the builder.

Worked example

A purchase request has fields for supplier, items, cost, a budget code and a finance note. Stage 1 collects supplier, items and cost. The architect assigns the budget code to stage 2 (Line Manager) and the finance note to stage 3 (Finance). In the visibility grid, cost is visible at stages 2 and 3; the budget code is visible and editable at stage 3 so Finance can correct it; the finance note has no later stage. The Process Inspector then lists, for each stage, which fields the approver can read and which they can change.

Recommendations

Assign every field once you start distributing, or it silently stops being collected.
Keep approver stages short. Show what they need to decide, not the whole record.
Use field permissions for genuine confidentiality, not visibility.
Re-check after datastore changes using the builder's status box.

Stage Actions and Status Transitions

The buttons an approver sees at a stage are set on the stage's Form Stage Actions screen. What each button does to the request decides which status it shows next, and the decline and cancellation notifications decide who else hears about it.

Where to find it

Architect Panel → Forms:

Process Inspector — open the process, then the pencil beside The approver on a stage to reach Form Stage Actions
User Input Views — Additional E-mails/Notifications on the view, for decline and cancellation notices

The four buttons

Approve Request: always available. Moves the request to the next stage, or completes it at the last stage. Set its Button Text.
Decline Request: switch on to offer it. Ends the request as declined.
Transfer to Stage: switch on, then tick the Allowed Stages and give each its own button text (it defaults to Transfer to and the stage name). Sends the request to that stage instead of the next one, earlier or later.
Request More Information: switch on, set the button text and choose File Attachments. Sends the request back to the requester with a question; see Stage Information Request Reminders.

Approve, decline and transfer can each ask the approver extra questions when pressed, such as a reason for declining. Those answers are stored against the decision, not on the record. They reach the requester's e-mails only through ##AMDATA/APPROVEFIELDS## and ##AMDATA/DECLINEFIELDS## (the automatically written e-mails include them); transfer answers reach no e-mail. Press Save Stage Actions when done.

On a stage whose Stage Action is Verify Identity or Require Compliance, the buttons are withheld until the check is satisfied, whatever is configured here.

Statuses a request can have

The request list's Current Stage column and its tabs read the latest event on each request:

A stage name: waiting for that stage's decision. Active Requests and the per-stage tabs count these.
Waiting for Information: sent back to the requester.
Declined: an approver declined it.
Cancelled: the requester cancelled it.
Timed Out: a stage time-out declined it. Reported separately from Declined.
Completed: approved at the last stage, or completed there by a time-out.

What the requester can do

The requester's tracking link (in the automatic confirmation and progress e-mails) shows the progress bar and, until the last stage is approved, a Cancel Request button. After a decline, if the view allows re-applying, it offers Apply again with my details pre-filled, which opens a fresh form with their previous answers. The tracking page does not make that offer after a shortlisting decline, because the window has closed, although an automatically written declined e-mail still carries the link.

What an approver sees afterwards

Each stage link works once. Opened again it says what happened, for example You have already approved this request, This request has timed out and can no longer be actioned or This request has been declined in a previous stage.

Telling earlier approvers

Additional E-mails/Notifications opens Form Stage Decline/Cancellation Notifications: a grid with earlier stages down the side and later stages across the top. Tick a cell to e-mail the approver of the earlier stage when the request is declined at the later one, or cancelled by the requester. An approver who said yes at stage 2 then learns that stage 4 said no. Press the save button under the grid.

What goes wrong

No way out but Approve. If Decline is off and there is no time-out, a request that should not proceed can only be approved or left. Switch Decline on for any stage that judges anything.
Transfer to a stage that was renumbered sends the request somewhere unintended. Re-check Allowed Stages after renumbering.
Looking for a decline reason on the record. It is not there; it is on the progress page under the stage's Decline Fields.

Worked example

A change request has stages Technical Review (2), Change Board (3) and Scheduling (4). At stage 3 the architect enables Decline with a reason field, and Transfer to Stage allowing Technical Review, with the button text Send back for rework. In the notifications grid they tick stage 2 under stage 3, so the technical reviewer hears when the board declines. The requester's declined e-mail uses ##AMDATA/DECLINEFIELDS## to quote the board's reason.

Recommendations

Name buttons after the decision, not the mechanism.
Ask for a reason on every decline.
Notify earlier approvers of late declines; it saves them chasing.
Check each stage's buttons in the Process Inspector's The approver panel.

Reference Numbers and Prefixes

Every request has a reference: the record's ID on the datastore, with an optional prefix in front. A prefix such as BA- or PR/ makes it obvious which process a reference belongs to when it turns up in an inbox or a phone call.

Where to find it

Architect Panel → Forms:

User Input Views — the reference number prefix, set when the view is created or through Edit User Input View
Process Inspector — the prefix of every process, in the list and at the top of each one

How a reference is made

The reference is the prefix followed by the record ID: a view with prefix BA- shows record 1234 as BA-1234. Nothing extra is stored on the record. The prefix is added whenever a reference is displayed, so:

the number is unique within the datastore, because it is the record ID;
two views over the same datastore with different prefixes show the same record under different references;
changing the prefix changes every reference the view displays from then on, including on old requests. E-mails already sent keep the old form.

Where the reference appears

Automatically written requester e-mails: the subject is the view name followed by the reference in square brackets, for example Building Access Request [BA-1234]. With no prefix it reads [Ref No. 1234]. Automatically written approver e-mails are different: they are headed [ACTION REQUIRED] with the view name, your site name and the stage name, and carry no reference in the subject.
The request's progress page: headed with the view name and the reference.
Shortlisting and Expiring Soon: in their Ref columns.
Flag notification e-mails: in the subject, beside the flag name.
The requester's Your Requests page: each entry is headed Request and the reference.

The approver request list shows the bare record number, without the prefix.

Using it in your own templates

There is no single tag for the prefixed reference. Type the prefix into the template and follow it with ##AMDATA_ID##, which inserts the record ID: BA-##AMDATA_ID##. If you later change the prefix, update the templates too, or the e-mails and the screens will disagree.

Setting the prefix

On the builder, under Existing Views, press Edit User Input View for the view (or set it when creating a new one).
Enter the prefix in the reference number prefix setting. Include any separator you want, such as a hyphen or slash; nothing is added for you.
Save, then search your e-mail templates for the old prefix and update them.

What goes wrong

A reference quoted by a requester is not found. Search the datastore by the number after the prefix; the prefix is not stored.
Templates show a different prefix from the screens after a change. Templates hold typed text; update them.
Two processes share a prefix. The same number may then mean different records in different datastores. Give each view its own.

Worked example

An organisation runs three processes: building access, equipment loans and purchase requests. It gives them the prefixes BA-, EQ- and PR-. Its custom confirmation templates read Your request BA-##AMDATA_ID## has been received. When the service desk takes a call about EQ-512, they know which process it belongs to and open record 512 in the equipment loans list. A year later the purchase prefix changes to PO-; the architect updates the view and the two purchase templates the same afternoon.

Recommendations

Set a prefix on every view, short and distinct.
Include the separator in the prefix itself.
Decide the prefix before go-live; changing it later rewrites every displayed reference.
Keep templates in step with the prefix.

Submission Success Actions

Two settings decide what happens at either end of a request. The success action decides what the requester sees the moment they submit. The Process Complete Action decides what happens once the last stage has approved.

Where to find it

Architect Panel → Forms:

User Input Views — both settings, when the view is created or through Edit User Input View
Process Inspector — the Where it ends panel shows the Process Complete Action

The success action

The success action is chosen from a list when you create the view. The choices, in the order the list offers them:

Show a message: HTML you write replaces the form on the page. Use it to confirm receipt and say what happens next.
Go to a web address: the browser is sent to a URL you enter.
Refresh the page the form sits on.
Refresh the web app, for forms used inside the installed app.
Go to a page in the application, named by its query string rather than a full address.
Run a JavaScript handler: a function your developer has added to the page receives control. Only useful where such a function exists.
A PHP callback option. The submission code does not recognise this choice: the request is saved, and the requester then sees a configuration error. Do not use it.

In the message, the web address and the page query string, %%AM-ID%% is replaced by the new record's ID. So Your reference is BA-%%AM-ID%% shows the prefixed reference, and a URL can carry the ID to a page that displays the request.

The Process Complete Action

This setting is required. It runs when the last stage approves the request; on a view with no stages, it runs on submission. Three choices:

Send E-mail: choose who receives it (the same recipient choices a stage offers), the account it is sent from, and optionally a template. Without a template the platform writes the message, with a subject of the view name, your site name and the reference.
Run PHP Callback Function: name a function your developer has added to the application's custom code. If the function does not exist the error is logged and nothing else happens.
Nothing.

This is separate from the requester's completion e-mail, which is one of the six e-mails under Standard E-mails/Notifications. A request completed by a stage time-out using Complete Request does not run the Process Complete Action and sends nothing.

Setting them up

Decide what the requester needs to know at submission: usually that it arrived, the reference and the next step.
On the builder, choose the success action and fill in its message, address or query string.
Choose the Process Complete Action. If it sends an e-mail, name the sending account.
Save, submit a test request with View Form, and approve it through every stage to see both ends work.

What goes wrong

A configuration error after submitting: the success action is set to the PHP callback option, or holds a value the platform does not recognise. The request was saved; change the success action.
Nothing visible after submitting: a JavaScript handler was chosen and the page has no such function.
No completion e-mail: check whether you meant the Process Complete Action or the requester's completion e-mail. They are different settings.

Worked example

A public contact form (security level 1) uses Show a message: Thank you. Your reference is CF-%%AM-ID%%. We reply within two working days. Its single stage, Triage, e-mails the support mailbox. Its Process Complete Action sends an e-mail to the address in the form's e-mail field from the support account, using a template that thanks the person and links to the knowledge base. The team tests by submitting through View Form and approving at Triage.

Recommendations

Show the reference in the success message using %%AM-ID%% and your prefix.
Prefer a message over a redirect unless the next page adds something.
Avoid the PHP callback success option.
Test end to end after any change to either setting.

Stage Time-outs and the Complete Request Action

A stage time-out acts on a request that has waited at a stage for longer than you allow. It can decline the request, move it to another stage, or complete it where it stands. Complete Request is the newest of the three, and the only way to finish a request whose last stage nobody ever presses a button on.

Where to find it

Architect Panel → Forms:

User Input Views — Manage Stages, then the stage's Stage Timeout setting
Process Inspector — If nobody acts in time, in each stage's Timing panel

Architect Panel → Automation:

Tasks — the stage time-out task, which must be enabled

Admin Panel → Processes:

Expiring Soon — what is about to time out, with a Pause button

What counts as waiting

Two kinds of wait count, and both use the same time-out:

Waiting on the approver: the request arrived at the stage and nobody has decided.
Waiting on the requester: the approver asked for more information and the requester has not answered.

The clock starts when the request arrived at the stage, or when the information was requested. A request whose time-out is paused, and one whose stage is still holding back a delayed approver e-mail, does not time out.

The three actions

Decline Request: ends the request with the status Timed Out, not Declined, so time-outs are reported separately from refusals. If the declined e-mail is switched on, the requester receives it; the automatically written version says the time limit was reached. The decline/cancellation notifications you set up are sent too.
Move to Stage: sends the request to the stage number you name, and e-mails that stage's approver and the requester. Use it to escalate to a deputy.
Complete Request: records the stage as approved, exactly as if the approver had pressed Approve, and sends nothing. On the view's last stage that completes the request.

Complete Request exists for last stages that are a page rather than a decision, such as a certificate to download or a receipt to read. Without it those requests never reach Completed and stay on the Active list for ever. It does not run the Process Complete Action. On a stage that is not the last, the request moves on to wait at the next stage, but nobody there is e-mailed, so use it on the last stage only.

Setting a time-out

Open the stage from Manage Stages and switch Stage Timeout on.
Choose the action. For Move to Stage, enter the stage number to move to.
Choose the unit (seconds, minutes, hours, days, weeks, months or years) and the number of units.
Save. The Process Inspector should now describe the time-out in words under If nobody acts in time; a setting switched on but not filled in shows in amber.
Enable the stage time-out task on the Tasks screen. Until it runs, nothing ever times out.

Before you switch the task on

Preview mode on a task does not make it safe: a scheduled run always acts. To see what would happen, use Preview on the Tasks screen, or open Expiring Soon, which lists what will time out without doing anything. Its banner says whether the time-out task is missing, switched off or live. See Managing Requests.

What goes wrong

Nothing times out. The task is off, or the setting is switched on without a unit and number.
Move to Stage names a stage that does not exist. The request is not moved and the task reports an error.
A deadline quoted in an e-mail. If a template tells people they have six weeks, changing the time-out does not change the sentence. Change both together.
History pruned. Waiting time is measured from the audit trail; a request whose audit entry is missing is never timed out.

Worked example

On a work-experience form the last stage, Certificate, shows the student a page to download their certificate. Nobody approves it, so every finished placement sat in Active Requests. The architect sets the Certificate stage to Complete Request after 42 days. Six weeks after each student reaches the page, the request moves to Completed Requests and off the co-ordinator's working list. The certificate link keeps working afterwards, and the e-mail that promises six weeks is left matching the setting.

Recommendations

Use Complete Request only on a last stage.
Pair every time-out with a reminder set well before it.
Check Expiring Soon before enabling the task on a live system.
Keep units consistent across a view so nobody misreads them.

Delayed Stage E-mails

A stage can hold back the e-mail it sends its approver until a date on the form is reached, or until a set time after the request arrives. Use it when the approver should not be asked yet: a feedback request that only makes sense once a placement has finished, or a sign-off that waits for a start date.

Where to find it

Architect Panel → Forms:

User Input Views — Manage Stages, then Delay E-mail inside the stage's Send E-mail action
Process Inspector — the stage's On arrival panel

Architect Panel → Automation:

Tasks — User Input View - Delayed Stage E-mails, which must be enabled

The choices

Delay E-mail sits inside the Send E-mail stage action. Its options are:

No - send immediately: the normal behaviour, and what every stage saved before this option existed does.
Yes - when a date field is reached: enter the Date Field Row Name of a date field on the form. The e-mail goes out on or after midnight at the start of that date, server time.
Yes - a set number of minutes, hours, days, weeks, months or years after reaching this stage: one option per unit, each with a number to enter.

How it behaves

The request still arrives at the stage straight away. Only the approver e-mail waits. The requester's own progress e-mail is not delayed.
Every route into the stage is covered: approval from the previous stage, a new submission routed straight to it, and a transfer or time-out that moves a request there.
It is sent once. A failed send is tried again on the next run rather than being lost.
Reminders and time-outs wait for it. No reminder goes out, and the stage does not time out, until the delayed e-mail has actually been sent. A request is not declined before its approver has been told. Their clocks still run from when the request reached the stage, though, not from the e-mail.
A date that is empty or unreadable means the e-mail cannot be scheduled yet. It is checked again on each run and goes out once the field holds a date that has been reached.

Setting it up

Make sure the date field you want to use is drawn on a stage at or before this one, so it is filled in by the time it matters.
Open the stage from Manage Stages. Its Stage Action must be Send E-mail.
Set Delay E-mail and fill in the date field's row name, or the number of units.
Save, and read the stage's On arrival panel in the Process Inspector to confirm the delay.
Enable User Input View - Delayed Stage E-mails on the Tasks screen.

What goes wrong

The task is switched off. This is the serious one: the stage suppresses its e-mail and nothing ever sends it, so approvers are never asked. Enable the task before you save a delay on a live stage.
The row name is the field's title rather than its row name. The value is never found and the e-mail never sends.
A date field the requester can leave blank. Make it required, or the approver may never be asked.
A delay longer than the time-out. The moment the delayed e-mail goes out, the request is already overdue, and the next time-out run declines or moves it. Make the time-out longer than the delay.
Two runs at once, possible only when a previous run overran, can in rare cases send twice.

Worked example

A placement programme asks each supervisor for an evaluation of the student at stage 5. The request reaches that stage when the co-ordinator confirms the placement, often weeks before it starts. The architect sets stage 5's Delay E-mail to when a date field is reached with the row name of the placement end date. The supervisor is e-mailed the morning the placement ends. Because reminders and time-outs count from when the request reached the stage, not from the e-mail, the architect sets the stage's time-out longer than the longest placement plus the time a supervisor needs, so a request is never timed out the day its e-mail goes.

Recommendations

Enable the task first, then add delays.
Use a required date field for date-based delays.
Use a fixed period when there is no natural date.
Check the On arrival panel in the Process Inspector after saving.