Using the Utilities

This chapter provides an overview of the Global Payroll utilities and discusses how to:

• Define element relationships.

• Add records to an element map.

• View element relationships.

• Create and export rule packages.

• View the status of packages.

• Compare and upgrade rule packages.

• Rename elements.

• Create and export non-rule packages.

• Compare and upgrade non-rule packages.

• Copy packages.

• Stamp and package elements by version.

Understanding the Global Payroll Utilities

This section discusses:

• Utility usage guidelines.

• The packaging and upgrading processes.

• Base and related languages.

• The versioning functions.

• The delete functions.

• The process of connecting UNIX and NT directories.

Common Terms Used in This Chapter

See Also

Why the Core Application Uses Pay Item Name (PIN) Processing

Utility Usage Guidelines

Global Payroll provides a suite of integrated tools for implementing and maintaining the elements that define your payroll rules. You can use these utilities to view the relationships between elements, package and move elements and data between databases, and delete elements. When implementing your payroll system, you can use the utilities to move all or selected rules that you've created and tested into your production database. In an existing system, these utilities streamline the process of introducing new rules, installing system updates, and moving processing results and payroll data to other databases.

Here are some guidelines for using the utilities:

• Operations involving the utilities can have a significant impact on the system, so anyone using these tools must be very familiar with Global Payroll.

• Source and target databases must use the same PeopleTools release.

• The source and target databases used by the non-rule packager must share the same base language.

• Do not change the PIN_CODE in the Global Payroll language table (GP_PIN_LANG).

  Doing so can affect your ability to move elements.

• The utilities shouldn't be used during a pay run or while online work is being performed, but rather after business hours.

• You can import only one package at a time.

  Warning! Attempting to import more than one package at a time could result in the loss of critical data.

The Packaging and Upgrading Processes

To move rules and data between databases, you use several utilities in a specific sequence. This illustration shows the typical sequence for using the utilities to move rules and data between databases:

Moving rules and data between databases

To move rules and data between databases:

1. Create and upgrade a rule package.

   A rule package contains elements that are defined in records with PIN_NUM as the primary key. You use the Create/Export Rule Package and Apply Rule Package components to package and upgrade the elements you want to move. You can select individual elements for a package by name or by attribute, or you can select elements based on their version number. You tell the system whether you want to include only the focus elements or the focus elements plus the elements the focus elements use, based on the element map.

   You can direct the system to delete or upgrade elements in the target database. A batch process creates a package of elements that you can view online.

   After creating a package, you export it from the source database and import it into the target database; the system adds 50 000 000 to the value of each PIN number in the package to avoid overwriting elements in the target database that have matching PIN numbers.

   A batch compare process follows, in which the system compares the packaged elements with those in the target database. The goal is to determine which elements are new to the target database, which match elements that exist in the database, and which need deleting according to your instructions. Elements that are new to the target database are assigned the next PIN number.

   After reviewing the results of the comparison and resolving conflicts, you complete the upgrade process.

2. Create and upgrade a non-rule package.

   Non-rule packages contain data from records where PIN_NUM is not the primary key—plus information about related elements.

   To create a non-rule package:

   1. Define the criteria for creating the package of data to move.

   2. Export the non-rule data and element information from the source database.

   3. Import information for the elements (not the elements themselves) into the target database.

   4. Run a compare process that compares the packaged elements with those in the target database and identifies conflicts to address before importing non-rule data.

   5. Import the non-rule data and start an upgrade process that renumbers the PINs in the non-rule data records that were moved to the target database.

      For example, imagine that the absence results record (GP RSLT ABS) contains a take element with a PIN number of 1333 on the source database. The element was moved to the target database, and because it matches (based on PIN code) an element in the target database with PIN number 3453, the non-rule packager renumbers the PIN number in the absence results record.

Base and Related Languages

In the case of rule packages, the source and target database need not have the same base language. The rule packager, using Data Mover functionality, can identify the base language in the target database and use the correct language from either the base or related language table if that language existed in the source package. Additionally, the rule packager also creates a related language entry on the target database for the source database's base language. Consider the following example:

A German (DEU) target database contains the following data:

Base Data

You create a package from an English (ENG) source database copying PIN_CODE GP_TEMP001 for base language only. The system:

• Exports a data file containing information for PIN_CODE GP_TEMP001 from the ENG database.

  The data file contains the new PIN_NUM of 50 000 701.

• Imports the data file to the target database.

  Upon import, DataMover automatically creates a related language row with a language code of ENG.

The German target database now looks like this:

Related Language Data

The system then:

• Connects 50 000 701 with 701 using the PIN_CODE.

• Copies the DEU translatable fields from 701 to 50 000 701.

