Displaying Data from Siebel Open UI in External Applications

This topic describes how to display data from Siebel Open UI in an external application. It includes the following information:

"Displaying Siebel Portlets In External Applications"
"Configuring Advanced Options"
"Configuring Communications with Siebel Portlets When Hosted Inside iFrame"
"Additional Considerations"
"Limitations"
"Preparing Standalone Applets"
"Using iFrame Gadgets to Display Siebel CRM Applets in External Applications"

Siebel Open UI comes predefined to display Siebel CRM data only in a Siebel application, such as Siebel Call Center. This topic describes how to display Siebel CRM data in an external application or website, such as Oracle WebCenter or iGoogle.

Displaying Siebel Portlets In External Applications

You can configure Siebel Open UI to display a Siebel portlet. A Siebel portlet is a Siebel Open UI application that is embedded in a thirty-party Web site. Oracle WebCenter and iGoogle are examples of these types of third-party Web sites. An HMTL iFrame is used in these Web sites to display part of the Siebel application in a portlet window.

This topic describes how to display Siebel portlets in external applications. It includes the following information:

"Configuring Siebel Open UI to Consume Siebel Portlets"
"About Siebel Portlet Authentication and Security Requirements"
"Configuring Views to be Embedded in a Portal"
"Configuring Standalone Applets to be Embedded in a Portal"
"Configuring View-Based Applets to be Embedded in a Portlet"

Configuring Siebel Open UI to Consume Siebel Portlets

Siebel portlets can be integrated inside a portal application using iFrame or any other mechanism supported by the portal application. Siebel accepts both GET and POST requests.

To make a Siebel portlet available as part of a portal, you can add the portlet URL to an iFrame that resides on the main Web page. In this sample code, the HTTP GET method is used:

<HTML>
  <BODY>
    <IFRAME src = "http://server_address/application/start.swe?SWECmd=SWECmd=GotoView&IsPortlet =1&other_arguments"> </IFRAME>
  </BODY>
</HTML>

where:

server_address specifies the address of the Siebel Server.
application specifies the Siebel application.
SWECmd is a required argument that specifies how to display the Siebel application when the user accesses this URL.
isPortlet is a required argument that informs the Siebel Server that this application runs in a portlet. The server requires this argument so that it can do the processing it requires to support a portlet.
other_arguments specify how to display the Siebel application. For example, the login requirements to display, the applets to display, how to size applets, and so on.

For example, consider the following iFrame src:

http://server_name.example.com/callcenter_enu/start.swe? SWECmd=GetApplet&SWEApplet=Quote+List+Applet&IsPortlet =1&SWESM=Edit+List"style="height: 50%;width: 100%;&KeepAlive=1&PtId=my_theme"

Table 8-1 describes the parts of this iFrame src that specify the Siebel URL.

Table 8-1 Specifying URLs to Siebel Portlets

URL Argument	Description
http://server_name.example.com	Access the Siebel Server that resides at server_name.example.com.
/callcenter_enu	Run the CallCenter application.
/start.swe?	Start the Siebel Web Engine.
SWECmd=GetApplet	Provide commands to the Siebel Web Engine.
SWEApplet=Quote+List+Applet	Display the Quote List Applet.
IsPortlet =1	Run the CallCenter application as a portlet.
SWESM=Edit+List	Use the Edit List Mode
KeepAlive=1	Keep Siebel portlet sessions active even if the session is idle longer than SessionTimeout. Siebel CRM is predefined to expire a Siebel session that is not in use for a period of time according to the value that the SessionTimeout server parameter specifies. In the absence of this parameter, the session timing out will lead to Siebel Open UI displaying a login dialog box in the portlet. This behavior might not be desirable in a Siebel portlet. It is recommended that you set this argument to keep the session active. For more information about the KeepAlive parameter, see "Configuring the Portlet Session to Stay Alive".
&PtId=my_theme"	You can style a portlet application in such a way that the look and feel of the exposed application match that of the portal. The iFrame itself can be styled using a Cascading Style Sheet. For more information, see "Configuring the Use of Cascading Style Sheets Instead of iFrame Attributes". In addition, the Siebel application can be styled according to a theme. A theme can be defined in the Siebel manifest, and the PtId argument can be used to reference the theme. The theme defined will be applied to the exposed application.
SWECmd=ExecuteLogin &SWEUserName=user_name&SWEPassword=my_password	Provide user name and password authentication arguments. ExecuteLogin is allowed only through HTTP POST. For security reasons, passing user IDs and passwords in an HTTP request is not recommended. For more information, see "About Siebel Portlet Authentication and Security Requirements".

