End users with appropriate privileges can modify personal and shared dashboards, including the addition of pages and content. End users cannot create analyses and dashboards.
This chapter includes the following sections:
Before you create shared dashboards, ensure that you have planned the Oracle BI Presentation Catalog directory or folder structure and security strategy.
In general, to create a shared dashboard, you first create the dashboard and add content using the Dashboard Builder. You can also assign permissions to access the dashboard. Users who are members of multiple application roles can select the dashboard that they display by default from all of the dashboards to which they have permissions.
The following list provides other resources with information about dashboards:
Guidelines for creating a shared dashboard, within the broader context of the Oracle BI Presentation Catalog structure and security framework, are provided in Controlling Access to Saved Customization Options in Dashboards in Security Guide for Oracle Business Intelligence Enterprise Edition.
Information about shared folder structures in the Oracle BI Presentation Catalog is provided in Configuring and Managing the Oracle BI Presentation Catalog.
Information about permissions is provided in Security Guide for Oracle Business Intelligence Enterprise Edition.
Details for enabling users to act for others, which allows them to access the other users' dashboards, is provided in Enabling Users to Act for Others in Security Guide for Oracle Business Intelligence Enterprise Edition.
This section describes general tasks that you can perform to configure for the creation of analyses.
It includes the following sections:
Various options are available for exporting the results of analyses, for example, exporting to Microsoft Excel.
These options are described in Exporting Results in User's Guide for Oracle Business Intelligence Enterprise Edition. While users can export directly to an Excel format, they might notice greater performance when exporting large numbers of rows if they export first to CSV, then import that file into Excel.
If a user exports a large data set without using the CSV format and get an out-of-memory error, they should increase the heap size for the JavaHost service. The default heap size is 1024MB. Depending on the available memory on the computer, you might want to increase the heap size for the JavaHost service.
You can configure various options that change how the results of analyses or views are exported.
The following table describes the elements for manually configuring for export.
Element | Description | Default Value |
---|---|---|
DataValue |
Specifies whether data values (that is, numbers and dates) are exported in raw format with full number precision and format mask or as a string in the data format specified when exporting to Excel. Valid values are:
The export type is: xsi:type="excel" |
UseRawValue |
RepeatRows |
Specifies whether cells that span rows and cells that span columns are to be repeated when exporting tables and pivot tables to Excel. If set to true, then cells that span rows and cells that span columns are repeated, regardless of the Value Suppression setting in the Analysis editor. For example, in a table that has Year and Month values, Year is repeated for all Month values. If set to false, then the behavior is the same as that defined by the Value Suppression option in the Analysis editor:
For more information on the Value Suppression option, see User's Guide for Oracle Business Intelligence Enterprise Edition The export type is: xsi:type="excel" |
false |
Delimiter |
Specifies the column delimiter character for the CSV Format option, for example, a semicolon (;), when exporting raw data from results and views. The export type is: xsi:type="formattedText" |
"," |
KeepRowsTogether |
Specifies whether rows are to be kept together at page breaks when exporting to PDF. If set to true, rows are kept together at page breaks. If set to false, rows are split across page breaks. The export type is: xsi:type="pdf" |
false |
Orientation |
Specifies the orientation (either Portrait or Landscape) when exporting to PDF and to Powerpoint. The export type for PDF exports is: xsi:type="pdf" The export type for Powerpoint exports is: xsi:type="ppt" |
Landscape (for PDF exports) Portrait (for Powerpoint exports) |
QuoteTxtTab |
Adds quotes for the CSV Format option. When set to false, no quotes are added. The export type is: xsi:type="formattedText" |
true |
The administrator can set up subject areas in ways that assist content designers who work with analyses.
Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition provides complete information about setting up subject areas. The following list includes features of subject areas that assist content designers:
To make selections easy for content designers to discern in the Subject Areas pane when creating analyses, the administrator can set up the Presentation layer in the Oracle BI Administration Tool to give the appearance of nested folders. For example, the administrator can make the Sales Facts folder appear as a subfolder in the Facts folder.
When content designers create analyses, they can enable users to go to related analyses and content. If the administrator sets up dimensions and dimensional hierarchies for the subject area, then users can drill down on data results that are presented in graphs, tables, and pivot tables to obtain more detailed information.
There are no specific privilege settings that control access to navigation and drill-down features, which are available to all users.
Content designers can create analyses that include columns from a primary subject area and from one or more related subject areas.
You can configure various options that change the display and processing of data in views.
See also Using Fusion Middleware Control to Set Configuration Options for Data in Tables and Pivot Tables and Using Fusion Middleware Control to Set the Maximum Number of Rows Processed to Render a Table View.
This section contains the following topics:
You can configure various options that change the processing and display of data in views.
See the following sections:
You can use settings within the Cube element to affect the display and processing of data in pivot tables and graphs. The settings also take effect for XMLA export.
You can configure a similar group of settings that affects the display of data in table, pivot table, graph, trellis, narrative, ticker, and treemap views.
While the settings are often the same, you must include the element within each appropriate parent element to override the default setting that applies to that view. For example, many of the views use the MaxVisiblePages element. You must include that element within each of the Table, Pivot, Trellis, Charts, and Treemap parent elements, to override the default value of that setting for each of those view types.
The table below describes the common elements that affect the display of data in views. If the user exceeds these values, then the Oracle BI Server returns an error message when the view is rendered.
Element | Description | Default Value | Applicable Views |
---|---|---|---|
DefaultRowsDisplayed |
Specifies the default number of rows to display in views in analyses and dashboards. This number should not exceed the number that is specified for the MaxVisibleRows element. |
30 (10 for Simple Trellis) |
Narrative, Pivot Table, Table, Trellis |
DefaultRowsDisplayedInDelivery |
Specifies the default number of rows that can be included in the view when it is displayed on a dashboard. |
100 for Simple Trellis; 250 for Advanced Trellis, Table, and Pivot Table |
Pivot Table, Table, Trellis |
DefaultRowsDisplayedInDownload |
Specifies the default number of rows that can be included in the view when it is downloaded, such as to a PDF file. |
65000 (6500 for Simple Trellis; 10000 for Advanced Trellis) |
Pivot Table, Table, Trellis |
DefaultRowsDisplayedInDownloadCSV |
Specifies the default number of rows that can be included in the view when it is downloaded to a CSV file. For this to work, ODBC |
1048576 |
Table |
MaxCells |
Specifies the maximum number of cells or for a treemap, the maximum number of groups and tiles, to be displayed in a view. For pivot tables, tables, and trellises, this number should not exceed the product of MaxVisibleColumns times MaxVisibleRows, which is what the system attempts to render. |
50000 (1000 for Simple Trellis; 5000 for Treemap) |
Pivot Table, Table, Trellis, Treemap |
MaxPagesToRollOutInDelivery |
Specifies the maximum number of pages that can be included in the view when it is displayed on a dashboard. |
1000 |
Pivot Table, Table, Trellis |
MaxRecords |
Specifies the maximum number of records that can be included in the view. |
40000 |
Narrative, Ticker |
MaxVisibleColumns |
Specifies the maximum number of columns to be displayed in a view. |
2000 (75 for Simple Trellis; 150 for Advanced Trellis, 300 for Pivot Table) |
Graph, Pivot Table, Trellis |
MaxVisiblePages |
Specifies the maximum number of view prompts (or pages in PDF) to be displayed in a view. |
1000 (10000 for Treemap) |
Graph, Pivot Table, Table, Trellis, Treemap |
MaxVisibleRows |
Specifies the maximum number of rows to be displayed in a view. The value of DefaultRowsDisplayed should not exceed this value. For tables and pivot tables, specifies the number of rows that is displayed on the tooltip for the Display Maximum Rows per Page paging control button. |
500 |
Graph, Pivot Table, Table, Trellis, Treemap |
MaxVisibleSections |
Specifies the maximum number of sections to be displayed in a view. This element does not apply when a slider is in place for a graph. The SectionSliderDefault and SectionSliderLimit elements apply to limit section values when a slider is in place. See Manually Configuring for Graphs and Gauges. |
25 (10 for Simple Trellis; 50 for Advanced Trellis and Treemap) |
Graph, Pivot Table, Table, Trellis, Treemap |
JavaHostReadLimitInKB |
Specifies the maximum amount of data that is sent to the browser for a single graph. |
4096 |
Graph |
You can use settings within the GridViews element (such as DefaultRowFetchSlicesCount) to specify how data is fetched for table views, pivot table views, and trellis views that use scrolling as the method to browse data.
Content designers specify the method to be used to browse data (either scrolling or paging controls) in a table view, pivot table view, or trellis view in the Table Properties dialog: Style tab, the Pivot Table Properties dialog, or the Trellis Properties dialog: General tab, respectively. See User's Guide for Oracle Business Intelligence Enterprise Edition.
The table below describes the common elements for fetching data.
Element | Description | Default Value |
---|---|---|
DefaultRowFetchSlicesCount |
Specifies the maximum number of rows to be used in calculating the size of the scrolling view when it is initially displayed. When a user scrolls to the last row in the view, a link to fetch more rows (if there are more) is displayed. |
1000 |
DefaultColumnFetchSlicesCount |
Specifies the maximum number of columns to be used in calculating the size of the scrolling view when it is initially displayed. When a user scrolls to the last column in the view, a link to fetch more columns (if there are more) is displayed. |
300 |
DefaultFreezeHeadersClientRowBlockSize |
Specifies the number of rows to be returned to the client on an AJAX request (that is, when a user scrolls such that a request needs to be made to the server to get more rows into the table view, pivot table view, or trellis view). |
60 |
DefaultFreezeHeadersClientColumnBlockSize |
Specifies the number of columns to be returned to the client on an AJAX request (that is, when a user scrolls such that a request needs to be made to the server to get more columns into the table view, pivot table view, or trellis view). |
15 |
DefaultFreezeHeadersWidth |
Specifies the default maximum width of table views, pivot table views, and trellis views in pixels. Content designers can override this value using the Maximum Width field in the properties dialog for the view. |
700 |
DefaultFreezeHeadersHeight |
Specifies the default maximum height of table views, pivot table views, and trellis views in pixels. Content designers can override this value using the Maximum Height field in the properties dialog for the view. |
400 |
DefaultScrollingEnabled |
Specifies the Data View scrolling of table views, as follows:
|
true |
You can configure various options that change the display of graphs, including funnel graphs, and gauges.
These views types are also affected by the settings that are described in Manually Configuring for Data in Views.
Element | Description | Default Value |
---|---|---|
EmbedFonts |
See Configuring Fonts for Graphs for details. |
false |
DefaultWebImageType |
Specifies the default type for rendering an image when a format has not been specified in the URL or in the XML file for the view. Valid values are:
Flash, png, and html5 images provide the greatest degree of interaction because they support mouse-over behaviors (such as popup data labels), navigation, and drilling. DefaultWebImageType is honored for graphs only when |
html5 |
SectionSliderDefault |
Specifies the default number of values that can be displayed on a section slider bar. A section slider displays members of one or more attribute or hierarchical columns as values on a rectangular bar and provides mechanisms to select a value. For more information about defining section sliders in graphs, gauges, and funnels, see User's Guide for Oracle Business Intelligence Enterprise Edition. |
5 |
SectionSliderLimit |
Specifies the maximum number of values that can be displayed on a section slider bar. |
10 |
FlashCodeBase |
Specifies the name of the source for downloading the Flash plug-in. The default download source for the Flash plug-in is the vendor's website. In some organizations, users are instructed to download the latest Flash software from a corporate location instead of the vendor's website. You can modify the setting to point to another location that holds the Flash code base. Then, when users view a graph and a newer version of the Flash software is available on the corporate server, they can be prompted to download the newer version. |
vendor's web site |
FlashCLSID |
Specifies a custom global identifier (clsid) property for downloading Flash. After modifying the Flash download directory using the FlashCodeBase element, you can enable a download prompt by creating a new classID for the Flash ActiveX control to add a custom global identifier property. You can obtain the current global identifier property from any computer where Oracle BI Presentation Services graphing is being used. (The global identifier property used by Oracle Business Intelligence is D27CDB6E-AE6D-11CF-96B8-444553540000.) The custom global identifier property must contain the same number of characters and dashes as the global identifier used in the default Flash ActiveX control. Test flash graphs independent of Oracle Business Intelligence to ensure that they function with the custom global identifier property. |
No default value |
There are two ways you can configure fonts for graphs.
Set the embed fonts element
Deliver font files for printing
Setting the Embed Fonts Element
By default, graphs rely on users to have the appropriate device fonts installed on their system to display multilingual text in the graphs. When users enable rotation on O1 axis labels, the graphs can look unattractive at certain angles. The labels appear obscured without any anti-aliasing. You can set the EmbedFonts element to true to specify the use of embedded fonts instead of device fonts, which resolves this display issue.
Be aware that the use of embedded fonts can cause a loss of fidelity. Whenever end users select fonts, they see the Oracle-licensed Albany WT plain fonts by default. Because the graphing engine does not provide embedded fonts for Chinese, Japanese, and Korean locales, users with those locales might obtain unattractive results for label rotation.
Delivering Font Files for Printing
If you plan to print graphs in bi-directional languages to PDF or graphs in Chinese, Japanese, or Korean to PNG images, then you must deliver required font files (.TTF) as follows:
To print graphs in bi-directional languages to PDF, you must deliver the Albany family of fonts to this Java Runtime Environment (JRE) directory:
JAVA.HOME/lib/fonts
where JAVA.HOME is the directory name as specified by the "java.home" system property.
To print graphs in Chinese, Japanese, or Korean to PNG images, you must deliver the font file that contains all the needed glyphs to this JRE directory:
lib/fonts/fallback
For more information about font configuration files, see your Java documentation.
You can use the DefaultWebImageType element to specify the default type for rendering an image when a format has not been specified in the URL or in the XML file for the view.
Valid values are:
flash
In browsers that do not support flash format, the graph or gauge will not render. You should use the html5 value instead.
png (W3C Portable Network Graphics)
svg (W3C Scalable Vector Graphics)
The svg value is not supported in this release, so flash is used if svg is specified.
html5
In browsers that support only the flash format, the graph or gauge will render in flash format.
Flash and SVG images provide the greatest degree of interaction because they support mouse-over behaviors (such as popup data labels), navigation, and drilling.
Both tables and pivot tables can have colored bars on alternating lines. Such formatting is sometimes called "green bar styling," and the default color for these alternating bars is green. For pivot tables, content designers can control formatting features when editing tables and pivot tables, including whether alternating bar color is enabled.
As the administrator, you can change the default color for alternating bars, by editing a style configuration file. To change the color, edit the views.css file in the b_mozilla_4 folder, as shown in the following list. Change the six-digit hexadecimal color value to a new color value.
Tables use the CSS selector:
.ECell (for even-numbered rows)
.OCell (for odd-numbered) rows.
Pivot tables use the CSS selector:
.PTE (for odd-numbered rows)
The option for enabling the alternating bars is in the Edit View dialog and is labeled Enable alternating row "green bar" styling. If you change the color of the bars, then you might also want to change the label to indicate the color that you have set.
To change the label in the dialog for both the table and pivot table, open the tableviewmessages.xml file and find this entry:
WebMessageName = "kmsgTableViewEnableGreenbarReporting"
Copy the entry and the text line under it to a custom messages file in the custom messages folder, and change the text line appropriately. For example:
WebMessageName = "kmsgTableViewEnableGreenbarReporting" <TEXT>Enable alternating row "RED bar" styling</TEXT>"
You can configure various options that change the way that right-click interactions are handled in views for an analysis at runtime.
The elements in the instanceconfig.xml file specify the default settings for a new or upgraded analysis. You can edit the properties of an analysis in Presentation Services to modify how the analysis handles right-click interactions in views.
Element | Description | Default Value |
---|---|---|
InteractionPropertyAddRemoveValues |
Specifies whether the Add/Remove Values option is selected by default in the Analysis Properties dialog: Interactions tab. |
false |
InteractionPropertyCalcItemOperations |
Specifies whether the Create/Edit/Remove Calculated Items option is selected by default in the Analysis Properties dialog: Interactions tab. |
false |
InteractionPropertyDrill |
Specifies whether the Drill (when not a primary interaction) option is selected by default in the Analysis Properties dialog: Interactions tab. |
true |
InteractionPropertyGroupOperations |
Specifies whether the Create/Edit/Remove Groups option is selected by default in the Analysis Properties dialog: Interactions tab. |
false |
InteractionPropertyInclExclColumns |
Specifies whether the Include/Exclude Columns option is selected by default in the Analysis Properties dialog: Interactions tab. |
true |
InteractionPropertyMoveColumns |
Specifies whether the Move Columns option is selected by default in the Analysis Properties dialog: Interactions tab. |
true |
InteractionPropertyRunningSum |
Specifies whether the Display/Hide Running Sum option is selected by default in the Analysis Properties dialog: Interactions tab. |
false |
InteractionPropertyShowHideSubTotal |
Specifies whether the Display/Hide Sub-totals option is selected by default in the Analysis Properties dialog: Interactions tab. |
false |
InteractionPropertySortColumns |
Specifies whether the Sort Columns option is selected by default in the Analysis Properties dialog: Interactions tab. |
true |
You can configure settings that affect the way that users work with prompts.
Element | Description | Default Value |
---|---|---|
AutoApplyDashboardPromptValues |
Specifies whether to display various fields, as described in the following list: If true, then
If false, then
|
true |
AutoSearchPromptDialog |
Specifies whether search results are displayed and highlighted when the user types the search parameter (without clicking the Search button). |
true |
CaseInsensitive |
Specifies whether the auto-complete functionality is case-insensitive. If set to true, case is not considered when a user enters a prompt value such as "Oracle" or "oracle." If set to false, case is considered when a user enters a prompt value, so the user must enter "Oracle" and not "oracle" to find the Oracle record. The system recommends the value with the proper case. |
true |
Matching Level |
Specifies whether the auto-complete functionality uses matching to find the prompt value that the user enters into the prompt field. These settings do not apply when the user accesses the Search dialog to locate and specify a prompt value. Use the following settings:
|
MatchAll |
MaxDropDownValues |
Specifies the maximum number of choices to display in the following locations:
|
256 |
ResultsLimit |
Specifies the number of matching values that are returned when the auto-complete functionality is enabled. |
50 |
ResultRowLimit |
Specifies the number of records returned from the logical SQL for prompts (analyses and dashboard prompts). |
65000 |
ShowNullValueInPromptsWhenDatabaseColumnIsNullable |
Specifies whether to show the term "NULL" at runtime in the column prompt above the column separator in the drop-down list when the database allows null values. Use the following settings:
|
always |
SupportAutoComplete |
Enables or disables the auto-complete functionality of prompts. A setting of true turns auto-complete on, which means that the Prompts Auto-Complete field is displayed and is set to On in the My Account dialog and in the Dashboard Properties dialog. A setting of false turns auto-complete off, which means that the auto-complete fields in the My Account and Dashboard Properties dialogs are not available. |
false, unless you are running Oracle BI EE on the Oracle Exalytics In-Memory Machine |
You can configure settings that change the display of dashboards and presentation settings.
See the following sections:
In addition to the presentation settings that you can change in Fusion Middleware Control, other settings can be changed manually. Use various elements in the instanceconfig.xml file to change these settings.
Element | Description | Default Value |
---|---|---|
AnalysisEditorStartTab |
Specifies whether the Analysis editor is to open by default to the Criteria tab or the Results tab. This setting is applied when users click an analysis' Edit link from a dashboard, the Home Page, or the Catalog page. Valid values are:
Users can override this default setting by setting the Full Editor option in the My Account dialog. |
answerResults |
Enable508 |
Specifies whether content for Oracle BI EE is rendered in a browser in a way that facilitates the use of a screen reader. If you set this to true, then the BI Composer wizard in accessibility mode is used as the analysis editor, regardless of the setting of the Analysis Editor component. If you set this to false, and the setting of the Analysis Editor component is Wizard (limited functionality), then the BI Composer wizard in regular mode is used as the analysis editor. Users can override this default setting by setting the Accessibility Mode option in the Sign In page or the My Accounts dialog. |
false |
DefaultName |
Specifies the name to be used for dashboards that contain dashboard template pages and to override the path in which Oracle BI EE searches for dashboard template pages. By default, Oracle BI EE searches for dashboard template pages in dashboards named "default" in subfolders under /Shared Folders. |
default |
EnableDelayExecution |
Specifies whether content designers have the ability to delay the execution of dashboard pages. When this is set to true, the Prompt before Opening option is displayed in the Dashboard Properties dialog. See Delaying the Execution of Dashboard Pages in User's Guide for Oracle Business Intelligence Enterprise Edition. |
true |
MaxFollowLinks |
Specifies the default value for the maximum number of navigation links to follow in a briefing book. A briefing book navigation link is a type of link that can be added to a dashboard using the Dashboard Builder. The default value for this element is 5; the minimum is 1; and the maximum is 10. If you plan to download briefing books to PDF format, then do not set the value of this element to a number greater than 9 because of the table of contents limitation of nine links. For information about the table of contents, see Modifying the Table of Contents for PDF Versions of Briefing Books. For information about working with briefing books, see User's Guide for Oracle Business Intelligence Enterprise Edition. |
5 |
NumericFormatter |
Specifies a value to use for consistent output at a fixed number of digits. You might notice that after a certain number of significant digits, the number is not displayed appropriately. Use this setting to set the maximum number of significant digits, such as 16 on Linux platforms. |
No default value |
Note:
See Enabling the Ability to Create Links to Dashboard Pages for information about the defaults for the Bookmarks, MaxAgeMinutes, EnableBookmarkURL, and EnablePromptedURL elements. See Configuring an Alternate Toolbar for Oracle BI Publisher for information about the defaults for the ReportingToolbarMode element.
By default, the global header in Oracle BI EE contains menus and options that enable you to navigate easily among features. You might like to customize the global header and the Get Started section of the Home page to better meet the needs of users by disabling certain links or including your own links.
Changes that you make to the Get Started section do not affect the Help menu in the global header. For custom links, you can specify various attributes, including the following:
The text for the link (either a static string or a message name to use for localization).
A URL to access.
Whether the page from the URL replaces the current page or opens in a new tab or window that you can name.
The relative ordering of links in the header.
An optional icon to use with the link.
To customize the global header, you perform the tasks that are described in the following sections:
Create the customlinks.xml
file to specify customizations to the global header, as described in the following sections.
Create the file
You can place the customlinks.xml
file in any absolute path specified in the instanceconfig.xml
file. See Adding the CustomLinks Element. The recommended default location in which to create this file is the data directory for Presentation Services:
BI_DOMAIN/bidata/components/OBIPS/customMessages
Elements in the File
The following table describes the elements and attributes that you can include in the customlinks.xml
file. If you want to hide existing links that are shown by default, then you can comment out their entries in the file. You can’t modify the order of default links such as Favorites or Dashboards.
Table 18-1 Elements in customlinks.xml
Element or Attribute | Optional? | Data Type | Description |
---|---|---|---|
locations |
Optional |
Not Applicable |
Use as the parent element for specifying the locations of the links to add. If you don’t specify a location, then by default links are included before the Help link in the global header and at the end of the Get Started section. |
location: name |
Required |
String |
Use this attribute if you include the locations parent element. The values are: header: Specifies to include the link in the global header. getstarted: Specifies to include the link in the Get Started section of the Home page. |
location: insertBefore |
Optional |
String |
Specifies the ID of an existing link before you which you want to insert this link. If the specified ID is invalid, then the link is inserted in the default locations. See Specifying the insertBefore Attribute for information on valid values. |
link: id |
Required |
String |
Use as a unique ID that specifies the position of the link. You can include IDs for custom links to position them relative to default links. |
link: name |
Required |
String |
Specifies the name of the link that is not translated. |
link: localizedName |
Optional |
String |
Specifies the message ID of the link that is translated, which takes precedence over the non-translated name. |
link: iconSmall |
Optional |
String |
Specifies the file name of an icon to display with the link in the global header. The display of icons is controlled by the fmap syntax. See User's Guide for Oracle Business Intelligence Enterprise Edition for information on the fmap syntax. |
link: iconLarge |
Optional |
String |
Specifies the file name of an icon to display with the link in the Get Started section. The display of icons is controlled by the fmap syntax. |
link: privilege |
Optional |
String |
Specifies the name of privileges that a user must be granted to see the link. The privileges are indicated as an expression, as shown in the following example: privileges.Access['Global Answers']&& privileges.Access['Global Delivers'] |
link: accessibility |
Optional |
Boolean |
Specifies that in accessibility mode, the link is available only when the accessibility attribute is set to true. Values are true and false, and false is the default. In previous releases, the vpat attribute served the same purpose as the accessibility attribute. The vpat attribute has been deprecated. |
link: src |
Required |
String |
Specifies the URL for the link. |
link: target |
Optional |
String |
Specifies the browser window in which to open the link. The values are: self: Opens in same window in which Presentation Services is running. blank: Opens in a new window. any-name: Opens in a window with the specified name. |
link: description |
Optional |
String |
Specifies the description of the link that is not translated. |
link: localizedDesc |
Optional |
String |
Specifies the message ID of the link that is translated, which takes precedence over the non-translated description. |
Note:
You may want to place icons in a common directory structure exposed by the application server or HTTP Server or place them in the catalog file system and expose them via fmap. See Storing Custom Files Locally and Using the fmap Function to Reference Them in User's Guide for Oracle Business Intelligence Enterprise Edition for information on the FMAP syntax.After you update the customlinks.xml
file, the file is reloaded when you next restart Presentation Services, as described in Managing Oracle Business Intelligence Processes.
Specifying the insertBefore Attribute
You can include the insertBefore
attribute that is described in Table 18-1 to specify the ID of an existing link before which you want to insert another link. The following list provides the valid IDs for the global header:
The Get Started section includes no fixed IDs because you can customize its contents.
Sample File and Output
The following code sample shows a customlinks.xml
file that was edited to include links in the global header and the Get Started section.
<?xml version="1.0" encoding="utf-8"?> <customLinks xmlns="com.siebel.analytics.web/customlinks/v1"> <link id="l1" name="OTN" description="OTN open in new window" src="http://www.oracle.com" target="blank" > <locations> <location name="header" /> </locations> </link> <link id="l2" name="Google Search" description="Google open in named window" src="http://www.google.com/" target="google" iconSmall="common/info_ena.png" > <locations> <location name="header" insertBefore="advanced" /> </locations> </link> <link id="l3" name="Yahoo" description="Yahoo" src="http://www.yahoo.com" target="yahoo" iconLarge="common/helptopics_lg_qualifier.png"> <locations> <location name="getstarted" /> </locations> </link> <link id="l5" name="Gmail" description="gmail" src="http://www.gmail.com" target="blank" iconLarge="common/gmail.png" > <locations> <location name="getstarted" /> <location name="header" insertBefore="catalog" /> </locations> </link> </customLinks>
This file modifies the Home page as shown below. Note the following changes to the Home page:
The global header is modified to include the following:
Google Search — A link to the Google Home page with a custom icon, which is placed before the Advanced link.
OTN — A link to the Oracle Technology Network page, which is placed before the Help link.
Gmail — A link to the Gmail Home page, which is placed before the Catalog link.
The Get Started section is modified to include links to the Yahoo and Gmail Home pages that use custom icons.
Before custom links are visible on the Home page, you must edit the instanceconfig.xml
file to include the CustomLinks
element, and the Enabled
element (whose default is true) and filePath
element within it. Omitting the CustomLinks
element is the same as setting the Enabled
element to false; no custom links are displayed.
You must configure the software properly to make customizations visible to users.
If you want users to see the customizations that you have made, then you must ensure that the Custom Links privilege is assigned to the BI Consumer role, which occurs by default. You cannot assign this privilege to individual users, groups, or roles other than BI Consumer.
To verify the role for this privilege, use the Manage Privileges page in the Administration pages of Presentation Services. See Managing Presentation Services Privileges in Security Guide for Oracle Business Intelligence Enterprise Edition.
Users can create links (both bookmark links and prompted links) to dashboard pages.
This enables them, for example, to save a link as a bookmark or to copy and send a link to other users in email. A bookmark is a hidden object in the Oracle BI Presentation Catalog (under the /system/bookmarks
folder) that captures the state of a dashboard page. It is created when a user creates a bookmark link to the page. You can enable or disable the ability to create these links to dashboard pages. Further, in order for users to be able to create these links, you must grant the Create Bookmark Links and Create Prompted Links privileges associated with this feature.
For more information on these links, see About Creating Links to Dashboard Pages in User's Guide for Oracle Business Intelligence Enterprise Edition. For more information on privileges, see Managing Presentation Service Privileges in Security Guide for Oracle Business Intelligence Enterprise Edition .
When you include a BI Publisher report on a dashboard, you generally enable that report to participate as a recipient of the dashboard state by passing in dashboard context to that report using core dashboard prompts.
For scenarios that do not require passing of context to or from the BI Publisher report to the larger dashboard-based analytic application, you can display a variant of the default BI Publisher toolbar, which exposes the underlying parameter prompts of that BI Publisher report. Within that frame, a user can then pass in parameters to a single BI Publisher report.
This approach can be confusing to the user as any other dashboard prompts on the page do not contribute to the BI Publisher report, which also does not participate in passing context back to the rest of the application. Changes to the BI Publisher toolbar are also applied globally for all BI Publisher reports that are embedded in dashboards across the entire BI Publisher instance.
Use the ReportingToolbarMode element to affect how BI Publisher reports are embedded in Oracle BI EE. You configure the alternate BI Publisher toolbar by setting the element's value to 6. Remove the ReportingToolbarMode element to revert to the default toolbar behavior, or set it to the default value of 1.
Content designers can create custom layouts for printing and exporting dashboard pages.
When a content designer creates a custom layout for a dashboard page, the dashboard page is exported to Oracle BI Publisher. You can enable or disable the ability to export dashboard pages to Oracle BI Publisher by setting the EnableDashPageExport element.
See About Creating Custom Layouts for Printing and Exporting Dashboard Pages in User's Guide for Oracle Business Intelligence Enterprise Edition.
The PDF version of a briefing book contains a table of contents that is automatically generated. It contains an entry for each dashboard page, analysis, and report in the briefing book.
See Working with Briefing Books in User's Guide for Oracle Business Intelligence Enterprise Edition for information about the table of contents.
The default template for the table of contents, toc-template.rtf, is located in the ORACLE_INSTANCE\config\OracleBIPresentationServicesComponent\coreapplication_obisn
directory. You can modify the toc-template.rtf file to accommodate the needs of your organization.
The Smart View version packaged with Oracle Business Intelligence may be out of synchronization with the Oracle Business Intelligence server or with the latest available version of Smart View.
You can configure the Smart View for MS Office link that is displayed on the Download BI Desktop Tools list on the Oracle Business Intelligence Home page to point to a custom download link for the Smart View installer. You can then ensure that the correct version of Smart View for your environment is always available to your users. You do this by adding the SmartViewInstallerURL element to instanceconfig.xml.
You can configure the download link to point to a location where the smartview.exe resides, for example:
An external URL, such as the Smart View download page on Oracle Technology Network, where the latest version of Smart View is always available
An internal URL, such as internal web page or intranet site where the installation can start immediately
A folder on a local server, where the installation can start immediately
You might want to block specific analyses, such as requiring content designers to include certain columns with others, or requiring filters when certain columns are requested.
Answers includes an API that you can use to block queries based on the criteria specified in the analysis or based on formulas in the analysis. You can access the API using JavaScript to check conditions and validate analyses.
This section contains the following topics:
This section explains how to use JavaScript to check conditions and validate analyses.
You write your own JavaScript programs for performing these tasks and other similar ones. Oracle BI EE does not install any JavaScript programs. As you write JavaScript programs, you can store them in the singleton data directory (SDD), which you first deploy as a virtual directory:
SDD/components/OBIPS/analyticsRes
Where SDD is the Singleton Data Directory for example, DOMAIN_HOME/bidata
.
See Setting Up Shared Files and Directories.
To place JavaScript programs in a directory other than this one, then you can do so, if you specify the full path name in the code that calls the program. For example, you can use code such as the following:
<script type="text/javascript" src="http://example/mydir/myblocking.js" />
When a user attempts to execute an analysis that your code blocks, you can display an error message, and the analysis is not executed.
The answerstemplates.xml file includes a message named kuiCriteriaBlockingScript that can be overridden to either define or include JavaScript that defines a validateAnalysisCriteria function. By default, this message contains a function that always returns true.
Answers calls your validateAnalysisCriteria function when the user tries to execute the analysis. The function can return true if the analysis is not blocked, or false, or a message if the analysis is blocked. If a message or a value other than false is returned, then the message is displayed in a popup window. In either case, the query is blocked.
The following code example shows the blocking of a query. First, place the following XML code in the answerstemplates.xml file.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="QueryBlocking" table="Messages"> <WebMessage name="kuiCriteriaBlockingScript" translate="no"> <HTML> <script type="text/javascript" src="fmap:myblocking.js" /> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
This XML code calls a JavaScript program called myblocking.js. Ensure that you place this file in the following directory:
SDD/components/OBIPS/analyticsRes
SDD is the Singleton Data Directory.
The following is sample code for the myblocking.js program.
// This is a blocking function. It ensures that users select what // the designer wants them to. function validateAnalysisCriteria(analysisXml) { // Create the helper object var tValidator = new CriteriaValidator(analysisXml); // Validation Logic if (tValidator.getSubjectArea() != "Sample Sales") return "Try Sample Sales?"; if (!tValidator.dependentColumnExists("Markets","Region","Markets","District")) { // If validation script notifies user, then return false alert("Region and District are well suited, do you think?"); return false; } if (!tValidator.dependentColumnExists("Sales Measures","","Periods","Year")) return "You selected a measure so pick Year!"; if (!tValidator.filterExists("Sales Measures","Dollars")) return "Maybe filter on Dollars?"; if (!tValidator.dependentFilterExists("Markets","Market","Markets")) return "Since you are showing specific Markets, filter the markets."; var n = tValidator.filterCount("Markets","Region"); if ((n <= 0) || (n > 3)) return "Select 3 or fewer specific Regions"; return true; }
If you do not override the function using the template as described previously, or if the function returns anything other than false, then the criteria is considered to be valid and the analysis is issued. The criteria is validated using this same mechanism for preview and save operations as well.
After making this change, either stop and restart the server for Oracle BI Presentation Services, or click the Reload Files and Metadata link on the Administration page.
Answers provides a hook that lets you incorporate a JavaScript validation function that is called from Answers when a content designer enters or modifies a column formula. If the call fails and returns a message, then Answers displays the message and cancels the operation.
Additionally, helper functions are available so the query blocking function can check for filters, columns, and so on, rather than traversing the Document Object Model (DOM) manually. The DOM is a way of describing the internal browser representation of the HTML UI page that is currently being displayed in Answers. See Validation Helper Functions.
The criteriatemplates.xml file includes a message named kuiFormulaBlockingScript that can be overridden to include JavaScript that defines a validateAnalysisFormula function. By default, this message contains a function that always returns true.
Answers calls validateAnalysisFormula before applying changes made by the content designer. If the function returns true, then the formula is accepted. If the function returns false, then the formula is rejected. Otherwise, the return value from the function is displayed in the message area beneath the formula, as it does currently when an invalid formula is entered.
The content designer has the option to click OK to ignore the error. To display your own alert and allow the content designer to continue, your function should return true. To block the query, return false or a message. Your function should investigate the formula passed to it using a JavaScript string and regular expression techniques for validation.
The following code example shows a sample custom message.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="QueryBlocking" table="Messages"> <WebMessage name="kuiFormulaBlockingScript" translate="no"> <HTML> <script type="text/javascript" src="fmap:myblocking.js" /> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
The following code example shows blocking based on the formula entered.
// This is a formula blocking function. It makes sure the user does not enter an unacceptable formula. function validateAnalysisFormula(sFormula, sAggRule) { // do not allow the use of concat || in our formulas var concatRe = /\|\|/gi; var nConcat = sFormula.search(concatRe); if (nConcat >= 0) return "You used concatenation (character position " + nConcat + "). That is not allowed."; // no case statements var caseRe = /CASE.+END/gi; if (sFormula.search(caseRe) >= 0) return "Do not use a case statement."; // Check for a function syntax: aggrule(formula) aggrule should not contain a '.' var castRe = /^\s*\w+\s*\(.+\)\s*$/gi; if (sFormula.search(castRe) >= 0) return "Do not use a function syntax such as RANK() or SUM()."; return true; }
After making this change, either stop and restart the server for Oracle BI Presentation Services, or click the Reload Files and Metadata link on the Administration page.
Validation helper functions are defined in a JavaScript file.
These functions are defined within a JavaScript file named answers/queryblocking.js. This table contains the list of helper functions and their descriptions.
Validation Helper Function | Description |
---|---|
CriteriaValidator.getSubjectArea() |
Returns the name of the subject area referenced by the analysis. It generally is used in a switch statement within the function before doing other validation. If the analysis is a set-based criteria, then it returns null. |
CriteriaValidator.tableExists(sTable) |
Returns true if the specified folder (table) has been added to the analysis by the content designer, and false if the folder was not added. |
CriteriaValidator.columnExists(sTable, sColumn) |
Returns true if the specified column has been added to the analysis by the content designer, and false if the column was not added. |
CriteriaValidator.dependentColumnExists(sCheckTable, sCheckColumn, sDependentTable, sDependentColumn) |
Checks to ensure that the dependentColumn exists if the checkColumn is present. It returns true if either the checkColumn is not present, or the checkColumn and the dependent column are present. If checkColumn and dependentColumn are null, then the folders are validated. If any column from checkTable is present, then a column from dependentTable must be present. |
CriteriaValidator.filterExists(sFilterTable, sFilterColumn) |
Returns true if a filter exists on the specified column, and false if no filter is present. |
CriteriaValidator.dependentFilterExists(sCheckTable, sCheckColumn, sFilterTable, sFilterColumn) |
Checks to ensure that the dependentFilter exists if the checkColumn is present in the projection list. It returns true if either the checkColumn is not present, or the checkColumn and the dependent filter are present. |
CriteriaValidator.filterCount(sFilterTable, sFilterColumn) |
Returns the number of filter values that are specified for the given logical column. If the filter value is "equals," "null," "notNull," or "in," then it returns the number of values chosen. If the column is not used in a filter, then it returns zero. If the column is prompted with no default, then it returns -1. For all other filter operators (such as "greater than," "begins with," and so on) it returns 999, because the number of values cannot be determined. |
You can control certain aspects of the initial state of new views that are added to an analysis and of new objects that are added to a dashboard page.
For example, you can add a default footer to new analyses and set defaults for dashboard sections. You control these aspects by customizing the appropriate XML message files to override the default values that are specified during installation.
This section describes the XML message files to customize to override the view defaults distributed with Oracle BI Presentation Services.
For analyses, the file answerstemplates.xml includes a message named kuiCriteriaDefaultViewElementsWrapper from within kuiAnswersReportPageEditorHead. This message includes two additional messages, kuiCriteriaDefaultViewElements, in which you can define default values, and kuiCriteriaDefaultViewElementsMask, in which masks are defined. The mask XML message is protected and you cannot modify its contents.
The wrapper message adds the combined XML into a JavaScript variable, kuiDefaultViewElementsXML, that is used to apply the new default values.
For dashboards, the file dashboardtemplates.xml includes a message named kuiDashboardDefaultElementsWrapper that adds XML into a JavaScript variable named kuiDefaultDashboardElementsXML for use within the dashboard editor.
The following sections provide examples of customizing default values.
To cause these customizations to take effect, either stop and restart the server for Oracle BI Presentation Services, or click the Reload Files and Metadata link on the Administration page.
You can specify that default headers and footers are displayed on all new analyses.
For example, footers can contain messages such as a confidentiality notice, the company's name, and so on. You can specify a default header or footer by creating an XML message that specifies the text and formatting to apply.
The following XML code example creates a footer that contains the text "Acme Confidential" in bold, red letters.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="Answers" table="ViewDefaults"> <WebMessage name="kuiCriteriaDefaultViewElements" translate="no"><HTML> <view signature="compoundView" > <pageProps pageSize="a4"> <pageFooter showOnDashboard="true" show="true"> <zone type="top"><caption>[b]Acme Confidential[/b]</caption> <displayFormat fontColor="#FF0000"/></zone> </pageFooter>
</pageProps> <pageProps pageSize="a4"> <pageFooter showOnDashboard="true" show="true"> <zone position="top"> <caption fmt="html"> <text>[b]Acme Confidential[/b] </text> </caption> <displayFormat> <formatSpec hAlign="center" fontColor="#FF0000"/> </displayFormat> </zone> </pageFooter> </pageProps> </view> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
The results of an analysis are displayed when editing views of data. If you prefer that the content designer explicitly asks to view the results, then you can create an XML message that specifies that auto-preview is disabled when new views are created.
The content designer can still click the Display Results link to view the results when editing a view.
Note:
You can add signature entries for various views to the XML code. You can locate the signature value for a view in the XML representation of the analysis. While editing an analysis, see the analysis XML field on the Advanced tab of the Analysis editor. Look for the xsi:type attribute of the <saw:view> element. The signature value is the value without the "saw:" prefix.
The following XML code example disallows the auto-previewing of results when working with a view in Answers.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="Answers" table="ViewDefaults"> <WebMessage name="kuiCriteriaDefaultViewElements" translate="no"><HTML> <view signature="tableView" showToolBar="true" showHeading="true /> <view signature="pivotTableView" autoPreview="false" /> <view signature="titleView" autoPreview="false" /> <view signature="viewSelector" autoPreview="false" /> <view signature="htmlviewnarrativeView" autoPreview="false" /> <view signature="tickerview" autoPreview="false" /> <view signature="htmlview" autoPreview="false" /> <view signature="dvtchart" autoPreview="false" /> <view signature="dvtgauge" autoPreview="false" /> <view signature="dvtfunnel" autoPreview="false" /> <view signature="trellisView" autoPreview="false" /> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
The results of a newly formed analysis are displayed as a title view followed by either a table or pivot table in a compound layout.
A table is created if the analysis contains only attribute columns, and a pivot table is created if the analysis contains at least one hierarchical column.
You can create an XML message that specifies that the compound view defaults to a different assemblage of views, such as a narrative followed by a graph. The content designer can still add and rearrange views within the compound layout.
The following XML code example sets the default compound layout to a narrative followed by a graph.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="Answers" table="ViewDefaults"> <WebMessage name="kuiCriteriaDefaultViewElements" translate="no"><HTML> <view signature="compoundView" > <cv signature="narrativeView" /> <cv signature="dvtchart" /> </view> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
By default, the results of drilling in a dashboard are displayed on a new page, section names are not displayed in the dashboard, and sections can be expanded and collapsed.
You can change these default values by creating an XML message that specifies that new default values for the dashboard section. A content designer who edits the dashboard can still modify this behavior using the options within the dashboard editor.
The following XML code example makes section heads visible, enables drilling, and does not allow sections to collapse.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="Answers" table="ViewDefaults"> <WebMessage name="kuiDashboardDefaultElements" translate="no"><HTML> <element signature="dashboardSection" drillInline="true" showHeading="true" collapsible="false" /> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
By default, dashboards are printed without headers or footers and in a portrait orientation.
If you prefer that newly added dashboard pages default to having a custom header and footer and print in landscape orientation, then you can create an XML message that specifies these characteristics. A content designer who edits the dashboard can still modify this behavior using the options within the dashboard editor.
The following XML code example adds a custom header and footer to a dashboard page and specifies landscape orientation.
<?xml version="1.0" encoding="utf-8"?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web.messageSystem"> <WebMessageTable system="Answers" table="ViewDefaults"> <WebMessage name="kuiDashboardDefaultElements" translate="no"> <HTML> <element signature="dashboardPage" personalSelections="false"> <pageProps orientation="landscape" printRows="all" pageSize="a4"> <pageHeader showOnDashboard="true" show="true"> <zone position="top"> <caption>[b]Acme is Cool[/b]</caption> <displayFormat> <formatSpec fontSize="9pt" hAlign="center" fontColor="#FFFFFF" backgroundColor="#000000"/> </displayFormat> </zone> </pageHeader> <pageFooter showOnDashboard="true" show="true"> <zone position="top"> <caption>[b]CONFIDENTIAL[/b]</caption> <displayFormat> <formatSpec fontSize="7.5pt" hAlign="center" fontColor="#999999" borderColor="#CC99CC" fontStyle="italic" borderPosition="all" borderStyle="single"/> </displayFormat> </zone> </pageFooter> </pageProps> </element> </HTML> </WebMessage> </WebMessageTable> </WebMessageTables>
Users of a dashboard page or an analysis might have the ability to modify the data that they see in a table view.
This ability is often referred to as "write back." As the administrator, you assist the content designer in configuring write back for users.
The following sections provide information about how to configure for write back:
If a user has the Write Back to Database privilege, then the write-back fields in analyses can display as editable fields if properly configured.
If the user does not have this privilege, then the write-back fields display as normal fields. If the user types a value in an editable field and clicks the appropriate write-back button, then the application reads the write-back template to get the appropriate insert or update SQL command. It then issues the insert or update command. If the command succeeds, then it reads the record and updates the analysis. If there is an error in either reading the template or in executing the SQL command, then an error message is displayed.
The insert command runs when a record does not yet exist and the user enters new data into the table. In this case, a user has typed in a table record whose value was originally null.
The update command runs when a user modifies existing data. To display a record that does not yet exist in the physical table to which a user is writing back, you can create another similar table. Use this similar table to display placeholder records that a user can modify in dashboards.
Note:
If a logged-on user is already viewing a dashboard that contains an analysis where data has been modified using write back, the data is not automatically refreshed in the dashboard. To see the updated data, the user must manually refresh the dashboard.
Refer to the following example which demonstrates how the Oracle BI Administrator works with the content designer to configure write back processes.
Users can write back to any data source (except for an ADF data source) that allows the execution of SQL queries from the Oracle BI Server. As you configure for write back, keep the following limitations in mind:
Numeric columns must contain numbers only. They should not contain any data formatting characters such as dollar signs ($), pound signs or hash signs (#), percent signs (%), and so on.
Text columns should contain string data only.
If a logged-on user is already viewing a dashboard that contains an analysis where data has been modified using write back, the data is not automatically refreshed in the dashboard. To see the updated data, the user must manually refresh the dashboard.
You can use the template mechanism only with table views and only for single-value data. The template mechanism is not supported for pivot table views or any other type of view, for multiple-value data, or for drop down columns with single-value data.
All values in write-back columns are editable. When displayed in non printer friendly context, editable fields are displayed as if the user has the Write Back to Database privilege. However, when a logical column is mapped to a physical column that can change, the logical column returns values for multiple level intersections. This scenario can cause problems.
Any field in an analysis can be flagged as a write-back field, even if it is not derived from the write-back table that you created. However you cannot successfully execute the write-back operation if the table is not write-back enabled. The responsibility for correctly tagging fields lies with the content designer.
A template can contain SQL statements other than insert and update. The write-back function passes these statements to the database. However, Oracle does not support or recommend the use of any statements other than insert or update.
Presentation Services performs only minimal validation of data input. If the field is numeric and the user enters text data, then Presentation Services detects that and prevents the invalid data from going to the database. However, it does not detect other forms of invalid data input (values out of range, mixed text and numeric, and so on). When the user clicks the write-back button and an insert or update is executed, invalid data results in an error message from the database. The user can then correct the faulty input. Content designers can include text in the write-back analysis to aid the user, for example, "Entering mixed alphanumeric values into a numeric data field is not allowed."
The template mechanism is not suitable for entering arbitrary new records. In other words, do not use it as a data input tool.
When creating a table for write back, ensure that at least one column does not include write-back capability but does include values that are unique for each row and are non-null.
Write-back analyses do not support drill-down. Because drilling down modifies the table structure, the write-back template does not work.
Caution:
The template mechanism takes user input and writes it directly to the database. The security of the physical database is your own responsibility. For optimum security, store write-back database tables in a unique database instance.A write-back template file is an XML-formatted file that contains one or more write-back templates.
A write-back template consists of a WebMessage element that specifies the name of the template, the connection pool, and the SQL statements that are needed to insert and update records in the write-back tables and columns that you have created. When content designers enable a table view for write back, they must specify the name of the write-back template to use to insert and update the records in the table view.
You can create multiple write-back template files. You can include multiple write-back templates in a template file, customizing each one for the fields that are used in each specific analysis. However, the best practice recommendation is to include only one template in a file.
A write-back template must meet the following requirements:
You must specify a name for the write-back template using the name attribute of the WebMessage element.
For write back to work correctly, when enabling a table view for write back, a content designer must specify the name of the write-back template to be used to insert and update the records in the view.
The following example shows the specification of the write-back template that is called "SetQuotaUseID."
<WebMessage name="SetQuotaUseID">
To meet security requirements, you must specify the connection pool along with the SQL commands to insert and update records. These SQL commands reference the values that are passed in the write-back schema to generate the SQL statements to modify the database table. Values can be referenced either by column position (such as @1, @3) or by column ID (such as @{c1234abc}, @{c687dfg}). Column positions start numbering with 1. The use of column ID is preferred. Each column ID is alphanumeric, randomly generated, and found in the XML definition of the analysis in the Advanced tab of the Analysis editor.
You must include both an <insert> and an <update> element in the template. If you do not want to include SQL commands within the elements, then you must insert a blank space between the opening and closing tags. For example, you must enter the element as
<insert> </insert>
rather than
<insert></insert>
If you omit the blank space, then you see a write-back error message such as "The system cannot read the Write Back Template 'my_template'".
If a parameter's data type is not an integer or real number, then add single quotation marks around it. If the database does not do Commits automatically, then add the optional postUpdate node after the insert and update nodes to force the commit. The postUpdate node typically follows this example:
<postUpdate>COMMIT</postUpdate>
Example 18-1 Examples: Write-Back Template Files
A write-back template file that references values by column ID might resemble this example:
<?xml version="1.0" encoding="utf-8" ?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web/message/v1"> <WebMessageTable lang="en-us" system="WriteBack" table="Messages"> <WebMessage name="SetQuotaUseID"> <XML> <writeBack connectionPool="Supplier"> <insert>INSERT INTO regiontypequota VALUES(@{c0},@{c1},'@{c2}','@{c3}',@{c4})</insert> <update>UPDATE regiontypequota SET Dollars=@{c4} WHERE YR=@{c0} AND Quarter=@{c1} AND Region='@{c2}' AND ItemType='@{c3}'</update> </writeBack> </XML> </WebMessage> </WebMessageTable> </WebMessageTables>
A write-back template file that references values by column position might resemble this example:
<?xml version="1.0" encoding="utf-8" ?> <WebMessageTables xmlns:sawm="com.siebel.analytics.web/message/v1"> <WebMessageTable lang="en-us" system="WriteBack" table="Messages"> <WebMessage name="SetQuota"> <XML> <writeBack connectionPool="Supplier"> <insert>INSERT INTO regiontypequota VALUES(@1,@2,'@3','@4',@5)</insert> <update>UPDATE regiontypequota SET Dollars=@5 WHERE YR=@1 AND Quarter=@2 AND Region='@3' AND ItemType='@4'</update> </writeBack> </XML> </WebMessage> </WebMessageTable> </WebMessageTables>
The user interface in Oracle BI EE is generated by using scripts and custom interfaces, and is therefore highly customizable.
The look-and-feel is controlled by skins, styles, and themes. Skins and themes can define the user interface chrome (visible graphic features) outside the home and dashboard area.
Oracle BI EE is shipped with several styles, such as Skyros, blafp (browser look and feel), and FusionFX (fusion applications). Saved themes are also available in style selectors.
The following sections provide information about how to customize the web user interface:
Skins, styles, and themes change the way an interface looks.
You can control the way that the interface for Oracle BI EE is displayed to users by creating skins, styles, and themes. The primary difference between skins and styles is that styles apply to only dashboard content, whereas skins apply to every other part of the user interface. For example, within Oracle BI EE, skins apply to components that are used in analyses and scorecarding. Themes can apply to the entire interface, dashboard content, or both, depending on how they are applied.
You specify the default skin and style in the instanceconfig.xml file. The content designer can then alter certain elements to control how dashboards are formatted for display, such as the color of text and links, the font and size of text, the borders in tables, the colors and attributes of graphs, and so on. See Modifying the User Interface Styles for Presentation Services. You design and apply themes using the Manage Themes page, which is enabled in the instanceconfig.xml file. You can then provide access on the Manage Privileges page.
Skins and styles are organized into folders that contain Cascading Style Sheets (CSS) and images. While skins and styles are typically used to customize the look and feel of analyses and dashboards by providing logos, color schemes, fonts, table borders, and other elements, they can also be used to control the position and justification of various elements by including specialized style tags in the relevant style sheet file. See About Style Customizations. Themes are organized using the Manage Themes page.
Some points to keep in mind as you plan to customize the web user interface.
In Oracle BI Presentation Services, you customize the user interface elements and appearance by modifying skins, and styles, not with JavaScript, and you do not modify JavaScript files because the objects and methods in scripts might change, and because these files might be replaced when upgrading.
In a dashboard, users with the appropriate permissions can customize an individual dashboard section by adding HTML to it. This HTML can include JavaScript. See Working with HTML Markup in User's Guide for Oracle Business Intelligence Enterprise Edition.
Users with appropriate permissions can customize the entire interface and analyses output using themes. See Creating Custom Themes in User's Guide for Oracle Business Intelligence Enterprise Edition.
You can adapt the Oracle BI EE deployment to a particular language. See Localizing Oracle Business Intelligence.
Oracle BI EE ships with various styles, such as blaf (browser look and feel), FusionFX (fusion applications), and Skyros. If you are going to customize the look-and-feel of Oracle BI EE or Oracle BI Publisher, Oracle strongly recommends that you use the custom style provided in the bicustom-template.ear as your starting point.
This custom style is a copy of the Skyros style. See Modifying the User Interface Styles for Presentation Services for additional information.
Most of the common Skyros styles and image files, including the style sheet (master.css), are contained in a master directory. The topic Customizing Your Style describes this directory and its structure in detail.
Within the style sheet, each element (or class) that is available for update is documented by comments.
Other style sheets are also contained within the Skyros style and skin folders. You are not likely to need to update these files unless you are creating an advanced custom skin that provides styles for each detail of the user interface.
When creating your own styles and skins for Presentation Services, you must create CSS, graph.xml, and image files, and then make them available to Oracle BI EE. You can use two approaches to make these files available:
Approach 1: You use the bicustom.ear file to package your files into a single file that can then be easily deployed throughout the nodes in a cluster. This approach is useful when deploying in a clustered environment for scaled-out production systems. See Approach 1: Deploying the "bicustom.ear" File for the First Time?.
To redeploy the bicustom.ear file, see Approach 1: Redeploying the "bicustom.ear" File.
Approach 2: You use a shared file system. This approach is useful when you want to see your changes in Oracle BI EE immediately or when your customizations are outside the Presentation Services firewall. See Approach 2: Deploying Using Shared Folders.
To view the modifications that you made using Approach 2, see Approach 2: Viewing Your Modifications to a Shared Folder.
Enterprise Archive (EAR) files are archive (ZIP) files composed of a specific folder and file structure.
You can create an EAR file using any ZIP tool (for example, 7-zip) and then renaming the ZIP extension to EAR. Oracle provides the bicustom-template.ear file as a starting point.
The bicustom-template.ear file contains a bicustom.war file. Web Archive (WAR) files are also ZIP files composed of a specific folder and file structure. You must update the bicustom.war file within the bicustom-template.ear file to include your custom skin files. The bicustom.war file that is shipped with Oracle BI EE contains an example folder structure to help you get started.
Note:
This approach automatically deploys your custom skin to all nodes in your Oracle BI EE cluster.
Copy ORACLE_HOME/bi/bifoundation/jee/bicustom-template.ear
to BI_DOMAIN/bidata/components/OBIPS/bicustom.ear
.
Note:
The patch or upgrade process may overwrite the bicustom-template.ear file, but it does not overwrite the bicustom.ear file.
Update the bicustom.ear file.
Extract the bicustom.war file from the bicustom.ear file.
Extract the files from the bicustom.war file.
Edit the files to create your custom style and save your changes. See Customizing Your Style
Update the bicustom.war file with your changes.
Update the bicustom.ear file with your new bicustom.war file.
Deploy the bicustom.ear file.
Log in to Oracle Weblogic Server Administration Console.
Click Lock & Edit.
Click Deployments in the Domain Structure region.
Click Install in the Deployments table.
Navigate to the folder containing the bicustom.ear file (by default, this file is located in BI_DOMAIN/bidata/components/OBIPS/
).
Select the bicustom.ear file.
Click Next.
Select Install this deployment as an application.
Click Next.
Select I will make the deployment accessible from the following location.
Click Finish.
Click Save.
Click Activate Changes.
Start the new application.
Click Deployments in the Domain Structure region.
Select the bicustom check box in the Deployments table.
Click Start, and then select Servicing all requests.
Update the instanceconfig.xml file to specify which style and skin to use as the default value of the Styles option in the Dashboard Properties dialog. For additional information about updating styles in a dashboard, see Changing the Properties of a Dashboard and its Pages in User's Guide for Oracle Business Intelligence Enterprise Edition.
If these entries are not present in the instanceconfig.xml file, then fusionFX is the default style.
Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
Include the element and its ancestor elements as appropriate, as shown in the following example:
<ServerInstance> <UI> <DefaultStyle>Skyros</DefaultStyle> <DefaultSkin>Skyros</DefaultSkin> </UI> </ServerInstance>
where DefaultStyle and DefaultSkin are the names of the custom style and skin properties, respectively.
To use the Alta custom style and skin, replace the word Skyros
above with the word Alta
.
Note:
These names must match the names given to the folders containing the style and skin. Do not include underscores. For example: If your folder begins with the characters s_, such as s_Skyros, then omit s_.
Save your changes and close the file.
Restart Presentation Services. See About Managing Oracle Business Intelligence Processes.
To redeploy the bicustom.ear file, see Approach 1: Redeploying the "bicustom.ear" File.
Enterprise Archive (EAR) files are archive (ZIP) files composed of a specific folder and file structure.
Use this task to update your custom skin
Update the bicustom.ear file.
Update the deployment.
Log in to Oracle Weblogic Server Administration Console.
Click Lock & Edit.
Click Deployments in the Domain Structure region.
Select the bicustom checkbox in the Deployments table.
Click Update.
Click Finish.
Click Activate Changes.
Click Release Configuration.
Restart Presentation Services.
Note:
If you are changing component values, such as an image or font color in your customized files, you do not need to restart Presentation Services. Additionally, you do need to restart Presentation Services if you make a change to the default skin or style in the instanceconfig.xml file.
Approach 2 is best suited to development or test environments where you want the changes that you make to the CSS and image files in your custom style and skin folders to be visible in Oracle BI EE as soon as possible.
This approach is also used when your customizations are outside the Presentation Services firewall.
Web servers have their own ways of exposing static directories that can be located anywhere within their file system, including a shared file system such as clustering. Refer to the documentation for your specific server on exposing static directories.
Note:
See the following documents for full information about how to configure Oracle WebLogic Server to work with web servers such as Apache HTTP Server, Microsoft Internet Information Server (Microsoft IIS), and Oracle HTTP Server:
Using Oracle WebLogic Server Proxy Plug-Ins
Administering Oracle HTTP Server
Create your custom style.
Extract the bicustom.war file from the bicustom-template.ear file.
Extract the contents of the bicustom.war file to a location accessible to Oracle Weblogic Server (for example, c:\custom
).
Edit the files to create your custom style and save your changes. See Customizing Your Style for additional information.
Deploy the custom folder.
Log in to Oracle Weblogic Server Administration Console.
Click Lock & Edit.
Click Deployments in the Domain Structure region.
Click Install in the Deployments table.
Navigate to the folder containing your custom style (for example, c:\custom
).
Click Next.
Select Install this deployment as an application.
Click Next.
Select bi_cluster as the deployment target.
Click Next.
Set the name to AnalyticsRes.
Select I will make the deployment accessible from the following location.
Click Next.
Select Yes, take me to the deployment's configuration screen.
Click Finish.
Click the Configuration tab.
Enter /analyticsRes in the Context Root box.
Click Save.
Click OK.
Click Activate Changes.
Click Release Configuration.
Start the new application.
Click Deployments in the Domain Structure region.
Select the analyticsRes checkbox in the Deployments table.
Click Start, and then select Servicing all requests.
Update the instanceconfig.xml file to specify the path that points to your customization, which can then be accessed by Presentation Services.
Presentation Services generates the user interface for the Analysis editor and dashboards, which visualize data from Oracle BI Server, the core server behind Oracle Business Intelligence.
Open the instanceconfig.xml file for editing, located in:
BI_DOMAIN/config/fmwconfig/biconfig/OBIPS
Locate the ServerInstance section.
Include the elements, as shown in the following example:
<ServerInstance> <UI> <DefaultStyle>Skyros</DefaultStyle> <DefaultSkin>Skyros</DefaultSkin> </UI> <URL> <CustomerResourcePhysicalPath>c:\custom\res </CustomerResourcePhysicalPath> <CustomerResourceVirtualPath>/analyticsRes/res </CustomerResourceVirtualPath> </URL> </ServerInstance>
where DefaultStyle and DefaultSkin are the names of the custom style and skin properties, respectively.
To use the Alta custom style and skin, replace the word Skyros
above with the word Alta
.
Note:
The CustomerResourceVirtualPath points to the location entered in the Context Root box.
If you are embedding a Presentation Services' dashboard or report in an ADF application, you must include the SkinMappings element following the DefaultStyle and DefaultSkin elements, as shown in the following example:
<ServerInstance> <UI> <DefaultStyle>Skyros</DefaultStyle> <DefaultSkin>Skyros</DefaultSkin> <SkinMappings> <skinMapping> <biadfSkinFamily>fusion</biadfSkinFamily> <biSkin>FusionFx</biSkin> </skinMapping> <skinMapping> <biadfSkinFamily>blafplus-rich</biadfSkinFamily> <biSkin>blafp</biSkin> </skinMapping> <skinMapping> <biadfSkinFamily>skyros</biadfSkinFamily> <biSkin>Skyros</biSkin> </skinMapping> </SkinMappings> </UI> <URL> <CustomerResourcePhysicalPath>c:\custom\res </CustomerResourcePhysicalPath> <CustomerResourceVirtualPath>/analyticsRes/res </CustomerResourceVirtualPath> </URL> </ServerInstance>
Save your changes and close the file.
Restart Presentation Services.
Once you have configured your shared folder, you can view the changes to the CSS files and images.
Reload the metadata.
In Oracle BI EE, click the Administration link in the global header.
On the Administration tab, click the Reload Files and Metadata link.
Clear the browser's cache. Note that this process is dependent on the browser being used.
Click any link on the global header (for example, Home or Catalog) to see your changes.
Note:
If you add files, such as an image file, to your custom style folder, you must restart Presentation Services.
To create your custom style, you must edit one or more files.
The bicustom.war folder structure from which the style directory is extracted, contains the following in the application resources (res) directory (./res/), which houses the relevant files:
./res/filemap.xml
./res/s_Custom/
./res/s_Custom/master/
./res/s_Custom/master/master.css
./res/s_Custom/master/graph.xml
./res/s_Custom/master/custom.css
./res/s_Custom/master/styleproperties.res
./res/s_Custom/master/*.png
./res/s_Custom/master/*.gif
The style directory, prefixed by s_, contains the style sheet, image files, and a graph xml file.
All classes are located within the CSS or the graph.xml file.
The table below describes the content of the "res" folder structure.
Folder or File Name | Description |
---|---|
filemap.xml2 |
The filemap.xml file enables you to specify that your style or skin extends another style or skin. By default, s_Custom1 extends s_Skyros, which is defined in the filemap.xml file. This means that if a file cannot be found as part of your custom style or skin, then Presentation Services knows where to look next for that file. The content within the filemap.xml file looks similar to the following: <FileMap> <Styles Default="s_blafp"> <Hierarchy>s_Skyros/s_Custom</Hierarchy> </Styles <Skins Default="sk_blafp"> <Hierarchy>sk_Skyros/sk_Custom</Hierarchy </Skins> </FileMap> |
s_Custom |
s_Custom is a folder containing the files that define a style named Custom. The prefix, s_, indicates that the folder contains a style. This name displays in the Dashboard Properties dialog, Styles option. For additional information about updating styles in a dashboard, see Changing the Properties of a Dashboard and its Pages in User's Guide for Oracle Business Intelligence Enterprise Edition. If you want to change the default style manually by using the instanceconfig.xml file, the style name that you specify in the instanceconfig.xml file must match the style name specified as part of this folder name. You can name your style whatever you choose, but it must begin with s_. If you do change the name of the custom style, you must also update the filemap.xml file with the new style's name. If the files and folders that you add to the new style folder share the same names as files and folders in the base style (as defined in the filemap.xml file), then these new files and folders are used instead of the files in the base style. Use the files and folders in the base style as a guide for creating your custom style folders. You can define as many different styles as you like. Make a copy of the s_Custom folder in the same folder and name it by prefixing it with s_ (for example, s_Corporate). If you create additional custom styles, you must also add them to a style hierarchy in the filemap.xml file. |
sk_Custom |
sk_Custom1 is a folder that you create to customize the full skin and not just the style. You create sk_Custom as a sibling of the s_Custom folder. sk_Custom is not provided as part of the bicustom-template.ear file. The prefix, sk_, indicates that the folder contains a skin. If you want to change the default skin manually by using the instanceconfig.xml file, the skin name that you specify in the instanceconfig.xml file must match the skin name specified as part of this folder name. You can name your skin whatever you choose, but it must begin with sk_. If you do change the name of the custom skin, you must also update the filemap.xml file with the skin's new name. If the files and folders that you add to the new skin folder share the same names as files and folders in the base skin (as defined in the filemap.xml file), then these new files and folders are used instead of the files in the base skin. Use the files and folders in the base skin as a guide for creating your custom style folders. You can define as many different skins as you like. Make a copy of the sk_Custom folder in the same folder and name it by prefixing it with sk_ (for example, sk_Corporate). If you create additional custom skins, you must also add them to a skin hierarchy in the filemap.xml file. |
master |
The master folder contains all of the files that you likely need to create a custom style. |
master.css |
The master.css file contains all the CSS classes that are used by the style and defines the majority of the CSS classes and styles that are used throughout Presentation Services and Oracle BI Publisher. Changing the styles defined in the classes contained in this file widely impacts Oracle BI EE. Oracle does not recommend changing the CSS class selectors (CSS class names) in this file. Change the styles defined within each CSS class. The master.css file also contains comments to help you understand what classes apply and to which parts of the user interface they apply. |
custom.css |
The custom.css file is an empty (or blank) file that is imported by the master.css file. You can use the custom.css file to add your own CSS classes (for example, to apply styles to analyses) and override classes in the master.css file without changing the master.css file. Keeping your changes in the custom.css file, a separate file, enables you to take advantage of future improvements to the master.css file that are applied by patches and upgrades. |
graph.xml |
The graph.xml file enables you to define all the default styles that are applied to various graphs within analyses. The graph.xml file is documented with comments. These comments describe the valid values for each setting and provide a description of the elements for that style. |
styleproperties.res |
The styleproperties.res file provides advanced control over some of the elements of the user interface. For example, you can specify which version of the data loading animation to use when your dashboard is rendered. Data loading animations are used in the "status indicator" area of a web page when a page is loading data from the server. There are two different versions of the data loading animation: one animation uses dark foreground colors for use on light backgrounds and the other animation uses the reverse. The styleproperties.res file is documented with comments. These comments provide a description of the elements. |
.png and .gif (image files) |
All required images and the most common images are located in the master directory. These images are primarily .png and .gif formats. You can replace these images with your own files, preferably with images of the same size. |
File names, such as s_Custom, are case-sensitive and in lowercase on Linux.
Using the filemap.xml file to specify the style or skin that you are extending is applicable only for Presentation Services.
For security reasons, you can no longer embed content from external domains in dashboards. To embed external content in dashboards, you must edit the instanceconfig.xml file.
Open the instanceconfig.xml file for editing, located in:
ORACLE_HOME/user_projects/domains/bi/config/fmwconfig/biconfig/OBIPS
Depending on whether you want to embed content from all external domains or a specific external domain, perform one of the following actions:
To embed content from all external domains, include the elements and their ancestor elements, as shown in the following example:
<ServerInstance> <Security> <ContentSecurityPolicy> <PolicyDirectives> <Directive> <Name>frame-src</Name> <Value>*</Value></Directive> <Directive><Name>img-src</Name> <Value>*</Value> </Directive> </PolicyDirectives> </ContentSecurityPolicy>
Note:
The wildcard character "*" in the <Value> element enables you to embed content in dashboards from both internal and external domains.
To embed content from a number of specific domains, for example www.xxx.com, www.yyy.com, and so on, include the name of each domain separated by a space, in the elements and their ancestor elements, as shown in the following example:
<ServerInstance> <Security> <ContentSecurityPolicy> <PolicyDirectives> <Directive> <Name>frame-src</Name> <Value>www.xxx.com www.yyy.com</Value></Directive> <Directive><Name>img-src</Name> <Value>www.xxx.com www.yyy.com</Value> </Directive> </PolicyDirectives> </ContentSecurityPolicy>
Keep the following points in mind when you configure the instanceconfig.xml file for specific domains:
The default setting of the instanceconfig.xml file enables you to embed content from internal domains only. When you edit the instanceconfig.xml file to specify external domains, you overwrite the default setting of the file, thus preventing you from accessing internal domains. To enable you to continue accessing internal domains, you must precede the names of the external domains with the word 'self' followed by a space. For example, to continue to embed content from internal domains and a specific domain (www.xxx.com), you enter the following text in the <Value> element:
'self' www.xxx.com
When you configure the instanceconfig.xml file for specific domains, you can use the wildcard character to embed content from all sub-domains under the parent domain. For example, when you specify www.xxx.*.com, you can embed content from all sub-domains such as xxx.hr.com, xxx.fin.com, and so on.
Save your changes and close the file.