D Setting Up the SA System Subject Area

Oracle BI Presentation Services delivers alerts from Oracle BI Delivers to specified e-mail addresses, phone numbers, and so on. These delivery destinations are stored in the Oracle Business Intelligence profile for each user. In some cases, you might want to automatically populate the phone numbers or e-mail addresses in user profiles.

If you must automate only the population of e-mail addresses in user profiles, then you should populate the e-mail address field for users in your LDAP server or other authentication provider, if possible. These values are used to populate the e-mail address in Oracle Business Intelligence user profiles, enabling users to receive content from Delivers, even if they have not signed into Oracle Business Intelligence. This feature works for any LDAP server that has a mail attribute for its users.

In some cases, however, you might want to automatically populate additional user profile options, in addition to e-mail addresses. For example, you might want to automatically populate a cell phone number as part of the user profile information, if you want Delivers to deliver a format suitable for a cell phone (like text) using an e-mail gateway.

In this situation, you can configure a special subject area in the repository called SA System that retrieves user information from a database and populates the user profile information. This appendix explains how to configure and use the SA System subject area to accomplish this task.

If you choose to use the SA System subject area, then you should discourage users from configuring delivery profiles on their own. By default, values that are specified in delivery profiles take precedence over values that are shown in the SA System subject area.

This appendix contains the following topics:

• Section D.1, "About the SA System Subject Area"

• Section D.2, "Setting Up the Data Source for the SA System Subject Area"

• Section D.3, "Importing SA System Data Into the Repository"

• Section D.4, "Setting Configuration Options for the SA System Subject Area"

D.1 About the SA System Subject Area

In previous releases of Oracle Business Intelligence, SA System was a subject area that exposed group membership to Delivers and enabled contact information, such as e-mail addresses to be retrieved from a database and used as delivery devices in Delivers. The SA System subject area feature automatically populated delivery devices and profiles for users instead of requiring users to update their My Account screen in Delivers. The SA System subject area provided the users associated with each group and external e-mail addresses to Delivers.

In this release of Oracle Business Intelligence, Delivers still must determine group and role membership so that it can appropriately deliver alerts. Typically, however, your LDAP identity store is now the source of group and role membership. If SA System is defined and enabled, then membership of application roles and catalog groups is derived from the SA System subject area in Delivers. The names of the applications roles and catalog groups that are selected in an agent are used to determine group membership in the SA System subject area.

Note that you do not need SA System if you are using an LDAP server and you must populate only user profile e-mail addresses. The recommended best practice for populating e-mail addresses in user profiles is to use the mail attribute in your LDAP server. Because most portable devices can read e-mail directly, specific text or SMS formats are often not required for agent delivery, and populating e-mail addresses from LDAP is usually sufficient.

Also note that you do not need to use SA system to use the feature Get Recipients from the Analysis Used in the Agent Condition. Instead, this feature is used when the recipients can be determined from the query results and the data to be delivered is specific to those users.

Note that it is possible to configure initialization block-based user authentication using the tables in SA System as a source for the user population. Using the SA System data in this way is separate from using SA System to populate delivery profiles. Rather, these are independent functions that happen to be based on the same user source data.

D.1.1 About Group and Application Role Resolution

In this release of Oracle Business Intelligence, application roles are used to define security policies rather than groups. When you create an agent, you can choose whether it should be delivered to a user, an application role, or a Catalog group.

However, to maintain backward compatibility with previous releases, SA System still uses the Group Name column in the SA System source table to determine the e-mail addresses for the application roles and catalog groups that are specified for agents. Because of this, the SA System subject area functions the same as it did in previous releases, even though the Oracle Business Intelligence security model has changed significantly in the current release.

Because the group membership in SA System is used to determine the list of recipients rather than the membership of either application roles or Catalog groups, users should not add members to Catalog groups. Alternatively, administrators can synchronize the application role and Catalog group memberships with SA System whenever the memberships are updated.

D.2 Setting Up the Data Source for the SA System Subject Area

In your external data source, create a table called User that contains columns that correspond to the various delivery options. In addition, you must ensure that every user and group is present in the data.

Table D-1 shows the columns that are required for the SA System subject area table. You must create the columns that are listed in the order shown. Any external schema that has the information in this table can be mapped to the SA System subject area.

Table D-1 Columns in the SA System User Table

