Generating Form Letters for PeopleSoft Human Resources

These topics provide an overview of form letters for PeopleSoft Human Resources and discuss how to:

Generate form letters with PeopleSoft Process Scheduler.
Use naming conventions in form letter files.
Set up form letters.
Prepare to print form letters.
Adapt form letters.
Troubleshoot form letters.

Note: These instructions show you how to use templates to create form letters for PeopleSoft Human Resources. To create form letters for other PeopleSoft HCM applications, you follow a different method. Please follow the appropriate instructions to create your form letters.

PeopleSoft delivers a set of sample letters for use with the following:

PeopleSoft Human Resources: Administer Training
PeopleSoft Human Resources: Manage Labor Administration

The form letter processes search the database for records that have been tagged with specific letter codes. For example, when you enroll an employee in a training course using the Administer Training business process, you can add a letter code to the employee record that identifies the type of letter required. When you later run the training letter report, the system searches for records with the letter codes for training letters.

The form letter processes use Word to generate the letters based on data extracted from the PeopleSoft database.

To generate form letters for PeopleSoft Human Resources:

Create letter codes by using the Standard Letter Table page (STANDARD_LTR_TABLE).
Letter codes represent form letters and are used to link a record to the required letter.
Tag people's records with the appropriate letter code in the PeopleSoft Human Resources database.

Enter a letter code into the records of applicants, employees, contingent workers, or people of interest to flag the record when it's time to generate a form letter.

For example, when you enroll or add students to waiting lists for training courses, the system inserts letter codes into employee, contingent worker, and person of interest records.
Generate form letters by running a report that runs the following processes:
1. An SQR data extract process.
2. A WinWord WORDINIT process.
3. The PSMERGE Application Engine process.
The final step is completed by the Distribution Agent that moves the letter files to the Report Repository.
Send training letters by email.
This step is for the training letters only. The system also emails training letters to students if their email addresses are in their person records.

Note: You must configure SMTP and activate Workflow to automatically send training letters by email.

See PeopleTools System and Server Administration
Print the letters by using Microsoft Word.
The system creates the form letters in a temporary directory on the web server, putting all letters of the same type in one file.

The distributed architecture of the PeopleSoft Human Resources system enables you to access the application server far from local machines therefore the system doesn't print letters to a default printer. Instead, you select where you want to print the letters by using standard Microsoft Word print options.

Generating form letters for PeopleSoft Human Resources with PeopleSoft Process Scheduler

Step 1: SQR Data Extract Process

The SQR data extract process:

Identifies records in the database with the appropriate letter codes (and no print date).
Extracts data from these tagged records.
Updates the Print Date field in the tagged records.
Creates a data extract file (with an .ltr extension) that contains the data for each letter.

For example, the file containing data for offer letters is ltrof1.ltr, where of1 represents offer letter, and .ltr represents letter.

The SQR process sends its output to the log/output directory defined for SQR reports. Define the log/output directory in the Process Scheduler configuration file.

Step 2: WORDINIT WinWord Process

The WORDINIT WinWord process is an initialization process. Its purpose is to ensure that the PSMERGE application engine process can retrieve the location of:

The executable file for Microsoft Word, winword.exe.
The PS_HOME directory that contains the letter templates.

The WORDINIT process runs winword.exe and a dummy macro called PSINIT which opens and closes the psmerge.doc file without creating any output. By including the WORDINIT WinWord process in the job definition, the Process Scheduler ensures that it has loaded the location of the winword.exe file into PSPRCSPARMS.

The PSMERGE application engine process uses this information to call Microsoft Word.

Step 3: PSMERGE Application Engine Process

The PSMERGE Application Engine process completes the merge of the data extract files and the Word templates. It:

Retrieves the locations of the data extract files, winword.exe and the PS_HOME Winword directory.
Creates a file called param.txt in the log/output directory.
This file contains the locations of the files and a list of files to be merged.
Calls Microsoft Word to carry out the merge.
Microsoft Word:
- Opens the form letter templates that correspond to the data extract files.
- Merges the appropriate extract file data into the field codes for each template.
  For example, the offer letters template is ltrof1.doc and it includes field codes for names, addresses, and offer amounts.
- Inserts the data from the appropriate .ltr file into the template field codes.
  For example, it inserts the data from the ltrof1.ltr extract file into the ltrof1.doc template.
- Places the resulting letters in the log/output directory.

