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> start <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.




It is possible to use another triggers (instead or with log on with any user) to run batch file and start scenario. For example, this condition monitors Polywall Server service state and trigger the launching operation when this service stops or starts. 

Please note that 7036 events are disabled in Windows 8 and 10 and there are no known ways to turn them on!


Go to 'Triggers' tab and press 'new' to add a launch condition. Select 'On an event' in the 'Begin task:' list, select 'custom' radiobox below and press 'New Event Filter' button. In the appeared window select 'XML' tab, mark the 'Edit query manually' checkbox, paste the trigger condition (see below) and press OK.

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">
      *[System[(EventID='7036')]]
      and
      *[EventData[Data[@Name='param1'] and (Data='Apache Tomcat PolyWallServer')]]
    </Select>
  </Query>
</QueryList>


The code above is an XML query for Windows event viewer allowing to filter the exact system event. Refer the Microsoft Technet article for some insights on how to use it.  Basically we set two conditions in this XML query: a system event 7036, which is a service entering running or stopped state and the exact service name, which is 'Apache Tomcat PolyWallServer'. You may note that the event 7036 will trigger both on starting and stopping the service, though it is not a problem in our case. It is possible to filter only start event, but the implementation of Windows event logging is language specific, and is skipped in this tutorial for better compatibility with different system language locales.





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.


  1. Download attached zip archive with Polywall API client and batch file example and unzip all files to some folder. For example, C:/pwapiclient/.
  2. Run Windows Task Scheduler, go to Task Scheduler library and create a new task.
  3. Set task name - Start Polywall Scenario.
  4. Set parameter "Run with highest privileges.
  5. Go to Triggers tab and create a trigger to begin the task at log on of any user.
  6. Set a delay 30 seconds for the trigger.
  7. Go to Actions tab and create an action to start a program. Choose batch file from C:/pwapiclient/.
  8. Save the task and check the operability.