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 nonrule packages.

• Compare and upgrade nonrule 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 Elements 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 nonrule packager must also share the same base language.

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

  Doing so can affect the movement of this table.

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

• You should import only one package at a time.

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 Rule Package utility to package the elements being moved. You can select individual elements by name, specify the attributes of the elements to include in the package, or both. 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.

   An online compare process follows, where the system compares the packaged elements with those in the target base. 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 nonrule package.

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

   To create a nonrule package:

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

   2. Export the nonrule 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 nonrule data.

   5. Import the nonrule data and start an upgrade process that renumbers the PINs in the nonrule 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 nonrule packager renumbers the PIN number in the absence results record.

Base and Related Languages

The source and target database need not have the same base language. The rule packager, using Data Mover functionality, can change the data to the target's base language, if that base language is a related language in the source database. Additionally, the feature 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 an element and to package elements by multiple versions. Having created a package, 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 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 the following conditions:

• Not used in a result table.

• Not associated with payee data.

• Not linked to a nonrule table.

• Not used by another element.

• Not created by the PeopleSoft system.

See Also

Selecting Elements for a Rule Package

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 requires additional consideration. You can create scripts on the UNIX machine, but the importing and exporting of packages occurs on the NT system, where Process Scheduler is located. Of course, this means that you must have NT Process Scheduler to run the rule packager.

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: \\tl-nfs\dsapps\hcm890\datamover\

• UNIX system: /tl-nfs/dsapps/hcm890/datamover/

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

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, it also enables packager to define if elements are used in nonrule data, which is important when deleting elements and packaging nonrule data.

Although the system rebuilds the map when you create a rule package, we recommend that you rebuild the map when defining new elements, changing existing elements, or deleting 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.

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

Review this page for errors generated by the rebuild process.

Adding Records to an Element Map

The procedure of 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.

• 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 rule definitions to an element map.

• Add nonrules to an element map.

Page Used to Add Records to an Element Map

See Also

Pages Used to Define Element Relationships

Adding Rule Definitions to an Element Map

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

To add a rule definition to an element map:

1. Use PeopleTools to create a Structured Query Language (SQL) view for the record.

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

   The first line of the Select statement must read:

   SELECT PIN_NUM + 50000000

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 Element 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 PIN_NUM.

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

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

   7. If you selected Element Definition for the record type, identify the element types in the Applicable Element Types group box.

4. Click Rebuild Effdt Element Map to start the Rebuild process.

Important! After adding an element definition record to the element map, follow the rules for defining version relationships.

Example

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

Record definition for GP_PRORATION

SELECT PIN_NUM + 50000000
,EFFTDT
,EFF_STATUS
,ENTRY_TYPE ELEM
,PIN_NUMERATOR_NUM
,ENTRY_TYPE_ELEM2
,PIN_DENOMIN_NUM
,DENOM_USES_NUMER
,GP_VERSION
 FROM PS_GP_PRORATION

Adding Nonrules to an Element Map

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

To add a nonrule 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 d. You can select only PIN_NUM.

4. Click Rebuild Effdt Element Map to start the Rebuild process.

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.

Element maps include fields that contain PIN_NUM only. So, when looking at the map for an earnings 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.

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

This section provides overviews of how to move rules packages, define and create rule packages and discusses how to:

• Name rule packages.

• Select elements for a rule package.

• Select elements for a rule package by attribute.

• Modify the SQL Where clause for selection criteria.

• Display the elements in a rule package.

• Export packages of elements.

• View scripts.

Understanding How to Move Rule Packages

Rule packages include elements that are defined in records where PIN_NUM is the key. You can create a rule package and move its elements to a target database. This diagram displays the process:

Moving rule packages

To move rules from one database to another:

1. Define and create a rule package using the Create Rule Package component.

2. Export and import the rule package using PIA.

3. Compare and upgrade the elements in the package, using the Compare and Upgrade Package component.

Understanding How to Define and Create Rule Packages

Use the Create Rule Package component to define the selection criteria for the elements to include in your package and to specify the action the system takes for each element: upgrade (copy) the element to the target database or delete the element from the target database.

You can define two sets of selection criteria:

• Use the Create Rule Package - Packaging Criteria 1 page to select elements by name.

• Use the Create Rule Package - Packaging Criteria 2 page to select elements by attribute (element type, owner, used by, class, category, country).

  You can modify the SQL code that the system uses when it selects elements that meet your Criteria 2 parameters.

