Understanding PeopleSoft Environment Customizations

The PeopleSoft DPK setup script allows setup of a PeopleSoft environment quickly using the default data from the packaged Hiera YAML files. This section gives examples of ways to use the YAML files for customization.

Always use the documented procedures to make changes to your environment. Doing so will allow you to retain your customizations when removing a deployment before deploying a new patch or version.

Note:

You can use the customizations in this chapter whether you use the DPK script interactively or in silent mode. This list notes a few places where using the DPK customization is different for interactive or silent mode.

Use these guidelines when customizing your environment:

(Interactive mode) Do not change any of the original delivered YAML files.

This practice enables you to retain your customizations after deploying a new patch or update.

When you deploy the PeopleSoft DPKs, the YAML files associated with the deployment are installed in the following location. Use these files as the basis for the psft_customizations.yaml file.
- BASE_DIR/dpk/puppet/production/data/defaults.yaml
- BASE_DIR/dpk/puppet/production/data/psft_configuration.yaml
- BASE_DIR/dpk/puppet/production/data/psft_deployment.yaml
- BASE_DIR/dpk/puppet/production/data/psft_unix_system.yaml
(Silent mode) Do not change any of the original delivered YAML files.

This practice enables you to retain your customizations after deploying a new patch or update.

Use the YAML files in the following location as the basis for the customizations file used in silent installation:
- DPK_INSTALL/setup/puppet/production/data/defaults.yaml
- DPK_INSTALL/setup/puppet/production/data/psft_configuration.yaml
- DPK_INSTALL/setup/puppet/production/data/psft_deployment.yaml
- DPK_INSTALL/setup/puppet/production/data/psft_unix_system.yaml
(Interactive mode) Start with the DPK setup script and choose not to continue with the default initialization.

Answer no at the prompt “Do you want to continue with the default initialization process? [y|n]:” to exit the script and bypass the default initialization process.

To set up a customized PeopleSoft environment, use the DPK setup script for the first portion of the process, that is, to automate the tasks of extracting the DPK zip files, installing Puppet (if not installed), and copying the Puppet modules and Hiera data YAML files from the DPK into the location where Puppet looks for these files during the orchestration process. When you exit the script, it displays instructions on how to proceed to complete the initialization.
Always create a psft_customizations.yaml file to use for modified parameters.
- Never modify the delivered YAML files. Instead, by copying the parameters that you want to modify into the psft_customizations.yaml file you are able to save the customization.
- Copy only the section of the delivered YAML file that includes the parameters that you need to change, as directed by the samples in this documentation. Depending upon the specific type of customization, you may need to copy a single line, or an entire block of text, so be sure to check this documentation.
- The DPK setup script processes the psft_customizations.yaml file before the generated YAML files, so that the values in psft_customizations.yaml override the values in psft_configuration.yaml, psft_deployment.yaml, and psft_unix_system.yaml.
- (Interactive mode) Note that the file must be named “psft_customizations.yaml” for interactive mode deployment. Be sure to use the correct spelling.
- (Silent mode) You can name the customization YAML file whatever you like for the silent mode installation.
Verify the content of the delivered YAML files with each release.

The YAML files may have changed since this document was published. It is important that you copy the appropriate section of code from the YAML files you install with each new deployment, and use it as the basis for your psft_customizations.yaml file (or the silent mode customization YAML file).
Do not create new parameters for psft_customizations.yaml (or the silent mode customization YAML file).

The deployment recognizes only those parameters in the delivered YAML files or given in the product documentation.
Use a single psft_customizations.yaml file (or silent mode customization YAML file).

You can copy the necessary sections from more than one of the delivered YAML files and include them in a single psft_customizations.yaml file. Again, copy only those sections with the parameters you want to change.
Use the same psft_customizations.yaml file (or silent mode customization YAML file) for all deployments on a given base folder.

This applies to a use case in which you carry out more than one deployment on the same BASE_DIR. For example, you first install PS_HOME only, and use a psft_customizations.yaml file to specify a non-default PS_HOME location. Then you later do a second deployment, with the same BASE_DIR, to install mid-tier components, and you want to customize the location of Oracle WebLogic. In this case, use the first psft_customizations.yaml file, including the non-default PS_HOME, append the customization for the Oracle WebLogic location, and use it for the second deployment.
Include the remove: false attribute to retain your customizations through the clean-up process.