• Deletes the original PIN_NUM 701.

• Renumbers the new rows with the PIN_NUM of the target database.

The result of the process is updated information on the base table and a new ENG entry on the related language table, as shown below.

Base Table

Related Language Table

Had the package been defined as both base and related languages, the swapping of languages to some extent would already have been completed by datamover during the package import (if a related language row for the language of the target database was part of the package.) This would result in overlaying translatable fields of the base row with the contents of the copied language row. If only the related language was copied with the package, the process is the same as described above, except for translatable fields of the base row of the target database, which would be updated to contain the values of the moved language row.

The Versioning Functions

You can use the versioning utilities of Global Payroll to assign a version number to elements, and then have the system package only elements with this version number. Having created a package by version, you can move it to another database. In this case, the system moves changes from element definitions or component records (for example, if you change only an earning calculation, the element definition itself is not moved).

Version-based packages only pull data from the database base language table, not from the Pay Item Names — Related Language table (GP_PIN_LANG). The only way to move related language information from GP_PIN_LANG is to use a regular rule package.

The Delete Functions

To delete rules from the target or source database, you can enter instructions for deleting elements when defining the selection criteria for a package. To preserve the integrity of your data, you can delete an element only if it's not associated with other data. That is, the element being deleted must meet all of the following conditions:

• Not used in a result table.

• Not associated with payee data.

• Not linked to a non-rule table.

• Not used by another element.

• Not created by the PeopleSoft system.

Important! PeopleSoft recommends that you place elements to be deleted in a separate package from elements that you want to move from the source to the target database.

See Also

Selecting Elements for a Rule Package By Element

Selecting Elements for a Rule Package by Attribute

The Process of Connecting UNIX and NT Directories

If your application runs on UNIX, exporting and importing packages involves additional considerations. You can create data mover scripts on the UNIX machine, but the data mover used for importing and exporting packages can only be run via an NT Process Scheduler.

Important! Any job or process that uses data mover in a UNIX environment must run on an NT Process Scheduler.

Because UNIX and NT reference directories differently, you must define a shared directory that can be accessed by both platforms. In order to do so, the same paths must be mounted on both platforms. The path name must be defined identically on both machines. For example, we have defined the following directory structure to store datamover files:

• NT system: \\xx-xxx\hcm\datamover\

• UNIX system: /xx-xxx/hcm/datamover/

When you specify the path names before creating scripts, importing packages, or exporting packages, you must always use the NT notation including the double back slash. PeopleCode automatically transcribes the path name to the appropriate platform notation when needed.

Important! You must add the location of your scripts to the psprcs.cfg file in the NT Process Scheduler. You should verify that the section marked [Data Mover] has the Input and Output paths pointed to the same drive.

Defining Element Relationships

To define element relationships, use the Define Element Relationships (GP_PIN_FLD_MAP1) component.

The Define Element Relationships utility builds an element map that shows how elements with PIN numbers are related. It defines the relationship between elements, and enables packager to determine if elements are used in non-rule data, which is important when deleting elements and packaging non-rule data.

Although the packager process rebuilds the map when you create a rule package, we recommend that you rebuild the map when you define new elements, change existing elements, or delete elements. It's also advisable to rebuild the map for the target database after completing an upgrade. This ensures that the map is current when displayed.

This section discusses how to:

• Rebuild element maps.

• Review for errors.

See Also

Adding Records to an Element Map

Pages Used to Define Element Relationships

Rebuilding Element Maps

Access the Define/Build page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Define Element Relationships, Define/Build).

This page only lists those records that contain elements (which store PIN numbers). PIN NUM is often the key to these records, though this is not always the case.

Note. You cannot edit or delete this page if it displays information for a PeopleSoft-delivered object.

See Adding Records to an Element Map.

Fields Referencing Other Elements

This group box displays all fields that store the PIN numbers of (member) elements that are used by the record/field combination at the top of the page.

The sample page displays information for GP_ERN_DED, the record that defines earning and deduction elements. This record can use up to 17 elements. PIN_AMT_NUM and PIN_BASE_NUM are some of the fields that store PIN numbers of member elements. For example, PIN_BASE_NUM identifies the element that returns the base amount. To resolve an earning or deduction element, the system must know the PIN numbers of elements that store the amount, base, generation control instructions, and so on.

Applicable Element Types

When the record type is Element Definition, this group box identifies the corresponding element types. For example, the element types that apply to GP_ERN_DED are Earnings and Deductions.

Reviewing for Errors

Access the Validation page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Define Element Relationships, Validation).

Review this page for errors generated by the rebuild process.

Adding Records to an Element Map

