Summary

Use the Application Document wizard to generate Word documents that capture information about the application. The wizard includes two standard document templates for the generated Word document, and you can make simple customizations to those templates by following the steps in DCO 6.1 - How to customize Application Document templates.

What if you want to make more sophisticated changes, and have the wizard generate a document that includes additional or complex information? This article describes how to extend the standard Application Document wizard in more advanced ways to include sophisticated custom content in the output document, such as:

• Scenario 1: Include reports on more rule types in the output document
• Scenario 2: Reduce the number of properties reported in the Properties Referenced section of the output document by filtering out properties
• Scenario 3: Substitute custom images for screen shots and flow diagrams in place of the system-generated images
• Scenario 4: Inject additional text content, images, or screen shots into work type sections of the output document
• Scenario 5: Add customized selection criteria to optionally include rule types in the output document
• Scenario 6: Include detailed information about the rules of a specific rule type in the output document

Before you begin

This article builds on the steps presented in DCO 6.1 - How to customize Application Document templates. Before beginning the steps in this article, it is recommended that you:

• Read that article to familiarize yourself with the descriptions of the Word Template rules and the Word template document files
• Turn on field codes in Microsoft Word, as described in that article

Scenario 1: Include reports on more rule types in the output document

When you run the Document wizard and select one of the standard templates, the output document typically includes sections with tables of details about components used in the application: RuleSets, classes, rule types, and so on. For example, the output document typically includes a table of application RuleSets, as illustrated in the following sample image.

Sample RuleSet table in output document using the ESupply application:

The standard templates do not provide this type of report on every Process Commander rule type. Your organization might want the generated document to include a table for other rule types in your applications, such as test case rules or navigation rules.

The steps in this scenario describe how to include a rule type in the output document automatically, using the navigation rule type as an example. (Navigation rules are used to provide context menus for grid layouts, among other things.) The resulting output uses the same table format that is used in the standard template. The result is a table in the output document that lists the navigation rules in the application and which looks similar to the other tables in the output document, as illustrated in the following image.

Result of Scenario 1 - Navigation rules table in the output document:

The relationship between the output document and Word template files

As described in DCO 6.1 - How to customize Application Document templates, the structure of the output document is set by a Word file that is associated with a Word Template rule. This Word file serves as the base for the output document, and contains a combination of elements that determine what goes into the output document:

• Static content (text and images) residing within the file itself
• Field codes for property references, which get data from the clipboard
• Field codes for correspondence rules that insert complex content about the rules and application data

Title page of the ApplicationDocument.doc Word file:

Field codes referencing correspondence rules in the ApplicationDocument.doc file:

Because the generated output document is built on a base document file, the general steps to achieve a generated document that includes additional custom content are:

1. Create a custom base document file and associated Word Template rule, as described in DCO 6.1 - How to customize Application Document templates.
2. Create the appropriate correspondence rules for the desired content
3. Add field codes to the document file to insert the desired content

The following steps assume that you have completed the steps in DCO 6.1 - How to customize Application Document templates.

To include the standard report on a rule type:

1. Create a correspondence rule.
2. Reference it in a field code in your Word template document file.

In this example, navigation rules are added to the output document.

Step 1: Create the correspondence rule:

1. In the Application Explorer, right-click Process and select New > Correspondence.
2. In the New window, change the Filter By to All (instead of Implementation).
3. Select PegaAccel-Task-DocumentApp in the Applies To field.
4. Specify a name and select Mail for the Correspondence Type.
5. For the RuleSet and Version, select the RuleSet you created previously to hold your customized rules.
6. Click Create.

7. On the Corr tab, click to switch the editor to Source mode.
8. In the editor area, enter the following lines:

   <pega:include name="AppDocStyle" type="Rule-Obj-HTML"></pega:include>
   <h1>Navigation</h1> <%
   tools.putParamValue( "ViewClass", "Rule-Navigation" );
   tools.putParamValue( "ListViewClass", "" );
   tools.putParamValue( "ListViewName", "ListToDocument" );
   tools.putParamValue( "SectionName", "" );
   %>
   <pega:include name="DocumentList" type="Rule-HTML-Section" />

9. Save the correspondence rule ().

Here, because this scenario is for including the list of navigation rules in the output document, the correspondence rule specifies Navigation for the heading text (the <H1>) and Rule-Navigation for the ViewClass value. For a different rule type, substitute the heading you want to appear in the final document, and substitute the appropriate Rule-nnnnn class for the ViewClass.

