It is good practice to comment and describe rules, rule sets and repositories in Tomorrow Software. Comments and descriptions help explain the purpose of the design and why it was designed in the specific manner. It also makes life easier for the next rule writer, reducing the overhead associated with association and learning.

Rule Commenting

Each rule should be commented with an appropriate description that explains what it does. Rule comments could begin with a verb that briefly describes the activity.

Comments can also be added in the rule set page as a floating text box, with the “Comment” rule. This can be used to describe the purpose of specific rule activity on the page, or detailed technical information regarding the rule set.

Rule set and repository descriptions

Rule sets and repositories should be given an appropriate description as to help understand their purpose.

Rule set example:

Repository example:

Make use of Tomorrow Software configuration features that allow for application configuration, avoiding the need for maintenance of custom configuration files.

An advantage of the Tomorrow Software configuration is that access to the configuration can be centrally controlled through the Tomorrow Software console and permissions can be granted or revoked for any Tomorrow Software users.

System administrators should ensure that the Tomorrow Software file system has restricted access, so that changes to the Tomorrow Software file system can only be done through the same user that executes the Tomorrow Software console

Below is an example of a configuration that has “Global Fields” which are used to set application settings, that can easily be changed in the “Servers” node, once the configuration has been deployed.

In the “Servers” node below, under the corresponding server to which our configuration has been deployed, we can change the application settings that have been declared as “Global Fields”. Under “Server Settings” choose “Change..”.

These settings do not need a configuration redeploy to take effect.

Separation of code and data.

Avoid hard-coded html in the rules, instead use tag replacement techniques or templating techniques (custom templating, template engines, frameworks or CMS’s) that help separate code (business logic) from data (html output).

This helps web designers to focus only on the code relevant to the user interface and not any business logic.

Custom templating should be designed in such a way that it is directly related to the data output

with the use of “if”, “while”, “for”, “foreach”, “switch” control structures

and it should be readable.

The selected templating technique should be consistent throughout a solution, avoiding confusion.

Two tag replacement techniques are detailed in the Appendix A. For more advanced options, like the use of control structures, a templating engine should be used.

Content Files

Include static files, such as js/css libraries in the “Content Files” node.

File and folder organization should be agreed upon by the team, and remain easy to understand and structured.

Data Files

Include data files, such as html, CSV files in the “Data Files” node. A benefit of reading from “Data Files” is that it will be memory cached, and you can update it without redeploying all rule sets, but simply by deploying the data file on its own.

Data Sets

For smaller applications Data Sets are a preferred way to store data, instead of using SQL statements. Data Sets are incredibly flexible and do not require modifications to the schema for every new field or feature.

See the Data Set rules to study an example.

Data Sets are more than adequate for anything up to about 100,000 elements and they offer flexible “key-on-anyfield” and “add a new field any time you like without stopping” capabilities.

Data Input

Custom functions in the Tomorrow Software console can be used as an interface for corporate end-users who have been assigned the role of application/user data maintenance, such as localization data, selection list data, user data, csv files or databases.

User access to desired custom functions can be granted to users through the Tomorrow Software console, by a Tomorrow Software administrator.

Memory Considerations

Consider increasing maximum memory usage when reading from large files that their content needs to be saved to a variable for further processing (i.e., “File Reader” rule), by changing java startup properties in your Tomorrow.bat file. If the file just needs to be forwarded to a http client, then use the “HTTP File Response” rule.

Incorporate internationalization into your rule sets with the use of csv files (or Data Sets).

Consistent rule layout.

The way rules are layout in a rule set is a matter of preference. There is no "best" style that everyone should be following.

The best style is a consistent style.

If you are part of a team or if you are contributing to a project, you should follow the existing style that is being used in that project.

Avoid overly complex & large rule sets.

As a rule of thumb, rule sets should not have more than a dozen rules in them, for the sake of clarity and readability.

Modularize rule sets

Keep your rule sets modularized and specialized. It is tempting and easy to write one rule set that does everything. However, as you extend the functionality you will find that you do the same things in several sequences of rules.

To prevent that, make sure to write smaller, generic helper rule sets that fulfil one specific task rather than do all tasks.

At a later stage, you can also expose these rule sets to other repositories.

Rule sets can also be extended by new rule sets that include them and add more functionality. Well-designed rule sets should be easy to extend without redesigning the core.

Reusability

A sequence of rules that achieve the same outcome should not exist multiple times. These repeatable rules should be grouped into rule sets, where the same logic can easily be reapplied.

Parameterized included rule sets (rule sets as extensions) are advised, as they are similar to the X Engine’s rules in that they have clearly defined input/output parameters and can be included in other repositories for reuse.

Below is an example of a parameterized include rule set (rule sets as extensions).

You can access the input/output parameters under the “Rule Info” tab, on the left pane of a rule set page.

Rule set exit rules

Exit rules in any given rule set determine what chain points will be available for that rule set when it is embedded into another page.

Exit rules for success and failure should be included in rule sets for error handling and easier debugging.

The below example shows checks the user’s status and appropriately exits either with success or failure.

Below you can see the resulting chain points “OK” and “Fail”, of the “CheckUser.xml” rule set that is included in the “ProcessLogon” rule set.

Platform Independent

The goal is interoperability. Operating system, database or environment specific logic like the usage of AutoID in MySQL, for example, should be avoided.