Column	Data Type	Description
Logon	VARCHAR	The unique user ID of the user that logs on to the system. This cannot be null.
Display Name	VARCHAR	The full name of the user. This can be null.
Group Name	VARCHAR	The name of the group to which this user belongs. If a user belongs to multiple groups, then there should be one row for each group in the SA System table. This should not be null if any data access security is based on group membership.
Time Zone	VARCHAR	This column is currently not used and exists for future use. This should be null.
Language	VARCHAR	This column is currently not used and exists for future use. This should be null.
Locale	VARCHAR	This column is currently not used and exists for future use. This should be null.
Email	VARCHAR	The primary e-mail address for the user. This is a complete SMTP address such as [e-mail]. This can be null.
Email Priority	VARCHAR	This determines when an alert is delivered to this device. The value can be any combination of the three priorities of an agent: H for high priority, N for normal priority, or L for low priority. For example, if high, normal, and low priority alerts are to be delivered to this device, then the field should be HNL. If only high and normal priority alerts are to be delivered, then the field should be HN. This field should not be null if the Email column is specified. This can be null if Email is null.
Email Type	VARCHAR	This field can be one of two text strings, HTML or text. Because most primary e-mail clients can read rich MIME content (HTML with embedded images), HTML is usually the best choice. Choose text to support legacy e-mail clients that can read only plain text e-mail. This field should not be null if the Email column is specified. This can be null if Email is null.
Cell Phone	VARCHAR	This field is the complete SMTP address for the cell phone device that receives text message alerts. For example, [e-mail]. Only text messages are sent to this device. This can be null.
Cell Phone Priority	VARCHAR	This determines when an alert is delivered to this device. The value can be any combination of the three priorities of an agent: H for high priority, N for normal priority, and L for low priority. This field should not be null if the Cell Phone column is specified. This can be null if Cell Phone is null.
Pager	VARCHAR	This field is the complete SMTP address for the pager device that receives text message alerts. For example, [e-mail]. Only text messages are sent to this device. This can be null.
Pager Priority	VARCHAR	This determines when an alert is delivered to this device. The value can be any combination of the three priorities of an agent: H for high priority, N for normal priority, and L for low priority. This field should not be null if the Pager column is specified. This can be null if Pager is null.
Handheld	VARCHAR	This field is the complete SMTP address for the handheld device that receives text message alerts. For example, [e-mail]. Only text messages are sent to this device. This can be null.
Handheld Priority	VARCHAR	This determines when an alert is delivered to this device. The value can be any combination of the three priorities of an agent: H for high priority, N for normal priority, and L for low priority. This field should not be null if the Handheld column is specified. This can be null if Handheld is null.

D.3 Importing SA System Data Into the Repository

After you configure the external data source, you must create and build the subject area in the Oracle BI repository. To do this, you first import the User table from the data source into the Physical layer. Then, map the User table and columns from the Physical layer to the Business Model and Mapping layer. Finally, map the User table and columns from the Business Model and Mapping layer to the Presentation layer. The name for the subject area must always be SA System.

See Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition for information about importing data into the repository and modeling information in the Business Model and Mapping layer and Presentation layer.

Figure D-1 shows the table and columns in the Presentation layer of the repository.

Figure D-1 SA System Subject Area in the Presentation Layer

Description of "Figure D-1 SA System Subject Area in the Presentation Layer"

D.4 Setting Configuration Options for the SA System Subject Area

You can control the availability of the delivery options that are configured in the SA System subject area and the user-defined delivery options by including certain elements in the instanceconfig.xml file. These elements take effect only if the SA System subject area is being used.

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

To change configuration options for the SA System subject area:

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 following elements:

   • SystemSubjectArea: Specifies whether to recognize the delivery devices and deliver profiles that are configured in the SA System subject area:

     • True. Recognizes the delivery devices and delivery profiles that are configured in the SA System subject area and displays them on the My Account page. (Default)

     • False. Ignores the delivery devices and delivery profiles that are configured in the SA System subject area and does not display them on the My Account page.

     Include this element within the ServerInstance element.

   • IgnoreWebcatDeliveryProfiles: Specifies whether to ignore user-defined delivery devices and deliver profiles:

     • True. Ignores the user-defined delivery devices and delivery profiles and does not display them on the My Account page. (This means that users cannot create new delivery devices and delivery profiles.)

     • False. Recognizes the user-defined delivery devices and delivery profiles and displays them on the My Account page. (Default)

     Include this element within the Alerts element, which is itself included in the ServerInstance element.

   • UpperCaseRecipientNames: Specifies that only users whose user names are uppercase can have agents delivered to them.

     For example, suppose that you have users with names of user_lowercase and USER_UPPERCASE. If you set the UpperCaseRecipientNames element to true, then agents are sent only to USER_UPPERCASE.

     Include this element within the Alerts element, which is itself included in the ServerInstance element.

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

   <ServerInstance>
     <SubjectAreaMetadata>
       <SystemSubjectArea>true</SystemSubjectArea>
     </SubjectAreaMetadata>
      <Alerts>
        <IgnoreWebcatDeliveryProfiles>false</IgnoreWebcatDeliveryProfiles>
        <UpperCaseRecipientNames>true</UpperCaseRecipientNames>
      </Alerts>
   </ServerInstance>
   

4. Save your changes and close the file.

5. Restart Oracle Business Intelligence.

D.4.1 Managing the Case of Login Names for the SA System Subject Area

When the SA System subject area is used, login names are compared to the Logon column in the SA System subject area. By default, this comparison is case-sensitive. This means, for example, that a login of "Fred" does not match an SA System subject area entry of "fred." If the authentication method is case-sensitive, then this works fine because the login "fred," accepted at login, matches "fred" in the Logon column in the SA System subject area.

If the case of login names does not match, then invalid user name errors might result. To avoid this situation, ensure that the SA_SYSTEM Logon value and the LDAP user name value have the same case. For example, set the LOGON value in the SA_USER table to lowercase by including it within the Lower() function.

You can also use the UpperCaseRecipientNames element in the instanceconfig.xml file to ensure delivery only to users whose names are uppercase.