Understanding Supplemental Data

Because every organization has different data requirements for work orders based upon unique business processes and regulatory issues, PeopleSoft 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 Common Components Active Analytic Framework (AAF) to define the business rules for the additional data.

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 PeopleSoft 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

The following terms are used when discussing supplemental data:

Term	Definition
Supplemental Data Field	Defined in the Supplemental Data Record, mapped to fields of the data store record. Also referred to as "Field" in the context of supplemental data setup.
Display Group	Grouping of supplemental data fields, for display purpose.
Supplemental Data Page	The page where supplemental data will be displayed or entered in runtime. Also referred to as Page in the context of supplemental data setup.
Supplemental Data Record	Logical data model for supplemental data. Also referred to as Record in the context of supplemental data setup.
Supplemental Data Store	The physical table where supplemental data is stored. Also referred to as Data Store or Data Store Record.
Search Record	Record that saves search criteria for the base record.
Supplemental Search Record	Record that saves search criteria for the base record. The criteria are based on the supplemental data defined for the base record.

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 PeopleSoft Maintenance Management base record and a PeopleSoft Maintenance Management component.

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

Base Record	Supplemental Data Storage Record
WM_WO_HDR	WM_WO_HDR_SD
WM_WO_TSK	WM_WO_TSK_SD
WM_WR_HDR	WM_WR_HDR_SD

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.

Component	Page	Base Record
WM_ADD_WR_SS	WM_WORK_REQUEST_SS	WM_WR_HDR
WM_ADD_WR_WIZARD	WM_WR_SUMMARY_WIZ	WM_WR_HDR
WM_ADD_WR_WIZARD	WM_WR_SUPLDATA_WIZ	WM_WR_HDR
WM_WO	WM_TSK_SD_SEC	WM_WO_TSK
WM_WO	WM_WO_DETAIL	WM_WO_HDR
WM_WO	WM_WOHDR_SD_SEC	WM_WO_HDR
WM_WO_WR	WM_WOHDR_SD_SEC	WM_WO_HDR
WM_WOE_SD	WM_WOE_SD	WM_WO_TSK
WM_WORK_REQUEST	WM_WORK_REQUEST	WM_WR_HDR

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:

Base Record	Storage Record	Base Search Record	Supplemental Data Search Record
WM_WO_HDR	WM_WO_HDR_SD	WM_TSK_SRCH	WM_TSK_SRCH_SD

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:

Component	Page	Base Record
WM_WOE_TWP	WM_TSK_SRCH_SEC	WM_WO_HDR
WM_WOE_TWP	WM_WOE_TWP	WM_WO_HDR
WM_WOE_WB1	WM_TSK_SRCH_SEC	WM_WO_HDR
WM_WOE_WB1	WM_WOE_WB	WM_WO_HDR
WM_WOTSK_WORKBENCH	WM_TSK_SRCH_SEC	WM_WO_HDR
WM_WOTSK_WORKBENCH	WM_WOTSK_WORKBENCH	WM_WO_HDR

Example

PeopleSoft 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 PeopleSoft Maintenance Management and access the WM_WO_DETAIL page, the supplemental data group box containing the supplemental data fields appear on the page.