Introduction

Hello, World!

As with all new programming languages, the "Hello, World!" program generally is a computer program that outputs or displays the message "Hello, World!". Such a program is very simple in most programming languages and is often used to illustrate the basic syntax of a programming language. It is often the first program written by people learning to code.\

✨ Now step inside and follow these steps to complete your very first composition with Composable Agentic Platform.

Requirements

• A running local, or cloud hosted instance of X.

• Installed console version 10.0.0.21050 or later.

• Chrome or Firefox browsers are supported.

• Ports 80 and 443 are required to be available to run the console and Programmable Data Agent.

For the purposes of these instructions [your server name] = localhost

For example: http://[your server name]/console/ = http://localhost/console

You need access to a console login screen like this:

Say Hello [content file]

Click the link to open http://localhost/hello.html in a new browser tab:

You’ll see a simple html content file called hello.html has already been pre-deployed and is served up to the browser by the running Programmable Data Agent.

Go ahead and enter your name in the form and press the Say Hello button. The form submission responds with Hello.

Background Information

The Programmable Data Agent loads hello.html, prompting the user to enter a name and to click a button labelled Say Hello. When the button is clicked, the text entered should be appended to "Hello". For example, if the text entered is "World!" then the result will be "Hello World!"

Objective

The user experience needs improving because any text entered is currently ignored. Can you follow this guide to improve the user experience?

First up, let’s go and see where the hello.html file lives….

Login [console]

Login to the console using the default credentials. In your case if you are working on the localhost console, use the default credentials: http://localhost/console/

• User ID: admin

• Password: admin

Open Repositories

Once logged in, press Start followed by Repositories.

We typically call these “repos”. It’s the home, or workspace in the console of where your work lives.

Now Click on the Hello World repository folder (no need to expand the folder tree just now, as that’s where you can save and restore your repository backups – we’ll get to that soon enough!).

Now press View and then expand the Content Files folder.

Content files can be HTML, XML, images, or any other binary content that may be required to be served when requested.

Content files can also be dynamically modified by content rule sets, we’re not covering those in this example.Content files live within a content path that must map to the content path of the application. In our simple example, hello.html is served under localhost being the root directory, so therefore it resides in the top-level Content Files folder.

http://localhost/hello.html

As the Hello World configuration has already been deployed from the console to the target server Programmable Data Agent, this is why the page loads when requested.

Update Content Files

So, let’s inspect the html file. Click on hello.html, and a new portal window will open for the file. Click on the Update button as follows.

A new browser window opens to show a html editor for the hello.html content file. Note the input parameter name on the form is set to Name. We don’t need to make any changes to the html file so you can close this window.

So that’s a small introduction to Content Files. Next, let’s take a look at Rule Sets.

SendResponse [rule set]

With the Hello World repository open, expand the Rule Sets folder, then click the SendResponse rule set and press Update in the portal window that opens.

The rules editor is the graphical design tool for composing and maintaining rule sets. The rules editor is launched as a separate browser window from within the console application when you press Update.

Rules Editor – example for reference only

Go ahead and browse the vast catalogue of what we describe as “digital blocks” on the left-hand side. The catalogue is grouped into collections. To use any block in the catalogue, expand the group folder, then click and drag a block onto the main canvas as shown.

In this example, you can expand the Alert group folder and drag the Send Kapow SMS block onto the canvas.

Rules Properties – example for reference only

Now click to select the Send Kapow SMS block on the canvas, and the left-hand side catalogue will switch to the Properties tab.

Each block has properties you need to set when composing, along with adding a more meaningful description (like adding comments in code).

In this example you can set the properties as two variables called MESSAGE and MOBILE. The properties of this the block requires these in order to perform its intended function. These variables would need to contain the values of the SMS message, and the phone number to send the SMS message to.

Everything else is taken care of.

Each block has additional online help you can access by right-clicking over the selected block and pressing Help.

Give it a try.

Set Variable

So, let’s get back to our example. Click to select the first block called Set Variable and view its Properties.

Selected blocks banner colour turns grey.

The block does exactly what it says on the tin. It sets a new variable. In this example we’ve set the variable name to RESPONSE. With the value set to a snippet of html code. We enclose this snippet in quotes.

“<html><body><h1>Hello "+NAME+"</h1></body></html>”

Note how this value has been constructed in three parts.

“STRING”+VAR+”STRING”

You’ll remember from earlier, the form submission responds with “Hello”, that’s because the NAME value hasn’t been defined or “passed into” this rule so therefore it processes NAME as a blank value, so the value of RESPONSE would look like this on exit.

“<html><body><h1>Hello </h1></body></html>”

HTTP Response

Click to select the second block called HTTP Response and inspect the Properties. Selected blocks banner colour turns grey.

You can also COPY/ CUT / DELETE / PAST block(s) with a simple right click.

How easy is that?!

Guess what!?

This block also does exactly what it says on the tin. It responds to an http request with content of the response data that has been set in the property. In this case the variable RESPONSE is the html snippet value set in the preceding Set Variable block.

You’ll see this block also requires an HTTP Status code and Content Type set.

This rule performs the final response behavior by the Programmable Data Agent you’ve already experienced when you clicked the http://localhost/hello.html link and pressed the Say Hello button.

Rule Info

Click on the fourth tab called Rule Info for the SendResponse rule set.

The Export to Group and Short Description represent this rule set as a new block that can then be (re-)used in other compositions. We will use the Send Response rule that lives in the Hello World Grouped folder in the next steps.

Note it has the Parameter Type set to Input, Parameter Name set to NAME, and has been given a Label of Name.

We’ve finished looking at the SendResponse rule set now, so go ahead and close it by closing the Rules Editor window.

Do NOT save any changes if prompted to do so.

SayHello [rule set]

So, let’s create a new rule set that will pass the html form’s Name value into the response.

Create a new rule set

Click on the Rule Sets folder in the Hello World repository. In the portal window that opens, set the File Name to SayHello (case sensitive) and press the Create button.

Now open the newly created SayHello rule set for editing. Click on the SayHello rule set that has now appeared in the rule set folder of the Hello World repository and press Update just as you did to inspect the SendResponse rule set.

Search the catalogue

Go to the search tab and search for “Response” and drag the Send Response block onto the rules editor canvas.

Alternatively, you can find the same block in the catalogue from the first Grouped tab, located in the Hello World group folder. This is because the Rule Info tab of the SendReponse rule set has an export group defined as Hello World.

Either method is fine to search the catalogue and drag blocks onto the canvas.

Wire blocks together

Click on the Send Response block

yes, we’ve turned a rule set into a new block in the catalogue for re-use

and once again just set the properties. So, now set the Name property to Name (case sensitive, no quotes).

Remembering this was the input parameter set in the hello.html content file we looked at earlier.

Click and hold over the orange cog, then click-release over the green dot to “wire” the first block into the rule set in a right to left direction. Incidentally, all subsequent blocks are wired from the block exit chain point (right hand side) to the input of the next block (left hand side).

Press SAVE and close the rules editor window as shown.

That’s all you need for your new rule set.

HelloWorld [configuration]

The HelloWorld configuration defines the input into the Programmable Data Agent and the rule sets to run.

General tab

Expand the configurations folder and click the HelloWorld configuration. The General tab is the default view, and ensure you now select the SayHello rule set from the dropdown list of available rule sets. This is the “initialising” rule set that is processed by the Programmable Data Agent on the very first transaction it receives.

Embedded (dependent) rule sets that have been wired within the SayHello rule set are also deployed along with it’s parent, so you only need to set the top-level ruleset.

Therefore, any dependent rule sets will get deployed along with the configuration without having to define them.

You’ll note here that there are three other types of rule set that can be set to initialize and run when processing data. These are for (1) CONTENT, on (2) STARTUP, and on (3) COMPLETION. These are not required in this example.

Timers tab – information for reference only

Just to mention in passing, there is a fifth rule set you can set in the Timers tab of the configuration. These are rule sets that are initiated and run (as the name suggests) on a timed basis. For example, when a rule set is required to perform a defined process say, every 24 hours.

Input source tab

Click on the Input Source tab and inspect the different sources of data options available.

For this example, we are configuring the Programmable Data Agent to process web application data, but as you can see this is just one of a multitude of available options to define in the configuration, dependent on the composition and data sources being processed.

Databases tab – information for reference only

Click on the Databases tab. It’s here where you define the databases being made available to the Programmable Data Agent. You are not required to define a database for this example so there’s no need to configure a database.

Example only:

If you are interested, database connectivity specifying JDBC driver, connection string and schema credentials is an administrator set-up task in the console. You don’t need to complete that right now.

Deploy

With the new SayHello rule set defined as the rule set in the configuration, you can go ahead and press the Deploy button.

Select Programmable Data Agent as the target server and press the Deploy button.

Wait for the deployment to complete and the server restart in a few seconds, and you’ll see the Programmable Data Agent server details are shown.

Test

Click the link to open http://localhost/hello.html in a new browser tab and refresh the page.

Enter World! the press the Say Hello button, and if successful you’ll receive a Hello World! response.

[the crowd erupts into wild applause 👏🏻🍾]

Want some more?

Then read on….

Performance data and live probes

With the Hello, World! example now working successfully, let’s give you a glimpse under the hood of the Programmable Data Agent.

Go back to the console and click Get performance data in the Programmable Data Agent server portal window you have open.

On the next window click View Rules Performance

The rules editor window opens in a new window. Double click the Send Response block.

Place a probe on the Set Variable block. Right click over the green exit chain point and click New probe…

Click the Create button. Live probes are triggered by variables and values, and occurrences thereof. We can leave these blank to just trigger on the next transaction.

The exit chain point turns yellow to show the probe is set.

Now go to the browser tab of the demo page showing the SayHello output and click the back button so that the input hello.html page shows.

Input a new name Probe into the input field and click Say Hello, the page responds as expected with Hello Probe. Go back to the rules editor window with the probe set and you’ll see the exit chain point has turned red to show the probe has been triggered.

Right click on the red exit chain point and click View probe.

You can now see the transaction data that has just been processed by the Programmable Data Agent. The contents of the two variables NAME and RESPONSE.

[NAME]=[Probe]
[RESPONSE]=[<html><body><h1>Hello Probe</h1></body></html>]

Aside from helping you view live data to assist with composing or troubleshooting your solution, it also provides a superior debugging tool that can even be used on production servers without the need for logging.

Frame busting refers to the ability of an application to avoid being encapsulated within an IFRAME. The later approach can be used to not only make one site impersonate the capabilities of another, but more sinisterly, it can be used to overlay a different user experience on top of an IFRAMEd site and allow events to flow through to the IFRAME.

Using this approach, a user can inadvertently be tricked into performing actions within an application without even knowing that they are interacting with it.

A July 2010 study by Gustav Rydstedt, Elie Bursztein and Dan Boneh of Stanford University and Collin Jackson of Carnegie Mellon University named: "Busting Frame Busting: A Study of Clickjacking Vulnerabilities on Popular Sites", explores the risks and problems associated with framing. It can be found here:

http://seclab.stanford.edu/websec/framebusting/

The study mentioned above forms the basis of the following case study.

Frame busting defense

The defenses we will introduce in this case study are rather simple; we will add some JavaScript and a few extra HTTP headers to the logon page of the Qwerty app. Depending upon the application, it may also be relevant to add this code to other pages, but for now we will just select the logon page for simplicity.

The JavaScript we will add looks as follows:

<style>
html { visibility : hidden;}
</style>

<script>
if (self == top) {
document.documentElement.style.visibility='visible';
} else {
top.location=self.location;
}
</script>

The above script has been placed in the public domain by the authors of the study.

In simple terms, it sets the entire page invisible through use of a CSS directive and only makes it visible if the page itself is the top frame and JavaScript is enabled.

In addition to the above code, we will add a couple of HTTP Headers that take advantage of built in frame busting defenses in certain browsers. The headers to set are as follows:

X-FRAME-OPTIONS: SAMEORIGIN
X-Content-Security-Policy: allow *; frame-ancestors 'self'

Planning the rules