The “Next Number” rule creates cross platform next numbers

The environment to which we have deployed your solution should be irrelevant to the rules.

Error handling

Error handling logic should be incorporated in the rule set flow, and ideally a single rule set should handle and output all errors, with appropriate error identifiers/messages.

Optimize Loops

Loops can get unnecessarily slow if you’re doing things in them that could be done one time before entering the loop. Like setting a variable in a loop whose value doesn’t change.

If possible, computation-heavy code should be kept outside of loops.

Native rules

Only use rules (extensions) that are available and supported within Tomorrow Software.

Consistent Naming Scheme

Names should have word boundaries. There are two popular options:

• camelCase (first letter of each word is capitalized, except the first word)

• and underscores between words (like “user_surname”).

The underscore naming scheme in combination with the camelCase scheme is proposed for rule set names, as it can easily depict hierarchical structures, as shown below.

Repository names tend to be more humanly readable and are space separated words (“Rule Wizard”, “Silly Selfies”, “Notepad Demo”). But consistency is always important, no matter what naming scheme is used.

Variable Names

Give readable variable names that are easily distinguishable in a variable listing and are helpful for debugging.

Variable names should also be independent of platform or environment, e.g. CUSTOMER_NAME and not DEV_CUSTOMER_NAME.

Capital letters with underscore-separated words are proposed for the Tomorrow Software environment. Below is a variable list example:

Temporary Variable Names

Temporary variables with the same prefix could all be deleted with the “Delete Selected Variables” rule which could be called before the rule set exit. This is a proposed practice, as it cleans up the variable list, which makes it easier for debugging.

Below is an example of setting the variable “TEMP_COUNTER” and later deleting it before exit.

The resulting variable list on exit is shown below. Here you can notice that the “TEMP_COUNTER” variable is missing.

File Names

Variable values or parameter values that are file names should be case-sensitive.

In the below example the file’s name is “index.html” and therefore the parameter “File Name” should have the exact same case-sensitive value.

Unnamed numerical constants

Avoid using unnamed numerical constants, as to make clear what the number is supposed to represent, and to accommodate future changes. Its value can be set into a variable, and then the variable can be used wherever needed.

In the future if a change needs to be made to this value, it can easily be made once only in the “Set Variable” rule.

In the example below the variable “DAYS_IN_WEEK” is assigned the value “7” instead of using the number “7” directly in the “Counting loop” rule.

Avoid conflicts in rule set names among repositories

Rule sets that are exported from the repository should have unique names so that there are no clashes with other rule sets in the repositories in which they are included.

Below is an example of the repository “User Agent Detection” being included into the DEMO_REPO repository, under the label “Include data, content and rule sets from:”.

This guide provides a number of helpful hints and best practices for rule writing, while designing a Tomorrow Software solution.

It assumes that the reader is familiar with the Tomorrow Software Console and with rule writing within Tomorrow Software.

We strongly encourage you to follow these conventions to ensure that your rules are easy for fellow rule writers to follow and modify.

This particular document is subject to frequent revisions and we encourage anyone writing Tomorrow Software rules to contribute. If you have a methodology that you would consider best practice, please share it with us via email to support@tomorrowx.com.

The Best Practice repository demonstrates tag replacement techniques.

The initiator rule set “BestPractices_Init” calls the “SetupData” rule set that prepares the data that will be used in the “CreateOutput” rule set, where the output will be produced in html format.

The “CreateOutput” rule set contains the “Template Replacer” rule that uses the simple tag replacer technique to replace all identifiers in the html content, with the given variable names.

The “Fill Html List”, “Fill Html Options” and “Fill Html Table” helper rule sets that are part of the “HTTP Tools” repository, use the “tag replacement with parent tag repetition technique”, allowing for the repetition of html code already found in the “homepage.html” file and avoiding any hard-coded html in the rules.

Displaying a list of runtime variables in the console with the “List variables for Debug” rule or alternatively the "List variables on exit" rule is a proposed practice for debugging in Tomorrow Software. These rules display the variable list only when “Debug mode” is enabled in the configuration.

This helps you control the listing (or not) from the configuration before deployment, which is much easier to manage.

Usage of the “List variables” rule should be avoided. An easy way to find any leftover “List variables” is to use the “Document” button in the configuration and to search for it within the produced PDF.

Simple tag replacement.

A special tag is inserted in the html page, where we desire data to be inputted. The tag could be of the form “$tag_name$” or any other selected format that will uniquely identify it in the html page.

Use the “Template Replacer” rule to replace unique tags in the html page with the values of given parameters.

Tag replacement with parent tag repetition.

It is similar to the previous technique, with the added benefit of finding the parent html tag of the unique tag, in order to repeat it.

This is useful, for example, when we want to add new table rows without changing the already existing attributes and style of the “<tr” parent tag.

It can also be used for html options or html lists.

Use Tomorrow Software’s inbuilt performance analysis to determine the performance bottlenecks of your rule sets and make the appropriate changes.

Rule sets that work together for a common purpose or have a common theme can be grouped together into a repository.

Repositories can selectively export their rule sets, content and data to be used in other repositories.

Below is an example of the rule set User_Agent_Detection.xml being exported. This means that only this rule set will be visible when the repository “User Agent Detection” will be included in another repository.