The procedure for adding records to an element map depends on the record's main (first) key:

• If the main key is PIN_NUM, the record type is Element Definition (also called Rule Definition).

  Note. Rule definitions are created only by PeopleSoft.

• If the main key is not PIN_NUM, the record type is Output Result Data, Payee Data, or Set Up Definition, depending on its purpose.

This section discusses how to add non-rules to an element map.

Adding Non-Rules to an Element Map

This section describes the procedure for adding non-rule definitions to an element map, where the record's main key is not PIN_NUM.

To add a non-rule to an element map:

1. Use PeopleTools to create a SQL view for the record.

   The view must have the same structure as your new record, as illustrated in the following example.

   In the Select statement, enter + 50 000 000 after each field in the record that references a PIN number.

2. On the Define/Build page, add a row for the new record.

3. Complete these fields on the Define/Build page:

   1. For Record Type, select Output Result Data, Payee Data, or Set up Definition.

   2. For Record, select your new record.

   3. For Export Record, select the view that you created in step 1.

   4. For Effective Date Type, select the appropriate value for the record.

   5. For Field Name, select any field in the record that references PIN_NUM.

   6. In the Fields Referencing Other Elements group box, list each field within your record that contains a PIN number.

      This includes the field name defined in step e. You can select only PIN_NUM.

Example

This illustration shows how your SQL statement should match the record structure:

Record definition for GP_ PYE_OVR_SOVR

SELECT EMPLID
,EMPL_RCD
,PIN_NUM + 50000000
,BGN_DT
,PIN_SOVR_NUM + 50000000
,END_DT
,ENTRY_TYPE_SOVR
,SOVR_VAL_CHAR
,SOVR_VAL_NUM
,SOVR_VAL_DT
  FROM PS_GP_PYE_OVR_SOVR

Viewing Element Relationships

You can use the View Element Relationships utility to view hierarchical maps, including a map that existed as of a specific date.

This section discusses how to:

• View elements used by a focus element.

• View elements that use a focus element.

Pages Used to View Element Relationships

Viewing Elements Used by a Focus Element

Access the Uses page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, View Element Relationships, Uses).

Element maps include fields that contain PIN_NUM only. So, when looking at the map for an earning element, you don't see fields for frequency, currency, and other non-element information.

Perspective

To see additional information on a related element, click the element name in the Element Uses group box and select a view in the Perspective field.

Viewing Elements That Use a Focus Element

Access the Used By page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, View Element Relationships, Used By).

This page resembles the Uses page but shows all elements that use the focus element.

See Also

Viewing Elements Used by a Focus Element

Creating and Exporting Rule Packages

In release 9.1, Global Payroll offers a streamlined package creation process that enables you to create rule packages, create import/export scripts, and export rule packages using a single component for both standard and version based rule packages. You can run each step in this process—from package creation, to script creation, to package export—as part of a continuous sequence of steps, or run one step at a time. The Global Payroll system ensures that each step is complete before the next step begins, and displays the status of the package so that you can track your progress through the export process.

In addition, Global Payroll enables you to specify a default location on the Installation Settings page for the scripts used in the import/export process so that you do not need to enter the same basic information each time you export a package.

This section provides an overview of how to create and export rule packages, and discusses how to:

• Name rule packages.

• Select elements for a rule package by element.

• Select elements for a rule package by attribute.

• Select elements for a rule package by version.

• Modify the SQL Where clause for selection criteria.

• Create packages and scripts, and export packages.

• View the elements in a rule package.

• View version details for a package by version.

• View the status of a package.

• View a script.

Understanding How to Create and Export Rule Packages

To create and export a rule package:

Note. Rule packages can only include elements defined in records having PIN_NUM as the key.

1. Define criteria for selecting the elements in a rule package.

   You can define different kinds of selection criteria:

   • Use the Define Criteria By Element page of the Create/Export Rule Package (GP_PKG_CREXP) component to select elements for a package by name.

   • Use the Define Criteria By Attribute page of the Create/Export Rule Package component to select elements by attribute (element type, owner, used by, class, category, country).

     You can modify the SQL code that the system uses to select elements when you define criteria by attribute.

   • Use the Define Criteria By Version page of this component to select elements for a package based on their version number.

   You can specify criteria by element and by attribute for the same package. If you do this, the system selects all elements that meet the criteria specified on the Define Criteria By Element page or the Define Criteria By Attribute page.

   You cannot define criteria by version for a package together with criteria by element and/or by attribute. Version criteria are exclusive of other selection criteria.

2. Run the create package process to package the elements meeting the selection criteria.

   Do this on the Package Processing page of the Create/Export Rule Package component.

