19 Configuring and Managing Analyses and Dashboards

This chapter describes how to configure and manage analyses and dashboards and the objects that they contain, such as views, in Oracle Business Intelligence. For information about how content designers work with analyses and dashboards, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

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:

19.1 Managing Dashboards

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 or Catalog groups 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:

19.2 Performing General Configuration Tasks for Analyses

This section describes general tasks that you can perform to configure for the creation of analyses. It includes the following sections:

19.2.1 Increasing Heap Size to Assist in Exports to Excel

Various options are available for exporting the results of analyses, for example, exporting to Microsoft Excel. These options are described in "Exporting Results" in Oracle Fusion Middleware 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 Oracle Business Intelligence is installed on a computer with a 32-bit operating system, then advise users to export to CSV format for greater performance.

If users must export a large data set without using the CSV format on a computer with a 64-bit operating system, then users might experience an out-of-memory error. If users see this error message, then you must likely 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.

To increase the heap size for the JavaHost service to assist in exports to Excel:

  1. Open the opmn.xml file for editing. You can find opmn.xml at:

    ORACLE_INSTANCE/config/OPMN/opmn/opmn.xml

  2. Locate the ias-component tag for the JavaHost system component.

    For example:

    <ias-component id="coreapplication_obijh1">

  3. In the line that starts with <data id="start-args" value="-server -Xmx1024M

    set the -Xmx parameter to 2048M (or higher as necessary, depending on the available memory in the system and the size of the Excel export that you require).

    On a computer with a 32-bit Windows operating system, do not set this parameter to a large value, or the Java virtual machine does not start.

  4. Save and close the file.

  5. If you see an error message about a SocketTimeoutException from the com.siebel.analytics.javahost.io.ChannelWithTimeout class, then update the SocketTimeout parameter for the JavaHost service.

    Open the config.xml file for the JavaHost system component in the ORACLE_INSTANCE\config\OracleBIJavaHostComponent\coreapplication_obijhn directory.

    Locate the MessageProcessor section and the SocketTimeout parameter, which might be commented out. Uncomment SocketTimeout if necessary and specify a higher value. For example, specify at least 300000 milliseconds.

    The config.xml file and its settings are described in Section B.2, "Using the JavaHost Service for Oracle BI Presentation Services."

  6. Save and close the file.

  7. Restart OPMN.

  8. Restart the JavaHost system component process either using Fusion Middleware Control or from the command line using OPMN.

  9. In a clustered system, repeat these steps on each computer that runs the JavaHost process and if you later add JavaHost processes during scale-out. Note that the ias-component tag is different (for example, <ias-component id="coreapplication_obijh2">) on other computers where it is deployed.

19.2.2 Manually Configuring for Export

Note:

The ability to manually configure for export applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

