Skip to main content
This content has been archived and is no longer being updated. Links may not function; however, this content may be relevant to outdated versions of the product.
LinkedIn
Copied!

DCO 6.1 - Extending the Document wizard

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:

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
Notes:

Because some of these customizations are sophisticated changes that modify the user interface of the Application Document wizard itself, they are best performed by an experienced system architect.

These customizations require the availability of a production RuleSet as described in DCO 6.1 - How to customize Application Document templates. Some of the scenarios require completion of the steps in DCO 6.1 - How to customize Application Document templates before beginning the steps in the scenario.

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:

Table of RuleSets

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:

Table of navigation rules in ESupply

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 categoryProcess 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.

New correspondence rule

  1. On the Corr tab, click Source Mode icon to switch the editor to Source mode.
  2. 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" />

Correspondence rule for navigation rules list

  1. Save the correspondence rule (Save icon).

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:

<pega:include name="AppDocStyle" type="Rule-Obj-HTML"></pega:include> Includes the standard document style sheet AppDocStyle to automatically style the table in the output document with a standard header, cell borders, and other styling.
<H1>Navigation</H1> Specifies the level and text for the heading in the output document that comes before this new section. Here, we're using an <H1> to make this a top-level heading in the document.
tools.putParamValue( "ViewClass", "Rule-Navigation" ) Specifies the rule type. Here, we use Rule-Navigation to get the list of navigation rules included in the document.
tools.putParamValue( "ListViewClass", "" ) Specifies the Applies To class of the list view that reports on the instances of the rule type. If set to "", it defaults to the ViewClass. A value is required here when the ViewClass specifies an abstract class (like Rule-Connect-).
tools.putParamValue( "ListViewName", "ListToDocument" ) Specifies the standard ListToDocument list view, to include the standard default columns in the table in the output document.
tools.putParamValue( "SectionName", "" ) When "" is specified for SectionName, the output is a table with each rule instance as a row in the table. While a named section rule can be defined for more sophisticated output formatting, the simple case is to use "" to get the standard table.
<pega:include name="DocumentList" type="Rule-HTML-Section"></pega:include> Includes the standard DocumentList section that defines how the rule information is presented in the table in the output document.
Parts of the correspondence rule definition:

Labeled 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.

My Word Template rule

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

Contents page of Word template file

  1. 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:

New field code in Word template file

  1. 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.

Field code reference to OurNavRules

  1. Save the Word file. Then click Upload File in your Word Template rule to save the updated Word template document file.
  2. Click Save icon to save the rule with the updated file.
Run the wizard to test:
  1. Click Pega button> Application > Tools > Document to start the wizard.
  2. Select your custom template in the Template field.

Select custom template

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

Create Document wizard tab

  1. Click Create Document 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:

Navigation section in generated document

Return to top

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.

py properties in output document

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 Technical category and then select the Activity category.

Activity category in Rules Explorer

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

Pick values window

  1. 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.
  2. Click Save As to save a copy of the rule to the RuleSet you created previously to hold your customized rules (for example ESupply_templates).
  3. 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.

FilterReferencedProperties activity

  1. 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.

  2. 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:

Code to exclude py properties

Results in the following output:

Resulting output document excluding py properties

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.

Return to top

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 Rule Data icon 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.

pzInsKey in Rule Data

  1. 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
  2. In the Rules Explorer, right-click the Technical category 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.

New Binary File rule

  1. In the Binary File rule form, click Upload File. Browse to the image file that you want to use and upload it.
  2. 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.)
  3. Click Save icon 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

Return to top

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 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 (Save icon) the rule form.

Word Template for content at top of work type section

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

Return to top

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.

New property IncludeOurNavRules

  1. 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 Save As icon 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 checkbox

Cell Properties for the label:

Cell Properties for the checkbox's label

To preview how the checkbox looks at runtime within the wizard's Select Criteria step, click Related Rules icon and select Referencing Rules to find the sections that reference the CustomChaptersCriteria section and open one of those rules. In that rule form, click Previewto 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 Open rule icon next to the field. In the window that opens, select your production RuleSet and click Create.

  1. 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"

IsOurAppTemplate When rule

  1. Save the When Condition rule.
  2. Update the Cell Properties for the checkbox's label also so that it is only visible for the condition.
  3. 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".

Model updated to set checkbox selected by default

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 Source mode 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.

Condition logic added to 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.

Return to top

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

Navigation section in generated 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 Rule Data iconto 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.

Rule data for navigation rule

  1. 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.

New section rule dialog for DocumentUsage section

  1. Click the HTML tab and clear the Auto-generated HTML checkbox.
  2. 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.

HTML code for including usage information for navigation rules

  1. 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.
  2. Open the correspondence rule OurNavRules created in Scenario 1.
  3. 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.

Code in OurNavRules correspondence rule to use the new DocumentUsage section

  1. 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.

Output document with the detailed information about the ManagerReviewContext navigation rule

Return to top

Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us