3. View the package and clear any elements that you do not want to move to the target database.

   Do this on the View Package page of the Create/Export Rule Package component

4. Run the create scripts process.

   Do this on the Package Processing page.

   Note. The system generates three scripts for the export and import process: xxx_exp.dms (export script), xxx_imp.dms (import script), and gp_cleanup.dms (cleanup script), where xxx represents the name of the rule package.

5. Review the scripts created in step 4 (above).

   Do this on the View Scripts page of the Create/Export Rule Package component.

6. Run the export package process.

   Do this on the Package Processing page.

   You must export the package before you can import it into the target database.

Note. This section represents the create rule package, create import/export scripts, and export rule package steps as separate, discrete processes; however, you can also run these steps as part of a single continuous process.

Warning! If you add or change an element after creating a package, you must recreate the package to include your changes.

Pages Used to Create and Export Rule Packages

Naming Rule Packages

Access the Package Definition page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create/Export Rule Package, Package Definition).

Description and Comment	Enter a description of the package and comments.
Version Based and Define Criteria By Version	Select the Version Based check box to define a package using version criteria. By default, this check box is deselected. When you select this check box, the Define Criteria By Version link appears and the Define Criteria By Element and Define Criteria By Attribute Links disappear. Click the Define Criteria By Version link to access the Define Criteria By Version page, where you can specify the version of the elements that you want to include in the rule package.
Define Criteria By Element	Click the link to access the Define Criteria By Element page, where you can select elements to include in the package by name. Note. When you specify the elements to include in the package on the Define Criteria By Element page and click OK, the check box in front of this link is automatically selected.
Define Criteria by Attribute	Click the link to access the Define Criteria By Attribute page, where you can select elements to include in the package based on attributes of the elements. Note. When you define element attributes on the Define Criteria By Attribute page and click OK, the check box in front of this link is automatically selected Note. You cannot define version based criteria for a package together with element or attribute criteria, as these package types are mutually exclusive. The system provides the following controls to prevent this from occurring: After you define and save version criteria for a package, you cannot access the Define Criteria By Element or Define Criteria By Attribute pages to add element and attribute criteria. In addition, if you try to combine package types before saving your work—for example, you define a version based rule package and then try to define additional criteria by element or by attribute—all of the version criteria you have already entered will be deleted at save time and you will receive a warning message.

Note. After you import a package, the Define Criteria By Element, Define Criteria By Attribute, and Define Criteria By Version links are disabled and you can no longer modify the selection criteria.

Selecting Elements for a Rule Package By Element

Access the Define Criteria By Element page (click Define Criteria By Element link on the Package Definition page).

Packaging Criteria - Element List

See Also

Base and Related Languages

Selecting Elements for a Rule Package by Attribute

Access the Define Criteria by Attribute page (click Define Criteria By Attribute link on the Package Definition page).

Attribute Set1

Select the Attribute Set1 tab.

Attribute Set2

Select the Attribute Set2 tab.

See Also

Selecting Elements for a Rule Package By Element

Defining Security

Base and Related Languages

Modifying the SQL Where Clause for Selection Criteria

Access the Where Clause page (click the Show Where Clause link on the Define Criteria By Attribute page).

Where Clause Option

Select Use Default WHERE Clause to use the default clause or revert to it after editing the SQL code. Any edits you make to the Where clause will be lost when you select Use Default WHERE Clause. Select Change WHERE Clause to make the code on the lower part of the page available for editing.

Where Clause

If you select Use Default WHERE Clause as the Where Clause Option, the system displays the Where clause of the SQL statement that it created based on the selection criteria defined on the Define Criteria by Attribute page. The Where clause is not editable. If you select Change Where Clause, you can edit the SQL Where clause. The following rules apply: Do not use PIN_NUM as a selection criterion or any field where PIN_NUM can be stored. (Doing so prevents renumbering during the import process.) Add the prefix PS_GP_PIN to field names that you enter. Example: PS_GP_PIN.RECALC_IND. Note. When you Click OK and save, the system checks for the use of PIN_NUM, and looks for SQL syntax errors.

Selecting Elements for a Rule Package by Version

Access the Define Criteria By Version page (Select the Version Based check box on the Package Definition page and click the Define Criteria By Version link).

Used By	Select All Countries or Specific Country depending on whether you are defining version criteria for all countries or a single country.
Specific Country	If you select Specific Country in the Used By field, specify the country.
Version	Select the version of elements to include in the package. You can select multiple versions if they are for the same country.

Creating Packages and Scripts, and Exporting Packages

Access the Package Processing page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create/Export Rule Package, Package Processing).

After defining selection criteria for a package, use the Package Processing page to:

• Create packages based on the selection criteria you have defined.

• Create scripts to use in the export and import process.

• Export packages to the target database.

• Track the status of a package.

During the export process, the system automatically adds 50, 000, 000 to the value of the PIN number assigned to each element so that it can distinguish the imported elements from elements that exist in the target database.

Processing Options

The check boxes under Processing Options display the status of the creation and export process. Status values are:

• Created: If this check box is selected, the package has been created.

• Scripts Created: If this check box is selected, scripts have been created for the package.

• Exported: If this check box is selected, the package has been exported to the target database.

Create Processing

Export Processing

Process

Click the Process button to call and run the processes denoted by the check boxes you have selected: Create Package, Create Scripts, and Export 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 create package first, then create scripts, then export package.

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.

Viewing the Elements in a Rule Package

Access the View Package page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create/Export Rule Package, View Package).

After creating a package, you can view the elements in the package and individually select any elements that you do not want to export to the target database.

Viewing Version Details for a Package By Version

Access the View Version Detail page (click the View Version Detail link on the View Package page for a package by version).

For elements packaged by version, access the View Version Detail page to view each element's version number and the database records (tables) containing the element definitions.

Viewing the Status of a Package

Access the Package Status page (click the Package Status link on the Package Processing page).

View the date and time packages and scripts were created, and see when packages were exported, imported, compared, and upgraded.

Viewing a Script

Access the View Scripts page (click the View Scripts link on the Package Processing page).

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. See Defining Global Payroll Installation Settings.

View Package Script

Select the type of script that you want to view: export, import, or cleanup. The DataMover script appears.

Importing, Comparing, and Upgrading Rule Packages

In release 9, Global Payroll 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 Global Payroll 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, Global Payroll 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.

See Defining Global Payroll Installation Settings.

This section provides an overview of rule package, imports, comparisons, and upgrades, and discusses how to:

• Import a package.

• Run the compare report.

• Start the compare and upgrade processes.

• Review for upgrade errors.

Understanding Rule Package Imports, Comparisons, and Upgrades

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:

1. Run the import process on the Package Processing page of the Apply Rule Package component.

2. 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.

3. 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.

4. 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.

5. Rerun the compare process on the Package Processing page after correcting errors or excluding elements from the package.

6. 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 rule and non-rule packages, 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:

Compare process for rule packages (flowchart 1)

Compare process for rule packages (flowchart 2)

Warning! Upgrades override elements in the target database with the information that has been sent over from the source.

See Also

The Delete Functions

Running the Compare Report

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.

Note. We provide a sample compare report in the sample reports PDF file (hgpy91reports) delivered with this PeopleBook.

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 the 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:

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 that 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 in the compare report, 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.

Pages Used to Import, Compare, and Upgrade Rule Packages

Viewing a Package Definition

Access the Package Definition page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Apply Rule Package, Package Definition).

View the Package ID and description of the package you are comparing and upgrading.

Starting the Import, Compare, and Upgrade Processes

Access the Package Processing page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Apply Rule Package, Package Processing).

Access this page from the target database.

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.

Import Processing

Compare Processing

Upgrade Processing

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.

Reviewing Results of the Compare Process

Access the Package Elements page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Apply Rule Package, Package Elements).

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.

Reviewing for Upgrade Errors

Access the Package Compare Audit page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Apply Rule Package, Package Compare Audit).

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.

Viewing the Status of a Package

Access the Package Status page (click the Package Status link on the Package Processing page).

View the date and time packages and scripts were created, and see when packages were exported, imported, compared, and upgraded.

Viewing a Script

Access the View Scripts page (click the View Scripts link on the Package Processing page).

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. See Defining Global Payroll Installation Settings.

View Package Script

Select the type of script that you want to view: export, import, or cleanup. The DataMover script appears.

Renaming Elements

This section provides an overview on how to rename elements, and discusses renaming an element.

Understanding How to Rename Elements

Sometimes the compare process finds an element in the target database whose PIN code is the same as the source element's, but the two elements have different element types or owners. In this case, you receive one of the following error messages: "Element Owner/Type Conflict" or "Mbr Element Owner/Type Conflict."

To continue exporting the element, you can use the Element Rename Utility to change the PIN code of the target element. After changing the PIN code, always rerun the compare process.

When you instruct the system to change an element's PIN code, it checks the following:

• Is the new PIN code already in use?

  If yes, the system generates an error.

• Is the old PIN code used in PeopleSoft Enterprise Time and Labor?

  If yes, the system creates a warning. Remap the element in Time and Labor to reflect the new code.

• Is the new PIN code the same as the old PIN code?

  If yes, the system issues a warning.

