Before we go into any more technical details, let's look at a simple example.
This page demonstrates how to upload things and explains step-by-step how to create a Scenario Plan that does something useful.
If all you want to do is to showcase a program you wrote, this page should have all you need to know.
If you want to understand how Elody can let many programs by different developers work together, then you should also read the next three pages.
In this example we assume that we already have a program that does something useful, and we want to use Elody to publish this program.
We want to end up with a link that we can give to people with which they can quickly execute the program online.
We do this by providing a link to a Scenario Plan that is configured in such a way that the program we want to demonstrate is executed right at the start of the Scenario.
An example Scenario Plan demonstrating the Rules and Programs on this page can be found here. Simply click the button to start the Scenario, and a Message should appear asking you to enter parameters. You can also click this link instead to start the Scenario immediately.
This tutorial will demonstrate how to create such a Scenario Plan for your own programs, so that you can send a link to it to other people.
Before you can start, make sure you have done the following:
- Register an account with this website.
- Install and configure the lod-tools. You will use this tool to define Symbols and to upload Programs and Rules to Elody.
- Optionally, install and configure the lod-executor. This is not strictly necessary, but using it makes debugging much easier.
For this example, we are going to need two Symbols.
You can define new Symbols directly here, or you can create a text file to define the Symbols and pass it along with your Rule in the next step. If you have many Symbols, using a separate file for them is more convenient and also allows you to easily update the descriptions of the symbols when needed, so this is recommended.
This is what our file for defining Symbols looks like:
The tab 'original' shows the file you want to upload to create the symbols. This can be done using the following command:
lod-tools create-symbols -f "/path/to/a/file/describing/the/symbols/original.txt" -r "/path/to/a/file/describing/the/symbols/processed.txt"
The file in the tab 'processed' is the output file generated by this command.
As you can see, the file 'original' is written in a relaxed JSON format. It has the general structure of a JSON file, but missing quotation marks and commas and the like are inferred automatically and you can have linebreaks in strings.
As you can see if you follow these links, all references of the form [[program/rule/symbol:name/id]] in the descriptions of the Symbols have been turned into links. This also happens in the documentation of Rules and Programs and helps with navigating between objects.
The Symbol, Rule, Option and Program all have very similar names. This may be confusing at first, but it is actually intentional to make the relationship between these objects obvious. Pay close attention to whether the name is capitalized (Rule and Program) or not (Symbol and Option), and whether it uses hyphens (Rule and Option) or underscores (Symbol and Program).
If you use this website for a while, this will quickly become intuitive.
The names of Symbols, Rules, Options and Programs follow certain conventions. Specific prefixes are used to make it immediately obvious what the role of an object is in the grand scheme of things. For example, the below Rule starts with 'Demo-' because it is used for demonstrating something and is supposed to be triggered directly by a Scenario Plan. You can read more about this in the Best Practices.
The Scenario Plan
To make testing easier, you may want to create the Scenario Plan at this point.
Doing so is easy: just go to your list of plans and click the button to create a new one.
An example plan can be found here.
The following parts of this plan are important:
- It is not marked as 'private'. Otherwise other people won't be able to use it!
- It has the Symbol demo_a_simple_timeseries_prediction set as a starting tag, and the box that says it should be signalled is ticked (otherwise the Tag will be created, but it will not activate any Rules).
- You have set yourself as trusted. This makes sure that all your Rules get executed in the Scenario, even if the Rules have not received a high enough rating, yet.
- Optionally, you may decide to tick the checkbox 'Only trust explicitly'. If you do, then only your own Rules will be executed (since you have explicitly set yourself as trusted). This has the advantage that other people's Rules won't interfere with what you want to do. However, it also means that if you want your code to rely on Programs of other people, you will either have to call them yourself or manually set all those people and/or their Rules as trusted.
Once you have a Scenario Plan, you can show it to other people by copying its URL. If you want to create a link that will execute the Scenario immediately, add the parameter '?autostart' to the URL, like so: https://elody.com/scenario/plan/3/?autostart.
You can use the Scenario Plan to test your Rules and Programs after uploading them. Just start the Scenario Plan and use Developer Mode to check if Elody correctly executes the Rules and Programs you wrote. If any Rules or Programs result in an error, the Developer Mode will show an error message.
It is heavily recommended to also create a separate Scenario Plan for your own development and debugging. This way, you can change your programs later without interfering with the Scenarios other people are using. Simply create a second Scenario Plan that is identical to the first, except that it uses the !default_program_version Tag so that development versions of Programs are used, as in this Scenario Plan.
The Scenario Plan determines which Rules by other programmers are allowed to interact with your Scenario. You can check 'Only trust explicitly' in the Scenario Plan if you don't want anyone else's Rules to interfere. You can explicitly set some developers or their Rules as trusted to allow them to interact with the Scenario, or you can make no limitation at all and just let Elody decide which Rules to allow based on their ratings. Note that the checkbox 'Only trust explicitly' is checked in the example Scenario Plan linked above. If you uncheck this checkbox and run the Scenario, you will see if any other developers have written code that interacts with this example Demo (but only if they received a high enough rating).
This example does not require the user to enter text or upload files.
You can either add them to the starting tags of the Scenario Plan, or use a Rule to create them during the running Scenario when they are needed.
The Execution order
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.)
- Depending on the user's choice, the program will either visualize the 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.
The Rule is defined below. The tab 'Before validation' is the file that was uploaded to the server, using
lod-tools upload-rule -f "/path/to/a/file/describing/the/rule/Demo-a-simple-timeseries-prediction.txt"
The tab 'After validation' is the same Rule, but after the server has filled out any missing fields with default values.
Note that the Rule file has the same relaxed JSON format as the Symbols file. The fields called '_comment' explain what each part does.
The syntactical structure of Rules is complex. You can look at the documentation for a detailed explanation.
Additionally, if you open the page of the Rule by clicking the below link, you can look at the Rule in more detail on its own page. This 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.
Now that we have a way to call the Program, it is time to upload the Program itself.
As mentioned in the Rule, the name of the Program is 'Demo_a_simple_timeseries_prediction'. The below tabs show all the files the Program is composed of. Assuming these files are all in the same folder, we can upload the Program with:
lod-tools upload-program -n "The_name_of_my_program" -f "/path/to/a/folder/containing/the/program"
Note that this uploads the program as a development version, not a release version, since we did not use the '-r' option. As a a result, the program will only be available in the Scenario Plan meant for development. This makes it possible to work on your program later without changing what other users see until you are done making changes and debugging the program.
The file 'DESCRIPTION.txt' is documentation, the 'Dockerfile' and 'requirements.txt' are for Docker. The file 'app.py' contains the actual meat of the Program and is referenced by the Dockerfile. More complex Programs can of course be composed of multiple code files.
After uploading your Symbols, Rules and Programs, you can start your Scenario Plan to test things. If anything doesn't work as expected, you can use the Developer Mode to find out what the problem is.
If the error messages in the Developer Mode are not precise enough, consider using the lod-executor. With this tool, you can run all Programs of a Scenario locally.
The lod-executor creates a folder for each step involving a Program execution. Find the folder for the step where your Program fails, adapt your Program, and use this command to manually repeat the step that didn't work:
lod-tools test-program --help
You can also put print() statements in your Program, which will be put into a log file by the lod library.
Finally, don't hesitate to ask for advise on the forum!
Once you are done with debugging, don't forget to upload the program again with the '-r' option to mark it as a release version.
The program shown here can actually be called by other developers. A contributor who publishes a program with a simple demonstration rule does not need to understand the intricacies of how rules work, but if their program is good enough it can still get picked up and used by other developers anyway.
Once payment is implemented, they may even end up making money that way. (Elody will always leave it up to the developer who uploads the program whether or not they want to charge money for it.)
A more complicated Demo- Rule can make use of programs and rules of other developers. That way you can create a demo for your code even if that code relies on other programs that you didn't write yourself.
For example: At the end of the Program, if the user did not select the parameter use_inbuilt_visualization, the Tag demo_a_simple_timeseries_prediction_need_visualization is created. Rules created by other Programmers can now react to this Tag and provide a visualization.
The Symbol demo_a_simple_timeseries_prediction_need_visualization could be improved. Ideally, the Tags created to invoke other Rules should use Symbols that are already in use for that purpose. However, since this is the first part of the tutorial, we have no other choice but to create a new symbol because no other programs exist yet. If the programs you want to connect to already exist, you can be more proactive: check what symbols other rules are already using, and use those instead.
However, this is only an inconvenience, not a problem: As we will see later in this tutorial, it is possible to create intermediary Rules to add the missing Tags, and these intermediary Rules can even be created by other developers.
As Elody grows, contributors will add many useful general-purpose programs that can help to make your live easier. For example, the Tag task_get_user_feedback can be used to automate the process of getting feedback from endusers after they have used your program. It lets the enduser give written feedback, give ratings, or even send emails to their friends to advertise your program.
This concludes everything you need to know to make your programs available through Elody. The following pages will give more detailed explanations of the many ways Tags can be used, and demonstrate with examples how different Programs can be combined, even if they were written by different developers with little to no coordination between them.
There is an alternative to calling the programs of other developers in your Scenario: You can use the Symbol !export_object to export the results of the Scenario instead. The user can then import the object in other Scenarios later. This is useful if you do not want other developers to interfere with your Scenario directly, or if you create an important intermediate result that is relevant for many other Scenario Plans.