This page documents the syntax of all objects that can be created in a Scenario.
Each entry here is either a Node, which can be represented as a JSON object / Python dictionary when defining rules and options.
Sometimes, there is a choice of several different Nodes that can be used. In these cases, you can select the one you want using the 'type' field.
Note that this page is intended as a reference sheet. You do not need to read all this.
Option
An Option is created by a developer and used by Elody to determine what to do next.
Elody uses the confidence assigned to the Option using '!set_option_confidence' Tags to determine its priority relative to other Options.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| name | | | this field is required |
| The option name must consist of basic letters, numbers and dashes (-) and must begin with a lowercase letter. It may be at most 255 characters long.
|
| description | | can be null | default value: null |
| A description of the Option that should be understandable by other developers. A String with maximum length 5000.
|
| trigger | | | this field is required |
| A filter that is used to determine whether or not the Option should be executed. Additionally, the trigger can find arguments from the current scenario that are used as parameters later.
|
| display | | can be null | default value: null |
| A description of the message that should be displayed when Elody decides to offer the user the choice whether or not to select this Option. If this is null, this Option will never be offered for selection by the user. Note: If an Option is displayed, the arguments found by the trigger are determined at that moment. If the user selects the Option for execution, anything that would have changed the arguments selected by the trigger will be ignored.
|
| actions | | | this field is required |
| A list of actions that are executed when the trigger finds a suitable set of arguments to use and the Option is either selected by the user or has a high enough confidence to be executed immediately.
|
| existing_variables | | | default value: {} |
| This field is automatically generated. It summarizes which variables have been declared in this Option. If this Option was generated by another Rule or Option, it inherits any variables used by them at the moment of its creation. A mapping from string keys to content. The string keys are: The name of the variable. The name of a Rule or Option's variable must be at most 128 characters long and must consist only of a-z, A-Z, 0-9, underscores ('_') and hyphens ('-'). The content is: The type and value of the variable.
|
File
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| file | | | this field is required |
| A String with maximum length 260.
|
Tag
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| symbol_name | | | this field is required |
| The name of the Symbol to use for this Tag. A String representing a Symbol. The Symbol must exist.
|
| argument_identifiers | | | this field is required |
| |
| comment | | can be null | default value: null |
| The comment of the Tag (optional).
|
| weight | | can be null | default value: null |
| The weight of the Tag (optional). A Float value. Infinity and NaN are invalid.
|
Message
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| visibility | | | default value: "all" |
| Who this Message should be visible to. One of the following String values: 'all', 'developers', 'hidden'
|
| message_components | | | this field is required |
| |
Event (a choice of several types)
An event that can be executed by Elody.
Some of these can be created by rules and programs, others can only be scheduled by Elody herself.
| type | name | description |
|---|
default | Default event | The default event executed by Elody when it has run out of queued events. When this event occurs, Elody evaluates the situation and generates another event. It finds a suitable Rule or Option to execute, or finds a set of Options to present to the user, or decides that there is nothing to be done because there isn't enough information. This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness. |
execute_rule | Execute Rule event | An event to execute a Rule. This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness. |
execute_option | Execute Option event | An event to execute an Option. |
present_options | Present Options event | An event to display a list of Options to the user for selection. |
mention_uncertainty | Mention Uncertainty event | An event to mention to the user that Elody is uncertain what to do. This happens when too little information is available to do anything useful. This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness. |
execute_program | Execute Program event | An event to execute a Program. |
wait_for_signal | Wait event | An event to wait for more input from the user. |
user_command | User command event | An event to process input submitted by the user. This includes both text input and uploaded files, but not the selection of a displayed Option. This event can only be generated by the user. It can't be created by a developer and is only listed for the sake of completeness. |
Default event (A type of Event)
The default event executed by Elody when it has run out of queued events.
When this event occurs, Elody evaluates the situation and generates another event. It finds a suitable Rule or Option to execute, or finds a set of Options to present to the user, or decides that there is nothing to be done because there isn't enough information.
This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | can be null | default value: null |
| The arguments for this type of event. An arbitrary JSON-like object.
|
Execute Rule event (A type of Event)
An event to execute a Rule.
This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | can be null | default value: null |
| The arguments for this type of event. An arbitrary JSON-like object.
|
Execute Option event (A type of Event)
An event to execute an Option.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | | this field is required |
| The arguments for this type of event.
|
Execute Option event arguments
| Fields | | | |
|---|
| feedback_request_id | | can be null | default value: null |
| This is automatically set for each Option when Options are presented to the user. It can be used instead of the option_identifier, and one of the two must be set. An Integer with minimum value 0.
|
| option_identifier | | can be null | default value: null |
| Identifies the Option to execute. Must be set if feedback_request_id is not set.
|
| priority | | | default value: 100 |
| The priority with which the Execute Option event was selected for execution during a Default event, relative to other possible events. Does not do anything, but is logged for possible statistical optimization by Elody. This can be ignored, but is included for the sake of completeness. A Float in the range [0 ; 1000]. Infinity and NaN are invalid.
|
| confidence | | | default value: 100 |
| The confidence of the Option when it was selected for execution during a Default event. Does not do anything, but is logged for possible statistical optimization by Elody. This can be ignored, but is included for the sake of completeness. A Float in the range [0 ; 1000000]. Infinity and NaN are invalid.
|
| argument_dict | | | this field is required |
| The set of variables with which this Option will be executed. This will normally be the existing_variables field of the Option, but can be overwritten if necessary. A mapping from string keys to content. The string keys are: The name of the variable. The name of a Rule or Option's variable must be at most 128 characters long and must consist only of a-z, A-Z, 0-9, underscores ('_') and hyphens ('-'). The content is: The type and value of the variable.
|
| additional_parameters_selected_by_user | | can be null | default value: null |
| The parameters set here are stored in the file generated for the Option Display and that file is made available to the Option. If this Execute Option event came about because a user selected this Option from a list of displayed Options, then this value will be the set of parameters the user chose through Option Parameter Selector. An arbitrary JSON-like object.
|
| selected_button_index | | can be null | default value: null |
| The index of the button of the Option that was clicked by the user. If this is null, no button was clicked and the Option executed on its own.
|
| selected_button_text | | can be null | default value: null |
| The text that was displayed on the button of the Option that was clicked by the user. If this is null, no button was clicked and the Option executed on its own. A String with maximum length 1024.
|
Present Options event (A type of Event)
An event to display a list of Options to the user for selection.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | | this field is required |
| The arguments for this type of event.
|
Present Options event arguments
| Fields | | | |
|---|
| priority | | | this field is required |
| The priority with which the Present Options event was selected for execution during a Default event, relative to other possible events. Does not do anything, but is logged for possible statistical optimization by Elody. This can be ignored, but is included for the sake of completeness. A Float in the range [0 ; 1000]. Infinity and NaN are invalid.
|
| options | | | this field is required |
| |
Option with confidence and arguments
| Fields | | | |
|---|
| confidence | | | this field is required |
| The confidence of the Option of an Present Options event when it was selected for execution during a Default event. Does not do anything, but is logged for possible statistical optimization by Elody. This can be ignored, but is included for the sake of completeness. A Float in the range [0 ; 1000000]. Infinity and NaN are invalid.
|
| option_identifier | | | this field is required |
| |
| argument_dict | | | this field is required |
| The variables of the Option being presented. This is normally the field 'existing_variables' of the Option, but can be overwritten if necessary. A mapping from string keys to content. The string keys are: The name of the variable. The name of a Rule or Option's variable must be at most 128 characters long and must consist only of a-z, A-Z, 0-9, underscores ('_') and hyphens ('-'). The content is: The type and value of the variable.
|
Mention Uncertainty event (A type of Event)
An event to mention to the user that Elody is uncertain what to do. This happens when too little information is available to do anything useful.
This event can only be generated automatically. It can't be created by a developer and is only listed for the sake of completeness.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | can be null | default value: null |
| The arguments for this type of event. An arbitrary JSON-like object.
|
Execute Program event (A type of Event)
An event to execute a Program.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | | this field is required |
| The arguments for this type of event.
|
Execute Program event arguments
| Fields | | | |
|---|
| program_identifier | | | this field is required |
| |
| argument_dict | | | this field is required |
| The files provided to the Program as inputs. A mapping from string keys to content. The string keys are: The name with which the Program can access the object. The name of a Rule or Option's variable must be at most 128 characters long and must consist only of a-z, A-Z, 0-9, underscores ('_') and hyphens ('-'). The content is:
|
| argument_list_dict | | | this field is required |
| The objects provided to the Program as inputs, for lists of multiple objects at once. A mapping from string keys to content. The string keys are: The name with which the Program can access the list of objects. The name of a Rule or Option's variable must be at most 128 characters long and must consist only of a-z, A-Z, 0-9, underscores ('_') and hyphens ('-'). The content is:
|
| max_execution_duration | | | derived field, do not set! |
| The duration (in seconds) after which the Program is interrupted if it still hasn't finished executing yet. This value is derived automatically from the program_identifier and should not be set. A Float value. Infinity and NaN are invalid.
|
Wait event (A type of Event)
An event to wait for more input from the user.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | can be null | default value: null |
| The arguments for this type of event. An arbitrary JSON-like object.
|
User command event (A type of Event)
An event to process input submitted by the user.
This includes both text input and uploaded files, but not the selection of a displayed Option.
This event can only be generated by the user. It can't be created by a developer and is only listed for the sake of completeness.
| Fields | | | |
|---|
| identifier | | | this field is required |
| The Identifier of this object. When you create an object with a Program, it should have a preliminary Identifier. Once it is accepted by the server, it will get a non-preliminary one.
|
| priority | | | default value: false |
| Whether or not this Event should be given priority and executed before other Events. Normally, Events are added to a queue and processed in order. The events with priority come before any events without priority.
|
| args | | | this field is required |
| The arguments for this type of event.
|
User command event arguments
| Fields | | | |
|---|
| command_subtype | | | this field is required |
| A specification of the subtype of the user command. One of the following String values: 'initialize', 'submit_data', 'change_parameters', 'create_objects'
|
| command_text | | can be null | default value: null |
| The text entered by the user, if any. If this is null, no text was entered.
|
| files_dict | | can be null | default value: null |
| The files uploaded by the user. If this is null, no files were uploaded. A mapping from string keys to content. The string keys are: The content is: The path where the file was saved. This is independent of the file's official name.
|
| parameter_values | | can be null | default value: null |
| New values for the parameters the user uses for his scenario. If this is null, the parameters were not changed. A mapping from string keys to content. The string keys are: The name of the parameter. The content is: The new value of the parameter. An arbitrary JSON-like object.
|
| objects_to_create | | can be null | default value: null |
| A list of scenario objects to create. If this is null, no objects should be created. An arbitrary JSON-like object.
|
