Using Change Control

This chapter provides overviews of Change Control features, implementation considerations, and reporting change control information and discusses how to:

• Set up Change Control.

• Use projects.

• Use Change Control.

Understanding Change Control Features

The Change Control feature has three main functions to help you manage and track development. You can enable one or all of these functions to control how much access each user has to the Change Control commands.

This section discusses:

• Change Control locking

• Change Control history

• Change Control stamping

Change Control Locking

Change Control locking is keyed by PeopleSoft user IDs. When a definition is locked, it cannot be modified by anyone other than the user ID who locked it, and it can be unlocked only by that same user or by a Change Control administrator.

A locked definition is identified by:

• A small padlock icon above the definition in the project workspace (development view) of PeopleSoft Application Designer.

• The user ID of the person who locked the definition, which appears next to the name of the definition.

  Your user ID does not appear for definitions that you locked.

For example, the following icons seen in the project workspace display two locked and one unlocked record definitions:

Locked and unlocked record icons

The top record is unlocked; the middle record is locked by another user ID (PTDMO), and the bottom record (with no ID displayed) is locked by you, the current user.

Note. Standard Change Control locking is supported only for definitions that you can modify with PeopleSoft Application Designer. Other PeopleSoft definitions can be added to a project for upgrading, but they cannot be locked by developers. If you are a Change Control administrator, you can lock all upgradable database definitions, both PeopleSoft Application Designer development definitions and other types. However, for non-PeopleSoft Application Designer definitions, this action prevents unauthorized upgrading only, not unauthorized development.

Locking Projects

With Change Control, projects are treated like all other PeopleSoft Application Designer definitions: you must lock them before you can modify them. However, locking a project does not lock the definitions in the project, and modifying a definition in a project does not modify the project itself.

A project definition includes a name and a list of definitions. When you lock a project definition, other users cannot add or remove definitions from the project, and they cannot rename or delete the project. However, locking does not restrict access to the definitions that are named in the project definition. Likewise, modifying a definition has no affect on the definition of any project to which the definition might belong.

Note. PeopleSoft Application Designer provides an option to load the last open project on startup. If this option is enabled on your machine and Change Control locking is activated, you might receive an open in read-only mode? message at startup if you had not locked the project before or if someone else has the project locked. In either case, you can open the project in read-only mode. Remember, locking does not restrict your access to definitions in the project.

Locking Compared to Version Control

Change control locking is not the same as version control. With a version control system, you check out a copy of a definition and make your changes to the copy. After you check in the changed version, you can always undo your changes. This is not the case with change control locking.

Locking a definition prevents other users from modifying it. However, any changes that you save are written directly to the database, overlaying or replacing the existing definition. You cannot restore a previous version of a definition.

Locking and Upgrades

When preparing to upgrade a database, all development must cease in the source database to assure that the Compare process works with a static environment. It also assures that changes are not made to any definitions between the time that you set the upgrade defaults and the time that you copy the definitions.

You can freeze all development by using the Change Control Administrator dialog box to lock all database definitions. When the upgrade is done, use the same dialog box to unlock all definitions. However, be aware that this action permanently removes all previous lock settings from all definitions. Developers have no way of resetting their locks except by manually relocking. When you lock definitions in this way, it is not reflected in the Locked Objects dialog box or in the project workspace. If a developer has unsaved changes when you lock all definitions, the developer cannot save those changes.

For all of these reasons, you must inform developers that you plan to lock all definitions and you must give them time to save their changes, perhaps even to view the Locked Definitions dialog box and print the screen.

Locking definitions with the Change Control Administrator dialog box does not actually mark every definition as locked. Instead, it adds a single row at the top of the locking table. The presence of this row indicates to the system that full database locking is in effect, and it stores the user ID of the administrator who enabled the locking.

Full database locking also plays a role in the target database during the upgrade copy process. During a copy, the system always checks the locking status of the target database definitions to see if they are locked and by whom. If they were locked by a user ID other than the one performing the copy, then those definitions are not modified.

In major upgrades, checking the locking status of each definition before copying severely affects performance. To prevent this, use the Change Control Administrator dialog box to lock all target database definitions before copying. During the copy process, if the entire target database is locked, the system verifies that the user ID performing the copy process is the same user ID that locked the database. If these conditions are true, the system assumes that it was locked for the purpose of the upgrade and that it can safely copy all definitions without checking each one individually.