If you complete both pages, the system selects all elements that meet the criteria defined on the Create Rule Package - Packaging Criteria 1 page or the Create Rule Package - Packaging Criteria 2 page.

You can start the package creation process from either page.

To define and create the rule package using the Create Rule Package component:

1. Define the selection criteria for the elements to move and delete from the target database.

2. Run the Create Package process.

3. View the package.

   Cancel any elements that you’re not moving.

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

Pages Used to Create and Export Rule Packages

Naming Rule Packages

Access the Package Definition page.

Enter a description of the package and comments.

Selecting Elements for a Rule Package

Access the Packaging Criteria 1 page.

Packaging Criteria - Element List

See Also

Base and Related Languages

Selecting Elements for a Rule Package by Attribute

Access the Packaging Criteria 2 page.

Attribute Set1

Select the Attribute Set1 tab.

Attribute Set2

Select the Attribute Set2 tab.

Used By	Select where elements are used. Values are All Countries (default) and Specific Country. If you select Specific Country, you must complete the Country field.
Country	Select the country's three-digit country code if you selected Specific Country in the Used By field.
Category	To select only elements assigned to a particular category, select the category. (You assign a category to an element on the Element Name page.)
Element Class	Select the element class to package. (You assign an element class to an element on the Element Name page.) Valid values are: Customary, Not Classified, Sample Data, Statutory, and System Data.
Where Clause Option	The system converts the criteria entered on the Create Rule Packages - Packaging Criteria 2 page into SQL before it creates the package. The Where Clause is editable. Values are: Use Default WHERE Clause: Tells the system to use the default Where clause and discard SQL code modifications. Change WHERE Clause: Makes the other fields on this page unavailable and puts the SQL code on the Where Clause page in edit mode. Warning! Selecting Use Default WHERE Clause deletes any SQL code you may have entered on the Where Clause page.
Show Where Clause	Displays the Where Clause page, where you can view and alter the SQL code for your selection criteria.

See Also

Selecting Elements for a Rule Package

Defining Security

Base and Related Languages

Modifying the SQL Where Clause for Selection Criteria

Access the Where Clause page.

Where Clause Option

Select Use Default WHERE Clause to use the default clause or revert to it after editing the SQL code. Changes to the Where clause are lost. Select Change WHERE Clause to activate the code on the lower part of the page for editing.

Where Clause

If you selected Use Default WHERE Clause for Where Clause Option, the system displays the Where clause of the SQL statement that it created based on the selection criteria that you entered for the package on the Packaging Criteria 2 page. If you selected Change Where Clause, you can edit the SQL. 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 save, the system checks for the use of PIN_NUM, and looks for SQL syntax errors. The fields on the Packaging Criteria 2 page become uneditable.

Displaying the Elements in a Rule Package

Access the Create Rule Package - View Package page.

Action	Displays the action applicable to the element in your package. Values are: Upgrade, Delete, and Info Only.
Upgrade	This check box is selected automatically to include the element in the package for export. Clear it to exclude the element from the export.

Exporting Packages of Elements

Access the Element Export page.

Once you have created a package, you can export it. 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 exported elements from elements that exist in the target database.

To export a rule package:

1. Select the package ID.

2. Select a location for the exported files.

   The location of scripts and data files should be accessible by both the source and target databases.

   When deleting items, the source database and target database can be the same.

3. Select Create Scripts. This button will create the Packagename_exp.dms and Packagename_imp.dms scripts.

4. Export the package from the source database, and import it into the target database.

Viewing Scripts

Access the Export Rule Package - View Scripts page.

Script Location	Displays the script location, which must be accessible by both the import and export databases. The setup must be specific in the Process Scheduler configuration file, and the drives must be mounted on both machines. If the configuration file has changed during the process, the log will not open.
View Package Script	Select the type of script that you want to view: export, import, or cleanup. The DataMover script appears. Make sure that these scripts are correct.

Viewing the Status of Packages

This section discusses how to view the status of a package.

Page Used to View the Status of Packages

Viewing the Status of a Package

Access the Package Status page.

The last completed process determines which process you can run next.

Comparing and Upgrading Rule Packages

This section provides an overview of rule packages comparisons and upgrades and discusses how to:

• Run the Compare Report.

• Start the compare and upgrade processes.

• Review for upgrade errors.

Understanding Rule Package Comparisons and Upgrades

