About IAG application customizers

Applies To: Intelligent Application Gateway (IAG)

Whale Communications Intelligent Application Gateway (IAG) 2007 application customizers enable you to add functionality such as authentication, authorization, session timeout, or secured logoff to any Web application, or change the appearance of the application by adding graphics, messages, buttons or banners to the interface. The customizers enable the IAG filter to intercept data that is transmitted over IAG, and manipulate both requests, on their way to the application server, and responses, before they are returned to the browser. You can set the filter to manipulate the data of the original content, or “wrap” any third-party Web application in a frame.

IAG automatically customizes the trunk by applying a default template to the trunk. This is implemented in different ways for the different trunk-types, as follows:

• Portal trunks—the default portal home page supplied with IAG is customized.

• Webmail trunks—the Webmail application users access through the trunk is customized.

• Basic trunks—the application users access through the trunk is customized.

You can further customize the default template, or select to use a custom template.

In addition to the application customizers, you can configure the following options in the application customization interface:

• Configure the types of content on which data is searched and replaced by the application customization, HAT, and server name translation processes.

• Configure the handling of compresses data in responses

Using frames

Application customizers enable you to “wrap” the application in a frame. That is, you can add functionality to the application in an environment which you create and add to the original application, while the original application data stays unchanged. This is especially advisable in applications where users, while using the application, go through a large number of URLs, each requiring identical manipulation in order to add the required functionality. Under these conditions, if you manipulate the application data, you have to configure a large number of “data change” elements, one for each URL. Those will be difficult to maintain, and might affect system performance. However, we recommend you do not use frames in the following cases:

• If only a limited number of URLs in the application require identical manipulation.

• If the application breaks out of frames.

• If you wish the application to occupy the entire screen space.

  Note

  Frames must be used in conjunction with authentication. When you configure a trunk for an application that utilized frames, make sure the authentication option is enabled for the trunk.

Sample implementations

This section describes two of the application customizer implementations - session timeout warning, and replacement of server value in response headers, which demonstrate how application customizers enhance the functionality of IAG.

Session timeout warning

The application customizers enable IAG to warn users in advance when their session with the application is about to end, according to the Inactive Session Timeout configured for the trunk.

Users can click OK to renew the session and continue working without having to log into the application again.

Replacement of the server value in response headers

When a server sends a response to the client, one of the response headers it sends is a “server” header. This header contains information about the software used by the server to handle the request, and can contain multiple product tokens and comments identifying the server and any significant subproducts.

For example:

An Apache™ server returns the following server response header:

Server: Apache/2.0.47.(Unix).mod_ssl/2.0.47.OpenSSL/0.9.7b.DAV/2

In order not the expose information regarding the application servers, the application customizers replace the value of the server header with the value that represents IAG (Windows 2003 Server):

Server: Microsoft-IIS/6.0

This replacement ensures that, to the outside world, the application server always appears to be IAG, while the real application server remains hidden.

Customizing your Web applications

You can customize your applications as follows:

• In the Advanced Trunk Configuration window, in the Application Customization tab, you can select whether to use the default IAG template, or a customized template. This is also where you activate the option for Basic trunks, where application customization is not applied by default.

• Optionally, edit the application customization templates.

  Note

  The application customization templates are XML files. In order to edit them, you need to have a working knowledge of XML technology.

About the application customization tab

The Application Customization tab is part of the Advanced Trunk Configuration window, which you access from the main window of the Configuration program. You can use it to:

• Select whether to use the default application customization template that is supplied with IAG, or use a custom template.

• Enable and configure the application customization option in Basic trunks, where application customization is not applied by default.

• Configure the global Content-Type and URL Extension lists.

Application customization tab parameters

Parameter	Description
Enable Application Customization	Enables the application customization option, and applies the settings configured in the application customization templates, according to your selection in “Select Customized Template”, below.
Select Customized Template	Select application customization template: Automatic Other (Manual Configuration)
Search and Replace on Content-Type	Defines the global list of content-types on which the filter search and replace data.
Compression Handling in Responses	Defines how to handle compression in responses.

Global content type list

The content-type list defines the types of content on which data is manipulated by the application customization, HAT, and server name translation processes. Content-type is defined in the value of the HTTP header “Content-Type”.

By default, the list includes the following content-types

• text/.*

  Any type of text, for example:

  text/html, text/css, text/plain.

• application/x-javascript.*

  Text within JavaScript™.

If any of your applications require the manipulation of other content types, you can add the required content-type to the list; you can also remove existing content-types from the list. You configure the list in the Application Customization tab, in the Search and Replace on Content- Type area.

To configure the list of manipulated content-types

1. In the Application Customization tab, in the Search and Replace on Content-Type area, click Add.

   The Add Content-Type dialog box is displayed.

2. Enter the content-type you wish to add to the list, using regular expressions. For a description of regular expressions, see About Regex++ syntax.

3. Click OK.

   In the Search and Replace on Content-Type area, the content-type you entered is added to the list.

4. Repeat steps 1–2 to add all the content-types that require manipulation to the list.

   The application customization, HAT, and server name translation processes will search and replace data in all the content-types listed here.

Handling compression in responses

When the browser requests a URL, it can declare that it is willing to accept the content of the URL in a compressed form. This is specified in the HTTP header accept-encoding, where the header value defines the encoding type.

For example: accept-encoding: gzip,deflate

When the server receives this header, it can send the requested content in an encoded form, according to the encoding type or types specified by the client.

In order to be able to apply the application customization, HAT, and server name translation capabilities, the IAG filter might need to manipulate the content that the server sends to the browser.