Note. When you copy a project, the system does not check the locking status of the definitions in the source database. However, you should keep your definitions locked until the copy is complete.

Change Control History

When Change Control history is enabled, you can enter comments about the modifications that you made to PeopleSoft Application Designer development definitions. History entries contain a common set of information, including who created the entry, when, and the type of action that is associated with the entry. For example, when a user locks a definition, a history entry is automatically created containing the user ID, the date and time, and an action value of Add. This entry can also contain a project name, incident ID, and comment.

Automated History Prompting

Although you can always insert history entries manually, in many situations PeopleSoft Application Designer automatically inserts history entries and prompts you for comments. In special circumstances, the system adds entries without a prompt. For example, an action history provides some idea of what has happened to a definition, even if no comments were entered. This table describes possible action entries:

History and Upgrades

Change Control history is not copied along with its associated definition during an upgrade. However, if history is enabled in the source database, then the history of each affected target definition is updated with a comment noting when the copy was performed and by whom.

This history updating occurs in the background for all target definitions that are affected by the copy process, even non-PeopleSoft Application Designer definitions with histories that you cannot update or view, regardless of whether Change Control history is enabled in the source database.

Change Control Stamping

Change Control stamping is always in effect, regardless of whether locking and history are also enabled. For every definition in the database, PeopleTools maintains a last updated stamp, which denotes the date and time of the last update and the user ID of the person who saved the definition. When a PeopleSoft application delivers a new database, all of the definitions are stamped with a PeopleSoft proprietary ID: PPLSOFT.

Stamping and Upgrades

Change Control stamping provides critical information during an upgrade comparison. Because the system tracks the user ID of whoever last changed each definition, you can easily identify your adaptations. (Any definition that is stamped with a user ID that is not the PeopleSoft proprietary ID is considered an adaptation.) Whether you made an adaptation before or after the last update is irrelevant; the adaptation is always identified as such.

During a comparison, definitions that you last modified are given a status of Custom Changed (if you have changed them since the compare date) or Custom Unchanged (if you have not changed them since the compare date). PeopleSoft-modified definitions are given a status of either Changed or Unchanged.

Understanding Implementation Considerations

When deciding how to implement Change Control, consider:

• The level of development control that you want to maintain.

• The amount of freedom that developers need.

• The security requirements of the site.

Understanding Change Control Information Reporting

Currently, no predefined reports for retrieving Change Control information are available. However, you can create your own reports by querying the Change Control tables.

The two tables that you can use for reporting are the Change Control History table (PSCHGCTLHIST) and the Change Control Locking table (PSCHGCTLLOCK). These tables have an almost identical column structure:

Structure of PSCHGCTLHIST

The main difference between these two tables is that PSCHGCTLHIST contains a CHGCTRL_ACTION field, while PSCHGCTLLOCK does not.

Each PeopleSoft definition in these tables is uniquely identified by numeric codes (DEFINITIONID columns) and names (DEFINITIONVALUE columns). The different DEFINITIONID and DEFINITIONVALUE column pairs correspond to the various definition key types and values for each kind of definition. You can see these definition keys when you view the upgrade definition window. For example, translate values have four keys—Field Name, Field Value, Language Code, and Effective Date, as in this example:

Viewing definition keys

In the Change Control tables, the row containing the first translate value in the preceding example has the following field values:

When reporting on a particular definition type, you want to retrieve definition values, but you must limit the query by using the definition IDs for the definition type. The following tables list all of the upgradable definition types, their corresponding definition ID codes, and the type of value that each ID represents (in parentheses).

PeopleTools Definition Types

This table lists PeopleTools definition types and their definition IDs:

PeopleCode Definition Types

This table lists PeopleCode definition types and their definition IDs:

Change Control Supported Definition Types

These are the supported definition types for change control:

• Activity

• Application Engine Program

• Approval Rule Set

• Business Interlink

• Business Process

• Component

• Component Interface

• Field

• File Layout

• HTML

• Image

• Menu

• Message

• Message Channel

• Mobile Page

• Problem Type

• Page

• Project

• Record

• SQL

• Style Sheet

When reporting on Change Control history, consider one other field: CHGCTRL_ACTION. This field stores the one-letter code for the various actions that Change Control history tracks:

• A (Add)

• C (Copy)

• D (Delete)