Note: To find the ViewClass value to specify for a particular rule type, in the Rules Explorer, right-click on the rule type name and click Definition in the context menu. The class form for that rule type opens, and the class name is the value to specify for the ViewClass parameter.

The purposes of the pieces in this correspondence definition are:

Parts of the correspondence rule definition:

Step 2: Reference the correspondence rule in your Word base file:

Now that the correspondence rule is created, add a field code to your Word base file to include it.

1. In the Designer Studio, open your custom Word Template rule and click Download File to save the template file to your local system.

2. Double-click the file to open it in Word, make sure field codes are displayed, and scroll to the Contents page.

3. Position your cursor at the point where you want the new rule section to appear in the output document, and press Ctrl and F9 together to insert a new field code. A pair of curly brackets appears at that position.

In this example, the new field code is inserted at the end of the standard ones:

4. Type in the reference to your correspondence rule using this format: pega:insert corr=CorrRuleName, where CorrRuleName is the name of your correspondence rule.

In this example, the new field code references the OurNavRules correspondence rule created in this scenario.

5. Save the Word file. Then click Upload File in your Word Template rule to save the updated Word template document file.
6. Click to save the rule with the updated file.

Run the wizard to test:

1. Click > Application > Tools > Document to start the wizard.
2. Select your custom template in the Template field.

3. Select the Create Document step in the wizard. (The default selections on the other tabs are applied.)

4. Click to generate the output document. Microsoft Word opens and the document is dynamically generated. When a system message displays stating the document has finished loading, scroll through the document to locate the added rule type section.

In this scenario, our example shows the set of navigation rules that are in the application (included by the OurNavRules correspondence rule). The standard table styles of the blue header and borders are applied from the AppDocStyle reference in the correspondence rule:

Scenario 2: Filter Properties in Properties Referenced sections

The output document includes Properties Referenced sections when a user selects one of the following options in the Document wizard:

• A Detail Level of Property References on the Select Criteria step.
• The Referenced Properties checkbox on the Work Type Criteria tab on the Select Criteria step

Including properties in the output document can make the document long and repetitious, especially if the application has multiple layers and multiple work types. For example, by default all of the properties starting with "py", such as pyID and pyCaption, are listed for each work type.

To filter out properties that you do not want to see in the output document and prevent them from appearing, override the PegaAccel-Task-DocumentApp.FilterReferencedProperties activity rule.

1. In the Rule Explorer, expand the Technical category and then select the Activity category.

2. In the Criteria section, click for the Applies To Contains field and in the window that opens, select PegaAccel-Task-DocumentApp and click Apply.

3. In the Criteria section, click Run. The activities with Applies To Class of PegaAccel-Task-DocumentApp are listed. In the list, select the FilterReferencedProperties activity to open its rule form.
4. Click to save a copy of the rule to the RuleSet you created previously to hold your customized rules (for example ESupply_templates).
5. The first step in the activity creates a clipboard page named FilterProperties. Expand the second step in the activity to view its contents.

   The second step is a Java step that sets two properties (pRuleNames and pClassNames) on the FilterProperties clipboard page. These two properties provide the lists of those rules and classes that should be filtered out of the document.

   When processing the referenced properties for the output document, the lists are used to compare a property's pyRuleName and pyClassName against each value in the list using a starts with comparison. It there is a match, the referenced property is filtered out of the document.

6. In the Java Source Codefield, add lines for the starting strings that correspond to those properties you want to filter out of the output document.

   For example: If you add "Embed-" to pClassNames in this Java step, then all properties that have a pyClassName starting with "Embed-" are filtered out and do not appear in the output document. If you add "py" to pRuleNames, then all properties that have a pyRuleName starting with "py" are filtered out and do not appear in the output document.

7. Save the rule with your changes. (A warning message is displayed because the activity uses Java. You can ignore this warning.)

For example, adding the line pRuleNames.add("py"); as shown in the following images results in excluding all of the properties beginning with py from the output document.

For example, adding:

Results in the following output:

Note: When you override the PegaAccel-Task-DocumentApp.FilterReferencedProperties activity in this way, that change applies to all of the document templates — standard and custom — that your users select in the Template field of the Document wizard.

Scenario 3: Substitute Custom Images for System-Generated Screenshots and Flow Diagrams

You can provide other images to use in the output document in place of the system-generated screenshots or flow diagrams by creating binary file rules for the substitute images and uploading the images to those rules.

