Using scenarios¶

The Scenario service enables you to simulate and test your application using the Kanzi Connect service interfaces.

Scenarios consist of scripts, namely lambdas, and bindings that define when a script runs:

The Scenario service bindings are:
- Data triggers are set off run when runtime data that you set changes.
- Event triggers are set off when an event in a service occurs.
- Timer triggers are set off with a delay at time intervals for the set amount of times.
The Scenario lambdas have access to service runtime data, and invoke events and methods. To keep the application responsive, make sure that lambdas are relatively fast operations.

Kanzi Connect runs the scenarios on the Kanzi Connect server main thread.

Scenario lambdas¶

Lambdas have access to service runtime data, and invoke events and methods. For a scenario to be valid, it must contain at least one lambda and trigger. The syntax is similar to service scripting, but not limited to one service. See Using service scripting in the Kanzi Connect Simulator.

Scripts do not have to depend on a service, but they usually do. While a scenario is running, instances of depending services are kept alive. If a scenario depends on a service, and that service is not available in your application, the Scenario service writes a warning to the Kanzi Connect Server log, but the service still runs that scenario.

The Scenario service parses scenarios and their lambdas only when you start that scenario.

While service scripting works only with a service running on a Kanzi Connect Server, scenarios can control also remote services. However, there are some limitations when you run a service remotely:

Method calls to remote services run asynchronously, and thus cannot return values. This is similar to Kanzi applications: you can subscribe to an event and observe the state change using a method.
You cannot directly write to remote service runtime data. If remote service routes its data through a Kanzi Connect Server, the implementation can modify the mirror on that server but remote service cannot see the changes. If a scenario requires a change to a remote service runtime state, define the values writable in the service schema and use the auto-generated setter methods.

Limitations of lambdas:

Lambdas cannot call other lambdas.
Lambdas do not return values.
Lambdas cannot use busyloops or perform long lasting synchronous tasks, because they would block other tasks.
Enums are not supported on scenario scripts.

Calling a service¶

To call a service in a lambda

[ServiceName]:[target]

For example:

To use Media service to start playing playlist 1001
```
call_method('Media:playPlaylist',1001);
```
To invoke in the Media service the progress event
```
invoke_event('Media:progress',15,150);
```

To get from the System service the demo.vehicle_color runtime data

car color = get_runtime_value('System:demo.vehicle_color');

Functions¶

To store value pairs in strings

set_context_value('changeInValue', 250);

To retrieve a value in the same or another lambda within a scenario

var changeInValue = parseFloat(get_context_value("changeInValue"));

To stop a scenario in a lambda
```
request_exit();
```
Exit request stops all scenarios that use that lambda and clears all bindings in that scenario.

Creating a scenario¶

In this section you create a scenario that reacts to the value of the speed data object in the Cluster service by playing a track provided by the Media service. When the value of the speed data object is lower than 100, the scenario plays the 1002 track, and when the value is higher than 100, the scenario plays the 1007 track.

To create a scenario:

In Kanzi Studio create a project with the Kanzi Connect Client Application project template.
In the Kanzi Studio main menu select Kanzi Connect > Open Kanzi Connect Simulator.

Kanzi Studio opens the Simulator in your default browser. If you do not have Kanzi Connect Server already running on this computer, this command also starts the Kanzi Connect Server that is installed on your computer.

Note

The Kanzi Connect Simulator officially supports only the Google Chrome web browser.
In the Simulator select Scenarios.
In the Scenarios panel click and in the New Scenario window set:
- Name to the name that you want to use
  
  You use this name to access a scenario in Kanzi Studio.
  
  For example, name the scenario MyScenario.
- Dependencies to the services that this scenario requires before it can run
  
  In order to use a scenario, the dependency services that you add here must be present on the Kanzi Connect Server and in your application.
  
  For example, add dependencies to the Cluster Service and Media Service.

Create scripts that define your scenario:

In the scenario that you created click and name the script.

For example, name the script setup.

In the scenario script editor add to the setup script this script

call_method("Media:playTrack",1002,1007);
set_context_value("direction", "down");
set_context_value("threshold", "100");

Create another scenario script, name it change_track, and use this script

var direction = get_context_value("direction");
var threshold = parseFloat(get_context_value("threshold"));
var current_speed = get_runtime_value("Cluster:engine.speed");
if (direction == "down" && current_speed > threshold)
{
    call_method("Media:next");
    set_context_value("direction", "up");
}
else if (direction == "up" && current_speed < threshold)
{
    call_method("Media:previous");
    set_context_value("direction", "down");
}

../../_images/scenario-change_track-script.png

Create the trigger to run the setup script. In the Triggers section click and in the New Trigger window set:
- Type to how you want to set off this trigger:
  - Data triggers are set off run when runtime data that you set changes.
  - Event triggers are set off when an event in a service occurs.
  - Timer triggers are set off with a delay at time intervals for the set amount of times.
  For example, create a Timer trigger.