Before you adapt existing form letters or create new ones, you should be familiar with the naming conventions for each element of the process. Use the same naming conventions for the new form letter components that you create.

These topics discuss how to:

Use letter codes.
Use data extract files and corresponding Word letter templates.

Using Letter Codes

You create letter codes in the Standard Letter Table component. Use letter codes to indicate what kind of letter is required for a particular record. The standard letter codes that are delivered by PeopleSoft for use with the sample letters are listed below.

Using Data Extract Files and Corresponding Word Letter Templates

The extension .ltr represents form letters and the extension .doc is the normal templates extension. Every letter code for which you generate form letters must have a corresponding data extract file and a template with the same name of the data extract file:

Object	Example
New letter code	xyz
Data extract file name	aaaxyz.ltr
Template name	aaaxyz.doc

The letter codes and their associated data extract files and Word templates include:

Training letters

Purpose of Letter	Letter Code	Data Extract File	Word Letter Template
Confirmation of session enrollment	CON	ltrcon.ltr	ltrcon.doc
Rescheduling of course session	RSC	ltrrsc.ltr	ltrrsc.doc
Cancellation of course session	CAN	ltrcan.ltr	ltrcan.doc

Note: The Standard Letter Table also contains two codes, WTC and WTS, that are used in Administer Training for students on waiting lists. However, these codes don't have macros or sample letters associated with them.

Labor Administration letters

Purpose of Letter	Letter Code	Data Extract File	Word Letter Template
Confirmation of Disciplinary Action Filed	DAF	ltrdaf.ltr	ltrdaf.doc
Confirmation of Disciplinary Action Resolution	DAR	ltrdar.ltr	ltrdar.doc
Confirmation of Grievance Filed	GRF	ltrgrf.ltr	ltrgrf.doc
Confirmation of Grievance Resolution	GRR	ltrgrr.ltr	ltrgrr.doc

These topics discuss how to:

Set up the Process Scheduler.
Set up WinWord security.
Set up document templates.
Run the WORDSAMP process.
Specify the output type and format of the SQR process.

Setting Up the Process Scheduler

To set up your Process Scheduler to generate form letters:

Install the Microsoft Word on the same machine that runs the Process Scheduler.
Define the WINWORD parameter in the Process Scheduler configuration file.
The WINWORD parameter defines the location of the Microsoft Word executable file, winword.exe on the server. Make sure that there are no spaces in the path and the path does not end with a slash (/).
Use the Process Scheduler Manager to define a server specifically for running the form letter processes.
Select PeopleTools > Process Scheduler Manager > Use > Server Definitions to define the server. On the Distribution page, leave the Transfer Log Files to Report Repository check box deselected.

If you run the Process Scheduler as a service, modify the service to interact with the desktop:

From the Windows Control Panel, open Administrative Tools, Services.
Open the Process Scheduler service and access the log on tab.
For the Log on as field, select Local System account and select the Allow service to interact with desktop check box.
This enables Microsoft Word to run in the foreground of the server. You cannot run Microsoft Word macros as a background service.

See PeopleTools PeopleSoft Process Scheduler, “Using the PSADMIN Utility".

Setting Up Winword Security

To run the macro that completes the merge, you must set the macro virus protection to Low. To do this:

Run Microsoft Word and select Tools from the menu bar.
Configure security according to the version of Word you are running.

See Microsoft Word Legal User's Guide

Setting Up Document Templates

To generate form letters, the document templates and the macros must be located in the directory %PSHOME%\winword.

Check that the files psmerge.doc and psmerge.dot, and all the document templates in this directory are read-only.

Running the WORDSAMP Process

Before running any of the form letters processes, test your environment by running the WORDSAMP process. If this process runs successfully, this demonstrates that the environment is correctly configured to run Microsoft Word processes.

Note: To verify that the WORDSAMP process has successfully completed verify that it has created a document called wordsamp.doc.

To run the WORDSAMP process:

Select PeopleTools, Process Scheduler, System Process Requests. Select a Run Control ID and click Run.
The Process Request Dialog page (PRCSSAMPLEPNL1) appears.
Select your server in the Server Name field and select the Win Word Sample Process check box.
Click OK.
Click the Process Monitor link to check that the process runs successfully (Run Status is Success).
Check that a document wordsamp.doc is created. This document is posted to the Report Repository as a normal report.
If the process doesn't run successfully or the process doesn't create wordsamp.doc, then your environment is not set up correctly to run WinWord processes.

