Using Supplemental Data

This chapter provides an overview of supplemental data, and discusses how to establish supplemental data.

Understanding Supplemental Data

Because every organization has different data requirements for work orders based upon unique business processes and regulatory issues, Maintenance Management includes the Supplemental Data component to provide a way to define additional work-order related data. This component enables system administrators to extend the information that is stored for an object without requiring modifications to the object's base table (record) and without requiring additional PeopleCode or PeopleTools customizations. The supplemental data framework uses the PeopleSoft Enterprise Common Components Active Analytic Framework (AAF) to define the business rules for the additional data.

See PeopleSoft Active Analytics Framework.

Supplemental data is valuable when you want to capture information about a subset of object instances with fields that are relevant only to these particular object instances. Objects include records, pages and components, which you must configure specifically to accept supplemental data. For example, PeopleSoft defines and enables the Service Request, Work Order Header, and Work Order Task to include supplemental data for Maintenance Management. Supplemental data may be a field that is embedded in the page or displays on a secondary page. PeopleSoft defines and registers both the supplemental data store records associated with a base record and the components to be used for supplemental data. Be aware that adding any additional objects is regarded as a customization and requires familiarity with PeopleTools.

When you set up supplemental data, you define records and fields and map them to a data storage record. These definitions are not stored in the PeopleTools metadata tables but in the supplemental data's own metadata tables. You define supplemental data page elements to display on the page in two columns. You must also group supplemental data fields within a display group for display purposes. You assign display groups to pages that are enabled for supplemental data. Once you have made this designation, you can define the conditions under which the application should use the supplemental data. You may perform a search on one display group. The pages within the Supplemental Data component enable you to accomplish these tasks.

Considerations and Limitations

The decision to add supplemental data to your application should be based on how applicable the data objects are to instances of the object. If the data objects apply to a significant number of instances of the object, then it may be better to add a field to the table using Application Designer instead of using attributes to capture the data. If the data elements apply to a much smaller percentage of the objects, then attributes may be the solution. While supplemental data provides a large amount of flexibility in terms of adding data elements without changing the underlying data model, you should consider the following limitations when you are evaluating whether to implement supplemental data:

• Supplemental data does not fall under the normal upgrade capabilities that are provided with PeopleTools.

  Because supplemental data records are not a type of PeopleTools object, you cannot use the standard upgrade facilities that are provided by PeopleTools, such as the Upgrade Copy or Upgrade Compare process, to upgrade supplemental data from one database to another. The mechanism for migrating supplemental data is to extract the data from the source database and move the data to the target database, which can be accomplished, for example, by using Data Mover or a similar tool. PeopleSoft does not deliver any utilities, such as data mover scripts, for migrating supplemental data.

• Because supplemental data records are stored in separate tables (distinct from the base table), it can be difficult to incorporate supplemental information into reports.

• Supplemental data can only be displayed in a two-column format.

• Performance issues can occur if you have too many supplemental data records in the system.

  Use supplemental data only if the data elements are truly dynamic in nature or if they apply to certain instances of an object. Never use supplemental data simply because it is easier to create than standard PeopleTools fields.

Terms

We use the following terms when discussing supplemental data:

Supplemental Data Record Details

The Supplemental Data components, Register Record and Register Component are system-defined by PeopleSoft. The purpose of these options is to associate the supplemental data storage and optional search records with a Maintenance Management base record and a Maintenance Management component.

For each base Maintenance Management record, there is an associated supplemental data storage record:

The following components and pages are enabled for supplemental data. There are AAF contexts and terms defined for the components. You can define an AAF condition to show different display groups based on business rules.

The following delivered system data enables users to search work order tasks based on a work order header’s supplemental data. There can be supplemental display groups with no AAF condition on a search page. Since the advanced search page is implemented as a secondary page, which users can invoke from the main page, you need to have the same assignment for these two pages:

The system stores the search criteria in the Supplemental Data Search Record using the same mapping defined for the Supplemental Record. There are no AAF contexts and terms defined for the components used for the search:

Example