To ensure that your customizations are not removed when removing a deployed environment:
- For each segment of customization parameters in the psft_customizations.yaml file (or silent mode customization YAML file), include the remove: false attribute at the end of the segment.
- If you remove the environment manually (using the psft_puppet_apply script), set the ensure attribute to absent in default.yaml.
  
  If you remove the environment using the --cleanup option for the PeopleSoft DPK setup script, you do not need to set the attribute first because it is part of the script process.
- Remove the environment using the --cleanup option for the PeopleSoft DPK setup script, as described in this documentation.
  
  See "Installing the PeopleSoft Homes," Removing a Deployed PeopleSoft Environment.
Copy an entire section containing the parameter to be modified, and be sure to retain the indentation from the delivered YAML file.

The hierarchy and alignment of the YAML files are very important to the correct operation. In addition to the brief overview given here, review the information in the appendix “Using the Puppet Hiera YAML Files for Customization.”
- The YAML files include scalar type and collection type parameters.
  
  Scalar parameters are of the form key: value; for example:
```
db_platform: ORACLE
```
  Collection type parameters include a parameter name followed by one or more indented lists of key:value pairs. In this case, the value of the collection parameter is defined by the indented list of values; for example:
```
ps_home:
  db_type:    "%{lookup('db_platform')}"
  unicode_db: "%{lookup('unicode_db')}"
  location:   "%{lookup('ps_home_location')}"
```
- When you locate a parameter that you want to modify, be sure to locate the section heading that begins at the first column of the YAML file. This ensures that the deployment operation modifies the correct parameter.
- Be sure to retain the indentation from the delivered YAML file.
  
  Typically there is an indentation of 2 or 3 spaces for each successive subsection. This is necessary in order for the parameters to be correctly interpreted.
  
  Note:
  
  Be sure when copying and pasting that you retain the indentation. Depending upon the authoring or editing tools you use, the desired indentation may be lost when you copy and paste. It is a good idea to double-check the final psft_customizations.yaml file (or silent mode customization YAML file), especially for the special cases where you copy a sample from this documentation.
- When copying and modifying collection type parameters, use only spaces, not tabs, to indent the subsections.
(Interactive mode) Use the encrypted passwords from the generated YAML files.

The DPK setup script encrypts user-supplied passwords and includes them in the generated YAML files. If you copy a section of a YAML file with encrypted passwords, do not replace or remove the encrypted text.

The encrypted passwords are quite long. Be sure to copy the entire string, without adding spaces, tabs, or line feeds.

Note:

For the majority of the customizations described in this documentation, you copy the encrypted passwords from the generated YAML files. If that is not possible, see the appendix "Encrypting Passwords for Customization Files."
(Silent mode) Enter passwords in clear text.

When creating the psft_customizations.yaml file for silent mode installation, enter the passwords in clear text. Do not enter encrypted passwords.
Replace the entire attribute string.

The parameters in the delivered YAML files are written with Hiera lookup interpolation functions that act as variables. To modify each parameter, you must replace the entire string after the colon, and enclose your new value in double quotes. For example, in the psft_deployment.yaml file, the location for an Oracle WebLogic installation is given by the following parameters:
```
weblogic_location: "%{lookup('pt_location')}/bea"
weblogic:
  location:  "%{lookup('weblogic_location')}"
```
The second lookup function refers to the first. When pt_location is set as C:/psft, Oracle WebLogic will be installed in C:/psft/bea. To change this, remove both strings of text "%{lookup('pt_location')}/bea" and "%{lookup('weblogic_location')}", and replace them with the full path to the new location. Retain the two-space indentation, and use a forward slash (/) for paths on both Microsoft Windows and Linux; for example:

On Microsoft Windows:
```
weblogic_location:  "C:/psft/weblogic"
weblogic:
  location: "C:/psft/weblogic"
```
On Linux:
```
weblogic_location:  "/opt/bea/weblogic"
weblogic:
  location: "/opt/bea/weblogic"
```
Do not use the customizations to set up a non-Unicode environment if you are deploying the PeopleSoft Update Image DPKs for use with PeopleSoft Update Manager.