The option Compression Handling in Responses, which is defined in the Application Customization tab, reduces latency in delivery time, without losing those capabilities, by defining URL extensions for the types of content that:

• The application servers might send in a compressed form.

• Might contain textual data that needs to be manipulated by IAG.

The filter will pass all other types of content that it receives from the application servers, and which do not require manipulation, to the client without intervention.

You can add URL extensions to the default extensions listed in this area. For a description of the option “Support GZip Compression of Listed URL Extensions”, see the section "GZip commpression".

Configuring the URL extension list

This procedure describes how you add extensions to the default list of URL extensions where compression handling in responses is applied.

To configure the list of URL extensions

1. In the Application Customization tab, in the Compression Handling in Responses area, click Add.

   The Add URL Extension dialog box is displayed.

2. Enter the URL extension you wish to add to the list and click OK.

   In the Application Customization tab, the extension you entered is added to the URL Extension list, in the Compression Handling in Responses area.

3. If required, check the option Support GZip Compression of Listed URL Extensions. For details, see the section "GZip compression". This option applies to all the extensions in the list.

GZip compression

For the extension types listed in the URL Extension list, you can do one of the following:

• Activate the option Support GZip Compression of Listed URL Extensions:

In this setup, when the filter receives a request for content that is listed here, when it passes the request to the application server, it does one of the following:

• If the requesting browser supports GZip encoding, the filter informs the application server that the browser supports this type of encoding. The server can then send the content GZip encoded, in which case the filter will decompress it, manipulate the links as required, compress it again, and send it to the requesting browser.

  Note that even if the browser supports additional encoding forms, the filter informs the application server that the browser supports only GZip encoding.

• If the requesting browser does not support GZip encoding, the filter informs the application server that the browser does not support encoding, even if the browser supports other types of encoding. In this case, the server sends unencoded content to the filter. The filter then manipulates the links as required, and sends the content to the requesting browser in an unencoded form.

• If you do not activate the option Support GZip Compression, when the filter receives a request for content that is listed in the URL Extension list, when it passes the request to the application server, it informs the server that the browser does not support encoding. The server then sends unencoded content to the filter. The filter manipulates the links as required, and sends the content to the requesting browser in an unencoded form.

Advanced configuration of the templates

IAG supplies you with pre-defined application customization templates. If required, you can add functionality to your system by configuring additional options, removing options that are not applicable for your environment, or changing the configuration of existing options.

The following sections describe the functionality of the default application customization templates, and how you create a custom configuration file where you can modify and enhance the default settings. Before you create a custom configuration file, be sure to read the section "Before you begin"; it holds important information you should note.

Functionality

This section describes the functionality of each of the Application Customization templates supplied with IAG.

Microsoft Outlook Web Access 5.5

HTTPS_WhlFiltAppWrap_ForOWA55.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Add client-side Upload URL blocking

• Add the header Server: Microsoft-IIS/6.0

Microsoft Outlook Web Access 2000 SP2/SP3

HTTPS_WhlFiltAppWrap_ForOWA2000SP2.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Change Logoff Button URL to Logoff URL defined in Authentication tab

• Add the header Front-End-Https: On (HTTPS template only)

• Add the header Server: Microsoft-IIS/6.0

Microsoft Outlook Web Access 2000 POST SP3

HTTPS_WhlFiltAppWrap_ForOWA2000POSTSP3.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Change Logoff Button URL to Logoff URL defined in Authentication tab

• Add the header Front-End-Https: On (HTTPS template only)

• Add the header Server: Microsoft-IIS/6.0

Microsoft Outlook Web Access 2003

HTTPS_WhlFiltAppWrap_ForOWA2003.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Change Logoff Button URL to Logoff URL defined in Authentication tab

• Add the header Front-End-Https: On (HTTPS template only)

• Add the header Server: Microsoft-IIS/6.0

Microsoft Outlook Web Access 2003 SP1

HTTPS_WhlFiltAppWrap_ForOWA2003SP1.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Change Logoff Button URL to Logoff URL defined in Authentication tab

• Add the header Front-End-Https: On (HTTPS template only)

• Add the header Server: Microsoft-IIS/6.0

Domino Webmail 46 Interface

HTTPS_WhlFiltAppWrap_ForDominoWebMail46.xml

• Wrap the application in a frame and add a frame with a Logoff button above the application frame

• Add the header Server: Microsoft-IIS/6.0

Domino Webmail 50/60 Interface

HTTPS_WhlFiltAppWrap_ForDominoWebMail.xml

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Plant a Logoff button in the Webmail 5.0x template with the following updates:

  • Button is located at top of navigator, on left hand side

  • The word Logoff is written in upper case, to make it more visible

• Fix Logout option from upper menu in Webmail 6.0

• Add the header Server: Microsoft-IIS/6.0

Domino iNotes (Single Server)

HTTPS_WhlFiltAppWrap_ForDolsInotesSingle.xml

• Eliminate the popup message “Do you want to display nonsecure items?”

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Add and install an SSL VPN object for iNotes 5.0 and iNotes 6.0 & 6.02

• DOLS 5.x, 6, 6.02: change the installation URL

• Add the header Server: Microsoft-IIS/6.0

Domino iNotes (Multi Servers)

HTTPS_WhlFiltAppWrap_ForDolsInotesCluster.xml

• Eliminate the popup message “Do you want to display nonsecure items”

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Add and install an SSL VPN object for iNotes 5.0, 6.0, 6.02, and 6.5

• DOLS 5.x, 6, 6.02: change the installation URL

• Add the header Server: Microsoft-IIS/6.0

All Domino (Webmail 5x/6x/7x and iNotes) Interfaces

HTTPS_WhlFiltAppWrap_ForAllDomino.xml