Important! Do not rename an element when you are in the process of creating a package.

PeopleSoft created elements cannot be renamed.

Warning! Time and Labor stores PIN code information, so if you make a change, you must update Time and Labor data accordingly.

See Also

The Delete Functions

Configuring Human Resources

Page Used to Rename Elements

Renaming an Element

Access the Element Rename page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Rename Element Codes, Element Rename).

New PIN Code (new pay item name code)

Enter the new code. The old PIN code is replaced when you save. Note. When renaming a PIN, make sure that you use the PIN name plus the country suffix. For example: PIN NAME DEU.

Creating and Exporting Non-Rule Packages

This section provides an overview of creating and exporting non-rule packages and discusses how to:

• Name non-rule packages.

• Define selection criteria.

• Modify the SQL Where clause for the selection criteria.

• Display elements of a non-rule package.

• Export and import non-rule packages.

• View non-rule package scripts.

Understanding How to Create and Export Non-Rule Packages

Non-rule packages contain both non-elements and element information. Non-elements are those that belong to records where PIN_NUM is not the primary key.

Important! When creating a non-rule package, make sure that records that are related to the record you are moving are included in the same package. To move a complete set of related data, you need to understand which records are related.

Before moving non-rule data, make sure that the elements that are associated with the non-rule data exist in the target database. You can do this by creating a rule package that contains the elements that are associated with the data record that's being moved and copying (upgrading) the rule package to the target database.

For example, suppose that you are moving non-rule calendar detail records. Calendar details are associated with the process number element (PIN_PRC_NUM). Before moving the calendar data, create a rule package that contains the process number element and move it to the target database. The system can assign a new PIN number to this element in the target database, if necessary. Once this package is in the target database, you can move the calendar details by creating a non-rule package.

When the system moves the calendar details, it finds the process number element in the target database, retrieves the new PIN number that was assigned during the rule upgrade process, and renumbers the process number PIN in the calendar detail record. (Without renumbering, the calendar detail would contain PIN numbers that may not exist or are not related the element used by that calendar in the target database.)

To create and export a non-rule package:

1. Create the non-rule package.

   To do this, use the Create Non-Rule Package (GP_NR_PKG_CREATE) component.

   On this component you can:

   • Define the selection criteria for the records to move from the source database.

   • Run the create package process.

   • View the rules that are associated with the data that you're moving.

2. Export the non-rule package.

   To do this, use the Export Non-Rule Package (GP_NR_PKG_EXPORT) component.

   The system exports the non-rule data and the element information contained in the non-rule package.

Note. Global Payroll enables you to specify a default location for the scripts used in the export non-rule package process so that you do not need to enter the same basic information each time you export a package. To do this, access the Installation Settings page for Global Payroll (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, System Settings, Installation Settings) and specify the script location.

Pages Used to Create and Export Non-Rule Packages

Naming Non-Rule Packages

Access the Package Definition page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create Non-Rule Package, Package Definition).

Enter a description of the package and comments.

Defining Selection Criteria

Access the Package Criteria page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create Non-Rule Package, Package Criteria).

Package ID	Displays the package ID.
Record	Select the record that contains the data to move. The Data Selection group box becomes available.
Where Clause Option	The system converts the criteria entered on this page into SQL in order to select elements for the package. Values are: Use Default WHERE Clause: Tells the system to use the default Where clause. If the where clause has been changed and Use Default WHERE Clause is selected again, the page discards any SQL code modifications you have made and reverts to the Where clause based on the criteria you specified. Change WHERE Clause: Makes all other fields on the page unavailable and puts the SQL code on the Package Records page in edit mode.

Data Selection

Use the fields in the Data Selection group box to indicate which data to move. Selection criteria are optional, but if you don't enter selection criteria, no delete process is performed on the target database before source data importation. This can result in a "Duplicate Record" message from Data Mover during import, or it can cause the upgrade process to fail.

Modifying the SQL Where Clause for the Selection Criteria

Access the Create Non-Rule Package - Package Records page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create Non-Rule Package, Package Records).

Record	Displays the record from which fields are selected.
Where Clause Option	Select a Where clause option. Values are: Change WHERE Clause: Select to edit the SQL code on the lower part of the page. Use Default WHERE Clause: Select to use the default clause or revert to it after editing the SQL code. Changes that you have made to the Where clause are lost and the field is disabled.
Where Clause	If you selected Use Default WHERE Clause in the Where Clause Option field, the system displays the Where clause of the SQL statement it created based on the selection criteria that you entered for the package on the Create Non-Rule Package - Package Criteria page. This WHERE clause cannot be edited. If you selected Change Where Clause, you can edit the SQL. Do not use PIN_NUM as a selection criterion or any field where PIN_NUM can be stored. (Doing so prevents renumbering during the import process.)

