Citrix XenApp and XenDesktop session scripting

You can use FastTrack custom scripts in the Script Editor to query information about the executing Citrix Receiver client from the server-side, such as the client name and IP address. You can use a simple condition to detect, if a script is currently executing in an ICA session and take different actions based on this condition. This is also built into the Logon Script Wizard, where the client IP address can be used to make correct printer mappings.

From the client side, you can query version information and installation status of Citrix Receiver (formerly ICA Client) and you can start and control a desktop session, a XenApp application session or you can start a custom built .ica file. This enables you to create launch menus, which can be a mix of ICA sessions, RDP sessions and locally installed applications. Such menus can be useful for building application launchers or Thin PCs.

Make sure to also check out the RDS Session Terminator Application, which compiles a script into to an exe file that can logoff disconnected users by a Help Desk without administrative permissions.

Citrix session scripting

Citrix sessions from the server-side

Citrix XenApp Server menu When you use FastTrack scripts on the server-side, for example for Logon Scripts or application launchers, you can get the name and IP address of the remote client, the name of the executing XenApp application (if not a full XenApp or XenDesktop desktop session) and you can detect, if the script is actually running through a Citrix ICA session or not. This is extremely powerful information to have, because this means that you can differentiate your logon script and avoid unintended execution for remote users.

If you look under "Citrix Server" in the Engine Browser tree (see picture to the right) in the editor, you will see that "RemoteSession", "ClientName", "ClientIP" and "ClientIPPart" are also present under "Remote Desktop Services Server". This is because the intention is to provide transparency between ICA and RDP sessions with FastTrack scripts, because the logic wanted is in most cases the same for both and common functions and conditions will therefore result in much shorter scripts.

The ClientName function will return the name of the client executing the session regardless of ICA or RDP, whereas IcaClientName and RdpClientName will only work for one technology. The reason both are available is because "ClientName" makes sense in most cases and especially in common scripts like logon scripts; but for application launchers or similar, scripts are more readable, when using an explicit function like IcaClientName.

The condition "RemoteSession" determines, if the executing script is running under an ICA or RDP session. If you want separate logic, there are two split conditions called "IcaSession" and "RdpSession" to determine, which is true, if any. In the simplest form, you can use the information to stop a logon script on ICA and RDP sessions:

If RemoteSession Then Exit

Some of these features, including the RemoteSession check, are also used by the Logon Script Wizard that can check for Citrix Receiver installation status and launch conditions. The Logon Script Builder is essentially just a script generator.

Home Screen Logon Script General Settings

Using the client name in a custom script

Another example is that the we can use the client name to determine, if the computer running the session is a computer in the domain or not, as part of a logon script. We can do this by asking the Active Directory, if a computer account exists with the same name and then we can react to this. In the example below, we kindly remind the user that the Codes of Conduct for use of remote sessions applies and then we log the information to the server event log. We could have taken more severe steps, such as simply logging off the session or we could also just log the information server-side.

If RemoteSession Then

  If Not ComputerExists [ClientName] Then

    LogEvent Remote Logon,External logon by [UserName] from client named [ClientName] from [ClientIP].

    ShowMessage You are connecting to the network from an external computer. Remember that codes of conduct applies!

  End If

End If

When an unknown client is detected, the warning is shown (see below) and an entry is logged in the server's event log.

Citrix remote warning

Citrix event logging

Note that the client name may be mapped to a generated client name, when running a session through a web interface. This is a configurable behavior; please refer to CTX111851 here for more information.


Determining client location

You can also retrieve the IP address of the executing client. This information is especially useful for connecting printers and shares. If you look at the Logon Script examples, you will find examples, where location is determined by the IP address. When using the IPAddress or IPAddressPart functions, these return the IP address of the physical machine. When using remote session, we want to do the same, but we want to do it based on the IP address of the executing client. To solve this problem, we can simply use the ClientIP and ClientIPPart functions instead. These will first try to detect an ICA or RDP session and return the client IP address. If the session is not a remote session at all, the IP address of the physical machine is returned. The net result is that we can in general simply replace the functions and they will work as intended in all scenarios.

Citrix client

You can from the client-side use FastTrack scripts to query information about the installed version of Citrix Receiver. You can also start and control Citrix Receiver desktop and application sessions, the same way that you can do with Remote Desktop sessions. Please have a look under "Citrix Client" in the Engine Browser tree in the editor (see picture to the right).

Using installed Citrix Receiver information

Citrix Reciever client menu In the simplest form, you can use the information to pause a logon script and warn the user that he or she will not be able to execute ICA sessions at all:

If Not IcaClientInstalled Then

  ShowErrorMessage You do not have Citrix Receiver installed. Contact HelpDesk.

End If

You can also use the installed Citrix Receiver version information to warn about obsolete ICA client support after server upgrades.

