PROVISIO DevBlog

The Powerful Run Executable Job Action Type of SiteRemote

An often overlooked action type of the SiteRemote job system (in your SiteRemote team choose SiteKiosk from the menu and then select the job tab) is one called Run Executable. It is a more general action type than most of the others but that is what makes it so powerful. What it allows you to do is to basically run any executable including the use of parameters.  

 

You can run Windows Powershell, batch files, (silent) installers, Windows system tools and so on. This allows you to administrate your SiteKiosk Windows machines in almost every possible way in addition to the SiteKiosk administration and monitoring the SiteRemote GUI already helps you with.

It is even possible to update SiteKiosk remotely with the help of the Run Executable job action type. Please contact our support for more information, because the exact method varies based on the SiteKiosk version in use.

This job action type runs on the client invisible with administrative privileges in the context of the Local System user or visible with the rights of the user that is logged in at the moment the job is executed.

If the executable you run provides a return value you can use that to show whether the job was successful or not on the SiteRemote job page. Not using this option will show the job as successful if starting the executable did not return an error.

A simple example that starts Notepad with the SiteKiosk license text would be this command line:

"c:\windows\notepad.exe" "c:\program files (x86)\SiteKiosk\license-en.txt"

If you then choose the option Visible execution with user rights, the job will start Notepad with the license text file on the SiteKiosk Windows machine, once the job has been assigned and ececuted on a client.

