Creating Analytic Type Definitions

This section discusses how to:

  • Define an analytic type.

  • Configure analytic type records.

  • Configure models for optimization.

  • Associate Analytic Types with Analytic Models.

Note: When working with analytic type definitions, you can use the typical drag-and-drop features offered by PeopleSoft Application Designer. For example, you can drag record definitions and drop them into the analytic type record list, which is maintained on the Record tab of the analytic type definition.

In PeopleSoft Application Designer, select File > New > Analytic Type. A new analytic type definition appears, containing tabs for transactions, records, and models. The definition combines these items with an OPI to form the basis of an optimization application.

This is an example of the analytic type definition:

Image: Analytic Type – Transactions tab

This example illustrates the fields and controls on the Analytic Type – Transactions tab.

Analytic Type - Transactions tab

To complete the analytic type definition, you should configure the analytic type properties, then insert and configure the records, the optimization models, and the transactions, in that order.

To access the Analytic Type Properties – Attributes dialog:

  1. From the Analytic Type – Transaction tab, select File > Definition Properties.

  2. Select the Attributes tab.

Image: Analytic Type Properties – Attributes tab

This example illustrates the fields and controls on the Analytic Type Properties – Attributes tab. You can find definitions for the fields and controls later on this page.

Analytic Type Properties - Attributes tab

Field or Control

Definition
PeopleCode Plugin

Select to indicate that the analytic type should use the Optimization PeopleCode plug-in.

Select this check box only if the analytic type is to be used with optimization. If the analytic type is to be used with the analytic calculation engine, do not select this check box.

Psopidplugin is automatically entered in thePlugin Library Name field, which is read-only.

If you use this plug-in, you must also use the Package andClass fields to specify an application class that was developed to adapt the Optimization PeopleCode plug-in to your optimization application.

See Invoking the Optimization PeopleCode Plug-In.
Plugin Library Name

Enter the name of the OPI library.

Enter only the portion of the name that is specific to this library. Ignore operating system-specific prefixes (such as lib) and suffixes (such as .dll). In the exercise example, in Microsoft Windows, the library is libqeopt.dll. You would enter only qeopt here.

If you selected the PeopleCode Plugin check box, this field contains the valuepsopidplugin, and is read-only.
Plugin Library Version

Enter the application release version of the plug-in. The optimization engine uses this to confirm that the correct version of the plug-in library is used at runtime.
Message Set ID

Enter the message set ID in the message catalog containing the messages for the optimization application. The OPI uses this to access messages from the message catalog.
Plugin Application Class – Package

If you selected the PeopleCode Plugin check box, you must specify here the application package containing the application class to use with the Optimization PeopleCode plug-in for your optimization application.
Plugin Application Class – Class

If you selected the PeopleCode Plugin check box, you must specify here the application class containing the optimization PeopleCode program to use with the Optimization PeopleCode plug-in for your optimization application.

This class must be a subclass of the PT_OPT_BASE:OptBase application class.
Analytic Instance Application Class – Package

If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the application package name to associate with this analytic type, that contains the functionality to be used with the analytic type when it is created, deleted, or copied.

See Creating, Deleting, and Copying Analytic Instances.
Analytic Instance Application Class – Class

If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the name of the class in the application package that contains the Create, Copy, and Delete classes.

To configure analytic type records, in the analytic type definition, select the Record tab, and then select Insert > Record.

Image: Analytic Type Record Property dialog box

This example illustrates the fields and controls on the Analytic Type Record Property dialog box. You can find definitions for the fields and controls later on this page.

Analytic Type Record Property dialog box

Note: You can access the properties of an existing analytic type record by right-clicking the record and selecting the Analytic Type Record Properties option.

Field or Control

Definition
Record Name

Select the record to use in the analytic type definition.

Note: If you select a derived/work record, remember that its scope in optimization PeopleCode is different from that in other PeopleCode. When you use the CreateOptEngine or CreateAnalyticInstance function, each derived/work record is instantiated at level zero of the analytic instance rowset. The record persists, and you can continuously modify its data across multiple transactions, until you shut down the optimization engine using the ShutDown method.
Synchronization Order

Indicates the order in which the optimization engine reads the optimization application records. If a record has dependencies on another record, the dependent record should be read later. For example, the QE_RSM_EXERTGT record (synchronization order number is 4) depends on data in the QE_RO_MACH_CALS record (synchronization order number is 1). This order is determined by the application logic.
Read Once

Select to have the record read only once during the initial load of the analytic instance into the optimization engine.

You cannot select the Writeable check box if the Read Once check box is selected.