Displaying Elements of a Non-Rule Package

Access the Package Elements page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Create Non-Rule Package, Package Elements).

Note. This display page lists the rule elements used in the records being moved to the new database. These are informational elements. The page doesn't show data in records where PIN Num is not a field.

Creating Scripts and Exporting Non-Rule Packages

Access the Export Non-Rule Package - Package Records page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Export Non-Rule Package, Package Records).

Script Location	Specify the path to the location where you want the import/export scripts to be created when you click the Create Scripts button. 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. See Defining Global Payroll Installation Settings.
Record	Displays the name of the record containing the data that you're exporting.
Where Clause	Displays the Where clause of the SQL statement that selects the data to be exported.
Create Scripts	Click to create the import and export scripts for the non-rule package: xxx_elements_imp.dms, xxx_elements_exp.dms, xxx_records_exp.dms, and xxx_record_imp.dms (where xxx = name of package). The scripts will be created in the script location you specify.
Export	Click to export the package once you have selected a script location.

Viewing Non-Rule Package Scripts

Access the View Scripts page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Export Non-Rule Package, View Script).

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. See Defining Global Payroll Installation Settings.

View Package Script

Select the type of script that you want to view: either export or import scripts for the elements and records. The DataMover script appears.

Viewing the Status of a Package

Access the Package Status page (click the Package Status link on any page in the Export Non-Rule Package and Create Non-Rule Package components).

View the date and time a package was created, exported, imported, compared, and upgraded.

Importing, Comparing, and Upgrading Non-Rule Packages

This section provides an overview of comparing and upgrading non-rule packages and discusses how to:

• Import non-rule element information.

• Compare non-rule packages with the data in a target database.

• Import non-rule records.

• Upgrade non-rule packages.

Understanding How to Import, Compare, and Upgrade Non-Rule Packages

After creating and exporting a non-rule package:

1. Import the non-rule elements.

   To do this, use the Import Non-Rule Elements (GP_NR_PKG_IMPORT) component.

   The system imports the element information only—not the elements themselves.

2. Compare the elements in the non-rule package with those in the target database to ensure that the non-rule elements are in the target database.

   To do this, use the Compare Non-Rule Package (GP_NR_PKG_COMPARE) component.

   Using this component you:

   • Compare the element information in the package with the element information in the target database.

   • Identify any missing elements that need to be moved into the target database.

3. Import the non-rule records.

   To do this, use the Import Non-Rule Records (GP_NR_PKG_IMPRECS) component.

4. Upgrade the non-rule package.

   To do this, use the Upgrade Non-Rule Package (GP_NR_PKG_UPGRADE) component.

Note. Global Payroll enables you to specify a default location for the scripts used in the import non-rule package process so that you do not need to enter the same basic information each time you import a package. To do this, access the Installation Settings page for Global Payroll (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, System Settings, Installation Settings) and specify the script location.

Pages Used to Import, Compare, and Upgrade Non-Rule Packages

Naming Non-Rule Packages

Access the Package Definition page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Import Non-Rule Elements, Package Definition).

Enter or view a description of the package and comments.

Importing Non-Rule Element Information

Access the Import Non-Rule Elements - Package Records page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Import Non-Rule Elements, Package Records).

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. See Defining Global Payroll Installation Settings.

Import Package

If the button is available, click to start the import process.

Comparing Non-Rule Packages with Elements in a Target Database

Access the Compare Non-Rule Package - Package Elements page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Compare Non-Rule Package, Package Elements).

After completing the first part of the export and import process, log onto the target database and perform the compare process, which verifies that the elements needed by the data you're moving exist in the target database. The compare process checks PIN code and PIN type.

If the elements don't exist or if the element types do not match, the compare process fails and you must create a rule package and move the package to the target database before continuing with the non-rule upgrade.

Element List

This group box shows the results of the comparison of the source and target databases. If the compare process reports failures, correct the errors before continuing with the upgrade process.

Importing Non-Rule Records

Access the Import Non-Rule Records - Package Records page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Import Non-Rule Records, Package Records).

After reviewing the results of the compare process and moving any missing elements into the target database, you can import the non-rule records into the target database.

Click the Record Import button to import the records.

Upgrading Non-Rule Packages

Access the Upgrade Non-Rule Package - Package Records page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Upgrade Non-Rule Package, Package Records).

The final step is to renumber the elements on the non-rule data that you've imported so that they have the same PIN numbers as the matching elements in the target database, using the Upgrade Non-Rule Package component.

Viewing Non-Rule Package Scripts

