PROVISIO DevBlog

Using the Windows Screen Saver to Show Digital Signage Content

Some of our customers have asked us, if they can use the Digital Signage solution that is part of SiteRemote without starting the SiteKiosk application on the client. Instead of SiteKiosk they had the Windows screen saver in mind. A scenario for this would be that a company wants to show non-critical internal information on the desktops of their employees, e.g. information about social events.

The simple answer is: yes, that is possible. Just install SiteKiosk Windows on the client PC and register it with your SiteRemote team. The SiteKiosk installation is required as it contains the Digital Signage and remote management elements required to place and monitor the content on the client PC. Note that you need a SiteRemote license but as long as you don't want to secure the PC by starting the SiteKiosk browser and only use Digital Signage for the Window screen saver you do not need a SiteKiosk license.

On the client computer you need to open the Windows screen saver management and select SiteCaster from the dropdown menu of available screen savers. Set the screen saver time to the desired value.

Under your SiteRemote team you can create the Digital Signage content as usual and then assign it to the registered clients. Every time the Windows screensaver starts, it will display your Digital Signage files.

Note that you can mix these client PCs with others on which you are using SiteKiosk to protect the computer, so you can effortlessly manage both from your SiteRemote team.

Using the System Team to Create System Job Templates on a SiteRemote Server

While using a SiteRemote team, either on www.siteremote.net or on your own SiteRemote Server, you may have noticed that you will see different types of job templates under the SiteKiosk -> Jobs tab. There are system and team job templates. By default only system job templates are available, team job templates are created by a user of a team and will be added to the list of available system templates.

The existing system templates cover a number of useful tasks and are the same for every team on a SiteRemote Server. They are included in the SiteRemote Server installer.

If you run your own SiteRemote Server with a Business Edition license, that allows you to create multiple teams, you can create system job templates yourself. This makes it easy to assign often used  job templates not only to one but all teams on your SiteRemote Server, without the hassle of creating the same job separately for each team.

Customers with a Personal Edition license can only use one other team besides the System Team, therefore it does not make sense for them to create system job templates.

System job templates are part of the System Team. To log in to the System Team on your SiteRemote Server go to the SiteRemote Server Administration website and select the Teams tab. First in the list on that page with an ID of 0 is the System Team. Under the Users column click on the Show link and on the following page use Impersonate for the SystemUser to enter the System Team.

After the log-in to the System Team go to the SiteKiosk -> Jobs tab and create a new job template. That process is the same as if you would create a new job template under a normal team and is described in the SiteRemote documentation here. After the template has been created and saved under the System Team it will automatically show up under all other teams on the same server as a new sytem job template.

Please note that creating a system job template is the only reason you should ever be required to login to the System Team. The System Team should not be used for any other purposes. It is required for general background tasks that are automatically conducted by the SiteRemote Server itself.

If you are a customer who is utilizing our SiteRemote Dedicated Server option you can contact PROVISIO so we can create a new system job template for you.

Different Ways to Create SiteKiosk Windows and Android Logfile Entries

SiteKiosk logfiles are text files that contain runtime information about SiteKiosk. The logs are stored on the SiteKiosk client by default. If a SiteKiosk client is registered with a SiteRemote Server the log information is also transferred to the server, where it is used for the remote monitoring and management features of SiteRemote. This applies to SiteKiosk Windows (information can be found here) as well as SiteKiosk Android (the logs are under SiteKiosk\Logs on the sdcard of the device).

Besides containing information about SiteKiosk the logs can also be used to include entries from a website or an external application. This way you could for example generate a custom alert on a SiteRemote Server.

There are different ways to create SiteKiosk log entries from an external source, depending on the client, Windows or Android, and the type of the external source, either html code running in the SiteKiosk browser or another application.

In html code you can use the SiteKiosk Object Model, which is available in a Windows version and one for Android (the Android documentation is not publicly available yet but a preliminary version can be obtained by contacting PROVISIO support).

Note that all html examples require that the pages using the code are allowed to use the SiteKiosk Object Model. In the SiteKiosk Windows configuration you can configure this option under Access/Security -> URLs with Script Permission. In SiteKiosk Android you will find the option under Application -> Browser -> Script Permission (if you use another application option the path will vary).

Our first example demonstrates how to write a log message from a web page running in SiteKiosk Android:

<html>
<head>
	<title></title>
	<script src="sitekiosk.min.js"></script>
</head>
	<body>
		<input id="id_write" type="button" value="Write SiteKiosk Android Log Entry" />
	</body>
	<script type="text/javascript">
		siteKiosk.ready(function (){
			document.getElementById("id_write").onclick = function () {writeLog();};
			
			function writeLog(){
				var lk_logfile = siteKiosk.log;
				lk_logfile.log(20,"TEST",0,"A test log message.");
			}
		}());
	</script>
</html>

