Stateful behaviour

apiUi Stateful behaviour.

apiUi offers two ways to realize stateful behaviour.

  1. Applying the apiUi state machine., the low-code way.
  2. Working with environment variables, the high-code way.

State machine

Switch usage of the state machine on/off on operation level by clicking the below toggle-button.
When switched on, three extra columns will be shown in the messages grid in which you can enter Scenario names, RequiredStates and NextStates.
Each entered Scenario does have a state, the initial state is always 'Started'. On matching requests, apiUi will check if the required state of a candidate matches a scenario state. If so, the candidate will be used and the state for the corresponding scenario will be set to the value specified under NextState.


The screencopy below shows a scenario named scenario.Jan. The first time Jan is requested, the candidate Reply1 matches, based on contactId = 'Jan' and the state being 'Started'. On matching this candidate the state for scenario.Jan is set to 'Prospect' which will cause the next request for Jan to match Reply2.

Using the state machine

Resetting the state machine

The state machine can be reset by the menu option State machine->Reset or the script-function ResetStateMachine.
Resetting the state machine for an instance running remotely can also be done from the State machine menu.

State machine information

The menu option State machine->Information shows for each defined scenario it's name, it's current state and it's possible states.
If applicable, this information also shows states that can be set but are never required and required states that are never set, indicators for errors in data-entry.

Environment variables

Using environment variable to realize stateful behaviour requires scripting.

More information on working with environment variables


The script below realizes the fictitious scenario that every contact is a suspect the first time it is requested, a prospect the second time and a customer in all subsequent requests for that contact.

string := Req.getContactById.contactid;
string ws.contactTypeKey := 'contact[' + + '].contactType';

with do
  .contactId :=;
  .contactType := GetEnvVarDef (ws.contactTypeKey, 'suspect');
  if .contactType = 'suspect' then
    SetEnvVar (ws.contactTypeKey, 'prospect');
  if .contactType = 'prospect' then
    SetEnvVar (ws.contactTypeKey, 'customer');

The scripting above uses environment-variable names based on a key-attribute of the request. Initially the requested variable will not exist so the default value 'suspect' is used.
After filling the response attribute, the environment variable is set to a 'next' value for the next call for the same contact.
After the first request for getContactById with contactId = 'Jan' and two requests with contactId = 'Kees', below environment variables will exist:
contact[Jan].contactType with value prospect
contact[Kees].contactType with value customer

A more realistic scenario would be that you set the environment variable in another mocked operation that is a double for setting the contactType.