Access the View Script page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Import Non-Rule Elements, View Script).

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 called 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. See Defining Global Payroll Installation Settings.

View Package Script

Select the type of script that you want to view: export or import. The DataMover script appears.

Viewing the Status of a Package

Access the Package Status page (click the Package Status link on any page in the Import Non-Rule Package, Compare Non-Rule Package, or Upgrade Non-Rule Package components).

View the date and time a package was created, exported, imported, compared, and upgraded.

Copying Packages

This section discusses how to:

• Copy a rule package and its selection criteria.

• Copy a non-rule package and its selection criteria.

Note. Copying packages alone does not prepare the package for export. You must also run the create rule or non-rule process, which attaches all elements to the package.

Pages Used to Copy Packages

Copying a Rule Package and Its Selection Criteria

Access the Copy Rule Package page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Copy Rule Package, Copy Rule Package).

Copy To Package ID	Enter up to eight alphanumeric characters for the new package ID.
Copy Package Definition	Click to copy the package.

Copying a Non-Rule Package and Its Selection Criteria

Access the Copy Non-Rule Package page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Copy Non-Rule Package, Copy Non-Rule Package).

See the field descriptions for the Copy Rule Package page.

See Also

Copying a Rule Package and Its Selection Criteria

Stamping and Packaging Elements by Version

This section provides an overview of stamping and packaging elements by version and discusses how to:

• Stamp elements with a new version number.

• Define version relationships.

• Identify elements to package.

• View version details.

Understanding How to Stamp and Package Elements by Version

Versioning is a way to track the elements that were delivered for each release or update and to package elements by version. For example, elements delivered with Global Payroll 8.9 are labeled 8.90.00. Major releases, updates, and hot fixes typically require a new version of all or some previously delivered rules.

You can assign a version number (or label) to multiple elements and use the versioning utilities to package elements by version so that they can be moved to another database.

When you package elements by version, the system pulls the rows associated with the version that you specify. Once the elements are packaged, you can move them across databases, using the same procedures that apply to rule packages; you export the elements, compare them with existing elements in the database, and complete the upgrade.

To package elements by version:

1. Stamp the appropriate version number(s) on the elements that you want to package using the Version Stamping (GP_STAMPING) component.

2. Use the Define Criteria By Version page of the Create/Export Rule Package (GP_PKG_CREXP) component to define selection criteria for packaging the elements that you stamped in step 1.

3. Follow all other instructions presented earlier in this chapter for creating and exporting rule packages.

   See Creating and Exporting Rule Packages.

4. Follow the instructions presented earlier in this chapter for importing, comparing, and upgrading rule packages.

   See Importing, Comparing, and Upgrading Rule Packages.

See Also

Defining Element Names

Pages Used to Stamp and Package Elements by Version

Stamping Elements with a New Version Number

Access the Version Stamping page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Version Stamping, Version Stamping).

Use this page to stamp a version on elements that you add or modify or to restamp an existing version of an element.

Note. Versioning occurs only in element definition records (records with a primary key of PIN_NUM).

Defining Version Relationships

Access the Define Version Relationships page (Set Up HRMS, Product Related, Global Payroll & Absence Mgmt, Elements, Manage Global Payroll Packages, Define Version Relationships, Define Version Relationships).

Rule Definition Record	Displays the name of the parent record that contains the field GP_VERSION.
Child Record	Displays the child record whose data when changed causes GP_VERSION to be cleared from the corresponding row in parent record. (The name of the parent record is displayed here if there are no children.)
Export Record	Selected if the child record is to be included in the version package for export and import. For example, when an accumulator element changes, only data in GP_ACCUMULATOR and GP_ACM_MBR needs to be moved. The child record, GP_ACM_MBR_VW, does not need to be exported and imported because it is used only to associate accumulators with earnings and deductions in the Earnings and Deductions components.
Rule Record in Buffer	Applicable to accumulators only. Selected if the record that has GP_VERSION is in the component buffer (for example, when an earning accumulator is changed, and needs GP_VERSION cleared). Record GP_ACCUMULATOR is not in the component buffer. Select this check box to prevent the system from looking for the record in RECNAME_RULE_DFN in the component buffer and issue a SQLEXEC instead. The child record that exists in the earnings component is GP_ACM_MBR_VW.
PIN Number Field	Displays the name of the PIN_NUM field on the record that needs GP_VERSION cleared. Using the earlier example, the earning accumulator PIN_NUM is contained as PIN_MBR_NUM in the earning component buffer and PIN_NUM itself contains the earning PIN. So, when updating data for GP_ACCUMULATOR, data for PIN_MBR_NUM value and not PIN_NUM value from the earnings component must be updated.