• Eliminate the popup message “Do you want to display nonsecure items”

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Plant a Logoff button in the Webmail 5.0x template with the following updates:

  • Button is located at top of navigator, on left hand side

  • The word Logoff is written in upper case, to make it more visible

• Enable attachment blocking (forward email attachments or reply with an attachment) in Domino iNotes version 6.5 and higher

• Fix Logout option from upper menu in Webmail 6.0

• Add the header Server: Microsoft-IIS/6.0

Portal template

HTTPS_WhlFiltAppWrap_ForPortal.xml

• Change any instance of logout&redirectto to the Logoff URL defined in the Authentication tab

• In Domino iNotes 5.x, 6.0, 6.02, 7.0 and in OWA 2000 and OWA 2003: change the Logoff button URL to the Logoff URL defined in the Authentication tab, and prevent the Logoff from deleting the IAG session cookie

• DOLS 5.x, 6, 6.02, 7: change URL for installation

• Prevent a situation where a logoff from Citrix® and OWA 5.5 kills the upper frame

• Activate the Attachment Wiper on logout

• Embed JavaScript calls for popup warnings for Session Timeout and Scheduled Logoff

• Add the header Server: Microsoft-IIS/6.0

“OtherWeb” template

HTTPS_WhlFiltAppWrap_ForOtherWeb.xml

• Sample Data Change element (described in <DATA_CHANGE> in Manipulation Elements)

• Sample URL Change element (described in <URL_CHANGE> in Manipulation Elements)

• Add the header Server: Microsoft-IIS/6.0

Before you begin

The templates that control the application customization are located in this folder:

…\Whale-Com\e-Gap\Von\Conf\WizardDefaults\AppWrapTemplates

When a new trunk is created, the relevant template is copied to the following location:

…\Whale-Com\e-Gap\Von\Conf\Websites\<Trunk_Name>\Conf

The file is renamed as follows:

• In HTTP trunks:

  WhlFiltAppWrap_HTTP.xml

• In HTTPS trunks:

  WhlFiltAppWrap_HTTPS.xml

In order to change the default application customization definitions, create a custom file, as described in IAG_Creating a custom application customization file, and implement the changes in the custom file.

Conventions used by the application customization templates

The application customization templates follow these conventions:

• Tag names are uppercase:

  <TAG>...</TAG>

• Attribute names are lowercase:

  <TAG attribute=value>...</TAG>

• Attribute values are case insensitive:

  <TAG attribute=value>...</TAG>

  is identical to:

  <TAG attribute=VALUE>...</TAG>

• Some XML elements take regular expressions in the data. When regular expressions are used, this is indicated in the description of the element usage. When using regular expressions, note the following:

  • Use the syntax described in About Regex++ syntax. In order to use a character as is, make sure it is preceded by a slash. For example, to use the asterisk (*) wildcard in data that takes regular expressions, enter \*

• The supported encoding is Base64. In order to edit encoded text, use the Editor to convert from and to Base64, as described in About the Editor console.

Creating a custom application customization file

This section describes how you create a custom application customization file. The changes you make in the custom file are merged with the definitions of the template that is supplied with the system.

Creating a custom application customization file

To create a custom application customization file

1. Access the following location on the IAG computer:

   …\Whale-Com\e-Gap\Von\Conf\Websites\<Trunk_Name>\Conf

2. Under the Conf folder, create the following subfolder:

   CustomUpdate. If such a folder already exists, use the existing folder.

3. From the Conf folder, copy the following file to the CustomUpdate subfolder:

   WhlFiltAppWrap_HTTP.xml or WhlFiltAppWrap_HTTPS.xml, depending on the trunk-type.

4. For Basic trunks, enable and configure the application customization option, as described in Application Customization tab.

   At the Configuration program, click the Activate button to activate the configuration. Select the option Apply changes made to external configuration settings, and click Activate.

Syntax

An application customization template contains the following elements:

• The first element nested under the root element must be <MANIPULATION>

• The child elements that are nested under <MANIPULATION> manipulate the application data. You can use any of the elements described in the following sections, and include as many child elements as you wish under <MANIPULATION>.

Application customization template–sample code

<APP_WRAP ver="3.0" id="AppWrapSample#1.xml">

<MANIPULATION>

<URL_CHANGE>

<FROM_URL case_sensitive="false">/webload/

test_[0-9.]*k.html</FROM_URL>

<TO_URL>/webload/test_1k.html</TO_URL>

</URL_CHANGE>

<DATA_CHANGE>

<URL case_sensitive="false">/webload/test_1k.html</URL>

<SAR>

<SEARCH>start</SEARCH>

<REPLACE>Why</REPLACE>

</SAR>

</DATA_CHANGE>

<FRAME_WRAP>

<PARENT encoding="base64">PEhUTUw+</PARENT>

<MY_FRAME encoding="base64">PEhUTUw+0KPC9IVE1MPg==</MY_FRAME>

</FRAME_WRAP>

<ADD_HEADER add_to="request" filter_to_rws="http">

<NAME>Front-End-Https:</NAME>

<VALUE>On</VALUE>

</ADD_HEADER>

<HEADER_CHANGE>

<RESPONSE>

<APPLICATION>

<SERVER_NAME mask=””>192\.168\.1\.1</SERVER_NAME>

<PORT>80</PORT>

<URL>

<URL_NAME>/test\.html</URL_NAME>

<EDIT>

<HEADER>

<NAME>Set-Cookie:AppCookie</NAME>

<SAR>

<SEARCH encoding=””>125</SEARCH>

<REPLACE encoding=””>126</REPLACE>

</SAR>

</HEADER>

</EDIT>

</URL>