The sitekiosk.min.js script file that is referenced in the above example can be obtained from PROVISIO support. If you are using SiteKiosk Android 2.4.118 you do not need the external script anymore, instead you can reference the internal script file that is included in the installation:

<script type="text/javascript" src="sk:///siteKiosk/siteKiosk.js"></script>

With the release of SiteKiosk Android 2.5 you have a third option to access the SiteKiosk Object Model, that does not require to link a script file at all:

<script>
	//method to initialize the SK Object Model as of SKA 2.5
	(new Function(_siteKiosk.getSiteKioskObjectModelCode()))();
</script>

The log method that is used to create the log entry has four parameters. The first is the log level, possible values are 0 (verbose), 10 (debug), 20 (info), 30 (warning) and 40 (error). Mostly you will work with either 10, 20 or 30. The second parameter is the facility that triggered the log message. For most log entries this is usually SiteKiosk. If you generate your own log entries you should use your own facility name, you can choose whatever name you want for it (though you should stick to a standard character set ;-)). The next parameter is the log type, you should either use 0, which stands for a generic log message, or choose one above 9000 as the rest is already used by SiteKiosk for internal log messages. The final parameter is the text string of the actual log entry.

The example for SiteKiosk Windows (see below for a script example for the new SiteKiosk Chrome Fullscreen Browser) is similar to the Android example with slight variations due to differences in the two SiteKiosk Object Model versions:

<html>
	<SCRIPT TYPE="text/javascript">
		window.external.InitScriptInterface();
		function WriteToLog()
		{
			SiteKiosk.Logfile.Write(9001,20,"TEST","A test log message.");
		}
	</SCRIPT>
	<body>
		<input type="button" value="WriteToLog" onclick="WriteToLog()">
	</body>
</html>

The method used here is named Write and expects the same parameters as the Android log method, allthough in a different order. Further information can be found here.

Next is a script example for the new SiteKiosk Chrome Fullscreen Browser (available since SiteKiosk 8.91). The Object Model for the Chrome-based SiteKiosk browser is still in the making, but you can already write log messages. As you may note, this script has a lot of similarities with the Android version:

<!DOCTYPE html>
<html>
<head>
	<title></title>
	<script type="text/javascript" src="file://C:/Program Files (x86)/SiteKiosk/SiteKioskNG/assets/siteKiosk/sitekiosk.js"></script>
</head>
	<body>
		<input id="id_note" type="button" value="note" />
		<input id="id_warn" type="button" value="warn" />
		<input id="id_error" type="button" value="error" />
	</body>
	<script type="text/javascript">
		siteKiosk.ready(function (){
			 document.getElementById("id_note").onclick = function () {writeLog('note');};
			 document.getElementById("id_warn").onclick = function () {writeLog('warn');};
			 document.getElementById("id_error").onclick = function () {writeLog('error');};
			
			function writeLog(caseid){
				var lk_logfile = siteKiosk.log;
				
				switch(caseid){
					case "note":
						lk_logfile.info("TEST",0,"A test notification.");
						break;
					case "warn":
						lk_logfile.warn("TEST",0,"A test warning.");
						break;
					case "error":
						lk_logfile.error("TEST",0,"A test error.");
						break;
					default:
						break;
				}
			}
		}());
	</script>
</html>

There are three different methods, info for informational messages, warn for warning messages and error for error messages. They all accept three parameters. The first is a string for the facility that triggered the log message. For most log entries this is usually SiteKiosk. If you generate your own log entries you should use your own facility name, you can choose whatever name you want for it (though you should stick to a standard character set ;-)). The next parameter is the log type, you should either use 0, which stands for a generic log message, or choose one above 9000 as the rest is already used by SiteKiosk for internal log messages. The final parameter is the text string of the actual log entry.

The SiteKiosk Object Model can also be used from other applications to generate log messages, e.g. applications written in C#. SiteKiosk must run in order for the other application to write to the log files and both applications must run under the same user. A C# example that writes to the SiteKiosk logs has a few more lines than the html versions:

using System;
using System.Collections.Generic;
using System.Text;
using System.Runtime.InteropServices;
using SiteKioskRuntimeLib;

namespace SKControl
{
    class Program
    {
        [DllImport("ole32.dll", CallingConvention = CallingConvention.StdCall)]
        public static extern int CoGetClassObject(ref Guid rclsid, uint dwClsContext, IntPtr pServerInfo, ref Guid riid, out IntPtr ppv);