- Repeat to the number of times that you want to run the script when this trigger is set off:
  - To run a script only once, set to 0.
  - To run a script indefinite amount of times, set to -1.
  - To run a scrip a set amount of times, set to that amount. For example, to run the script only once, leave the value at 0.
- Initial Delay to the time in milliseconds after which you want to run the script
- Interval to the time in milliseconds after which to repeat the running of the script
Repeat the previous step, but create a trigger to run the change_track script:
- Type to Data
- Source to Cluster:engine.speed
  
  This way you set the trigger to monitor the value of the engine > speed data object in the Cluster Service data source.
In the scenario that you created click .

This way you deploy the scenario to Kanzi Connect Server.
In the Kanzi Studio main menu select Kanzi Connect > Open Kanzi Connect Editor.

Use the Kanzi Connect Editor to create and manage connections to Kanzi Connect servers and services.
In the Kanzi Connect Editor click + Add Connection and in the Select Connect Server window click Connect.

That way you create a connection to a Kanzi Connect Server. You can see the connection in the Kanzi Connect Editor.
- The Server IPV4 Address property sets the IP address of the Kanzi Connect Server that the Kanzi Studio Preview uses to connect to the server and look for Kanzi Connect services available on that server.
  
  Here you use the default Kanzi Connect Server running on the local host at the IP address 127.0.0.1.
- The Server IP Address property sets the address of the Kanzi Connect Server that the client application uses during runtime.
In Kanzi Studio in the Kanzi Connect Editor click + Import Service, in the Import Connect Services window select the Cluster, Media, and Scenario services, and click Import.

This way you import from the Kanzi Connect Server the Scenario service and the Cluster and Media services on which the Scenario service depends.
Use the speed data object from the Cluster service:
1. From the Data Sources window drag the Cluster data source to the RootPage node in the Project.
  
  This way you set the Data Context property of the RootPage node to the Cluster data source. By setting the Data Context property you tell your application from which data source it receives data. Now all the data in the Cluster data source is visible to the RootPage node and all its child nodes.
2. In the Project create a node where you want to use the data from the Cluster service.
  
  For example, in the RootPage create a Text Block 2D node.
3. From the Data Sources window drag the Cluster > engine > speed data object to the Properties window Text property.
  
  The Text Block 2D now shows the value that comes from the Cluster service.
Control the starting and stopping of the scenario:
1. In the Assets set Source to Factory Content and drag the Toggle Button to the Preview.
2. In the Project select the Toggle Button node, in the Node Components add the Toggle Button: Toggled On trigger, add to that trigger the Scenario: startScenario action, and set the Scenario.startScenario.name to MyScenario.
  
  You set the Toggle Button to start MyScenario when the user toggles on the button.
3. Add the Toggle Button: Toggled Off trigger, add to the trigger the Scenario: stopScenario action, and set the Scenario.stopScenario.name to MyScenario.

In the Preview when you toggle on the Toggle Button, the Toggle Button: Toggled On trigger executes the Scenario: startScenario action which in turn runs the MyScenario that you defined in the Simulator. When the value of the speed data object, that the Text Block node shows, is lower than 100, the scenario starts playing the 1002 track using the Media service, and when the value is higher than 100, the scenario starts playing the 1007 track.

Creating a scenario using snippets and references¶

Snippets and references enable you to add common functionality to scenario scripts without writing any code yourself.

The recommended workflow is to first add a code snippet, and then add a reference inside the code snippet.

To create a scenario using snippets and references:

In Kanzi Studio create a project with the Kanzi Connect Client Application project template, open the Open Kanzi Connect Simulator and select Scenarios.
In the Scenarios panel click and in the New Scenario window set:
- Name to the name that you want to use
  
  You use this name to access a scenario in Kanzi Studio.
  
  For example, name the scenario MyScenario.
- Dependencies to the services that this scenario requires before it can run
  
  In order to use a scenario, the dependency services that you add here must be present on the Kanzi Connect Server and in your application.
  
  For example, add dependencies to the Cluster Service and Media Service.
Create a script that defines your scenario:
1. To add a code snippet to your script, click + Snippet.
  
  For example, to add a function that sets the value of a service data element, click + Snippet, and click the SetDataValue snippet.
2. To add a service element references to your script, click + Reference and select the service element that you want to use.
  
  Using the + Reference you can add data, method, and event elements of services that you set as dependencies of your scenario.
  
  For example, to add a reference to an element in your script, click + Reference, and in the Media service for the current_track element group click the data element name.
This way you add this code to your script.
```
set_runtime_value("Media:current_track.name", 0);
```

Using scenarios¶

Scenario lambdas¶

Calling a service¶

Functions¶

Creating a scenario¶

Creating a scenario using snippets and references¶

See also¶