Maintenance Management serves as an excellent example of how supplemental data is set up and used in an application. For example, an organization may need to create work orders to assign and schedule resources to repair vehicles and uses PeopleSoft Maintenance Management. Part of this repair process includes the requirement to track any hazardous waste that was created while performing this work. This organization wants a Hazardous Waste group box to display, which contains the fields labeled as Date Generated (DATE), Description (DESCR), Notes (NOTES), Quantity (QTY), Unit of Measure (UOM), and Waste Code (WASTE_CD) when you create or update a work order task for this type of work.

Based on the registered records and components, you access the Define Record component and define each supplemental data record such as PS_HAZARD_WASTE, associate it with a supplemental data stored record, such as WM_WO_TSK_SD, and add all the field names and their associated details that you want to include in this record. Based on the hazardous waste example, you would add the fields: DATE, DESCR, NOTES, QTY, UOM, and WASTE_CD. You create a field name (WASTE_CD), a field label (Waste Code), select how the field will be used (code), the field length displays based on the field's use type (4 displays for code), and select a supplemental database field (SD_TEXT_4_1) in which to store each field's data. Since the use type for the field in this example is code, an additional group box displays where you can define all the field values and the order in which you want each value to display on the drop-down list For example, the WASTE_CD values might be D001, D002, D003, D004, D005, D006. Initially the status in the Record page is In Design. You must change the status in the Record page to Activated before saving the data and exiting this option.

Note. If you access the Define Record component for an existing record, you must change the status field to In Design before making any changes. After you add the new field, you must change the status field back to Activated before saving and exiting the component.

Once you have defined and activated all of your fields, you must access the Define Display Group component and create a display group, such as PS_HAZARD_WASTE, and associate it with a base record, such as WM_WO_TSK. You then must identify the fields and their associated records that you want to appear in either the left or the right column of the page. If a label is not associated with the field name, you may enter a label here. For example, for the PS_HAZARD_WASTE record, you might want to put the fields DATE , DESCR, and NOTES fields in the right column, and the QTY, UOM, and WASTE_CD fields in the left column.

Once you create a display group, you associate one or more of the display groups that you created to a component, such as the WM_WO component. This is also where you identify whether the condition is editable or read-only. If the condition is editable, you may access the condition term page where you may edit and add conditions for this display group. When you access the Work Order component in Maintenance Management and access the WM_WO_DETAIL page, the supplemental data group box containing the supplemental data fields appear on the page.

Establishing Supplemental Data

To establish supplemental data, use the following components:

• Register Record (FS_SD_REG_REC) component.

• Register Component (FS_SD_REG_COMP) component.

• Define Record (FS_SD_RECDEFN) component.

• Define Display Group (FS_SD_GRPDEFN) component.

• Assign Display Group (FS_SD_PAGE_GRP) component.

This section discusses how to:

• Define a supplemental data record.

• Define and map supplemental data record fields to data store records.

• Specify details for supplemental data record files.

• Define a supplemental data display group.

• Assign a supplemental data display group.

• Define conditions for display groups.

Pages Used to Set Up Supplemental Data

Defining a Supplemental Data Record

Access the Define Record - Record page.

Record	Enter a name for a supplemental data record. For example a possible supplemental data record name used for Maintenance Management may be PS_WASTE.
Base Record	Select a base record on the Define Record page to associate with this supplemental data record. For example, a Maintenance Management base record is WM_WO_TSK.
Status	Select a status of In Design during the time that you are defining this record. Change the status to Activated to indicate that you completed mapping the supplemental data fields. Note. If you update a record, before you add a field or make changes to a record, you must change this status back to In Design. When you have completed the modification, you must change the status back to Activated before saving and exiting the component.
Data Store Record	Select one of the data store records that you previously registered that you want to use to store this supplemental data record. For example, the data store record for this supplemental data record in Maintenance Management is WM_WO_TSK_SD.

Defining and Mapping Supplemental Data Record Fields to Data Store Records

Access the Define Record - Fields Summary page.

Field Name, Use Type, Length, Mapped to and Field Status

