Understanding Correspondence Templates

Template Packages and Package Usage

You make templates available to end users by bundling them in template packages. Packages can contain both templates and nontemplate (static) documents. Optionally, you can designate one template as the cover letter or email body.

Packages are associated with a specific language and with a usage. The usage determines the contexts from which the package is available. Generally, the runtime context for correspondence is the component from which the correspondence is sent. For example, from the Case component, you can access either the Send Notification page or the Correspondence Request page. From either of those pages, you can select packages with a usage that includes the Case component.

If you license PeopleSoft Multichannel Communications and use its email response management system (ERMS), you can also send template-based email correspondence from the context of inbound email. ERMS uses the email information, such as category, type, product group, product, language, related transactions and solutions, that is available from the email workspace to return a list of templates that are applicable to the email when sending responses.

When associating a package with a usage that includes multiple components, be sure that the terms in the package's templates can be resolved from any of the components. For example, if you define a single usage for sales and you associate that usage with both the Lead component and the Opportunity component, then the templates in a package with that usage need to be valid from both leads and opportunities.

PeopleSoft delivers several usages, including one called General Purpose, which is associated with all correspondence-enabled components. Use the General Purpose usage for correspondence that does not rely on any specific transactional context. For example, an introductory letter or a thank you letter that does not reference transactional data.

Template Packages Used in AAF Email Notifications

PeopleSoft CRM leverages correspondence templates to generate contents for automatic email notifications (a type of workflow action) that are sent via the Active Analytics Framework (AAF). When a correspondence template packages is specified as a workflow template (an attribute on the page), it is used only by AAF to send email notifications and is not applicable for users who want send a manual notification or correspondence request from a CRM transaction. The primary difference between the workflow-specific correspondence template packages and standard packages is that the former can contain terms that are resolved into data coming from the component buffer. The type of implementation for this kind of terms is context variable.

Templates

Template packages contain one or more template definitions, which in turn reference individual template files. Template files are marked for use with print correspondence, email correspondence, or both. The print and email versions are normally different presentations of the same content, although you can vary the content as necessary.

Template definitions support the following configurations:

• One template that is used for both print and email.

• Two templates, one for each channel.

• One template that is specific to a single channel.

Four types of template files exist:

• Internal text templates.

  Previous releases of PeopleSoft CRM enabled you to define this type of template within the PeopleSoft system. Customers who upgrade from previous releases may still utilize any existing templates of this type, but cannot create new ones. New internal templates are now created in HTML format.

  Note that if you modify an existing internal text format template using the new HTML template editor, the template will be automatically converted to and saved in HTML format, and will only be available for use with the email channel.

  Internal text templates included subject text and a body text area. The subject text is used only in email correspondence.

• Internal HTML templates

  Internal HTML templates include subject text and a body text area. The body text area can be formatted using the HTML template editor within the PeopleSoft system. HTML templates are used only in email correspondence.

• External .txt files created with any text editor.

• External rich text format (RTF) files created with any word processor that supports this format.

Because RTF files, unlike plain text templates, permit formatting, they are the best choice for all print templates, and they are often the best choice for email attachments (although you might want to convert them to PDF files rather than sending them in RTF format). Although you can use text templates for printing, the resulting plain text output is not usually suitable for correspondence. HTML templates are most useful for email body text.

External RTF and text files are uploaded into the system at the time they are associated with a template definition. When users generate correspondence that is based on external templates, the system downloads the templates to the PeopleSoft Process Scheduler server where terms are resolved and merged documents are created. The system then uploads the final merged documents to provide a permanent record of your correspondence. Set the locations of uploaded files (templates and merged documents) on the Correspondence Management Installation Setup page.

To create correspondence based on RTF files, you must set up the uniform resource locators (URLs) that are used to reference and access the various uploaded files.

See Supplemental Installation Instructions for PeopleSoft CRM Applications.

Template Handling for Manual Notifications

When users send manual notifications, the channel is always email (in this context, email encompasses both true email and worklists). The language is always the language with which the user logged onto the system.

The prompt for template packages is limited to packages of the appropriate language and usage. It is also limited to packages that contain only one email template and that template must be an internal template (not a .txt or .dot file). The prompt excludes packages that are specified as workflow templates.

When you define template packages for use with manual notifications, use the Cover Letter/Email Body field to identify the template. Do not include any static attachments.

When creating manual notifications, users select one package at a time and explicitly apply it. Applying the package forces an immediate merge, and the merged text is inserted into the notification's Message field, which contains the email's body text. Recipient-based terms are resolved based on the first external recipient listed. Therefore, users need to address the notification before applying the template, and they need to reapply the template after changing the notification's recipient list.

When applying a template, the system does not overwrite existing message text. Instead, as each template is applied, its body text is added to any message text that is already there. This enables users to apply multiple templates in sequence and to mix template-based text with free-form text. Users can also modify the template-based text once it appears in the body text field. The location and format of the newly added text depends on whether you license PeopleSoft Multichannel Communications and, if so, how you configure it.

