Setting Up the Data Library

This chapter gives an overview of the data library and discusses how to:

• Use the data library components.

• Create implementations.

• Create terms.

• Manage terms.

• Test term implementations.

Understanding the Data Library

The data library is a repository for information within the PeopleSoft Active Analytics Framework. Each element in the data library is exposed by way of a term, which is a pointer to a unit of data within the PeopleSoft system. This data may reside in a relational database, or it may be derived at runtime.

See Also

Understanding PeopleSoft Active Analytics Framework

Using Data Library Components

This section lists the components used to set up the data library.

Pages Used to Set Up the Data Library

Creating Implementations

Use the Define Implementations component (EOCF_IMPL_DEFN) to create and define implementations.

An implementation refers to the mechanism through which the data is retrieved, derived, or computed. The implementation knows either where the data physically resides or it knows the algorithm for deriving the value. All terms must be associated with an implementation unless the data to which the term refers is present in the component buffer.

An implementation can be associated with more than one term. Conversely, a term may require multiple implementations if it needs to be resolved from multiple contexts. Typically, application developers or IT personnel develop implementations.

Note. Terms that are resolved by accessing data available in the current operating component's buffer do not need implementations to be developed. PeopleSoft Active Analytics Framework provides mechanisms to access data that is available in the component buffer.

Oracle recommends that when multiple related terms will be accessed during a single business event, you create a single implementation to return a rowset containing the data for several terms; then, specify which data element or field position in the rowset or record is to be used for the term.

You develop Implementations using:

• Application class.

  Use application class implementations when retrieval or derivation of data involves writing procedural code, or as a resolution method when data must be retrieved from an external source such as another PeopleSoft database or legacy systems. The application class can return data to the data library in a variety of forms: rowset, record, date, datetime, string, number, date array, datetime array, string array, number array, and array of any. Use PeopleSoft Application Designer to develop the application classes.

  Note. Oracle does not recommend: 1) Using an application class to retrieve data from a component buffer; 2) Using an application class to retrieve the values for the binds directly by accessing the component buffer without registering them as implementation binds. Application classes must use Application Programming Interfaces (APIs) to retrieve the values for the implementation binds (input parameters).

• PS Query.

  Use Query Manager in PeopleSoft Application Designer to develop PS Query-based implementations. PS Query implementations are not appropriate for applications that get data from external databases or systems. The data library invokes the appropriate queries based on the information provided when you register the implementation. The data returned is available to the data library in the form of a rowset.

• SQL object.

  Use this implementation when the SQL used needs to be platform-independent and the data need not undergo complex transformations. SQL object implementations are not appropriate for applications that get data from external databases or systems. The data library invokes the appropriate SQL object based on the information provided when you register the implementation. The data returned is available to the data library in the form of a record or an array of any objects. Use PeopleSoft Application Designer to create a SQL object.

• Record.Field.

  Create a Record.Field-based implementation when the data can be retrieved directly from a table without going through complex transformations. The data returned is available to the data library in the form of string, date, datetime, number, string array, date array, datetime array, and number arrays.

Registering an Implementation

With the exception of component buffer implementations, all implementations must be registered in the PeopleSoft Active Analytics Framework. Before you register an implementation, you must define the PeopleSoft Application Designer objects if using application class, PS Query, or SQL Object implementation methods.

Specify the following items in the registration component:

• Functional name.

• Resolution method used for that implementation.

• Values for the parameters needed for invoking the implementation. The list of parameters varies depending upon the resolution method.

• List of binds that are expected by this implementation.

Note. The binds specified for an application class implementation are referenced in the application class object for retrieving the values. Therefore, changing these implementation bind names can have an adverse effect on the term resolution.

For IT users, the list of implementation binds specified are used for two purposes:

• To allow implementations to access these bind values.

  For any implementation, bind values are passed by position regardless of the resolution method used. Application class-based implementations alone have the additional capability to access the bind values by name.