After you have imported a rule package to the target database use the Compare and Upgrade Package component to compare and upgrade the rule package, as explained in this section.

To compare and upgrade a rule package:

1. Compare the packaged elements with the elements in the target database.

   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.

2. Resolve conflicts that are identified during the compare process.

   Conflicts 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 conflict.

3. Rerun the compare process after correcting errors or excluding elements from the package.

4. Run the upgrade process.

   The system renumbers the 50,000,000 rows added at import into the target database, renumbers the PINs that already exist in the database, renumbers the new elements by assigning new PIN numbers, and deletes rows according to the option chosen in the package. You can run this process only once.

Note. Before moving multiple elements simultaneously, it is recommended that you back up the target database before starting the process.

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! If you revise an element and export the element to another database that contains that element, the system overwrites that definition if you select the Upgrade check box on the Package Upgrade tab of the Package Elements page.

See Also

The Delete Functions

Running the Compare Report

You can create 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 to help you decide whether to upgrade a specific element or not.

The Compare Report creates a report displaying the affected elements and what the differences are between the elements in the Rule Package and the target database. The Compare Report can only be run at the same time as the compare process.

Note. Running the Compare Report will affect the performance of applying a rules package so you should run the Compare Report only when you need a field-by-field comparison of the rules package and the target database.

Compare Report Contents

The Compare Report consists of four columns. The columns and contents are described in the following table:

Elements Displayed in the Compare Report

The Compare Report contains details about each of these groups 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— The rows (records and fields) that will be changed are displayed. If a new row of data is being added, all fields appear.

• New Elements—For new elements that are contained in the Rule Package but not in the target database, the following GP_PIN fields are displayed: PIN Code (as the key field); PIN_NM; DESCR; COMMENTS. From Element Definition Records, only key fields are displayed.

• Deleted Elements—The following fields from GP_PIN are displayed: PIN Code (as the key field); PIN_NM; DESCR; COMMENTS. For rows that exist currently in the database, only key fields from Element Definition Records are displayed.

• Elements with no changes—No field information is displayed.

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.

For translate value fields, both the value itself and the corresponding translate value short description are displayed.

Pages Used to Compare and Upgrade Rule Packages

Starting the Compare and Upgrade Processes

Access the Package Elements page from the target database.

Use this page to start the Compare process, which compares the data from the source database to the target database. You also use this page to start the Upgrade process, which completes the upgrade, and to exclude elements from the upgrade process.

Package Upgrade

Select the Package Upgrade tab.

This page shows 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 any errors.

Before you can start the Upgrade process, at least one element must have passed the Compare process with no errors (warnings are acceptable). Click the Upgrade button to accept the changes.

Reviewing for Upgrade Errors

Access the Package Compare Audit page.

Parent	Displays the name of the erroneous 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.

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.

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.

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 Time and Labor and PeopleSoft Human Resources

Page Used to Rename Elements

Renaming an Element

Access the Element Rename page.

New PIN Code (new pay item name code)

Enter the new code. The old PIN code is replaced when you save.

Creating and Exporting Nonrule Packages

This section provides an overview of creating and exporting nonrule packages and discusses how to:

• Name nonrule packages.

• Define selection criteria.

• Modify the SQL Where clause for the selection criteria.

• Display elements of a nonrule package.

• Export and import nonrule packages.

• View nonrule package scripts.

Understanding How to Create and Export Nonrule Packages

Nonrule packages contain both nonelements and element information. Nonelements are those that belong to records where PIN_NUM is not the primary key.

Important! To create nonrule packages, you should be very familiar with the structure of the source database. To move a complete set of related data, you need to understand which records are related.

Before moving nonrule data, you must make sure that the elements that are associated with the nonrule 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.

Suppose that you’re moving calendar detail records. Calendar details are associated with the process number PIN (PIN_PRC_NUM), so you create a rule package that contains this element and move it to the target database. The system can assign a new PIN number to the element in the target database, if necessary. Now you can move the calendar details. You create a nonrule package, selecting GP_CAL_RUN_DTL as the record to move.

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 nonrule package:

1. Create the nonrule package.

   Use the Create Non-Rule Package component to:

   • 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 nonrule package, and import the element data.

   The system exports the nonrule data and the element information contained in the nonrules and imports the element information only.

Pages Used to Create and Export Nonrule Packages

Naming Nonrule Packages

Access the Create Non-Rule Package - Package Definition page.

