Uploading code to Elody takes a bit of effort to start with, because you need to set up the mechanism that allows a user to run your software with one click. This page doesn't just explain how to write Hello World, it also explains how to set everything up so that Elody says "Hello World!" exactly when you want it to.
In this example you will learn:
- How to define a Scenario Plan with its own URL. Anyone can use this Plan to run your code with one click.
- How to create a Symbol and a Rule.
- How to trigger a Rule you created from the Scenario Plan, and make it print a Message to the user.
Note that this example does not require uploading any of your own Software, yet.
We want to create a Scenario Plan that simply triggers a single Rule right after it starts. That Rule should print "Hello World!" to the user.
This basic setup is very useful for demonstrating programs to other people: Your Scenario Plan has a URL of its own. Other people only need to visit that URL to immediately see what you want to show them, directly in the browser. You can put this URL on your website, your Github, or your CV, or anywhere else where it could be useful to provide a very easy way to use your software. The rest of the tutorial will create Scenario Plans just like this, only with more complex Rules.
An example Scenario Plan demonstrating the Hello World example on this page can be found here: (Tutorial) Hello World. Simply click the button to start the Scenario, and the "Hello World!" Message should appear.
Before you can start, make sure you have done the following:
- Register an account with this website.
- Install Python 3 and pip.
- Optionally, create a virtual Python environment for Elody.
- Install and configure the lod-tools. You will use this tool to define Symbols and to upload Programs and Rules to Elody. The lod-tools require Docker for uploading programs, but this is not necessary yet, at this stage of the tutorial, so it's fine if you ignore Docker for now.
The first step is to create a Symbol that we can use to trigger our Rule.
Symbols consist of nothing more than a name and a description. They do not contain any logic of their own.
The Symbol we use for this will be called "demo_hello_world". The prefix "demo_" is used according to the Best Practices, because the Symbol is used to trigger a Rule directly from a Scenario Plan in order to demonstrate something.
A warning about names
The example Symbol and Rule given on this page have already been created. All Programs, Rules and Symbols on Elody must have unique names. That means that attempting to recreate the tutorial exactly as it is will fail, because it has already been created.
To create this Hello World example for yourself, you need to change the names of the symbol and rule on this page to something that hasn't been used before.
The easiest way to do this is to just pick a string and add it at the end of every occurrence of 'demo_hello_world' and 'Demo-Hello-World' on this page. For example, if you are called John Smith you could use demo_hello_world_john_smith_1 instead of demo_hello_world. Be sure to use the names consistently, or you could accidentally end up running someone else's Hello World example in your Scenario Plan.
This also applies to other examples of the tutorial: Elody does not allow duplicate names, so always add a suffix at the end of each Symbol, Rule, and Program that appears in this tutorial if you want to try implementing it yourself.
Defining your own Symbol
You can define new Symbols directly here, or you can create a text file to define the Symbols and upload it with the lod-tools. If you have many Symbols, using a separate file for them is more convenient, so this is recommended.
This is what our file for defining Symbols looks like:
You can upload this file and create the Symbol in it using the following command:
lod-tools create-symbols -f "/path/to/a/file/describing/the/symbols.txt"
As you can see, the file 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.
The Symbol created by running this command can be found here.
As you can see if you follow this link, the reference [[rule:Demo-Hello-World]] has been turned into a link to the Rule, which we will define below. All references of the form [[program/rule/symbol:name/id]] in the descriptions of the Symbols are automatically turned into links. This also happens in the documentation of Rules and Programs and helps with navigating between objects.
Notes about naming objects
The Symbol and Rule, defined here, as well as the objects defined on the following pages, 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 create a Scenario Plan, go to the list of Scenario Plans and click "Create new scenario plan" (you must be logged in for the button to appear).
Note that a Scenario Plan has two different views: One for endusers, and one for Contributors. The former just gives a description of the plan. The latter allows you to inspect and change the technical details. You can switch between the views using the tabs at the top of the screen.
Open the example Scenario Plan (Tutorial) Hello World and click on the "CONTRIBUTOR" tab at the top, to view the technical details. Make sure that your own Scenario Plan looks the same. Here is what each item does:
- Name and Description are just that. They are visible to Endusers, so make sure you enter something nice and descriptive, so that people will understand what your Scenario Plan is about. If you want to reach a non-technical audience, make sure that this description is understandable to non-technical people as well.
- When you are viewing a Scenario Plan you created yourself, there is a checkbox marked "Private". If this is ticked, only you can see this Scenario Plan. This is useful for experimenting, but you must not forget to uncheck that box if you want to show your Scenario Plan to other people.
- Under "Starting Tags", we need one entry for the Symbol we have defined. In the example, this is demo_hello_world. Make sure that your example uses the Symbol you defined instead, since demo_hello_world is already defined. Also make sure that the check box marked "Signal" is ticked: This basically tells Elody that this Tag is not just descriptive, but is actually intended to trigger something. More on this later.
- Under "Special treatment of individual developers" you need to do two things:
- Tick the check box marked "Only trust explicitly". This tells Elody that it should not use any Rules defined by anyone else, regardless of their ratings. Only Rules that you explicitly mark as trusted will be used when the Scenario is run. This is useful if you want to demonstrate something without the risk that Elody does something unexpected. Since this is a demonstration, we don't want other people to interfere, so let's tick that checkbox.
- Under "Developers", add yourself and mark the entry as "trusted". This tells Elody that all Rules that were created by you should always be trusted and used, regardless of their rating. This allows you to test new rules that haven't yet received a high enough rating to run on their own, or to prevent existing rules from interfering with what you are trying to do.
- Instead of marking yourself (the user) as trusted, you could also mark only a particular Rule as trusted under "Special treatment of individual Rules". This is useful if you want to experiment with different configurations, but is not really necessary here.
Here is what happens when a user starts this Scenario Plan:
The Scenario will start, and it will instantiate the Symbol demo_hello_world in the form of a Tag. This in turn will trigger the Rule that we will define below. Think of these concepts like this:
- The Symbol is the definition of a word in a dictionary, with a description of its meaning.
- A Tag is an instance of a word being spoken.
- The Scenario Plan starts by "speaking" a word (creating a Tag), and thereby gives an order to Elody.
- The Rules listen to the orders Elody receives, and can react to them.
Once you have a Scenario Plan, you can show it to other people by copying its URL (be sure to remove the "?tab=enduser" or "?tab=contributor" part). 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/77/?autostart.
The only thing left to do is to define the Rule.
The file for defining the Rule looks like this:
Don't forget to rename the Rule and to replace demo_hello_world with whatever Symbol you are using for your own example!
The file can be uploaded to the server, using the following command:
lod-tools upload-rule -f "/path/to/a/file/describing/the/rule/.txt"
Note that the Rule file has the same relaxed JSON format as the Symbols file.
Let's see what each part does:
- The 'name' field is the official name of the Rule. This is unique. Uploading a Rule with the same name again will create a new version of the Rule. If you change the name of the Rule and upload it, don't forget to deactivate the original Rule, or both will be active simultaneously.
- The 'description' is just that.
- The 'dependencies' are a list of Symbols that must be present for the Rule to become active. We list only demo_hello_world.
- The 'trigger' can list additional criteria to choose when exactly the Rule should fire, and to select parameters for it. Since this is not necessary here, we leave it blank. Triggers can do a lot of things, and will be explained later in the tutorial.
- The 'actions' are a list of actions that are performed when the Rule executes. This Rule has only one action, of type create_message. A create_message action can display a Message consisting of multiple components. We use just one component, which is the text "Hello World!".
You can open the page of the uploaded Rule here. On that page, the JSON format of the Rule is written out and annotated with links to the documentation. This makes it easy to look up the relevant sections of the documentation and find out what a Rule does, and is helpful for debugging.
The Execution order
Here is what will happen when the Scenario starts, in order:
- A demo_hello_world Tag is created, because the Scenario Plan specifies it.
- This Tag triggers the Rule Demo-Hello-World.
- The Rule creates a "Hello World!" Message object, which is displayed in the browser.
- Since there is nothing else to do, Elody enters a waiting state.
If everything worked, your plan should work exactly like the example Scenario Plan (Tutorial) Hello World, and displays "Hello World!" when it is run.