Internal text and HTML templates have subject text as well as body text. The subject text is applied only if the modification's subject field is blank. This means that once a template with subject text has been applied, the subject text of any subsequently applied templates is ignored.

Template Handling in the Correspondence Request Page

The Correspondence Request page supports packages with any number of templates, and it supports both print and email correspondence.

When users send correspondence from the Correspondence Request page, they explicitly select a channel and a language before prompting for template packages. The system limits the template package prompt based on the user's selections and based on whether the package's usage is valid for the context from which the Correspondence Request page was accessed.

Once the user selects a package, the system selects the appropriate subset of templates based on the selected channel.

Similar to manual notifications, the prompt excludes packages that are specified as workflow templates.

Because correspondence requests can include multiple templates, email correspondence applies additional logic to determine which template is used as the email body. Package definitions enable you to designate a cover letter template. The first internal (HTML or text) cover letter in the correspondence request is used as the email body. It is also used to set the subject of the email. Only one template provides the email body text; all other templates (including cover letters for additional packages in the request) become attachments. The content of internal templates is converted to .txt files for this purpose; subject text from internal HTML or text templates is ignored. Attachments based on HTML templates are saved in .txt files (with the HTML tags included in the text content).

Template Handling for AAF Email Notifications

The channel for correspondence packages that are used for sending automatic workflow notifications is always email. Each of them contains only one email template, and it must be an internal text template.

When defining template packages for AAF email notifications, use the Cover Letter/Email Body field to identify the internal text template and do not include any static attachments. The template, which provides the content of the automatic email notification, can contain terms that are resolvable by accessing data directly from the component buffer. Typically, these terms have the implementation type of context variables for the contexts of trigger points, for which AAF policies are processed.

PDF Options

Correspondence that is sent from the Correspondence Request page and that is based on text templates can be converted to PDF files before it is sent. (In the Send Notification page, however, the system always applies template text directly to the email body; PDF conversion settings are not applicable.) Note that HTML template correspondence cannot be converted to PDF files.

PDF conversion options are set at the system level and, depending on the system settings, at the package level. The PDF setting is not applied to the template that provides the body text for email correspondence; it is applied to email attachments and to all printed documents.

Correspondence that is converted to PDF is both delivered and stored in that format. The system overwrites the merged version of the RTF or text file with the PDF at delivery time; until the correspondence is delivered, it remains in its native format so that the sender can personalize the content (if your system settings allow personalization).

Referencing Term Objects

When you create term objects, you assign each one a term name. This is the name that you use when referencing the object within a template. Terms, the atomic element of term objects, are defined using the Manage Terms component in the AAF data library. They replace the tokens in correspondence templates used prior to release 9.0, and can be resolved into data that pertains to the context of the correspondence requests. In some cases, terms can be resolved into data regardless of contexts. Referenced in templates, terms, term groups and subtemplates are wrapped in specific term start and end tags (defined on the Correspondence Management Installation Setup page). The system uses these tags to recognize the presence of a term object.

For example, if you create a term with Product as the name and use double curly brackets as your term start and end tags (this is the system default), you place the term in a template in this format: {{Product}}. Term names are not case-sensitive.

Terms

Terms are placeholders for PeopleSoft CRM data. The system provides a folder structure, known as the subject area, in which terms are organized functionally. A term can be placed in more than one folder if necessary. The subject area is available throughout the CRM system to facilitate term selection; for example, when you insert terms in templates or subtemplates.

The term subject area includes folders that are specific for system terms and recipient terms. The rest of the terms are transactional and are grouped functionally:

• System terms.

  These terms can be used regardless of the transactions from which correspondence requests are made. They have generic implementations and do not require any input values from contexts to be resolved. System terms have application class-based implementations. PeopleSoft delivers a rich set of terms that can be used in any of the correspondence templates. Locate system terms under the Correspondence Template Terms, System Terms folder of the subject area.

• Recipient terms.

  This is data about the person to whom the correspondence is sent. For example, use recipient terms to represent the recipient's name and address.

  Recipient-related terms are located in the Correspondence Template Terms, Correspondence: Recipient Dtls folder.

  Note: Because recipient data is identified while the correspondence request is being processed, recipient-related terms cannot be tested individually using the term tester. Refer to PeopleTools documentation for more information on term tester.

• Transactional terms.

  This is data about a PeopleSoft CRM transaction, such as a case or lead. Transactional terms are associated with specific components and can be resolved only from the context of those components. For example, when sending correspondence from a case, case-related terms are resolved for the current case.

  When you define transaction terms, you can define different data extraction methods for different contexts. For example, a term called Status would have different data extraction processing for cases and service orders. You can even use different methods to resolve the term in different contexts. For example, use an application class to resolve case status, but a PS query to resolve the service order status.

  When sending email from the Outbound Email page that has a related transaction, transactions can be considered the current context. For example, if an outbound email is related to a case, case-related terms can be resolved. If the outbound email has two related cases, the system loops through both of them and creates two documents, one for each case.

  Transaction terms cannot be reliably resolved from an outbound email that is related to more than one type of transaction (for example, a case and a service order). Therefore, in this situation, the system does not permit users to apply template packages with a transaction-specific usage.