The rules required for this case study are extremely simple. Our plan is to:

1. Determine whether we are on the logon page.

2. If yes, add the frame busting code.

Getting started

The very first step as always is to create a repository. In this case we will name it "Frame Busting Example".

Once done, copy and paste the JavaScript code into a text file named "framebust.js" and upload it to the data folder in the repository.

Then create a new blank rule set named "FrameBust".

Creating the rules

The first rules we need simply determine if we are on the logon page:

These rules are the same as in most of our other examples, so we will just list the properties here for quick reference:

Once the properties are set, simply add a chainpoint to the Switch rule and name it "logon.jsp".

We next add the rules to inject the JavaScript and headers:

We read the frambust.js file into a variable, we then set a couple of variables to the header values we need, and finally we add the JavaScript and headers to our response. The properties look as follows:

Values are: SAMEORIGIN,allow *; frame-ancestors 'self'

Header field names are: X-FRAME-OPTIONS,X-Content-Security-Policy

That is it, save the rule set and create a configuration to test it.

Creating the configuration

The configuration for this rule set is very simple, we create one named "FrameBustTest". The following shows the relevant sections that need to be defined:

Testing

Qwerty is a suitable test application for this case study because it uses frames to encapsulate the logon and other internal pages.

When navigating to Qwerty landing page URL in the browser you will see is as follows:

http://localhost/qwerty/

To test the new rule set, deploy the configuration to the Qwerty demo server and start it. Then refresh the Qwerty logon page.

Whilst you will not see any visual differences in the appearance of the Qwerty application, the Qwerty landing page URL in the browser will now look like this:

http://localhost/qwerty/logon.jsp

We can proceed to navigate to other pages in the Qwerty application outside of the main Qwerty frame.

For example, these pages would normally all be loaded from within the Qwerty frame, but are now visible in the main browser address bar:

• http://localhost/qwerty/main.jsp

• http://localhost/qwerty/setup.jsp

• http://localhost/qwerty/pay.jsp

We have successfully "Busted" out of the frame.

Introduction

This manual describes how to install browser certificates for testing access and modifications to sites that are protected by HTTP Strict Transport Security (HSTS). It is assumed that the reader is familiar with the basic steps of deploying configurations within Composable Agentic Platform and knows how to view the console output associated with the Composable Agentic Platform proxy server.

When using the Composable Agentic Platform browser proxy for accessing secure web sites over HTTPS, you will encounter certificate warning in the browser, just like the following:

These warning are relatively easy to get around by clicking on the Advanced button and adding an exception.

However, with the advent of HTTP Strict Transport Security (HSTS) this has now become impossible to do as the browser will refuse to add the exception:

The following guide provides instructions on how to overcome this problem by installing a trusted certificate authority into your browser that Composable Agentic Platform in turn will use to generate valid replacement certificates for each SSL site on the fly.

Getting started

Before you begin you should make some updates to your Composable Agentic Platform installation.

Required Updates

The first step is to update/install the following components via the update server:

• Composable Agentic Platform console (10.0.0:21050 or later)

• Base Rules (2021-07-16 or later)

• BIP Runtime (2018-08-07 or later)

• HTTP Rules (2021-07-15 or later)

Locating the certificate

After the BIP Runtime extension has been installed, locate the folder named ‘Certificates’ under the Composable Agentic Platform Server installation:

Our certificate is found in that folder with the name: root.pem

Installing the certificate in Firefox

To install the certificate authority in Firefox, start by selecting Options from the main menu:

The select the Privacy & Security section and click View Certificates:

In the certificate manger, select the Authorities tab:

Click on Import… then open the**root.pem** file from the location described earlier (the Certificates folder).

You will be given the option to select the level of trust for the certificate. Select “Trust this CA to identify websites” and click on OK:

Click on OK again to close the certificate manager.

Routing Firefox through the Composable Agentic Platform browser proxy

To be able to see traffic flowing between Firefox and your target site, you must configure Firefox to use the proxy. Under the Options Advanced settings, select the Network tab and click on Settings.

Configure the proxy as shown and click on OK:

You can now close the Settings tab in Firefox.

The certificate is now installed, and you are ready to see traffic.

Installing the certificate in Chrome/Edge for Windows

Please note that by using the Chrome installation method, other browsers (such as the Microsoft Edge browser will be affected as well).

We will therefore only show the Chrome approach.

Important: To install the certificate, the user MUST have administrative privileges on the system.

In the Chrome browser, select Settings:

Scroll down the page that appears and click on Privacy and Security

Locate the HTTPS/SSL section and click Manage certificates…

In the dialog box that appears, navigate to the Trusted Root Certification Authorities tab and click on Import.

This takes you to the certificate import wizard:

Click on Next

Important: PEM files are not available as a default filter. To locate the file, select All Files (*.*):

Locate and select the root.pem file, then click on Open

The file name now appears in the Certificate Import Wizard and you can click on Next.

Select the certificate store as shown and click on Next:

You will be presented with a review page. Click on Finish.

A security warning appears. Make sure you click on Yes:

The certificate will be imported:

Close the certificates list:

Routing Chrome/Edge through the Composable Agentic Platform browser proxy

Please note that by using the Chrome installation method, other browsers (such as the Microsoft Edge browser will be affected as well). We will therefore only show the Chrome approach.

Within the Chrome advanced settings, locate Network and click on Change proxy settings…

In the internet properties that appears, click on LAN settings:

Set the proxy server as shown and click on OK:

Then click OK again to close the internet properties and close the Settings tab in Chrome. The certificate is now installed and you are ready to see traffic.

Installing the certificate into the OSX Key Chain for Safari and Chrome

Please note that both Safari and Chrome use the same certificate store so this installation applies to both.

To install the certificate, navigate to the Certificates folder and double-click on the root.pem file. The Keychain Access utility will launch and requires you to enter your Admin User credentials:

Enter your password and click on Modify Keychain

This will launch the Keychain Access utility with the certificate imported into the System keychain:

Double-Click on the TomorrowX CA certificate to bring up the details:

Expand the Trust option and set the drop-down ‘When using this certificate’ to Always Trust:

Close the pop-up details window and enter your administrator password to update. The entry will now have a blue circle with a white cross to indicate a trusted certificate and will have the following text: “This certificate is marked as trusted for all users”:

Testing the certificate installation

Now that your certificate is installed, switch to the Composable Agentic Platform console, select the Product Trial repository and deploy the BasicWebLister configuration to the proxy server.

Wait for the proxy server to start.

You are now ready to test if you can bypass HTTP Strict Transport Security (HSTS) protection. In your browser go to https://www.google.com

Google should load as normal:

And you should see traffic in the proxy console:

Before explaining how to combat CSRF (Cross Site Request Forgery), a quick explanation of the technique behind it is in order.

A cross site request forgery relies on a user visiting a malicious site, shortly after they have logged into a genuine site, and whilst they still have a session cookie active with the genuine site.

By making the user's browser send malicious requests directly back to the genuine site, the malicious site can exploit the fact that the user is already logged in, to effectuate such things as placing orders in the user's name, sending emails using the user's credentials or posting comments to other users in what may well be a trusted user's name. The list of exploits is endless and only really subject to the vulnerabilities of the site being attacked.

Ways to make the user visit the malicious site whilst still being logged into the genuine site includes phishing, posting of links in comments on the genuine site, or even just "trial and error" by posting links on sites that may also be frequented by users of the genuine site.

The limitation of the CSRF attack is that it is always "blind". The attacker cannot see what the application responds with, or what the current state of the session is; due to restrictions imposed by browser security models that say that a request from one server (domain) cannot be sent to another.

CSRF defense techniques

How to best protect your site against CSRF attacks depends on how it was written. Generally speaking, most applications perform actions as a result of an HTML form being posted to the site. Some sites also respond with actions to a GET request

For example: "http://www.mysite.com/delete.jsp?orderToDelete=12345"

This example will focus on protecting applications that use a form POST. This is done by adding a hidden field to every form presented by the application. This hidden field contains a random value that is unique to the specific session of the user. We will require that this field is always present on a form POST, making it virtually impossible for a malicious site to second guess what a valid POST request might look like.

The technique for protecting a site that uses GET requests is similar, simply requiring the addition of an additional URL parameter to every URL that takes parameters, instead of a hidden form field.

Planning the rules

The first step in implementing our CSRF defense is to create a simple plan of action i.e. what do we intend to do, and how do we wish to go about doing it. It is a good idea to write this down in plain English and then use that text as a guide whilst designing the rule structure. In this case, the plan reads as follows:

1. If a POST request comes in whilst there is an active session, then make sure it has our hidden field, and that it is the hidden field we have generated for that session. If the field is not present, we should respond to the user with an HTTP Status code of 403 (Forbidden).

2. Whenever a new page is provided by the application, make sure we add a large random number as the hidden field to every form presented by the application. The large random number we use should be generated once for the session and then be stored in it for easy reference and good performance.

That sounds easy enough; so, let's begin...

Getting started

Create a new repository named "CSRF Example" and add a new rule set named "CSRF".

Filter out static content before it hits the core rules using a Name Splitter and Switch rule as shown:

• The Name Splitter conveniently extracts the extension of the object being requested using the following properties:

• The Switch rule operates on the EXT variable. By adding new chain points for each type of static content they are eliminated from reaching the rule set.

As we are dealing with Web Applications, and we need to know information such as the method used (POST/GET), the first step is to add an HTTP Request Tracker rule from the HTTP group in the rules catalog to the CSRF rule set:

A good technique for rule writing is to start by determining the "flow" of events or pages that will subsequently have rules applied to them.

In our case we have two flows:

• The verification of the forms

• The addition of the form fields.

So, our next action is to add a Sequencer rule from the Flow group in the rules catalog:

Implementing step 1

Now, the first step in our written plan is to check if we are dealing with a POST request in the session, and if the form posted has our hidden field. The first part is very easy:

Only the If Condition requires some properties:

The next step is simple. We need to look up the current hidden field from the session:

Once again, there are not many properties:

The variable names and values we have chosen are arbitrarily selected, although they should be meaningful and memorable.

In this example, we have decided that the hidden field is stored with a session key named "CSRF.key" and that the hidden field on all forms is named "CSRF". We could have chosen any names as long as we use them consistently when we add the field to the form and store the session key.

All that is left for the first step is to make sure that if the key doesn't match, then the user receives a 403 error.

Once again, the properties are very simple:

We use a Set Completed rule after the response, as once we have decided that the user should be rejected, there is no need to proceed with the rest of the rule set. Instead we simply terminate the flow.

Implementing step 2

We are now ready to implement the second part of the plan. The first step in doing so is getting the actual response from the server so that we can add the hidden field if we need to.

The HTTP Server Execute rule takes care of this, even if you are writing rules using a built in forwarding proxy.

Once again, the properties are very simple as we are just interested in the application response:

Once again, we need to check if a session is present, but after the HTTP Server Execute rule, as that rule may in fact result in a session being created:

If there is a session, then we need to add our unique CSRF key to it. The first step in doing that is to see if we already have that key:

Once again, not many properties:

If we don’t have it, we need to create it, which is easy:

The properties for these rules are as follows:

The session key we use is the same "CSRF.key" that we used in step 1.

All that remains now is to add the field to the form and send the response back to the user.

Thankfully there is a dedicated rule that handles the first problem, the "Insert Hidden Field" rule.

Note that we are handling various loose ends too: connecting a Session not found to the HTTP Response, and connecting the existing session key to the Insert Hidden Field rule.

The final properties that must be set are as follows:

Testing

Our rule set is now complete, and we are ready to test it. A good sample application for this test is the Qwerty application. Create a configuration for the test named "CSRFTest" and set it as follows:

(Only relevant sections shown)

Once you have set up your configuration, deploy it to the Qwerty demo server and try testing it.

You will see in the Qwerty application, in the "Set up 3rd Party Accounts" page, that there is now a CSRF hidden field added to the page:

Use the performance data to further verify that everything is working as you expected.

Adding more protection

If you look further through the page source of the Qwerty application, you may also notice the following link:

This is a classic case of a GET request that can be exploited using CSRF. In this basic case study, we only protect POST requests of forms. However, if your application also uses actions on GET request, you can fairly easily amend the rule set to also cover GET requests.

This involves manipulating any URL parameters in the pages that are used for actions.

You can do this using the String Replacer rule, especially if your application uses ".jsp" or ".do" or ".aspx" as URL identifiers for active content.

For example, you could replace ".jsp?" in every page with ".jsp?CSRF=0123456789&" and then check for the field on every URL that ends in ".jsp" and has PARAMETER_NAMES (from HTTP Request Tracker Rule) not equal to blank. If you do that you will achieve the same result as the Insert Hidden Field rule does in this case study.

Additional CSRF notes

The above example is based on implementing the CSRF problem as a single rule set.

Introduction

Welcome to the Tomorrow Software reference for interacting with the PiFace Digital 2 I/O board for Raspberry Pi. In this guide we will provide instructions on how to set up a Raspberry Pi and PiFace combo to accept button input and control a few LEDs and relays.

Licensing

The licensing of the PiFace Extension is the same as most other extensions that we provide. You simply need a valid Tomorrow Software license.

The PiFace Extension uses the Pi4J open source (LGPL V3 license) library. This is a free unencumbered license for private and commercial use.

Prerequisite

It is assumed in this document that you have prior experience with Tomorrow Software and that concepts such as server definitions and rule writing are familiar to you.

Getting started

The very first thing you need to get started is some hardware. The following photo shows the most essential components:

What you need is as follows:

• HDMI cable plus a TV/monitor with HDMI input (not shown)

• Micro-USB power supply (Preferably 2A)

• Raspberry Pi 2 board

• Case designed for the Raspberry Pi and PiFace together (optional)

• Multi-meter (Optional but really handy)

• USB Wi-Fi dongle

• Raspberry Pi Noobs SD Card

• PiFace Digital 2 board

• Standard USB mouse

• Standard USB keyboard

Hardware Assembly

The assembly of the hardware is incredibly simple:

• Mount the PiFace on top of the Raspberry Pi board

• Insert the Wi-Fi dongle, keyboard and mouse into the USB slots

• Remove the micro-SD card from inside the Noobs SD pocket and insert it into the bracket on the underside of the Raspberry Pi

• Connect the HDMI cable from your Raspberry Pi to your monitor

• Connect the power supply and wait for it to boot up

Initial configuration

Once the operating system has booted, you will see the following image:

Using your cursor keys, space bar to select and Tab key to navigate options, set up your time zone, locale and select the option to boot to desktop.

Enabling SPI

The PiFace board communicates with the Raspberry Pi over an interface known as SPI. This interface is not enabled by default, so we need to do so. From within the configuration tool, select Advanced Options and SPI.

Enable SPI and load by default. Once done, return to the main menu, hit the Esc key and type:

This will force a reboot and after a startup you now end up in LXDE:

From here, we need to configure our Wi-Fi connection. Click on Preferences then Wi-Fi Configuration.

Next click on Scan. After a short while, your Wi-Fi network should appear and you can double-click on it to provide a password. Once done, simply click on Add and your internet connection will be established.

Wait for the IP address to show up and note it down for later.

Updating and upgrading

Because our project requires the latest drivers and software, the next step is to update the operating system.

Open a terminal window and type the following commands:

These two commands will take quite a while to complete, depending on your internet speed. Please ensure both tasks complete without errors before continuing.

Installing Pi4J

The Tomorrow Software PiFace extension relies on an open source project known as Pi4J. We need to install this next. At the command line, type:

Optional USB drive support

Next, we need to get the Tomorrow Software installed. There are two options:

• Downloaded from the web

• Install using a USB thumb drive

If you have received the software on a USB thumb drive, you need to perform some additional configuration. If you downloaded the image, please skip to the next section.

In the terminal window, create a folder where the USB drive will be mounted:

Next, we need to edit the file system table:

Add the following line to the end of the file:

IMPORTANT: This has to be ONE line in the file

Press Ctrl-X and a capital Y, followed by Enter to save.

Then reboot:

Once the reboot has completed, insert the thumb drive and make sure you can access it.

Allow root access

Tomorrow Software is required to be installed as the user root as it uses ports such as 80 (http) and 443 (https).

To achieve this, you need to be able to switch to root using the su command.

To enable root access, type the following command:

Pick a good password and enter it twice.

Starting the file manager

We are now ready to start the file manager in root mode to copy the image into place.

At the command prompt, type:

Enter the password you just set up, then type:

This will start the file manager as root.

Locate the “Tomorrow-Software-Server-10.0.0.zip” image you either downloaded or on your thumb drive, then right click and select Copy.

Change the folder to /opt and create a new folder named “local”.

Copy the zip file to this location, right click it and select “Extract Here”.

In the terminal window (as root), create a symbolic link to the distribution as follows:

Setting the software to auto-start

Right click the file tomorrow.sh in /opt/local/Tomorrow/server/bin, select Properties, then the Permissions tab and make sure Execute is set to “Only owner and group”.

Copy the file tomorrowstart from /opt/local/ Tomorrow /server/bin to /etc/init.d.

Right click the file, select Properties, then the Permissions tab and once again make sure Execute is set to “Only owner and group”.

Then enter the following commands in a terminal window (logged in as root).

Starting the instance

Everything is now ready for the first run of the Tomorrow Software engine. Reboot your Raspberry Pi. You can either do this from the menu or by typing:

Once rebooted, wait for CPU to settle down after startup – it can take quite a while (2-3 minutes on a PI 2). Do NOT attempt to log in during this phase.

Defining the console type

Logging in to the instance should happen from some other computer. The best way to do this is to modify the hosts file on the computer in question to give it a valid name. For example: homeauto.local

Then, simply open a browser and point it to the following URL:

Log in using the user admin and the password admin. You will access the main console. Select Administration then Console Setup:

Change the console type to “Forwarding Proxy without console” and click on Save.

This will shut down Tomorrow Software on the Raspberry Pi. Give it a minute or two to complete, then return to the Raspberry Pi and reboot it.

Setting up the server definition

At this point there will no longer be a console running on the Raspberry Pi. It is instead required to be managed from another Tomorrow Software console instance. To enable this, we need to log in to that alternate console instance and set up a new server definition:

As well as the basics above, we also need to set up the protected hosts, remove the client IP restrictions and disable the browser proxy:

Make the required changes and click on Save.

If all your settings are correct, your instance will now show green in the Servers section:

Required Updates

The next step is to update/install the following components via the update server:

PiFace Rules

Testing the setup

It is now time to test all the setup work. We will start by turning on LEDs on demand.

Switching LED rule set

From within the Tomorrow Software console, create a new repository named “LED Test”, then create a new rule set named “LEDSwitch” in that repository.

Hit update on the rule set and create the following:

Properties are:

Click on the Save button to save the new rule set.

Test configuration

Return to the console to create a new configuration in the LED Test repository:

Click on Create to create the configuration.

Deployment and Testing

It is now time to deploy the configuration to the PiFace Server. Deploy the configuration selecting the “Restart immediately” option.

Wait for the deployment to complete. This can take several minutes, especially the first time. Once the deployment is complete, return to a browser and enter the following URL:

Provided you have followed every step above, LED 4 on the PiFace board will now turn on. You can turn it off using:

Responding to button presses

When a button is pressed or released, this needs to trigger an event. For this purpose, there is a rule named “PiFace Button Listener”, which applies to each button.

You place these rules in a startup rule set.

The following shows a startup rule set that will turn LED 1 on when button 1 is pressed and turn it off when button 2 is pressed:

We also need to modify the configuration to accept the startup rule:

Deploy the configuration the the PiFace server and once again enter the following URL in a browser:

This will trigger the Programmable Data Agent startup and activate the button listeners. Now try to press button 1 on the PiFace. LED 1 will turn on. If you press button 2, LED 1 will turn off.

Notice that LED 1 is linked to a relay. You can hear it click when the LED turns on or off.

Push notifications is rapidly emerging as one of the most efficient ways of sending information to users without going through email, SMS or other channels (such as Messenger or Slack).

Push notifications have a very high click-through rate and is supported by all modern browsers and platforms except Apple’s.

The push notification framework provides a simple way to add push notifications to your application with the ability to fall back to alternatives if the user is on an unsupported platform.

A push notification appears as a message in the user’s notification section. For example, in Windows a message could look like this:

It consists of an Icon, A headline and a text body (where supported).

If the user clicks on the message, an event is generated that will open a web page specific to the message and will also send a notification back to the server that the user clicked the message.

There are some restrictions to using push messages:

1. The web site sending the message MUST be using a secure protocol (https), even during development

2. The user must be on a supported platform

3. A set of cryptographic keys must be created to sign messages

The push notification framework helps you manage the last 2 of those 3 items above. To install certificates within your application, please refer to the product reference.

Please note: This manual will reference the Push Notification Demo repository, which can be obtained from the update server.

Getting started

The push notification framework consists of 3 rules and a precisely structure HTML page. In the following section we will cover these rules in detail.

Initialize Push Notifications

This rule does two things:

1. It either obtains, reads, or creates credential keys to use with the notifications

2. It initializes a data set used to store notification user information

Server Keys

The condition for creating keys is that no keys are present in the credentials vault or in the file system, so they must be created. This is done directly on the target server as two new files the first time the rule is executed:

You can choose to simply leave these files on the server (in which case you should also place them in the Data Files section of the repository you are working with and ensure they are deployed using the Register Data Files rule).

The preferred way however is to store the keys in the credential vault. This is a simple exercise of opening the key files with a text editor and copying the text from them to the appropriate keys in the vault:

Once the keys are in the vault, the files can be removed from the target server.

Subscriber Data Set

The data set created by the rule is named “WebPushSubscribers” and is entirely managed by the framework. You can however query and work with the data set in rules as well if you wish. To do so, you will need to know the field names which are: subscriber, target, endpoint and group.

• Subscriber refers to the user id within your application for a logged in user

• Target is the type of communication. For example: Push, Email, SMS etc

• Endpoint is the key to sending, it can be a Push key, email address, phone number (or whatever else is a valid definition of where the message should end up depending on the target)

• Group is the target group. It can be the same as the subscriber (for direct communication) or it can be a subscribed group (such as offers, recalls, alerts etc).

The Push Notification Controller

The Push Notification Controller rule manages everything related to interacting with the browser to ensure push notifications can be subscribed to and delivered. It automatically generates correct and tested JavaScript pages and a default icon for the rest of the framework to use.

Even though the controller manages all these interactions, you always have the option of doing your own additional processing (For example when a user subscribes or unsubscribes or performs a click through on a notification).

The controller only needs a few properties:

• The Database is the database where subscriber information should be store.

• The Subscriber is the user ID of the user involved in the interaction. Note that generally speaking it is best to have a user logged in so that you can target specific users, rather than just a generic group of people.

• The Default URL to open is a fallback mechanism for browsers that do not yet support a target URL to open for each message. In that case, clicking on the notification should send them to a sensible page (such as a login page).

