View source for Setting up a Citrix environment when automating applications

== '''<big>Setting up the Citrix environment</big>''' ==
When you create a Pega Robotic Automation solution, the setup differs based on whether the applications that you want to automate are served up by a Citrix server or if you have applications that need to interact with applications that exist on the client machine and are also served up by a Citrix server.
* Desktop published on Citrix server – With this setup, you do not require the Citrix Channel Driver installation. You only need to install Robot Runtime in the published desktop.
* All applications are published on Citrix server – With this setup, you do not require the Citrix Channel Driver installation or the use of Citrix contexts in your solution. You only need to install Robot Runtime on the Citrix server and add it as a published application. You will not be able to use Monitor All for adapters because the published application could be started on a different server than the server on which Robot Runtime is running.
* Applications published on the Citrix server and installed on the client – This scenario is called ''mixed mode''. In mixed mode, you install Robot Runtime on both the Citrix server where the applications reside and on the client machines. You must also have the Citrix Channel Driver installed on the client, and your solution must contain a Citrix context that is configured for the Citrix environment that the applications are hosted on.
This document discusses the ''mixed mode'' scenario.

=== <big>Publishing Robot Runtime on the Citrix server</big> ===
Add <code>Pega.Loader.exe</code> as a published application on the Citrix servers that you want to automate the applications for.  

Assign to it an application name, the file path to the Robot Runtime executable, and the following command line argument: “%**”.

The application name that you assign here is used as the Published Application Name in the solution’s Citrix context.

=== <big>Creating your solution</big> ===
When working in a mixed mode scenario, add a Citrix context to your solution for the Citrix server environment that contains the applications that you want to automate. You can add items such as adapters, automations, and Windows forms under the Citrix context. Be sure to add an adapter for each application that you want to automate that is hosted on the Citrix server under its Citrix context. Automations are added under the Citrix context if the initiating event belongs to a control for an adapter under the context. 

Also note that when you are using exit points in your automation, parameter values cannot be transferred across the context. If you need to pass information from an exit point, use a variable stored in the global container.

More information on Citrix contexts and how to use them can be found here: https://community.pega.com/knowledgebase/documents/using-citrix-contexts

=== <big>Configuring the Citrix context for your Citrix environment</big> ===
Depending on how your Citrix environment is set up, you must configure certain properties for the Citrix context. You can find more information about these and other properties for the Citrix context here: http://help.openspan.com/191/#t=citrix%2Fcitrix_context_properties.htm&rhsearch=citrix&rhhlterm=citrix

==== Required properties ====
You must set these properties regardless of which Citrix environment you are using. 
{| class="wikitable"
!Property
!Description
|-
|'''Run Local'''
|Set to <code>True</code> when debugging the solution locally without a connection to the Citrix server.  When you deploy a solution, you will want to set this to <code>False</code>. Remember that when you debug locally, all applications must be on the machine that you are debugging on.
|-
|'''Project To Load'''
|This is the path of the solution located on the Citrix server.
|-
|'''Published Application Name'''
|This is the name assigned to the published Robot Runtime on the Citrix server.
|-
|'''Login Section''' 
(Domain, Login, Password)
|Provide a value for these items if you want to use a specific set of credentials to launch the published Robot Runtime on the Citrix server. If you want to use pass-through authentication, you do not need to enter these values.
|-
|'''Client Location'''
|This is the path to the Citrix receiver installation on the client. By default, the Citrix receiver is installed on the client in this location: <code>C:\Program Files\Citrix\ICA Client</code>. If this is the case on the client machine, this setting does not need to be filled in. If the Citrix receiver is installed in a different location, set this value to that location.
|}

==== Properties for specific Citrix environments ====
'''XenApp 6.5 to 5.0 (without Netscaler)''' – This applies if your Citrix server is XenApp version 6.5 to 5.0 and Netscaler web front end is not used. In addition to the required properties listed in the previous section, modify the properties in the '''XenApp 6x and Older''' section on the Citrix context. If there is only one Citrix server that you are connecting to, you can just add the IP address of this server.   

If there are multiple Citrix servers in a farm, set the '''Http Browser Addresses''' property to add the IP addresses for your Citrix zone data collectors. If you want to use a specific login, enter the credential information under the '''Login''' section under the Citrix context.  

If you want to use pass-through authentication, leave this section blank.  
[[File:Xenapp 6x.png|none|thumb|336x336px]]  