• To allow the data library engine to use these binds to uniquely tag the data in application cache.

  If IT users take a shortcut by retrieving the necessary data by directly accessing the context (by not registering the data as implementation binds), the data library engine may, as a result, tag the data with incomplete key information. This could cause the same cached data to be incorrectly reused for resolving terms for which it is not valid.

Creating Terms

A term is a user-friendly name that refers to the data library content. It's essentially a piece of information that could exist in the PeopleSoft system or an external system, or it could be derived. For example, the data could be available in the component buffer; retrieved using a PS Query or an SQL object; or computed using an application class.

Terms are the building blocks in policies. Functional users can build conditions for a policy using terms present in the data library. Terms must be registered in the PeopleSoft Active Analytics Framework before they can be used.

Registering a term is a multistep process that includes:

1. Developing an implementation.

2. Registering the implementation.

3. Defining the term.

4. Associating the term with one or more subject areas.

5. Testing and activating the term.

Defining Term Properties

Defining a term involves specifying:

• Term name, code, and type (constant or variable).

• Data type.

  The data library supports primitive data types of string, number, datetime, date, time; and PeopleSoft-specific data types of record and rowset.

• Number of rows to be returned and whether they are scalar or vector (returning an array).

  Terms that are record or rowset data types have number of rows set to One.

  Note. Terms returning a vector (where value of number of rows is many) do not appear in the term list while you are building a condition for a policy.

• User binds.

  These are values that would be supplied either during the construction of a condition or at the time of associating the term with the application. Not all terms will have the binds; however, user binds may make a term more reusable.

• Optionally, details about how the data needs to be captured for user binds: whether a prompt or drop-down list box needs to be shown and how to derive the values.

• Which implementation needs to be used for resolving the term.

• Whether the term can potentially be resolved from any context, or only from specific contexts.

• How the data library needs to extract the data from the content returned by the implementation.

• Prompt details for the term.

  Specifying prompt details for a term is needed only when the term will be used to build a condition. The prompt details convey how the data needs to be captured on the right-hand side for a term participating in a condition.

• Configuration details for prompts.

  The details that you provide are used during the construction of a condition. When a term is selected as an element in a condition, the right-hand side widget will be constructed based on the configuration details specified for the prompts. You can configure the following prompt types:

  • Translate

    Specify a translate field name in which its values appear to the end user on the right-hand side of a condition.

  • Dropdown

    Specify a record name, data field name, and description field name. The record and data field names supply the valid data values to display in the drop-down list box; the description field provides a user-friendly description of the data value.

  • Prompt

    Specify a record name, data field name, and description field name. The record and data field names supply the valid data values to display in the prompt; the description field provide a user-friendly description of the data value.

  • Custom

    Specify a custom application class, a data field name, and a description field name. Valid values are retrieved by execution of the specified application class method and presented as a prompt.

• Scope of each term implementation.

  • When caching is activated for a term, data that is cached is uniquely identified by the implementation ID and all of the implementation bind values for that implementation.

  • When scope is specified as the trigger point, after the first invocation of a term, subsequent references to the same term in one or more policies associated with the same trigger point force the data library engine to retrieve the data from the cache, provided that all the values for the implementation binds match those of the ones belonging to the data present in the cache.

  • When scope is defined as a component, the longevity of the data is for a specific instance of the transaction.

  • When scope is defined as global, the cached data is available for the entire user session.

  • When scope is defined as Do Not Cache, data is retrieved by invocation of the implementation every time.

• Association of a term with subject areas.

  Subject areas act as file cabinets. You must assign a term to at least one subject area, but you can associate it with more than one.

Note. PeopleSoft Active Analytics Framework does not format the data. The term user or term implementer is responsible for formatting it according to his or her needs. For example, the term Current Date is always resolved using the standard YYYYMMDD format.

Using Generic Implementations

A generic implementation can resolve terms within the requesting context. You define generic implementations for terms when they can be used in various contexts and when any new contexts may want to use that term.

Examples of generic implementations are:

• Customer-specific measures such as customer value, the number of cases reported in a period of time, or the number of telephone interactions with the customer.

• Customer profile information, such as first and last name, email address, and customers within a segment.