• I (Informational)

• L (Lock)

• R (Rename)

• U (Unlock)

Here's an example of a SQL query to report on all deleted definitions:

select oprid, definitionvalue1, definitionvalue2, 
definitionvalue3, definitionvalue4, dttm­_stamp, projectname, 
incident_id, descrlong 
from pschgctlhist
  where chgctrl_action = 'D'
  order by oprid, definitionvalue1

Note. Full history tracking is supported only for PeopleSoft Application Designer definitions: business processes, business process maps, fields, menus, panels, panel groups, projects, and records. Other definition types have history entries only when the CHGCTL_ACTION field value is C, and only if they have been upgraded.

Setting Up Change Control

This section provides an overview of Change Control security and discusses how to:

• Appoint a Change Control administrator.

• Enable or disable Change Control.

Understanding Change Control Security

Using the Security component, you can assign users one of three Change Control access levels, depending on how much authority you want them to have. This table describes the available access levels:

If Change Control locking is disabled, these access levels have no security value. If history is disabled, users with developer and supervisor access can still view the History dialog box, but users with restricted access cannot.

Remember that Change Control is based on user ID. If developers all share the same user ID, then Change Control offers no advantage in control because each developer can modify definitions that are locked by others.

Appointing a Change Control Administrator

Appoint Change Control administrators by giving certain users supervisor-level access to Change Control. When users have this access level, they can enable and disable Change Control.

See Setting PeopleTools Permissions.

Enabling or Disabling Change Control

To enable or disable Change Control:

1. In PeopleSoft Application Designer, select Tools, Change Control, Administrator.

   The Change Control Administrator dialog box appears.

2. Specify the System Wide Options and access control:

   Use change control locking	Select to require that PeopleSoft Application Designer definitions be locked before they can be modified.
   Use change control history	Select to enable PeopleSoft Application Designer developers to insert comments about open definitions. If both Use change control locking and Use change control history check boxes are selected, developers are prompted for comments when locking and unlocking definitions. Note. Because these are system-wide settings, if you change them all users must log off and on again for the changes to take effect.
   Lock all definitions	Select or deselect to lock or unlock all definitions in the database. Usually, you lock all definitions only before a major upgrade, because it permanently removes all individual developer locks.

Using Projects

This section provides an overview of projects and discusses how to:

• Use multiple databases for development.

• Use distributed development environments.

Understanding Projects

You can use all levels of Change Control with or without also using projects. If you decide not to use projects, you rely on the Locked Objects dialog box, rather than the project workspace, to identify locked definitions. The dialog box provides a better overall view of locking status because it shows all of the PeopleSoft Application Designer definitions in the database, not just those in the current project.

Use projects to track the definitions that are changed as part of a change or feature request. This set of definitions is commonly referred to as the change set. The Options dialog box has an option to insert a definition into a project when it is modified and saved. If you start with an empty project, this option provides an easy way of tracking the change set for this incident. When the change request is completed, the project contains everything that is associated with the change. You should also use the Comments field in the Project Properties dialog box to list any external definitions, like COBOL or Structured Query Report (SQR) modules, that must be migrated with this change.

Using Multiple Databases for Development

Managing change in a single database environment is straightforward, but very few PeopleSoft users operate in a single database environment. The classic development model uses three databases: development, test, and production. You apply all changes to the development database. After you unit-test the change, migrate the change set to the test database, where it goes through more rigorous testing. Usually, you would run one or more regression test suites to ensure that you resolve the issue that you intended to resolve with no unwelcome side effects. Finally, that change set is migrated into the production database. If you find a problem at any stage in the process, the incident is sent back to development and the process begins again.

This model assumes that the development database is the master database. You can use the Change Control locking feature to lock down the modules on which you and other developers are working. When developers complete the changes in the development database, they notify the Change Control administrator and use the upgrade copy facility to copy the change set into the test environment. As long as you use the technique that is described previously in this section, the project should contain the entire change set. The system tracks all of the documentation for the change in the development database. The only information that appears in the test and production databases is a history line indicating it was copied. Definitions move only in one direction in this model: from development to test, then from test to production.

Note. The only case in which you can copy a definition back to development from either test or production is if a problem must be recreated and another change was already made to the affected definition. Do this with extreme care because upgrade copies are destructive and cannot be undone if you discover that you overlaid another developer's change. For this reason, you should apply changes directly to test or production databases only rarely.