See PeopleTools PeopleSoft Process Scheduler, "Submitting and Scheduling a Process Request".

Specifying the Output Type and Format of the SQR Process

When you run the form letter report to generate letters, make sure that the Type and Format fields are set up correctly for the SQR data extract process. The SQR process must be set up with Type set to File and Format set to LP.

For example, if you are creating a training letter, check the output type and format as follows:

Select Administer Training > Student Enrollment > Create Training Letters > Create Training Letters page (RUNCTL_TRN001).
Enter run parameters and click Run.
On the Process Scheduler Request page, click Training Letters to access the Job Detail page.
In the Process List group box, which lists the three processes run to generate letters, locate the SQR process TRN001 and select File in the Type field and LP in the Format field.

For information about running the form letter reports, refer to the appropriate PeopleSoft Human Resources documentation.

See Tracking Disciplinary Actions.

See Generating Student Form Letters.

See Generate Recruitment Letters Page.

Before you can print form letters, you need to modify the macros supplied by PeopleSoft to suit your environment and set up your process scheduler configuration file.

Depending on your configuration, you may need to make these changes to the standard Microsoft Word macros that are supplied by PeopleSoft:

Default path to the empty.doc file that contains all the macros.
Location of the letters produced.
The macros create letters in the directory C:\TEMP on your application server. We recommend that you edit the macros to change the location of the letters so that when you print them from Microsoft Word, you print them to your local printers.

To set up the system to print form letters:

On the Servers - Distribution page, create a new dedicated Process Scheduler leaving the Transfer System Files to Report Repository check box deselected to run form letters.
Define the WINWORD variable in the process scheduler configuration file.
WINWORD defines the location of the Microsoft Word executable file that the process scheduler runs to produce the form letters. For example, if Microsoft Word is run on the application server, you might have this line in the process scheduler configuration file:
```
WINWORD=C:\APPS\OFFICE97\OFFICE
```

See PeopleTools: PeopleSoft Process Scheduler.

Form letters are useful for many administrative tasks besides those for which we deliver sample letters. You can modify the sample form letters in several ways, from simple changes to text in the templates to adding the Letter Code field to other pages in PeopleSoft Human Resources.

These topics discuss how to:

Modify the text in sample letter templates.
Add fields to sample letters.
Create new form letters.
Add letter code fields to pages.

Modifying the Text in Sample Letter Templates

The form letter templates that are delivered with PeopleSoft Human Resources contain sample text for different types of tasks that you can change to suit your needs. For example, you'll probably want to change the sender names in the letters to the names of the employees in your organization who are responsible for administering the tasks. If you need to modify only the text, without changing any fields that are used or pages and tables that are referenced in PeopleSoft Human Resources, use the following procedure.

To modify the text in a form letter:

Find the Word letter template to update.
Templates are located in the directory \PS\WINWORD.
In Microsoft Word, open the document that you want to modify.
If you see " " in the document, select Tools > Options; then select the Field codes check box.
Make changes to the text as you would in any other document and save the file.

Warning! Don't overwrite the field codes (enclosed in curly brackets). They are the placeholders for the values that are extracted from PeopleSoft Human Resources.

Adding Fields to Sample Letters

In addition to updating the text of a sample letter, you can include other types of data from PeopleSoft Human Resources.

Note: To make this change, you should be familiar with Microsoft Word fields and the report writer used to extract data values from your PeopleSoft Human Resources database.

To use additional fields in form letters:

Add field codes to the form letter templates for any new data types that you want to include.
Modify the SQR that extracts data from PeopleSoft Human Resources so that it retrieves values from all of the fields that you want to use and writes them to the appropriate data extract files.
For example, to include title in the Training Enrollment Confirmation letter ltrcon.doc, add a title field code to the form letter template. Also add a variable for title in TRN001.sqr so that the SQR retrieves the title value and writes it to the data extract file.

Here's what the data extract file looks like before the change:
```
systemdate, Name, . . ., 
```
```
"August 10, 2001", "Barry Robert Campbell" 
```
Here's what it looks like after the change:
```
systemdate, Name, Title....
```
```
"August 10, 2001", "Barry Robert Campbell", "Director". . .
```

Creating New Form Letters