• The Is default URL also welcome page is important only to ensure that if the user already keyed in the welcome URL and already has that open (without a page, such as https://example.com/ and not https://example.com/index.html) the browser should not open index.html but rather just focus the original welcome page).

Wiring it up

The Push Notification Controller is designed to be the last rule in our normal application flows. In the sample repository that looks like this:

It is important to note that the sample repository is cut down to an absolute minimum for maximum clarity. Your production repository should follow the guidelines set out in the Best Practices manual.

The demonstration repository entry point

To help you experience push notifications we have created a simple entry page called index.html. It presents as follows:

Returning to this page logs out any user. To log in as one of the two users just click the relevant button.

No passwords required.

Create a subscription page

To go along with the Push Notification Controller, you will need a subscription page served up as content. There is a very minimum sample page in the Push Notification Demo repository named subscribe.html. It presents as follows (after checking that notifications are possible):

Should your browser NOT support push notifications, you will receive the following page instead:

And finally if you are trying with something like Internet Explorer you will receive this message:

All of the above sections are simply DIVs in the sample HTML file:

The important thing to understand is that the various IDs of each DIV must remain in place.

You can change the DIVs to <section> or <span> tags (or whatever you like), but the IDs must be present so the Push Notification Controller rule can take charge of the page in the background.

Mandatory IDs

There are several critical IDs that must remain in place. They are as follows:

Radio and Checkbox Groups

In addition to the IDs, there are 2 named radio button groups:

and:

Notice the slight difference in the name that separates the two groups. It’s a common mistake to copy from one group to the other and forget to correct the name.

Alongside each radio button that is NOT a Push notification, you will need to specify a hidden value for each:

This provides the framework with information on how to define the destination of the non-Push notifications.

The next section is the checkboxes to enable additional groups the user can subscribe to.

You can have an unlimited number of these groups. Each selection by the user will automatically subscribe them to that group and notifications can be sent to all subscribers.

Buttons

The framework requires two buttons on the page:

Both these buttons should be disabled in the HTML by default. The framework will enable the right button at the right time.

Connecting to the framework

The final step is to connect the HTML to the framework. This is done by importing a javascript file that is dynamically generated by the framework. You do not need to have this file anywhere in your repository, it is fully generated along with all dependencies.

And with this, you now have a fully functioning push notification page, so it is time to look at how to send them.

Sending Push Notifications

Sending push notifications involves either sending an individual message or sending notifications to an entire group of people. In the demonstration repository there is a sample sending page name send.html:

This page enables you to send individual push notifications to the two users or you can send a recall notification to all users that has subscribed to recalls.

The page shown after the message is the page that will be opened when the user clicks the notification.

The Send Push Notification rule

All notifications (regardless of the method of sending) can be managed with the Send Push Notification rule:

There are several options to define how the push notification looks and acts:

• The Database relates to the location where subscriber data is stored.

• The Audience should be either the internal user ID that the application can use to identify a user or a notification group name.

• The Sender Email should be the email of someone who can assist with technical queries from the external push notification servers used to send the notifications. Those servers are managed by organizations such as Google and Microsoft and the email is used for relaying complaints or warnings.

• The Expiry is provided in minutes with a maximum of 24 hours allowed.

• The Title is the key short description of the notification

• The Icon is an icon to show to the user when the notification is displayed. If no icon is provided a default will be displayed.

• The URL to open is the URL that will open when the user clicks on the notification. Not all browsers support this and should they not, the default URL to open from the Push Notification Controller will be used instead.

• The Message allows for a longer notification message to be displayed. Not all browsers support this.

• The Tag is a value that can be used to avoid sending the same notification to the user over and over. Messages with the same tag name will only be available once in the user’s notification system. The following Re-notify is related to this. It determines if the user should get another notification as a result of an unopened tag group or not.

• Vibrate can be used to control the vibrations of the user’s device. It is specified as a series of on/off pairs in milliseconds. For example: “100,200,100,200” would mean vibrate for 100ms, pause for 200ms, vibrate for 100ms, pause for 200ms.

Message personalization

This rule notably includes the ability to personalize the message being sent and permits the sending through alternative channels.

For every message, the following variables are available: NOTIFICATION_TARGET, NOTIFICATION_USER, NOTIFICATION_ENDPOINT, NOTIFICATION_MESSAGE, NOTIFICATION_URL and NOTIFICATION_TITLE

The rule writer can use the first 3 to determine where to send a message and identify the relevant user being notified – and can use the last 3 to customize the message.

In our demonstration repository we do this by inserting the user name into the message for group messages:

The Personalize title rule has the following properties:

This is based on the title being sent to the recall group looking like this:

So for each message being sent, the Personalization chain point will insert the actual user name into the title.

Alternative notification methods

If the user that signed up for notifications did not have a supported browser, we can offer alternatives (such as email, SMS or other targets).

To support the sender managing those alternative channels for us, the Alternative chain point is called whenever a target is different to “Push”. In our demonstration repository we showcase this with a simple output to the console:

However, the rule writer has access to all the 6 variables listed previously at this point in the flow and can use it to send the notification to the right target using the rules most relevant for that:

Google Analytics lets you do more than measure sales and conversions. It also gives insights into how visitors find and use your site, and how to keep them coming back.

This case study demonstrates Tomorrow Software as an easy integration option for adding tracking code to web pages typically done so outside of the normal software development life cycle (SDLC). Not only does this provide an easy, and rapid deployment of such third-party services, but also ensures that as and when new pages are introduced it provides comfort that tracking code will be ‘appended’ to each and every page the web application responds with back to the user’s browser.

This example is a common method whereby you can simply read a JavaScript file containing the required tracking code, insert your account ID and append it to any web page.

For information regarding the Google Analytics service please refer to:

https://www.google.com/analytics/web/

Planning the rules

The first step of any rule writing is to determine what we want to do and how it can be accomplished.

Before you begin you will need to ensure that you have a valid Google Account email address and password for using the service, or alternatively sign up, it only takes a couple of minutes. https://accounts.google.com

We will discuss tracking code throughout this case study, which is only accessible once you have logged in to Google Analytics.

To access your tracking code:

• Log in to Google Analytics https://www.google.com/analytics/web/.

• From the Admin page, select the .js Tracking Info property from within the list of accounts. Please note that tracking code is profile-specific.

• The tracking code can be copied and pasted from the Website Tracking text box from the Tracking Code menu item.

The code will be similar to the below (where x replaces your specific account code 'UA-xxxxxxx-x' ):

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-xxxxxxx-x', 'auto');
ga('send', 'pageview');
</script>

• Replace the code with 'UA-xxxxxxx-x' as we can set the account ID in Tomorrow Software rules later, which makes managing the rules and different Google Analytics accounts much easier.

• Copy and paste the above JavaScript code into a file named "google.js" and save somewhere local i.e. your desktop, for use later on in the exercise.

It is this tracking code that performs the task of collecting the browser data of visitors.

Getting started

Start by creating a new repository called “Google Analytics Example”.

It’s recommended that the process involved in adding the Google Tracking code be split into two:

• setting a variable which holds the unique Google User account 'UA-1234567-1’.

• and then inserting this value into the tracking code itself.

This means that you can subsequently update the account or the code separately in future deployments, or when Google amend their tracking code.

Keeping this in mind, you should create the following blank rule sets:

• GoogleAnalytics: this rule set will be responsible for creating the new UA variable plus reading the tracking code and adding it to the page.

• Qwerty_test: this rule set will allow you to test how a deployment can work in the demonstration Qwerty example application.

The two new blank Rules will be visible now within the repository.

Uploading the Google Tracking Code

In the Tomorrow Software console select the Data Files folder, then upload the ‘google.js’ file you created above and saved to your desktop.

Ensure you upload to the newly created “Google Analytics Example” repository that will now be available in the drop-down list of available folders.

Press upload and the file will now be visible in the repository in data files for the rules to use.

GoogleAnalytics Rule Set

Using a Set Variable rule set a new variable called Google_UA with the value “UA-1234567-1” where 1234567-1 is replaced with your specific Google Analytics user account.

Then using the File Reader read the google.js file and give it a variable name called ‘GOOGLE_ADD’

Next use a String Replacer rule to insert the newly created Google_UA variable into the tracking code .js file, followed by the HTTP Response Addition rule, to append the Google Tracking code to the response.

The string replacer rule will basically look through the code (which is now called ‘GOOGLE_ADD’) and replace any found content with the value of the variable we have defined ‘Google_UA’.

The HTTP Response Addition rule will now take effect and provide the amended google.js file as an addition to the page response and will activate this in the user’s browser.

The final step for this rule set is to add a couple of Exit rules called “OK” and “Fail” which will assist in rules performance to tell you if the rule is working, and to help with embedding this as a rule set within another rule set.

Qwerty_test Rule Set

This rule set will allow you to see an example deployment to the Qwerty demo application.

Of course, with every response from the application there is static content which you don’t wish to add Google tracking code to, so take a couple of simple steps to filter off transactions which don’t require code appending.

For example, a jpg image may be served up on a page each and every time a user navigates to this page so adding code to this page will not provide any additional customer insight.

Using the Name Splitter rule to identify the URI extension is a useful way to filter out unwanted data before reading the Google Analytics rule set.

• Variable Name: URI

• Last Name Variable: we are only interested in the last part of the URI so we name this variable EXT.

• Split Pattern: “.” is the identifier of the URI which tells the rule which part of the value we want to use or split.

Using the Switch rule set the Switch Variable properties to EXT as created above and proceed to ‘Add Chain Points’ for the static content you wish to ignore such as gif, css, html, js, jpg.

The final step is to connect the newly created GoogleAnalytics.xml rule set now located in the Rule Sets folder.

Setting up the configuration file

Finally, you can set up the configuration file. Click the Configurations menu, select the “Google Analytics Example” repository from the drop-down list, and enter some basic information about the rule to load.

The following screen shots show the information required for the “General”, and “Input Source” tabs.

You can now click the “Create” button to create your configuration file. Once created, click the “Deploy” button to deploy it to your Qwerty demo server.

Future considerations

The above case study shows how to implement Google Analytics tracking code in a specific environment, though of course each individual application will be different.

Validate the code is working

You will be able to log into your Google Analytics and select real-time traffic reports within the reporting dashboard, to validate the tracking code has been inserted, and is working correctly on your website.

You can also right click the page in the browser to view source code to verify the Google tracking code has been correctly inserted into the target application page.

Introduction

Developing Web Applications using the Composable Agentic Platform Framework often requires collaboration between server-side rule writers and client-side web page designers.

The Composable Agentic Platform Framework provides a methodology to make this collaboration as easy and seamless as possible.

This guide provides best practices examples of the various workflows that go into the development of a new application and the maintenance of an existing one.

Starting a new Web Application

As a best practice, web applications should be designed from the perspective of function. This means rule writers must have basic HTML and JavaScript skills, but are not required to understand the intricacies of making a web page responsive and attractive once functionality is achieved.

Modern web applications rely heavily on AJAX, functional JavaScript, JavaScript and JQuery libraries and other tools that define functionality, but not necessarily look and feel (which is typically achieved using CSS).

So, a web application should be started by the rule writers and contain the bare minimum of design elements to be functional. After that the role of the web page designers will be to make those pages shiny and friendly.

Throughout this manual we are going to work through a very simple example to illustrate the steps involved. Each section will have either [Rules], [Admin] and/or [Web] in their headlines to denote which role the section applies to. This allows you to quickly skip sections that may not be relevant to your job.

Setting up the tutorial repository [Admin]

Before you can start on this example, please install the “Web Application Tutorial” repository from the update server and create roles and users for the rule writers and web designers. Then deploy the repository to a proxy server for the users to access.

The web designer role should have:

• Server Permissions: VIEW, STOP, START and DEPLOY CONTENT for the Proxy Server

• Repository Permissions: VIEW, VIEW CONTENT, EDIT CONTENT and DEPLOY CONTENT for the Web Application Tutorial repository.

Tutorial Application Functionality [Rules][Web]

The tutorial application is a simple data maintenance app. You can add and delete quotes from your favorite authors. The landing page ([server]/index.html) looks like this:

To create a new quote, enter an author and click on Create:

The new quote is now stored:

And you can add a few:

In turn, to remove a quote, just click on the adjacent Delete button.

So, we now have a fully functional (albeit very ugly) web application.

Tutorial Application Artifacts [Rules]

The repository installed contains a configuration, some basic rules and content for an app that can be learned in a few minutes. We hasten to add that the application is not secure, has no validation and the patterns used can be a reference for functionality only.

The Startup rule set defines the Data Set used, the SubmitManager rule sets determines what happens when a button is clicked and the ContentManager rule set grabs the row snippet from the content files, builds the table rows and inserts them into the page. We will explain the page components in the next section for web designers.

It is now imperative that you train the web designer in the application functionality so that modifications made can be tested by the designer directly.

Understanding the Composable Agentic Platform Interface [Web]

When you first log into the Composable Agentic Platform console, you are greeted with the following interface:

Before you do anything else, you should change your assigned password to one of your own choice. You do this by clicking on the Password button (top right).

The desktop

The 8 radio buttons each represent a different desktop. For now, just leave the first one active only.

To get started, click on Start -> Servers:

Window controls

This will open a new window with the servers you can control:

You can minimize, maximize or close the window using the controls in the top right corner:

To move the window around, click down on the window header and drag it where you want it.

To resize the window, use the resize anchor in the bottom right corner:

Every window you open, and position stays in place if you log out and back in, so it pays to spend a little time organizing your desktop.

Server management

In the window you just opened, you can see the Proxy Server. Click on it to see the current state of the server. It should look like this:

You will likely be limited to Stopping and Starting the server and accessing the console. The console window is mainly used by server-side developers but can be useful if you are trying to identify a problem.

In most cases it will show something as simple as this:

Servers are instances of application containers, they are not physical servers. There is normally no risk associated with stopping and starting development servers.

Repository Management

To work with your assigned repositories, click on Start -> Repositories:

You will receive a list of repositories that you can access:

Click on the Web Application Tutorial:

Content Files

Then click on the View button. This will open the list of content files for you and close the repository window. Here we have expanded all the subfolders to make it easier to see:

So the entire application at this point contains just 2 files and 1 folder: “index.html”, the folder “snippets” and the file “quotefragment.snippet”.

At this stage, to make your life as easy as possible, we suggest you arrange your desktop similarly to the below:

You can (with some difficulty) work with the files directly through the console, uploading and downloading files as you need, but the Composable Agentic Platform console contains a much easier way to manage the lifecycle of you web development using your local file system, which we will discuss next.

Tutorial Application Initial Design Life Cycle [Web] [Rules]

Whenever you are assigned a repository where you need to exclusively maintain or modify content files, the simplest and easiest way is to work in a “scratch” folder.

A scratch folder can either contain ALL the content files in the repository or just a sub-set. The benefit of using a scratch folder is that anything you add or change will be synchronized with the target server immediately, allowing you to test your changes without having to perform any form of deployment task.

It is important to understand that those synchronizations are temporary. They will be removed when you either: Restart the server or redeploy the repository to the server. More about this later.

For now, start by clicking on “Content Files” in the repository tree:

Creating the scratch folder content

Since we are just starting the application, the correct approach now is do download all the artifacts and use them to create our scratch folder. To do this, click on Download. The repository content will download as a zip file:

Create a new scratch folder somewhere in your file system and copy the zip file to it and unzip it:

We now have our artefacts:

IMPORTANT: You MUST unzip the folder even if your file system supports moving into a zip file directly as the synchronization in most cases does not work with a zip file on it’s own.

So, let’s open the folder:

These are our artifacts that we need to edit and make attractive. So now we need to connect the Scratch folder to the server.

Connecting the scratch folder to the server

To connect the folder to the server, we go back to the Composable Agentic Platform console and click on Live Web Development:

This gives you an option to select a server that you can connect content to:

Select the Proxy Server and click on Live Web Development again.

(Should the Proxy Server be greyed out in the list then it is most likely stopped. In that case open the Servers window, select the Proxy Server and click on Start and wait 30 seconds – then return to the window above and click on Refresh).

You are now ready to link the server and the local folder:

To do this, drag the root folder inside the scratch folder (Web Application Tutorial) into the drop zone in the Window:

Your local folder and the server’s temporary content space will now synchronize. Unless you have a slow internet connection, this happens very quickly. You can see the process of what remains to be synchronized in the Queued section in the window.

If everything went well, you will see this:

IMPORTANT: If you close the window, your session expires, or you log out of the console then you will be disconnected. Do not despair, simply reconnect and the console will only synchronize from where you left off.

Your local folder and the server are now connected. In the next section we will test it.

Testing the folder synchronization

To test the connection, we are going to open the index.html file and make a very simple change. For this demo we will use the Atom editor, but you can use any tool of your choice as long as it saves to your scratch folder. Here is a listing of the index.html page.

You will notice that it is just basic HTML with one little anomaly: The $QUOTES$ tag inside the table. The reason for the placement of this tag is as a placeholder for when the server generates the list of quotes.

It is EXTREMELY important for the application functionality that you do NOT change the name of any of these tags, nor can you change the name or id attribute of any elements contained in the page.

In most cases you can change the tags (for example turning <span> into <div> or a table into <section> tags). However you must verify that the application remains functional in case there are JavaScript dependencies.

NOTE TO RULE WRITERS: When you create tags that contains snippets, it is important to include a comment about where the snippet can be found.

In our example application, the snippet to include looks like this:

As you can see, this snippet represents a single line in the table that the application can use to control the formatting of that line and even some actions as shown above.

So let’s modify the index.html file with something subtle first. Try changing:

<h1>Welcome to the house of quotes</h1>

To:

<h1>WELCOME TO THE HOUSE OF QUOTES</h1>

Wait 3 seconds then refresh the application page:

Adding artifacts

At this stage you can now add sub-folder to your scratch folder, add css files, images, JavaScript libraries, fonts and anything else that can help you style the page.

For example, we created a new folder named css:

Then we added a file named style.css to that folder:

And then we import that style sheet into our main page:

And save the changes. Within seconds the page now presents as:

And you can test that none of your changes have broken functionality.

At this point we hope that it is clear that working on the web design is now just a matter of respecting the developer tags in the pages and using your skills.

It is important to understand that changes in your scratch directory are always ADDED to the server content delivery. If you delete files, they will not be deleted from the server’s temporary content system, but they will be removed when you make the changes from your scratch folder permanent.

Making the scratch folder permanent

The last step in the initial design phase is to make the changes you have made permanent. To do this you must return to the console:

The first thing you should do is disconnect the synchronization by closing the synchronization window and then open the content files window:

Scroll down to the bottom of the page and get ready to upload your changes:

You should set the Upload type to Folder and then click on Choose Files.

Select the application content folder and click on Upload. You will possibly receive a warning:

Confirm by clicking on Upload and then click on the Upload Button:

All your changes will now be uploaded to the master content for the repository:

IMPORTANT: Whatever files you upload will be ADDED to the repository and will only create new files or replace existing files with the same name. Files in the master content with names not existing in your scratch folder will stay in place. This concept is useful for application maintenance which we will discuss in the next chapter.

Once your files finish uploading, the last step is to deploy them to the server’s permanent content delivery system.

To do this, click Content Files and then on the Deploy button:

You will be asked to pick one or more servers to deploy your content to:

Select the Proxy Server and click on Deploy. The server window will open and if you have a lot of content to deploy you will see a progress bar. However, in our case it will probably be so quick that you will not even notice:

So, close the server window, log out and inform the rule writer that you have completed your work.

Tutorial Application Maintenance Life Cycle [Web] [Rules]

The maintenance life cycle of a web application’s content files differs from the initial creation in several ways:

1. It may be performed by the rule writer in isolation

2. It may involve the web designer styling new features

3. It may only involve a small subset of the application

For these reasons you may not always wish to create a complete scratch folder with all the required synchronization of image files etc.

Building a maintenance scratch folder

If you are working collaboratively with other users, you should ALWAYS download the latest files from the repository before making any changes. Do not rely on an old scratch folder as you will possibly remove someone else’s work.

The good news is that anything you place in the scratch folder will either override or add to the content. Nothing will ever be deleted.

So before you synchronize your scratch folder, you can comfortably delete anything you do not intend to change after you have unzipped the download.

Alternatively you can create a scratch folder by downloading individual files from within the portal and copying them into the right location in the scratch folder (remembering to create the correct matching sub-folders if needed):

Once again, after you have completed your scratch folder you should connect it to the server and make your modifications that way. There are two reasons for this:

1. You can test your changes instantly

2. You can verify that you are not accidentally stepping on someone’s toes (see below)

Server collaboration check

If you just change one or two files you may be tempted to simply upload your file changes and deploy them. We do however strongly discourage that approach because it means you test after deploy (permanent) and you have not performed a collaboration check.

The collaboration check tells you if someone else is also doing work with a scratch folder at the same time as you are. It will show up before you connect for synchronization as follows:

If you see this warning you should NOT connect your scratch folder without communicating with the named user.

Template Engine [Web] [Rules]

The platform contains a rule named “Merge HTML Pages”. This rule is used to merge content into a wrapping page with headers and footers.

For example, consider the following master.html template:

It contains the headers and footers for the pages, but not the actual content. You can have more than one template in the same application if needs be.

The important part is line 18 in the above code. This is where the content for each page will be inserted, although any <head> tags in the content will be appended to the page just before the </head> in the template.

These rules do of course work with live web development, so the web designer can modify them on the fly while testing content.

For example:

When merged with the master.html page will produce:

Notice line 11 where the <title> tag is not inserted and line 18 where the content is inserted.

It is possible to control where precisely the <head> information is inserted into the template. Sometimes this is necessary to give some JavaScript libraries preference over others. To specify a precise spot in the master template where content <head> information should be insert, place the following comment at that location:

Internationalization [Rules]

If your application needs to be translated into multiple languages and locales, there are tree rules to help you:

Translate HTML page

This rule is usually placed either immediately after all static content is loaded for any given page, but before any dynamic content is injected into the page. The Content Variable should contain the content to be translated.

The rule can determine if the content is HTML or simply plain text. If HTML, the rule will isolate constants such as plain HTML text, <select> options, input place holders etc., being fully HTML aware.

The rule is capable of recording text that needs to be translated and can write that text out to one or more files (merging it with existing known translations).

Building translation files depends on the content of the global variable BUILD_TRANSLATION, rather than a property. This approach is to enable the easy switching on/off of translation recording between development and production without the need to change the rule structure.

If the BUILD_TRANSLATION global variable is set to “Yes” the Programmable Data Agent will write out fresh translation files in the format “translation-"+locale+".utf8” to the home folder on the target server.

So to get a translation file that can be handed to a local language expert, let the rule “learn” all the text that should be translated and then have the language expert translate that.

The rule is capable of translation into complex character languages such and Chinese and Japanese. Please see the rule help file for further information.

From International Values

Use this rule to convert international edited values (currency, numbers, dates) to a usable internal format.

This rule can convert input from any given locale into a consistent US internal format for processing.

All values returned uses US number formatting (. as decimal point) and all dates will be returned in YYYYMMDD format.

To International Values

This rule is the inverse of the previous rule. It takes US formatted numbers and YYYYMMDD formatted dates and converts them to the appropriate local version (for example: MM/DD/YY for the US.

Working in a HTML aware way [Rules]

The framework contains a HTML aware rule that can significantly simplify the co-operation between the rule writer and the web designer.

Using this rule, you can set the value of check radio buttons, checkboxes, select options in lists and input fields in a HTML document. You can also set the value of text areas, output tags, spans, labels and divs. For these tags, the value obviously refers to the innerHTML of those tags.

For checkboxes, the value can either be “on”, “true” or “checked” if no specific value has been defined for the checkbox. For lists (select tag), the options to select must have a value attribute.

Tags to set can be identified by name, ID or class name. If more than one instance of a identifier exists, all will be set.

This approach can in many cases be used to avoid using $TAGS$ in the HTML and the web designer can instead provide a page with sample values that makes visual sense on its own and the rule writer simply overrides those sample values before serving the page to the user.

Using the scripting interface

The Tomorrow Software console ships with a scripting interface to facilitate automated management by other tools. The scripting interface is based on the TCL (Tools Command Language) version 8.4 syntax and commands, but also includes a number of Tomorrow Software specific commands.

As scripting is a programming interface, the scripting engine is not multi-lingual. It is invoked by a simple HTTP/S POST command to the URL:

http://<server>/console/ScriptRunner

The parameters for the POST are as follows:

All parameters should be UTF-8 encoded.

Learning TCL

It is beyond the scope of this manual to provide complete details of the TCL language. TCL has been in use for many years and plenty of online resources exist for learning the language. An excellent primer can be found here:

Also, several sample scripts can be found in the /Education/script samples folder.

Testing scripts

To assist with testing scripts, a specific page has been made available:

http://<server>/console/scriptRunner.jsp

This page allows you to enter a user ID and password, as well as a script, and submit it to the console. The output from the submission is returned to the browser.

Tomorrow Software specific TCL extensions

Tomorrow Software introduces a number of extensions to the standard TCL language. All of the extensions relate to specific console management tasks.

In addition, output written with the "puts" command is written to the HTTP Response stream rather than STDOUT.

Command: createUser

The createUser command creates a new console user. The command takes a number of parameters to correctly define a user in the console:

The following script snippet shows an example of how to use this command:

This command can only be executed with administrator or security authority.

Command: deployConfiguration

The deployConfiguration command deploys a specific configuration to a nominated server. Only configurations located in a repository can be deployed using this command. The parameters for the command are Server ID, Repository Name and Configuration Name. The following script snippet shows an example of how to use this command:

The command will wait for the deployment task to complete before continuing. The deployment does not result in a server restart. The stopServer and startServer commands should be used after this command to ensure that the deployed configuration takes effect. This command is only valid for production servers.

Command: deleteUser

The deleteUser command deletes a user based on a provided user ID. The following script snippet shows an example of how to use this command:

This command can only be executed with administrator or security authority.

Command: getAudit

The getAudit command retrieves a subset of the internal Tomorrow Software audit log. The following snippet shows an example of how to use this command:

The above commands retrieve all audit log entries after the Java Time Stamp 1425064936463.

This command can only be executed with administrator or security authority.

Command: getConfiguration

The getConfiguration command reads a specific configuration from a specific repository and provides access to all elements of the configuration (including the ability to update it if the user has the appropriate authority.

The following script snippet shows an example of how to use this command:

The above command obtains the BasicWebTrial configuration from the Product Trial repository, outputs the default rule set file name and then sets the maximum number of test records to 20,000 before updating the configuration (writing it to the file system).

The following table provides a list of all of the readable properties on the configuration object:

Each of the above values can also be set using the equivalent setter method (replacing "get"/"is" with "set").

Please note that for any arrays, ALL arrays in a set (attributes, databases, timer rule sets) MUST be set to the same length before invoking update.

The TCL interface only supports updating existing configurations. New configurations cannot be created using TCL and existing configurations cannot be deleted.

Command: getUser

The getUser command reads a specific user and provides access to some elements of that user.

The following script snippet shows an example of how to use this command:

The above command reads the user test123, outputs the name of that user and then sets the role before updating the user.

The following table provides a list of all the readable properties on the user object:

Most of the above values can also be set using the equivalent setter method (replacing "get"/"is" with "set"). The values that cannot be set are: Logon, Created and LastLogon.

This command can only be executed with administrator or security authority.

Command: serverList

The serverList command obtains a list of all configured servers in the console that the user is authorized to view. The response is in the form of an array of server IDs. The following script snippet shows an example of how to use this command:

A sample output from running the above script is as follows:

Command: serverStatus

The serverStatus command is used to interrogate the current status of a server, based on the server's ID. The following script snippet shows an example of how to use this command:

The return value from the command is a server status object. The following methods are available on the object:

Command: setCredentials

The setCredentials command is used to set the value of a given field in the credentials vault. The specific vault and field must exist already.

The following script snippet shows an example of how to use this command:

This command can only be executed with administrator or security authority.

Command: startServer

The startServer command is used to start a nominated server.

The following script snippet shows an example of how to use this command:

The command will wait for up to 30 seconds to ensure that the server is actually started. Provided the server starts, the command will return "1". If the server fails to start, then "0" will be returned.

Command: stopServer

The stopServer command is used to stop a nominated server.

The following script snippet shows an example of how to use this command:

The command will wait for up to 30 seconds to ensure that the server is actually stopped. Provided the server stops, the command will return "1". If the server fails to stop then "0" will be returned.

Command: userExists

The userExists command checks if a given user ID exists. The command returns "0" if the user ID is not found or "1" if the user ID is found. The following script snippet shows an example of how to use this command:

This command can only be executed with administrator or security authority.

Command: updateApplication

The updateApplication command updates a console application (such as Qwerty or the console itself. The following script snippet shows an example of how to use this command. In this case the console itself will be updated:

This command can only be executed with administrator authority.

Command: updateExtension

The updateExtension command updates/installs an extension from the update server (such as the Base Rules or the Http Rules). The following script snippet shows an example of how to use this command:

This command can only be executed with administrator authority.

Command: updateRepository

The updateRepository command updates/installs a repository from the update server (such as the Product Trial repository). The following script snippet shows an example of how to use this command:

This command can only be executed with administrator authority.

Command: userList

The userList command obtains a list of all users in the console. The response is in the form of an array of user IDs. The following script snippet shows an example of how to use this command:

A sample output from running the above script is as follows:

This command can only be executed with administrator or security authority.

Introduction

Welcome to a new dimension of Microsoft Windows automation. Using the Tomorrow Software Windows Automation Extension you can now not just script up the flow of a Windows Application – but you can also combine it with data from many other sources and the powerful rule writing capabilities of the Tomorrow Software Multi-Protocol engine.

The extension is based on the popular AutoIt automation product and we have included tools from that product to help your automation efforts. AutoIt is a free product, however, if you find the product and the Windows Automation extension useful, we would encourage you to make a donation to the creators of AutoIt at:

https://www.autoitscript.com/site/donate/

Licensing

The licensing of the Tomorrow Software Windows Automation Extension is the same as most other extensions that we provide. You simply need a valid Tomorrow Software license.

The license for the AutoIt tools described in this reference guide is found in the “data” folder where you also found this document. In a quick summary it is a classic free software license.

Getting started

Before you begin your first automation project, you need to make some updates to your Tomorrow Software installation.

Required Updates

The first step is to update/install the following components via the update server:

• Tomorrow Software console (B18020 or later)

• Base Rules (2018-04-26 or later)

• Parallel Processing Rules (2018-04-23 or later)

• Windows Automation Rules (2018-04-23 or later)

If you received this document through some means other than the update server, then you will also need to install the Windows Automation repository.

At this point, stop the Tomorrow Software instance.

Updating the Java Runtime Environment

The JRE that ships with Tomorrow Software is a basic 32 bit JRE. The version may depend on when you received your copy of the product.

To successfully run automation projects, you need to update the JRE to at least version 8 for your platform (32 bit or 64 bit).

You can download the correct JRE from here: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html

Once you have installed the JRE, you need to update the JRE folder under the Tomorrow Software installation with the JRE that you installed on your Windows PC. You do this by renaming the original JRE folder and creating a new one by copying the JRE from C:\Program Files\Java\jre1.8.0_(version) and renaming it to jre.

Installing the required tools

The final step is to install the Au3Info tool. You need this tool to inspect running Microsoft Windows programs and identify the names of controls that you can manage. The easiest way to install the tool is to download it from the Windows Automation repository’s data folder and save it to your desktop (or some other convenient location).

There are two versions available:

• Au3Info.exe is for 32-bit Windows systems

• Au3Info_x64 is for 64-bit Windows systems

Make sure that you download the right version.

Your first automation

In this example we will take you through the automation of creating a document in Windows Notepad and saving it.

Start by restarting the Tomorrow Software Server instance, log in and create a new repository called “Notepad Exercise”.

Then create a new rule set called “NotePadDemo”:

and open it up in the rules editor.

Starting an application

The very first thing we need to do is start notepad itself. To start an application, simply drag the Run Application rule onto the canvas:

And set the properties as shown:

This step alone will cause Notepad to start up. You do not need to provide a directory since notepad will be in the system path.

Since we are going to do something more than just start the application, we need to make sure that it is fully loaded before we start pressing keys. So we add a Wait Active rule:

With the properties set as follows:

Identifying windows

Here it is relevant to pause for a minute and look at those properties.

Firstly, the Windows Label. Many of the rules provided in the Windows Automation framework use the Label and Text combination to identify windows to work with. The logic of this combination is as follows:

The Label match is basically starting from the beginning of the label matching as many characters as provided in the rule.

In this case we match the entire label.

The optional Text matching refers to a text within the window that was opened. This could be any word visible on the page or within a dialog box. This matching is used for more precise pinpointing of a window.

We will perform such a match later in this section.

Entering text

For now, we will simply send some keystrokes to Notepad to create a document we can save:

Testing

Let’s try and run our three new rules and see what happens. In the Notepad Exercise repository create a new configuration as follows:

And set the input source to:

We can now deploy our configuration to any convenient active server (You can use a Multi-Protocol server or even Qwerty). As long as you tick the “Restart immediately”, shortly after the deployment is complete, you will see Notepad start up and the text appear:

Sending formatted text

You may have noticed that the text entered in our example was set as “Raw”:

Your other option would be to use the formatting text feature:

This feature allows you to send specific keystrokes with great ease. For example:

!a would be the same as sending Alt-a
^a would be the same as sending Ctrl-a
+a would be the same as sending Shift-a
#a would be the same as sending Windows key (Win-a)

You can combine these keys: ^!a would be Ctrl-Alt-a.

If you need to send any of those characters without sending them as special keys, you must enclose them in curly brackets. For example {!} to send a !

You can also send normal Windows keys by enclosing them in curly brackets. For example:

{SPACE} {ENTER} {DEL} {TAB} {BS} {HOME} {UP} {DOWN} {LEFT} {RIGHT}

The name used in the brackets can be most normal windows keyboard designations.

If you need to repeat a few keystrokes, you can do this by entering the key name followed by a count. For example:

{DEL 5}

Will result in the delete key being hit 5 times.

So we could in theory expand on our example to make notepad try to close once the text was entered. The keystrokes for closing a Window is Alt-F4. We would do this in formatted text as follows:

Doing this results in the following outcome:

You can try this if you wish, just remember to switch it back to “Hello World!!” and “Raw “afterwards to continue this exercise.

Reading window text

It is one thing being able to send keystrokes, but more often than not for automation, you will need to know the content of specific fields or you may need to be able to set the value of specific named fields without just using keyboard navigation.

This is where the tool from AutoIt (that you installed earlier) comes into play. Start up the correct version of Au3Info:

Click on the Finder tool and drag it onto the main Notepad window:

You will see that the tool provides you with the basic Windows information (Title and Class). It also provides us with the Basic Control Info, which is that the field is of the Class “Edit” and it is instance “1”.

What we need at this stage is the ability to identify a specific field in a specific window. The best and safest way to do this is to click on the “Control” tab:

And then double-click on the “Advanced Mode” entry. This copies the identifier [CLASS:Edit; INSTANCE:1] to the clipboard for us so that we can use it easily.

So all we need now is to add a “Get Control Text” rule (and a List Variables so we can see what’s going on):

The properties for the Get Control Text would be as follows:

The control identifier being easily set by entering two double-quotes and pasting the content of the clipboard from the AutoIt tool in between them.

A quick run and peak at our console will confirm that this is working:

Text outside controls

There are certain circumstances where text is not necessarily linked to a specific control. The Windows Calculator is one such example. It actually stores the result window not in the control, but in the window itself. If you need to get to this text, you can use the Get Window Text rule instead of the Get Control Text rule.

Hint: When you extract text from the Window itself, it is often formatted across multiple lines. An easy way to get visibility of control characters in text is to escape them as if they would be going into a URL. You can do this with the Escape rule.

Closing windows

It is now time to close our window. This is simply done with the Close Window rule:

The properties should look familiar now:

The result of adding this rule will inevitably be:

Now, we wish to wait for this dialog to appear and then hit Enter to save the file we just created. Once again, this should now be familiar territory:

With the properties being set as follows:

Note the use of Window text in the “Wait for save box” rule. It is conceivable that Notepad my put out many dialogs that is simple labeled “Notepad”, so the extra check for the word “Save” somewhere on the dialog box helps us confirm we are in the right place.

Advanced controls

But now things are getting a little tricky. Once we hit enter, we need to wait for the “Save As” dialog to appear:

On the surface, this may look quite simple. We wait for the dialog box to appear, we find the controls for the directory and file name, put in some values and hit Save.

The first step is not too hard:

Next, we discover (using the AutoIt tool) that the directory control is named “ToolbarWindow32”:

However, through experimentation it quickly becomes obvious that you can’t just set the control value to “Address: MyDirectory” using the Set Control Text rule. It simply has no effect. So, we need to introduce a workaround. In this case, some experimentation shows that if you click on the far right corner of the control, you can actually enter a directory name:

And the text is preselected, so if we can just do the same mouse clicks in rules, we will be able to override the text in the control and continue. This requires a few steps

Getting a control position

We start by getting the control position so that we can figure out where to click within it:

Adding a List Variables rule and running this results in the following output in the console:

So now we know the position and dimensions of the control. The next step is to figure out the correct position to click. A simple calculation rule will take care of that:

All that remains now is to “click”:

Most of the above should now be clear. We are basically clicking the far left side of the control, using the left mouse button. If you don’t provide an X or Y position, the center of the controls axis respectively will be clicked.

All that remains now is to set the control value by sending the right key strokes:

Notice that we hit the Enter key as part of this exercise. This is because the Save As dialog box changes to the directory entered, once the Enter key is hit.

If you are following this example, make sure that you pick a directory that actually exists. In our example, we have created C:\DemoData purely for this exercise.

The next job is to set the actual file name. Using AutoIt, we discover that the control name for this is “[CLASS:Edit; INSTANCE:1]”. So this looks pretty straight forward. However, setting the control text by itself:

Does not work well. The resulting file name actually becomes “mydemo.txt*.txt”.

So formatted text once again comes to the rescue. We preface the new file name with a Ctrl-a (select all) followed by Delete to clear the field:

Note that there are other ways you could achieve the same goal. This is just an illustrative example.

All that remains is to hit the Save button. Any old Windows Keyboard warrior will know that underlined text character in a Windows dialog box can be invoked using Alt+[underlined key]:

In this case, Alt+S will save the file. So we go ahead and invoke it:

If you run this complete example, you will now have a file in your designated folder called “mydemo.txt”

Handling exceptions

Of course, if you run our scenario twice, you will encounter another message dialog telling you that the file already exists:

It is important to handle the kinds of exceptions as otherwise your automation project may become unreliable. In our case, we wait for the “Already exists” dialog to appear, with a timeout telling us if we need to handle it or not:

In the above example, the file will simply be replaced if it already exists.

Interference

A significant problem with Windows automation is interference. Essentially the automation rules are sending keystrokes and mouse clicks to applications. If someone (a human being mostly) tries to also enter keys or click the mouse at the same time, the automation is likely to fail. For this reason, automations should always run on a dedicated machine with no other activity.

When running a cluster of Tomorrow Software Server instances as a REST service, you need to consider the avoidance of interference traffic impacting automation requests. For example, a load balanced clustered web-based service may have heartbeat health check request pings to confirm service availability, or other unwanted requests; such traffic needs to be filtered (not necessarily blocked) but prevented from reaching the automation rulesets.

Parallel processing

A final issue to be aware of when running automations is that multiple concurrent automations also interfere with each other. For this reason, the best approach is to queue automations if they need to run on the same server. The easiest way to do this is with the “Launch Queued Process” rule:

This rule will ensure that Programmable Data Agent wide, only one automation rule set will run at any one point in time. However, the rules are not held up whilst these automation requests are queued.

If you need to wait for an automation process to complete before continuing, the best rule to use is “Wait for Queued Process”. This rule will place the automation request on the queue and will not continue until the automation has completed.

Windows automation as a service

Scaling up

Given you can only run one automation process at any one point in time, you may need a load balanced setup to share automation requests over multiple servers.

The best way to do this is by wrapping the automation request into a REST service and deploying it to multiple virtual server instances behind a load balancer in round robin mode.

Using this approach, the load balancer will find the next available server and distribute the load evenly.

A core virtual server instance should be created so that it can be cloned whenever more capacity is needed.

Set-up

The default BaseApp Tomorrow Software Server service instance is suitable for running as a REST service, please refer to the instructions file Read me.txt located in Tomorrow-Software-Server-10.0.0]/BaseApp/ for set up. Also refer to the Product Reference.pdf section entitled “Removing other unnecessary components” to remove the Tomorrow Software Console and other unwanted demo applications and server instances not required.

Please note that Windows Automation instances cannot be run as a service. They must be started using a bat file in the Windows startup group.

Example to run at start up: Windows Server 2012

Modify Local Group Policy Editor > Administrative Templates > System > Logon > Run these programs at user logon

Enable this option, press show and enter the following value, and apply/OK to this configuration.

CMD /c "c:\Tomorrow\Tomorrow-Software-Server-10.0.0\Tomorrow.bat"

Where c:\Tomorrow\Tomorrow-Software-Server-10.0.0 is this example directory path.

When using this option you need to edit the default Tomorrow.bat file to add the following three lines before cd server to accommodate the start up directory path as follows, once again where c:\Tomorrow\Tomorrow-Software-Server-10.0.0 is this example directory path.

cd/
cd Tomorrow
cd Tomorrow-Software-Server-10.0.0
cd server

Active Desktop using RealVNC

A significant limitation with Windows automation (like most GUI automation tools) is that it requires an active desktop to run. So, when you log out of any remote desktop connection or lock the computer, automation is paused/stuck until you reconnect. It is therefore impractical to retain open RDP connection for multiple Tomorrow Software Server instances when running as a REST service with high availability demands. The following is a working example to overcome this limitation.

Example: In Windows Server 2012 set the Turn off the display option to Never in Control Panel Power Options.

You still need a way for the remote server to have it’s head/desktop to be unlocked and active. The best way to do this is to use the VNC protocol rather than RDP. There are numerous VNC software (server and client) available that are also free and/or open source.

For this example, we have tested with RealVNC - https://www.realvnc.com/download/vnc/latest/ VNC for Windows version 5.2.3.

Please ensure you refer to Licensing terms https://www.realvnc.com/products/vnc/ as a License key is required to install and use Real VNC for your environment and organisation.

RealVNC VNC Server uses modes to provide remote access to computers in different circumstances, to meet different needs.

VNC Server needs to install on the Tomorrow Software Server instance, and VNC Viewer needs to be installed on a ‘controller’ server.

Given the Tomorrow Software Console server will have access to the server instances, this server is a good candidate to run VNC Viewer, although a dedicated server with access to the instances can perform this connectivity too.

VNC Server installs and runs on default port 5900, so ensure any security group policies have been amended to permit connection using this port, together with ports that are running the REST service. The BaseApp to use as a REST service runs as default on port 10001 as defined in the rulesengine.properties settings.

RealVNC installation notes

During the standard RealVNC installation process, ensure you select the appropriate components for your REST service instance and Console Server or controller.

There is also an install option to add an exception to the Windows firewall during installation, but if you are still experiencing connection problems you may still be required to inspect your server firewall settings.

Before starting the VNS Server service, it’s useful to know all VNC applications are controlled by VNC parameters, set to suitable default values for most users out-of-the-box.

Please refer to this link for RealVNC parameter names reference information. https://help.realvnc.com/hc/en-us/articles/360002251297-VNC-Server-Parameter-Reference-

The easiest way to set the authentication scheme and credentials for the VNC Viewer controller in order to connect to VNC Server is to start the VNC Server (User Mode) desktop application.

For example, set the simple authentication scheme using VNC password in the VNC Server – Options > Users & Permissions option as follows.

Once the authentication scheme and access credentials have been set, and Licensing updated if required, ensure you stop the running VNC Server (User Mode) by pressing the More button, followed by Stop VNC Server as follows.

The parameter IdleTimeout specifies the number of seconds to wait before disconnecting users who have not interacted with the host computer during that time. The default value for IdleTimeout is 3600 seconds, so you need to set this parameter to 0 in order to never disconnect idle connections. You need to add the IdleTimeout parameter in Windows Registry Editor when running VNC Server as a Windows service as follows.

1. Using Registry Editor, navigate to HKEY_LOCAL_MACHINE\Software\RealVNC\vncserver.

2. Select New > String Value from the shortcut menu and create IdleTimeout.

3. Select Modify from the shortcut menu, and specify appropriate Value data, 0.

With VNC Server successfully installed and parameters set, amend the VNC Server service with Startup Type set to Automatic.

Also, the Allow service to interact with desktop option must be checked as follows.

With the IdleTimeout parameter set to 0 as a minimum, restart the server and START the VNC Server service.

You are now ready to connect to the Tomorrow Software server instance running VNC Server from the controller running VNC Viewer.

Connect to the Tomorrow Software Console server (or controller) using a standard Windows remote desktop connection; install the default VNC Viewer components, and start the VNC Viewer application from the desktop shortcut.

The VNC Viewer application will then prompt to enter the host name or IP address of the REST Service server instance running VNC Server.

With the ‘Let VNC Server choose’ option for encryption selected you will prompted as follows for the password set on VNC Server earlier in the VNC Server – Options > Users & Permissions option.

If connection is successful the VNC Viewer will launch a connected window to the server, at which point you can login using your Windows user credentials, and you can proceed to repeat the process to make a VNC connection to all VNC Server instances if operating in a scaled cluster.

Even with VNC Viewer closed, because it is simply a relay of the host’s screen to your desktop (works differently than RDP), when disconnected, it just stops relaying, and that is all. The relay works like a splitter connection, both the local head/monitor has access, and the VNC Viewer has access.

By this design, VNC will continue to retain an active desktop even though you’re not connected over VNC, as long as the host desktop is logged in and not locked.

The environment – Tomorrow Software Console server, and multiple connected REST service server instances as defined in the Tomorrow Software Console server definitions are now ready for use; the VNC Viewer windows residing on the Tomorrow Software Console server (or controller) can be closed, and the remote desktop connection closed, and desktop will remain unlocked and active.

Initial Steps

Upon first login to the portal application, you may choose to edit the Unassigned Company and role which are created by default. This is not required and if you prefer you may leave it with its default settings. Please note that you cannot delete this entry. This unassigned company acts as a fallback for users who have yet to be assigned a company and role once registered.

Grouped Permissions

Permissions are grouped by Company/Role/User.

When you first create a resource i.e. a page, you will see that a permission is already assigned for that page. The default permission is always assigned as a global one. Meaning that everyone can view, access, edit or download that resource however the resource is not yet active or visible to anyone. You will need to enable this option for the resource in question so that a user can view, access, edit or download.

Possible Permission Combinations

• When no company or role or specific user is selected a global permission is assigned and no other permission is allowed to exist.

• When only a specific company is assigned then all roles and users within that company can view, access, edit or download that resource.

• When only a specific company and specific role are assigned then all users of that company and role can view, access, edit or download that resource.

• When only a specific company, specific role and specific user is assigned, then only that user within the company and role selected can view, access, edit or download that resource.

The above combinations can exist in parallel between companies, roles and users in one resource.

Companies

Add a new company

Actions

• Navigate to Companies > Add New or alternatively use the Add New button on the Company's page.

• Complete the required fields and submit the form.

Fields

• Company Name

  • Enter the company name i.e. TomorrowX Limited

• Domain check

  • Enter the company’s domain name i.e. tomorrowx.com (without www)

• Unique/Short Name

  • Enter a unique name for the company i.e tomorrowx

• Approver(s) email

  • Enter a high-level e-mail address for the company. Used for approving employee actions i.e. purchasing a training course or software trial license.

• Accounting email

  • Enter an e-mail address for the company’s account dept.

• Currency

  • Enter the 3 letter currency code for the company i.e USD

Edit an existing company

Actions

• Navigate to Companies > View All and select the company you would like to edit by clicking the Edit link to the right of the company name.

• Make any relevant changes to the fields and submit the form.

Fields

• See Fields from 2.0 above +

• Assign Menu

  • Select a menu to assign to this company - see 5.1 Menus - Add a New Menu

Assign Support Agents

Actions

• Navigate to Companies > View All and select the company you would like to assign a support agent to by clicking the Support Agents link to the right of the company name.

• Make any relevant changes to the fields and submit the form.

Fields

• Assign a New Agent

  • Support Agent

    • Select a user from the list to assign as a support agent

  • Make Head of Support

    • Select this option to set the user assigned above as the Head of Support of a company. Only one agent may be assigned to a company as a Head of Support. To assign a new Head of Support agent, delete the existing one first and then add a new agent.

• Assigned Agents

View/delete assigned agents

Assign an IP Range

Actions

• Navigate to Companies > View All and select the company you would like to assign an IP Range to by clicking the IP Ranges link to the right of the company name.

• Make any relevant changes to the fields and submit the form.

Fields

• Assign a New IP Range

  • Start IP

    • Enter the starting IP Address. If no IP range is to be used simply enter a single IP Address here. i.e. 10.10.10.10

  • End IP

    • Enter the ending IP Address. If no IP range is to be used leave this field empty. i.e. IP Range: 10.10.10.255

• Assigned IP Ranges

View/delete assigned IP Addresses

Roles

Add a new role

Actions

• Navigate to Companies > Roles > Add New or alternatively use the Add New button on the Roles page.

• Complete the required fields and submit the form.

Fields

• Role Name

  • Enter a role name i.e. Analyst

• Assigned to Company

  • Select a company to assign the role to

Edit an existing role

Actions

• Navigate to Role > View All and select the role you would like to edit by clicking the Edit link to the right of the role name.

• Make any relevant changes to the fields and submit the form.

Fields

See Fields from 3.1 above +

Users

Add a new user

Actions

• Navigate to Users > Add New or alternatively use the Add New button on the Users page.

• Complete the required fields and submit the form.

NOTE: Before creating a user, be sure that the company as well as the role that the user will be assigned has already been created. See 2.1 Companies - Adding a new company.

Newly created user account status is always set to Inactive once created and needs to be updated to an Active state before it can be used. See 4.2 Users - Edit an existing user below.

Fields

• First Name

  • Enter the user's first name

• Last Name

  • Enter the user's last name

• Email Address

  • Enter the user's company e-mail address (must use the same company domain as below)

• Company Domain

  • Select the user's company domain name

• Mobile Number

  • Enter the user’s mobile number (used for receiving device verification codes, OTP codes etc.)

• Company

  • Assign a company to the user - see note above.

• Role

  • Assign a role to the user - see note above.

Edit an existing user

Actions

• Navigate to Users > View All and select the user you would like to edit by clicking the Edit link to the right of the user.

• Make any relevant changes to the fields and submit the form.

Fields

• User Details

  • See Fields from 4.1 above +

  • User Internal Type

    • Select the appropriate user type i.e Client, Admin, Partner, Unassigned

  • User Account Status

    • Enable/disable the user’s account

• Trusted Devices

  • View/delete user’s trusted devices

User stats

Actions

View user login stats on this page.

Menus

Add a new menu

Actions

• Navigate to Config > Menus and select the Add New button on the Menus Overview page.

• Complete the required fields and submit the form.

Newly created user menu status is always set to Inactive once created and needs to be updated to an Active state before it can be used. See 5.2 Menus - Edit an existing menu below.

Fields

• Menu Name

  • Enter a name for the menu i.e. Internal User’s Menu

Edit an existing menu

Actions

• Navigate to Config > Menus and select the menu you would like to edit by clicking the Edit link to the right of the menu name.

• Complete the required fields and submit the form.

Fields

• See Fields from 5.1 above +

• Status

  • Select whether this menu is active or inactive from the drop down menu

MENU LINKS

Add a new menu link

Actions

• Navigate to Config > Menus and select the Menu Links button.

• On the Menu Links Overview page, select the Add New button.

• Complete the required fields and submit the form.

Fields

• Link Name

  • Enter a name for the menu link i.e. Downloads

• Link

  • Enter the URL path of the link i.e. user/downloads

• Link CSS Class

  • Add a custom CSS class name to be used on the <li> element of the menu.

• Link CSS Icon

  • Add a custom CSS class name to be used on the <i> element of the menu which displays the icon i.e. fa fa-cog. (See for compatible icons)

• Sub Links

  • Select whether this menu item will have children menu items (Active) or not (Inactive)

Edit an existing menu link

Actions

• Navigate to Config > Menus and select the Menu Links button.

• On the Menu Links Overview page select the menu link you would like to edit by clicking the Edit link to the right of the menu link name.

• Complete the required fields and submit the form.

Fields

• See Fields from 5.3.1 above +

Add sub menu links

Actions

• Navigate to Config > Menus and select the Menu Links button.

• On the Menu Links Overview page select the menu link you would like to add sub links to by clicking the Sub Links link to the right of the menu link name.

• Complete the required fields and submit the form.

Fields

• Assign New Sub Links

  • Sub link Name

    • Enter a name for the sub link i.e. white papers

  • Sub link URL

    • Enter a URL for the sub link i.e. user/downloads/white-papers

Assigned Sub Links

• View/delete sub links from a main menu link

Set link permissions

Actions

• Navigate to Config > Menus and select the Menu Links button.

• On the Menu Links Overview page select the menu link you would like to set link permissions for by clicking the Permissions link to the right of the menu link name.

• Complete the required fields and submit the form.

Fields

• Assign New Permission

  • Company

    • Select a company from the drop down list to allow access to this menu item.

  • Role

    • If you would like to further restrict access to this menu link select a specific role for the company selected above.

  • User

    • If you would like to further restrict access to this menu link select a specific user for the company and role selected above.

• Assigned Permissions

  • View/delete assigned menu link permissions

Set up an existing menu

Actions

• Navigate to Config > Menus and select the menu you would like to set up by clicking the Setup link to the right of the menu name.

• Complete the required fields and submit the form.

Fields

• Assign New Links

  • Links

    • Select a link from the drop down to assign it to the currently selected menu

  • Sort Order

    • Enter a number in order to set the position of the menu item within the menu

• Assigned Links

View/delete menu links

Pages

Add a new page

Actions

• Navigate to Config > Pages and select the Add New button on the Pages Overview page.

• Complete the required fields and submit the form.

Fields

• Page Name

  • Enter a name for the page you are creating i.e. Company Profile

• URI Collection

  • Enter the URI collection (group of pages) i.e. profile

• URI Controller (Page)

  • Add a URI controller name (page) i.e. pages

• URI Method (Action)

  • Add a URI method (action) i.e. view

Edit an existing page

Actions

• Navigate to Config > Pages and select the page you would like to edit by clicking the Edit link to the right of the page name.

• Complete the required fields and submit the form.

Fields

• See Fields from 6.1 above +

• Status

  • Select whether this page is active or inactive from the drop down menu.

Set page permissions

Actions

• Navigate to Config > Pages and select the page you would like to set permissions to by clicking the Permissions link to the right of the page name.

• Complete the required fields and submit the form.

Fields

• Assign New Permission

  • Company

    • Select a company from the drop down list to allow access to this page.

  • Role

    • If you would like to further restrict access to this page, select a specific role for the company selected above.

  • User

    • If you would like to further restrict access to this page, select a specific user for the company and role selected above.

• Assigned Permissions

View/delete assigned page permissions

Downloads

Add a new download

Actions

• Navigate to Downloads > Add New or alternatively use the Add New button on the Downloads Overview page.

• Complete the required fields and submit the form.

Fields

• File Name

  • Enter a name for your download i.e. whitepaper 1

• No. Of Downloads Allowed

  • Enter the max number of downloads allowed - Limit Downloads field below must be set to Limited in order to be active.

• Limit Downloads

  • In order to limit a file to a certain number of downloads, set this to Limited and set the total number of downloads allowed above.

• File Upload

  • Choose a file to upload.

• Mark as Featured Download

  • Select this in order to mark your file as a “Featured Download”. Featured downloads are displayed throughout the site in certain locations.

Edit an existing download

Actions

• Navigate to Downloads > View all and select the download you would like to edit by clicking the Edit link to the right of the download item name.

• Complete the required fields and submit the form.

Fields

• See Fields from 7.1 above +

• Visibility

  • Set whether the download is visible or not.

Set download permissions

Actions

• Navigate to Downloads > View all and select the download you would like to set permissions for by clicking the Permissions link to the right of the download item name.

• Complete the required fields and submit the form.

Fields

• Assign New Permission

  • Company

    • Select a company from the drop down list to allow access to this download.

  • Role

    • If you would like to further restrict access to this download, select a specific role for the company selected above.

  • User

    • If you would like to further restrict access to this download, select a specific user for the company and role selected above.

• Assigned Permissions

  • View/delete assigned file download permissions.

Download Stats

Actions

View file download stats on this page.

Solutions

Add a new solution

Actions

• Navigate to Solutions > Add New or alternatively use the Add New button on the Solutions Overview page.

• Complete the required fields and submit the form.

NOTE: Before creating a new solution, be sure that you have created the appropriate solution categories and solution industries. See 8.4.1 Add solution category and 8.5.1 Add solution industry.

Fields

• Solution Name

  • Enter a name for your solution

• Solution Image

  • Enter the filename of the image to use as the solution image. Be sure to include the file type extension.

• Synopsis

  • Enter a short synopsis for the solution. Used on sub-solution pages.

• Description

  • Enter a longer description for the solution which will be displayed on the individual solution page. Use the WYSIWYG editor to style the information entered.

• Deployment Requirements

  • Enter any deployment requirements for the solution which will be displayed on the individual solution page. Use the WYSIWYG editor to style the information entered.

• Category

  • Select a category which the solution belongs in.

• Industry

  • Select an industry which the solutions belongs in.

• Mark as Featured Solution

  • Select this to mark the solution as a Featured Solution. Featured solutions are displayed throughout the site in certain areas.

Edit an existing solution

Actions

• Navigate to Solutions > View all and select the solution you would like to edit by clicking the Edit link to the right of the solution item name.

• Complete the required fields and submit the form.

Fields

• See Fields from 8.1 above +

• Status

  • Set whether the solution is active or inactive.

Set solution permissions

Actions

• Navigate to Solutions > View all and select the solution you would like to set permissions to by clicking the Permissions link to the right of the solution name.

• Complete the required fields and submit the form.

Fields

• Assign New Permission

  • Company

    • Select a company from the drop down list to allow access to the solution.

  • Role

    • If you would like to further restrict access to a solution, select a specific role for the company selected above.

  • User

    • If you would like to further restrict access to a solution, select a specific user for the company and role selected above.

• Assigned Permissions

  • View/delete assigned solution permissions.

Solution Categories

Add a new solution category

Actions

• Navigate to Solutions > Categories and select the Add New button.

• Complete the required fields and submit the form.

Fields

• Category Name

  • Enter a name for the solution category.

• Category Description

  • Enter a description for the category. Used on solution category pages.

• Category Image

  • Enter the filename of the image to use as the solution category image.

Edit an existing solution category

Actions

• Navigate to Solutions > Categories and select the solution category you would like to edit by clicking the Edit link to the right of the solution category name.

• Complete the required fields and submit the form.

NOTE: Setting a solution category to Inactive will result to hide all solutions assigned to it.

Fields

• See Fields from 8.4.1 above +

• Status

  • Set whether the solution category is active or inactive.

Solution Industries

Add a new solution Industry

Actions

• Navigate to Solutions > Industries and select the Add New button.

• Complete the required fields and submit the form.

Fields

• Industry Name

  • Enter a name for the solution industry.

• Industry Description

  • Enter a description for the industry. Used on solution category pages.

Edit an existing solution industry

Actions

• Navigate to Solutions > Industries and select the solution industry you would like to edit by clicking the Edit link to the right of the solution industry name.

• Complete the required fields and submit the form.

Fields

See Fields from 8.5.1 above +

Web Stats

View web stats

Actions

• Navigate to Web Stats.

• View user web stats in the table displayed.

  • Clicking on table rows will expand the data displayed for a user.

• You may add an alias for a specific entry to keep track.

• View User's Click Path displays individual pages which the user has visited.

  • Clicking on table rows will again expand the row and display more Geo IP information for the specific page which the user has visited.

Portal Settings

Edit portal settings

Actions