Click the Field Name link to access the Fields Detail page. The remaining fields on this page are all defined in the Fields Detail page. Once you finish adding all the fields and their descriptions on the Field Details page, and change the Status value in the Record page to Activated, each new field name and its characteristics appear on this summary page. You may then click on each field name and access the field name's detail information in the Define Record - Fields Detail page.

Specifying Details for Supplemental Data Record Fields

Access the Define Record - Fields Detail page. You access this page when you click the Field Name on the Define Record - Fields Summary page.

Field Name	Enter a name for the supplemental data field and a description of the field. For example, in Maintenance Management this field might be called WASTE_CD.
Field Label	Enter the a label to display on the page for this field. For example, in Maintenance Management this field might be Waste Code.
Use Type	Select one of the following based on how the field will be used: Code Number Signed Number Text Time Yes/No
Field Length	Select a length based on the selected Use Type: If the use type is a number or signed number consisting of an integer or decimal position, the field lengths may only be: 9.0, 7.2, and 15.4. If the use type is text, the field length may be 4, 20, 50, or 100. If you select any of the remaining use types, each type's field length is dictated by the specific length of the selected use type.
Mapped To	Select the data store field to which you want to map this field.

Note. Once you change the status to Activated on the Record page, the information listed above, with the exception of the description and field label, becomes read-only and cannot be modified.

Codes

This group box displays if you selected code as a Use Type and identifies a list of code values for a drop-down list.

Defining a Supplemental Data Display Group

Access the Define Display Group page.

Display Group	Select a base record to associate this new display group with and enter a name for this display group in the Define Display Group Add page.
Label	Enter a label for the display group data group box.
Occurs	Enter the number of rows of data to display in the group box.

Left and Right Columns

The supplemental fields that you want to appear on a page are defined in left and right columns.

Assigning a Supplemental Data Display Group

Access the Assign Display Group page.

Component Name and Market

Select the component that is enabled for supplemental data and with which you want to associate a supplemental data display group in the Assign Display Group Search page. The Market for which this component was defined displays as read-only along with the Component Name.

Enabled Pages and Display Groups

This group box displays the name of the pages within the component that are enabled for supplemental data, their associated base record, and any associated display groups. You may also add the display groups that you want to appear in this component and page.

Note. If the supplemental data page is registered as a search page, then you may add only one display group to the page; you must select 1 as the value in the Occurs field for the selected display group; you must define all fields for this display group for the same record definition; and you must map this record to a data store record defined with a Search Supplemental Search record. With Maintenance Management, you can only search based on supplemental data for the Work Order Header.

Defining Conditions for Display Groups

Access the Assign Display Group - Conditions page.

Supplemental data depends on the Active Analytics Framework (AAF) to define and resolve the conditions for a supplemental data display group. AAF is a PeopleSoft Enterprise Component that includes the following components:

• Data Library Framework.

• Rule Evaluation Engine.

• Rule Builder Framework.

• Action Framework.

Maintenance Management utilizes all of these AAF components with the exception of the Action Framework.

See PeopleSoft Active Analytics Framework.

You define a condition using a combination of a term, an operator, and a value or term. A term is a non-technical name that refers to the information (data) that can be retrieved or computed and is the object evaluated within a condition. This page enables you to build conditions by viewing and selecting the terms, operators, and value/term that define the condition.

To add a condition:

1. Select a term.

2. Select an operator.

3. Enter or select values or terms to define the right side of the condition equation, if required by the selected operator.

Note. To add conditions for values derived from control tables that are keyed by setID (for example, Work Type, Service Group ID), you must use one of the “in list” operators (is in list, or is not in list).

There are two modes that you can use to specify conditions:

• Basic.

  This is the default mode. When you select this option, the Select Subject Area group box appears, with a folder hierarchy of subjects. Navigate through the subjects and select one to view the terms available in an adjacent group box. Click a term to select it and insert it into the condition.

  If the criteria you define includes more than one condition row, the system uses AND logic for the conditions, therefore all of the conditions must be met for the criteria to evaluate as true.

• Advanced.

  This mode enables you to group condition rows using parenthesis, specify the logical operator for each condition row (AND, OR), and specify terms as values in the right-hand side of the condition equation.