Configuring a Wizard¶
A wizard is configured as a template on a process. The template decides what the wizard does to the case, how someone gets into it, and what each step shows.
Choosing the type¶
A template has one of four types, and the type is what decides whether the wizard creates a case or continues one.
- New Case (Creation Process): filling the wizard in starts a new case, and the case creates its own instance.
- New Case (Lifecycle Process) (new in Atfinity 17): filling the wizard in starts a new case for an instance Atfinity already holds.
- Ongoing Case (Fixed Instances) (new in Atfinity 15): continues an existing case, scoped to a chosen set of instances that still need information.
- Ongoing Case (Whole case) (new in Atfinity 16): continues an existing case as a whole, rather than specific instances.
A type that starts a case belongs to one kind of process, and says so in its name, so a template offers only the New Case type of its own process. A template whose process is later changed to the other kind is reported as a configuration inconsistency as soon as the configuration changes, so you see it on the template without waiting, and it blocks Put Live until the type and the process agree.
Reach for Ongoing Case (Fixed Instances) where you know which instances the person has to answer for, such as one client updating their own details, and for Ongoing Case (Whole case) where the wizard covers the case regardless of who is in it.
Deciding how it starts¶
An Ongoing Case wizard is created from the Wizards tab of a case, for one email address. A template is offered there only where its condition matches, the same way a rule condition does.
A New Case (Lifecycle Process) wizard starts from an instance page instead (new in Atfinity 17). An enabled template of that kind is offered on the pages of the instances of its outcome ontology once its configuration is live, as long as the reader reaches its process and the process's own condition for creating a lifecycle case matches. Starting it asks for the email address of the person filling it in, creates the case for that instance straight away, and hands back a link to send them. The link belongs to that one wizard, and the person confirms the address on the authentication step before the form opens.
Can be started over the API, off by default, lets another system start a wizard that creates a case and take back the link, see Start wizards. Such a template also picks the entry step the person lands on, rather than opening on its initial step. A New Case (Lifecycle Process) wizard lands there only when the calling system skips authentication, and one started for an email address opens on its authentication step instead.
Steps before the form¶
A New Case (Creation Process) wizard starts with a cover step, with its own image and text.
An Ongoing Case or New Case (Lifecycle Process) wizard starts with an authentication step instead, confirming the address the wizard was created for. Its initial step has to be that authentication step, and a template whose initial step is anything else, or that has no authentication step at all, is reported as a configuration inconsistency that blocks Put Live. These wizards always confirm the address by email, so their templates have no email authentication toggle and cannot take a registration step. A wizard starts with a form step only where the system that started it has authenticated the person already. A New Case (Creation Process) wizard has no such address, so it can take a registration step, where the person registers their own and the wizard keeps it from then on. Confirming the address sends a single-use link that expires after ten minutes.
Building a step¶
A step's layout holds categories and fields, the same building blocks as a process layout. Three components exist only here.
Super categories¶
Info
New in Atfinity 17.
A super category is a component you place among the categories in a step. It has no description and no fields of its own, so moving it does not move any content with it, unlike moving a category.
Its title is either fixed, or calculated with a RuLa formula, the same principle used to name a case or an instance. On a step that repeats per instance the formula is evaluated once for each one, so every section is named after the instance whose fields follow. An instance whose formula returns nothing falls back to the fixed title.
On a step that repeats for every 'Beneficial Owner' instance, a super category with a calculated title announces whose fields follow, without moving those fields if it is repositioned.
Descriptions¶
Info
New in Atfinity 17.
A field, a category and a structure information can each have a description, the same text already used as help text in the Case Manager, and that description can also be shown in the wizard.
A description is rich text and supports bold, italic, bulleted and numbered lists, and links. Any other formatting, such as strikethrough or a code block, is dropped when you paste it in. An item without a description has nothing to show, regardless of its toggle.
Each field, category and structure placed in the wizard has its own toggle for this, on by default. A field or category placed on more than one step has an independent toggle for each placement. Fields inside a structure's occurrences are the exception: their toggle is set once on the structure's own field layout and applies wherever that structure is used, rather than per step.
Documents and booklets¶
Info
New in Atfinity 17.
A file field resolves to one document or booklet of the case with a RuLa expression, and lets the end user download it.
The expression is required and must resolve to exactly one document or booklet, for example through
CASE.documents_by_key, an instance's documents_by_key, or
CASE.booklets_by_key.
If it resolves to anything else, or to nothing for the current case, the file field does not appear in the wizard at
all.
A file field can also let the end user view the resolved document or booklet inside the wizard, in addition to downloading it. This is off by default.
Trying it out¶
Info
New in Atfinity 17.
Test wizard, on the template, runs the wizard on the draft configuration, so you can try a template out before you put it live. It creates a draft case and its wizard the same way the real start does, and hands back a link that opens the wizard. The case appears under Draft cases rather than in the Case Manager, so a test run never counts towards the cases the template is used in, and you delete it there once you are done.
The wizard opens on the entry step the template names for an API start, when it can be started over the API, and otherwise on the first cover or form step of the flow. A template of a type that starts a case for an instance asks which instance to run on, and offers the valid draft instances rather than real clients. Approving a draft case makes its instances valid the way approving a real case does, without touching any real client, so approve a draft case holding the instance you want to test against first.
Following a wizard once it is out¶
A wizard starts as created, becomes opened when its link is followed, and completed once its last step has
been served, whether the person reaches it by filling the wizard in or by following an email link back to it.
One still in created can be withdrawn.
One that has been opened can be set to inactive instead, which keeps its answers and stops further work on it.
Finishing the case completes every wizard still open on it.
Reason about status and type in rules with
WIZARD, or across a case with
CASE.wizards.