Siebel Open UI supports HTTP POST and exposes the Siebel portlet for HTTP POST requests. The Siebel portal can send the following URL with the listed form fields:

http://server_name.example.com/callcenter_enu/start.swe
SWECmd=ExecuteLogin
SWEUserName=user_name
SWEPassword=my_password
SWEAC=SWECmd=GetApplet
SWEApplet=Quote+List+Applet
IsPortlet =1
KeepAlive=1
PtId=my_theme"

About Siebel Portlet Authentication and Security Requirements

Siebel Open UI portlets must be configured differently depending on whether the application is hosted in HTTP and in HTTPS. The recommended configuration guidelines are as follows:

HTTP. Implement SSO and access Siebel over HTTP or HTTPS, depending on the requirement.
HTTPS. Implement SSO and enable SSL for Siebel.

WARNING:

You should never pass user IDs and passwords in the HTTP request to a Siebel portlet. Passing user IDs and passwords exposes authentication details to the end user.

Configuring Views to be Embedded in a Portal

You can allow a view to be embedded in a portal. When configured, a specified view of the Siebel application is displayed in the portal. The view specified must be accessible anonymously or by the user who is logged in to the Siebel Open UI client.

To allow a view to be embedded in a portal, include the following command in the URL:

SWECmd=GotoView; SWEView=<View Name>; ]

The full URL should use the conventions in the following example:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=<View Name>

For example, with the Opportunities List View embedded in a portal, the URL would use the conventions in the following URL:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=Opportunities+List+View

Configuring Standalone Applets to be Embedded in a Portal

Siebel Open UI supports standalone applets. You can expose standalone applets in a portal. This can be achieved by providing the following GetApplet command in the URL:

SWECmd=GetApplet; SWEApplet=<Standalone Applet Name>; SWESM=<Applet's Show Mode>

About the SWESM Parameter

The applet show mode can be modified by setting the SWESM parameter value to one of the following preconfigured modes for the applet:

Base
Edit
Edit List
Query

The full URL should use the conventions in the following example:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GetApplet&SWEApplet=Opportunity+List+Applet&SWESM=Base

About Search Specifications

When using standalone applets in portals, the data displayed in the standalone applet can be controlled by using search specifications. The search specifications are applied to various Business Component fields on which the standalone applet is deployed. You can control the search specifications using the following parameters:

BCField<n>. Defines the business component field on which to query.
BCFieldValue<n>. Defines the value that the BCField<n> must match for the record to be displayed.
PBCField<n>. Defines the parent business component field on which to query.
PBCFieldValue<n>. Defines the value that the PBCField<n> must match for the record to be displayed.

For example, if you wanted to specify the Opportunities List applet embedded in a portal and limit the records displayed to Opportunity Names that match ”Test Opportunity” you could use the following URL:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GetApplet&SWEApplet=Opportunity+List+Applet&SWESM=Base&BCField0=Opportunity+Name&BCFieldValue0=Test+Opportunity

Search Specifications Guidelines

Follow these additional guidelines when defining your search specifications:

When specifying multiple business component fields or parent business component fields, use the AND operator at the end of the final expression. Only records that satisfy all of the matching criteria are returned by the search.
Field values can contain any type of data that is accepted by the Siebel search specification system. For example, ”PBCFieldValue2=Opportunity1+OR+Opportunity2” is a valid value.
Field values not exposed in the applet can still be used by the URL. The fields in the business component to which the applet refers will be explicitly activated and used for the query.
Search specifications applied to a URL will work in context. Therefore, the user will not be able to access the super-set of records, unless the user navigates to the view in question.
If a parent business component field and parent business component field value is configured in a URL, and the business component does not have a parent business component, then the specification is ignored.
If a business component field is used in the URL that does not exist on the business component, then the URL is considered invalid and the applet will fail to build. This results in unpredictable behavior in the portal.

Configuring View-Based Applets to be Embedded in a Portlet

When an applet has been configured part of a view rather than as a standalone applet, it can still be exposed in a portlet. To do this, use the GotoView command with the following additional parameters:

SWECmd=GotoView; SWEView=<View_Name>; SWEApplet=<Applet_Name>

Only the applet specified in the portlet will be embedded in the portlet. For example, only the Opportunity List Applet will be shown using the following URL:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=Opportunity+List+View&SWEApplet=Opportunity+List+Applet

Note:

If an applet that does not exist in the view is specified, then the URL is considered invalid and the applet will fail to build. This results in unpredictable behavior in the portlet.

Configuring Advanced Options

This topic describes advanced options when configuring Siebel Open UI in an external application. It includes the following information:

"Configuring Multiple Command Chaining in a URL"
"Configuring the Portlet Session to Stay Alive"
"Configuring the Use of Cascading Style Sheets Instead of iFrame Attributes"

Configuring Multiple Command Chaining in a URL

Use the SWEAC parameter to chain more than one command in a URL. An example, where this might be useful is a situation where you want to navigate to a certain view and create a new record in that view's active applet.

To configure multiple command chaining in a URL, include the following attribute in the URL:

SWEAC=SWECmd=NewRecord]

The full URL should use the conventions in the following example:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=Opportunities+List+View&SWEAC=SWECmd=NewRecord

The preceding example runs the Siebel application in the portlet and takes the context to the Opportunity View to create a new record in the active applet on that view.

Configuring the Portlet Session to Stay Alive

Siebel sessions that are not in use will eventually expire. The time for which the session is kept alive is determined by the value of SessionTimeout Siebel server parameter. In some cases when exposing Siebel as a portlet expiring sessions this might not be optimal.

To override the SessionTimeout Siebel parameter so that the portlet session stays alive, include the following attribute in the URL:

KeepAlive=1

Other values for this parameter are as follows: TRUE, T, ON, and Y.

The full URL should use the conventions in the following example:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=Contact+List+View&KeepAlive=1

When using the KeepAlive attribute, consider these additional guidelines:

The KeepAlive attribute value is enforced by monitoring periodic client pings to the Siebel server. Consequently, the client must be on a network connected to the server.
If the KeepAlive attribute value is omitted or set to FALSE the session will eventually timeout and a login screen is returned to the portlet.
Once the KeepAlive attribute is set to TRUE by a request (either the URL or a subsequent message-based communication) it cannot be changed to FALSE by a subsequent request.

Configuring the Use of Cascading Style Sheets Instead of iFrame Attributes

The iFrame tag supports a number of attributes, which can be used to control the visual formatting of the portlet content. For a full list of the attributes, see the following W3C website:

http://www.w3.org/wiki/HTML/Elements/iframe

In recent HTML revisions, many attributes are being deprecated. Consequently, it is recommended that cascading style sheets be used for visual formatting.

Siebel Open UI attaches CSS classes for the portlet iFrame. In Siebel Open UI, the CSS can be applied by defining a theme in the Theme.js file and passing the theme name as a parameter in the URL under PtId.

The full URL should use the conventions in the following example:

http://<siebel_server>/<application>/start.swe?IsPortlet =1&SWECmd=GotoView&SWEView=Contact+List+View&KeepAlive=1&PtId=CUSTOM_PORTLET_THEME

Where CUSTOM_PORTLET_THEME is defined in Theme.js. If the argument value is omitted, invalid, or cannot be found in Theme.js, then the Siebel Open UI will use the default theme.

For more information about customizing themes, see "Customizing Themes".

Configuring Communications with Siebel Portlets When Hosted Inside iFrame

This topic outlines the Siebel server parameter configurations to enable communication with Siebel portlets when hosted inside iFrame. These parameters can be modified for the Siebel component with which the functionality is meant to communicate. The instructions in this topic are not required when cross-domain communications are not needed.

To configure communications with Siebel portlets when hosted inside iFrame

Set up the Siebel server parameters:

Log in to a Siebel client with administrative privileges.
Navigate to the Administration - Server Configuration screen, and then the Servers view.
In the Siebel Servers list, choose a Siebel Server.
In the Components list, select the component that you want to expose as a portlet

In the Component Parameters list, add the following parameters.

