Configuring Siebel Open UI > Configuring Siebel Open UI to Interact with Other Applications > Displaying Data from External Applications in Siebel Open UI >

Integrating External Content

This topic provides an overview of Portal Agents. It describes the configuration and administration tasks necessary to display external content in the Siebel user interface. It also includes a reference topic that lists all of the commands available for use with Portal Agents. This chapter contains the following information:

• About Portal Agents
• Process of Creating Portal Agents
• Determining the Login Requirements
• Portal Agent Configuration
• Portal Agent Administration
• Defining End-User Login Credentials
• Example Portal Agent
• Reviewing the SWE Log File
• Portal Agent Command Reference

About Portal Agents

Portal Agents allow you to integrate external data into the Siebel user interface. Portal Agents retrieve data by sending HTTP requests to external applications, and then display the HTML results in a Siebel applet or on some other portion of a Siebel application Web page.

Portal Agents combine a set of features and technologies that allow you to integrate external content at the user interface layer, including the following:

• Single sign-on technology (SS0). For applications that are participating in a single sign-on framework, this feature eliminates the need for the user to enter login credentials, such as user name and password, more than once for each work session. For more information about single sign on, see Siebel Security Guide.
• Session management and session reuse. Allows the Siebel application and the external application to maintain a user's session context, without reauthenticating for subsequent requests. This minimizes session resource overhead on the external application, and allows the user to retain session context, such as shopping cart contents.
• Time-out handling. The Siebel Server automatically reauthenticates when a request is submitted after the external application's timeout period has passed.
• Symbolic URLs, with multiple disposition types. Allows content to be displayed in different ways, such as in a new browser window, inline with the other content, in an <iframe> tag. For more information, see About Disposition Types.
• Session proxy. For content integrated using a disposition type of Inline, the Siebel Server manages the interactions with external applications on behalf of the user. For more information about the Inline disposition type, see Inline Disposition Type.
• Symbolic URL commands. Commands that direct the Portal Agent to assemble the URL for the external application in several ways. These include dynamically referencing the user's user name and password, retrieving stored user name and password values, retrieving data from the user's personalization profile, establishing the size of an <iframe> tag, and determining whether to set the browser cookies from the application server's login page. For a complete list of commands, see Portal Agent Command Reference.

NOTE:  Portal Agents do not integrate data at the data layer or integrate business logic. Other mechanisms in the Siebel Portal Framework, such as Integration Objects and Virtual Business Components, are designed to meet those types of integration needs. For more information about Siebel EAI, see Overview: Siebel Enterprise Application Integration.

This topic contains the following information:

• Portal Agents and Authentication Strategies
• About Disposition Types

Portal Agents and Authentication Strategies

Portal Agents can be configured to support different authentication strategies:

• Simple Portal Agents. The external application does not require any authentication parameters.
• Single Sign-On Portal Agents. The external application requires authentication parameters. Form-based Portal Agents send authentication parameters as part of the body portion of the HTTP request.

For more information about authentication, see Siebel Security Guide.

About Disposition Types

One of the steps in setting up a Portal Agent is creating a symbolic URL. The symbolic URL specifies the information necessary to construct the HTTP request to send to the external application. Symbolic URLs can be one of several disposition types. The disposition type determines the following:

• The interaction between the browser, the Siebel Server, and the external application.
• How external content is displayed in the user interface.

It is important to understand these disposition types and determine which one suits your integration needs. Each disposition type is discussed in one of the following topics:

• Inline Disposition Type
• IFrame Disposition Type
• Form Redirect Disposition Type

For information about defining symbolic URLs, see Defining Symbolic URLs.

Inline Disposition Type

With a symbolic URL disposition type of Inline, the Siebel Server receives content sent by an external application. It combines the external content with Siebel-produced content and composes a single HTML page, which it then sends to the client browser for display to the user. Optionally, links in the aggregated content are rewritten so they reference the Siebel Server (proxy), rather than referencing the external application server directly. This allows the Siebel Server to handle links in the aggregated content in such a way that it appears to the user as one integrated application rather than from different application servers.

The Inline disposition type supports session management. The Siebel Server uses session management to manage session cookies and automatically log in again to an external application after a time out occurs.

The Inline disposition type requires that:

• The page you are integrating does not include complex JavaScript and does not reference frames.
• The maximum number of characters in the calling URL is 2048.
• No methods other than the GET method are invoked.

If the Inline disposition type is not appropriate, then you might try the IFrame disposition type.

IFrame Disposition Type

Use this disposition type when aspects of the external application do not allow content to be aggregated with other Siebel content. For more information, see Portal Agent Restrictions.

