Skip to content

Start wizards

Another system can hand a person a wizard, either as a plain link to the template or by starting the wizard over the API and passing on the link it receives. Use it where the person is already in front of another screen, an online banking portal or a CRM, and that system hands them a form.

For a New Case (Creation Process) template, send the person to <wizard address>/w/<wizard_template_uuid>. That uuid is shown on the template itself, and is not its number. The link needs no API key, opens on the cover step, and can be opened as often as anyone likes.

Start a wizard over the API

Info

New in Atfinity 17.

A call starts a wizard either on a creation process, where the case brings its own instance, or on a lifecycle process, for an instance Atfinity already holds. Each call creates a case and one wizard on it, so the answers land on the same case data a user sees in the Case Manager. Calling twice creates two cases, so call once for every wizard the person actually starts. The reference carries the two calls, their bodies and their answer, and each call needs an API key.

Every template another system may start needs Can be started over the API, next to Enabled on the Wizard Templates tab of the process, and both only count once the configuration is live.

Every template also carries an entry step, the step the person lands on, which is where this differs from the plain link: the calling system has introduced the wizard already, so the form starts immediately instead of on a cover. Switching the toggle on picks the first form step, and any cover or form step can be chosen instead. An inconsistency is raised while the toggle is on and no entry step is set. A cover chosen as the entry step needs a condition, unless it is the cover a New Case (Creation Process) template starts with. A New Case (Lifecycle Process) template starts with its authentication step, so on those an entry cover always needs one.

The creation call always answers with a link that opens the wizard without asking the person to confirm an email address, and so does the lifecycle call with skip_authentication set to true. The calling system vouches for the person, so hand such a link only to the person it was requested for. Such a link works once: the first browser to open it keeps the wizard, and a second one is turned away. It expires ten minutes after it was created if nobody opens it, and your installation can be set to a different lifetime. The browser that opened it can return to the wizard for as long as its session lasts, and a person who loses the session, by clearing cookies or switching device, needs a new call, which starts a new case. Hand url to the person straight away rather than storing it. link is the same address without the wizard address. Anything that opens the link on its way uses it up, so a link scanner, a chat or mail preview, or a proxy that fetches links ahead of the person leaves them with an error.

Create a case on a creation process

A New Case (Creation Process) template produces the case and its instance, so its call needs nothing but the uuid of the template.

Create a case on a lifecycle process

A New Case (Lifecycle Process) template creates the case for one instance of the outcome ontology of its process, which has to be valid. Its call takes the instance either by its Atfinity id or by an identifier of your own.

Without skip_authentication, the call takes the email of the person instead, and the wizard opens on the authentication step the template starts with, which sends a link to that address and only to that address. The entry step plays no part in such a call, and the form opens once the person has followed the link. Such a link is not single use and does not expire, since the email address stands in for it.

For an identifier of your own, an account number or a customer number, switch on Allow external identifier and pick the information carrying that value. Only a text or a whole number information of the outcome ontology can be picked, and the value has to be unique among the instances of that ontology.

One valid instance carrying the value starts the wizard. No valid instance carrying it answers item_not_found, whether no instance carries the value or only one that is not valid, and the two cannot be told apart from the answer. Several answer multiple_instances_for_identifier, listing every instance id that carries the value so somebody can correct the duplicates.

A user starting the same template from an instance page gives the email address of the person in the same way, see Configuring a wizard.

When a wizard cannot be started

Code Status Meaning
invalid_uuid 400 The uuid in the path is not a uuid.
missing_required_parameter 400 The lifecycle call named neither an instance id nor an identifier, or sent neither an email nor skip_authentication.
invalid_email 400 The email is not an email address.
wizard_template_not_startable_over_api 400 The template does not have Can be started over the API switched on.
wizard_is_disabled 400 The template is not enabled.
wizard_template_without_api_entry_step 400 No entry step is configured.
wizard_template_without_authentication_step 400 An email was sent, and the template has no authentication step.
wizard_template_cannot_be_started_from_an_instance 400 The template does not create a case on a lifecycle process, and was started on the lifecycle call.
wizard_template_is_not_a_creation_wizard 400 The template does not create a case on a creation process, and was started on the creation call.
process_is_not_a_creation_process 400 The process of the template continues with an existing instance instead of creating one.
process_is_not_an_enabled_lifecycle_process 400 An instance was named for a wizard of a creation process, or the process is disabled.
process_does_not_match_instance_ontology 400 The instance is not of the outcome ontology of the process.
cannot_create_lifecycle_case_for_not_valid_instance 400 The instance is not valid.
wizard_template_without_instance_identifier 400 The template does not allow an external identifier.
multiple_instances_for_identifier 400 Several instances carry the identifier.
no_access 403 No instance has the id, or the caller has no access to the instance.
item_not_found 404 No live template carries the uuid, or no valid instance carries the identifier.