Parameter	Description
PortletAPIKey	This is a required parameter. It is a unique key configured as a server parameter. The source portal program will need to pass this key, in order to be able to invoke a call on the Siebel application exposed as the portlet. The messaging object used to communicate with Siebel Portal will need to contain a parameter msg.Key. The msg.Key must match the key configured in this parameter. If the messaging object does not contain a key, or contains an invalid one, the invocation will result in an error in the Siebel portlet.
PortletOriginList	This is a required parameter. It defines the list of valid domains from which the Siebel portlet will accept a communication request. A comma separated list can be provided for this parameter. Any invocations coming from domains that are not listed here will cause an error in the Siebel portlet.
PortletMaxAllowedAttempts	This is an optional parameter. Its default value is 3. This parameter specifies the number of unsuccessful communication attempts with the portlet before Siebel Open UI blocks any subsequent calls. An unsuccessful call can occur in the following situations: A domain attempts to send a communication request to the portlet, but the PortletOriginList does not specify this domain. The portlet_key sent by the communicating domain does not match the parameter specified in the Siebel server. The Siebel portal will remain blocked up to the time extent as defined by PortletBlockedInterval after which the Siebel Open UI resets the unsuccessful attempts to zero.
PortletBlockedInterval	This is an optional parameter. Its default value is 900 seconds. This parameter specifies the time in seconds for which Siebel portlet will remain blocked to any communication attempt from the hosting portal or a neighboring portlet after having exceeded the number of unsuccessful communication attempts (as defined by PortletMaxAllowedAttempts). During this time, the Siebel portlet will still be open to access by the user of the application. However, no programmatic access is permitted.

Based on your configuration, the portal, or another portlet in the portal, add the following object to your custom code:
```
var msg = new Object();
msg.SWEView = view_name;
msg.SWEApplet = applet_name;
msg.SWECmd =GotoView or GetApplet
msg.Key = portlet_key;
```
Note:
The SWEView, SWEApplet, and Key arguments are required. All other arguments are optional.

where:
- view_name specifies the view that Siebel Open UI displays in the portlet window. If you specify only the view, then Siebel Open UI displays the view and all the applets that this view contains.
- applet_name specifies the applet that Siebel Open UI displays in the portlet window. If you specify only the applet, then Siebel Open UI displays only this applet and no view. If you specify the view and applet, then Siebel Open UI displays the applet in the view.
- GotoView or GetApplet specifies whether or not to display a view or an applet in the portlet window.
- portlet_key must specify the value that you specify for the PortletAPIKey server parameter in Step 1. The Siebel client sends this value to the Siebel Server when it calls a Siebel application. You must include the msg.Key argument, and the value of this argument must match the value of the key that the PortletAPIKey server parameter contains on the Siebel Server. If the messaging object does not contain a key, or if it contains a key that does match the value of the server parameter, then Siebel Open UI displays an error in the Siebel portlet.
For example, the following code displays the Opportunity List Applet inside the Opportunity List View:
```
var msg = new Object();
msg.SWEView = Opportunity List View;
msg.SWEApplet = Opportunity List Applet;
msg.Key = oracle123;
```
Add the following code immediately after the code that you added in Step 2.
```
document.getElementById('siebelframeid').contentWindow.postMessage(msg, '*');
```
This code invokes a change in the Siebel Portlet window, so that the requested view or applet will get loaded in the content area.
You can use SWE commands to display a Siebel portlet in Siebel Open UI. For security reasons, you can use only the GotoView and GetApplet method to call a Siebel portlet from an external application. GotoPage and GotoPageTab are not applicable to Siebel Open UI. For more information, see the topic describing SWE commands available in Siebel Open UI in Siebel Portal Framework Guide.

Additional Considerations

The following list outlines additional considerations when displaying data from Siebel Open UI in external applications:

All parameters passed in a URL need to be URL-encoded. For example, ”Account List View” would become ”Account+List+View” or ”Account%20List%20View”. For more information on URL encoding, refer to:

http://en.wikipedia.org/wiki/Percent-encoding
Anonymous sessions are supported in portlet expositions.
Tasks and workflow URLs are also supported in portlets.
SWE Commands are limited to the ones mentioned in step 4 of "Configuring Communications with Siebel Portlets When Hosted Inside iFrame". However, other parameters may be passed in portlet mode to the Siebel server. They will be honored by the server depending on the context.
If the content in the Siebel portlet is bootstrapped to load an applet using the GetApplet method, then the subsequent messaging to the portlet will be limited to whether the applet can be invoked. Operations such as invoking of popups or navigating to other views will not be supported. If these are required, the portlet must be bootstrapped via the GotoView call. For more information, see "Configuring Standalone Applets to be Embedded in a Portal".