The IFrame disposition type uses the <iframe> tag to create an internal frame as part of the page generated by the Siebel Server. It allows the Portal Agent to retrieve content to populate the internal frame. This content does not pass through the Siebel Server, but is directly requested by the client and sent by the application server to the user's browser. Although this disposition type is not as preferable as the Inline disposition type, in most cases, it is a method that works.

The IFrame disposition type supports JavaScript and frames. Therefore, if the Inline disposition type does not work, then the IFrame option is the best option. The IFrame disposition type also supports the Session Keep Alive feature. However, it does not support session management.

The IFrame disposition type works in many cases. However, it does not work when frames displayed within the <iframe> tag refer to top-level JavaScript objects. If frames in the page that you are trying to integrate refer to top-level JavaScript objects, then you might use the Web Control disposition type instead, if it is applicable.

Contextual Navigation Between Siebel Business Applications and Oracle Business Intelligence Pages

When an Oracle^® Business Intelligence (Oracle BI) page is integrated with a Siebel application through the portal framework and the portal content is dependent on the Siebel record, any change or update of the record in the Siebel application must also be reflected in the portal content. For example, for an Oracle BI applet embedded in a view with the Account List applet, its content dynamically changes at the same time that the content is changed within the Account List applet. To enable this behavior, you must do the following:

• Define a symbolic URL. For more information, see Defining Symbolic URL Arguments.
• Set parameters for the symbolic URL. For more information, see Portal Agent Command Reference.

Form Redirect Disposition Type

In the Form Redirect scenario, the Siebel Web client submits a request to the Siebel Server. The Siebel Server creates a form with the necessary authentication information in it, and then sends the form back to the browser. The browser loads the form and then submits it to the external host for processing. The external host sends back the results, which the browser displays in a new window.

The Form Redirect disposition type is usually displayed in a new window, rather than inline with other Siebel applets.

The Form Redirect disposition type is not commonly used with Siebel Business Applications.

Portal Agent Restrictions

Portal Agents are meant to bring existing applications and content into the Siebel user interface without requiring additional modifications of the external application. However, this is not always possible due to the way HTML and Web browsers are designed. For example:

• The use of frames by an external application might not be amenable to inline aggregation methods.
• Specific frame references in the returned content referring to global frames (_NEW, _TOP, .parent()) might not be amenable to inline aggregation methods.
• Reliance on JavaScript functions defined in (assumed) external frames might not be amenable to inline aggregation methods.
• URLs that are created dynamically by JavaScript might not be amenable to any fixup techniques, because the URLs would not be easily parsed on the HTML content.

For these reasons, an Inline disposition type does not work often. However, if you control both the Siebel application instance and the external application, and can resolve some of these issues, then the Inline disposition type might work correctly. For more information about the Inline disposition type, see Inline Disposition Type.

If you do not have control over the external application, the IFrame disposition type is the method most likely to provide satisfactory results. It works with about 80% of the form-based application sites tested. For more information about the IFrame disposition type, see IFrame Disposition Type.

Disposition Types Summary

Table 15 summarizes the characteristics of each disposition type.

Process of Creating Portal Agents

To create a Portal Agent, perform the following tasks:

1. Determining the Login Requirements.
2. Configuring Business Components to Handle External Data.
3. Complete one of the following:
   • Displaying External Content Within an Applet.
   • Displaying External Content Outside of an Applet.
4. Defining Web Applications.
5. Defining Symbolic URLs.
6. Defining Symbolic URL Arguments.

Determining the Login Requirements

Before you configure Portal Agents, you must understand what information is required by the external application to authenticate users. Typically, this information is gathered using a form page, also called a login page, and then sent to the external application. You must determine exactly what information the form gathers from the user and sends to the external application, including field names and values.

In cases where you have specific knowledge about how an external application is implemented and can consult with authoritative sources regarding how the application authenticates users, determining the required input fields and values is relatively simple.

In cases where you do not have specific knowledge about how an external application is implemented, you must attempt to understand its authentication method by examining the application's login page. The steps describe an approach that you can use to reverse-engineer a login page and provide related Portal Agent configuration tips.

NOTE:  It is not always possible to reverse-engineer a login page. For example, JavaScript might process login field values prior to delivering the POST back to the application server, session values might be encoded in the form itself, or session values might be stored in the browser's session cookies.

This task is a step in Process of Creating Portal Agents.

To reverse-engineer a login page

1. Navigate to the external application's login page and determine whether the external application uses authentication.

   For more information, see Defining Symbolic URLs.

2. If the external application uses form-based authentication, then view the login page's HTML using your browser's view source command.
3. Identify the form on the login page that asks for user credentials (the form might ask for other information as well) and identify the input fields in this form used to authenticate users.

   It is usually best to strip out all non-form lines of HTML and to isolate the <input> tags. That is, remove lines previous to <form ...> and after </form> and remove lines that are not part of the <input> tags.