Note. This Change Control model is just one that you can use. We provide it to give you an idea of how you can implement Change Control in your environment. While you do not need to follow this model exactly, you should implement a Change Control model that enables you to track changes to the system and prevent developers from overwriting each other’s changes.

Using Distributed Development Environments

You should use a master development database even if each development team works on its own copy of the database. Developers should lock down the definitions on which they intend to work in the master development database, and then copy those modules to their private databases. This method ensures that no other developer makes a change to those definitions while they are checked out.

When a developer is ready to copy changes back to the master development database, you check the Change Control history of the locked definitions in the master development database. Do this before using upgrade copy to migrate them back, just in case a Change Control administrator has overridden a lock and made a change while the definitions were checked out.

Note. Change Control administrators should always notify the developer who has a lock on a definition before they override to avoid unexpected surprises later.

Using Change Control

This section discusses how to:

• Lock and unlock definitions.

• View locked definitions.

• Insert comments.

• Delete page definitions.

• View Change Control history.

Locking and Unlocking Definitions

You can lock and unlock definitions manually. You can also have PeopleSoft Application Designer lock unlocked definitions for you each time that you open them.

You must have developer or supervisor access to Change Control to lock and unlock definitions. If you have supervisor access, you can also lock all definitions at once, which can be helpful when performing upgrades to ensure that definitions are not modified in the middle of the process.

This section discusses how to:

• Lock or unlock an unopened definition in the current project.

• Unlock an unopened definition that is not in the current project.

• Lock or unlock an open definition.

• Lock definitions automatically when you open them.

• Lock or unlock all definitions at once.

Locking or Unlocking an Unopened Definition in the Current Project

To lock or unlock an unopened definition in the current project:

1. In the project workspace, select the Development tab at the base of the workspace window to activate the development view.

2. Select the definitions that you want to lock or unlock.

3. Right-click any of the selected definitions and select Lock Definition or Unlock Definition.

Unlocking an Unopened Definition Not in the Current Project

To unlock an unopened definition that is not in the current project:

1. Select Tools, Change Control, View Locked Definitions.

   The Locked Definitions dialog box appears.

   Note. The View Locked Definitions menu item is not available if you have restricted access to Change Control.

2. Select the definition type and user.

   You can view all locked definitions of the specified type by selecting all from the User drop-down list box.

3. Select the definitions to unlock.

4. Right-click any selected definition and select Unlock Definition.

   If Change Control history is enabled, the system will prompt you for comments.

Locking or Unlocking an Open Definition

To lock or unlock an open definition:

1. Activate the definition.

2. Select Tools, Change Control, and then select either Lock Definition or Unlock Definition.

Locking Definitions Automatically When You Open Them

To lock definitions automatically when you open them:

1. Select Tools, Options, Change Control.

2. Select Lock definition when it is opened.

   Now, whenever you open a definition it is locked automatically, unless you have only restricted access to Change Control. In this case, the system will notify you that you have restricted access and will ask whether you want to open the definition in read-only mode.

   Note. Like all settings in the Application Designer Options dialog box, this setting controls the behavior on your workstation only. Also, definitions cannot be unlocked automatically; you must always unlock them manually.

Locking or Unlocking All Definitions at Once

To lock or unlock all definitions at once:

1. Select Tools, Change Control, Administrator.

   The Change Control Administrator dialog box appears.

2. Select Lock all definitions to lock all definitions or deselect it to unlock all definitions.

   Locking all definitions applies a database-wide lock that is tagged with your user ID.

   Warning! Selecting this check box removes individual locks from all database definitions. You should proceed with this step only if you have informed all of your developers and given them an opportunity to save any unsaved work.

3. Click OK.

   If you are locking all definitions, the system warns you that this action permanently cancels existing locks. Click Yes.

Viewing Locked Definitions

At times you may want to see a definition even if it is locked.

To view locked definitions:

1. Select Tools, Change Control, View Locked Definitions.

   The Locked Definitions dialog box appears.

2. Select the user whose locked definitions you want to view.

3. Select the type to display.

   You can view only one definition type at a time. You can also unlock definitions in this dialog box.

Inserting Comments

When Change Control history is enabled, you can insert comments about an open definition at any time. To help ensure that you insert new comments with each modification, you can instruct PeopleSoft Application Designer to prompt you for a comment every time you save a definition, every time you lock or unlock a definition, or both.