        public bool IsSiteKioskActive()
        {

            /*
                returns false, if SiteKiosk is not currently running
                returns true, if SiteKiosk is running
            */


            // initialize GUID's for classes and interfaces
            Guid lr_FactoryGuid = typeof(ISiteKioskFactory).GUID;
            Guid lr_FactoryClass = typeof(SiteKioskFactoryClass).GUID;
            Guid lr_SiteKioskGuid = typeof(ISiteKiosk).GUID;

            ISiteKiosk mk_pSiteKiosk;

            // try to get the ISiteKioskFactory interface of the instance
            // of SiteKioskFactoryClass
            IntPtr lk_FactoryPtr = new IntPtr();
            CoGetClassObject(ref lr_FactoryClass, 4, new IntPtr(), ref lr_FactoryGuid, out lk_FactoryPtr);
            if (lk_FactoryPtr == IntPtr.Zero)
                // SiteKiosk is not running
                return false;

            // convert the received IntPtr to the requested ISiteKioskFactory
            // interface
            ISiteKioskFactory lk_Factory = (ISiteKioskFactory)Marshal.GetObjectForIUnknown(lk_FactoryPtr);

            if (lk_Factory == null)
                return false;

            // call CreateSiteKiosk to get the ISiteKiosk interface of the
            // current instance of SiteKiosk
            IntPtr lk_SiteKioskPtr = new IntPtr();
            lk_Factory.CreateSiteKiosk(ref lr_SiteKioskGuid, out lk_SiteKioskPtr);

            if (lk_SiteKioskPtr == IntPtr.Zero)
                return false;

            // convert the received IntPtr to the requested
            // ISiteKioskFactory interface
            mk_pSiteKiosk = (ISiteKiosk)Marshal.GetObjectForIUnknown(lk_SiteKioskPtr);

            if (mk_pSiteKiosk == null)
                return false;

            // write to the SiteKiosk log file
            ILogfile2 lk_SKLog = (ILogfile2)mk_pSiteKiosk.Logfile;
            lk_SKLog.Write(9001, 20, "TEST", "A test log message from an external application.");

            return true;
        }

        static void Main(string[] args)
        {
            bool lb_ReturnValue = false; //false if SiteKiosk is not running, true if SiteKiosk is running; not used in this example
            
            Program lk_Prog = new Program();
            lb_ReturnValue = lk_Prog.IsSiteKioskActive();
        }
    }
}

As the C# example is basically using the SiteKiosk Windows Object Model the syntax of the Write method is the same as if you would use it in html code. Make sure to read the part about using the SiteKiosk Object Model in C# from the SiteKiosk Object Model documentation. Running the example code from within Visual Studio while SiteKiosk is running and the debug output window is enabled (SiteKiosk Windows configuration -> Logfiles -> Show output window) will give you something like this:

Note that you may need to build your C# application for an x86 target platform rather than any cpu, otherwise it may fail to detect SiteKiosk on a 64-bit system, because SiteKiosk runs as a 32-bit application.

Using the Blackboard to Transfer Machine Information from SiteRemote to SiteKiosk Windows

A team on the remote management solution SiteRemote enables you to manage your SiteKiosk machines by assigning them to folders and tags. You can also assign address information like the location of the machine or the responsible maintenance person. This information can also come in handy on the client machines. For example you may use it to display different content based on the location address or the assignment to a specific folder or tag. This also means, that whenever you change this information on the server you can directly make use of that change on the client.

Let's find out how to get the information from the SiteRemote server. We will use the SiteKiosk Object Model inside an HTML page running in the SiteKiosk Windows browser. The SiteKiosk Object Model provides the ReadBlackboardAsString method. We will use that method to get the name of the SiteRemote team the machine is registered to, the SiteRemote display name of the machine, the folder and tags the machine is associated to and the address information assigned to the machine. For our example the setup lools like this:

The ReadBlackboardAsString method accepts a string as parameter that specifies the requested information (see the Remarks part here for further information) as shown in this example excerpt:

//Get the name of the SiteRemote team the machine is registered with.
document.getElementById("teamname").innerHTML = SiteRemotePlugin.ReadBlackboardAsString('StC.TeamInfo.Name');
//Get the display name of the machine in the SiteRemote team it is registered with.
document.getElementById("machinename").innerHTML = SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.Name');
//Get the folders and tags the machine is part of.
document.getElementById("groupstags").innerHTML = SplitBlackBoardStrings(SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.LocationInTreeview'));
//Get address information for the machine, e.g. location, maintenance contact.
document.getElementById("supportinfo").innerHTML = SplitBlackBoardStrings(SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.SupportInfo'));

The method returns a string with the SiteRemote blackboard information. Be aware that the string is in JSON format. You can either handle it as a normal string, just like in the above example, which is why the information for the group/tag membership and the address information is processed in an additional method (see the full example code below to see the code of that method) that splits the string at every comma. You can also work with the string in JSON format, for which you may need to add additonal script, see the Examples part here for more information.

The full example code we can build around the reading of the SiteRemote blackboard looks like this:

<html>
	<head>
		<title>SiteKiosk Blackboard Example</title>
		
		<style type="text/css">
			div { color:black; font-style:arial; font-size:18px; }
			span { color:red; font-style:arial; font-size:24px; }
		</style>

		<script type="text/javascript">
			window.external.InitScriptInterface();
			
			SiteRemotePlugin = SiteKiosk.Plugins("SiteRemote");
			
			//First check if the machine is registered with SiteRemote.
			if (SiteRemotePlugin.IsRegistered){
				//Registered. Trigger the initial blackboard request. Note: the first request will most likely come back empty.
				ReadSiteRemoteBlackboard();
			}
			else{
				//Not registered. Show message on screen.
				document.getElementById("registered").stlye.display = "none";
				document.getElementById("notregistered").stlye.display = "inline";
			}
			
			function ReadSiteRemoteBlackboard(){
				try{
					//Get the name of the SiteRemote team the machine is registered with.
					document.getElementById("teamname").innerHTML = SiteRemotePlugin.ReadBlackboardAsString('StC.TeamInfo.Name');
					//Get the display name of the machine in the SiteRemote team it is registered with.
					document.getElementById("machinename").innerHTML = SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.Name');
					//Get the folders and tags the machine is part of.
					document.getElementById("groupstags").innerHTML = SplitBlackBoardStrings(SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.LocationInTreeview'));
					//Get address information for the machine, e.g. location, maintenance contact.
					document.getElementById("supportinfo").innerHTML = SplitBlackBoardStrings(SiteRemotePlugin.ReadBlackboardAsString('StC.MachineInfo.SupportInfo'));
				}catch(e){
					//Blackboard information is not yet available, try again in 10 seconds.
					window.setTimeout("ReadSiteRemoteBlackboard()", 10000);
				}
			}
			
			function SplitBlackBoardStrings(blackboardstring){
				//Split the Blackboard string for better readability.
				var blackboardstringelements = blackboardstring.split(",");
				var composedelements = "";
				
				for (var i = 0; i < blackboardstringelements.length; i++){
					composedelements += blackboardstringelements[i] + "<br />";
				}
				
				return composedelements;
			}
		</script>
	</head>
	<body>
		<div id="registered" style="display:inline;">
			This machine is part of the SiteRemote Team <span id="teamname">[Information not yet available. Please wait.]</span> and 
			its display name on the SiteRemote server is <span id="machinename">[Information not yet available. Please wait.]</span>.
			<br /><br />
			The machine is assigned to the following groups and tags:
			<br />
			<span id="groupstags">[Information not yet available. Please wait.]</span>
			<br /><br />
			These addresses are available for the machine:
			<br />
			<span id="supportinfo">[Information not yet available. Please wait.]</span>
		</div>
		<div id="notregistered" style="display:none;">
			This machine is not registered with SiteRemote!
		</div>
	</body>
</html>

If you save the example code as an HTML page and place it in the html subfolder of your SiteKiosk installation and then configure SiteKiosk to use it as a start page you will get output similar to this:

Note that of course this requires that you register your SiteKiosk Windows client with a SiteRemote server and assign tags and address information to it. As you can see above the address information may include empty fields, if those values have not been provided when creating the address information. You can sort through those with standard Javascript string handling procedures.

For further reading you may want to have a look at the AttachBlackboardListener and DetachBlackboardListener methods, that will enable you to automatically and continously listen for changes to blackboard information on the SiteRemote server, so that the client can immediately react to those changes.

How to Use SiteRemote to License Your SiteKiosk Android Devices

Of course you can always apply your SiteKiosk Android license to each of your devices manually by using the configuration editor. But to spare you some repetitive work or even the trip to the device, you can easily use the Job feature of SiteRemote to remotely apply a license to your SiteKiosk Android devices. This can be a device that is previously not licensed or one that you want to change the license on.

Note that you need the SiteKiosk Android version you can get from our website and not the SiteKiosk Android Lite version from the Google Play Store.

First you have to login to your SiteRemote team. Then you select the SiteKiosk tab and choose Jobs from the submenu. On the next page you choose to create a new job. Make sure to use "SiteKiosk Android" as the client type and "Execute Script" as the action type. Choose the other options to your liking and then click on the Add button next to "Execute Script". Now add the following code lines as the script:

siteKiosk.license.registerLicense("AAAAA-BBBBB-CCCCC", function (data) {
    siteKiosk.siteRemote.scriptJob.finish(0, JSON.stringify(data));
});

Of course you need to replace AAAAA-BBBBB-CCCCC with the actual license code you received from PROVISIO. Make sure to enable the checkbox "Script requires SiteKiosk Object", otherwise the job will return an error.

In order for the client to use the license, SiteKiosk needs to be restarted. You can do this for example as a second job step by choosing the "SiteKiosk Command" option under action type and then select the Restart.

Finally assign the job to one or more devices you want to apply your SiteKiosk Android license to.

How to Create a Chromium-based Fullscreen Browser in SiteKiosk 8.9

In SiteKiosk 8.9 we introduced a Chromium-based browser engine for rendering content. In that version of SiteKiosk the engine is limited to the Start Screen start page skin. Full Chromium browser engine support is planed for SiteKiosk 9.0 coming in 2015, therefore the follwing instructions only apply to SiteKiosk 8.9.

Using Chromium will enhance the browser experience which is evident in the new Start Screen start page skin. With a few lines of code you can convert the Start Screen into a fullscreen browser to for example make use of the enhanced touch screen features for you own web page. This can be useful for an information or self-service kiosk terminal where no browser toolbar is required. Here are the required steps:

1) Install SiteKiosk 8.9.
2) Start the configuration editor and switch to the Start Page & Browser options.
3) Choose the new Start Screen and press the Customize button.
4) Open the configuration editor of the Start Screen from the next dialog.
5) Choose Template 3 in the dropdown at the top of the editor.
6) Click on the Settings button in the toolbar of the editor.
7) Switch to the Background page and select HTML instead of the default Video selection.
Add the following HTML code:

<script>
window.top.document.location = "http://www.google.de/";
</script>

The URL can of course be replaced by whatever you prefer. You may change the background color if you like at the top of the Background options page. Accept the changes by pressing the OK button.
8) Save the settings in the Start Screen editor.
9) Save the SiteKiosk configuration.
10) Start SiteKiosk.

Now your website is displayed in fullscreen mode in the new Chromium-based browser engine of SiteKiosk 8.9.

Please note the there are a number of limitations as the current use of the Chromium engine in SiteKiosk 8.9 is only intended for the Start Screen. For example there are no error pages if you surf to a non-existent page, you will then see just a blank page. So make sure you test this customization thoroughly in case you actually plan to deploy it.

How to Manually Map the File Manager Folder of SiteRemote in Your Windows Explorer

The File Manager of SiteRemote is also accessible via WebDAV. Usually you just need to download a JavaScript from the SiteRemote File Manager web page and then execute the script locally to map the file manager folder of your SiteRemote Team as a WebDav Network Drive into the Windows Explorer.

But if for any reason it is not possible to use the JavaScript option you can proceed as follows to manually map the file manager folder of SiteRemote in your Windows Explorer.

Please note: One reason you need to manually map the file manager folder is when you installed your SiteRemote server into a virtual directory of a web page. In that case the Javascript file you can download from the File Manager web page of your SiteRemote team cannot create the WebDAV mapping for you.

The following example demonstrates the manual mapping procedure under Windows 8, it is very similar on other Windows operating systems:

1. Open the Windows Explorer and press the button “Map network drive”.


2. Choose a drive letter that is not in use and add https://www.siteremote.net/TeamRoot (replace www.siteremote.net with the URL of any other SiteRemote server if you are not using the service provided by PROVISIO) to the input field “Folder”. Enable the checkbox “Connect using different credentials”.
If you want that the folder also will be reconnected after a Windows Reboot you can activate the checkbox “Reconnect at logon”.


3. After pressing the “Finish” button you will be prompted for a login.

4. Then you need to enter the user name and password of your SiteRemote user.
Optionally enable the checkbox “Remember my credentials” (e.g. if you also enabled “Reconnect at logon” before).


5. Finally the folder will be accessible through the Windows Explorer and you can use it like any other (Network) drive.

 

In case you want to disconnect the folder just right click on it in the Windows Explorer and choose “Disconnect” from the context menu.

Using SiteRemote to Change Windows Registry Settings

The SiteRemote job system enables you to make Windows registry changes on your SiteKiosk Windows clients that are registered with your team. This can be used for example to change a Windows setting remotely or add a registry key to make Windows or an application behave differently than before.

The registry changes can be made in Javascript using methods of the Windows Script Host. The scripts can be distributed to the clients by creating a SiteRemote job with the action type 'Execute Script'.

After you selected the 'Execute Script' action type you can copy and paste the following to the script text box:

var gk_WshShell = new ActiveXObject("WScript.Shell");
//Create a test registry key 
gk_WshShell.RegWrite("HKLM\\Software\\SiteRemoteTest\\Test", "SiteRemote generated this registry key for testing purposes", "REG_SZ");

For this example, make sure to not enable the option 'Script requires SiteKiosk Object' as we want to first write to the HKEY_LOCAL_MACHINE (HKLM) part of the registry. If you enable the option, the script is executed with the rights of the user SiteKiosk is running under at the time of the script execution. Depending on the user rights writing to HKLM might not be possible. With the option disabled the script is executed with the full rights of the Local System Windows user.

The result will look like this if you view it with the Windows Registry Editor:

Note that the example uses the Software path, which means that on a 64-Bit system the entry will automatically be created under Wow6432Node as the client application executing the code is running in 32-Bit mode.

If you use the next example script as part of a SiteRemote script job you would change the entry that has been created by the code above:

var gk_WshShell = new ActiveXObject("WScript.Shell");
//Change the test registry key
gk_WshShell.RegWrite("HKLM\\Software\\SiteRemoteTest\\Test", "SiteRemote changed this registry key for testing purposes", "REG_SZ");

The next example would delete the test entry that has been created in the Windows registry:

var gk_WshShell = new ActiveXObject("WScript.Shell");
//Delete the test registry key
gk_WshShell.RegDelete("HKLM\\Software\\SiteRemoteTest\\");

As mentioned above, if you want to write to the registry hive of the user you are running SiteKiosk under, at the moment the job is executed on the client computer, you need to activate the option 'Script requires SiteKiosk Object'. This is normally used for executing SiteKiosk Object Model code, but it also means that the code is not executed with the System user the job would otherwise be running under.

The following example will do the same as the first one with the exception that it will write the key to the registry hive of the user (HKEY_CURRENT_USER or HKCU):

var gk_WshShell = new ActiveXObject("WScript.Shell");
//Create a test registry key 
gk_WshShell.RegWrite("HKCU\\Software\\SiteRemoteTest\\Test", "SiteRemote generated this registry key for testing purposes", "REG_SZ");

If you use HKCU and do not activate the option 'Script requires SiteKiosk Object' the key will be written to the hive of the System user.

Note that contrary to the examples that did not have the checkbox for the SiteKiosk Object enabled this one creates the key directly under the Software path, even on a 64-Bit system, as the client application responsible for executing the code under these circumstances is running in native mode.

Changing Individual SiteKiosk Configuration Elements with a SiteRemote Job

Often you just need to change a single SiteKiosk configuration setting. Even when using a great number of SiteKiosk machines this is not a problem, you can just use the configuration feature of SiteRemote to distribute the changed configuration file to the machines.

But what if your machines all use configurations that differ in parts, for example the configurations are all using a different start page to reflect their individual locations while the rest of the settings are the same. This challenge can be solved by making use of the fact that the SiteKiosk configuration files are built on the XML format. This enables you to create a Javascript file that can access and edit a specific element of the configuration file.

The following script examples do not use the SiteKiosk Object Model. They use common Javascript/JScript techniques as described for example in the Microsoft MSDN library.

The first example will enable the fullscreen mode of SiteKiosk. The script starts by creating the required ActiveX objects to access the Windows registry and to edit an XML document. Next it queries the path of the latest SiteKiosk configuration file from the registry, either of a 32 or a 64 bit system. It then loads the document and assigns the XML node for the fullscreen setting and changes its text. Finally the edited configuration file is being saved. For further information on the methods to work with an XML document see http://msdn.microsoft.com/en-us/library/System.Xml.XmlDocument_methods%28v=vs.110%29.aspx.

try{
	//Wsh Shell Object
	var WshShell = new ActiveXObject("WScript.Shell");

	//XML support
	var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.3.0");

	//Path to the SiteKiosk configuration
	var OsType = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment\\PROCESSOR_ARCHITECTURE");
	if (OsType == "x86")
		var gstr_configpath = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\PROVISIO\\SiteKiosk\\LastCfg"); //you may use an absolute path instead, e.g.: var gstr_configpath = "c:\\program files\\sitekiosk\\config\\myconfig.skcfg"
	else
		var gstr_configpath = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\LastCfg"); //you may use an absolute path instead, e.g.: var gstr_configpath = "c:\\program files\\sitekiosk\\config\\myconfig.skcfg"

	if(xmlDoc.load(gstr_configpath)){
		var lk_nodeselection = xmlDoc.documentElement.selectSingleNode("//sitekiosk-configuration/browserbar/hidemode");
		//Changes the node text to 1 which enables permanent fullscreen mode (0 disables fullscreen, 2 enables fullscreen mode for specific URLs only).
		lk_nodeselection.text = "1";
		//Saves the  changes
		xmlDoc.save(gstr_configpath);
	}
	else{
		//Returns an error exit code to SiteRemote 
		ExitResult.Code = 1;
		ExitResult.Description = "Error opening configuration file.";
	}
}
catch(e){
	try	{
		if(e.number != 0)
			ExitResult.Code = e.number;
		else
			ExitResult.Code = 1;
		ExitResult.Description = e.description;
	}
	catch(e){}
}

After running the script the fullscreen setting of the SiteKiosk configuration looks like this:

The second example adds a URL excluded from filtering to the Content Filter of SiteKiosk. Again it starts by creating the required ActiveX objects and finding the path to the latest SiteKiosk configuration file. Next it adds a new XML node to an existing one for the URL that should be excluded from filtering. After that the document is being saved. For further information on the methods to work with an XML document see http://msdn.microsoft.com/en-us/library/System.Xml.XmlDocument_methods%28v=vs.110%29.aspx.