You can configure various options that change how the results of analyses or views are exported.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the settings for export:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Enter the following namespace declaration in the WebConfig element:

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    Note that the Export element includes the required attribute xsi:type, which specifies the type of export. Valid values are:

    • excel (for export to Excel)

    • formattedText (for data export)

    • pdf (for export to PDF

  3. Locate the Download section in which you must add the elements that are described in Table 19-1.

  4. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Download>
    <Export xsi:type="excel">
        <RepeatRows>false</RepeatRows>
    </Export>

    <Export xsi:type="formattedText">
        <Delimiter char=","/>
    </Export>

    <Export xsi:type="pdf">
        <KeepRowsTogether>true</KeepRowsTogether>
    </Export>

  </Download>
</ServerInstance>

  5. Save your changes and close the file.

  6. Restart Oracle Business Intelligence.

Table 19-1 describes the elements for manually configuring for export.

Table 19-1 Elements for Manually Configuring for Export

Element Description Default Value

RepeatRows

Specifies whether cells that span rows and cells that span columns are to be repeated when users export tables and pivot tables to Microsoft 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:

  • If Value Suppression is set to Suppress, then cells that span rows and cells that span columns are not repeated. For example, in a table that has Year and Month values, Year is displayed only once for Month values.

  • If Value Suppression is set to Repeat, then cells that span rows and cells that span columns are repeated. For example, in a table that has Year and Month values, Year is repeated for all Month values.

For more information on the Value Suppression option, see Oracle Fusion Middleware 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

19.2.3 Providing Access to Metadata Dictionary Information

When creating analyses, content designers might need more information about subject areas, folders, columns, or levels (such as relationships to other metadata objects) to guide them. You can provide content designers with this information by allowing them access to the metadata dictionary for the repository. The metadata dictionary describes the metrics that are contained within the repository and the attributes of repository objects. The metadata dictionary output is a static set of XML documents.

To provide access to metadata dictionary information:

  1. Ensure that the metadata dictionary has been generated and the files have been stored in an appropriate location. For information, see "Generating a Metadata Dictionary" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.

  2. Set the DictionaryURLPrefix element within the ServerInstance element in the instanceconfig.xml file to one of the following values. The value that you specify depends on the web servers in use.

    • The prefix for the name of the directory in which you have stored the XML files. The directory must have been specified as a shared directory for the web server, and the web server must be the same one that is used by Oracle BI EE.

      For example, suppose that you stored the XML files for the metadata dictionary in a directory called demo1 under the metadictionary directory. Suppose that the metadictionary directory is specified as a shared directory for the web server, which is also used by Oracle BI EE. Then you specify the following value for the DictionaryURLPrefix element:

      <DictionaryURLPrefix>demo1/</DictionaryURLPrefix>

      See the documentation for the web server for information about sharing directories.

    • The URL that points to the directory in which you have stored the XML files. Use a value such as this when the files for the metadata dictionary are stored in the directory structure for a web server that is not being used by Oracle BI EE. For example:

      <DictionaryURLPrefix>http://10.10.10.10/metadictionary/demo1</DictionaryURLPrefix>

    The following shows an example setting in the instanceconfig.xml file:

    <WebConfig>
  <ServerInstance>
    <SubjectAreaMetadata>
      <DictionaryURLPrefix>demo1</DictionaryURLPrefix>
    </SubjectAreaMetadata>
  </ServerInstance>
</WebConfig>

    For information about working in the Oracle BI Presentation Services configuration file (instanceconfig.xml), see Section 3.4, "Using a Text Editor to Update Configuration Settings."

  3. Grant the Access to Metadata Dictionary privilege to the appropriate content designers. For information about privileges, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

For details on how content designers can view metadata dictionary information, see "Viewing Metadata Information from the Subject Areas Pane" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

19.2.4 Supporting Nested Folders, Navigation, and Drill-Down

The Oracle BI Administrator can set up subject areas in ways that assist content designers who work with analyses. Oracle Fusion Middleware 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 Oracle BI 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.

19.3 Configuring for Displaying and Processing Data in Views

You can configure various options that change the display and processing of data in views. See also Section 7.3.3, "Using Fusion Middleware Control to Set Configuration Options for Data in Tables and Pivot Tables" and Section 7.3.4, "Using Fusion Middleware Control to Set the Maximum Number of Rows Processed to Render a Table" for related information.

This section contains the following topics:

19.3.1 Manually Configuring for Data in Views

Note:

The ability to manually configure for data in treemap views applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

You can configure various options that change the processing and display of data in views, as described in the following sections:

19.3.1.1 Manually Configuring Cube Settings for Pivot Tables and Graphs

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.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the Cube settings:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the Cube section, in which you must add the following elements:

    • CubeMaxRecords — Specifies the maximum number of records that are returned by an analysis for the view to process. This roughly governs the maximum number of cells that can be populated in a view; unpopulated cells in a sparse view do not count. The default is 40000.

    • CubeMaxPopulatedCells — Specifies the maximum number of cells in a view that can be populated with data from the Oracle BI Server. The default is 120000.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Views>
    <Cube>
      <CubeMaxRecords>40000</CubeMaxRecords>
      <CubeMaxPopulatedCells>120000</CubeMaxPopulatedCells>
    </Cube>
  </Views>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.3.1.2 Manually Configuring Settings for Data in Views

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.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the settings that change the display of data in views:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the Table, Pivot, Trellis, Charts, Narrative, Ticker, and Treemap parent sections, in which you must add the elements that are described in Table 19-2.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Views>
      <Table>
        <MaxCells>10000</MaxCells>
        <MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
        <MaxVisiblePages>1000</MaxVisiblePages>
        <MaxVisibleRows>500</MaxVisibleRows>
        <MaxVisibleSections>25</MaxVisibleSections>
        <DefaultRowsDisplayed>30</DefaultRowsDisplayed>
        <DefaultRowsDisplayedInDelivery>250</DefaultRowsDisplayedInDelivery>
        <DefaultRowsDisplayedInDownload>65000</DefaultRowsDisplayedInDownload>
        <DefaultRowsDisplayedInDownloadCSV>65000</DefaultRowsDisplayedInDownloadCSV>
      </Table>
      <Pivot>
        <MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
        <MaxVisibleColumns>300</MaxVisibleColumns>
        <MaxVisiblePages>1000</MaxVisiblePages>
        <MaxVisibleRows>500</MaxVisibleRows>
        <MaxVisibleSections>25</MaxVisibleSections>
        <DefaultRowsDisplayed>30</DefaultRowsDisplayed>
        <DefaultRowsDisplayedInDelivery>250</DefaultRowsDisplayedInDelivery>
        <DefaultRowsDisplayedInDownload>65000</DefaultRowsDisplayedInDownload>
        <DefaultRowsDisplayedInDownloadCSV>65000</DefaultRowsDisplayedInDownloadCSV>
      </Pivot>
      <Trellis>
        <Simple>
            <MaxCells>1000</MaxCells>
            <MaxVisibleSections>10</MaxVisibleSections>
            <MaxVisiblePages>1000</MaxVisiblePages>
            <MaxVisibleRows>100</MaxVisibleRows>
            <MaxVisibleColumns>75</MaxVisibleColumns>
            <MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
            <DefaultRowsDisplayed>10</DefaultRowsDisplayed>
            <DefaultRowsDisplayedInDelivery>100</DefaultRowsDisplayedInDelivery>
            <DefaultRowsDisplayedInDownload>6500</DefaultRowsDisplayedInDownload>
        </Simple>
        <Advanced>
            <MaxCells>5000</MaxCells>
            <MaxVisibleSections>50</MaxVisibleSections>
            <MaxVisiblePages>1000</MaxVisiblePages>
            <MaxVisibleRows>250</MaxVisibleRows>
            <MaxVisibleColumns>150</MaxVisibleColumns>
            <MaxPagesToRollOutInDelivery>1000</MaxPagesToRollOutInDelivery>
            <DefaultRowsDisplayed>25</DefaultRowsDisplayed>
            <DefaultRowsDisplayedInDelivery>250</DefaultRowsDisplayedInDelivery>
            <DefaultRowsDisplayedInDownload>10000</DefaultRowsDisplayedInDownload>
        </Advanced>
      </Trellis>
      <Charts>
        <MaxVisibleColumns>2000</MaxVisibleColumns>
        <MaxVisiblePages>1000</MaxVisiblePages>
        <MaxVisibleRows>2000</MaxVisibleRows>
        <MaxVisibleSections>25</MaxVisibleSections>
        <JavaHostReadLimitInKB>4096</JavaHostReadLimitInKB>
      </Charts>
      <Narrative>
        <MaxRecords>40000</MaxRecords>
        <DefaultRowsDisplayed>30</DefaultRowsDisplayed>
      </Narrative>
      <Ticker>
        <MaxRecords>40000</MaxRecords>
      </Ticker>
      <Treemap>
        <MaxCells>5000</MaxCells>
        <MaxVisiblePages>10000</MaxVisiblePages>
        <MaxVisibleRows>10000</MaxVisibleRows>
        <MaxVisibleSections>50</MaxVisibleSections>
      </Treemap>
  </Views>
</ServerInstance>

    Note that this example does not include elements that might exist in the file, but that are centrally managed by Fusion Middleware Control and cannot be changed manually.

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-2 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.

Table 19-2 Common Elements for Manually Changing the Display of Data in Views

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.

25 (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.

65000

Pivot Table, Table

MaxCells

Note: This element (when included for treemap) applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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)

Graph, Pivot Table, Trellis

MaxVisiblePages

Note: This element (when included for treemap) applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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

Note: This element (when included for treemap) applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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.

2000 (100 for Simple Trellis; 250 for Advanced Trellis; 10000 for Treemap)

Graph, Pivot Table, Table, Trellis, Treemap

MaxVisibleSections

Note: This element (when included for treemap) applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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 Table 19-4.

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

19.3.1.3 Manually Configuring Settings for Fetching Data for Table Views, Pivot Table Views, and Advanced Trellis Views

You can use settings within the GridViews element (such as DefaultRowFetchSlicesCount) to specify how data is fetched for table views, pivot table views, and advanced 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 advanced trellis view in the Table Properties dialog: Style tab, the Pivot Table Properties dialog, or the Trellis Properties dialog: General tab, respectively. For more information, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

To manually edit the settings for fetching data:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the GridViews parent section, in which you must add the elements that are described in Table 19-3.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Views>
    <GridViews>
        <DefaultRowFetchSlicesCount>1000</DefaultRowFetchSlicesCount>
        <DefaultColumnFetchSlicesCount>300</DefaultColumnFetchSlicesCount>
        <DefaultFreezeHeadersClientRowBlockSize>60</DefaultFreezeHeadersClientRowBlockSize>
        <DefaultFreezeHeadersClientColumnBlockSize>15</DefaultFreezeHeadersClientColumnBlockSize>
    </GridViews>
  </Views>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-3 describes the common elements for fetching data.

Table 19-3 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

19.3.2 Manually Configuring for Graphs and Gauges

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 Section 19.3.1, "Manually Configuring for Data in Views."

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually edit the settings that change the display of graphs and gauges:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Search for the Charts sections, in which you must add the elements that are described in Table 19-4.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Views>
    <Charts>
     <EmbedFonts>true</EmbedFonts>
     <SectionSliderDefault>150</SectionSliderDefault>
     <SectionSliderLimit>300</SectionSliderLimit>
     <DefaultWebImageType>png</DefaultWebImageType>
     <FlashCodeBase>\\CORPORATE\Download\Flash</FlashCodeBase>
     <FlashCLSID>E38CDB6E-BA6D-21CF-96B8-432553540000</FlashCLSID>
    </Charts>
  </Views>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-4 Common Elements for Manually Configuring Graphs and Gauges

Element Description Default Value

EmbedFonts

See Section 19.3.2.1, "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 (W3C Portable Network Graphics), and svg (W3C Scalable Vector Graphics). Flash and SVG images provide the greatest degree of interaction because they support mouse-over behaviors (such as popup data labels), navigation, and drilling.

The svg value is not supported in this release, so flash is used if svg is specified.

flash

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 Oracle Fusion Middleware 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

19.3.2.1 Configuring Fonts for Graphs

You can do one or both of the following tasks to configuring fonts for graphs:

  • Set the embed fonts element

  • Deliver font files for printing

19.3.2.1.1 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.

19.3.2.1.2 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.

19.3.3 Manually Changing Alternating Bar Color

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>"

19.3.4 Manually Configuring for Interactions in Views

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.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually configure for interactions in views:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the sections in which you must add the elements that are described in Table 19-5.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Analysis>
    <InteractionProperties>
      <InteractionPropertyAddRemoveValues>false</InteractionPropertyAddRemoveValues>
      <InteractionPropertyCalcItemOperations>false</InteractionPropertyCalcItemOperations>
      <InteractionPropertyDrill>true</InteractionPropertyDrill>
      <InteractionPropertyGroupOperations>false</InteractionPropertyGroupOperations>
      <InteractionPropertyInclExclColumns>true</InteractionPropertyInclExclColumns>
      <InteractionPropertyMoveColumns>true</InteractionPropertyMoveColumns>
      <InteractionPropertyRunningSum>false</InteractionPropertyRunningSum>
      <InteractionPropertyShowHideSubTotal>false</InteractionPropertyShowHideSubTotal>
      <InteractionPropertySortColumns>true</InteractionPropertySortColumns>
      <InteractionPropertyHideColumns>false</InteractionPropertyHideColumns>
    </InteractionProperties>
  </Analysis>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-5 Elements for Configuring 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/Delete 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/Delete 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

InteractionPropertyHideColumns

Specifies whether the Hide Columns option is selected by default in the Analysis Properties dialog: Interactions tab.

false

19.4 Configuring for Prompts

You can configure settings that affect the way that users work with prompts, as described in this section.

To configure for prompts:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the sections in which you must add the elements that are described in Table 19-6.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <Prompts>
    <MaxDropDownValues>256</MaxDropDownValues>
    <ResultRowLimit>65000</ResultRowLimit>
    <AutoApplyDashboardPromptValues>true</AutoApplyDashboardPromptValues>
    <AutoSearchPromptDialogBox>true</AutoSearchPromptDialogBox>
    <AutoCompletePromptDropDowns>
      <SupportAutoComplete>true</SupportAutoComplete>
      <CaseInsensitive>true</CaseInsensitive>
      <MatchingLevel>MatchAll</MatchingLevel>
      <ResultsLimit>50</ResultsLimit>
    </AutoCompletePromptDropDowns>
    <ShowNullValueInPromptsWhenDatabaseColumnIsNullable>always</ShowNullValueInPromptsWhenDatabaseColumnIsNullable>
  </Prompts>
</ServerInstance>

    Note that this example does not include elements that might exist in the file, but that are centrally managed by Fusion Middleware Control and cannot be changed manually.

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-6 Elements for Configuring Prompts

Element Description Default Value

AutoApplyDashboardPromptValues

Specifies whether to display various fields, as described in the following list:

If true, then

  • The Show Apply Button and Show Reset Button fields are displayed on the Edit Page Settings dialog.

  • The Prompts Apply Buttons and Prompts Reset Buttons fields are displayed in the Dashboard Properties dialog.

  • The Prompt Buttons on Current Page option is displayed on the Dashboard builder's Tools menu.

If false, then

  • The Show Apply button and Show Reset button fields are not displayed on the Edit Page Settings dialog.

  • The Prompts Apply Buttons and Prompts Reset Buttons fields are not displayed in the Dashboard Properties dialog.

  • The Prompt Buttons on Current Page option is not displayed on the Dashboard builder's Tools option.

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.

For information, see "What is Auto-Complete?" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

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:

  • StartsWith — Searches for a match that begins with the text that the user types. For example, the user types "M" and the following stored values are displayed: "MicroPod" and "MP3 Speakers System".

  • WordStartsWith — Searches for a match at the beginning of a word or group of words. For example, the user types "C" and the following values are displayed: "ComCell", "MPEG Camcorder", and "7 Megapixel Digital Camera".

  • MatchAll — Searches for any match within the word or words.

MatchAll

MaxDropDownValues

Specifies the maximum number of choices to display in the following locations:

  • At runtime, in choice lists, check boxes, list boxes, and radio buttons in prompts.

  • At runtime, in the Values list of the Select Values dialog when the user selects the Search option from the prompt values list.

  • At design time in the Values list on the Filter editor and in the Available list of the Select Values dialog that is displayed when the user clicks the Search link from the Value list in the Filter editor.

  • At design time in the Available list of the Select Values dialog that is displayed when the user selects Specific Column Values in the Choice List Values field or Specific Values in the Default selection field and clicks the corresponding Select values button.

  • At design time while working with the Slider User Input type, in the list that is displayed for the Lower Limit, Upper Limit, Default Low Value, and Default High Value fields or when the users clicks the corresponding Search link within any of these fields.

256

ResultsLimit

Specifies the number of matching values that are returned when the auto-complete functionality is enabled.

50

ResultRowLimit

Note: This element applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

Specifies the number of records returned from the logical SQL for prompts (analyses and dashboard prompts).

65000

ShowNullValueInPromptsWhenDatabaseColumnIsNullable

Note: This element applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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 — Always shows the term "NULL" above the column separator in the drop-down list.

  • never — Never shows the term "NULL" in the drop-down list.

  • asDataValue — Displays as a data value in the drop-down list, not as the term "NULL" above the separator in the drop-down list.

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

For information about prompts and searching, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

19.5 Manually Changing Presentation Settings

You can configure settings that change the display of dashboards and presentation settings, as described in the following sections:

19.5.1 Manually Changing Presentation Setting Defaults

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.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually change additional presentation setting defaults:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the sections in which you must add the elements that are described in Table 19-7.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <AnalysisEditorStartTab>answerResults</AnalysisEditorStartTab>
  <Enable508>false</Enable508>
  <Dashboard>
    <DefaultName>Templates</DefaultName>
    <PersistPageState>false</PersistPageState>
    <EnableDelayExecution>true</EnableDelayExecution>
  </Dashboard>
  <BriefingBook>
      <MaxFollowLinks>6</MaxFollowLinks>
  </BriefingBook>
  <Formatters>
  <NumericFormatter maxSignificantDigits="16"/>
  <Formatters>
</ServerInstance>

    Note that this example does not include elements that might exist in the file, but that are centrally managed by Fusion Middleware Control and cannot be changed manually.

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

Table 19-7 Common Elements for Manually Changing Additional Presentation Setting Defaults

Element Description Default Value

AnalysisEditorStartTab

Note: This element applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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:

  • answerResults

  • answerCriteria

Users can override this default setting by setting the Full Editor option in the My Account dialog.

answerResults

Enable508

Note: This element applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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

Note: This element applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

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 Oracle Fusion Middleware 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 Section 19.5.6, "Modifying the Table of Contents for PDF Versions of Briefing Books."

For information about working with briefing books, see Oracle Fusion Middleware 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

PersistPageState

Specifies whether to drop the page scope context when navigating among dashboard pages.

true

Note:

See Section 19.5.3, "Enabling the Ability to Create Links to Dashboard Pages" for information about the defaults for the Bookmarks, MaxAgeMinutes, EnableBookmarkURL, and EnablePromptedURL elements. See Section 19.5.4, "Configuring an Alternate Toolbar for Oracle BI Publisher" for information about the defaults for the ReportingToolbarMode element.

19.5.2 Providing Custom Links in Presentation Services

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:

19.5.2.1 Updating the customlinks.xml File

Update the customlinks.xml file to specify customizations to the global header, as described in the following sections.

19.5.2.1.1 Default File Location

The default location for this file is the data directory for Presentation Services:

ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn

19.5.2.1.2 Elements in the File

Table 19-8 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 cannot modify the order of default links such as Favorites or Dashboards.

Table 19-8 Elements for the customlinks.xml File

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 do not 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 Section 19.5.2.1.3, "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 Oracle Fusion Middleware 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']&amp;&amp; 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.

After you update the customlinks.xml file, the file is reloaded when you next restart Presentation Services, as described in Chapter 4, "Starting and Stopping Oracle Business Intelligence."

19.5.2.1.3 Specifying the insertBefore Attribute

You can include the insertBefore attribute that is described in Table 19-8 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:


Navigation Bar
catalog
dashboard
favorites
home
new
open
user
Search Bar
admin
advanced
help
logout

The Get Started section includes no fixed IDs because you can customize its contents.

19.5.2.1.4 Sample File and Output

The following code sample shows a portion of a customlinks.xml file that was edited to include links in the global header and the Get Started section.

<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>

This file modifies the Home page as shown in Figure 19-1. 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.

Figure 19-1 Sample Home Page with Custom Links

Description of Figure 19-1 follows
Description of "Figure 19-1 Sample Home Page with Custom Links"

19.5.2.2 Adding the CustomLinks Element

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 within it (whose default is true). Omitting the CustomLinks element is the same as setting the Enabled element to false; no custom links are displayed.

You can also decide to store the customlinks.xml file in a location other than the default one. If you do so and you want the changes that you specify in the customlinks.xml file to be visible on the Home page, then you must add the filePath element to the file. If you leave the customlinks.xml file in its default location, then you need not include the filePath element in the instanceconfig.xml file. See Section 19.5.2.1.1, "Default File Location" for the location.

To add the CustomLinks element:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Search for the ServerInstance section, in which you must add the CustomLinks element.

  3. Include the elements and their ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
   <CustomLinks>
      <Enabled>true</Enabled>
      <filePath>c:/mydir/mysubdir/customlinks.xml</filePath>
   </CustomLinks>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.5.2.3 Setting the Custom Links Privilege

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 Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for information.

19.5.3 Enabling the Ability to Create Links to Dashboard Pages

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 Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition For more information on privileges, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for information.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To enable the ability to create links to dashboard pages:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the Server Instance section.

  3. Include the following elements and their ancestor elements as appropriate:

    • EnableBookmarkURL: Use this element to enable the ability to create bookmark links to dashboard pages:

      • true — Enables the ability to create bookmark links. (Default)

      • false — Disables the ability to create bookmark links.

    • EnablePromptedURL: Use this element to enable the ability to create prompted links to dashboard pages:

      • true — Enables the ability to create prompted links. (Default)

      • false — Disables the ability to create prompted links.

    • MaxAgeMinutes: Use this element within the Bookmarks element to specify that bookmarks older than the specified number of minutes are removed. The default is 43200 minutes, which corresponds to 30 days.

      Note that every time a bookmark is accessed, the expiration timer is reset. This resetting means that if a bookmark is accessed frequently, it might never be removed. Setting the value to 0 means that the bookmark is saved for 0 minutes (and does not mean that it does not expire). You cannot set bookmarks to never expire. If you want bookmarks to last for a long time, then set the value to a large number of minutes and access the bookmarks within the allotted number of minutes.

    The following entry is an example of these settings:

    <ServerInstance>
  <Dashboard>
    <EnableBookmarkURL>true</EnableBookmarkURL>
    <EnablePromptedURL>true</EnablePromptedURL>
  </Dashboard>
  <Cache>
      <Bookmarks>
          <MaxAgeMinutes>43200</MaxAgeMinutes>
      </Bookmarks>
  </Cache>
</ServerInstance>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.5.4 Configuring an Alternate Toolbar for Oracle BI Publisher

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 Presentation Services 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.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually configure an alternate toolbar for BI Publisher:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the AdvancedReporting section in which you must add the ReportingToolbarMode element.

  3. Include the element and its ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <AdvancedReporting>
      <ReportingToolbarMode>6</ReportingToolbarMode>
  </AdvancedReporting>
</ServerInstance>

    The following list describes the element values:

    • 1 = Does not display the toolbar.

    • 2 = Displays the URL to the report without the logo, toolbar, tabs, or navigation path.

    • 3 = Displays the URL to the report without the header or any parameter selections. Controls such as Template Selection, View, Export, and Send are still available.

    • 4 = Displays the URL to the report only. No other page information or options are displayed.

    • 6 = Displays the BI Publisher toolbar to display the parameter prompts of the BI Publisher report

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.5.5 Enabling the Ability to Export Dashboard Pages to Oracle BI Publisher

Content designers can create custom print layouts for high-fidelity printing of dashboard pages by using the Custom Print Layouts component in the Print Options dialog. Custom print layouts enable end users to produce high-quality printed dashboard content. When a content designer creates a custom print layout for a dashboard page, the dashboard page is exported to BI Publisher. You can enable or disable the ability to export dashboard pages toBI Publisher by setting the EnableDashPageExport element.

For more information on custom print layouts, see "About Creating Custom Print Layouts for High-Fidelity Printing of Dashboard Pages" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To enable the ability to export dashboard pages to BI Publisher:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the AdvancedReporting section in which you must add the EnableDashPageExport element.

  3. Include the element and its ancestor elements as appropriate, as shown in the following example:

    <ServerInstance>
  <AdvancedReporting>
      <EnableDashPageExport>true</EnableDashPageExport>
  </AdvancedReporting>
</ServerInstance>

    The element values are:

    • true — Enables the ability to export dashboard pages to BI Publisher by showing the Custom Print Layouts component in the Print Options dialog. (Default)

    • false — Disables the ability to export dashboard pages to BI Publisher by hiding the Custom Print Layouts component in the Print Options dialog.

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.5.6 Modifying the Table of Contents for PDF Versions of Briefing Books

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 Oracle Fusion Middleware 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.

19.5.7 Configuring a Custom Download Link for the Smart View Installer

Note:

Configuring a custom download link for the Smart View installer applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions.

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

To configure a custom download link for the Smart View installer:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the <CatalogPath> and <DSN>AnalyticsWeb</DSN> elements and add the SmartViewInstallerURL element after those elements.

  3. Use the syntax in the following examples to add the SmartViewInstallerURL element:

    Example for download from Oracle Technology Network:

    <CatalogPath>/example/path/work/abc/instances/instance1/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/catalog/SampleApp</CatalogPath>
<DSN>AnalyticsWeb</DSN>
<SmartViewInstallerURL>http://www.oracle.com/technetwork/middleware/epm/downloads/smart-view-1112x-1939038.html</SmartViewInstallerURL>

    Example for download from an intranet site:

    <CatalogPath>/example/path/work/abc/instances/instance1/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/catalog/SampleApp</CatalogPath>
<DSN>AnalyticsWeb</DSN>
<SmartViewInstallerURL>http://myserver:8080/downloads/smartview.exe</SmartViewInstallerURL>

    Example for download from an internal server

    <CatalogPath>/example/path/work/abc/instances/instance1/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/catalog/SampleApp</CatalogPath>
<DSN>AnalyticsWeb</DSN>
<SmartViewInstallerURL>\\myserver\downloads\smartview.exe</SmartViewInstallerURL>

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.6 Blocking Analyses in Answers

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:

19.6.1 Storing JavaScript Files

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 following directory, which you first deploy as a virtual directory:

ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\analyticsRes

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" />

19.6.2 Blocking Analyses Based on Criteria

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 ORACLE_INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplication_obipsn\analyticsRes 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.

19.6.3 Blocking Analyses Based on Formula

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.) For more information about the helper functions, see Section 19.6.4, "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.

