Importing, Comparing, and Upgrading Rule Packages
Absence Management offers a streamlined package import and compare process that enables you to run the import, compare, and upgrade process using a single component for both standard and version based rule packages. You can run each step in this process—from package import, to comparison, to upgrade—as part of a continuous sequence of steps, or run one step at a time. The Absence Management system ensures that each step is complete before the next one begins, and displays the status of the package so that you know exactly where you are in the process.
In addition, Absence Management enables you to specify default packager-related options on the Installation Settings page so that you do not need to enter the same basic information each time you run the import, compare, and upgrade process. Use the Installation Settings page to:
Specify a default location for the scripts used in the import process.
Specify compare report print options for standard and version based rule packages to control the type of information that appears in the compare report.
Specify the conditions under which an upgrade is permitted—that is, you can elect to proceed with upgrades despite errors and warnings in the compare process, or choose not to allow upgrades containing errors or warnings.
|
Page Name |
Definition Name |
Usage |
|---|---|---|
|
GP_PKG_DFN |
View the description and package ID of a rule package. |
|
|
GP_PKG_T_RUNCTL |
|
|
|
GP_PKG_ELEM_UPG |
View the results of the Compare processes and exclude elements from the Upgrade process. |
|
|
GP_PKG_CMP_AUDIT |
Review for errors that occur during the Compare process. Before continuing with the Upgrade process, correct the errors and rerun the Compare process. |
|
|
GP_PKG_DTTM_SEC |
View the date and time a package was created, exported, imported, compared, and upgraded. |
|
|
GP_PKG_SCRIPTS_SEC |
View export, import, and cleanup scripts. |
After running the export process, use the Apply Rule Package (GP_PKG_APPLY) component to import the package into to the target database, compare the rules in the source database to those in the target database, and upgrade the rule package.
To import, compare, and upgrade a rule package:
Run the import process on the Package Processing page of the Apply Rule Package component.
Compare the packaged elements with the elements in the target database by running the compare process and generating the compare report on the Package Processing page of the Apply Rule Package component. Generating the compare report is optional.
The system determines which elements are new to the target database, which update existing elements in the target database, and which need deleting from the target database.
Review the compare report and the results displayed on the Package Elements and Package Compare Audit pages of the Apply Rule Package component to determine the results of the compare process.
On the Package Elements page you can exclude elements from the upgrade process.
Resolve warnings and errors that are identified in the compare report, on the Package Elements page, and on the Package Compare Audit page during the compare process.
Warnings and errors can occur for several reasons. For example, the source element could use other elements that don't exist in the target database and are not included in your package or an element that you want to delete could be used in a results table. The corrective action depends on the type of error and warning.
Rerun the compare process on the Package Processing page after correcting errors or excluding elements from the package.
Run the upgrade process after deciding whether to proceed with errors and/or warnings.
Do this on the Package Processing page.
During the upgrade process the system:
Updates the imported elements with the correct PIN number if they already exist in the database.
Assigns new numbers to the new elements.
Deletes rows according to the option chosen in the package.
You can run this process only once.
Note: This section presents the package import, comparison, and upgrade steps as separate, discrete processes; however, you can run these steps as part of a single continuous process.
Note: Before moving multiple elements simultaneously, it is recommended that you back up the target database.
What Happens During the Compare Process
For each exported element, the system looks for an element in the target database with the same PIN code, element type, and element owner.
This flowchart shows the logic that the system uses to perform the comparison and generate the resulting warning or error messages (flowchart 1).
This flowchart shows the logic that the system uses to perform the comparison and generate the resulting warning or error messages (flowchart 2).
Warning! Upgrades override elements in the target database with the information that has been sent over from the source.
Important! When you upgrade an existing element, the system updates the matching element in the target database, but it does not delete member data unless there is new member data to replace it. For example, if you delete the last row of an existing formula in the source database and then export and apply a package to the target database, the child rows remain unchanged in the target database. Likewise, if you remove all child elements from the Generate Positive Input Member List for an absence take in the source database, the system does not remove the child elements from the same absence take in the target database.
You can generate a compare report while performing the compare process. The compare report enables you to see what elements the Rule Package will change on a field-by-field basis. Use this information to decide whether to upgrade a specific element.
The compare report creates a report displaying the affected elements and what the differences are between the elements in the Rule Package and the elements in the target database. The compare report can only be run at the same time as the compare process.
Compare Report Summary Page
The summary page is the first page of the compare report. It includes the following information:
Type of rule package (regular or version based).
Version of the elements included in the rule package if the package is version based.
The names of the source and target databases.
The date and time that the import and compare processes were run.
The countries with elements included in the package.
The total number of elements in each of these categories listed below, depending on the Compare Report Print Options selected on the Package Processing page:
Elements with errors/warnings.
Modified elements.
New elements.
Deleted elements.
Unchanged elements.
Note: These totals are for all of the elements in a package except those that are for information only, and are not separated by country. The exception to this rule is that the total for errors/warnings includes informational elements.
Compare Report Body
The body of the compare report consists of four columns. The columns and contents are described in the following table:
|
Column |
Contents |
|---|---|
|
Elements |
Note: Upgrade action, upgrade, compare status, and error or warning messages appear only on the Elements With Error/Warning Messages page of the report. |
|
Record.Field |
Record and field name for the values contained in the Source Database and Target Database columns. |
|
Source Database |
Data values that are moving from the source to the target database as part of the Rule Package for the applicable record or field name. |
|
Target Database |
Data values that are currently in the target database for the applicable record or field name. |
Note: Elements in the compare report are displayed based on the alphabetical order of their country codes. For example, elements for CHE (Switzerland) appear before elements for DEU (Germany). The country code All (Across All Countries) appears if there is an element in the package that is defined for All countries or is in error/warning status.
Elements Displayed in the Compare Report
The compare report is made up of different sections containing detailed information about different categories of elements:
Elements with Errors or Warnings — All elements that have an error or warning message appear in this first section with basic information about the element (if it is available). All errors and warnings should be looked into and resolved before continuing the upgrade process.
Modified Elements — This section is for modified elements and displays the rows (records and fields) that will be changed in an upgrade. If a new row of data is being added, it also appears in this section.
Important! The element definition tables for array, bracket, formula, fictitious calculation, and historical rule elements include a sequence number field. This field is not always displayed online and has a purely technical function; however, you may see these elements appearing in the compare report as modified due only to changes in their sequence number. This is expected, as the report provides a field-by-field comparison. If the report lists these elements as modified, you should determine whether fields and information other than sequence number have changed (as this is what is critical from a functional perspective). If only the sequence number has changed, there will be no functional impact from an upgrade to these elements.
Important! Rate Code elements are keyed by both PIN Number (PIN_NUM) and HR Compensation Rate Code (COMP_RATECD). As a result, if the HR Rate Code is changed in an element definition, you will see this displayed in the modified elements section of the compare report as a new row (with 2 key fields appearing) and a deleted row (with 2 key fields appearing).
New Elements — This section is for new elements in the rule package (elements that are not in the target database), and displays the following fields from GP_PIN: PIN Code (as the key field); PIN_NM; DESCR; COMMENTS.
Deleted Elements — This section is for deleted elements, and displays the following fields from GP_PIN: PIN Code (as the key field); PIN_NM; DESCR; COMMENTS.
Elements with no changes — Only pin code and element name are displayed in this section.
Note: These report sections are displayed country by country in alphabetical order of the country codes. For example, report sections for CHE (Switzerland) appear before those for DEU (Germany). If you request a report section and there are no elements belonging to that category, the following message appears in that section of the compare report: "There are no elements that qualify for this section." For country code 'All' (Across All Countries), the report sections only print out if there are elements to report on. No page is printed if no elements exist for 'All' in the section—not even the message noted above appears. Country code 'All' pages always appear at the end of the report.
Note: For formulas, only the formula text is displayed, rather than details about each individual field.
For all PIN Number fields, the compare report displays the corresponding PIN Code instead of the PIN Number.
Note: In the compare report, record information is printed in the following sort order: GP_PIN (if applicable), Parent Element Definition Record (if applicable), and Child Element Definition Records (if applicable). Within each of these records, the data displayed is sorted by effective-date descending (if effective date is in the record) and then by key fields ascending.
Use the Package Definition page (GP_PKG_DFN) to view the description and package ID of a rule package.
Navigation:
This example illustrates the fields and controls on the Package Definition page.
View the Package ID and description of the package you are comparing and upgrading.
Use the Package Processing page (GP_PKG_T_RUNCTL) to .
Navigation:
Access this page from the target database.
This example illustrates the fields and controls on the Package Processing page.
Use this page to import, compare, and upgrade rule packages and to track the status of an upgrade.
Processing Options
The check boxes under Processing Options display the status of the upgrade. Status values are:
Imported: If this check box is selected, the package has been imported into the target database.
Compared: If this check box is selected, the elements in the package have been compared with those in the target database.
Upgraded: If this check box is selected, the target database has been upgraded with the elements in the package.
Field or Control |
Description |
|---|---|
Package Status |
Click to access the Package Status page, where you can view the date and time packages and scripts were created, and see when packages were exported, imported, compared, and upgraded. |
Import Processing
Field or Control |
Description |
|---|---|
Import Package |
Select Import Package to instruct the system to import the elements in the package into the target database during processing. You must specify a path to the scripts used to import the package. This check box is always enabled, regardless of whether the package has already been imported. |
Script Location |
Specify the path to the location where you want the scripts to be created. The location of the scripts and data files must be accessible by both the import and export NT Process Scheduler for the import and export databases. You must specify the script location in the Process Scheduler configuration file (psprcs.cfg). Note: We discuss how to specify the script location in the Process Scheduler configuration file in the section titled The Process of Connecting UNIX and NT Directories. See The Process of Connecting UNIX and NT Directories. Note: You can define a default script location on the Installation Settings page for all packager scripts. |
View Scripts |
Click to access the View Scripts page, where you can view the export, import, and cleanup scripts. |
Compare Processing
Field or Control |
Description |
|---|---|
Compare Package |
Select Compare Package to have the system compare the imported elements with those in the target database during processing. This check box is enabled when:
When the compare process is complete, check the Package Upgrade tab on the Package Elements tab and then review the Package Compare Audit page for errors. |
Create Compare Report |
Select to generate a report comparing elements in the rule package to the elements in the target database on a field-by-field basis. This check box is enabled when you select the Compare Package check box. |
Update Statistics |
Select to update statistics in the appropriate tables when running the compare process. |
Compare Report Print Options |
These check boxes determine what data appears in the compare report.
Note: You can set default print options for the compare report on the Installation Settings page. You can override these defaults when you run the compare process on the Package Processing page. |
Upgrade Processing
Field or Control |
Description |
|---|---|
Upgrade Package |
Select Upgrade Package to have the system upgrade the target database with the elements in the package during processing. This check box is enabled when:
This process upgrades only those elements that pass the compare process without errors. You can upgrade a package only once. Note: The upgrade process will not be completed if there are errors or warnings—unless you select upgrade with errors and/or warnings. If you choose not to upgrade with errors and warnings and there is an error or a warning, the process monitor will show success but the message log will display one of the following messages: 1. "The Upgrade process cannot continue because the compare process finished with some elements having a status of Error. Please see online 'Package Elements' page or review the 'Error/Warning' section of your report." or 2. "The Upgrade process cannot continue because the compare process finished with some elements having a status of Warning. Please see online 'Package Elements' page or review the 'Error/Warning' section of your report." Even with the upgrade with errors and warnings check boxes selected, at least one element must have a status of success for the process to upgrade the elements. You must fix the errors. Important! Do not run the compare and upgrade processes together with regular payroll processes. This is to avoid affecting other users. |
Update Statistics |
Select to generate and view statistics on the upgrade process. This check box becomes available when you select Upgrade Package. |
Continue Upgrade Processing |
Select With Errors and/or With Warnings to proceed with the upgrade despite errors and warnings in the compare report. If you do not select one or both of these options, and there are errors or warnings, the process will not upgrade. The process will run to success but a message will be generated with information about the errors or warnings. These check boxes become available when the Upgrade Package check box is selected. Note: Even with the With Errors check box selected, elements that are in error are not included in the upgrade—only elements in the package that are not in error are upgraded in the target database when you run the upgrade process. By contrast, selecting the With Warnings check box does not prevent an element with an associated warning from being included in the upgrade if the upgrade check box is selected. However, if you do not select With Errors and/or With Warnings, and there is even a single error or warning, the process will not upgrade. The process will run to success but a message will be generated with information about the errors or warnings. Note: You can set default options for continuing an upgrade on the Installation Settings page. You can override these defaults when you run the upgrade process on the Package Processing page. |
Process
Click the Process button to call and run the processes denoted by the check boxes you have selected: Import Package, Compare Package, and Upgrade Package. Note that you can select all three check boxes at the same time and run these processes as a single, continuous sequence, or run one process at a time. However, the processes must run in the order of import first, then compare, then upgrade.
Note: When you click the Process button the Process Monitor page appears, so that you can monitor the process. Wait until the program finishes before opening a page associated with the package.
Use the Package Elements page (GP_PKG_ELEM_UPG) to view the results of the Compare processes and exclude elements from the Upgrade process.
Navigation:
This example illustrates the fields and controls on the Package Elements page: Elements tab.
This example illustrates the fields and controls on the Package Elements page: Package Upgrade tab.
This page displays the results of the compare process. If failures are reported, correct the errors before continuing with the upgrade. The Package Compare Audit page provides additional information about the errors.
Field or Control |
Description |
|---|---|
View Element Browser Compare |
Click this button to load the package into the Element Browser Page where you can view a comparison of the elements updated by the package. |
Source PIN Number (source pay item name number) |
Displays the PIN number of the element from the source database (without an added 50 000 000). |
Element Name |
Displays the name of the element in the source database. |
Upgrade |
Select this option to overwrite the element with the data from the source database. If you modified the target element then your changes will be lost. To exclude the element from the upgrade process, clear the check box. Excluded elements will retain any changes you may have made. Important! If you exclude an element from the package, you must rerun the compare process before resuming the upgrade. |
Result |
Displays the result of the comparison. Values are: Not Done: You haven't yet run the compare process. Success: The compare process encountered no errors. Failure: The compare process failed. The Reason field shows why. Warning: The PeopleSoft system has modified the element in the source database (the upgrade flag is checked on) or you have taken control of the element ownership (the upgrade flag is checked off). The Reason field explains the reason for the warning. In order to accept or ignore the change, update the upgrade flag to indicate whether you want the element upgraded. Note: Failures are listed first, followed by warnings and then successes, so if the entries on the first page all read Success, you can assume that the entire comparison process succeeded. |
Reason |
If the compare process failed or generated a warning, one of the following reasons appears here: New Element Not Copied Completely: You're trying to copy a new element into the target database but that element has no GP_PIN record—only a definition. (For example, you stamp and package elements by version. Another person modifies the element and clears the version number.) Restamp the element with the appropriate version and export it again. Note: This error occurs when an element is new and only GP_PIN is brought in and not the definition, or when the definition is there but not GP_PIN. Element Owner / Type Conflict: The PIN code for the source element matches a PIN code in the target database, but the owner or element type doesn't match. Use the Element Rename page to change the PIN code in the target database. If an element is customer-defined, the Element Owner field on the Compare and Upgrade Package - Package Elements page reads Customer. Member Element not found: The source element uses other elements that don't exist in the target database and aren't included in the package. Remove the element from the upgrade process by clearing the Upgrade check box, or include the missing elements in the packaging criteria, recreate the package in the source database, and re-import it. Mbr Element Owner/Type Conflict (member element owner/type conflict): This is similar to the Element Owner/Type Conflict message but applies to a member element that's used by the focus element. Use the Element Rename page to change the PIN code in the target database. Element does not exist: You're trying to delete an element that's not in the target database. PS Delivered/Customer Modified: This warning indicates that the element in the target database has been modified and no longer matches the element in the source database. To accept the PeopleSoft or customer modifications and overwrite any changes in the target database, select the Upgrade check box. The element ownership remains PS Delivered/Customer Modified once the check box is selected. PS Delivered/PS Modified: This warning indicates that the PeopleSoft system has changed the ownership of the element in the source database so that it's no longer PeopleSoft delivered or maintained. To reject the change, clear the Upgrade check box. Cannot delete PS-Owned Element: You're trying to delete a PeopleSoft-owned element from the target database. You cannot delete such elements. Duplicate Package Element Found: You're trying to import an element that is in another package that's being upgraded. Used in Non-Elem Defn (element definition): You are trying to delete an element that is used in a non-element definition. Modify the non element definition so that it no longer uses this element. Used in Output Results: You are trying to delete an element that is used in a processing result table. (Results cannot be deleted from the result tables.) Used in Payee Data: You're trying to delete an element that's associated with payee data. Modify the payee data so that it no longer uses this element. Used in Rule Defn (definition): You are trying to delete an element that is used by another element. Modify the rule definition so that it is no longer uses this element. Auto-component used in RuleDfn (rule definition): You are trying to delete an element whose component is used by a rule definition. Modify the element definition so that it is no longer uses this component. |
New Element |
The check box is selected if the element to be upgraded isn't in the target database. |
Upgrade Status |
Indicates whether the upgrade process has occurred. Changes from Not Done to Done after you complete the compare and upgrade processes. |
Use the Package Compare Audit page (GP_PKG_CMP_AUDIT) to review for errors that occur during the Compare process.
Before continuing with the Upgrade process, correct the errors and rerun the Compare process.
Navigation:
This example illustrates the fields and controls on the Package Compare Audit page – Elements tab.
This example illustrates the fields and controls on the Package Compare Audit – Package Upgrade tab.
Field or Control |
Description |
|---|---|
Parent |
Displays the name of the parent element. |
Member Element |
Displays the name of the member element that generated the error. |
Failure Reason |
Displays the cause of the failure. The same information appears in the Reason field on the Package Elements tab. |
Upgrade Action |
Displays the action that the system was trying to take when the error occurred. Values are: Upgrade, Delete, and Info Only. |
Package Upgrade
Select the Package Upgrade tab.
Field or Control |
Description |
|---|---|
Parent |
Displays the name of the parent element that generated the error. |
Member Element |
Displays the name of the member element that generated the error. |
Record (Table) Name |
Displays the name of the record that stores the parent element and its members. |
PIN Num Fieldname (pay item name number field name) |
Displays the name of the field that contains the key field. |
Field Name |
Displays the name of the field that contains the member element that created the error. |
Use the Package Status page (GP_PKG_DTTM_SEC) to view the date and time a package was created, exported, imported, compared, and upgraded.
Navigation:
Click the Package Status link on the Package Processing page.
This example illustrates the fields and controls on the Package Status page.
View the date and time packages and scripts were created, and see when packages were exported, imported, compared, and upgraded.
Use the View Scripts page (GP_PKG_SCRIPTS_SEC) to view export, import, and cleanup scripts.
Navigation:
Click the View Scripts link on the Package Processing page.
This example illustrates the fields and controls on the View Scripts page.
Field or Control |
Description |
|---|---|
Script Location |
Displays the script location, which must be accessible by both the import and export NT Process Scheduler for the import and export databases. You must specify the script location in the Process Scheduler configuration file (psprcs.cfg). Note: We discuss how to specify the script location in the Process Scheduler configuration file in the section titled The Process of Connecting UNIX and NT Directories. See The Process of Connecting UNIX and NT Directories. Note: You can define a default script location on the Installation Settings page for all packager scripts. |
View Package Script |
Select the type of script that you want to view: export, import, or cleanup. The DataMover script appears. |