An example of using the client version information as part of a logon script to check and warn the user about older versions could look like this:

If Not IcaClientInstalled Then

  ShowErrorMessage You do not have Citrix Receiver installed. Contact HelpDesk.


  If [IcaClientVersionMajor]<13 Then

    ShowErrorMessage You have an old version of Receiver installed. Contact HelpDesk.

  End If

End If

If the end user has a version older than version 13.x, a warning is shown that the user must contact the HelpDesk like the one below.

Citrix Menu

Citrix Receiver was formerly known as Citrix ICA Client and the versioning is kept across name changes. Citrix Receiver 3.2 is therefore the ICA client version 13.2, Citrix Receiver 2.0 is ICA client version 12.0, etc.

Citrix sessions from the client-side

You can start ICA desktop and application sessions and you can query status information, when the session has ended. You can for example use this to build launch menus mixed between local applications and Remote Desktop and XenApp sessions. Have a look at the building a Thin PC page for an example of using a menu instead of starting Explorer.exe as the shell process.

The are two commands to start a published application (which can also be a published desktop) and it is important to understand the difference. Let's look at how a session is normally established:

Citrix webinterface

The user logs on to the web interface, which serves a list of applications available to the user. The web interface asks the XML Broker for the application list and it also asks the XML Broker to select the server that has the least load to host the session. The RunIcaApp command does the same thing, but without the web interface. So basically you can script your way around the web interface and you can specify credentials when using the command.

The RunIcaAppDirect command will bypass the XML Broker and start a session on a specific server directly and is therefore typically only useful for administrators. In small environments with only one server, the XML Broker and XenApp server are one and the same, but it it still best practice to use the RunIcaApp command in case there will be more servers at a later date.

Observe that the ShowIcaDesktop and ShowFullIcaDesktop commands are not for published desktops, but for direct access to a specific server. To access a published desktop from any server, the RunIcaApp must be used and pointed to a published desktop. In case of published desktops, the DisableSeamlessIcaMode should be called first to avoid a seamless session.

There are collections available to get information from the XML Broker. The IcaApplications collection will return a list of available applications, which is the same list the web interface would serve. So we could build our own menu to ask the user to select an application and start a session based on the choice. The below in an example of these, where the XML Broker has the IP address You can insert this example in the script editor by selecting "XenApp Launcher" in the "New Script" window.

Set App = [Menu Select Application:,[IcaApplications]]

If Not VarIsEmpty App Then RunIcaApp,[Var App]

Ica Menu

The script below is a an example, which mixes local applications, XenApp sessions and Remote Desktop sessions. The first menu item starts the locally installed notepad. The second item starts a windowed desktop through an ICA session, the third item starts an RDP Remote Desktop and the fourth item starts notepad as a seamless Citrix XenApp server application. You can insert this example in the script editor by selecting "Remote Session Menu" in the "New Script" window. Note that in this example, the XML Broker port is 8080. This is just to demonstrate the syntax, as the default port 80 is often set up to be a different port, because of another web applications using port 80 on the XML Broker server.



If Not IcaClientInstalled Then

  ShowErrorMessage You do not have Citrix Receiver installed. Please contact the HelpDesk.


End If



Set Selection=[Menu Select item,Document|Notepad,Screen|Acme Server 1,Screen|Acme Server 2,Process|Acme App 1,Stop|Exit]


Switch [Var Selection]

  Case Notepad

    Run Notepad.exe

  Case Acme Server 1


  Case Acme Server 2


  Case Acme App 1




End Switch


Goto Restart

Citrix Menu

When an ICA session has finished, you can use the "LastIcaSessionFailed" condition to determine success. If the condition is true, the function "LastIcaError" contains the error message.

Rating: 5 out of 5

"Use this as a replacement for VBScript and PowerShell"

"It's easy to include attractive GUI elements in FastTrack scripts, beyond the basic dialog boxes and text input that VBScript offers ... Another powerful feature is the ability to distribute scripts as Windows Installer (.msi) or standard .exe files. Although interesting in its own right, this ability results in a much more intriguing capability: to repackage -- or wrap -- software installers as .msi files without using snapshots. If you've ever created an .msi installer file from before-and-after system snapshots, for use with a software distribution system such as Group Policy or SCCM, then you know how hit-and-miss the results can be."

Read full review

Rating: 8 out of 10

"Faster than the rest"

"We found the FastTrack syntax to be more transparent and easier to learn than Microsoft's PowerShell – the editor in particular provided good support in this regard. the Script Editor offers a large number of options from the command set through to simple output of graphical elements, which cannot be achieved at all with PowerShell or other solutions or only with a significantly greater level of effort."

"Anyone wanting to tackle the many hurdles in everyday admin and especially anyone for whom logon scripts and client automation is a priority will benefit from the variety of functions offered by FastTrack."

Review in English      Review in German