19.6.4 Validation Helper Functions

These functions are defined within a JavaScript file named answers/queryblocking.js. Table 19-9 contains the list of helper functions and their descriptions.

Table 19-9 Validation Helper Functions

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.

19.7 Specifying View Defaults for Analyses and Dashboards

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.

19.7.1 XML Message Files for View Defaults

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.

19.7.2 Examples of Customizing Default Values for Analyses and Dashboards

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.

19.7.2.1 Adding a Default Header or Footer to New Analyses

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>
   </view>
</HTML>
</WebMessage>
   </WebMessageTable>
</WebMessageTables>

19.7.2.2 Preventing Auto-Previewing of Results

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>

19.7.2.3 Setting Defaults for Analyses in the Compound Layout

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>

19.7.2.4 Changing Dashboards Section Defaults

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>

19.7.2.5 Specifying Dashboard Page Defaults Including Headers and Footers

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>

19.8 Configuring for Write Back in Analyses and Dashboards

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:

19.8.1 How Write Back Works

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.

19.8.2 Process for Configuring Write Back

The process for configure write back is as follows:

  1. (for the content designer) Work with the Oracle BI Administrator of the repository to assess the reporting needs in the organization and make a list of write-back columns that are needed and the analyses in which they are displayed.

    Hierarchical columns do not support the write-back capability but attribute columns, measure columns, and double columns do support the write-back capability. For double columns, you can write back to the display column. No automatic translation of the code column is provided.

  2. (for the Oracle BI Administrator of the repository) Create a physical table in the database that has a column for each write-back column needed and select the Allow direct database requests by default option in the General tab of the Database dialog.

    Note:

    For optimum security, store write-back database tables in a unique database instance.

    For how, see Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition

  3. (for the Oracle BI Administrator of the repository) Enable write back on the columns using the Oracle BI Administration Tool. This includes:

    • Disabling caching on the physical table

    • Making the logical columns writeable

    • Enabling Read/Write permissions for the presentation columns

    For how, see "Enabling Write Back On Columns" in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition

  4. (for the administrator) Create write-back template files that specify the SQL commands that are necessary to both insert and update values into table views for which you want to enable write back.

    For how, see Section 19.8.5, "Creating Write-Back Template Files."

  5. (for the administrator) Add the LightWriteback element in the instanceconfig.xml file.

    See Section 19.8.6, "Setting the LightWriteback Element."

  6. (for the administrator) In Oracle BI Presentation Services, grant the following write-back privileges to the appropriate users: Manage Write Back and Write Back to Database.

    For how, see "Managing Presentation Services Privileges" in Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition.

  7. (for the content designer) Add the write-back capability to columns.

    For how, see "Adding the Write-Back Capability to a Column" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

  8. (for the content designer) Add the write-back capability to table views.

    For how, see "Adding the Write-Back Capability to a Table View" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.

