Product Documentation

Windows Type Application Definitions

May 09, 2015

Use Windows type application definitions to identify Windows applications, Java applications, and applications started from an SAP Logon Pad.

For the purposes of defining an application definition, categorize any application launched by a file with an .exe extension as a Windows application.

To gather information required for Windows application definitions, launch the application and navigate to the form that requires a user credential management event (user logon, change password, successful password change, or failed password change) while running the Form Definition Wizard from the console or from the Application Definition Tool. The wizard provides instructions for locating and identifying the applicable parts of the application.

Identifying Forms

When creating application definitions for Windows type applications, use the Identify form page to provide the information required for Single Sign-On Plug-in to uniquely recognize the form being defined.

The identifying information includes the Window title and the executable file name. When Single Sign-On Plug-in detects the executable file name, it monitors the application for the defined Window titles.

When a window title is detected, Single Sign-On Plug-in performs the actions defined for the form.

To identify a form

  1. If you haven't already done so, start the Windows program and navigate to the user logon, change password, successful password change, or failed password change form.
  2. From the Identify Form page of the Form Definition Wizard, click Select.
  3. If the desired program is not highlighted, use the Window selector to choose from the other available programs.

Identifying Dynamic Window Titles

While on the Identify form page, you can edit the titles in Window titles for this form to manage dynamic Window title data such as a date or session identifier. To do so, substitute wildcard characters for dynamic data that appears in the Window title as follows:

Wildcard Description
? Use only for a single dynamic/changing character in a Windows title.
* Use this value to represent dynamic title data for one or more characters. This value is not recommended for empty Windows titles. Use NULL for these situations.
NULL Use this value for empty Windows titles (the word “NULL” must be all uppercase).

Identifying Secure Paths

The Executable file names and paths area displays the name of the identified executable file and any secure path information.

Secure paths limit recognition of the application to only those program instances initiated from the paths defined here. If one or more secure paths are identified, Single Sign-on Plug-in submits credentials only when the identified program is run from the defined path and all other defined form identifiers are present.

You can define a secure path by clicking, in the Window selector, Use Full executable path.

If no path information is defined, None provided appears and Single Sign-On Plug-in provides credential information to any program that matches the other form identifiers.

Separate multiple paths with semicolons. You can use absolute paths or environment variables to identify the path.

Note: You can use application definitions that include secure path information to create an application definition template; however, the secure path is not included as part of the template.

Defining Form Actions

The Define form actions page is used to define the actions that must be performed by the Single Sign-on Plug-in to submit the credentials for the specific form being defined.

The top of the page displays the selection of user credentials associated with the specific form:

  Logon Form Password Change Form Successful Password Change Form Failed Password Change Form
Username/ID X X X X
Password X   X X
Old Password   X    
New Password   X    
Confirm Password   X    
Custom Field 1 X   X X
Custom Field 2 X   X X

The bottom of the page displays the defined action sequence.

The objective of this page is to define the actions to be taken by the Single Sign-on Plug-in to successfully submit the required user credentials to the identified form.

To define form actions

The following procedure is sufficient for most Windows applications:

  1. Click the Set/Change hyperlink associated with a specific user credential. This action opens the Configure Control Text dialog box used to identify the control to receive the selected credential.
  2. Select the control type candidate to receive the credential. As the different candidates are selected, the associated control type is visibly highlighted on the application to make it easier to identify the control type that is to receive the identified user credential or submit button.
  3. Repeat this action for all the user credentials required by the form and for the button required to submit the form.

    Some forms require domains or other user-configurable credentials that must be successfully submitted to process the form. To accommodate these requirements, two custom fields are made available. Assign special-requirement credentials to these fields. The names associated with these fields are defined on the Name custom fields page of the Application Definition Wizard after the form is defined.

    Note: Not all the credentials identified in the top of the Define form actions page must be configured.

Window Identifier

The Window Identifier page is used to define a Windows control ID that uniquely identifies a form when more than one window can be identified using only the defined Windows title and the executable file name. It is useful only if the Windows control ID can be used to differentiate among the multiple forms that can be identified.

Select the Enable matching by Window Control ID check box and provide the control ID that uniquely differentiates the window for the form being defined from all the other possible forms.

Identification Extensions

Identification extensions are part of the Application Definition Extensions. These extensions provide support for using applications that are external to the plug-in software to recognize the occurrence of a user credential management event and perform the credential submission process.

Although Single Sign-on administrators can generally create application definitions using the Single Sign-on console component and the Application Definition Tool, some applications have special considerations or requirements that require an alternate means of detecting the application and submitting the user credentials or performing other similar actions.

To support these applications, Single Sign-on administrators can use the Application Definition Extensions to provide an abstraction for the application controls and the associated data input mechanisms.

Identification extensions are developed by third-party implementers and implementation is application-specific. Therefore the procedures required to configure their use are application-specific.