Enter a description of the package and comments.

Defining Selection Criteria

Access the Create Non-Rule Package - Package Criteria page.

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 before creating the package. The Where clause is editable. Values are: Change WHERE Clause: Makes all the fields on package criteria page unavailable and puts the SQL code that appears on the Where Clause page in edit mode. Use Default WHERE Clause: Tells the system to use the default Where clause and discard SQL code modifications on package criteria page.

Data Selection

Use these fields 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.

Record	Displays the record from which fields are selected.
Where Clause Option	Select a Where clause option. Values are: Change WHERE Clause: Select to enable editing SQL code on the lower part of the page for editing. Use Default WHERE Clause: Select to use the default clause or revert to it after editing the SQL code. Changes that you’ve made to the Where clause are lost.
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. 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 Nonrule Package

Access the Create Non-Rule Package - Package Elements page.

Note. This display page lists the elements that are included in the package as informational items. It doesn’t show the nonelement items.

Exporting and Importing Nonrule Packages

Access the Export Non-Rule Package - Package Records page.

Record	Displays the name of the record 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 (XXX_elements_imp.dms, XXX_elements_exp.dms, XXX_records_exp.dms and XXX_record_imp.dms, where XXX = name of package) for the non-rule package. The scripts will be created in the script location you specify.
Export	Click, once you have selected the location.

Viewing Nonrule Package Scripts

Access the Export Non-Rule Package - View Scripts page.

Comparing and Upgrading Nonrule Packages

This section provides and overview of comparing and upgrading nonrule packages and discusses how to:

• Import nonrule element information.

• Compare nonrule packages with a target database.

• Import nonrule records.

• Upgrade nonrule packages.

Understanding How to Compare and Upgrade Nonrule Packages

After exporting a nonrule package:

1. Import the nonrule elements.

   This pertains to information about the elements, not the elements themselves.

2. Compare and upgrade the elements in the package to ensure that the rules are in the target database.

   Use the Compare Non-Rule Package component to:

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

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

3. Use the Import Non-Rule Records component to import the nonrule records.

4. Use the Upgrade Non-Rule Package component to complete the upgrade.

Pages Used to Compare and Upgrade Nonrule Packages

Importing Nonrule Element Information

Access the Import Non-Rule Elements - Package Records page.

After reviewing the results of the Compare process and moving any missing elements into the target database, you can import the nonrule records into the target database.

Comparing Nonrule Packages with a Target Database

Access the Compare Non-Rule Package - Package Elements page.

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 nonrule 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 Nonrule Records

Access the Import Non-Rule Records - Package Records page.

Click Record Import to import the records.

Upgrading Nonrule Packages

Access the Upgrade Non-Rule Package - Package Records page.

The final step is to renumber the elements on the nonrule 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.

Copying Packages

This section discusses how to:

• Copy a rule package and its selection criteria.

• Copy a nonrule 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.

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 Nonrule Package and Its Selection Criteria

Access the Copy Non-Rule Package page.

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 rules by version:

1. Use the Create Package by Version component to:

   • Define the selection criteria for elements being packaged.

   • Create the package.

   • View the package to confirm that it includes the intended data, including effective-dated data, as applicable.

2. Follow the procedures presented earlier in this chapter for exporting rule packages.

3. Follow the procedures presented earlier in this chapter for comparing and upgrading rule packages.

See Also

Creating and Exporting Rule Packages

Comparing and Upgrading Rule Packages

Defining Element Names

Pages Used to Stamp and Package Elements by Version

Stamping Elements with a New Version Number

Access the Version Stamping page.

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 in element definition records (records with a primary key of PIN_NUM).

Defining Version Relationships

Access the Define Version Relationships page.

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 earnings 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 earnings accumulator PIN_NUM is contained as PIN_MBR_NUM in the earnings component buffer and PIN_NUM itself contains the earnings 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.

Identifying Elements to Package

Access the Packaging Criteria - Version page.

Language	Display-only. Indicates that base language information associated with the selected elements is to be copied to the target database. See Base and Related Languages.
Used By	Select where elements are used. Values are All Countries (default) and Specific Country. If you select Specific Country, you must complete the Country field.
Version	Select the version of elements to include in the package. You can select multiple versions if they are from the same country.
Create Package	Click this button to start the batch process that creates the package.

Viewing Version Details

Access the View Version Details page.

This page provides information about the elements that have been packaged by version, including effective dates.