The optimization engine reads these records only once during the initial data load. The assumption is that the data in these records does not change (or the user doesn't care if it changes) from the initial load of the optimization engine until shutdown.

For the exercise machine problem, you might create a record that contains the name of an exercise machine and the number of calories one can burn on it. This information needs to be read only once by the optimization engine. Furthermore, the information will not change, so a VERSION field is not required.
Readable

Select to have the record checked for updates by the optimization engine with every optimization transaction.

Readable records, besides being loaded during the initial load, are checked for updates by the optimization engine at the beginning of every optimization transaction. For every readable optimization application record, you must also create a corresponding optimization delete record and associate the readable record with the delete record. This process is explained later in this topic.

Note: Oracle recommends that you keep the analytic type records in sync with the optimization delete records.

For the exercise machine example, an appropriate readable record contains the name of a person who exercises, the start time and duration of the exercise, and the number of calories that the person wants to burn. This record is readable and scenario-managed. It has a VERSION field and a PROBINST field that contain the name of the person. Because this is pure source data, this data is not writable.
Writable

Select to enable the optimization engine to modify rows for this record. A record can be both readable and writable. Records more likely to be readable and writable than just writable.

A writable record contains result data from the optimization engine. For the exercise machine example, the system calculates this data every time you request an exercise summary. For this reason, it is purely writable.
Scenario Managed

Select to indicate that the record will contain data pertaining to multiple analytic instances.

Note: Scenario-managed records must have a PROBINST key field.

See Scenario Management.
Callback

Select to enable the optimization engine to update its working data whenever this record changes.

Your analytic type definition might include a record that you expect to change during the course of the optimization. If you want those changes to be taken into account by the optimization, you can define it as a callback record, so you can use provided PeopleCode callback methods to dynamically propagate those changes to the derived data structures of the optimization. A callback record must be readable and writable.

Warning! If you select this check box for a record, you must ensure that you override all of the abstract callback placeholder methods that are defined in the extended PT_OPT_BASE:OptBase application class, even if it contains only a Return statement. Otherwise your Optimization PeopleCode plug-in will fail.

See OptBase Application Class.
Record Fields

In the Record Fields list, select the fields in this record that need to be read into the optimization engine.

These are the fields that the OPI can access. Key fields and the VERSION field (if it exists) are always selected automatically. To conserve memory used by the optimization engine, select only the necessary fields.

When the analytic type definition is saved, if there are fields that have not been selected but are being mapped to a cube or dimension, an error message is displayed, and you must go back and correct the error before you can save the analytic type definition. If there is a record in the analytic type definition that has none of its fields mapped to any cube or dimension, a warning message is displayed when you try to save the analytic type definition. You can continue to save the analytic type definition after you have acknowledged the warning message; you do not have to change anything in the definition.

You need to specify and configure analytic type models for optimization only if both of the following conditions are true:

  • You selected the PeopleCode Plugin check box in the analytic type properties, indicating that your analytic type definition should use the Optimization PeopleCode plug-in.

  • Your application documentation indicates that an optimization model is necessary for the optimization application you are developing.

In the analytic type definition, select the Models tab, and then select Insert, Optimization Model.

The Analytic Type Optimization Model Property dialog box appears.

Image: Analytic Type Optimization Model Property dialog box

This example illustrates the fields and controls on the Analytic Type Optimization Model Property dialog box. You can find definitions for the fields and controls later on this page.

Analytic Type Optimization Model Property dialog box

Note: Your application documentation discusses which models to specify, and what configuration settings to make for each model. You can access the properties of an existing analytic type model by right-clicking the model and selecting the Analytic Type Model Properties option.

Field or Control

Definition
Model Name

Select the optimization model required to implement an optimization application with this analytic type.

Solver Settings

A solver setting is a collection of solver parameters with default values that define a particular solver behavior suitable for the optimization model. Specify one or more solver settings to make available to your optimization application, including:

  • Solver Setting.

    Enter the name of the solver setting.

  • Solver Type.

    Select the solver type: LP (linear programming),MIP (mixed integer programming), or LPMIP (both).

  • Active.

    Select the active solver setting. Only one solver setting can be active at a time.

Configuring Solver Parameters

For each solver setting that you specify, you can configure one or more solver parameters.

In the Analytic Type Optimization Model Properties dialog box, double-click a solver setting to access the Analytic Type Optimization Solver Property dialog box. This dialog box has a grid with two columns: Parameter ID andParameter Value:

Image: Analytic Type Optimization Solver Property dialog box

This example illustrates the fields and controls on the Analytic Type Optimization Solver Property dialog box.

Analytic Type Optimization Solver Property dialog box

Each solver type has a different set of available parameters, and each parameter has a default value. When you select a solver parameter from the Parameter ID drop-down list box, its default value appears in theParameter Value cell, and a new row appears for adding another parameter. Your application documentation discusses which parameters to specify for each solver setting, and what value to specify for each parameter.

Creating Mathematical Formulation Files

In addition to the analytic server log files, you can also create a mathematical formulation file for debugging. This file is written in either MPS or LP format and can be requested for technical debugging purposes. The file type is generally LP; however, if the system cannot create an LP file it creates an MPS file. The filename is either AnalyticType_AnalyticInst.LP or AnalyticType_AnalyticInst.MPS, with AnalyticType being the name of the analytic type and AnalyticInst being the name of the analytic instance ID. This file is generally written to the same directory as the application server log. Also, this directory can be configured in the application server configuration file.

You indicate whether to write this file by specifying a solver parameter.

In the Analytic Type Optimization Model Properties dialog box, double-click a solver setting to access the Analytic Type Optimization Solver Property dialog box. This dialog box has a grid with two columns: Parameter ID andParameter Value.

Select the WriteMPS option forParameter ID. In theParameter Value column, enter 1 to write the file or 0 to not write the file.

For PeopleSoft Analytic Calculation Engine, you only need to associate an analytic type with an analytic mode.

In the analytic type definition, select the Models tab, and then select Insert, Analytic Model.

Image: Analytic Type Analytic Model Property dialog box

This screenshot shows the fields and controls on the Analytic Type Analytic Model Property dialog box.

Analytic Type Analytic Model Property dialog box

Select the name of the analytic model that you want to associate with the analytic type. If you specify to add all the records and fields that are used in the model, they are automatically added to the records on the Records tab.

In the analytic type definition, select the Transactions tab, and then select Insert > Transaction.

Image: Analytic Type Transaction Property dialog box

This example illustrates the fields and controls on the Analytic Type Transaction Property dialog box. You can find definitions for the fields and controls later on this page.

Analytic Type Transaction Property dialog box

Note: You can access the properties of an existing analytic type transaction by right-clicking the transaction and selecting the Analytic Type Transaction Properties. option.

Field or Control

Definition
Transaction Name

Enter the case-sensitive name of the transaction.

If the PeopleCode Plugin check box is selected in the analytic type properties, this value must match the name of a method defined in the application class that you specified for this analytic type.

If the PeopleCode Plugin check box is not selected in the analytic type properties, this value must match the name of a service defined in the OPI that you selected in the analytic type properties.

The transaction name that you specify must be distinct within an analytic type.

For the exercise machine example, three transactions are needed. The QEOPT.DLL OPI implements these transactions:

  • SOLVE solves the exercise machine problem.

  • GET_SUMMARY produces a summary of exercises for a person.

  • IS_MACHINE_AVAILABLE returns whether an exercise machine is available for a specified time.

The transaction name can contain up to 30 characters.

See OptBase Application Class.
Lock Flag

Select this option to prevent changes to the optimization application tables while this transaction runs. Typically, this flag should be set for extremely fast but critical transactions where data integrity is crucial. In the exercise planning example, optimization transactions do not need the lock flag.

Important! The lock flag can hamper performance, so use it with caution.

Parameter Attributes

Each transaction can have any number of parameters.

If the application class method corresponding to this transaction has parameters, you must define a row in this grid with equivalent attributes for each of the parameters.

Field or Control

Definition
Name

Enter the name of the parameter. The name must match the transaction parameter name defined in the OPI, or the equivalent method parameter defined in the application class that you specified for this analytic type.

The transaction parameter name can contain up to 20 characters, and it must be distinct within an analytic type.
Type

Select the parameter type (String, Integer, Double, Date, DateTime, Time, or arrays of these types, or Record Array). The type must match the transaction parameter type defined in the OPI, or the equivalent method parameter type defined in the application class that you specified for this analytic type.

Note: Do not pass an array of type Integer as a transaction parameter. Use an array of type Number instead.
Input/Output

Select Input, Output, or Both.
Attributes

Select Required, Optional, or Default (the parameter has a default value). This is not applicable to output parameters.

Note: If an input parameter is required, it must be supplied when you use either the RunSynch or RunAsynch PeopleCode methods.
Value

If the Attributes field is set to Default, enter a default value for this parameter. If the type is Record Array, enter the name of the record. Otherwise, leave this blank.