You can customize and extend the content of the output documents created by the Application Document Wizard.

This article describes the structure of the documents, the rules that support them, and how to incorporate the following changes to the wizard and template structures.

You can customize and extend the content of the output documents created by the Application Document Wizard.

This article describes the structure of the documents, the rules that supp

You can customize and extend the content of the output documents created by the Application Document Wizard.

This article describes the structure of the documents, the rules that support them, and how to incorporate the following changes to the wizard and template structures.

You can customize and extend the content of the output documents created by the Application Document Wizard.

This article describes the structure of the documents, the rules that support them, and how to incorporate the following changes to the wizard and template structures.

• Add rule types to the wizard
• Add selection criteria to the wizard
• Replace images for screenshots and flow diagrams
• Filter property references
• Add supplementary text and screenshots
• Incorporate changes in the Word template generated by the wizard

Note: These are advanced procedures that require the skills of an experiences system architect. They can be applied to a Process Commander V5.5 SP1 system but may not be available on V5.4 SP 2 and V5.4 SP3 systems.

About Template Rules and Document Structure

The wizard uses the two Microsoft Word documents - ApplicationDocument and ProjectDocument. They provide working samples that you can copy and edit to meet your company's documentation requirements.

Documents are configured as instances of Word Template rules in the PegaAccel-Task-DocumentApp class and associated with the Document Application category.

In the Template section, the Document Application value in the Category field identifies that this is a template that will be used by the Document Wizard to create the output.

In the Criteria section, the ApplicationDocumentCriteria value in the Section field corresponds to the name of the Section rule (shown below) that displays on the criteria input screen of the wizard where users select the detail level and rules they want to include in the document.

The images below provide a view of the underlying structure of the Microsoft Word document that is uploaded into and generated by the ApplicationDocument template rule.

Notice that it uses a combination of structural elements to display text and pull data into the document when it is generated.

• Freeform text
• Property references that pull information from the clipboard
• Correspondence rule inserts that specify complex content for the rules and application data included under the high level headings of the document

Viewing and updating the Word document

Follow these steps when you want to view and edit the Word document and load it into a template.

1. Select the template rule you want to change and save it to your RuleSet. 
   Note: The PegaApp-Definition RuleSet must be a prerequisite of your RuleSet version. \
2. Click Edit Word Template to open the template in Microsoft Word. This grays out the button on the rule form while it is in editing mode.
3. Enable the display of the field codes to see the property and rule references in the Word template.
   • Click  at the top left corner of the window and select .
   • Display the Advanced options and scroll to the Show document content section.
   • Select the Show field codes instead of their values check box.

   

    
4. Edit the Word document and Save it. 
5. Click Upload File. 
6. When the load completes, click Save. 

Adding Field Codes to a Word Template

If you want to add new correspondence and property references to a template, add the field codes and format them as described below.

1. Position your cursor at the point in the template where you want to insert the field code.
2. Press Ctrl and F9 to insert a pair of empty curly brackets {}.
3. Type the field code between the brackets
   • The format for a property reference field code is {pega:reference.PropertyName}
   • The format for a correspondence rule field code is {pega:insert corr=Name of the Correspondence Rule}

Adding a Rule Type to the Wizard

To add and populate data for a rule type for Document Wizard template, you must:

• Add a checkbox to the criteria section of the wizard
• Create a section that maps the data that is selected in the wizard into the document
• Add the content to the template

Adding a Checkbox

You add a checkbox to the criteria selection screen of the wizard to give users the ability to control whether or not the section containing the rule data is included in the document.

1. Create a true/false property that AppliesTo the PegaAccel-Task-DocumentAppclass and save it to your RuleSet. 
   Note:  To save rules into the PegaAccel-Task-DocumentApp class, the Pega-AppDefinition  RuleSet must be listed as a prerequisite for the RuleSet version in which you save the property.
2. Save the CustomChaptersCriteria section rule to your RuleSet.  This section is empty by default and included directly under the default set of checkboxes in the SelectApplicationChapters section that is referenced in the Criteria of the template rule.
    
   • Add a checkbox for the property you created.
   • Click Save.
      
    See the ApplicationDocumentChapters section rule for an example.
3. Optionally, update the model rule for your document template to determine whether the checkbox should be checked or not by default. PegaAccel-Task-DocumentApp.FullDetailCriteriaModel. is an example.

Creating a Section

To create a new section for a rule type, the idea is to take pieces of rule data and display it in a meaningful way in the document.

For example: create a section named Document with an Applies To class of the rule type want to document. The section would display a header, include the standard section named DocumentRuleHeader and contain the logic of the rule. DocumentRuleHeader is provided out of the box and includes information about applies to class, rulename, RuleSet/version and so on.