You can create form letters for different purposes. For example, you might want to create a form letter notifying students they are on the waiting list for a course session.

To create a new form letter:

Create a new letter code in the Standard Letter table.
Create a Word letter template, including the appropriate text, field codes, and data statement reference.

The file name of the template must match the data extract (.ltr) file name. For example, if the data extract file is app004.ltr, the Word template file must be called app004.doc.

You might find it easier to adapt an existing form letter template than to create a new one. Look through the form letter templates to see if there's one that needs only minor modifications to serve as a new form letter template.

For example, create a form letter for interview schedules (INT) by adapting the offer letter template. In the directory \PS\WINWORD, open ltrof1.doc. Modify the text as needed and add any new field codes that you want to use in the letter. Save the new template under a different name, ltrint.doc.
Edit the SQR that selects and extracts data from other PeopleSoft Human Resources tables and stores it in a separate data extract file.
Insert the MERGEFIELD field code where you want the merge process to insert data from the data extract file into the letter. Press ALT + F9 to insert the MERGEFIELD field code.

For example, to create a new form letter for interview schedules, you create new procedures in app007.sqr to extract values from all the fields and create a separate data extract file to store interview schedule letter information.

The SQR process must include the name and extension (.ltr) of the data extract file that is created. An example is:
```
begin-procedure Write-Heading
move '{IMPORTPREFIX}' to $FileName !start a new report file
do Get-prcsoutputdir
if (rtrim($prcsoutputdir,' ') <> '')
move $prcsoutputdir to $Filename
concat 'APP004.LTR' with $Filename
end-if
NEW-REPORT $Filename
Let $InputField1 = 'LANG,Audience,Job_Requisition,JobTitle,DeptID,DeptName,Min_Rt_Annual,Max_Rt_Annual,Name1,Value1,Name2,Value2,Name3,Value3,Name4,Value4,Name5,Value5,Name6,Value6,Name7,Value7,Name8,Value8,'
Let $InputField2 = 'Name9,Value9,Name10,Value10,Name11,Value11,Name12,Value12,Name13,Value13,Name14,Value14,Name15,Value15,Name16,Value16,Name17,Value17,Name18,Value18,Name19,Value19,Name20,Value20,AsOfToday'
Let $InputFieldTot = $InputField1 || $InputField2
move
$InputFieldTot
to $ioarea
print $ioarea (1,1)
next-listing
end-procedure
```
If you create an Application Engine process, the file created by the process must have an .ltr extension.

See PeopleTools SQR for PeopleSoft Developers
Copy the new letter template to the Process Scheduler %PS_HOME%\winword directory.
Create a PSJOB to ensure that the SQR, WORDINIT, and PSMERGE processes are run in the correct order.
Define the job to include these steps in the following order:
1. SQR process or Application Engine data extract process.
2. WORDINIT Winword process.
3. PSMERGE application engine.
Note: PeopleSoft recommends that you do not modify any of the delivered Winword macros or templates.

Note: To link your new letter to PeopleSoft Process Scheduler, ask your human resources project leader or see the references below.

Adding Letter Code Fields to Pages

We deliver PeopleSoft Human Resources with Letter Code fields in several pages in Administer Training, Administer Workforce, and Manage Labor Relations.

You can add the Letter Code field to any other pages (and their underlying tables) in PeopleSoft Human Resources. For example, if you routinely send letters to employees, notifying them of career planning sessions, you can add the Letter Code field to one of the pages from the Plan Careers menu.

Note: To make this change, you should be familiar with PeopleSoft Application Designer; Microsoft Word field codes, macros, and data statements; and the SQRs that are used to extract data values from your PeopleSoft Human Resources database.

When you add the Letter Code field to another page and its underlying table or tables in the system, also create:

A letter code that represents the particular application.
A form letter template with the appropriate text, field codes, and data statements.
An SQR that extracts data from the correct tables in PeopleSoft Human Resources and creates new data extract files.
A job containing the SQR, WinWord process WORDINIT, and the Application Engine PSMERGE.

See PeopleTools: Application Designer Developer's Guide "Working With Processes and Reports"

See PeopleTools: Process Scheduler.

These topics discuss:

Troubleshooting the SQR process.
Troubleshooting the WORDINIT process.
Troubleshooting the PSMERGE Application Engine process.
Troubleshooting the Process Scheduler.
Troubleshooting the Winword Directory.
Troubleshooting Winword processes.
Troubleshooting the PSMERGE process.