</APPLICATION>

</RESPONSE>

</HEADER_CHANGE>

</MANIPULATION>

</APP_WRAP>

Manipulation elements

The following elements can be nested under <MANIPULATION>:

• <ADD_HEADER>.

• <DATA_CHANGE>.

• <FRAME_WRAP>.

• <HEADER_CHANGE>.

• <URL_CHANGE>.

The following sections describe the elements and their usage, their child elements, and the relationships between them.

<ADD_HEADER>

Description

Adds a header to either requests or responses.

Usage

• <ADD_HEADER> is optional.

• An unlimited number of <ADD_HEADER> elements can be nested under <MANIPULATION>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
add_to	request, response	Mandatory
filter_to_rws	http, https	Optional. If this attribute is used, the header is added to the request only if the IAG filter and the application server communicate using the protocol defined in the attribute value.

Child Elements

<ADD_HEADER> must contain one of each of the following elements:

• <NAME>.

• <VALUE>.

[<ADD_HEADER>] > [<NAME>]

<NAME>

Description

Child element of <ADD_HEADER>. Defines the header name.

Usage

• One <NAME> element must be nested under each <ADD_HEADER> element.

• Only one <NAME> element can be nested under each <ADD_HEADER> element.

Attributes & Attribute Values

None.

Child Elements

None.

[<ADD_HEADER>] > [<VALUE>]

<VALUE>

Description

Child element of <ADD_HEADER>. Value of the header defined in <NAME>.

Usage

• One <VALUE> element must be nested under each <ADD_HEADER> element.

• Only one <VALUE> element can be nested under each <ADD_HEADER> element.

Attributes & Attribute Values

None.

Child Elements

None.

Sample Code: <ADD_HEADER>

// Adds the header "Front-End-Https: On" to each request from the

// filter to the RWS (Depending the communication from the filter

// to the RWS is HTTP).

<ADD_HEADER add_to="request" filter_to_rws="http">

<NAME>Front-End-Https:</NAME>

<VALUE>On</VALUE>

</ADD_HEADER>

// Adds the header "Cache-Control: no-cache" to each response from

// the filter to the browser.

<ADD_HEADER add_to="response">

<NAME>Cache-Control:</NAME>

<VALUE>no-cache</VALUE>

</ADD_HEADER>

<DATA_CHANGE>

Description

Searches and replaces data string or strings in the data received from the application server before data is sent to the browser.

Usage

• <DATA_CHANGE> is optional.

• An unlimited number of <DATA_CHANGE> elements can be nested under <MANIPULATION>.

Attributes & Attribute Values

None.

Child Elements

<DATA_CHANGE> must contain one of each of the following elements:

• <URL>.

• <SAR>.

[<DATA_CHANGE>] > [<URL>]

<URL>

Description

Child element of <DATA_CHANGE>. Defines the URL in which data is searched and replaced.

Usage

• One <URL> element must be nested under each <DATA_CHANGE> element.

• Only one <URL> element can be nested under each <DATA_CHANGE> element.

• Takes regular expressions.

Attributes & Attribute Values

Attribute	Values	Default	Type/Comments
case_sensitive	true, false	false	Optional

Child Elements

None.

[<DATA_CHANGE>] > [<SAR>]

<SAR>

Description

Child element of <DATA_CHANGE>. Defines a string to search and replace.

Usage

• One <SAR> element must be nested under each <DATA_CHANGE> element.

• An unlimited number of <SAR> elements can be nested under each <DATA_CHANGE> element.

Attributes & Attribute Values

None.

Child Elements

<SAR> must contain one of each of the following elements:

• <SEARCH>.

• <REPLACE>.

  Note

  <SEARCH> and <REPLACE> elements always come in pairs–for every <SEARCH> element there must be a <REPLACE> element.

[<DATA_CHANGE>] > [<SAR>] > [<SEARCH>]

<SEARCH>

Description

Child element of <SAR>. Defines the string that <SAR> searches.

Usage

• One <SEARCH> element must be nested under each <SAR> element.

• Only one <SEARCH> element can be nested under each <SAR> element.

• Two <SEARCH> elements (nested under different <SAR> elements), where one is a sub-string of the other, would cause an error.

• The search is case insensitive.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional

Child Elements

None.

[<DATA_CHANGE>] > [<SAR>] > [<REPLACE>]<REPLACE>

<REPLACE>

Description

Child element of <SAR>. Defines the string with which <SAR> replaces the string defined in <SEARCH>.

Usage

• One <REPLACE> element must be nested under each <SAR> element.

• Only one <REPLACE> element can be nested under each <SAR> element.

• Case is maintained.

• The following variables can be used as placeholders in the data of <REPLACE>; note that variable names are case sensitive:

• WhlSessionTimeout: the maximum time a session can be inactive before it expires. Configured in the Session tab of the Advanced Trunk Configuration window, under “Inactive Session Timeout” (described in Default and Privileged Session Settings).

• WhlLogoffURL: URL to be recognized by the filter as the logoff URL. Configured in the Authentication tab of the Advanced Trunk Configuration window, under “Logoff URL” (described in Configuration in the Authentication Tab).

  Tip

  You can see an example of the use of the WhlLogoffURL variable in a <FRAME_WRAP> element in Sample Code: <FRAME_WRAP>.

• WhlScheduledLogoffTimer: after the time defined in this variable elapses, the user is required to re-authenticate. Configured in the Session tab of the Advanced Trunk Configuration window, under “Automatic Scheduled Logoff After …. Minutes” (described in IAG_Default and privileged session settings).