Limitations

The following list outlines limitations when displaying data from Siebel Open UI in external applications:

Siebel supports only one portlet in a valid Siebel session. Consuming more than one portlet that is targeted to the same Siebel session is not supported.
Opening Siebel Open UI in multiple browser tabs that share the same Siebel session ID is not supported.
Portal communications as described in "Configuring Communications with Siebel Portlets When Hosted Inside iFrame", is not supported in any version of Microsoft Internet Explorer. Siebel Open UI uses HTML 5 specified Cross Document Messaging, that is not fully supported in the latest version of Internet Explorer.

Preparing Standalone Applets

A standalone applet is a type of applet that Siebel Open UI can display outside the context of a Siebel CRM view. A predefined view references a business object, a business object references a business component, and an applet also references a business component, but an applet does not reference a business object in a predefined Siebel Open UI configuration. You must modify this configuration so that the applet can work independently of the view. To do this, you configure the applet to directly reference the business object.

To prepare standalone applets

Open Siebel Tools.

For more information, see Using Siebel Tools.
In the Object Explorer, click Applet.
In the Applets list, query the Name property for the applet that Siebel Open UI must display outside of the view.
In the Object Explorer, expand the Applet tree, and then click Applet User Prop.
In the Applet User Properties list, add the following applet user property.
Property Description
Name Enter the following value:
Business Object
Value Enter the name of the business object that this applet must reference.

Property	Description
Name	Enter the following value: Business Object
Value	Enter the name of the business object that this applet must reference.

Using iFrame Gadgets to Display Siebel CRM Applets in External Applications

The example in this topic describes how to use iFrame gadgets to configure Siebel Open UI to display a Siebel applet in an external application.

Siebel Open UI must be configured to use Web Single Sign-On (SSO) authentication. For more information, see the topic that describes the web single sign-on authentication in Siebel Security Guide.

A Siebel portlet can be exposed to a portal from an anonymous session when SSO is not configured. This example details the use case for exposing a Siebel application to a portal from an anonymous Siebel session.

To use iFrame gadgets to display Siebel CRM applets in external applications

Do the setup:
1. Create a LinkedIn profile at the http://www.linked.com Web site.
2. Create a Gmail profile at the http://www.google.com/ig Web site.
Configure the external applications:
1. Open a new browser session, navigate to http://www.linked.com/, and then log in to your profile:
2. Open a new browser tab, navigate to http://www.google.com/ig, and then log in to your Gmail profile:
3. Navigate to http://www.google.com/ig/settings.
4. Click Add More Gadgets.
5. In the Search for Gadgets section, enter iFrame Gadget, and then click Search.
6. In the Search Results for the iFrame Gadget list, click iFrame Gadget.
7. Click Embed This Gadget.
8. In the Add This Gadget to Your Webpage page, enter the following URL that Siebel Open UI uses to display the applet. You enter this URL into the Address of Page to Show field:
```
http://server_name/callcenter_enu/start.swe?SWECmd=ExecuteLogin&SWEAC=SWECmd=GotoView&SWEView=view_name&IsPortlet=1&SWEApplet=applet_name
```
  where:
  - server_name identifies the name of the server.
  - view_name identifies the name of the view that contains the applet.
  - applet_name identifies the applet that Siebel Open UI must display in the external application.
  For example, you enter the following URL to display the Opportunity list applet:
```
http://server_name.example.com/callcenter_enu/start.swe?SWECmd=ExecuteLogin&SWEAC=SWECmd=GotoView&SWEView=Opportunity+List+View&IsPortlet=1&SWEApplet=Opportunity+List+Applet
```
  Note:
  This URL will work for anonymous sessions in which the user has the required permissions to access Opportunity List view.
9. Click Preview Changes.
10. Click Save.
Test your modifications:
1. Verify that iGoogle refreshes the page and displays the Opportunity list.
2. Expand the widget to full screen to display the full width of the list.
3. To choose a LinkedIn contact, use the menu that Google displays on the list header on the right side of the screen.
4. Verify that the Web browser displays the opportunities for the contact that you choose.
5. Verify that the chosen LinkedIn contact matches a Siebel contact record.
  
  Make sure the Web browser displays a layout that is similar to the following layout.