Substituting other images is usually done to replace captured screenshots that do not meet your organization's needs or in situations where you want to control what specific images appear in the output document. For example, you might find that a system-captured screenshot does not show all of the content you want, and you prefer to use one that you take from running the process itself that contains labels for the intended readers of the document. Or you might find that a system-captured screenshot is too small and difficult to read, or one might be too large and take up too much space in the pages and you prefer to substitute a more appropriate image.

To substitute an image for a flow, harness, or flow action in the output document, create a binary file rule with a File Name equal to the pzInsKey of the corresponding rule by following these steps:

1. Determine the rule (flow rule, harness rule, or flow action rule) for which you want to provide a substitute image in the output document.
2. Open the rule and copy its pzInsKeyto a text editor (such as Notepad or Wordpad) by following these steps:
   1. Open a text editor so it is ready for you to paste in the pzInsKey value.
   2. Locate the rule in the Application Explorer and select it to open its rule form.
   3. Click to view its rule data.
   4. Scroll down to the pzInsKey line and copy the value of the pzInsKey to a text editor window.
   5. Close the rule data window and close the rule form.

3. In the text editor window where you copied the pzInsKeyvalue, replace all spaces in the value with underscores (_) and remove all of the hash ('#') and decimal ('.') characters.

   For example, a pzInsKey value of:

   RULE-OBJ-FLOWACTION ECORP-FW-ESUPPLY-WORK-PURCHASEORDER CONFIRMORDER #20100325T172747.079 GMT

   Would be updated to:

   RULE-OBJ-FLOWACTION_ECORP-FW-ESUPPLY-WORK-PURCHASEORDER_CONFIRMORDER_20100325T172747079_GMT