19.8.3 Example: Process for Configuring Write Back

  1. After working with the Oracle BI Administrator of the repository, the content designer determines that:

    • These write-back columns are needed: YR, Quarter, Region, ItemType, and Dollars

    • The analysis in which these columns are displayed is titled Region Quota

  2. The Oracle BI Administrator of the repository does the following:

    • Creates a physical table called regiontypequota that includes the YR, Quarter, Region, ItemType, and Dollars columns

    • Selects the Allow direct database request by default option in the General tab of the Database dialog

  3. Using the Oracle BI Administration Tool, the Oracle BI Administrator of the repository:

    • Makes the WriteBack table noncacheable in the Physical layer

    • Makes the Dollars column in the WriteBack table writeable in the Business Model layer

    • Enables Read/Write permission on the Dollars column in the WriteBack table in the Presentation layer to the BI Author and Authenticated User

  4. The administrator creates a write-back template file that contains the following write-back template, named SetQuotaUseID:

    <?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>

    And stores it in:

    ORACLE_INSTANCE/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obipsn/analyticsRes/customMessages

  5. The administrator adds the LightWriteback element to the instance.config.xml file as follows:

    <WebConfig>
    <ServerInstance>
        <LightWriteback>true</LightWriteback>
    </ServerInstance>
</WebConfig>

  6. The administrator grants the following privileges using the Administration: Manage Privileges page in Oracle BI Presentation Services:

    • Manage Write Back to the BI Author

    • Write Back to Database to the Authenticated User

  7. The content designer edits the Region Quota analysis and, for each of the following columns, enables the column for write back by completing the Column Properties dialog: Write Back tab:

    • YR

    • Quarter

    • Region

    • ItemType

    • Dollars

  8. The content designer edits the table view in the Region Quota analysis and enables it for write back by selecting the Enable Write Back box and entering SetQuotaUseID in the Template Name field in the Table Properties dialog: Write Back tab.