• WhlOwnURL: URL where the graphic files used by the internal website are located: /InternalSite/

  Tip

  You can see an example of the use of the WhlOwnURL variable in <REPLACE> in Sample Code: <DATA_CHANGE>”.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional

Child Elements

None.

Sample Code: <DATA_CHANGE>

// When a request to the URL "/webload/test_1k.html" is identified,

// the response received from the application server would be

// manipulated prior to sending it to the browser. In the first SAR

// sample, every occurrence of the word "start" (case insensitive)

// will be replaced with the word "Stop". The second SAR is a bit

// more complex. The replace entry contains the reserved

// placeholder WhlOwnURL. This placeholder will be replaced by

// its actual value. Since the value of WhlOwnURL is

// "/InternalSite/", SAR will search for "ImageFromOurServer.jpg"

// and replace it with the following:

// "/InternalSite/ImageFromOurServer.jpg"

<DATA_CHANGE>

<URL case_sensitive="false">/webload/test_1k\.html</URL>

<SAR>

<SEARCH>start</SEARCH>

<REPLACE>Stop</REPLACE>

</SAR>

<SAR>

<SEARCH>src=ImageFromOurServer.jpg</SEARCH>

<REPLACE>src=WhlOwnURLImageFromOurServer.jpg</REPLACE>

</SAR>

</DATA_CHANGE>

<FRAME_WRAP>

Description

Defines a frame that wraps the application, including the frame’s size, position, and attributes, and the features that the frame adds to the application.

Usage

• <FRAME_WRAP> is optional.

• Only one <FRAME_WRAP> element can be nested under <MANIPULATION>.

Attributes & Attribute Values

None.

Child Elements

<FRAME_WRAP> must contain one of each of the following elements:

• <PARENT>.

• <MY_FRAME>.

[<FRAME_WRAP>] > [<PARENT>]

<PARENT>

Description

Child element of <FRAME_WRAP>. Defines the position, size, and attributes of the frame that wraps the application.

Usage

• One <PARENT> element must be nested under <FRAME_WRAP>.

• Only one <PARENT> element can be nested under <FRAME_WRAP>.

• The frame is a top frame; it must not be wrapped by an external frame.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional. Note We recommend that you encode the data under <PARENT>. For details, see “Content”, below.

Content

<PARENT> contains an HTML file that describes the structure of the frame. The file is encoded, using Base64 encoding, so that XML syntax does not collide with the HTML content.

The HTML content must contain a <FRAMESET> element, which defines the original URL requested by the user and the frame wrapping of that URL, using <FRAME> child elements, as follows:

• <FRAME src=”/WhlFrame.html”>

  The frame that will be used, either the default frame supplied with IAG, or a user-defined frame.

  Definition of the frame is described in <MY_FRAME>

• <FRAME src=”/WhlOrigURL.html”>

  The URL originally requested by the user.

  Warning

  <FRAMESET> must contain the two <FRAME> elements described above.

  Do not change the value of the attributes of these elements. Note that the values are case-sensitive.

[<FRAME_WRAP>] > [<MY_FRAME>]

<MY_FRAME>

Description

Child element of <FRAME_WRAP>. Defines the features that the frame adds to the application.

Usage

• One <MY_FRAME> element must be nested under <FRAME_WRAP>.

• Only one <MY_FRAME> element can be nested under <FRAME_WRAP>.

• The following variables can be used as placeholders in the data of <MY_FRAME>; note that variable names are case sensitive:

  • WhlSessionTimeout: the maximum time a session can be inactive before it expires. Configured in the Session tab of the Advanced Trunk Configuration window, under “Inactive Session Timeout” (described in IAG_Default and privileged session settings).

  • WhlLogoffURL: URL to be recognized by the filter as the logoff URL. Configured in the Authentication tab of the Advanced Trunk Configuration window, under “Logoff URL” (described in Configuration in the Authentication Tab).

    Tip

    You can see an example of the use of the WhlLogoffURL variable in <MY_FRAME> in Sample Code: <FRAME_WRAP>.

• WhlScheduledLogoffTimer: after the time defined in this variable elapses, the user is required to re-authenticate. Configured in the Session tab of the Advanced Trunk Configuration window, under “Automatic Scheduled Logoff After … Minutes” (described in IAG_Default and privileged session settings).

• WhlOwnURL: URL where the graphic files used by the internal website are located under:

  …\Whale-Com\e-Gap\von\InternalSite.

  Tip

  You can see an example of the use of the WhlOwnURL variable in a <DATA_CHANGE> element in Sample Code: <DATA_CHANGE>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional. Note We recommend that you encode the data under <MY_FRAME>.

Child Elements

None.

Sample Code: <FRAME_WRAP>

// A frame wrap is composed of a frameset and a specific frame.

<FRAME_WRAP>

<PARENT encoding="base64">

// Note: For the sake of clarity of this sample, the code

// is not encoded to base64 (in real life it should be).

// In this sample we define a frameset composed of two

// frames (those two frames are the required minimum,

// however you could add more frames). The first frame

// holds a user's customized frame and the second one holds

// the requested URL. The respective logical identifiers for

// those frames are "/WhlFrame.html" and "/WhlOrigURL.html"

// (case-sensitive).

<HTML>

<FRAMESET id=main rows='11%, *'>

<FRAME src='/WhlFrame.html' scrolling='no'>

<FRAME src='/WhlOrigURL.html'>

</FRAMESET>

</HTML>

</PARENT>

// This defines the look and content of the user's customized

// frame which is referred to by the logical name

// "/WhlFrame.html".

<MY_FRAME encoding="base64">

// This is a definition of a simple html document containing

// a button triggering a call to the logoff url.

<HTML>

<HEAD>

</HEAD>