try{
	//Wsh Shell Object
	var WshShell = new ActiveXObject("WScript.Shell");

	//XML support
	var xmlDoc = new ActiveXObject("Msxml2.DOMDocument.3.0");

	//Path to the SiteKiosk configuration
	var OsType = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment\\PROCESSOR_ARCHITECTURE");
	if (OsType == "x86")
		var gstr_configpath = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\PROVISIO\\SiteKiosk\\LastCfg"); //you may use an absolute path instead, e.g.: var gstr_configpath = "c:\\program files\\sitekiosk\\config\\myconfig.skcfg"
	else
		var gstr_configpath = WshShell.RegRead("HKEY_LOCAL_MACHINE\\SOFTWARE\\Wow6432Node\\PROVISIO\\SiteKiosk\\LastCfg"); //you may use an absolute path instead, e.g.: var gstr_configpath = "c:\\program files\\sitekiosk\\config\\myconfig.skcfg"

	if (xmlDoc.load(gstr_configpath)){
		var lobj_snglnode = xmlDoc.selectSingleNode("//plugin[@name='SiteCoach']");
		var lobj_newelelement,lstr_newtext;
		lobj_newelelement=xmlDoc.createNode(1, "exclude", lobj_snglnode.namespaceURI);
		lstr_newtext=xmlDoc.createTextNode("http://www.provisio.com");
		lobj_newelelement.appendChild(lstr_newtext);
		lobj_snglnode.appendChild(lobj_newelelement);
		//Saves the  changes
		xmlDoc.save(gstr_configpath);
	}
	else{
		//Returns an error exit code to SiteRemote 
		ExitResult.Code = 1;
		ExitResult.Description = "Error opening configuration file.";
	}
}
catch(e){
	try	{
		if(e.number != 0)
			ExitResult.Code = e.number;
		else
			ExitResult.Code = 1;
		ExitResult.Description = e.description;
	}
	catch(e){}
}

After running the script the Content Filter page of the SiteKiosk configuration looks like this:

To run such a script just go to the Jobs section of SiteRemote and create a new job and select Execute Script as action. Copy and paste the code into the text field and assign the job. Do not activate the checkbox Script requires SiteKiosk Object, as it would run the script within the SiteKiosk user context, who for security reasons does not have the necessary rights to edit the configuration.

Note that you should make changes to the configuration file with care and test them first before applying to a great number of terminals. E.g. writing XML incompatible values to the configuration will make the file unreadable, so SiteKiosk will then load the emergency configuration file instead.

In order to let the new configuration file become the active configuration you need to restart SiteKiosk.

LDAP User Mapping in SiteRemote

Note: The following applies to the current release version 5.1.0.2188 and above. For compatibility reasons with OpenLDAP the syntax of the user.config section has been changed from the original release version 5.1.0.2186. The old syntax is no longer supported.

With SiteRemote Server 5.1 we introduced LDAP user mapping for customers running their own SiteRemote server. Now you can use user credentials provided by the directory service of your company's domain (q.v. Active Directory) for authentication in SiteRemote.

LDAP users and normal SiteRemote team users can be used together. At least one SiteRemote team user is required for each team you want to map LDAP users to.

Before you can map LDAP users to SiteRemote you need to create at least one team. You can do that for example on the Teams tab of the SiteRemote Server Administration. Note that while creating the team you need to specify a user, this user must not be an LDAP user but a normal SiteRemote Team user. This is the user responsible for a team and it cannot be deleted when logged in with an LDAP user. You can only delete this user from another SiteRemote team user account within a team (Note: it is planned for future SiteRemote versions to make the primary administration user permanent, so this behaviour might change).

After the team creation you can proceed to prepare your SiteRemote server to use LDAP authentication. You now need to manually edit the configuration file of the server. You will find the SiteRemoteServer.config file under ..\PROVISIO\SiteRemote\Config. Open it with an editor like Notepad and scroll down to the bottom. There you need to change the default User.config section right before the closing configuration tag:

<User.config LdapServerPort="0" LdapSecureSocketLayer="false" />

to something like this:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
	...
	
	...
	<SiteCaster.config VideoAudioAnalyzerPath="VideoAudioAnalyzer.exe" />
	<User.config>
		<LdapImportFullFilePath>c:\ldapuserlist.csv</LdapImportFullFilePath>
		<LdapServerHost>ldapserver.yourdomain.biz</LdapServerHost>
		<LdapServerPort>389</LdapServerPort>
		<LdapSecureSocketLayer>false</LdapSecureSocketLayer>
		<LdapUserPatterns>yourcompany\{0}</LdapUserPatterns>
	</User.config>
</Configuration>

The User.config section is the parent element for all LDAP related child elements in the SiteRemote configuration.

The LdapImportFullFilePath element must include the full path to the .csv file that includes the domain users you want to map to SiteRemote. More on that file a little later.

LdapServerHost includes the full host name of your LDAP server, you may also use an IP adress.

LdapServerPort specifies the port your LDAP server uses. The default LDAP port is 389 or 636 if using an SSL connection.

LdapSecureSocketLayer is a boolean value. It is true if the server uses SSL.

LdapUserPatterns defines the way SiteRemote queries the user with the LDAP server. There are three supported principal forms: LDAP DN, Kerberos and NTLM. Note that these forms cannot be mixed. {0} is a required part of the pattern and is replaced by SiteRemote to include the user name that is authenticated with the LDAP server. The same user data is also used to perform the LDAP request.
LDAP DN uses the LDAP distinguished name syntax. This is used for example in OpenLDAP installations like Novell eDirectory.