19.8.4 Write-Back Limitations

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.

  • 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.

  • 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.

19.8.5 Creating Write-Back Template Files

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.

To create a write-back template file:

  1. Create an XML file. The write-back template file can have any name of your choosing, because the system reads all XML files in the CustomMessages folder.

  2. Add the appropriate elements following the requirements specified in Section 19.8.5.1, "Requirements for a Write-Back Template" and the examples shown in Section 19.8.5.2, "Examples: Write-Back Template Files."

  3. Store the write-back template file in the analyticsRes directory that the administrator has configured for static files and customer messages:

    ORACLE_INSTANCE/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obipsn/analyticsRes/customMessages

    While XML message files that affect a language-specific user interface must be localized, the XML file that is used for configuring a write-back template is usually not translated, because it is language-independent.

    In the rare cases where write-back template files must be language-dependent (for example, if a user logging in using the l_es (Spanish) locale would use a different SQL command than a user logging in using l_fr (French) locale), then the write-back template files should exist in appropriate language directories.

19.8.5.1 Requirements for a Write-Back Template

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>

19.8.5.2 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>

19.8.6 Setting the LightWriteback Element

For users to write back values, you must manually add the LightWriteback element in the instanceconfig.xml file. Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, "Using a Text Editor to Update Configuration Settings."

