Oracle® Fusion Middleware Integrator's Guide for Oracle Business Intelligence Enterprise Edition 11g Release 1 (11.1.1) E16364-01 |
|
Previous |
Next |
This chapter describes the Oracle BI EE Action Framework and explains the configuration required to add actions to Oracle BI EE content. This chapter contains the following topics:
Section 4.2, "Overview of the Action Framework Configuration"
Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework"
The Action Framework is a component of the Oracle BI EE architecture. It consists of the following items:
Actions Web Services for creating and invoking actions that are deployed in the application server.
Components that reside within the Presentation Server and Scheduler Services.
Actions-specific JavaScript in the presentation tier for creating actions and invoking certain action types directly from the browser.
To prepare the Action Framework for use in Oracle BI Presentation Services, you must perform the following tasks:
Configure the Action Framework. For more information, see Section 4.2, "Overview of the Action Framework Configuration" and Section 4.3, "Configuring the Action Framework".
Secure Actions. For more information, see Section 4.4, "Overview of Action Security" and Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
Set up action targets. For more information, see Section 4.6, "Target Functionality for Actions".
The Action Framework provides functionality for creating, managing, and invoking actions. Actions provide functionality to:
Navigate to related content.
Invoke operations, functions, or processes in external systems.
Actions are created and managed in the Oracle BI Presentation Services user interface. Actions can be included within analyses, dashboards, agents, KPIs, and Scorecard objectives. There are several different types of actions, for example, Navigate to a Web Page, Invoke a Web Service, and Invoke a Browser Script.
For a list of action types, their descriptions, and information about creating and using actions, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
The actions that are available in Oracle BI EE are categorized into two groups: those actions that navigate to related content; and those actions that invoke operations, functions, or processes in external systems. Actions are further categorized into action types based on the technology they invoke (for example, URL or Web service).
For a description of each action types and information about adding Action links to business intelligence content, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
Table 4-1, "System Components that Execute Actions" shows each action type and the system components that execute them. For more information about how a specific action type is executed and the other system components that are used in the process, see Section 4.6, "Target Functionality for Actions".
Table 4-1 System Components that Execute Actions
Action Type | Executed by... |
---|---|
Navigate to BI Content |
Browser |
Navigate to a Web Page |
Browser |
Navigate to EPM Content |
Browser |
Navigate to E-Business Suite |
Browser |
Invoke a Web Service |
AES |
Invoke a Java Method (EJB) |
AES |
Invoke a Browser Script |
Browser |
Invoke an HTTP Request |
AES |
Invoke Server Script |
Scheduler |
Invoke Agent |
Scheduler |
Java Jobs |
Javahost |
Some action types are automatically available when Oracle BI EE is installed, while others require specific configuration to make them available. For action types requiring additional configuration, you must provide information about the external systems hosting functionality to be invoked by the actions, including the location of the target functionality and access details.
Where security policies are applied to action targets (for example, a target Web service that is secured using a SAML-based policy), you must create security policy files in the same location.
A keystore is also required for security policies that include encryption or signing. For information about policy files and keystores, see Section 4.4, "Overview of Action Security".
Certain actions require credentials to be entered into the credential store. These credentials are used for either browsing for action targets when creating an action or when invoking the target action. For information about additional credentials for actions, see Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
This section summarizes the configuration you must perform to use each action type. Table 4-2, "Configuration Requirements by Action Type" lists each action type and its required confirmation. Note the following column descriptions:
Column 1 contains the name of each action type displayed by the Oracle BI EE user interface.
Column 2 indicates whether an entry in the configuration file is required so that the Oracle BI EE Presentation Services action menus displays the action type.
Column 3 indicates whether a registry entry can be added to the configuration file to enable a browsable list of action targets in the Web front-end.
Column 4 indicates whether additional credentials are required in the credential store.
Column 5 indicates the action types that can implement various security policies and therefore require policy files and, where necessary, additional keystore information.
Table 4-2 Configuration Requirements by Action Type
Action Type | Requires Configuration Entry? | Supports Registries? | Additional Credentials Required? | Policy Enabled? |
---|---|---|---|---|
Navigate to BI Content |
No |
No (Browse for navigation targets enabled by default.) |
No |
No |
Navigate to Web Page |
No |
No |
No |
No |
Navigate to EPM Content |
Yes (Registry) |
Yes (Mandatory) |
Yes |
No |
Navigate to E-Business Suite |
Yes |
No |
No (Requires Oracle E-Business Suite security integration.) |
No |
Invoke a Web Service |
No |
Yes (Optional) |
No (Optional) |
Yes |
Invoke a Java Method (EJB) |
Yes (Registry) |
Yes (Mandatory) |
Yes |
No |
Invoke a Browser Script |
No |
No (Browse for navigation targets enabled by default.) |
No |
No |
Invoke an HTTP Request |
No |
No |
No |
No |
Invoke Server Script |
No |
No |
No |
No |
Invoke Agent |
No |
No |
No |
No |
Java Job |
No |
No |
No |
No |
All actions require a target. A target is something to navigate to or an operation, function, or process to invoke. Before you create an action, you should confirm that the target for the action is in place. For example, a target URL should be available for a Navigate to a Web Page action, and a target Web service should be in place for an Invoke Web Service Action.
Some action types have targets within the Oracle Business Intelligence system (for example, Navigate to BI Content), while other action types are primarily for invoking functionality or navigating to content in external systems (for example, Invoke a Java Method). In all cases, the process of creating an action assumes that a suitable target already exists for the action to consume.
For example, suppose that a content designer is building a dashboard that requires an action that the user clicks to book a meeting room. To accomplish this task, you might use Oracle JDeveloper to create and deploy a Web service named Room Booking Service with an operation named bookRoom. This is the target Web service operation to be invoked by the action. After you create and deploy the Web service, the content designer is able to create an "Invoke a Web Service" action.
The Oracle BI EE installation contains a configuration file named ActionFrameworkConfig.xml. You manually edit this configuration file to specify how you want the Action Framework to behave. This configuration file is located by default in the following location:
<Oracle Middleware Home>\user_projects\domains\bifoundation_domain\config\fmwconfig\biinstances\coreapplication
The configuration file contains several elements. Table 4-3, "Action Framework Configuration Elements" describes each element.
Table 4-3 Action Framework Configuration Elements
Element Name | Description |
---|---|
location-alias |
Use to enable actions to refer to a location alias rather than a fixed URL. Setting up aliases can make migrating between test and production systems easier. For more information about this element, see Section 4.3.1, "Aliases". |
registry |
Use to provide information about the pre-configured registries for Web Services, EJBs, and so on. that provide predefined sets of targets for actions. For more information about this element, see Section 4.3.2, "Registries". |
content-type |
Use to provide information about the types of content for which a registry returns information. For more information about this element, see Section 4.3.3, "Content Types". |
account |
Use to provide information about gateway accounts. Use for authenticating to action targets. For more information about this element, see Section 4.3.4, "Accounts". |
policy |
Use to provide information about the location of Oracle Web Services Manager (OWSM). For more information about this element, see Table 4-6, "Policies". |
proxy |
Use to provide information about proxy settings for accessing Web Services or URLS. For more information about this element, see Table 4-7, "Proxy". |
ebusinesssuiteconfig |
Use to specify whether the custom action "Navigate to E-Business Suite" displays in the Oracle BI Presentation Services user interface. For more information about this element, see Table 4-8, "ebusinesssuiteconfig". |
A sample action configuration file is available for download from the Oracle Web site. You can use the samples contained in this file along with this document to understand the various ways to configure actions. The sample files are located at the following Oracle Web site:
http://www.oracle.com/technology/products/bi/enterprise-edition.html
After you modify the configuration file, you need to restart the Managed Server in Weblogic that is hosting your Oracle BI EE environment. For general information about how to restart the Managed Server in Weblogic, see "Confirming Whether the Managed Server is Running, and Starting it if Necessary" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
This topic describes the location alias element. Location aliases provide a substitution mechanism so that actions refer to an alias rather than a fixed URL. Aliases are useful if you want to switch between test and production systems. The aliases element can contain zero or more location-alias elements. Note the following example:
<location-alias> <alias>webservicehost</alias> <actual>myserver.oracle.com:7001</actual> </location-alias>
Based on the webservicehost
alias in this example, an Oracle BI EE user is able to create an action to invoke a target Web service through the following WSDL:
http://msyserver.oracle.com:7001/MyWebService/myservice.wsdl
The action saved to the catalog stores the reference to the WSDL as:
http://@[webservicehost]/MyWebService/myservice.wsdl
When this action is invoked, the Action Framework substitutes the alias for the actual value before invoking the service.
The Administrator can later change the "actual" element value within the location-alias
element so that the saved action points to a different URL without requiring an update the action.
An alias can refer to the server and the application path. Therefore, the following example is also valid. Note that the alias should not include the full path to the target WSDL.
<location-alias> <alias>webservicehost</alias> <actual>myserver.oracle.com:7001/MyWebService/</actual> </location-alias>
This topic describes the registry element. A registry defines how the Action Framework should access a browsable library of action targets. For more information about action types and their configuration requirements, see Section 4.2, "Overview of the Action Framework Configuration".
You can create registry definitions to support the following action types:
Navigate to Oracle's Hyperion Enterprise Performance Management (EPM) content
Invoke a Web Service
Invoke a Java Method (EJB)
The Hyperion registry contains no additional elements beyond the standard registry elements. The location element should be used to define the Hyperion URL to interrogate. You will need to specify an account with access to the Hyperion targets. The following example is an entry for an EPM content action type. See Table 4-4, "Registry Entry Elements and Descriptions" for a description of each element.
<registry> <id>HDPreg</id> <name>Hyperion Directory Provider</name> <content-type>epm</content-type> <provider-class>oracle.bi.action.registry.epm.HDPRegistry </provider-class> <description>Hyperion Financial Reports Registry</description> <location> <path>http://epms.oracle.com:1901/workspace/browse/listXML</path> </location> <service-access> <account>EPM</account> </service-access> </registry>
The following example is an entry for an EJB registry of Java methods. The ejb-targets element, which is embedded within the custom-config element, tells the EJB registry specifically about the application server hosting the EJBs and the EJBs that should be exposed as registries from that server.
See Table 4-4, "Registry Entry Elements and Descriptions" for a description of each element.
<registry> <id>reg03</id> <name>Sample EJBs</name> <content-type>java</content-type> <provider-class>oracle.bi.action.registry.java.EJBRegistry</provider-class> <description>Custom Java classes which can be invoked as action targets</description> <location> <path/> </location> <custom-config> <ejb-targets> <appserver> <context-factory>weblogic.jndi.WLInitialContextFactory </context-factory> <jndi-url>t3://localhost:9704</jndi-url> <server-name>localhost</server-name> <account>WLSJNDI</account> <ejb-exclude>mgmt</ejb-exclude> <ejb-exclude>PopulationServiceBean</ejb-exclude> </appserver> <ejb-app> <server>localhost</server> <app-context>ActionSamplesEJB</app-context> </ejb-app> </ejb-targets> </custom-config> </registry>
The following example is an entry for a WSIL registry of Web Services. See Table 4-4, "Registry Entry Elements and Descriptions" for a description of each element.
<registry> <id>reg1</id> <name>Sample Web Services</name> <content-type>webservices</content-type> <provider-class>oracle.bi.action.registry.wsil.WSILRegistry</provider-class> <description></description> <location> <path>http://localhost:9704/ActionSamples/inspection.wsil</path> </location> <service-access> <path>/Sample Web Services/Rating Service</path> <policy>SAMLPolicy</policy> <propagateIdentity>true</propagateIdentity> </service-access> <service-access> <path>/Sample Web Services/Customer Rating Service</path> <account>PayrollUser</account> <policy>userNamePolicy</policy> <propagateIdentity>false</propagateIdentity> </service-access> </registry>
Table 4-4, "Registry Entry Elements and Descriptions" contains each registry element and its description.
Table 4-4 Registry Entry Elements and Descriptions
Element | Description |
---|---|
registry |
This element is the outer-most element that contains the registry definition. |
id |
This element holds an internal identifier that must be unique for each registry. |
name |
This element is the display name that is used by the ActionRegistryService when displaying the list of registries. The name that you specify in this element is also used as the root path for any targets within this registry. |
content-type |
You can use Oracle supplied values only. This element points to a content-type, which is another element defined in the Action Framework configuration file. For more information, see Section 4.3.3, "Content Types". |
provider-class |
You can use Oracle-supplied values, only. Table 4-5, " Provider-Class Element Values" contains the valid values for this element. |
description |
This element is reserved for future use. |
location |
This element specifies the path to the registry that may contain aliased elements. For example, a WSIL file. |
service-access |
This element is optional. You can define zero or more service-access elements in a registry definition. The service-access element specifies the authentication required to access the registry and, where specified, sub-paths within that registry. Note the following:
|
path |
This element is optional. This element is located within the service-access element and specifies a path to a subset of the services in the registry. The path is not a physical location. The path hierarchy starts with the registry name and can be found in the user interface by expanding the nodes that lead to a particular action target when creating a new action. |
account |
This element is optional. This element is located within the service-access element and points to an instance of an account element defined elsewhere in the configuration file. If a registry element contains a service-access element with just an account element, then that account is used to access all services within that registry that are not specified by specific path-based service-access elements. For webservices registries, the credentials held against the account referenced are used by the Action Framework to invoke target actions if the propagateIdentity element has a value of false. For epm registries, the credentials held against the account are used by the Action Framework to browse for EPM content. |
policy |
This element is optional. Use this element for webservices registries only. This element is located within the service-access element and points to a policy defined in the policies section elsewhere in the configuration file. This element is required for accessing target Web Services that define a WS-Security policy. Note that when invoking secured Web Services in this way, you need to correctly configure OWSM to work with Actions. For more information, see Section 4.5.3, "Configuring OWSM". |
propogateIdentity |
Use this element for webservices registries only. This element must be set if the policy element is set. This element is located within the service-access element and can be set to true or false. A value of true is valid when used in conjunction with policies that assert identity (for example, SAML-based policies) to enable propagating the identity of the user who initially invoked the action. If the propagateIdentity element is set to true, the account element becomes redundant and instead the identity of the user who invoked the action (for example, in Oracle BI Presentation Services or run as in scheduler) is used to invoke the target Web service. Setting this element to true in conjunction with a username/password token policy is not supported. |
custom-config |
Use this element for java registries only. This element is used to specify how to access the EJBs on the target application server. |
ejb-targets |
Use this element for java registries only. This element defines the application server where EJBs are deployed in the appserver element, and one or more J2EE applications containing EJBs on the specified appserver that is exposed in the ejb-app elements. |
appserver |
Use this element for java registries only. This element is located within the ejb-target element and defines the connection and authentication information to connect to the application server where EJBs are deployed. This element contains the following elements:
|
ejb-app |
Use this element for java registries only. This element points to one or more J2EE applications containing EJBs. This element contains the following elements:
|
Table 4-5, " Provider-Class Element Values" contains the valid values for the provider-class element. For more information about the provider-class element, see Table 4-4, "Registry Entry Elements and Descriptions".
Table 4-5 Provider-Class Element Values
Related Action Type | Content Type | SPI Class |
---|---|---|
Navigate to EPM Content |
EPM |
oracle.bi.action.registry.epm.HDPRegistry |
Invoke a Java Method (EJB) |
Java |
oracle.bi.action.registry.java.EJBRegistry |
Invoke a Web Service |
Web Services |
oracle.bi.action.registry.wsil.WSILRegistry |
This topic describes the content-type element. Each content-type element provides meta-information about the types of services to which the registries are connecting. The content types provided during installation should not be modified. You can use only the content types shown in the following example:
<content-types> <content-type> <typename>webservices</typename> <displayname>Web Services and BPEL Processes</displayname> <actionType>WebServiceActionType</actionType> </content-type> <content-type> <typename>epm</typename> <displayname>Hyperion Applications</displayname> <actionType>URLActionType</actionType> </content-type> <content-type> <typename>misc</typename> <displayname>Mixed Services</displayname> <actionType>URLActionType</actionType> </content-type> <content-type> <typename>java</typename> <displayname>Java Actions</displayname> <actionType>JavaActionType</actionType> </content-type> </content-types>
This topic describes the account element. The account element defines gateway accounts, which are used for authentication to action targets. The registry element's service-access element then references the accounts that you have specified. For more information about the registry section, see Section 4.3.2, "Registries".
The following example is an account entry. Table 4-6, " Account Elements and Descriptions" describes each element.
<account> <name>SAMLTest</name> <description>Test SAML Account</description> <adminonly>false</adminonly> <credentialkey>SAMLTest</credentialkey> <credentialmap>oracle.bi.actions</credentialmap> </account>
Table 4-6, " Account Elements and Descriptions" contains each account element and its description. For information about storing credentials, see Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
Table 4-6 Account Elements and Descriptions
Element | Description |
---|---|
name |
This element specifies the name referenced in registry service-access elements, or the appserver element for Java registries. Each account must have a unique name within the Action Framework configuration. |
description |
This element is reserved for future use. |
adminonly |
This element is reserved for future use. You must set this element to false. |
credentialkey |
This element is used for looking up credentials in Oracle's Credential Store Framework (CSF). A set of credentials with the specified key must exist in the domain credential store. |
credentialmap |
This element specifies the map in which to look for the credentialkey in CSF. |
The policy element is used to describe the location of OWSM client policy files used in accessing secured Web Services as action targets. Each policy element provides a name to reference the policy that may then be used by service-access elements as a shorthand to specify that the AES should apply the policy file referred to when invoking an action target covered by that service-access element.
Note: To invoke a secured Web service as described above, you must configure OWSM to work with Actions. For more information, see Section 4.5.3, "Configuring OWSM". |
The following example is a policy entry. Table 4-7, "Policy Elements and Descriptions" describes each element.
<policy> <name>SAMLPolicy</name> <policyfile>ActionsSAMLPolicy.xml</policyfile> </policy>
Table 4-7, "Policy Elements and Descriptions" contains each policy element and its description.
Table 4-7 Policy Elements and Descriptions
Element | Description |
---|---|
name |
This element specifies the name referenced in service-access elements. Each policy must have a unique name within the Action Framework configuration. For more information about the service-access element, see Section 4.3.2.4, "Registry Elements Descriptions". |
policyfile |
Use this element to enable actions to invoke Web Services that have WS policies applied to them. This element specifies the name of a file stored in the same directory as the ActionFrameworkConfig.xml file. This file contains an OWSM policy that OWSM applies at runtime when a Web service action that was created from a registry path using this policy is executed. For more information about the service-access element, see Section 4.3.2.4, "Registry Elements Descriptions" |
You need to manually create a separate Action Framework policy file for each distinct client security policy being used to secure target Web services. An Action Framework policy file contains a reference to a Web services client policy defined in OWSM, which provides a standard WS-Policy PolicyReference element used to invoke a target Web service.
To manually create or copy these files, access the sample files, which are located here:
http://www.oracle.com/technology/products/bi/enterprise-edition.html
After you create or copy the files, save them in the same folder as the main ActionFrameworkConfig.xml.
See the following example of an Action Framework Policy file's contents:
<?xml version="1.0" encoding="UTF-8"?>
<oracle-webservice-clients>
<webservice-client>
<port-info>
<policy-references>
<policy-reference uri="oracle/log_policy" category="management"/>
<policy-reference uri="oracle/wss11_saml_token_with_message_protection_ client_policy" category="security"/>
</policy-references>
</port-info>
</webservice-client>
</oracle-webservice-clients>
The Action Framework policy file needs to point to the appropriate client policy in order to invoke a Web service secured by a service policy.
For example, if a target Web service is secured by the policy "oracle/wss11_saml_token_with_message_protection_service_policy," then the Web service client (that is, in this case the Action Framework) needs to use the counterpart client policy to invoke this Web service. The appropriate client policy in this example is "oracle/wss11_saml_token_with_message_protection_client_policy."
You should enter the name of the appropriate client policy into the Action Framework policy file against the "policy-reference uri" element with a category of "security."
The service and client Web services policies available through OWSM can be viewed through Enterprise Manager's Fusion Middleware Control by selecting Web Services and then Policies from the Weblogic domain. For more information about the predefined policies available through OWSM, see "Predefined Policies" in Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
The proxy element specifies proxy settings. The proxy settings are used for accessing items such as Web Services and URLs that would ordinarily be inaccessible from the network containing the Weblogic server where the Action Framework Web Services are deployed.
The following example is a proxy entry. Table 4-8, " Proxy Elements and Descriptions" describes each element.
<proxy> host>proxyserver.oracle.com</host> <port>80</port> <userid>jsmith</userid> <password>johsmi</password> <nonProxyHosts>localhost|*.oracle.com|10.1.10.78 </nonProxyHosts> </proxy>
Table 4-8, " Proxy Elements and Descriptions" contains each proxy element and its description.
Table 4-8 Proxy Elements and Descriptions
Element | Description |
---|---|
host |
This element specifies the host name of the server where the proxy server is located. |
port |
This element specifies the proxy server's port number. |
userid password |
These element specifies the userid and password for the proxy server. Use these elements for a proxy that requires authentication. Leave these elements blank for a non-authenticating proxy. |
nonProxyHosts |
This element allows for a pipe character (|) separated list of the server, domain names, and patterns to exclude from the proxy. Use this element so the system does not attempt to use the proxy to access internal resources. |
The ebusinesssuiteconfig element specifies that an Oracle E-Business Suite system is available. If this element is present in the configuration file, Oracle BI Presentation Services displays the menu option that allows users to create a Navigate to E-Business Suite action. Users must have the proper privileges to access E-Business Suite from Oracle BI Presentation Services.
The following example is an ebusinesssuiteconfig entry.
<ebusinesssuiteconfig> <visible>true</visible> </ebusinesssuiteconfig>
Action Framework and actions security is determined by credentials, privileges, and permissions.
Credentials are security-related attributes used to authenticate or authorize users and systems requesting access to Oracle BI EE resources such as actions. If you have configured one or more registries in the Action Framework to use credentials in the credential store for either browsing for actions targets or invoking actions (namely, if you have specified account elements in the ActionFrameworkConfig.xml) you need to enter a credential into the credential store to match each account element in the ActionFramworkConfig.xml file.
For example, if you have the following account defined in the configuration file, you need to enter a credential for JNDIUser into a map called oracle.bi.actions.
<account> <name>WLSJNDI</name> <description>Account used to access WLS JNDI.</description> <adminonly>false</adminonly> <credentialkey>JNDIUser</credentialkey> <credentialmap>oracle.bi.actions</credentialmap> </account>
For more information about how enter a credential into the credential store, see Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
Actions privileges control the rights that users have to access the actions features and functionality in Oracle BI Presentation Services. The Oracle BI EE Administrator grants or denies privileges to specific application roles, individual users, and Catalog groups. The actions privileges are:
Create Navigate Actions
Create Invoke Actions
Save Actions containing embedded HTML
For more information about the action privileges, see "Access to Oracle BI Enterprise Edition Actions" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
Action permissions are authorizations that the action's owner grants to users or roles. Permissions determine what tasks a user can perform on an action (for example, execute the action). The Oracle BI EE Administrator must give an action's owner the necessary privileges before the owner can assign permissions to action catalog objects. The action permissions are:
Delete
Execute
Read
Write
For more information about assigning permissions to action object stored in the catalog, see "Permission Definitions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
This section contains the following procedures:
Use these procedures to enter a credential into the credential store to match each account element in the ActionFrameworkConfig.xml file. For more information about setting up credentials with Action Framework, see Section 4.4.1, "Oracle BI EE Credentials".
Use the following procedure to add a credential map and credential key to the credential store.
Log into Oracle Enterprise Manager 11g Fusion Middleware Control. The default location is http://<your host name>:7001/em
.
Expand the tree menu to view your domain, and then right-click on the domain name. An options list displays.
Highlight the Security option and from the list, select Credentials. The "Credentials" dialog displays.
Click Create Map and add a new map.
Click Create Key and add a key against the credential map you created.
Save the key and map.
Note the following account element.
<account> <name>SecureTest</name> <description>Test Secure Account</description> <adminonly>false</adminonly> <credentialkey>SecureTest</credentialkey> <credentialmap>oracle.bi.actions</credentialmap> </account>
If you have this account element in your ActionFrameworkConfig.xml and the following conditions are true:
this account element is referenced by a registry to invoke a Web service secured using a username and password policy
the propagateIdentity element is set to false,
then you must enter a username and password that is valid for invoking the target Web service. This should be added to a credential map called oracle.bi.actions against a credentialkey of SecureTest.
Use the following procedure to create a default self-signed keystore. Note that creating a default keystore is suitable for demonstration or development use, but is not suitable for production use. In production, a keystore that was created by importing a valid, correctly signed certificate should be used as described in the keytool documentation. For security policies that involve signing or encryption, you must also add a certificate to the bifoundation_domain keystore.
For more information about keytool and Solaris/Linux, go to http://java.sun.com/javase/6/docs/technotes/tools/solaris/keytool.html
.
For information about keytool and Windows, go to http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html
.
Confirm that your installer installed the JDK bin directory and that it displays in your path. For example, <MIDDLEWARE_HOME>/jdk160_11/bin/
.
Open a command prompt at <MIDDLEWARE_HOME>/user_projects/domains/bifoundation_domain/config/fmwconfig
.
Run the following command to create a default keystore.
keytool -genkeypair -keyalg RSA -alias orakey -keypass orakey_passphrase -keystore default-keystore.jks -storepass store_passphrase -validity 3600
The command creates a keystore with the name default-keystore.jks (if it does not already exist) and adds a new private key entry with alias "orakey" and password as "orakey." You can change the alias, password, and storepass in the command, but they must match the OWSM credentials added to the credential store in the Section 4.5.3, "Configuring OWSM" procedure.
When prompted, answer the questions. Enter responses relevant to your organization. See the example. Note that in the example, the user "weblogic" refers to the System Administrator user created during the install. If you chose a user other than "weblogic," enter that username instead.
What is your first and last name? [Unknown]: weblogic What is the name of your organizational unit? [Unknown]: J2EE Test Encryption Purposes Only What is the name of your organization? [Unknown]: Oracle What is the name of your City or Locality? [Unknown]: US What is the name of your State or Province? [Unknown]: US What is the two-letter country code for this unit? [Unknown]: US Is CN=weblogic, OU=J2EE Test Encryption Purposes Only, O=Oracle, L=US, ST=US, C=US correct? [no]: yes
Confirm that the keystore was generated correctly by using the following command to list its contents.
keytool -list -v -keystore default-keystore.jks -storepass welcome1
Running this command produces a response similar to the following example.
Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry Alias name: orakey Creation date: 16-Sep-2009 Entry type: PrivateKeyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=weblogic, OU=J2EE Test Encryption purposes Only, O=Oracle, L=US, ST=US , C=US Issuer: CN=weblogic, OU=J2EE Test Encryption purposes Only, O=Oracle, L=US, ST=U S, C=US Serial number: 4ab0ee4e Valid from: Wed Sep 16 14:55:26 BST 2009 until: Fri Jul 26 14:55:26 BST 2019 Certificate fingerprints: MD5: 84:0E:F4:F4:F3:30:0B:FF:4C:D4:E5:E6:BE:AE:64:DF SHA1: E4:73:80:4D:96:A6:9F:DE:06:0E:82:3B:D3:18:86:57:FE:CD:C6:37 Signature algorithm name: SHA1withRSA Version: 3 ******************************************* *******************************************
Check if the default-keystore.jks file exists at the path. If it does not exist, copy it there.
<MIDDLEWARE_HOME>/user_projects/domains/bifoundation_domain/config/fmwconfig
Use the following procedure to configure OWSM to work with actions. Perform this procedure so that you can create an action that invokes a Web service where the target Web service has a WS security policy applied to it.
For security policies that involve signing or encryption, you must also add a certificate to a keystore. Note that the enc-csf-key, keystore-csf-key, and sign-csf-key credentials should match the corresponding passphrases given in the keypass and storepass arguments when running keytool.
In Enterprise Manager, add a credential map named oracle.wsm.security. For instructions on how to add a credential map, see Section 4.5.1, "Adding a Credential Map and Credential Key to the Credential Store".
Add the following keys to the oracle.wsm.security map.
Table 4-9 oracle.wsm.security Map Keys
Keyname | Type | User Name | Password |
---|---|---|---|
basic.credentials |
Password |
weblogic* |
welcome1 |
enc-csf-key |
Password |
orakey |
welcome1 |
keystore-csf-key |
Password |
owsm |
welcome1 |
sign-csf-key |
Password |
orakey |
welcome1 |
* This username refers to the System Administrator user created during the installation. If you chose a username other than "weblogic," enter that user name instead. Similarly, you should use the password for that account during install.
Save the map.
This section contains further information about setting up target functionality in external systems. The action links added to business intelligence content invokes these target functionalities. The action types explained in this section are:
This action type allows users to browse for target content in the EPM repository and then create an action to navigate to the selected content. Only navigation to Oracle Hyperion Financial Reporting content is currently supported.
For more information about creating this action type in Presentation Services, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
In order for the Action Framework to provide this action type, you must have performed the following tasks:
Modified the configuration file's registry element. For information about this required configuration, see Section 4.3.2.1, "Navigate to EPM Content Action Type Registry Example".
Added a credential to the credential store to enable the browse for EPM content functionality. For more information, see Section 4.4.1, "Oracle BI EE Credentials" and Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
Figure 4-1, "Navigate to EPM Content Process Flow" illustrates the Navigate to EPM Content action type's process flow.
Figure 4-1 Navigate to EPM Content Process Flow
This action type allows users to navigate from Oracle BI EE to Oracle E-Business Suite. The Oracle BI EE session holds the context of the user's Oracle E-Business Suite session, including the current Oracle E-Business Suite responsibility in the Oracle BI EE session variables.
A Navigate to Oracle E-Business Suite action takes two parameters:
Connection Pool - This parameter contains the name of the BI connection pool that connects to the target Oracle E-Business Suite environment as defined in the repository.
Function - This parameter contains the name of the target Oracle E-Business Suite function to which to navigate. The Oracle E-Business Suite administrator needs to provide the target function ID.
Note that before users can invoke a Navigate to E-Business Suite action, they must have privileges to execute direct database requests against the Oracle E-Business Suite connection pool.
Note that for a user to successfully invoke a Navigate to E-Business Suite action, the target Oracle E-Business function must be accessible from the user's current Oracle E-Business Suite.
For information about this action type's required security integration configuration, see Chapter 5, "Integrating with Oracle E-Business Suite Security".
You can use Oracle Forms Builder to customize a target form and add one or more new, custom parameters to be populated from Oracle BI EE. For information about completing this task, see the Oracle Forms Developer and the Oracle E-Business Suite documentation.
You can use Oracle E-Business Suite's Forms Personalization to map the value or values from these new custom parameters into the form fields used by Oracle E-Business Suite for searching for transactions. For information about completing this task, see the Oracle E-Business Suite documentation.
When you create an action to navigate to the target Oracle E-Business Suite function, you must manually add new parameters with the same names as the custom parameters that you added to the Oracle E-Business Suite form. Note that the new parameters that you add are in addition to the two default parameters (Connection Pool and Function).
After you add the parameters and you invoke the action, Oracle BI EE passes the parameters to the target Oracle E-Business Suite form. Finally, the Form Personalizations take the passed parameter values and uses them to retrieve the required target transaction.
This action type allows users to browse for target Web Services operations and then create an action to invoke the selected content. For information about how Action Framework supports calls to Web Services, see Section 4.6.4, "Supported Functionality for Calling Web Services".
For more information about creating this action type in Presentation Services, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
In order for the Action Framework to provide this action type and before a user can create an Invoke a Web Services action, you must have performed the following tasks:
Confirmed that a target Web service with a URL to the WSDL for that Web service exists.
If you want to allow users to browse for Web Services, you must have added a WSIL document that points to one or more WSDL documents. The WSIL document must be accessible via a URL. For more information, see Section 4.6.3.2, "Example of a WSIL Document".
If you want to browse to Web Services operations or apply security policies, you must have modified the configuration file's registry element so that it references the target WSIL document. For information about this required configuration, see Section 4.3.2.3, "Invoke a Web Service Action Type Registry Example".
Confirmed whether you need to add credentials to the credential store to invoke Web Services. If the target Web service is secured, appropriate configuration needs to be added to pass credentials to the Web service operation when it is invoked. A suitable keystore might also be required. For more information, see Section 4.4.1, "Oracle BI EE Credentials", Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework", and Section 4.5.2, "Creating a Default Keystore".
WSIL defines an XML format for referencing Web service descriptions. These references are contained in a WSIL document and refer to Web service descriptions (for example, WSDL files) and to other aggregations of Web Services (for example, another WSIL document or a UDDI registry). Note the following WSIL example:
<?xml version="1.0" encoding="UTF-8"?> <inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"> <service> <abstract>Web Service: Order Services</abstract> <name>Order Service</name> <description referencedNamespace="http://schemas.xmlsoap.org/ wsdl/"location="http://localhost:9704/ActionSamples/ OrderProcessPort?wsdl"/> </service> </inspection>
Use the following list to troubleshoot actions to Invoke a Web Service.
Confirm that you can invoke the target Web service from a test client such as the HTTP Analyzer in JDeveloper.
If the target Web service has a security policy, check the ActionFrameworkConfig.xml file to make sure that the Action Execution Service (AES) is using the appropriate client policy.
Go to Oracle Enterprise Manager to check the logs and diagnostics for Action Services. To access the log files, go to the Enterprise Manager, access the Business Intelligence navigation tree, and select coreapplications to display information about the Oracle BI instance. Select the Diagnostics tab and select the Log Messages sub tab. In the View/Search Log Files area, click Action Services log.
You can enable verbose logging for Weblogic by adding the following entries to the JAVA_OPTIONS variable in the startWebLogic.cmd/*.sh file. After you have modified the JAVA_OPTIONS variable, you must restart Weblogic.
-Dweblogic.wsee.verbose=* -Dweblogic.log.RedirectStdoutToServerLogEnabled=true - Dweblogic.webservice.client.verbose=true"
Check the ActionFrameworkConfig.xml file for mistakes or omissions.
Thoroughly check any associated policy files and make sure they are in the correct location.
If the target Web service applies a security policy that includes either message protection or encryption, thoroughly check the additional OWSM credentials in the Credential Store.
Figure 4-2, "Invoking a Web Service Process Flow" illustrates the Web Service action type's process flow.
Figure 4-2 Invoking a Web Service Process Flow
This section describes the supported technologies and limitations used by the Action Framework when it invokes Web Services.
Note the following items:
The Action Framework supports HTTP for both WDSL browsing and calling Web Services through Actions.
The Action Framework supports HTTPS for WSDL browsing of Web Services.
The Action Framework supports HTTPS for sending messages over a secure channel between AES and the target Web service. However, Action Framework does not currently support the use of digital certificates for authenticating between AEService and the target Web service.
Note the following items:
A Web Service called from the Action Framework needs to be SOAP-based.
The Action Framework supports synchronous, request/response messages.
The Action Framework does not support WS-Addressing.
The Action Framework supports the following data types in outgoing and incoming SOAP 1.1 and 1.2 messages. Note that support for arrays is currently limited. The action framework allows you to enter a single value into any array (for example, String[]) in an out-going SOAP message.
xsd:any
xsd:base64Binary
xsd:string
xsd:date
xsd:time
xsd:dateTime
xsd:double
xsd:decimal
xsd:int
xsd:short
xsd:long
xsd:byte
xsd:Boolean
xsd:float
The SOAP response document is made available to the user interface and can be formatted using XPATH and html. The document can retrieve multiple occurrences of the same parameter, but you must map each occurrence to a specific XPATH parameter.
Note the following items:
The Action Framework supports WSDL.
The Action Framework supports synchronous, request/response messages.
Note the following items:
The Action Framework supports WSIL.
The Action Framework does not currently support UDDI.
The Action Framework supports WS-Security based on the policies available to the OWSM.
This action type allows users to browse for target Java methods deployed in Enterprise Java Beans (EJBs) and then create an action to invoke the selected method.
For more information about creating this action type in Presentation Services, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
In order for the Action Framework to provide this action type and before a user can create an Invoke a Java Method (EJB) action, you must have performed the following tasks:
Added a target EJB with a URL to the JNDI location for that EJB. Note that the Action Framework expects EJBs to be deployed to the default location of /ejb
.
Modified the configuration file's registry element so that it references the target EJB. For information about this required configuration, see Section 4.3.2.2, "Invoke a Java Method Action Type Registry Example".
Added a credential to the credential store to invoke the EJB method. The appropriate configuration needs to be added to pass credentials to the EJB method when it is invoked. For more information, see Section 4.4.1, "Oracle BI EE Credentials" and Section 4.5, "Adding and Maintaining Credentials for Use With the Action Framework".
The Action Framework finds the Java methods exposed through the remote interface of the EJB. The parameters of exposed methods become the parameters for an action.
When deploying an EJB method, you may import, but not modify, the oracle.bi.action.annotation.OBIActionParameter class found in Actionframework-common.jar. This class, which was deployed with the installation of Oracle Business Intelligence, allows you to annotate parameters for use by the Action Framework when creating actions.
The following example shows code to define a remote interface exposing a method called ArchiveReport. Note that the import statement for oracle.bi.action.annotation.OBIActionParameter and the annotation @ OBIActionParameter. This annotation allows you to specify a parameter name and a prompt value to display when creating an action.
package project1; import java.io.FileNotFoundException; import java.io.IOException; import javax.activation.DataHandler; import javax.ejb.Remote; import oracle.bi.action.annotation.OBIActionParameter; @Remote public interface ArchiveReport { String ArchiveReport( @OBIActionParameter (name = "Filename", prompt = "Enter filename location:") String filename, @OBIActionParameter (name = "Analysis", prompt = "Report to Archive:") DataHandler document) throws FileNotFoundException, IOException; }
You can send documents from the catalog to a Java method in an EJB. The binary data for the document is sent using a specific Java data type. Therefore, if you want to create a Java method that accepts an analysis as a parameter, your Java method should include a specific Java data type (javax.activation.DataHandler) as a parameter. The Action Framework recognizes this data type as capable of receiving a document in one of the supported export formats (for example, PDF or HTML).
Figure 4-3, "Invoke Java Method (EJB) Process Flow" illustrates the Invoke a Java Method (EJB) action type's process flow.
Figure 4-3 Invoke Java Method (EJB) Process Flow
This action type allows users to browse target JavaScript functions and then create an action to invoke the selected function.
For more information about creating this action type in Presentation Services, see "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
Use the following information to help you create JavaScript functions.
The target JavaScript functions that Actions to Invoke a Browser Script call are hosted in the UserScripts.js file are found in the following location:
<middleware home>/user_projects/domains/bifoundation_domain/servers/bi_server1/tmp/_WL_user/analytics_11.1.1.2.0/<installation dependent folder>/war/res/b_mozilla/actions/UserScripts.js
A sample UserScript.js file can be downloaded as part of the samples for Oracle Business Intelligence 11g from the Oracle Web site. The sample files are located at the following URL: http://www.oracle.com/technology/products/bi/enterprise-edition.html
You can edit the UserScripts.js file and add any user-defined JavaScript functions to invoke from a client-side script action.
Custom functions should use the namespace USERSCRIPT so that no function name conflicts occur with the product code, and so that the Action Framework can identify functions when creating an action.
Custom functions in the UserScripts.js file consist of a function to contain the actual code to be called when the action is invoked, and, optionally, an associated "publish" object used by the Action Framework to browse for the function when creating the action and for mapping values to the function parameters.
The example shows a JavaScript function of USERSCRIPT.example_displayParameters that can be called by an action. Target functions receive a single parameter and a named array of values, indexed by the parameter name.
/** This is an example function to display all parameters that are received * @params {Array} aParams an array of values indexed by the parameter name */ USERSCRIPT.example_displayParameters = function(aParams) { var sArgs = ""; for( args in aParams ) { var argName = args; var argValue = aParams[argName]; sArgs += "Parameter name: " + argName + " Value: " + argValue; sArgs += "\n"; } alert( sArgs.length == 0 ? "No Parameters" : sArgs ); };
The USERSCRIPT.parameter object is defined at the beginning of the UserScripts.js file. This object is used by the Action Framework to define parameters in custom JavaScript functions for use when creating an action to Invoke a Browser Script. Each parameter object includes a name, a prompt value holding the text to be displayed against the parameter when creating an action, and a default value.
/** This is the parameter object you can create to supply default parameters on creation of Script action. * See the 'displayParameters' example below for usage. * @param {String} sName is the unique name of parameter. * @param {String} sPrompt is the display text used to prompt for the parameter value. * @param {String} sValue (Optional) is the default value for the parameter. */ USERSCRIPT.parameter = function(sName, sPrompt, sValue) { this.name = sName; this.prompt = sPrompt; this.value = sValue; };
The example shows the definition of a "publish" object that defines parameters for the Action Framework. All functions within the USERSCRIPT namespace that include a "publish" object can be browsed for selection when creating an action. The publish object defines the array of parameters to be passed by an action to the target JavaScript function. Note that functions that do not have an associated "publish" object may still be invoked by an action, but the Action Framework is not able to browse to these private functions, and therefore parameters need to be added to the action definition manually.
USERSCRIPT.example_displayParameters.publish = { // The existence of this 'publish' object causes the 'USERSCRIPT.example_displayParameters' function to be // shown when browing the available user script functions (during creation of a Script action). // If you wish the Script function to have parameters automatically created on selection of the function, // create a 'parameters' object as shown below. // You can have any number of parameters, with each parameter requiring a unique name, prompt and an // optional value. parameters : [ new USERSCRIPT.parameter( 'p1', 'Enter value for Param 1', 'p1 default value' ), new USERSCRIPT.parameter( 'p2', 'Enter value for Param 2', 'p2 default value' ), new USERSCRIPT.parameter( 'p3', 'Enter value for Param 3' ) ] // If no generated parameters are required, either create an empty array // parameters : [] // or don't declare the 'parameters' object at all. };
Figure 4-4, "Invoke a Browser Script Process Flow" illustrates the Invoke a Browser Script action type's process flow.
Figure 4-4 Invoke a Browser Script Process Flow
This action type allows users to specify the filename of a custom script to execute (on Microsoft Windows) when the current agent completes. The custom script type can be either JavaScript or VBScript. For more information about configuring this capability, see "Configuring and Managing Agents" and "Introducing Oracle BI Scheduler" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
When setting up this action type, you can select options for whether results are passed to the script, as well as desired formats. You can also manually add additional parameters. Depending upon the type of content to be passed (from either the conditional request or the delivery content), results may be passed in some of the following formats:
MHTML (MIME HTML used in email)
Plain Text
XML
CSV
Excel
Powerpoint
In order for the user to create an Invoke Server Script action, you must confirm that the custom script file resides on the same server as the Oracle BI Delivers server (the Scheduler).
Figure 4-5, "Invoke a Server Script Process Flow" illustrates the Invoke a Server Script action type's process flow.
Figure 4-5 Invoke a Server Script Process Flow
Agents can execute actions depending on whether a data condition is met. For detailed conceptual information about agents and procedures for creating agents and adding actions to them, see "Delivering Content" and "Working with Actions" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition.
If you add an Invoke Agent action to an agent and the following conditions exist, then the child agent will be invoked once with filter values generated by the results of the parent agent.
The parent agent to which you are adding the Invoke Agent action uses a condition to determine whether the parent agent delivers its content and runs its associated actions.
The Invoke Agent action invokes a child agent that also uses a condition to determine whether the child agent delivers its content and runs its associated actions, and that condition is based on an analysis that filters its data by a column prompt.
For example, suppose you have the following:
A parent agent that uses a condition based on an analysis that uses the Region, District, City, and Sum (Sales) columns
A child agent that uses a condition based on an analysis that uses the Region, District, City, and Sum (Sales) columns and filters on Region and City.
And suppose when the parent agent runs, the following results are generated:
Region | District | City | Sum (Sales) |
---|---|---|---|
Central | A | C1 | 100 |
Western | B | C2 | 200 |
The child agent will run once using the filter values generated by the results of the parent agent, that is, Region = Central and City = C1, or Region = Western and City = C2.
Figure 4-6 illustrates the Invoke Agent action type's process flow.
In Oracle BI EE 10g, you could specify a custom Java program to execute on Windows and UNIX when an iBot completed. When migrating to the current Oracle BI EE release, these actions are upgraded to read-only Java Job actions.
If you are creating new actions to run Java methods, you should use the Invoke a Java Method (EJB) action type. In order to use Java Job actions that have upgraded from 10g, you need to copy the jar file that includes the target java class into the default user Jar file path, as specified for the Oracle BI Javahost. Where the target java class imports Oracle BI EE classes, you should re-compile your target java class referencing the 11g Oracle BI EE classes in the classpath and make sure these classes are available to the target class when it is invoked. For more information, see "Introducing Oracle BI Scheduler" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition
Figure 4-7, "Java Job Process Flow" illustrates the Java Job action type's process flow.