<LdapUserPatterns>cn={0},ou=users,ou=us,o=yourcompany</LdapUserPatterns>

Because that syntax is very specific in regards to the location that is queried within the LDAP structure, you can add more than one pattern. The patterns must be seperated by a semicolon.

<LdapUserPatterns>cn={0},ou=users,ou=california,ou=us,o=yourcompany;cn={0},ou=users,ou=de,o=yourcompany;cn={0},ou=users,ou=gb,o=yourcompany;</LdapUserPatterns>

Kerberos authentication is usually used in Windows Active Directory. This syntax does not require different patterns as it queries the complete LDAP tree.

<LdapUserPatterns>{0}@yourcompany.biz</LdapUserPatterns>

NTLM authentication is also commonly used in Windows Active Directory. This syntax does not require different patterns as it queries the complete LDAP tree.

<LdapUserPatterns>yourcompany\{0}</LdapUserPatterns>

Here is another full example that uses SSL and LDAP DN:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
	...
	
	...
	<SiteCaster.config VideoAudioAnalyzerPath="VideoAudioAnalyzer.exe" />
	<User.config>
		<LdapImportFullFilePath>c:\ldapuserlist.csv</LdapImportFullFilePath>
		<LdapServerHost>ldapserver.yourdomain.biz</LdapServerHost>
		<LdapServerPort>636</LdapServerPort>
		<LdapSecureSocketLayer>true</LdapSecureSocketLayer>
		<LdapUserPatterns>cn={0},ou=users,ou=california,ou=us,o=yourcompany;cn={0},ou=users,ou=de,o=yourcompany</LdapUserPatterns>
	</User.config>
</Configuration>

After making and saving the changes to the SiteRemoteServer.config file you need to restart the SiteRemote Server service in the Microsoft Management Console for Windows Services (services.msc).

Now its time to create and place the .csv file with your LDAP user list at the location you specified in the SiteRemote configuration file. Note that the file only needs to contain the LDAP users you actually want to use with SiteRemote and not all LDAP users in your domain. Each line of the .csv file represents one LDAP user. The syntax is as follows:

[<oldusername>],<username>,<team>,<role(s)>,[<group(s)>]

oldusername is optional and required if you want to rename a user and keep this user's assignments within a SiteRemote team. This can be useful due to a name change because of marriage for example. oldusername then specifies the existing name of the user and username would contain the new one. Providing a name in this field is optional, if you don't provide a name you still need to write the comma to separate this field from the next. Note that user names must be unique, each user name can only be used once.

username specifies the name of the user. This field is required. Note that user names must be unique, each user name can only be used once.

team specifies the SiteRemote team name you want to assign the user to. This field is required.

role(s) (optional since SiteRemote Server 5.2 or higher) specifies the role or roles that you want to assign to the user. The role names of the default roles are language specific and depend on the language that was assigned at the time the team was created. For example the default roles for English are Administrator, User and Guest, in German they are Administrator, Benutzer and Gast. Other roles can be created and individually named in a SiteRemote team under Administration -> User Roles. If you want to assign more than one role you need to use quotation marks and separate each role by a comma.

group(s) is optional and only available with SiteRemote Server 5.2 or higher. You can assign LDAP users to groups you have created. If you want to assign more than one group you need to use quotation marks and separate each group by a comma. Note that each user will be automatically assigned to the Everyone group of a SiteRemote team.

Generally quotation marks are recommended to be used for each field. Here is an example of how the file can look like:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser3","team2","Administrator"
,"LDAPuser4","team2","User,Team2Role1,Team2Role2"
"LDAPuser5","LDAPuser7","team2","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

Note that the empty lines between the teams are not required, yet they can be used to better visualize assignments for different teams.

Each time you edit and save the .csv file or overwrite the existing file with a new one, the changes are applied.

To remove a user, simply delete the line from the .csv file and save it. The following would remove LDAPuser4 from team2:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser3","team2","Administrator"
,"LDAPuser7","team2","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

To remove all LDAP users from a team, just remove them all from the file. Placing an empty file will remove all LDAP users from all teams. The next example will remove all LDAP users from team2:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

In case you want to assign a group but no role, the line would look like this:

,"LDAPuser6","team3",,"Admin Group"

Status messages regarding the processing of the file can be found in the SiteRemote server log file. The file SiteRemote.log can be found under ..\PROVISIO\SiteRemote\Log.

For full functionality the LDAP user authentication requires SiteKiosk Android 2.2 or higher or SiteKiosk Windows 8.9 or higher. Older versions cannot be registered with the SiteRemote server using an LDAP user.

In case you are using the TerminalCommander tool please make sure you are using the version that comes with SiteRemote Server 5.1 or higher.

Please note that the AutoRegister tool does not support LDAP users due to technical limitations.