To manually set the element for write back:

  1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

  2. Locate the ServerInstance section in which you must add the LightWriteback element.

  3. Include the element and its ancestor elements as appropriate, as shown in the following example:

    <WebConfig>
    <ServerInstance>
        <LightWriteback>true</LightWriteback>
    </ServerInstance>
</WebConfig>

    Note that this example does not include elements that might exist in the file, but that are centrally managed by Fusion Middleware Control and cannot be changed manually.

  4. Save your changes and close the file.

  5. Restart Oracle Business Intelligence.

19.9 Customizing the Oracle BI Web User Interface

Note:

The ability to customize the Oracle BI Web User Interface applies to Oracle BI EE 11.1.1.7.10 and later versions, and might not be available in earlier versions. For more information about Oracle BI EE 11.1.1.7.10, see "New Features for 11.1.1.7.10."

The user interface in Oracle BI EE 11g is generated by using scripts and is therefore highly customizable. The look-and-feel is controlled by skins and styles. Skins define the user interface chrome (visible graphic features) outside the home and dashboard area.

Oracle BI EE 11g is shipped with several styles, such as Skyros, blafp (browser look and feel), and FusionFX (fusion applications).

The following sections provide information about how to customize the web user interface:

19.9.1 What Are Skins and Styles?

You can control the way that the interface for Oracle BI EE is displayed to users by creating skins and styles. The primary difference between skins and styles is that styles only apply to 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.