1. Determine which rule properties to document.

• Open an instance of the rule.
• Click the icon to display the XML data structure of the rule.

• Create a section rule to display the data. For example, if you want a simple section that documents a Declare Expressions rule, you would create a section rule named Declare-Expressions.Documentthat would look something like this:

   

  

  Note: 	 is the syntax for a tab and useful and important syntax when you want to line up data in the document.

Adding the content to the Template

To add content, create a correspondence rule that applies to the PegaAccel-Task-DocumentAppclass and save it to your RuleSet . Then, reference it in the Word document.

Note: To save rules to this class, the PegaApp-Definition RuleSet must be a prerequisite to your RuleSet version.

Use the following structure when you configure the correspondence rule.

1. All text should be contained within an <html> tag.
2. (Optional) If the section can be conditionally included based on a checkbox property, the content of the html tag should be contained within a <pega:when> tag that checks the value of the property.
3. Include the standard document style sheet AppDocStyle to automatically style tables with a background color on the header row, cell borders, etc..
4. Enter a header for the section.
5. Include a DocumentList section and its parameters. Four parameters define the layout of the rules in the document as a list by including a section to document each rule or as a table.
   • ViewClass- the class of the rule you want to list in the section. This value can specify an abstract class.
   • ListViewClass - the AppliesTo class of the list view. If left blank, the value defaults to the ViewClass parameter. A value is required for the parameter when the ViewClass parameter specifies an abstract class such as Rule-Connect-.
   • LiveViewName - the name of the list view you want to use. Use the out of the box list view ListToDocument that applies to Rule-. If you want to document the rules in a table format and want to change the column structure, you can copy this list view to another applies to class and update it.
   • SectionName - specifies the name of a section to include for each result returned by the list view. Use this if you want to document the logic of a rule rather than just listing it in a table. If the value is left blank, the results appear in a table format with each result appearing as a row in the table.

   The following example illustrates the five configuration points that form the correspondence structure.

   

Filtering Properties in Rule References

Properties are included in the Rules Referenced section of a document when a user selects Referenced Properties and Entity Relationship Diagrams as part of the Work Type criteria in the wizard.

To filter properties and prevent them appearing in the output document, you override the PegaAccel-Task-DocumentApp.FilterReferencedProperties activity rule.

A java step in the activity creates a clipboard page containing two string list properties that list rules and classes that should be filtered out of the document.

• pyRuleNames
• pyClassNames

When processing referenced property, the lists are used to compare the property's pyRuleName and pyClassName against each value in the list using a a starts with comparison. It there is a match, the referenced property is filtered out of the document. For example: If you add “History-“ to pyClassNames then all properties with a pyClassName starting with “History-“ are filtered out.

Overriding Images for Screenshots and Flow Diagrams

You can configure an override image to use in place of a screenshot or a flow diagram in the document by creating a binary file rule and uploading the image. Usually, this is done to workaround screenshots that are too small, too large, do not show the content you want, or generate errors during screen capture.

1. From the Class Explorer, select New > Technical > Binary File.
2. Enter the App Name (Directory). The value must be webwb.
3. Enter the File Name. The name must match the pzInsKey of the rule that this binary rule overrides except that the spaces in the key are replaced with underscores and the "#"and "." characters are omitted. For example:

4. To override a rule with the key    RULE-OBJ-FLOWACTION MYAPP-SAMPLE STEP1 #20080105T124530.750 GMT

   The file name must be                 RULE-OBJ-FLOWACTION_MYAPP-SAMPLE_STEP1_20080105T124530750_GMT

5. Enter the File Type (Extension). The value must be jpg, gif, png, bmp, or tiff.
6. Click Save.

See the online help topic: About Binary File rules

Including Additional Information and Screenshots for a Work Type

You can create a template rule that automatically pulls supplementary information and/or screenshots into the document section for a work type when that work type is selected in the wizard and included in the document. This is static text and not intended to pull in additional data from the clipboard or a rule. 

1. Create a Microsoft Word document that contains the supplementary content you want to add.
2. From the New menu, select SysAdmin > Word Template.
3. In the Applies To field, select the Implementation Class of the work type.
4. In the Purpose field, enter the same value you selected for the Applies To value and append either _top or _bottomto the value as an indicator of whether you want the information inserted at the beginning.
   • Appending _top includes the template at the beginning of the work type section
   • Appending _bottom includes the template at the bottom of the work type section.
     
     For Example: AlphaCorpFW-Work-Request_top inserts the text of this document before the standard section text when the Request work type is included in the document.
    
5. Leave the Category and Criteriafields blank.
6. Click Upload File.
7. When the upload completes, click Save.

Return to About the Direct Capture of Objectives