Generally, Single Sign-on administrators are not involved in the development of these extensions. Extensions are created by third-party implementers. Because configuration of these extensions is extension-specific, instructions for configuring the extension will most likely accompany the extension.

Defining Action Sequences for Windows Forms by Using the Action Editor

Use the Define form actions page to define actions that must be performed by the plug-in software to submit the credentials for the specific user credential management form being defined.

For many Windows applications, the basic information gathered in the Form Definition Wizard is enough to define the form. However some forms require more information, steps, special keys, or other actions to successfully complete a user credential management task. For these forms, on the Define form actions page, click Action Editor to open the Action Editor dialog box.

The Action Editor dialog box consists of:

  • Select Actions

    Displays all possible action-sequence actions:

  • Configure Actions

    Used to define the action-specific options to include in the action sequence.

  • Sequence Actions

    Displays the sequence of defined actions to perform to process the specific user credential management form.

At the bottom of the Action Editor dialog box is the Advanced Settings button that is used to access the Advanced Settings dialog box. The Advanced Settings dialog box has two controls:

  • Control ordinal numbers

    Select this check box to use control ordinal numbers (often referred to as Z-order) instead of control ID numbers. Control ordinal numbers are independently enumerated during the definition process (and by the plug-in software) to uniquely identify the controls independently of the control ID numbers defined by the application.

    Consider selecting this feature defining .NET applications that dynamically generate control ID numbers or for applications that have duplicate control ID numbers.

  • Initial delay

    Select this option and define the amount of time that the plug-in software is to delay processing before beginning the action sequence. A delay can also be configured by starting the action sequence with a delay using the Insert delay action for additional information.

    Unlike using the Insert delay option that is accessed from the Select Actions area on the Action Editor dialog box (defined as a send key operation), any initial delay defined here can be used to avoid creating an application definition that is supported only on Versions 4.5, 4.6, 4.6 with Service Pack 1, 4.8, and 5.0 of the Single Sign-on Plug-in.

To define an action sequence

  1. Select an action from among the choices in Select Actions.
  2. Configure the action using the Configure Actions options. When you are satisfied with the configuration settings, click Insert. The configured action appears in Sequence Actions.
  3. Repeat Steps 1 and 2 for all actions required by the user credential form.
  4. Select actions in Sequence Actions and click Move Up or Move Down to arrange them in the correct execution sequence required by the user credential management form being defined.
  5. When satisfied that the action sequence is correct and complete, click OK. This action returns you to the Define form actions page with the defined action sequence in the Action sequence area.
  6. Click Next to continue the form definition process on the Configure other settings page. If any combination of form actions limits the defined sequence to the plug-in/agent of only Password Manager 4.5, Password Manager 4.6, Password Manager 4.6 with Service Pack 1, Single Sign-on 4.8, and Single Sign-on 5.0, a message appears to allow you to continue or return to modify your configuration.

Considerations for Windows Type Definitions

When defining Windows type application definitions, consider the following:

  • Application templates help reduce the effort of creating application definitions.
  • Test your application definitions with the plug-in software before you make them available to users.
  • Most application definitions work using only the basic information. If an application definition does not work as expected in your test environment, it may be due to unique features such as a dynamic window title, dynamic control IDs, or other special identifiers or actions that were programmed into the application.
  • To export application definitions from your test environment to your production environment, use the Export administrative data task from the Single Sign-on component of the Citrix AppCenter.
  • Settings that are selected at the application definition level apply to all forms within the application definition.
  • Some settings that are selected at the application definition level can be overridden at the form level. For example, for an application with three defined forms, the auto-submit can be enabled at the application definition level. Each time the plug-in software encounters one of these three forms for this application, the user credentials are supplied and submitted automatically. However, auto-submit can be disabled for one of the forms at the form level and the plug-in software will not submit the information for that specific form automatically—in this case the user is required to click Submit or OK for the selected form.
  • To create a hot key for the custom field name, place an ampersand (&) in the field name immediately before the letter you want to specify as the hot key.

    If no hot key is identified, the plug-in software dynamically appends a numeric value as the hot key for the control. This will appear on the button as (1) or (2) depending on the number of custom fields that are defined.

    Be sure to test the resulting form to ensure that the defined name does not exceed the amount of space allocated to the custom field name.

Redirect to Windows Application Configuration

When no form is recognized for the Web application in the Web Form Wizard, the form definition must be redirected to use a form definition defined for a Windows application.

Forms may not be recognized when the Web application uses ActiveX controls, Flash-based controls, some types of Ajax controls, or other non-HTML-based controls used to manage user credential management events.

In these cases, ensure that the Redirect to Windows application check box is selected on the Name form page. Click Next to progress through each of the remaining Form Definition Wizard pages, and click Finish on the Confirm settings page.

The form recognition characteristics and credential actions must now be defined using Windows type definitions and send key actions.