Parameters can be used to determine what is displayed in a window, report, or component, or how that object behaves. Ignition has built-in support for passing parameters into the client. This feature is extremely easy to set up and provides a lot of flexibility.
As an example, let’s say you have three identical machines with their own HMI (Ignition client). It would be best to create one project that is parameterized and uses indirection instead of creating three separate projects. You can pass in the machine name so the main screen points to the correct set of tags. That way, you also avoid having to put in a machine selector or a startup script to determine which machine to point to.
First, the parameters are passed into the client as “Client Tags”. Client tags, as the name implies, are only available for use in the clients and have a client scope. This means that their values are isolated to a client runtime. Even though they are created in the Designer, each client creates its own instances. This makes them very useful as in-project variables for passing information between screens and between other parts of the clients, such as scripting. A client tag can store this value for indirection and it can be used across multiple windows without users on different clients fighting over the current value as they would with a standard tag. This makes it perfect for creating parameterized windows.
Now that we have identified what we pass parameters into, let’s look at how we identify the parameters when opening the client. There are three ways to launch an Ignition client: Java Web Start, Native Client Launcher, and Mobile (HTML5 browser). All methods have the ability to pass parameters but the configuration is slightly different.
Java Web Start
Java Web Start (JWS) allows you to download and run the Ignition client/Designer from the Ignition Gateway. Clients can be launched in Windowed or Fullscreen mode from the Home page of the Gateway webpage.
The link downloads a JNLP file that is a known extension for JWS. When you open the JNLP file, the client will download and run. The launch button simply redirects to a project-specific launch URL. Every project has dedicated launch URLs for each mode:
Note: Replace the IP address with your internal IP address and “Demo”.jnlp with your project name.
Windowed Mode
http://[Your Internal IP Address]:8088/main/system/launch/client/[Project Name].jnlp
Fullscreen Mode
http://[Your Internal IP Address]:8088/main/system/launchfs/client/[Project Name].jnlp
We can add parameters, as GET parameters, to each URL that will be used to pass into the client, i.e.:
http://[Your Internal IP Address]:8088/main/system/launch/client/[Project Name].jnlp?machine=MachineA
It is very important that the GET parameter name matches the name of the client tag exactly, case matters. It is a good practice to avoid spaces in the parameter name and parameter value. If you have a space, make sure to properly escape that in the URL.
If you want to pass in more than one parameter, simply add multiple GET parameters to the URL. The example below passes into two parameters, “machine” and “param”:
http://[Your Internal IP Address]:8088/main/system/launch/client/[Project Name].jnlp?machine=MachineA¶m=Test
You can simply save the JNLP file on your desktop and use it again to launch the client with parameters.
Native Client Launcher
The Ignition Gateway contains downloadable native executables that can launch clients directly without invoking JWS. Using the native executables, you can set up clients in ways that are impossible to achieve with JWS, such as launching clients automatically as part of a machine startup script. It is a more robust shortcut than the default desktop shortcuts created by Java.
Native Client Launchers for Windows, Linux, and Mac OS X are available on the Gateway Home page. Click on the Download link to download the native launcher that you need for your operating system.
When the client launcher opens for the first time, you must select a Gateway on the Gateway Configuration screen. If you don’t see your Gateway, you can still manually enter the Gateway address under the Manually Input Gateway tab. The format is "host:port", i.e. localhost:8088. The client launcher will attempt to connect to the Gateway that you selected.
Once a Gateway is selected, you will see a list of projects. Make sure the “Create desktop icon” checkbox is selected and launch your project. A shortcut will get added to your desktop. We can easily modify the shortcut to pass parameters into the client by right-clicking on the shortcut and selecting Properties.
The shortcut’s default target looks like this:
"C:\Users\User\Downloads\Ignition Client Launcher\clientlauncher.exe" scope=C project=Demo windowmode=window gateway.addr=localhost:8088/main
Following along with the previous example of passing the machine name into the client, we can make the following changes to the target:
"C:\Users\User\Downloads\Ignition Client Launcher\clientlauncher.exe" scope=C project=Demo windowmode=window gateway.addr=localhost:8088/main -Djavaws.launchparams="machine" -Djavaws.launchparam.machine="MachineA"
If you need to pass in multiple parameters, do the following:
"C:\Users\User\Downloads\Ignition Client Launcher\clientlauncher.exe" scope=C project=Demo windowmode=window gateway.addr=localhost:8088/main -Djavaws.launchparams="machine;param" -Djavaws.launchparam.machine="MachineA" -Djavaws.launchparam.param="Test"
Again, it is very important for the launch parameter’s name to match the name of the client tag exactly, case matters.
The example above was from a Windows OS but the same techniques are applicable to Linux and Mac OS X. For more information on the Native Client Launchers, refer to our User Manual here.
Mobile Module (Using Browser)
The Mobile Module adds the ability to launch Vision Module projects on modern smartphones and tablets that don’t have support for Java. This module lets you keep track of your control system while moving around your facility.
Mobile clients run inside of the browser. To launch a project on a mobile device, you need to navigate your device’s browser to the mobile launch URL. You will find the direct mobile launch URL on the Home page of the Ignition Gateway.
Smartphones and tablets will automatically redirect to that URL when visiting the Gateway webpage. The URL looks like this:
http://localhost:8088/main/system/mobile
That URL will bring you to the Mobile Launch page, where you will see a listing of all projects. Each project has a direct URL as well:
http://localhost:8088/main/system/mobile?project=Demo
Note: Replace the IP address with your internal IP address and “Demo” with your project name. We can add parameters, as GET parameters, to each URL that will be used to pass into the client, i.e.:
http://[Your Internal IP Address]:8088/main/system/mobile?project=[Project Name]&machine=MachineA
Again, it is very important that the GET parameter name matches the name of the Client Tag exactly, case matters.
If you want to pass in more than one parameter simply add multiple GET parameters to the URL. The example below passes into two parameters, “machine” and “param”:
http://[Your Internal IP Address]:8088/main/system/mobile?project=[Project Name]&machine=MachineA¶m=Test
Summary
As you can see, it’s very easy to pass parameters into an Ignition client through all launch mechanisms. This feature provides a lot of flexibility but needs to be used wisely. Don’t use this feature to pass in user credentials or any sensitive data. We don’t want to open our client to any vulnerabilities or injection attacks. It is mainly used to provide context to the Ignition client.
Thanks, and I look forward sharing more Ignition tips with you here on the blog.
