In this example you will learn:
- How to ask a user for input arguments.
- How to give arguments to a Progam.
- How to create an Option from within a Program, and alter the control flow.
- How to delegate a task to Elody, so that other Developers can react to it. (Doing this will be a test later in the tutorial)
- How to give the user a file to download.
- How to ask the user for a rating.
The Scenario Plan demonstrating the Rule and Program on this page can be found here: (Tutorial) Demo of a simple timeseries prediction.
The Execution order
The Execution order of this Scenario Plan is a little different from before, because we ask the user for input and need to verify that the input is valid.
Here is what will happen when the Scenario starts, in order:
- A demo_a_simple_timeseries_prediction Tag is created, because the Scenario Plan specifies it.
- This Tag triggers a Rule, defined below.
- The Rule creates an Option, which Elody presents to the user and which asks them to choose parameters.
- When the user is done entering parameters and submits the Option, it runs the Program we want to demonstrate and passes the selected parameters to it.
- Optionally, if the parameters entered by the user were invalid, the Program will create another Option so the user can try again. This repeats until the entered parameters are valid. The Program is run again each time.
- Once the input is valid, the program makes a prediction. Depending on the user's choice, it will either visualize the resulting file using a simple, inbuilt visualization, or it will create a Tag that signals other Rules that there is a file that needs to be visualized. In this way, other developers can extend this Program.
The Rule defines an Option to ask the user for input. This Option is not much different from the Options you have seen before.
- Some of the message_components of the display field are now of type "option_parameter_selector". These are used to give the user a way to enter input data.
- The display field defines a parameter_file_name field. This field defines a variable with the name "userParametersFile" that can be referenced later in the Option. It also creates a File and assigns it to that variable. The parameters the user selects using the option_parameter_selector fields are stored in this file (in JSON format) when the user clicks the Option's submit button.
- The execute_program action now has an additional field called "arguments". We can use this to make any variables of the Option available to the Program. We use it to give userParametersFile to the Program, under the name user_parameters_file. ("userParametersFile" is the name for the variable used by the Option, "user_parameters_file" is the name used by the Program for the File it receives)
Note about variables
Elody's Rules and Options can use variables. It is important not to confuse Elody's variables, which reference Elody objects (Programs, Rules, Symbols, Files, Messages, etc.) with the variables defined by the option_parameter_selectors.
All of the parameters the user chooses through option_parameter_selector message_components are stored in a single File, and that File is assigned to the Elody variable userParametersFile.
By the way: The Option's confidence is set to 1000 because that is very high and guarantees that the Option will be displayed. At the same time, the display has 'must_always_be_shown' because normally an Option who's confidence is this high will be executed immediately without being displayed to the user first. Since we rely on parameters entered by the user, we must force the Option to be displayed instead of executed.
If anything is unclear, you can look at the documentation for a detailed explanation. Additionally, you can look at the Rule in more detail on its own page, here. This page includes annotations and links to other objects and to the appropriate parts of the documentation, which can help you to understand the Rule more quickly. This is also useful for debugging your own Rules.
Some highlights of this Program:
The Program can open the user_parameters_file it receives as an input from the Rule.
The parameters the user selected via the option_parameter_selector message_components are elements in that file.
While most of the option_parameter_selector parameters are validated directly by the Option, the parameter 'timeseries' is not, since there is no predefined way to check if a text is a list of numbers. Therefore, the Program has to test this first.
If the timeseries is invalid, the Program recreates the Option that triggered it, to give the user another attempt to enter valid data.
This can repeat as often as necessary until the user enters data correctly.
The user can select a parameter called use_inbuilt_visualization.
If this is true, the Program uses a standardized message_component_plot to visualize the result.
If this is false, the Program instead creates a demo_a_simple_timeseries_prediction_need_visualization Tag. It is now up to other developers to write Rules that respond to this Program. Doing this is an excellent challenge for later in the tutorial.
- The Program offers the created files for download.
- The Program creates a form to ask the user for feedback. Any feedback entered here is automatically posted to the forum, so that you can review it.