Using Contextual Implementations

If the input data needed for invoking an implementation is too specific and cannot be supplied outside of the component, then the implementation must be associated with the component's context. For example, terms such as case status, order creation date, and case description cannot be resolved from components other than those in which they are present.

Terms that have different implementations depending upon their contexts will have an implementation associated with a specific context. For example, the term Revenue for a customer / segment / segment group is computed based on the context from which it originates. The implementation specific to the customer context calculates the revenue value from that customer. The implementation specific to a segment context calculates the revenue value generated from all the customers belonging to that segment, and so on for each segment group.

Managing Terms

Before defining a term:

• Create context definitions if you're using a contextual implementation.

• Register any implementations if the term is not accessing the component buffer.

• Create prompt records in PeopleSoft Application Designer if prompt options need to be specified.

Access the Manage Terms page (Active Analytics Framework, Data Library, Manage Terms).

Use the Manage Terms (EOCF_TERM_DEFN) page to define and manage terms.

Term Name	The unique identifier of the term. This is the label that will be displayed to the functional users. Though allowed, Oracle recommends that special characters not be used in term names.
Term Type	Select to specify whether a term is a variable or constant. Variable terms must have at least one implementation.
Term Code	Uniquely identifies a term when you access a term programmatically. This is user-defined.
Number of Rows	The number of rows to be returned, one or many (scalar or vector). If this field is Many, the term cannot participate in policy conditions. Note. Applications directly integrating with the data library are responsible for converting the resolved output value of a term (which will be of data type any) to the appropriate data type.
Status	Valid values are Active, Inactive, and In-Design. Only active terms are used in policy conditions and other applications.
Data Type	Returns the data type of the term. Possible values are string, number, date, datetime, time, record, and rowset.
Run-Time Display	Specify user binds for this term, which will be needed when the resolved value of the term depends on user-defined binds.
Prompt Users for Bind Values	Specify the bind name; (optional) specify prompt options.
Generic Implementation	Specify a generic implementation. Generic implementations are resolved by deriving the bind values from the runtime context. Terms having generic implementations can be resolved by multiple contexts. You specify a generic implementation by selecting an existing implementation from the prompt or creating a new one using the Create button. Click the View applicable contexts link to view the list of contexts in which this term would be resolved.
Contextual Implementation	Select an implementation that is specific to a context. Contextual implementations are resolved by deriving the bind values from this specific context.
Input Mapping	Maps the implementation binds to context variables or to constant values. If the term has user binds, one or more implementation binds must be mapped to the user binds. For generic implementations, this mapping is critical for this term to be resolved by multiple contexts.
Output Mapping	Specify the extraction parameters for a term implementation such that a subset of the value returned by the implementation is returned as the resolved value of the term.

Note. Use caution when making changes to the term definition after the term has been associated with one or more policies. Changes to term attributes such as data type, number of rows, implementation category, and implementation details; or changing a non-configurable term to a configurable term and vice versa, could have significant impact on the policies that reference this term. These changes could possibly result in invalidating these policies. Before making any of these changes, view the policies using a term by clicking the link View Policies Using This Term.

Testing Term Implementations

Access the Test Term Implementation page (Enterprise Components, Active Analytics Framework, Data Library, Manage Terms, Test Term Implementation).

Use the Test Term Implementation (EOCF_TEST_TERM) page to test the implementations of a term.

Specify Implementation	Specify whether you want to test the generic or contextual implementation defined for the term. If you select Contextual, you must specify a context name from the drop-down list box to display a list of bind values that are required by this implementation in a grid. If you select Generic, the context from which the term is resolved must be specified. Select Flush Cache if you do not want the system to fetch the value for this implementation from the memory cache.
List values	Enter sample values for the parameters expected by the implementation and click Run Test.
Test Results	Displays the resolved value of a term implementation being tested and the elapsed time to retrieve the value.

Note. Context-variable implementations of a term cannot be tested. Also, terms that have application class implementations accessing data from a component buffer or directly from the context cannot be tested in the Term Tester page. Testing these terms will result in an error message.