System terms and recipient terms are always resolved by application classes. Transactional terms, however, can be resolved by any of the following five mechanisms:

• Application class.

• PeopleSoft Query.

• Constants.

  Constants are short text phrases that you use in multiple templates.

• SQL Object.

• Record.Field.

The system does not perform any formatting of term content; the term's creator is responsible for returning the value properly formatted. For example, if a telephone number is stored in the system as a series of numbers, but you want to format the phone number with hyphens between the numbers, the term must convert the data from the format in which it is stored to the proper display format.

Terms can represent a single value (data at level zero in the context of the correspondence) or a multivalue rowset (data at level one in the context of the correspondence). For example, a term representing a recipient's name resolves to a single value, and a term for line item data in an order resolves to an array (because an order can include multiple line items).

When a term represents an array, you need to package it into either a term group or a subtemplate to ensure that all values in the array are included in the merged correspondence. The implementation of term groups must return a rowset. While processing correspondence requests, correspondence management does not trigger the processing of all the rows in the term even if you set the number of rows to many in the term definition. The situation is different, however, for correspondence templates that are intended for AAF email workflow notification. If the term represents a piece of data that is available in the component buffer as a child scroll (which forces the AAF decision engine to evaluate every row in the child scroll by using a term that refers to a data element in the child scroll), it triggers the AAF workflow action to process every row in the child scroll if the condition of the AAF policy is evaluated to true. The workflow action passes the content of that specific row to the correspondence management for processing. In this situation, every row in the child scroll is being processed by correspondence management.

The same data can be represented by a single-value term or a multivalue term, depending on the context. When you send correspondence related to a specific case, a term for the case ID represents a single value. But if you send correspondence that lists all of a customer's open cases, a term for the case ID represents a single array. Because these two case ID terms are resolved differently, you would need to define two terms to support these two scenarios.

When you create a template definition, you enable the template's term objects by adding them to the Term & Subtemplate & Term Group Reference Detail grid on the Template page. When you add an HTML template to the template definition, the system automatically enables all term objects that are in the template. However, because the system does not parse external templates, it is a manual process to enable the term objects that are referenced in the external template. Failure to enable the relevant terms causes the system to leave unresolved term text in the merged document.

Terms are resolved by the data extraction and merge processes. The merge process is independent of the process that delivers the final correspondence, which means that you can preview the merged correspondence before sending it.

Term Groups

Term groups are used exclusively to manage data from rowsets—that is, data arrays. For example, orders include multiple line items, so you can create a term group to represent the overall line item. Each term in that term group represents one data element from the line item, for instance, the line number, product, quantity, price per unit, or total price.

The terms in a term group represent record.field data from the same rowset, and each must be resolved by the same application class or query.

Data that you reference with a term group is always presented as a table. In internal and external text files, which do not support a table object such as you might use in an RTF file, the tabular format is achieved through character spacing.

A template does not let you refer to term groups as a whole. Instead, use the syntax {{Term Group.Term}} to refer to specific terms within a term group.

In HTML templates, place the term group.term references together in one row without a carriage return or any intervening characters other than spaces, which are ignored during the merge. At merge time, the system replaces the row with a table. The column titles and column widths are controlled by the template group definition. If the term text is longer than the allowed width, it wraps to the start of the next line rather than aligning with its column position. Additional formatting options are possible when using term group.term references within RTF files.

Using Terms in RTF File Tables

For additional control over the presentation of data arrays in RTF files, use tables. This approach gives you access to that application's extensive presentation options. Within a table, follow these guidelines:

• All term group.term references in a single table must be to the same term group.

• Cells that contain term references must not contain any other text.

  For example, you cannot put Solution Number {{Case Solutions.Solution ID}} in a single cell. Instead, you must place the static text Solution Number in one cell and the term {{Case Solutions.Solution ID}} in another.

• Do not merge table cells vertically, as this prevents the merge script from accessing the affected table rows.

 

If you've used the table formatting features to create table header rows, those rows are repeated when the table breaks across pages. This, however, is standard word processor functionality and has nothing to do with the merge process.

The following example illustrates another approach to formatting term data:

Any formatting that you apply in the table is retained in the final merged correspondence. In the preceding example, the case note summary term is italicized; therefore, the note summaries in the merged document are also italicized. Also, although the illustration includes table gridlines, you can format the table so that the gridlines are invisible. In that case, the final merged correspondence looks similar to the following:

Subtemplates

Subtemplates are a type of internal text template. Use subtemplates to create reusable content that can be referenced in either internal or external templates.

Subtemplates can include terms and a combination of static text. For example, a subtemplate containing a standard salutation for letters might include the date, the recipient's name and address, and a greeting such as Dear {{Salutation Code}} {{Last Name}}.

Subtemplates do not have to include terms. For example, you can use a subtemplate for a copyright notice or privacy statement.

Using the term group.term syntax in a subtemplate produces the same formatting as an internal text template: the term group.term data is placed in a table, with column headers and width that are controlled by the term group definition.