Please note that past DevBlog posts have described how to access 64-Bit system folders and registry paths (https://devblog.provisio.com/post/2015/11/03/Accessing-64-Bit-System-Folders-and-Registry-from-the-SiteRemote-Job-System.aspx) or how to unzip zip archives uploaded with a SiteRemote job step to a specific destination folder (https://devblog.provisio.com/post/2016/02/22/Distributing-the-SiteKiosk-Windows-Start-Screen-with-SiteRemote.aspx) all with the help of the Run Executable job action type.

Create a new project template from an existing project

It is possible to make existing SiteCaster projects in SiteCaster permanently available again as templates. This entry describes how to create a template from an existing project if you have an own server.

First you have to export the corresponding project:

1. Open the project in the editor and copy the project ID from the URL.

for example:

https://www.siteremote.net/sitecastercms/editor/assets/index.html#app-editor?projectId=5e7b5098415fcafc08348a01&variantId=5e7b5098415fcafc08348a03

2. Insert the project ID in the following line.

3. https://www.siteremote.net/sitecastercms/api/projects/5e7b5098415fcafc08348a01/export

4. Copy the URL

5. Open a new tab and paste the created export address – press Enter

6. Press Enter to download the zip file 

In the second part you have to modify the project folder and transfer it to a template folder:

1. Unpack the zip file.

2. Rename the content.json file located in the folder to content.original.json

3. Go to the following directory on the server:

C:\Program Files (x86)\PROVISIO\SiteRemote\Web.SiteCaster\server\projects\projectTemplates

4. Copy one of the existing template folders and paste it again.

5. Rename the folder (e.g. name of the template).

6. Replace the image file in the folder with an image file of your template, whereby the name preview must be retained and the file type has to be JPG.

7. Open the projectTemplate.manifest file in the folder with a text editor (e.g. Notepad)

8. Change the name of the template "name": "${string:StartScreenTemplate.name}", e.g. to "name": "TEST-Template”

9. Change the Project ID "projectID": "311f9e4eb2427f5ec02e32f1" in the file to create a unique new ID e.g. "projectID": "777f9e4eb2427f5ec02e32f1

10. Open the folder: 00000000000000000000

11. Delete the content of the folder

12. Add the complete content of the zip folder with the content.original.json file into the 00000000000000000000000000 folder

13. Open the SiteCaster Editor in a browser and click on the Create New Project button -> The new project template is now available

If you want to offer your template on your server in a team-specific manner, you must use the following path for the procedure described above:

C:\Program Files (x86)\SiteRemote\Common\Teams\teamStorage\<TeamId>\projectTemplates

The team ID specified in the path is individual per team and can be found on the server administration page in the tab teams.

Using tags to display variants of a SiteCaster project on different machines

If you want to display variants of a SiteCaster project that differ only in a few elements, you can use the tag feature in SiteCaster as a display condition.

In the following example, a SiteCaster project is published on two machines to display two variants of a project:

Log into your SiteRemote team and select the Monitoring tab. To generate tags for your machines, right click on a machine in the tree view and select Assign Tags.

 

Then enter the name of your tags e.g. Terminal 1 and Terminal 2 press Add and select it using the checkbox. Confirm the setting with Save.In SiteCaster, generate your sample project using the empty template. Use the Add button to add a swap container to the project. Insert two different images into the swap container. In order to use the Tag display condition, you will need to enable the expert mode in SiteCaster. To do so, you need to insert &expert at the end of the URL in the URL address field of your browser and then press Enter to reload the project. 

After activation of the expert mode you see the Expert Edit button in the tool bar.  

Then select one of the images and open the properties dialog by double-clicking on the image. Go to the section Display condition and select the Display under these conditions option. Activate the check box Tag and enter the tag name Terminal 1. Close the properties dialog with pressing the Save button. Activate the same setting on the other image with the tag name Terminal 2. After publishing the project to both clients the first image is displayed on the device with the tag Terminal 1 and the second image on the device with the tag Terminal 2. The described scenario can be extended with further tags as you like.   

How to Encrypt SiteRemote Server to SQL Server Connections

If you want to encrypt the connection between your SiteRemote Server and the Microsoft SQL Server hosting the database for SiteRemote, especially when using a remote Microsoft SQL Server, you can just enable forced encryption in the settings of your Microsoft SQL Server. This enables basic encryption between the two servers. To learn how you can enable encryption for your Microsoft SQL Server please refer to the documentation of the SQL Server provided by Microsoft.

The above enables encryption but does not protect from man-in-the-middle attacks on the connection. If you need this additional layer of security, configure your Microsoft SQL Server to use a certificate and make sure the machine running the SiteRemote Server trusts the certificate. Please refer to the SQL Server documentation provided by Microsoft for the SQL Server version you are using to configure this setup. Once this is done, you need to change the connection string used by SiteRemote to connect to the SQL Server. Note that this change can only be done after SiteRemote has been installed.

Open the file ..\PROVISIO\SiteRemote\Config\SiteRemoteServer.config from your SiteRemote installation folder with an editor and look for lines similar to this example:

<ConnectionStrings>
	<Add Name="default" Encrypted="true">
		<ConnectionString>Data Source=sql.server;Initial Catalog=SiteRemoteBackEndServer;User ID=sa;Password=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</ConnectionString>
	</Add>
</ConnectionStrings>

You need to add encrypt=true and trustServerCertificate=false (true would not validate the certificate) to the connection string. The above example would look like this with the additional settings added:

<ConnectionStrings>
	<Add Name="default" Encrypted="true">
		<ConnectionString>Data Source=sql.server;encrypt=true;trustServerCertificate=false;Initial Catalog=SiteRemoteBackEndServer;User ID=sa;Password=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</ConnectionString>
	</Add>
</ConnectionStrings>

Limiting the Color Mode for VNC Connections

Please note that the following text is an updated version of this older post. The update applies to SiteRemote 5.1 and above (including version 6.1, which is the current version at the time of writing this post).

SiteRemote uses the auto mode to set the colors for the VNC session. This usually provides the best experience. You may like or need to limit the color mode to 256 colors only when establishing the connection, mainly because of poor connection speed.

To switch from auto mode to 256 colors you need to edit a file on the PC you are establishing the connection from. On this PC you have installed the UVNC client for SiteRemote, it is usually located in the path C:\Program Files (x86)\PROVISIO\VncViewer\. There you can find the file options.vnc. Please open the file with an editor like Notepad. You will see that there is not much in it:

[connection]
index=

These lines need to be added to the file:

[options]
autoDetect=0
QuickOption=0

The complete file should now look like this:

[connection]
index=
[options]
autoDetect=0
QuickOption=0

Save the file under its original name. Next you need to right-click the file, choose Options -> Security and give the default Windows Users group read and write access to the file.

When you now start your next VNC session it will default to just 256 colors, therefore speeding up the view on a slow Internet connection.

Note that independent from this change you can always edit the options of a running VNC connection by clicking the Options button in the upper toolbar of the VNC window. This allows you to make one-time changes to the current connection.

Using the Expert Mode of the SiteCaster Editor

The SiteCaster Editor comes with an expert mode, that allows you to edit settings beyond their default value range. This gives you the opportunity to customize your projects to match very specific requirements. Feel free to experiment with this mode, but be aware that changing values beyond their default range is outside of the scope of our free support.

To enter the expert mode open a project to view the project page. Now click the address bar of your browser and append &expert to the URL. Make sure you place it at the very end of the URL and then press enter to open the expert mode.

Next select the element you want to customize. In our example we want to adjust the font size and the font family of the Time/Date element. To do that, click on the new advanced edit button you will see in the toolbar after entering the expert mode.

After clicking the button you will see a list of all properties of the selected element in the inspector. In the list you will find the dateFontFamily and dateFontSize properties. Use the drop-down of the dateFontFamily property to select String and type in the font family of your liking into the text field. For the dateFontSize property select Number from the dropdown and then type in the pixel value you want to choose. Click on the Save button after you are done to apply the changed values.

To give you an idea of the advanced possibilities you get from choosing the expert mode here is a view of the default options you have for the Time/Date element.

 As you can see the default element will cover the needs of most users but when using the expert mode you can change the properties to whatever you like.

SiteRemote-Controlled Alert System for SiteKiosk Windows

The kiosk management solution SiteRemote can be used to create an alert message system for kiosk systems running SiteKiosk Windows. An alert message will overlay the default SiteKiosk user inferface informing users of special events. Note that the solution described in this blog post is intended as a sort of emergency system. If you just want to show changing information you should consider using SiteCaster.

Two files are needed on the SiteKiosk terminal. One is a JavaScript file (named alertswitch.js in this example) the second is an HTML file (named alert.html in this example). Both should be placed in a folder called alert that should be placed in the HTML folder of the SiteKiosk installation path.

Let's start with the alertswitch.js JavaScript file. The code of the file is as follows:

//Periodic event to check alert conditions every 25 seconds
//The lower this value the harder to use the local SiteKiosk escape menu to close SiteKiosk
SiteKiosk.Scheduler.AddPeriodicEvent(25000, CheckAlertValue);

//Shell object used to read the registry
var WshShell = new ActiveXObject("WScript.Shell");

//Global variable for the event id of the periodic alert text check
var PeriodicEventID = 0;

//Alert dialog properties
var gk_Emergency = SiteKiosk.SiteKioskUI.CreateHTMLDialog();
//Path to the html file used for the alert
gk_Emergency.URL = "file://" + SiteKiosk.SiteKioskDirectory + "Html\\Alert\\Alert.html";
gk_Emergency.TopMostWindow = true;
gk_Emergency.Closable = false;
gk_Emergency.Title = false;
gk_Emergency.Border = false;
gk_Emergency.Scrollbars = false;
gk_Emergency.Sysmenu = false;
gk_Emergency.CloseOnInput = false;
gk_Emergency.OnClose = onClose;
gk_Emergency.Maximize();

function CheckAlertValue(){
	try{
		//Check registry value !NOTE! The following registry path is for 64-Bit systems!
		if (WshShell.RegRead("HKLM\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\AlertValue") !== ""){
			//Resets the screensaver idle timeout to make sure the screensaver is not interfering with the alert
			SiteKiosk.ScreenSaver.Reactivate();
			//Show the alert
			gk_Emergency.ShowDialog();
			//Force hiding of the task bar during the alert (Note: Not required when running SiteKiosk in full screen mode)
			SiteKiosk.SiteSkin.TaskbarVisible = false;
		}
		else{
			if (PeriodicEventID !== 0)
			//Remove the periodic event that checks for alert text changes	
				SiteKiosk.Scheduler.RemoveEvent(PeriodicEventID);
			
			//Show the taskbar again (Note: Not required when running SiteKiosk in full screen mode)
			SiteKiosk.SiteSkin.TaskbarVisible = true;
			
			//Close the alert
			gk_Emergency.CloseDialog();
		}
			
	}
	catch(e){
		//No matching registry value, do nothing
	}
}

//Return the registry value to the alert dialog on request
function GetRegistryValue(){
    return WshShell.RegRead("HKLM\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\AlertValue");
}

//Allow the alert to write the event id of the periodic event that checks for alert text changes
function SetPeriodicEventID(evtid){
    PeriodicEventID = evtid;
}

function onClose(){
	if (PeriodicEventID !== 0)
	//Remove the periodic event that checks for alert text changes because dialog has been closed from outside of the script
		SiteKiosk.Scheduler.RemoveEvent(PeriodicEventID);
}

The file must be added to SiteKiosk as an external script file. This can be done in the configuration of SiteKiosk under Start Page & Browser -> Advanced. The file uses the AddPeriodicEvent method of the SiteKiosk Object Model to periodically check a registry value (in our example HKLM\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\AlertValue). The registry value is either an empty string or contains the alert text that should be displayed. If the check does not return an empty string, the ShowDialog method is used to show the dialog defined with the CreateHTMLDialog method. One of the properties of the dialog is the path to the alert.html file explained below in this document. If the alert is shown the taskbar of SiteKiosk is switched off (only required if no full screen mode is used) using the TaskbarVisible property. Additionally the SiteKiosk screensaver will be prevented during the display of the alert to minimize any possible interference with the alert message, which is why the Reactivate method is used. Once an empty string is detected in the registry the alert is switched off by means of the CloseDialog method.

The external script also contains two methods to provide the HTML file that displays the actual alert with the alert message (GetRegisryValue method) and to receive the event id of the periodic event used in the HTML file to check for changes in the alert text. The id is used to stop the periodic event once the alert message is no longer displayed with the help of the RemoveEvent method.

The alert.html HTML file that accompanies the external script is used to display the alert message. You might change the design of that page to whatever you like. The code of the HTML file is as follows:

<!DOCTYPE html>
<html>
<meta charset="utf-8">
<head>
	<style> 
	html { 
		background: red no-repeat center fixed; 
		background-size: cover;
	}
	body { 
		font-family: arial;
		text-align:center;
		font-size: 100px;
		color: white; 
	}
	div {
		margin-top: 15%;
		padding: 20px;
	}
	</style>
	</head>
	<body style="margin:0px;"> 
		<div id="Alert-Text">
			... 
		</div>
	</body>
	<script type="text/JScript">
		//Initialize the SiteKiosk Object Model
		window.external.InitScriptInterface();
		
		//Get the alert text from the external script
		function GetAlertValue(){
			document.getElementById("Alert-Text").innerHTML = SiteKiosk.ScriptDispatch.GetRegistryValue();
		}
		
		GetAlertValue();
		//Check the alert text every 5 seconds for changes
		var evtid = SiteKiosk.Scheduler.AddPeriodicEvent(5000, GetAlertValue);
		//Write event id to external script to remove event when closing the alert
		SiteKiosk.ScriptDispatch.SetPeriodicEventID(evtid);
	</script>
</html>

After the initialization of the SiteKiosk Object Model the ScriptDispatch object is used to retrieve the alert message from the external script. The AddPeriodicEvent method is used to periodically request the alert message to quickly react to changes. The id for that event is passed to the external script so that the event can be canelled once the alert is closed.

Note that the times for the periodic events in the script can be changed to your liking and the requirements of your environment.

With the two files required on the SiteKiosk terminal in place we can now focus on the SiteRemote part. Obviously the SiteKiosk terminal needs to be registered with a SiteRemote server. Within your SiteRemote team go to the SiteKiosk tab and select Jobs. Scroll all the way down and select New template. For the alert system to work we need at least two templates. One that switches the alert on and one to switch it off. The template that switches the alert on includes the string for the alert message. In case you have different predefined alert messages that you want to display with the alert system based on different situations, you can create different templates for each of the messages.

The create an ON template provide a job name, select SiteKiosk Windows as client type and Execute Script as action type. Click Add next to the selected action type and paste the following script into the script field. Make sure that you do not select the option Script requires SiteKiosk Object:

//ON !NOTE! The following registry path is for 64-Bit systems!
var gk_WshShell = new ActiveXObject("WScript.Shell");
gk_WshShell.RegWrite("HKLM\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\AlertValue", "Alert Text", "REG_SZ");

This will write the string Alert Text to the registry of a SiteKiosk terminal the job will be assigned to. Change the string to whatever you like and make as many different ON templates as you require. Note that you can also change the text each time you assign the job template to a machine.

The OFF template simply writes an empty string to the terminal's registry:

//OFF !NOTE! The following registry path is for 64-Bit systems!
var gk_WshShell = new ActiveXObject("WScript.Shell");
gk_WshShell.RegWrite("HKLM\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\AlertValue", "", "REG_SZ");

Each time you want to activate or deactivate an alert on one machine or a number of machines click one of the templates and assign it. If you assign the ON template from this example to a machine that runs the required files described above you will get an alert like this:

Note that for the alert message to be displayed, SiteKiosk must be running, which is the normal state on a SiteKiosk kiosk terminal.

Using VNC Repeater Connection with SiteRemote Server Behind NAT Gateway

If you are using your SiteRemote Server behind a NAT gateway and you want to use the VNC Repeater Connection, you need to make a change to the Siteremoteserver.config file. Please note that this is only required when using the repeater connection, which uses the SiteRemote Server as a repeater, not when using the direct connection.

Open the file ..\PROVISIO\SiteRemote\Config\SiteRemoteServer.config with an editor like Notepad. And look for the line

<VNCRepeater.config Enabled="true" ViewerPort="5901" ServerPort="5500" MaxSessionCount="42" />

Now add the HostName parameter to that line that specifies the host name of the NAT gateway that will forward the repeater request to your SiteRemote Server. Please make sure that required ports are open and forwarded correctly.

The line should look like this, of course with your host name instead of siteremote.your-comp.com:

<VNCRepeater.config HostName="siteremote.your-comp.com" Enabled="true" ViewerPort="5901" ServerPort="5500" MaxSessionCount="42" />

You are now able to use a VNC repeater connection with your SiteRemote Server as the repeater behind a NAT gateway.

The above applies to SiteRemote Server 6.1 or higher.

Using the SiteKiosk Object Model in SiteCaster

The PROVISIO Developer Blog has many examples of how to use the SiteKiosk Object Model in the browsers of SiteKiosk Windows and SiteKiosk Android or as an external script in SiteKiosk Windows. This time we will look at a short example that shows you how to use the Object Model in SiteCaster as well.

Because SiteCaster is Chrome-based, it uses the new SiteKiosk Object Model for Chrome. This Object Model is still in the making, the most current state of the preliminary documentation can be obtained through our support department. Interested developers can just send us a short email.

The example code is for SiteKiosk Windows and will show you how you can start an external application from a SiteCaster element.

The first step is to create an html page that will open an application by using the SiteKiosk Object Model. The code for the simple test web page looks like this:

<!DOCTYPE html>
<html>
<head>
    <title></title>
	<script>
    //method to initialize the SK Object Model for SiteKiosk Windows (Chrome) and SiteKiosk Android
    (new Function(_siteKiosk.getSiteKioskObjectModelCode()))();
</script>
</head>
    <body style="margin:0px;text-align:center;background-color:#FFD932;">
        <input id="id_test" type="button" value="Test" style="margin-top:50px;" />
    </body>
    <script type="text/javascript">
        siteKiosk.ready(function (){
             document.getElementById("id_test").onclick = function () {dotest();};
             
            function dotest(){
                //will only work in SiteKiosk Windows and open the specified application
				siteKiosk.system.windows.skLegacy.externalApps.run("C:\\Program Files (x86)\\Notepad++\\notepad++.exe", false); 
            }
        }());
    </script>
</html>

You need to initialize the SiteKiosk Object Model by running _siteKiosk.getSiteKioskObjectModelCode(). The method siteKiosk.system.windows.skLegacy.externalApps.run(path,checkifalreadyrunning) will start the specified application. The first parameter is a string containing the path (and optional start parameters) to the local application on the machine SiteCaster is running on. The second parameter is a boolean value that specifies whether SiteKiosk should check if the application is alreay running or start additional instances. The page can either be stored locally on the machine where SiteCaster is running or on a web server. Either way, you need to make sure that the URL or path of the file has been added in the SiteCaster configuration of SiteKiosk as an URL with script permission.

The second step is to add the page to SiteCaster. Go to your SiteCaster team and either edit an existing project or create a new one. In this example I use the Start Screen template and add a new Webpage element to the left of the existing center elements.

Step three is publishing the project to the assigned machines where you can then push a button to start a local Windows application from SiteCaster.

Note that depending on the nature of the started application you might want to consider making additional configuration and/or script changes to handle closing the application or allowing/blocking certain dialogs of the application.

Using the Blackboard Information Page on a SiteRemote Server

NOTE: This only applies to customers running their own SiteRemote Server (5.2 and above).

The Blackboard is used by the SiteRemote Server and the SiteKiosk Windows and SiteKiosk Android clients to exchange some internal information. There have been two Developer Blog posts (SiteKiosk Windows, SiteKiosk Android) that have shown how this information can be used on a client with the help of the SiteKiosk Object Model. This post will show how to view all available Blackboard information of a single client machine by adding a page to the teams of a SiteRemote Server. This also enables you to easily search the Blackboard information.

Please be aware that the Blackboard information is limited in its use for purposes other than the internal processes of the SiteRemote server and client communication, under specific project circumstances the option to use it might still be very helpful.

To add the Blackboard page to teams on your SiteRemote Server version 6.1 or higher, go to the Settings page of the SiteRemote Server Administration and check the option Show Blackboard information page per machine and Blackboard machine list filter settings on Team settings page. Save the change. Note that in SiteRemote Server version 6.1 or higher, this will also provide you with the option to create your own machine list blackboard filters. Go to the Administration -> Settings page in a SiteRemote team and look for the Machine List Settings. There you can create machine list filters that search through the blackboard entries of machines.

To add the Blackboard page to teams on your SiteRemote Server version 5.2 to 6.0, you need to edit the file ..\PROVISIO\SiteRemote\Web\Web.sitemap. Open it with an editor and look for these lines:

<siteMapNode url="terminal/logs/view.aspx" title="$(String:683)" accesstype="LogFileTab" displayTreeView="true">
	<siteMapNode url="terminal/logs/createexport.aspx" displayTreeView="true"></siteMapNode>
</siteMapNode>

Add this new line directly after:

<siteMapNode url="terminal/blackboard/blackboard.aspx" title="Blackboard" accesstype="LogFileTab" displayTreeView="true"/>

Afterwards you should get this result:

<siteMapNode url="terminal/logs/view.aspx" title="$(String:683)" accesstype="LogFileTab" displayTreeView="true">
	<siteMapNode url="terminal/logs/createexport.aspx" displayTreeView="true"></siteMapNode>
</siteMapNode>
<siteMapNode url="terminal/blackboard/blackboard.aspx" title="Blackboard" accesstype="LogFileTab" displayTreeView="true"/>

If you now login to a team on your SiteRemote Server and select a machine from the treeview on the left, you will have a new Blackboard tab next to the Logfiles tab of that machine.

The page can slightly differ based on the available Blackboard information of that specific machine.

You can now also use the SiteRemote search feature to search the value fields of the Blackboard. To search through the Blackboard use the bs macro. Let's look at an example, the Blackboard contains the current SiteKiosk configuration of a machine in the key CtS.SiteRemote.Config.Files/d/SiteKiosk. If you now want to find all machines that use the www.your-comp.com URL as the start page, you would simply search vor bs:www.your-comp.com and the result lists all machines with that URL in the configuration.