'''XenApp 7.x with Storefront enabled''' '''(without Netscaler)''' – This applies if your Citrix server is XenApp version 7.x and Netscaler web front end is not used and Storefront is enabled in your Citrix environment. In addition to the required properties listed in the previous section, modify the properties in the '''XenApp 7x''' section. Enable this method by setting the '''Use Storefront Web''' property to <code>True</code>. Also provide the Storefront URL in the '''Storefront Web Url''' property. And, if pass-through authentication is enabled in your Citrix environment and you want to use it with Robot Runtime, set the '''Use Passthrough Authentication''' property to <code>True</code>. To use a specific login instead, supply the credential information in the '''Login''' section for the Citrix context.
[[File:XenApp 7x Section.png|none|thumb|342x342px]]

'''WebInterface/Netscaler''' – This applies when your Citrix environment has a Netscaler web front end or Storefront is not enabled in your Citrix environment. Using this method launches an executable that contains an embedded Chromium browser that navigates to obtain the ICA file that is needed to launch the published Robot Runtime application.To enable this, set the '''Use Web Interface Citrix''' context property to <code>True</code>. Also enter the URL of the Citrix Web interface website for the '''Web Interface URL''' property. If you use Netscaler as a front end, also set the '''URL Is Netscaler''' property to <code>True</code>.  

The executable that navigates to obtain the ICA file is enabled to navigate generic cases where the web interface path to start a published application has not been modified. However, to account for cases where the web interface path has been modified, you may need to provide JavaScript content so that the executable with the embedded browser can navigate from the web interface landing page to obtain the ICA file. If this is needed, set the '''Run Custom JavaScript''' property to <code>True</code> and add the custom JavaScript in the '''Custom JavaScript Content''' property.   

When developing the custom JavaScript, you can use variables defined in the Citrix context:

<code>%username%:</code>  – The username property

<code>%password%:</code>  – The password property

<code>%domain%:</code>  – The domain property

<code>%publishedapppath%:</code>  – The path (including folders) to the desired published application.
[[File:XenApp WebInterface-NetScaler.png|none|thumb|336x336px]]

==== Other scenarios ====
These properties need to be set based on certain scenarios.
* You have Windows dialog messages that pop up in the Citrix session when launching a published application that need to be dismissed to continue. In this situation, you will need to define these dialogs and set the '''Dismiss Dialogs''' property in the '''Citrix context Misc''' section to <code>True</code>. To define the windows to be dismissed, add them by clicking the '''Dialog Dismissal List''' property. This displays a window where you can add the class name of the window, the window title, and the x,y coordinates of the control to click to dismiss the dialog. To get the class name and window title, use a third party tool such as Spy++ or Inspect. The x,y coordinates are based off the upper left corner of the window.
[[File:Citrix Dialogue dismissal window.png|none|thumb|529x529px]]
* If you do not want to use pass-through authentication but want to use different credentials to launch the published Robot Runtime application per Citrix server, you can use the external property file. To create this file, run the <code>OpenSpan.Connectors.Citrix.WebInterfacePropertyManager</code> executable that resides in the Robot Studio installation directory. Here you can set the credentials (user name, password, domain) and can also set the published application name and project to load. To use this file, on the Citrix context set the '''Use External Property File''' property to <code>True</code> and set the '''External Properties File Pat'''h to the path where this file resides. If you do this, the settings are read from that location and are used instead of the settings that are configured in the Citrix context.
'''Note''': The resulting generated file is encrypted using the machine algorithm. Therefore, it must be created on each of the client machines. You cannot copy it across environments.
[[File:Citrix context override.png|none|thumb|696x696px]]

=== <big>Interrogating applications</big> ===
Robot Studio must be installed on a Citrix server that hosts the applications that you want to automate to interrogate those applications. You must create the solution and interrogate the client side applications and then move and open this solution in Robot Studio on the Citrix server that hosts the Citrix applications that you want to automate. After you finish interrogating the applications that reside on the Citrix server, you can transfer the solution back to be opened in Robot Studio on the client machine to work on automations and the rest of the solution.

=== <big>Installing the Citrix Channel Driver</big> ===
Install the Citrix Channel Driver that is included along with the product installation on every client machine that runs the mixed mode solution.

=== <big>Deploying the solution</big> ===
When you deploy the solution, make sure that the '''Run Local''' property for the Citrix context is set to <code>False</code>. After the deployment is finished, copy the solution file to the location on the Citrix server that you set with the Citrix context’s '''Project To Load''' property. 

----