Overview
The standard way to launch a scenario in Polywall is using the Designer interface. Although sometimes it is necessary to launch a scenario at some specific moment, typically at Server startup (i. e. after Windows boot and logging into Windows user account). This article provides a step-by-step guide for launching Polywall scenarios on Server startup. It can also be useful as a general tutorial on how to configure various complex Polywall launching scenarios.
We recommend to inspect all information in the article, but quick step by step guide with the example is available in the end of this article. Use it if you are running out of time.
The Polywall API client
The pivotal element in launching Polywall scenarios is Polywall API - a protocol, which provides interaction with Polywall Server via TCP connection. The full API description is available in the API documentation. The API can be accessed using terminal, though it is not always convenient. A more convenient way is using Polywall API client, a command-line utility, providing an interface to Polywall API. The documentation for API client is accessible via command line. Type pwapiclient --help in command line to see the documentation and all the options provided. It is also included for reference below.
The Task Scheduler
The Task Scheduler is a standard Microsoft Windows component, which provides an ability to launch programs at predefined events or moments of time. Refer the Microsoft web site for documentation and guides. The easiest way to launch Task Scheduler is to run Taskschd.msc in command line. In this tutorial we are going to to create a task on the event of Polywall Server component start or restart.
Creating a launch batch
This section describes how to create a windows batch for launching a Polywall scenario. Basically to launch a scenario it is enough just to type a command:
pwapiclient -s=<server name or ip> play <scenario name>
This will work fine when the server is already started and is working in normal state. The pitfall is that as Polywall is a complex multi-threading and distributed system, it has to get in to a steady state: all the processes and initializing routines have to start working properly and it takes some time. To get a stable launching scenario right on server startup it is necessary to do some checks and force initializings. The easiest way to do that is creating a batch. It can be named e.g. pwlaunch.bat. To create it open a notepad and create a file pwlaunch.bat with following contents:
@echo off cd C:\pwapiclient ::set scenario name here: set scenario="MyScenarioTitle" ::check if Polywall is running tasklist /FI "SERVICES eq PolyWallServer" 2>NUL | find /I /N "tomcat7">NUL if not "%ERRORLEVEL%" == "0" goto :eof ::force init pwapiclient -s=localhost -v -t=1 api "xStatus Scenarios" ::launch scenario pwapiclient -s=localhost -v -t=1 play %scenario% >log.txt 2>&1
Place the created pwlaunch.bat to the same folder where pwapiclient.exe is located.
Below is the explanation on this script. You can skip it if you don't want to go in detail, but note though, that you need to substitute "a" in the third line of the code above for your scenario name.
The strings starting with :: are just comments and are ignored by command line interpreter, they are left just for convenience.
Before we start to run command, we need to go to the folder where pwapiclient is located. For that we use command cd C:\pwapiclient. Of course, this will work in the case where pwapiclient is in this folder on drive C.
At first we create a system variable 'scenario' with a scenario name. It is named "MyScenarioTitle" in the example above and has to be exact as the real scenario name without .zip extension (zip archives are in c:/polywall/hall folder, in Designer all scenario titles are shown without zip extenstion). The system variable is made for convenience and this is the only place, where scenario title must be defined. All commands below do not require any changes.
Then we have to check whether Polywall server is running:
tasklist /FI "SERVICES eq PolyWallServer" 2>NUL | find /I /N "tomcat7">NUL
if not "%ERRORLEVEL%" == "0" goto :eof
The above code performs such a check and the batch script terminates with a non-zero error level if it is not. Thus, if Polywall Server service is not running, the batch file will not proceed and will be terminated.
The next step is to force Polywall initialization. We just issue some API Status command to do that:
pwapiclient -s=localhost -v -t=1 api "xStatus Scenarios"
Note, that we use 'localhost' as server name, as we are going to launch the batch at Server directly.
And finally we launch a scenario with
pwapiclient -s=localhost -v -t=1 play %scenario% >log.txt 2>&1
Where %scenario% is a variable with scenario name defined above while logs and errors redirected to log.txt file for future convenience if something goes wrong. The variable %scenario% has not need to be replaced by real scenario title. The title is defiled earlier.
Creating a scheduled task
Once the batch is ready we have to tell the Task Scheduler to launch it every time Polywall starts. The easiest way is to schedule the above pwlaunch.bat on system logon, though in this tutorial we are going to fulfill a more complex task: launch a scenario every time server process restarts, including the first system startup without the need for a logon event, allowing a silent scenario start without any user interaction.
- Launch task scheduler, e.g. by typing Taskschd.msc in console.
- Create a task by selecting Action / Create Task from menu.
- Give a name to a task, let it be "Start Polywall scenario".
- Now we have to set the trigger to launch the batch script every time user log on. The task must be run when user is logged on only and with highest privileges.
- The useful notice: if scenario playing command will be sent without logon, so Visualizer will not be running, Polywall Server will accept the command nonetheless and scenario will start playing technically inside Server component. Content from scenes will not appear on the video wall, because Visualizer is off, but all scenes will rotate. If we will perform logon and start Visualizer, the content will appear not immediately, but when new scene time comes and it opens new content - the same logic as when we reboot server with an active scenario.
- Now go to Triggers tab and add new trigger with the conditions begin the task at log on with any user, tick the checkbox for the delay and make it 30 seconds. Delay is necessary and ensures that Polywall Server and Visualizer will have enough time to start. Do not forget about checkbox in the end called "Enabled". It must be ticked as well.
- Switch to Actions tab and press 'New' to enter the actual program to be run on the event we described previously. Enter the full path to pwlaunch.bat created above in 'Program/script' field and press OK twice.
- The configuring is completed. Check the result.
Polywall API client command reference
usage: pwapiclient [-h] -s SERVER [-p PORT] [-v] [-t TIMEOUT] [-w WAIT]
[play|scene|stop|listen|api] ...
arguments:
-h, --help show help message and exit
-s SERVER, --server SERVER
Server ip/hostname
-p PORT, --port PORT Server port, default is 9999
-v, --verbose be verbose. Useful for troubleshooting
-t TIMEOUT, --timeout TIMEOUT
timeout for initial connection in seconds, default is
1 second
-w WAIT, --wait WAIT time to wait for response from server, default is 1
second.
commands:
[play|scene|stop|listen|api]
type pwapiclient <command> -h for command help
play NAME play scenario
scene NAME play scene
stop stop scenario
listen listen to server output. Press Ctrl+C to interrupt
api COMMAND send arbitrary api command to server
examples:
pwapiclient -s=localhost play MyScenario
play MyScenario at local server
pwapiclient -s 1.2.3.4 stop
stop current scenario at server 1.2.3.4
pwapiclient -s=example.com -p=5555 -v api "xCommand Scenarios Stop"
launch command "xCommand Scenarios Stop"
at example.com:5555 in verbose mode
pwapiclient --server localhost listen
listen to server at localhost
Quick guide with the example.
We need to launch scenario named "Myscenario1" at every Windows boot.
- Download attached zip archive with Polywall API client and batch file example and unzip all files to some folder. For example, C:/pwapiclient/.
- Run Windows Task Scheduler, go to Task Scheduler library and create a new task.
- Set task name - Start Polywall Scenario.
- Set parameter "Run with highest privileges.
- Set a delay 30 seconds for the trigger.
- Go to Actions tab and create an action to start a program. Choose batch file from C:/pwapiclient/.
- Save the task and check the operability.