<BODY topmargin=0 leftmargin=0 >

<form action="/WhlLogoffURL.html" method=get>

<input type=submit value=Logoff>

</form>

</BODY>

</HTML>

</MY_FRAME>

</FRAME_WRAP>

// Since both the frameset and the user's customized frame are

// controlled by this template, you can easily achieve a wide range

// of capabilities gained by using various Internet technologies

// (JavaScript, HTML, DHTML, etc.).

<HEADER_CHANGE>

Description

Adds and deletes headers, and replaces header values, in either requests or responses. Header manipulation can be configured for a single application, a range of applications, or an application-type.

Usage

• <HEADER_CHANGE> is optional.

• Only one <HEADER_CHANGE> element can be nested under <MANIPULATION>.

Attributes & Attribute Values

None.

Child Elements

<HEADER_CHANGE> can contain one each of the following elements:

• <REQUEST>.

• <RESPONSE>.

[<HEADER_CHANGE>] > [<REQUEST>]

<REQUEST>

Description

Child element of <HEADER_CHANGE>. Manipulates headers in requests.

Usage

• <REQUEST> is optional.

• Only one <REQUEST> element can be nested under <HEADER_CHANGE>.

Attributes & Attribute Values

None.

Child Elements

• <REQUEST> must contain at least one <APPLICATION> element.

• <REQUEST> can contain an unlimited number of <APPLICATION> elements.

[<HEADER_CHANGE>] > [<RESPONSE>]

<RESPONSE>

Description

Child element of <HEADER_CHANGE>. Manipulates headers in responses.

Usage

• <RESPONSE> is optional.

• Only one <RESPONSE> element can be nested under <HEADER_CHANGE>.

Attributes & Attribute Values

None.

Child Elements

• <RESPONSE> must contain at least one <APPLICATION> element.

• <RESPONSE> can contain an unlimited number of <APPLICATION> elements.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>]

<APPLICATION>

Description

Child element of <REQUEST> and of <RESPONSE>. Defines header manipulations for an application or application-type.

Usage

An unlimited number of <APPLICATION> elements can be nested under <REQUEST> and under <RESPONSE>.

Attributes & Attribute Values

None.

Child Elements

<APPLICATION> must contain:

• One of the following:

  • One <SERVER_NAME> element;

  Or,

  • One <APPLICATION_TYPE> element.

• One or more <URL> elements.

Optionally, for each <SERVER_NAME> element, <APPLICATION> can also contain one <PORT> element.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<SERVER_NAME>]

<SERVER_NAME>

Description

Child element of <APPLICATION>. Defines the server or subnet where manipulated is required.

Usage

• One <SERVER_NAME> element can be nested under each <APPLICATION> element.

• Only one <SERVER_NAME> element can be nested under <APPLICATION>.

• For each <SERVER_NAME> element, one <PORT> element can also be nested under <APPLICATION>.

• Can be defined using one of the following methods:

  • Server name or a range of names, using regular expressions.

  • Subnet, using the “mask” attribute. For example:

    For subnet class A:

    <SERVER_NAME mask="255.0.0.0">63.0.0.0</SERVER_NAME>

    For subnet class B:

    <SERVER_NAME mask="255.255.0.0">160.12.0.0</SERVER_NAME>

    For subnet class C:

    <SERVER_NAME mask="255.255.255.0">192.168.1.0</SERVER_NAME>

    Note: In this syntax, enter the actual IP address, not regular expressions.

    Tip

    For an example of the use of the both methods, refer to Sample Code: <HEADER_CHANGE>, to the <RESPONSE> section.

Attributes & Attribute Values

Attribute	Values	Type/Comments
mask	subnet mask	Optional. Used to define a subnet mask.

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<PORT>]

<PORT>

Description

Child element of <APPLICATION>. Defines the port number on which the server, defined in <SERVER_NAME>, listens to incoming requests.

Usage

• Optional.

• For each <SERVER_NAME> element, one <PORT> element can be nested under <APPLICATION>.

• Only one <PORT> element can be nested under <APPLICATION>.

Attributes & Attribute Values

None.

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<APPLICATION_TYPE>]

<APPLICATION_TYPE>

Description

Child element of <APPLICATION>. Defines the type of application where manipulated is required.

Usage

• One <APPLICATION_TYPE> element can nested under each <APPLICATION> element.

• Only one <APPLICATION_TYPE> element can be nested under <APPLICATION>.

Attributes & Attribute Values

None.

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>]

<URL>

Description

Child element of <APPLICATION>. Defines the URL or range of URLs for which header manipulation is configured, and the required manipulations.

Usage

• One <URL> element must be nested under each <APPLICATION> element.

• An unlimited number of <URL> elements can be nested under <APPLICATION>.

Attributes & Attribute Values

None.

Child Elements

<URL> must contain the following:

• One <URL_NAME> element.

• One of the following elements:

  • <ADD>.

  • <DELETE>.

  • <EDIT>.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<URL_NAME>]

<URL_NAME>

Description

Child element of <URL>. Defines the URL or range of URLs for which header manipulation is configured.

Usage

• One <URL_NAME> must be nested under <URL>.

• Only one <URL_NAME> can be nested under <URL>.

• Takes regular expressions.

Attributes & Attribute Values

Attribute	Values	Type/Comments
InternalScheme	http, https	Optional
ExternalScheme	http, https	Optional

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<ADD>]

<ADD>

Description

Child element of <URL>. Defines headers to add to either requests or responses, for the application defined in <APPLICATION>.

Usage

Only one <ADD> element can be nested under <URL>.

Attributes & Attribute Values

None.

Child Elements

<ADD> can contain an unlimited number of <HEADER> elements.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<ADD>] > [<HEADER>]