This section discusses how to:

• Insert a comment for an unopened definition in the current project.

• Insert a comment for an open definition.

• Enable a prompt for comments when saving a definition.

Inserting a Comment for an Unopened Definition in the Current Project

To insert a comment for an unopened definition in the current project:

1. In the project workspace, select the Development tab at the base of the workspace window to activate the development view.

2. Select the definition for which you want to insert comments.

   You cannot insert comments for more than one definition at a time.

3. Right-click the selected definition and select Insert Comment.

   The Insert Comment dialog box appears.

4. Enter the necessary information:

   Project	Displays the name of the current project by default, but you can delete or replace this value.
   Incident ID	Enter the incident identification to which your development corresponds.
   Comments	Enter information about why and how you are modifying the definition.

   If you click OK, the information is inserted into the definition history and the dialog box closes. If you click Apply, your comments are inserted, but the dialog box remains open. You can then enter comments for another history entry. When you click OK or Apply, the new comments are inserted as a new history entry; they do not replace the previous entry.

Inserting a Comment for an Open Definition

To insert a comment for an open definition:

1. Use the list in the Window menu to navigate to the definition.

2. Select Tools, Change Control, Insert Comment.

3. Enter the name of the project and incident ID.

4. Enter your comments.

5. Click OK or Apply.

Enabling a Prompt for Comments When Saving a Definition

To be prompted for comments when saving a definition:

1. Select Tools, Options, Change Control.

   The Change Control page appears.

2. Select Prompt for comments when definition is saved.

   Whenever you save a definition, the system prompts you to insert history comments.

   Note. This setting affects the behavior on your workstation only. One possible drawback to using this setting is that a definition might be saved many times as part of a single change, and you will be prompted for comments at every save.

Deleting Page Definitions

When deleting page definitions with Change Control enabled, the system presents this message:

Are you sure you want to delete <definition name> definition? You are presented with Yes and No options. If you click the Yes button and the page is locked, then the system will delete the page. If you click the Yes button and the page is not locked, then this message box appears:

You must lock <definition name> before you may rename or delete it.

You must lock the page before you are allowed to delete it.

If you click the No button, then the system does not delete the definition.

Note. If the definition is a base language page, then the system also deletes all non-base language pages. If the definition is a non-base language page, then the system deletes only the selected non-base language page.

If you select multiple pages to delete but the base language page is not included in the selection,  then the system prompts you for lock comments for each selected non-base language page. If you select multiple pages to delete and the base language page is included in the selection, then the system prompts you for lock comments for only the base language page.

See Also

Designing Global-Ready Pages

Viewing Change Control History

For every PeopleSoft Application Designer development definition in the database, you can view its Change Control history.

To view Change Control history:

1. Select Tools, Change Control, View History.

   The History dialog box appears.

2. Select a definition type and name.

   The Definition Name list box contains only the names of PeopleSoft Application Designer definitions that have at least one history entry. Click the Refresh button to ensure that you are viewing the most recent listing of locked definitions.

   The history table contains these columns:

   Date	Displays when each entry was added.
   User	Displays who added an entry.
   Action	Displays why a comment was entered. Five of these Action types—Lock, Informational, Unlock, Rename, and Delete—represent actions that you perform in PeopleSoft Application Designer and for which the system prompts for comments.
   Add	Denotes an automatic history entry that PeopleTools inserts when a new definition is created. In this case, and whenever the system performs a background lock or unlock, the system does not prompt you for comments. The Comment column contains the text System Generated. Note. PeopleSoft Application Designer performs automatic locks and unlocks under certain situations. For example, when you rename a locked definition, that definition must be unlocked before it is renamed and then relocked afterward. Likewise, when you delete a locked definition, the definition is automatically unlocked following the deletion. The system does not prompt you for comments during any of these unlock or relock actions, but it adds corresponding history entries automatically.
   Copy	The system adds this type of history entry automatically when a definition is copied into the current database. In this case, the Project value is the name of the copied project in the source database, and no comments are added.
   Project, Incident ID, and Comment	Displays the project name, incident ID, and relevant comments.

3. Double-click a row in the grid to open a history entry, if necessary.

   The History Details dialog box appears. This dialog box is a read-only version of the Insert Comments dialog box. You cannot update the information that appears in this dialog box.