4. In the Rules Explorer, right-click the Technical category and select New > Binary Filefrom the context menu. In the New Instance of a Rule window that opens:
   1. In the App Name (Directory) field, enter webwb.
   2. Copy the updated value from the text editor into the File Name field. (This is the value from step 3 with underscores replacing the spaces and the # and . symbols removed.)
   3. In the File Type field, enter the file extension (type) of the graphic file of the substitute image. The value must be one of the following: jpg, gif, png, bmp, or tiff.
   4. In the RuleSet Version fields, select the production RuleSet that you previously created to hold customized rules.
   5. Click Create.

5. In the Binary File rule form, click Upload File. Browse to the image file that you want to use and upload it.
6. Update the default value in the rule's Description field so that it is less than 64 characters. (The system uses the File Name value as the default description. Because the default value here is the pzInsKey value, it is typically longer than the allowed 64 characters for the description and you cannot save the rule unless you shorten the description.)
7. Click to save the binary file rule.

When you next run the Document wizard and specify the criteria to include that rule type in the output document, the image in the binary file rule is used in the output document in place of the system-generated image.

See also the online help topic: About Binary File rules

Scenario 4: Include Additional Information (Text and Images) for a Work Type

By using Word Template rules with Purposefields of a specific format, you can have the system automatically include supplementary static information (text and images) within the corresponding work type section in the output document.

This method is intended for including additional static content at the beginning or end of the output document's section describing a work type. This method is not intended to pull in additional system-obtained data from the clipboard or from a rule.

1. Create a Microsoft Word document that contains the supplementary content you want to add. Save it as a .docfile.

   Note: As a best practice, start the Word document with a heading styled with Heading 2 style from the Microsoft Word Styles panel. This causes the new content to appear at the appropriate heading level in the output document's table of contents, within the standard section for the work type. (The standard Work Type section begins with a Heading 1, so for headings within that section, it is best to use higher heading styles so that they appear at the appropriate heading levels in the output document.)

2. In the Rules Explorer, right-click the SysAdmin category and select New > Word Template. In the New Instance of a Rule window:
   1. In the Applies To field, select the work type's implementation class (such as ECorp-FW-ESupply-Work-PurchaseOrder.
   2. Copy the value in the Applies To field and paste it into the Purposefield. At the end of the pasted-in value, type:
      • _top, to include the additional content at the beginning of the work type section in the output document
      • _bottom, to include the additional content at the end of the work type section in the output document

      For example, for a work type of PurchaseOrder, with an implementation class of ECorp-FW-ESupply-Work-PurchaseOrder, a Purpose value of ECorp-FW-ESupply-Work-PurchaseOrder_top inserts the content of this Word Template rule at the beginning of the PurchaseOrder Work Type section in the output document whenever the PurchaseOrder work type is specified to be included in the document.

   3. In the RuleSet Version fields, select an available RuleSet and RuleSet Version, and click Create.
3. In the Word Template rule form, leave the Category and Criteriafields blank.
4. Click Upload File. Browse to the Word file you created in step 1 and upload it.
5. When the upload completes, save () the rule form.

When a user runs the Document wizard and specifies including that work type in the output document, the content in the uploaded Word document appears in the output document within the system-generated section about that work type, either at the beginning (if _top was used) or at the end (if _bottom was used) of that section.

See also the online help topic: About Word Template rules

Scenario 5: Add custom selection criteria to optionally include rule types in the output document

The following steps assume that you have completed the steps in Scenario 1.

Scenario 1 describes how to include reports on more rule types in the final generated document based on your custom document template. You can further enhance that option by giving your users the ability to specify whether to include those additional rule reports in the output document.

To give your users this ability in the Select Criteria step of the wizard:

1. Add checkboxes to the Document wizard's criteria selection user interface for your users to select to include the additional rule reports. You add the checkboxes into an existing section rule provided for this purpose.
2. Provide the underlying logic for displaying the checkbox only when your custom application document template is selected in the Select Application step of the wizard.
3. Provide the logic for including the appropriate correspondence rule only when the checkbox is selected

Step 1: Add a checkbox for the users to select to include the additional rule reports

1. Create a property to hold the selection state of the checkbox:
   1. In the Rules Explorer, right-click the Data Model category and select New > Property.
   2. In the New Instance of a Rule window:
      • Set the Applies To field to PegaAccel-Task-DocumentApp
      • Enter a descriptive name in the Property Name field (for example IncludeOurNavRules)
      • Select the production RuleSet you previously created
      • Set the Type to TrueFalse
   3. Click Quick Create to create and save the new property.

2. Update the standard PegaAccel-Task-DocumentApp.CustomChaptersCriteriasection with a checkbox:
   1. Locate and open the PegaAccel-Task-DocumentApp.CustomChaptersCriteriasection rule. (One way to locate the rule is to use the Search field in the Designer Studio header bar.)

      This section is empty by default. It is included in a layout within the standard PegaAccel-Task-DocumentApp.ApplicationDocumentChapters section directly under the default set of selection checkboxes. At runtime, the ApplicationDocumentChapters section displays the selection checkboxes for the Application Criteria tab on the Select Criteria step of the wizard.

   2. Click to save a copy of the rule to your production RuleSet.
   3. Add a checkbox to the existing layout by dragging the Checkbox control from the Basic palette. At runtime, your users select this checkbox to select to include the rule type report in the output document. Next to the checkbox, click to open its Cell Properties panel. In the Cell Properties panel, select the property you created in Step 1 (for example, .IncludeOurNavRules). Click OK.
   4. Add a label for the checkbox by adding a column next to the checkbox, and dragging the Label control from the Basic palette into the cell next to the checkbox. In the label's Cell Properties panel, enter the label you want displayed next to the checkbox (for example, Navigation Rules) and select the property in the Label For field. Click OK.
   5. Save the rule.

Cell Properties for the checkbox:

Cell Properties for the label:

To preview how the checkbox looks at runtime within the wizard's Select Criteria step, click and select Referencing Rules to find the sections that reference the CustomChaptersCriteria section and open one of those rules. In that rule form, click to see the checkbox in context with the rest of the standard section.

To make your checkbox look more like the other checkboxes in that section:

1. Open the Cell Properties for one of the standard checkboxes.
2. Copy the value in the Control field.
3. In the Cell Properties for your checkbox, paste that value into the Control field.
4. Save the CustomChaptersCriteria section.

Step 2: Provide the underlying logic to only display the checkbox when your users select your custom application document template in the Select Application step

In this step, you add a when condition to the checkbox and its label so that they are visible only when the user has selected your custom template. Because the additional rule type reports are included in the output document using field codes in your custom template document, the checkbox should be available only when that template is used in the wizard.

1. In the Cell Properties for the checkbox, select Other Condition for the Visible field. In the Condition field, type IsOurAppTemplate and click the next to the field. In the window that opens, select your production RuleSet and click Create.

2. In the When rule form, use the SmartPrompt to select .pyTemplate for the first value, select =, and enter the value from the Purpose field (pyPurpose) of your custom template. For example, with a custom template with pyPurposeof MyApplicationDocument, the When statement is:

   When .pyTemplate = "MyApplicationDocument"

3. Save the When Condition rule.
4. Update the Cell Properties for the checkbox's label also so that it is only visible for the condition.
5. Optionally, to specify whether the new checkbox should be checked by default at runtime, save a copy of the standard PegaAccel-Task-DocumentApp.pyDefault model rule to your production RuleSet and update it to set the property you created in Step 1 to "true".

Step 3: Provide the logic for including the appropriate correspondence rule only when the checkbox is selected

The following steps describe how to add a condition to the correspondence rule to include the rule type's content when the checkbox is selected.

1. Open the correspondence rule created in Scenario 1. (In our examples, this is the OurNavRules correspondence rule.)
2. Click to switch to Source mode.
3. In the existing correspondence block, add a <pega:when tag at the top that is valid when the property you created in Step 1 for the checkbox is true. This property is true at runtime when the user selects the checkbox to include the report for this rule type in the output document.

   For example, the following line is used in the example where the name of the custom template is:

   <pega:when test=".IncludeOurNavRules==true">

4. Add a </pega:when> line at the end of the block.
5. Save the correspondence rule.

Using the examples illustrated in this scenario, when a user runs the Document wizard and selects the MyApplicationDocument template, the Navigation Rules checkbox appears on the Select Criteria step of the wizard. When the output document is generated, it includes the report on navigation rules. When one of the other templates is selected, the checkbox does not appear, nor is the report on navigation rules included in the output document.

Scenario 6: Include detailed information about the rules of a specific rule type in the output document

The following steps assume that you have completed the steps in Scenario 1 for including the standard report for that specific rule type in the output document.

Scenario 1 describes how to include reports on more rule types in the final generated document based on your custom document template. The standard report is a table in the output document that provides standard information, such as name and Applies To class, about the instances of that rule type.

Example: Standard table of RuleSets in output document

You can include more detailed information about the rules of a specific rule type by:

• Determining which rule data to include in the output document.
• Create a section that has an Applies To class of the rule type. This section provides the HTML content that is used to display the rule information in the output document. This section displays a header, using the standard DocumentRuleHeader section, and the rule data.
• Add a reference to that new section in the appropriate correspondence rule that includes that rule type in the output document.

For example, the following steps describe how to extend the results from Scenario 1 to include the information about who last updated each navigation rule in the application and the timestamps of the updates.

1. Open one of the navigation rules in your application and click to view its rule data.

   The name of the operator who last updated the rule is in the pxUpdateOpName property, and the timestamp of the update is in the pxUpdateDateTime property.

2. Create a section rule with the Applies To class set to Rule-Navigation and a Purpose set to DocumentRuleInfo, and save it to your custom RuleSet.

3. Click the HTML tab and clear the Auto-generated HTML checkbox.
4. In the HTML Source field, enter the HTML to include the standard DocumentRuleHeader section and the pyUsageinformation from the rule data.

   <h3><pega:reference name=".pyRuleName" mode="normal" /></h3>
   <pega:include name="DocumentRuleHeader" type="Rule-HTML-Section" />
   <span><strong>Last updated by:</strong>&#0009;<pega:reference name=".pxUpdateOpName" mode="normal" /> </span>
   <br />
   <span><strong>Last updated on:</strong>&#0009;<pega:reference name=".pxUpdateDateTime" mode="normal" /> </span>

   Notes:

   • &#0009; is the syntax for a tab and is useful for lining up content in the output document.
   • The <span> tags are used to apply to these lines the same text style used in the standard DocumentRuleHeader section, so they'll have similar styles in the output document.

5. Save the section. A warning advising use of the auto-generated HTML displays. Because this section is used for the output Word document and not for a user interface, the warning can be ignored.
6. Open the correspondence rule OurNavRules created in Scenario 1.
7. In Source mode, add the following lines before the </pega:when>line:

   <%
   tools.putParamValue( "ViewClass", "Rule-Navigation" );
   tools.putParamValue( "ListViewClass", "" );
   tools.putParamValue( "ListViewName", "ListToDocument" );
   tools.putParamValue( "SectionName", "DocumentRuleInfo" );
   %>
   <pega:include name="DocumentList" type="Rule-HTML-Section" />

   Note that the newly created DocumentRuleInfo section is referenced in the SectionName parameter.

8. Save the correspondence rule.

Using the examples illustrated in this scenario, when a user runs the Document wizard and selects the MyApplicationDocument template and the Navigation Rules checkbox on the Select Criteria step, both the table of navigation rules and the update information about each navigation rule appear in the output document.