<HEADER>

Description

Child element of <ADD>. Defines the header that is added.

Usage

• At least one <HEADER> element must be nested under <ADD>.

• An unlimited number of <HEADER> elements can be nested under <ADD>.

Attributes & Attribute Values

None.

Child Elements

<HEADER> must contain one each of the following elements:

• <NAME>.

• <VALUE>.

  Note

  When you define an <ADD> element, under <HEADER>, <NAME> and <VALUE> elements always come in pairs–for every <NAME> element there must be a <VALUE> element, defining the header value.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<ADD>] > [<HEADER>] > [<NAME>]

<NAME>

Description

Child element of <HEADER>. Name of the header that is added.

Usage

• One <NAME> element must be nested under <HEADER>.

• Only one <NAME> element can be nested under <HEADER>.

Attributes & Attribute Values

None.

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<ADD>] > [<HEADER>] > [<VALUE>]

<VALUE>

Description

Child element of <HEADER>. Value of the header that is added.

Usage

• One <VALUE> element must be nested under <HEADER>.

• Only one <VALUE> element can be nested under <HEADER>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<DELETE>]

<DELETE>

Description

Child element of <URL>. Defines headers to delete from either requests or responses, for the application defined in <APPLICATION>.

Usage

Only one <DELETE> element can be nested under <URL>.

Attributes & Attribute Values

None.

Child Elements

• <DELETE> must contain at least one <HEADER> element.

• <DELETE> can contain an unlimited number of <HEADER> elements.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<DELETE>] > [<HEADER>]

<HEADER>

Description

Child element of <DELETE>. Defines the header that is deleted.

Usage

• At least one <HEADER> element must be nested under <DELETE>.

• An unlimited number of <HEADER> elements can be nested under <DELETE>.

Attributes & Attribute Values

None.

Child Elements

• <HEADER> must contain one <NAME> element.

• <HEADER> can contain only one <NAME> element.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<DELETE>] > [<HEADER>] > [<NAME>]

<NAME>

Description

Child element of <HEADER>. Defines the name of the header that is deleted.

Usage

• One <NAME> element must be nested under <HEADER>.

• Only one <NAME> element can be nested under <HEADER>.

• In “Cookie” and “Set-Cookie” headers only: takes regular expressions in the cookie name.

Attributes & Attribute Values

None.

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>]

<EDIT>

Description

Child element of <URL>. Defines the replacement of header values in either requests or responses, for the application defined in <APPLICATION>.

Usage

Only one <EDIT> element can be nested under <URL>.

Attributes & Attribute Values

None.

Child Elements

• <EDIT> must contain at least one <HEADER> element.

• <EDIT> can contain an unlimited number of <HEADER>.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>] > [<HEADER>]

<HEADER>

Description

Child element of <EDIT>. Defines the header that is edited.

Usage

An unlimited number of <HEADER> elements can be nested under <EDIT>.

Attributes & Attribute Values

None.

Child Elements

<HEADER> must contain one each of the following elements:

• <NAME>.

• <SAR>.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>] > [<HEADER>] > [<NAME>]

<NAME>

Description

Child element of <HEADER>. Defines the name of the header whose value is replaced.

Usage

• One <NAME> element must be nested under <HEADER>.

• Only one <NAME> element can be nested under <HEADER>.

• In “Cookie” and “Set-Cookie” headers only: takes regular expressions in the cookie name.

Attributes & Attribute Values

Attribute	Values	Default	Type/Comments
method	Name, Value, All	Value	Optional; applicable for cookies only (“Cookie” and “Set-Cookie” headers). Defines where the replacement takes place: Name: cookie name Value: cookie value All: both cookie name and value Note Attribute values are case insensitive

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>] > [<HEADER>] > [<SAR>]

<SAR>

Description

Child element of <HEADER>. Defines header value that is replaced, and the replacement value.

Usage

An unlimited number of <SAR> elements can be nested under <HEADER>.

Attributes & Attribute Values

None.

Child Elements

<SAR> must contain one each of the following elements:

• <SEARCH>.

• <REPLACE>.

  Note

  <SEARCH> and <REPLACE> elements usually come in pairs–for every <SEARCH> element there must be a <REPLACE> element. An exception to this rule is when you replace a cookie name in “Cookie” and “Set-Cookie” headers (value of the “method” attribute is “Name”). For this type of replacement, there is no need for a <SEARCH> element.

  For example:

  <HEADER>

  <NAME method="Name">cookie:abc.*</NAME>

  <SAR>

  <REPLACE encoding="">ddd</REPLACE>

  </SAR>

  </HEADER>

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>] > [<HEADER>] > [<SAR>] > [<SEARCH>]

<SEARCH>

Description

Child element of <SAR>. Defines the header value that is replaced.

Usage

• One <SEARCH> element must be nested under <SAR>.

• Only one <SEARCH> element can be nested under <SAR>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional

Child Elements

None.

[<HEADER_CHANGE>] > [<REQUEST>]¦[<RESPONSE>] > [<APPLICATION>] > [<URL>] > [<EDIT>] > [<HEADER>] > [<SAR>] > [<REPLACE>]

<REPLACE>

Description

Child element of <SAR>. Defines the replacement header value.

Usage

• One <REPLACE> element must be nested under <SAR>.

• Only one <REPLACE> element can be nested under <SAR>.

Attributes & Attribute Values

Attribute	Values	Type/Comments
encoding	base64	Optional

Child Elements

None.

Sample Code: <HEADER_CHANGE>

<HEADER_CHANGE>

<REQUEST>

<!--

In a request to server 192.168.1.1 and URL /test.html, the code