The environments for the PeopleSoft Update Images are required to be Unicode.
Verify existing installations before beginning deployment.

You have the option to use existing installations, for example for Oracle WebLogic, but you have the responsibility to ensure that the installation is supported, complete, and correct. The deployment script does not verify whether an installation directory includes a valid, working installation.

See Preparing the Customization File for Component Software Locations.
Set the Puppet environment if necessary.

The process to complete the initialization using the customizations, as described in the section Completing the Customized Deployment, runs the psft_puppet_apply script, which sets necessary environment variables and runs the puppet apply command. If you choose to use the puppet apply command directly rather than the script, you may get a message saying that “puppet” is not recognized. This message may indicate that the Puppet software is not included in your system’s path. In that case, you can use the commands given here to set the Puppet environment. You should also set the Puppet environment if you need to run puppet apply after the script execution has ended with an error.

Note:

Oracle recommends that you use the delivered psft_puppet_apply script, not the puppet apply command.

You must also set the Puppet environment before you encrypt passwords to include in the psft_customizations.yaml file for a customized deployment on Linux.

See "Encrypting Passwords for Customization Files."

On Microsoft Windows, to set the Puppet environment, run this command
```
"BASE_DIR\psft_puppet_agent\bin\puppet_shell.bat"
```
To set the environment variables on Linux, use pspuppet.sh along with manual commands. The pspuppet.sh script is installed by the DPK setup script in BASE_DIR/psft_puppet_agent, and will set the Puppet PATH and LIBRARY environment variables. Source the script by entering the following command:
```
. BASE_DIR/psft_puppet_agent/pspuppet.sh
```
The dot, or period (“.”) at the beginning of the command is a source operator that ensures that the script commands persist in the shell environment that you are deploying from. After sourcing the script, continue with the deployment by running the puppet apply command.

On Linux, first specify the following environment variables:
```
export PUPPET_DIR=BASE_DIR/psft_puppet_agent
export PUPPET_BIN=${PUPPET_DIR}/bin
export PUPPET_LIB=${PUPPET_DIR}/lib
```
Next, source pspuppet.sh to set the Puppet PATH and LIBRARY environment variables:
```
. BASE_DIR/psft_puppet_agent/pspuppet.sh
```
Use only the predefined web profiles.

PeopleSoft PeopleTools includes four predefined web profiles — DEV, KIOSK, PROD, and TEST. In the delivered YAML file psft_configuration.yaml, the web profile is specified by the scalar parameter pia_webprofile_name: PROD. If you want to specify a different value using psft_customizations.yaml, be sure to use one of the four predefined values.

See PeopleTools: Portal Technology, "Configuring Web Profiles."
When using the customizations for a PeopleSoft web server domain, do not use the names PIA, PIA1, PIA2, or weblogic for the domain name.

The name of the WebLogic domain and the server and cluster names within it must be unique. The names PIA, PIA1, and PIA2 are reserved for use by the PeopleSoft system. The name weblogic is reserved for use by the Oracle WebLogic software. These restrictions apply to single server and multi-server domain creation.

See Preparing the Customization File for PeopleSoft Domain Definitions.

See PeopleTools: System and Server Administration, "WebLogic Domain Types."
To specify a non-default location for the Process Scheduler Report Repository, you must create the Report Repository directory before you begin the DPK installation.

The Report Repository is the designated server for reports that are generated from the PeopleSoft Process Scheduler Server. In the delivered YAML file psft_configuration.yaml, the Report Repository location is defined as a subdirectory of PS_CFG_HOME, as specified by this scalar parameter:
```
report_repository_dir: "%{lookup('ps_config_home')}/psreports"
```
To define a different location, create the directory first. Use the report_repository_dir parameter with the customized location in the psft_customizations.yaml file.

See PeopleTools: Process Scheduler, "PeopleSoft Process Scheduler Architecture."

See the task Setting Up Process Scheduler to Transfer Reports and Logs to the Report Repository in the PeopleSoft 9.2 Application Installation guide for your database platform. The installation guides are located on the pages for the PeopleSoft applications (such as PeopleSoft Human Capital Management) on Oracle Help Center.

See Oracle PeopleSoft Documentation Home, https://docs.oracle.com/en/applications/peoplesoft/index.html