Start wizards

Info

New in Atfinity 17.

Another system can start a wizard and receive the link to it, either to create a new instance or to continue with one Atfinity already holds. 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.

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. The reference carries the two calls, their bodies and their answer.

Every template another system may start needs Can be started over the API, next to Enabled on the Wizard Templates tab of the process.

Create an instance

A creation wizard produces the case and its instance, so its call needs nothing but the uuid of the template. That uuid is shown on the template itself, and is not its number.

Such a 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. Put Live fails while the toggle is on and no entry step is set.

The link is always pre-authenticated, since the person never gave Atfinity an address, so skip_authentication is not read on this call.

Where the person should start from a plain link instead, send them to <wizard address>/w/<wizard_template_uuid>. That link needs no API key, opens on the cover step, and can be opened as often as anyone likes.

Continue with an instance

An ongoing template continues with one instance of the outcome ontology of a lifecycle process, which has to be valid. It also needs no condition, since a condition means the wizard is offered inside a case instead. Its call takes the instance either by its Atfinity id or by an identifier of your own.

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 instance carrying it answers 404. Several answer multiple_instances_for_identifier, listing every instance id that carries the value so somebody can correct the duplicates.

Skipping the email confirmation

Without skip_authentication, the person opens the link and confirms their email address before they see the first step, the same as a wizard sent from a case.

With skip_authentication set to true, the link opens the wizard directly, because the calling system has already authenticated the person. Such a link works once: the first browser to open it keeps the wizard, and a second one is turned away. It also expires ten minutes after it was created if nobody opens it, and your installation can be set to a different lifetime. Hand it to the person straight away rather than storing it. A user who starts the same wizard from an instance page always gets a link that asks for the email address.

When a wizard cannot be started

Code	Status	Meaning
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	A creation wizard, and no entry step is configured.
wizard_template_is_not_ongoing	400	A creation wizard was started on the ongoing call.
wizard_template_is_not_a_creation_wizard	400	An ongoing wizard was started on the creation call.
wizard_template_with_condition_not_startable_from_instance	400	The template has a condition.
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	The caller may not skip the authentication, or has no access to the process or the instance.
item_not_found	404	No such template, or no instance carries the identifier.