in this sample does the following:

1.In all “cookie” headers that start with “abc”, search:

xxx,replace with: yyy

2.Add the header “xyz” with the value “zzz”

3.Delete the “referer” header

-->

<APPLICATION>

<SERVER_NAME mask=””>192\.168\.1\.1</SERVER_NAME>

<PORT>80</PORT>

<URL>

<URL_NAME>/test\.html</URL_NAME>

<EDIT>

<HEADER>

<NAME>cookie:abc*</NAME>

<SAR>

<SEARCH encoding=””>xxx</SEARCH>

<REPLACE encoding=””>yyy</REPLACE>

</SAR>

</HEADER>

</EDIT>

<ADD>

<HEADER>

<NAME>xyz</NAME>

<VALUE encoding=””>zzz</VALUE>

</HEADER>

</ADD>

<DELETE>

<!-- NOTE: You cannot delete a Host header from

requests, you can only edit it

-->

<HEADER>

<NAME>referer</NAME>

</HEADER>

</DELETE>

</URL>

</APPLICATION>

</REQUEST>

<RESPONSE>

<!--

In response from server 192.168.1.1 and URL /test.html, the

code in this sample does the following:

1.In a “set-cookie” header named “AppCookie”, search: 125,

replace with: 126

2.Add the header “xyz” with the value “zzz”

3.Delete all the 'Set-Cookie' headers with cookies that start

with xxx

In response from subnet 192.168.1.0 and URL /control.html, the

code in this sample deletes the 'Cache-Control' header.

-->

<APPLICATION>

<SERVER_NAME mask=””>192\.168\.1\.1</SERVER_NAME>

<PORT>80</PORT>

<URL>

<URL_NAME>/test\.html</URL_NAME>

<EDIT>

<HEADER>

<NAME>Set-Cookie:AppCookie</NAME>

<SAR>

<SEARCH encoding=””>125</SEARCH>

<REPLACE encoding=””>126</REPLACE>

</SAR>

</HEADER>

</EDIT>

<ADD>

<HEADER>

<NAME>xyz</NAME>

<VALUE encoding=””>zzz</VALUE>

</HEADER>

</ADD>

<DELETE>

<HEADER>

<NAME>Set-Cookie:xxx.*</NAME>

</HEADER>

</DELETE>

</URL>

<SERVER_NAME mask=”255.255.255.0”>192.168.1.0</SERVER_NAME>

<URL>

<URL_NAME>/control\.html</URL_NAME>

<DELETE>

<HEADER>

<NAME>Cache-Control</NAME>

</HEADER>

</DELETE>

</URL>

</APPLICATION>

</RESPONSE>

</HEADER_CHANGE>

<URL_CHANGE>

Description

Used for internal redirection. Redirects the URL before the request is sent to the application server. Can be used to direct users to alternative sites, display messages, and more.

Usage

• <URL_CHANGE> is optional.

• An unlimited number of <URL_CHANGE> elements can be nested under <MANIPULATION>.

• <URL_CHANGE> is not a transitive redirection—a URL can only be redirected once.

  For example: if you redirect a request from /default.jpg to /images/default.jpg, you cannot then redirect it from /images/default.jpg to a different destination by configuring an additional <URL_CHANGE> element.

• <URL_CHANGE> elements are processed in the order by which they appear in the template; the first matching <URL_CHANGE> element is activated.

  Tip

  <URL_CHANGE> elements are processed prior to <DATA_CHANGE> elements.

  If you wish to combine a <DATA_CHANGE> element with a <URL_CHANGE> element, the URL must reside on the application server; such a combination is not possible when the URL resides on the local host.

Attributes & Attribute Values

None.

Child Elements

<URL_CHANGE> must contain one of each of the following elements:

• <FROM_URL>.

• <TO_URL>.

[<URL_CHANGE>] > [<FROM_URL>]

<FROM_URL>

Description

Child element of <URL_CHANGE>. Defines the URL to be redirected.

Usage

• One <FROM_URL> element must be nested under each <URL_CHANGE> element.

• Only one <FROM_URL> element can be nested under each <URL_CHANGE> element.

• Takes regular expressions.

Attributes & Attribute Values

Attribute	Values	Default	Type/Comments
case_sensitive	true, false	false	Optional

Child Elements

None.

[<URL_CHANGE>] > [<TO_URL>]

<TO_URL>

Description

Child element of <URL_CHANGE>. Defines the location to where the URL, which is defined in <FROM_URL>, is redirected.

Usage

• One <TO_URL> element must be nested under each <URL_CHANGE> element.

• Only one <TO_URL> element can be nested under each <URL_CHANGE> element.

• Must contain a specific URL (does not take regular expressions).

Attributes & Attribute Values

Attribute	Values	Default	Type/Comments
local_host	true, false	false	Optional. If local_host=false, the page resides on the application server. If local_host=true, the page must reside under IAG’s root directory: …\von\InternalSite

Child Elements

None.

Sample Code: <URL_CHANGE>

// In this sample we intend to change every URL of the format

// /webload/test_[0-9]*k\.html (pay attention there is a use of

// a regular expression here, which defines a sequence of zero or

// more digits).

// The following URL would be considered a match:

// 1) /webload/test_105k.html

// 2) /webload/test_4k.html

// When identifying a matching URL we change it to the URL defined

// in the TO_URL entry. The TO_URL could be located under the RWS

// (default) or under the filter's root directory, as in this

// sample.

<URL_CHANGE>

<FROM_URL case_sensitive="false">/webload/

test_[0-9]*k\.html</FROM_URL>

<TO_URL local_host="true">/webload/test_1k.html</TO_URL>

</URL_CHANGE>