You specify the default style and skin 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 Section 19.9.4, "Modifying the User Interface Styles for Presentation Services" for additional information.

Styles and skins 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" for additional information.

19.9.2 General Tips for Customizing the Web User Interface

As you plan to customize the web user interface, keep the following points in mind:

19.9.3 About Style Customizations

Oracle BI EE 11g ships with various styles, such as blafp (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 Section 19.9.4, "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. Table 19-10 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.

19.9.4 Modifying the User Interface Styles for Presentation Services

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:

19.9.4.1 Approach 1: Deploying the "bicustom.ear" File for the First Time

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.

To deploy the bicustom.ear file for the first time:

  1. Copy ORACLE_HOME\bifoundation\jee\bicustom-template.ear to ORACLE_HOME\bifoundation\jee\bicustom.ear.

    Note:

    The patch or upgrade process may overwrite the bicustom-template.ear file, but it does not overwrite the bicustom.ear file.

  2. Update the bicustom.ear file.

    1. Extract the bicustom.war file from the bicustom.ear file.

    2. Extract the files from the bicustom.war file.

    3. Edit the files to create your custom style and save your changes. See Section 19.9.5, "Customizing Your Style" for additional information.

    4. Update the bicustom.war file with your changes.

    5. Update the bicustom.ear file with your new bicustom.war file.

  3. Deploy the bicustom.ear file.

    1. Log in to Oracle Weblogic Server Administration Console (see Section 2.3, "Centrally Managing Oracle Business Intelligence Java Components Using the Oracle WebLogic Server Administration Console" for additional information.)

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Click Install in the Deployments table.

    5. Navigate to the folder containing the bicustom.ear file (by default, this file is located in ORACLE_HOME\bifoundation\jee).

    6. Select the bicustom.ear file.

    7. Click Next.

    8. Select Install this deployment as an application.

    9. Click Next.

    10. Select I will make the deployment accessible from the following location.

    11. Click Finish.

    12. Click Save.

    13. Click Activate Changes.

  4. Start the new application.

    1. Click Deployments in the Domain Structure region.

    2. Select the bicustom checkbox in the Deployments table.

    3. Click Start, and then select Servicing all requests.

  5. 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 Oracle Fusion Middleware 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. Styles and skins are located in the ORACLE_HOME\bifoundation\web\appv2\res directory.

    1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

    2. 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.

      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_.

    3. Save your changes and close the file.

  6. Restart Presentation Services. See Section 4.1, "About Starting and Stopping Oracle Business Intelligence" for additional information.

Note:

You cannot have a global style in a multitenancy environment. See Chapter 18, "What is Multitenancy?" for detailed information.

To redeploy the bicustom.ear file, see Section 19.9.4.2, "Approach 1: Redeploying the "bicustom.ear" File."

19.9.4.2 Approach 1: Redeploying the "bicustom.ear" File

To update your custom skin:

  1. Update the bicustom.ear file. (See Section 19.9.4.1, "Approach 1: Deploying the "bicustom.ear" File for the First Time.")

  2. Update the deployment.

    1. Log in to Oracle Weblogic Server Administration Console.

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Select the bicustom checkbox in the Deployments table.

    5. Click Update.

    6. Click Finish.

    7. Click Activate Changes.

    8. Click Release Configuration.

  3. 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.

19.9.4.3 Approach 2: Deploying Using Shared Folders

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.

In Oracle BI EE, static files are located in ORACLE_HOME\bifoundation\web\appv2. 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:

Oracle Fusion Middleware Using Web Server 1.1 Plug-Ins with Oracle WebLogic Server

Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server

  1. Create your custom style.

    1. Extract the bicustom.war file from the bicustom-template.ear file.

    2. Extract the contents of the bicustom.war file to a location accessible to Oracle Weblogic Server (for example, c:\custom).

    3. Edit the files to create your custom style and save your changes. See Section 19.9.5, "Customizing Your Style" for additional information.

  2. Deploy the custom folder.

    1. Log in to Oracle Weblogic Server Administration Console.

    2. Click Lock & Edit.

    3. Click Deployments in the Domain Structure region.

    4. Click Install in the Deployments table.

    5. Navigate to the folder containing your custom style (for example, c:\custom).

    6. Click Next.

    7. Select Install this deployment as an application.

    8. Click Next.

    9. Select bi_cluster as the deployment target.

    10. Click Next.

    11. Set the name to AnalyticsRes.

    12. Select I will make the deployment accessible from the following location.

    13. Click Next.

    14. Select Yes, take me to the deployment's configuration screen.

    15. Click Finish.

    16. Click the Configuration tab.

    17. Enter /analyticsRes in the Context Root box.

    18. Click Save.

    19. Click OK.

    20. Click Activate Changes.

    21. Click Release Configuration.

  3. Start the new application.

    1. Click Deployments in the Domain Structure region.

    2. Select the analyticsRes checkbox in the Deployments table.

    3. Click Start, and then select Servicing all requests.

  4. 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.

    1. Open the instanceconfig.xml file for editing, as described in Section 3.6, "Where Are Configuration Files Located?"

    2. Locate the ServerInstance section.

    3. 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.

      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>

    4. Save your changes and close the file.

    5. Restart Presentation Services.

To view your modifications to a shared folder, see Section 19.9.4.4, "Approach 2: Viewing Your Modifications to a Shared Folder."

19.9.4.4 Approach 2: Viewing Your Modifications to a Shared Folder

Once you have configured your shared folder, you can view the changes to the CSS files and images.

To view your modifications:

  1. Reload the metadata.

    1. In Oracle BI EE, click the Administration link in the global header.

    2. On the Administration tab, click the Reload Files and Metadata link.

  2. Clear the browser's cache. Note that this process is dependent on the browser being used.

  3. 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.

19.9.5 Customizing Your Style

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.xml

  • ./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.

Table 19-10 describes the content of the "res" folder structure.

Table 19-10 Application Resources Folder Contents

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 Oracle Fusion Middleware 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.xml

The styleproperties.xml 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.xml 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.

  1. File names, such as s_Custom, are case-sensitive and in lowercase on Linux.

  2. Using the filemap.xml file to specify the style or skin that you are extending is applicable only for Presentation Services.

19.9.6 Example of Modifying the Skyros Master Branding Class

You can modify the CSS for Skyros to effect changes to any element contained within the CSS. For example, if you want to change the background color of the master branding area from black to bright blue, perform the following steps:

To modify the background color:

  1. Open the master.css file.

  2. Scroll down and locate the class that you want to customize. In the sample code, modify the .masterBrandingArea class. Also note that the code contains inline comments to identify that code section.

    .
.
.
.masterHeader
{
    font-weight: bold;
    color: #003d5b;
    text-align: left;
}
/* BRANDING AREA ========================================================= */
/* This class applies to the branding area shown at the top of most pages. */
{
.masterBrandingArea
{
    background-color: #000000;
    color: #ffffff;
    padding: 5px;
}
/* This class applies to the brand name text shown at the top of most pages. */
.masterBrandingAreaBrandName
{
   font-size: 17px;
   font-weight: bold;
.
.
.

  3. Change the HTML background-color code value from #000000 to #3300ff.

  4. Save the file.

  5. Reload the metadata and clear the browser's cache. See Section 19.9, "Customizing the Oracle BI Web User Interface" for additional information.