4. Determine whether the method attribute of the <form> tag is POST.

   If it is POST, then you must define the PostRequest command as an argument of the symbolic URL. For more information, see Defining Symbolic URL Arguments and PostRequest Command.

   If it is GET, then you do not have to define a symbolic URL command, because the default method of symbolic URLs is GET.

5. Determine the target of the form's action attribute, which is usually specified as action="some string".

   If the target of the action attribute is an absolute URL, one that begins with http or a forward slash (/), then use this URL as the base of the Portal Agent.

   If it is a relative address, then you also have to determine where the root of the URL is defined. It could be defined relative to the URL of the login page itself (most common), in a <codebase> tag (rare) or in JavaScript (hard to determine).

   The target URL is defined using the Host Administration View and the Symbolic URL Administration view. For more information, see Defining the External Host and Defining Symbolic URLs.

6. Determine any argument values defined in the target URL.

   These are the characters after the ? character. Usually, these are simple field-value constants. The exception is when a field or a value is a session identifier that is dynamically assigned by the external application server and is only valid for a period before it times out. In this case, it might not be possible to configure a Portal Agent. Define any argument values contained in the target URL as symbolic URL arguments. For more information, see Defining Symbolic URL Arguments.

7. Identify each of the form's <input> tags and determine which ones are necessary to send to the external application for authentication.

   Often there are <input> tags in the form with a type attribute of hidden that are not evident when interacting with the application. Determining whether hidden fields are optional or required is often process of trial and error.

   Some <input> tags might not have values identified. Either these fields are awaiting input to be entered by the user (for example, login name or password) or they are hidden fields with no values.

   • If the input field is specific to the user (it asks for the user's login name and password), then you can use UserLoginId Command and UserLoginPassword Command commands to instruct the Portal Agent to retrieve the user's credentials from the user's My Logins view. For more information, see Defining End-User Login Credentials.
   • If there are hidden fields with no values, then, when you enter them as symbolic URL arguments, make sure that the Required Argument column is not checked. If it is checked, and the input field has no value, then the Portal Agent does not send this request to the target application server, because there is no value to put in its place.

     You define the input fields and values as symbolic URL arguments. For more information, see Defining Symbolic URL Arguments.

NOTE:  The Mozilla browser includes a page info command (^I) that analyzes forms on a page and displays the method, input fields, and so on.

Portal Agent Configuration

Using Portal Agents to integrate external content into the Siebel user interface requires some simple configuration in Siebel Tools. You must configure a field on the business component to handle external data and then configure either an applet or a Web page item to display the content in the user interface. An applet displays external content inside the applet container on a view. A Web page item displays external content outside of an applet, such as in the banner frame for example.

NOTE:  This topic describes the configuration tasks that are unique to integrating external content with the Siebel user interface. It does not describe standard configuration tasks that you might be required to perform. For example, after you configure an applet to display external content, you might have to associate that applet with a view, add the view to a responsibility, and so on. These additional tasks are standard procedures for configuring Siebel Business Applications and are outside the scope of this book. For more information about configuring Siebel Business Applications, see Configuring Siebel Business Applications.

This topic contains the following information:

• Configuring Business Components to Handle External Data
• Displaying External Content Within an Applet
• Displaying External Content Outside of an Applet

Configuring Business Components to Handle External Data

To configure business components to handle external data using a symbolic URL, you must create a new calculated field on the business component. Rather than representing structured content, such as records in a database, this field represents the HTML content sent from an external host.

NOTE:  Although a symbolic URL displays data that is not stored in the database, the business component must have at least one record stored in an underlying table so that it is instantiated at run time.

This task is a step in Process of Creating Portal Agents.

To configure a business component to handle external data using a symbolic URL

1. Create a new field on the business component.
2. Set the field's Calculated property to TRUE.
3. Set the field's Type property to DTYPE_TEXT.
4. In the Calculated Value field, enter the name of the symbolic URL (enclosed in double quotes) that you want to use to submit the HTTP request.

   The name of the symbolic URL in the Calculated Value field must be enclosed in double quotes so that it evaluates as a constant. See the business component named AnalyticsSSO in the Siebel Repository for an example of fields configured this way.

Displaying External Content Within an Applet

After you have created the calculated field on the business component, you expose it in the user interface. You display the external content using a control in a form applet or list applet.

NOTE:  You can also expose external content outside an applet, such as in the banner area. See Displaying External Content Outside of an Applet.

This task is a step in Process of Creating Portal Agents.

To display external content within an applet

1. Create an applet that you want to use to display the external content.

   The applet must be based on the business component that you configured in Configuring Business Components to Handle External Data.

2. Add a new control or list column to the applet.
3. Associate the control or list column with a calculated field on the business component that is configured to represent the external data.
4. Set the control or list column's Field Retrieval Type property to Symbolic URL.
5. Set the control or list column's HTML Type property to Field.

Displaying External Content Outside of an Applet

After you have created the calculated field on the business component, you expose it in the user interface. You can display the external content outside of an applet using Web Page Items.

NOTE:  You can also expose external content inside an applet, by using an Applet Control or List Column. For more information, see Displaying External Content Within an Applet.

This task is a step in Process of Creating Portal Agents.

To display content outside of an applet

1. Start Siebel Tools.
2. Go to the Web Page object type and select the Web page on which to display external data.
3. Create a new Web Page Item or use an existing one.
4. Set the Type property of the Web Page Item to Field.
5. Create the following two Web Page Item Parameters:

   Name	Value
   FieldRetrievalType	Symbolic URL
   SymbolicURL	[name of symbolic URL]

   NOTE:  The symbolic URL is mapped to the calculated field defined for the business component.

Portal Agent Administration

You administer Portal Agents through several views located under the Administration - Integration screen in the Siebel Web client. As described in the following topics, these views allow you to define how to handle links, define the external host, and define the HTTP request that is sent to the external host.

This topic contains the following information:

• Defining the External Host
• Defining Web Applications
• Defining Symbolic URLs
• Defining Symbolic URL Arguments
• Configuring Multiple Symbolic URLs and Hosts for Alternative Execution Locations
• Defining Content Fixup

Defining the External Host

You define the external data hosts in the Host Administration view. This view allows you to do the following:

• Maintain external host names in a single place.
• Define how to handle (fix) links after external HTML content is rendered.

To define a data host

1. Navigate to the Administration - Integration screen, and then WI Symbolic URL List.
2. From the drop-down menu, select Host Administration.
3. Enter a new record and define the necessary fields.

   Some of the fields are described in the following table:

   Field	Comments
   Name	Name of the external host.
   Virtual Name	User-defined name for the host.
   Authentication Type	Leave this value blank. For more information, see Defining Symbolic URLs.

Defining Web Applications

Web applications allow multiple symbolic URLs to send requests to the same Web application and share the same session. This is useful if you have two different applet controls that use symbolic URLs to submit requests to the same Web application. You can associate these symbolic URLs to a single Web application and specify whether they share the same session.

There might be cases in which you do not want requests to share the same session. For example, you might not want to share a session when a session cookie contains more information than the session ID, as this could result in unexpected behavior. When you define a Web application, you specify whether it shares sessions.

Web applications also allow you to define the Time Out value for the session time out feature. The Session Time Out feature is only applicable to symbolic URLs with a disposition type of Inline.

This task is a step in Process of Creating Portal Agents.

To define a Web application

1. Navigate to the Administration - Integration screen, and then WI Symbolic URL List.
2. From the drop-down menu, select Web Application Administration.
3. Enter a record and complete the fields.

   Some of the fields are described in the following table:

   Field	Description
   Shared	Indicates whether requests generated by symbolic URLs associated with this Web application share the same session.
   Time Out	Defines the time out parameter for the session management feature, which is only applicable to symbolic URLs with a disposition type of Inline.

Defining Symbolic URLs

You use the Symbolic URL Administration view to specify how to construct the HTTP request to the external application and to define any arguments and values to be sent as part of the request.

This task is a step in Process of Creating Portal Agents.

To define a symbolic URL

1. Navigate to the Administration - Integration screen, and then WI Symbolic URL List.
2. From the drop-down menu, select Symbolic URL Administration.
3. In the Symbolic URL Administration list view, enter a new record.

   Some of the fields are defined in the following table:

   Field	Description
   URL	Use the URL field to enter a URL for the external application. A best practice is to substitute the host's Virtual Name, the one that you defined in the Host Administration view, for the host's actual name. Doing this makes administering host names easier, because you might have many symbolic URLs pointing to one host. If the host name changes, then you only need to change it in the Host Administration applet rather than having to change it in several symbolic URL definitions. For example, https://Virtual_Host/path... NOTE:  Use the Secure Sockets Layer protocol (SSL) with symbolic URLs to ensure that communication is secure. For more information about using SSL, see Siebel Security Guide. For applications that use form-base authentication, the URL is identified by the action attribute of the <form> tag. For more information, see Determining the Login Requirements.
   Host Name	The Virtual Name of the host defined in the Host Administration view.
   Fixup Name	Name of the fixup type defined in the Fixup Administration view. The fixup type defines how links embedded in the external HTML content are rendered. For example: Default. Use this fixup type with the IFrame disposition type. Link fixup is inside the view. This fixup does not affect any of the links. The links (relative or absolute) remain as they are with the content being passed back in its original form. InsideApplet. This fixup converts all of the relative links to absolute links and any links using a host defined in the Host Administration view are proxied in order to maintain SWE context. OutsideApplication. This fixup converts all of the relative links to absolute links using the host and path of the parent URL. No links are proxied.
   Multivalue Treatment	Determines how arguments are handled. Possible values are: Comma Separated. Instructs SWE to insert a comma between the values defined in the symbolic URL arguments when appending the arguments to the URL. It inserts a comma after the value in the first Argument Value field and the first value in the second Argument Value field. The second Argument Value field is simply a text string entered by the user. Separate Arguments. Instructs SWE to enter separate arguments for each value defined in the two Argument Value fields. Use First Record Only. Uses the first record in the current record set.
   SSO Disposition	The value selected in this field determines how the HTTP request is constructed and sent and how the external content is rendered in the user interface. Possible values are: Inline. Proxies the request through the Siebel Server and displays content inline with other applets on a view. IFrame. Uses the <iframe> tag to display content inline with other applets on a view. Web Control. Uses an ActiveX control to display content inline with other applets on a view. Browsers displaying symbolic URLs of type Web Control must be set to handle ActiveX controls. For more information about browser security settings, see Siebel Security Guide. Form Redirect. SWE constructs a form which it sends back to the browser, which the browser then sends to the external host. The content received is displayed in a new window. Server Redirect. SWE sends the browser a 302 Response with the value of the external host's URL in the header. The browser is redirected to the external host. The content received is displayed in a new window. Note that for Server Redirect there is a required Symbolic URL argument. For more information, see Portal Agent Restrictions. For detailed descriptions of each disposition type, see About Portal Agents.
   Web Application Name	Associates a Web application with this symbolic URL. For more information about Web applications, see Defining Web Applications.

Defining Symbolic URL Arguments

Symbolic URL Arguments allow you to configure Portal Agents in several ways. You use symbolic URL arguments for two purposes, to define data to be sent to an external host and to submit commands to SWE that affect the behavior of Portal Agents.

When defining arguments that send data, such as authentication requirements, the Argument Name and Argument Value are appended to the URL as an attribute-value pair. You can define symbolic URL arguments that send data as constants or that dynamically retrieve data from the Siebel database. Symbolic URLs allow you to retrieve data from the user's instantiated Siebel business component, such as Service Request or Account, or retrieve data from the Siebel Personalization business component, such as the user's ZIP Code or Language.

For information about how to determine required data for applications that use form-based authentication, see Determining the Login Requirements.

Symbolic URL arguments also allow you to implement commands which you use to define the behavior of Portal Agents. For usage descriptions of available commands, see Portal Agent Command Reference.

This task is a step in Process of Creating Portal Agents.

To define symbolic URL arguments

1. Navigate to the Administration - Integration screen, and then WI Symbolic URL List.
2. From the drop-down menu, select Symbolic URL Administration.
3. In the Symbolic URL Administration list view, select the symbolic URL that you want to configure.
4. In the Symbolic URL Arguments form, enter the arguments that need to be sent to the external host.

   Some of the fields are defined in the following table:

   Field	Description
   Name	Name of the argument. For arguments of type Constant, Field, and Personalization Attribute, this field defines the exact field name expected by the external application. It is the first part of an attribute-value pair appended to the URL. For argument types of commands, the Name can usually be anything. The only exception to this is for the EncodeURL and PreloadURL commands. For more information, see Portal Agent Command Reference.
   Required Argument	When this field is checked (default) the argument must have a value. If you are configuring an argument that does not have a value, then uncheck the Required field. If an argument has no value and the Required field is checked, then the request is not sent because there is no value to append to the URL.
   Argument Type	The Argument Type determines the source of the data to be send along in the HTTP request. Possible values are: Constant. Sends the value defined in the Argument Value field in the request. Field. Sends the value of a single-value or multi-value field from the current Siebel business component. Profile Attribute. Sends the value of a field from the Siebel Personalization business component. URL Argument. Data comes from the named argument of the current request. Language Value. The user's current language setting; for example, ENU. Command. Implements commands that allow you to affect the behavior of the symbolic URL. For a complete list of commands, see Portal Agent Command Reference.
   Argument Value	The value of the argument varies depending on the Argument Type. Descriptions of possible values for each argument type are described here. If the Argument Type is one of the following: Constant. The Argument Value is the second part of the attribute-value pair that is appended to the URL. Field. The Argument Value defines a field name from the current business component. The data from this field is the second part of an attribute-value pair that is appended to the URL. Profile Attribute. The Argument Value defines a field name on the Siebel Personalization business component. The data from this field is the second part of an attribute-value pair that is appended to the URL URL Argument. The Argument Value defines the name of the argument on the incoming SWE request. Language Value. The Argument Value is left null. Command. The Argument Value typically defines the name of the command. For more information, see Portal Agent Command Reference.
   Append as Argument	When this field is checked (default), the value is added as a URL argument on the outgoing request. If this field is not checked, then the value is substituted in the text of the outgoing URL.
   Sequence	Determines the sequence of the arguments. In some cases the target host requires arguments in a particular order.

Configuring Multiple Symbolic URLs and Hosts for Alternative Execution Locations

You can configure multiple symbolic URLs and symbolic URL hosts, to execute applications in alternative locations (for example, for testing or demonstration purposes). This topic contains the following information:

• Configuring Alternative Symbolic URLs
• Configuring Alternative Symbolic URL Hosts

NOTE:  When you use an alternative symbolic URL host, all symbolic URLs in the application that are configured to use that host will use the alternative host name. In contrast, when you use alternative symbolic URLs, each symbolic URL used in the application must have its own alternative symbolic URL. Therefore, you can reduce the effort required to execute the application in an alternative location by using an alternative symbolic URL host rather than a symbolic URL.

Configuring Alternative Symbolic URLs

To use an alternative symbolic URL, define the additional symbolic URL at the Symbolic URL Administration view, and specify the following parameter in the [DataSources] section of the application's configuration file:

SymbolicURLSuffix. The value of this parameter is appended to the end of the name of the default symbolic URL to specify the name of the alternative symbolic URL.

For example, if the parameter SymbolicURLSuffix is set to _MyDemo in the application's configuration file, and the default symbolic URL name is AccountNews, then the symbolic URL that is used when the application is executed is AccountNews_MyDemo. The URL value associated with the AccountNews_MyDemo symbolic URL in the Symbolic URL Administration page is used.

NOTE:  When you define the alternative symbolic URL, its name must match the name of the existing symbolic URL with the value of the SymbolicURLSuffix parameter appended to it.

For more information about defining symbolic URLs, see Defining Symbolic URLs.

Configuring Alternative Symbolic URL Hosts

To use an alternative symbolic URL host, define the additional symbolic URL host at the Host Administration view, and specify the following parameter in the [DataSources] section of the application's configuration file:

SymbolicURLHostSuffix. This value is appended to the end of the name of the existing symbolic URL host to specify the name of the alternative symbolic URL host.

For example, if the parameter SymbolicURLHostSuffix is set to _demo in the application's configuration file, and the existing host name is ABC, then the new host name is ABC_demo. The host name value associated with ABC_demo in the Host Administration page is used.

NOTE:  When you define the alternative symbolic URL host, its name must match the name of the existing symbolic URL host with the value of the SymbolicURLHostSuffix parameter appended to it.

For more information about defining hosts, see Defining the External Host.

Defining Content Fixup

The Fixup Administration view allows you to define how links embedded within external HTML content are rendered in the Siebel user interface. The fixup types that you define here will be associated with symbolic URLs.

To define a fixup type

1. Navigate to the Administration - Integration screen, and then WI Symbolic URL List.
2. From the drop-down menu, select Fixup Administration.
3. Enter a new record and define the fields.

   Some of the fields are described in the following table:

   Field	Comments
   Link Context	Select one of the following values: Do Nothing. This fixup does not affect any of the links. The links (relative or absolute) remain as they are with the content being passed back in its original form. Outside Application. This fixup converts all of the relative links to absolute links using the host and path of the parent URL. No links are proxied. Inside Application. This fixup converts all of the relative links to absolute links and any links using a host defined in the Host Administration view are proxied in order to maintain SWE context. After the user clicks a link, this fixup type renders HTML in the view, using the entire view for display. Inside Applet. This fixup handles links the same way as the Inside Application fixup type. However, in this case, when a user clicks a link, it renders HTML within an applet. The other applets remain present on the view.
   Context View Name	Name of the view that displays the link. This is optional.
   Link Target	Specifies the name of a specific target frame of the link. For example, _blank for a new browser window or AnyName to open a window of that name. This option is not often used.

NOTE:  Fixup is required for all links.

Defining End-User Login Credentials

The Portal Framework provides a mechanism to store user login credentials for external Web applications. The SSO Systems Administration view allows you to specify an external application and then enter login credentials on behalf of users. The My Logins view, located in the User Preferences screen, is used by end users to maintain their own credentials.

To specify an external Web application and define login credentials

1. Navigate to the Administration - Integration screen, and then SSO Systems Admin List.
2. In the SSO Systems list, enter a new record and define the following:

   Field	Description
   System Name	Name of the external Web application.
   Symbolic URL Name	Select the name of the symbolic URL that interacts with the external Web application. The symbolic URL must be configured with the UserLoginId Command and UserLoginPassword Command commands as arguments. These arguments instruct the symbolic URL to pass the stored login credentials when authenticating with an external Web application.
   Description	Enter a description of the Web application.

3. If you are defining login credentials on behalf of end users, then, in the SSO System Users list, enter end-user login names and passwords.

Example Portal Agent

This topic provides an example of using a symbolic URL to integrate content from an external site. The high-level steps to do this are:

1. Review the Login Form.
2. Define the External Host.
3. Define the Symbolic URL.
4. Define Symbolic URL Arguments.
5. Define User Login Credentials.
6. Testing the Integration.

Each of these steps is described in the topics that follow. This example uses www.example.com, which does not have the login page and other elements described here; substitute your actual site.

NOTE:  This example assumes that the underlying objects are already configured to support the symbolic URL. For more information, see Portal Agent Configuration.

Review the Login Form

By reviewing the login page at www.example.com, you can determine the target URL of the Action attribute and the required arguments that are being passed to the Web application. Assume that www.example.com has a login page that contains the following <form> and <input> tags:

<form action="/index.shtm" method="POST" name="frmPassLogin" onsubmit="return logincheck();">

<input TYPE="TEXT" NAME="SearchString" SIZE="18" MAXLENGTH="100" VALUE="">

<input type="hidden" value="All" name="sc">

<input type="hidden" value="ON" name="FreeText">

<input type="image" src="/images/nav/button/bttn_form_arrow.gif" NAME="Action" border="0"/ alt="Submit Search"></td>

<input type="text" name="username" size="18">

<input type="password" name="password" size="18">

<input type="image" src="/images/nav/button/bttn_form_arrow.gif" border="0" name='login' />

<input type="checkbox" name="remember" checked/>&nbsp;<span class="bdDkGray">Remember my Login<br></span

</form>

From the action attribute of the <form> tag, you can determine that the target URL is relative to the root of the login page's URL. Therefore, the target URL is:

www.example.com/index.shtm

You can also determine that the method attribute of the <form> tag is POST:

method="POST"

After reviewing the <input> tags, you can determine that the required arguments are:

username

password

NOTE:  Notice that not all input fields are necessary for login.

For more information about reviewing login forms, see Determining the Login Requirements.

Define the External Host

The external host is simply the address of the login page. In this example, it is www.example.com. Be sure to provide a meaningful name in the Virtual Host Name field. This value is used instead of the actual host name when you define the symbolic URL. This makes administration easier if the host name changes. Also notice that there is no value for the Authentication Type.

Figure 39 shows the external host defined for this example.

Figure 39. External Host Administration

For more information, see Defining the External Host.

Define the Symbolic URL

After you define the external host, you can define the symbolic URL. Notice that the URL defined here uses the Virtual Name of the host, not the actual name. Also notice that, when you select the external host from the Host Name field, it is populated with the actual host name. When SWE constructs the URL, it substitutes the actual Host Name for the Virtual Name in the URL. In this example, the fixup type is Default, because the page is displayed in the browser using the <iframe> tag and therefore, it is recommended that links not be fixed up in any way.

Figure 40 shows the symbolic URL defined for this example.

Figure 40. Symbolic URL

For more information about defining symbolic URLs, see Defining Symbolic URLs.

Define Symbolic URL Arguments

You use symbolic URL Arguments to define the information that you want to append as arguments to the URL. You also use symbolic URL arguments to define commands that you want to execute. In this case, the following arguments are required:

• PostRequest. This command instructs SWE to submit the request using a POST method rather than GET, which is the default. In this case, you know that POST is required because the method attribute of the <form> tag specifies POST.
• UserLoginPassword. This command instructs SWE to retrieve the password stored for the user and pass it to the external application. The name of this argument is the name of the input field expected by the external application. In this case, it is password.
• UserLoginID. This command instructs SWE to retrieve the stored login name for the user and pass it to the external application. The name of this argument is the name of the input field expected by the external application. In this case, it is username.

Figure 41 shows the symbolic URL arguments defined for this example.

Figure 41. Symbolic URL Arguments

For more information about symbolic URL arguments, see Defining Symbolic URL Arguments. For more information about symbolic URL commands, see Portal Agent Command Reference.

Define User Login Credentials

Finally you must define login credentials for a user. The values defined here are appended as arguments to the URL constructed by SWE. In this case, the following user name and password are defined:

• The user name is Joe_Smith@example.com.
• The password is abracadabra.

Testing the Integration

After completing the previous steps, you can test the integration.

To test the integration

1. Log out of the application.
2. Log back in as the test user.
3. Navigate to the applet or Web page item that is associated with the symbolic URL.

   Content from the external host, in this case example.com, is displayed in the Siebel user interface.

Reviewing the SWE Log File

Reviewing the SWE log file can help you to debug errors in your Portal Agent configuration.

• The location of the log file is SIEBSRVR_ROOT\log.
• The name of the log files are swelog_pid.txt and sweusage_pid.txt, where pid is the process ID of the corresponding Siebel process.

For more information about log files and about configuring log levels, see Siebel System Monitoring and Diagnostics Guide.

Portal Agent Command Reference

Portal Agent commands allow you to carry out actions such as use a set of stored credentials for authentication or define additional attributes for the <iframe> tag. These commands are entered as symbolic URL arguments. For more information, see Defining Symbolic URLs.

The following commands are described in this topic:

• EncodeURL Command
• FreePopup Command
• IFrame Command
• IsRecordSensitive Command
• NoCache Command
• NoFormFixup Command
• PreLoadURL Command
• PostRequest Command
• UserLoginId Command
• UserLoginPassword Command
• UseSiebelLoginId Command
• UseSiebelLoginPassword Command

EncodeURL Command

Use the EncodeURL command to specify whether to encode arguments appended to the symbolic URL. By default, the URL is encoded. However, some servers do not recognize standard encoding, in which case you can use this command to not encode the URL.

Define the fields in the Symbolic Arguments applet. See Table 16.

FreePopup Command

Use the FreePopup command to show portal contents in a popup window.

The symbolic URL contains the FreePopup command, it notifies the client that the popup is a free one and the client displays the contents in the popup window.

FreePopup is supported for FormRedirect, the only disposition type available for opening a portlet in a popup.

To start the external application as a full browser window, use the values in Table 17.

To start the external application as a modal window, use the values in Table 18.

IFrame Command

Use the IFrame command to define additional HTML attributes for the <iframe> tag.

Define the fields in the Symbolic URL Arguments applet. See Table 19.

Disposition Types

Use the IFrame command with the IFrame disposition type.

IsRecordSensitive Command

Use the IsRecordSensitive command to turn on or off the record-sensitive feature. Set the value to TRUE to ensure that a child applet with a symbolic URL is refreshed on the parent record, for instance, when you embed an Analytics report as a child applet with a requirement that it display contextual information.

This command is turned off by default. Set this argument value to TRUE in the Symbolic URL Arguments configuration.

Define the fields in the Symbolic URL Arguments applet. See Table 20.

NoCache Command

Use the NoCache command to instruct SWE not to cache Inline responses on the server. This command is only valid for the Inline disposition type.

Define the fields in the Symbolic URL Arguments applet. See Table 21.

NoFormFixup Command

Use the NoFormFixup command to instruct SWE not to fix up a form by putting proxy SWE arguments into links that appear on the page.

Define the fields in the Symbolic URL Arguments applet. See Table 22.

PreLoadURL Command

Use this command to specify a preloaded URL. Use this command when the external application gathers information from a preloaded cookie on the client machine. Use this command with disposition types of IFrame and Web Control.

Define the fields in the Symbolic URL Arguments applet. See Table 23.

PostRequest Command

Use PostRequest to configure the Portal Agent to use the POST method instead of the GET method, which is the default. Use this command when the method of the action attribute is POST. This method avoids displaying user information on a Web page or browser status bar. Use this command with disposition types of IFrame and Web Control only.

Define the fields in the Symbolic URL Arguments applet. See Table 24.

UserLoginId Command

Use the UserLoginId command to send the stored user login ID for a particular Web application. The command gets the user's Login ID from the My Login Credential business component.

For more information about how user login IDs are entered into this business component, see Defining End-User Login Credentials.

Define the fields in the Symbolic URL Arguments applet. See Table 25.

UserLoginPassword Command

Use the UserLoginPassword command to send the stored user password for a particular Web application. The command gets the user's password from the My Login Credential business component.

For more information about how user passwords are entered into this business component, see Defining End-User Login Credentials.

Define the fields in the Symbolic URL Arguments applet. See Table 26.

UseSiebelLoginId Command

Use the UseSiebelLoginId command to retrieve the user's Siebel login ID from the stored set of credentials.

Define the fields in the Symbolic URL Arguments applet. See Table 27.

UseSiebelLoginPassword Command

Use the UseSiebelLoginPassword command to retrieve the user's Siebel password from the stored set of credentials.

Define the fields in the Symbolic URL Arguments applet. See Table 28.