Troubleshooting the SQR Process

For the SQR data extract process check that:

The process is run with the output Type set to File and Format set to LP. If you have run the SQR with any other output type or format, make sure that you delete these data extract files.
The data extract file has been produced in the format xxx.ltr in the Process Scheduler log/output directory.
Use the Process Monitor to delete all failed Process Requests.

Troubleshooting the WORDINIT Process

If the WORDINIT process fails and the environment is correctly configured, the most likely cause is macro security. Switching off the macro security works for some Microsoft NT networks. You may also need to consult your Systems Administrator.

In some networks, Microsoft Word automatically switches the security level back to "high" when running the process. For example, if Winword macro security is defined at the NT User Profile level then you need to set macro security to "low" for the NT ID that starts the PeopleSoft Process Scheduler service.

Note: Windows locks and caches the macro virus protection settings for Winword and this may cause difficulties when turning off the macro virus protection.

Try hard-coding the path to PS_HOME in the Process Definition for WORDINIT:

Navigate to PeopleTools > Process Scheduler > Processes.
Select Process Name in the Search By field and enter WORDINIT.
Select the Override Options page.
In the Parameters field replace %%PS_HOME%% with the hard-coded path to the directory.

Troubleshooting the PSMERGE Application Engine Process

If the PSMERGE Application Engine process does not complete and you have added extra fields to the SQR data extract process, check that the fields have also been included in the document template and that the fields occur in the same order.

Troubleshooting the Process Scheduler

Check that the Process Scheduler is configured correctly:

You must define a separate Process Scheduler server at Process Scheduler Definition level with the Transfer Log Files to Report Repository check box deselected.
Confirm that the WINWORD parameter is correctly specified in the prcs.cfg file.

Check that all failed attempts at running the form letters have been deleted using the Process Monitor. Delete any Process Requests that have failed.

Use the Windows Task Manager to check that there are no Winword processes still running. Delete these before rerunning the form letter report.

Once Microsoft Word is interacting with the desktop it may try to reinstall itself. To avoid this, disable the Windows Installer.

Troubleshooting the Winword Directory

Check that the template files are in the correct directory with the correct access:

The Winword templates and the macros must be located in the %PS_HOME%\winword directory.
The files psmerge.doc and psmerge.dot and the document templates in the %PSHOME%\winword directory must be read-only.

See PeopleTools PeopleSoft Process Scheduler

Troubleshooting Winword Processes

To display errors and debug the Winword Processes, modify your Process Scheduler configuration file, psprcs.cfg, by adding the following line to the Process Scheduler section of the file (after the line for the Allow Dynamic Changes parameter):

Allow To Interact With Desktop=1

Save the changes, clear the cache and re-start the application server.

See PeopleTools PeopleSoft Process Scheduler, "Using the PSADMIN Utility".

Troubleshooting the PSMERGE Process

If the PSMERGE Application Engine process is failing or the status remains as Processing, take the trace file, AE_PSMERGE_<PI>.trc (where <PI> is the process instance number), and extract the arguments from the file, combine them and run them from a command line. This tests the process outside the Process Scheduler.

For example if AE_PSMERGE_<Pl>.trc is set up as follows:

cmd = D:\PSHR88\WINWORD\run.bat
	cwd = (null)
	argc = 5
	argv[0] = D:\PSHR88\WINWORD\run.bat
	argv[1] = C:\PROGRA~1\MICROS~4\OFFICE\WINWORD.EXE
	argv[2] = D:\PSHR88\appserv\prcs\HCUPG3WD\log_output\AE_PSMERGE_387\387_PARAM.TXT
	argv[3] = D:\PSHR88\WINWORD\PSMERGE.DOC
	argv[4] = /mPSMERGE

You run them from the DOS command line as follows:

D:\PSHR88\WINWORD\run.bat  C:\PROGRA~1\MICROS~4\OFFICE\WINWORD.EXE
D:\PSHR88\appserv\prcs\HCUPG3WD\log_output\AE_PSMERGE_387\387_PARAM.TXT
D:\PSHR88\WINWORD\PSMERGE.DOC  /mPSMERGE

See PeopleTools PeopleSoft Application Engine, "Tracing Application Engine Programs"

Generating Form Letters for PeopleSoft Human Resources

Understanding Form Letters for PeopleSoft Human Resources