prpc rule config clist 33

PRPC Rule Configuration Checklist Version 3.3

Copyright 2013 Pegasystems Inc., Cambridge, MA

All rights reserved.

This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc.

This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described.

This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant.

For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders.

Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document or Help System could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time.

This document is the property of: Pegasystems Inc. One Rogers Street Cambridge, MA 02142-1590

Phone: (617) 374-9600 Fax: (617) 374-9620

www.pega.com

Document: PRPC Rule Configuration Checklist Version: 3.3 Updated: March 2013

Contents About This Document ...................................................................................... 1

Intended Audience ........................................................................................... 1

Related Documents .......................................................................................... 1

Configuration Checklist and Guidelines ........................................................... 2

1. Common to all PRPC rules ............................................................................ 3

2. Property Rules ............................................................................................ 4

3. Edit Validate Rules ...................................................................................... 4

4. Flow Rules ................................................................................................. 5

5. When Rules ................................................................................................ 5

6. Section Rules ............................................................................................. 5

7. Flow Action Rules ........................................................................................ 6

8. Class Rules ................................................................................................. 6

9. Activity Rules .............................................................................................. 6

10. Logging .................................................................................................... 8

11. Utility Functions ......................................................................................... 9

12. Database .................................................................................................. 9

13. Agents .................................................................................................... 10

About This Document This document lists configuration guidelines you can use to help ensure high quality in your PRPC rule configuration. It is presented in a table and checklist format that can be used by your Technical Leads to execute targeted configuration reviews.

It does not list items that are part of the preflight warning library and is based on the 6.3 warning library.

Intended Audience The document is intended be shared with Stream Leads and System Architects. Having insight into how their work is reviewed for quality by the Technical lead will help them build a better configuration.

Related Documents

Name Location Document

PRPC 6.3 Dictionary of Rule Warnings

PDN ID 26482

https://pdn.pega.com/implementation-methodology-dco/prpc-63-dictionary-of-rule-warnings

Standards for rule names, tables, and other objects

PDN ID 26160

https://pdn.pega.com/implementation-methodology-dco/standards-for-rule-names-tables-and-other-objects

Ten Guardrails to Success

PDN ID 25685

https://pdn.pega.com/implementation-methodology-dco/ten-guardrails-to-success

PRPC Rule Configuration Checklist

1

Configuration Checklist and Guidelines This section contains thirteen tables that you can use as a checklist for rule configuration and guideline information for the following configuration categories:

1. Common to all PRPC rules

2. Property rules

3. Edit Validate rules

4. Flow rules

5. When rules

6. Section rules

7. Flow Action rules

8. Class rules

9. Activity rules

10. Logging levels

11. Utility functions

12. Database

13. Agents


2

1. Common to all PRPC rules Topic Code

√ Checklist topic/question and Configuration Commentary

1.1 Is this Rule Required? Rules created for testing and trial purposes need to be removed from the rules DB. Those lying under locked RuleSets should be blocked in a higher RuleSet version so, that they are not carried forward after next skimming.

1.2 Is it NOT possible to use an Out of the Box (OOTB) rule instead and avoid creating this rule? OOTB rules are much more robust and time tested, so they are always preferred over custom rules.

1.3 Can an existing generalized application rule be reused in place of this rule? Rule reuse helps reduce the overall number of rules in the Rules DB, which makes the application easy to maintain over its lifetime.

1.4 Is the Rule name in compliance with Project Naming Conventions? Following naming conventions makes code/rule maintenance easier.

1.5 Is the Rule Purpose evident from the rule name? Follow the rule naming conventions documented in the PDN article ID 26160 titled Standards for rule names, tables and other objects.

1.6 Does the rule belong to the Appropriate Rule set? Placing the rule in the most appropriate RuleSet promotes rule reuse. Delegated rules should be in a production RuleSet (or anything you want to be able to change in production without a full test cycle, but only put appropriate rule types in here - e.g. activities are too easy to make a mistake in and changes should have a test cycle)

1.7 Does the rule belong to the Appropriate RuleSet Version? Wrong RuleSet versions could lead to rule resolution and access related issues.

1.8 Was the rule created in the Appropriate Class / Class Hierarchy? Placing the rule under the most appropriate class is necessary for rule reuse and proper rule resolution.

1.9 Does the rule’s Short Description explain the rule adequately? 1.10 Is the rule’s Full Description well documented?

A rule’s full description is important for long-term rule maintenance and for the purpose of auto-generated documentation. Describe what this rule does in a couple sentences.

1.11 Is the rule’s Usage properly documented? Rule usage documentation is important for long-term rule maintenance and for the purpose of auto-generated documentation. Explain how to use the rule, how it is used, how parameters should be set, or reasons for non-standard coding practices.

1.12 Does the Rule Circumstance make sense for this rule (If the rule is circumstanced) Rule circumstancing is a powerful feature of PRPC, it makes the rule easy to maintain. However, improper usage could lead to unexpected results.


3

Topic Code


1.13 Does this rule comply with the Build for Change approach? The prime focus of PRPC based solutions is to build change-aware applications. Each and every rule in PRPC should be created & viewed with the Build For Change slogan in mind.

1.14 Does this rule comply with the best practice recommendation - Calculate and Edit Declaratively, Not Procedurally? Whenever the value of a property is calculated or validated, you must use declarative rules wherever appropriate. Create a Declare Expressions rule instead of using a Property-Set method in an activity. Use a Declare Constraints rule instead of a Validation rule.

1.15 Are any preflight warnings expressively explained and justified in the History tab, or in the rule’s custom fields?

2. Property Rules Topic Code


2.1 Is the property created with an appropriate Type for its usage? Using the wrong property type could limit rule reuse.

3. Edit Validate Rules Topic Code


3.1 Can this rule NOT be replaced with a Declare Constraint rule? Calculate and edit declaratively, not procedurally.


4

4. Flow Rules Topic Code


4.1 Is the flow rule well commented / annotated? Use the comment symbol to explain important features.

4.2 Is the flow rule readable and understandable? Flow rule should be readable by the business; they will appear in “where am I”. Make sure they are simple, and their layout is consistent across the whole application.

4.3 Is the flow componentised and reusable? Does it use parameters appropriately? Does it follow high cohesion and low coupling?

5. When Rules Topic Code


5.1 There is NO comparison of strings using “==” in this rule? Comparison using “==” should be replaced with .equals or .equalsIgnoreCase appropriately to avoid conflicting results with string interns. Where possible, use the OOTB Function Alias to perform this comparison.

6. Section Rules Topic Code


6.1 When previewing the code, does the section occupy 100% of the width? Do not drop sections inside layout cells. Place them above or below layouts.

6.2 Is the 'Localize?' box checked, when appropriate? If your project is using localization this should be true for every section.


5

7. Flow Action Rules Topic Code


7.1 Do the activities used in the flow action have “Pre” and “Post” prefixes in the names? Using pre and post prefixes to activities called from the flow action makes them easier to identify.

8. Class Rules Topic Code


8.1 Does the class name end with “-“ in case of Abstract Classes?

9. Activity Rules Topic Code


9.1 Is the activity type appropriately selected? 9.2 Is this activity processing limited to a coherent purpose and the number of

steps does not exceed 20? Is the activity not too big and highly cohesive? Consider splitting the activity in multiple activities

9.3 Are there NO hardcoded class names in Page-New/Obj-Browse/Page-Change-Class/Obj-Open/… steps? Reference DCR and GRS declarative page instead (do this from the outset for all classes in a new project)

9.4 Are the clipboard pages created in this activity (Page-New method calls) removed appropriately? Removing temporary clipboard pages is a good practice that reduces memory consumption overhead.

9.5 Are the clipboard pages named appropriately and within the proper context? 9.6 Do the activity steps have enough description documented to understand the

purpose of every step? It should not be necessary to expand every single step to understand how the activity works


6

Topic Code


9.7 Is exception handling used when needed? Think about what may happen when your method fails? For example Obj-Open-By-Handle with lock. Use transition to handle errors on any step that can generate an error (e.g. Obj-*, RDB-*, Commit, ...)

9.8 All iteration steps in the activity are necessary? 9.9 Do not append 'T000000.000 GMT' to a Date to make a DateTime.

This results in midnight GMT rather than midnight local time. To turn a date into a DateTime at midnight in your local time zone use @changeDateTimeTZ(param.Date + "T000000.000", pxRequestor.pyUseTimeZone, "GMT"). You will see many tables at the moment where the time component in the local time zone is sometimes 0100, and sometimes 0000 (in a UK implementation, due to British Summer Time/GMT switchover). This will be eliminated by following the above. Setting a Date value into a DateTime results in time zone conversion. However, this (at least in our case) is done based on the 3-digit timezone code, which is non-unique. In our case BST results in GMT+05:00, but British Summer Time should be GMT+01:00. Avoid using DateTime properties to store Dates for which the time portion is of no interest. A good example of this is Date of Birth. DateTime Properties are subject to Time Zone conversion, which can result in a “moving date” where the time is discarded at display time.

9.10 Do not use pyWorkPage as a step page since it limits reusability. 9.11 Is the activity parameterised?

This greatly augments reuse potential. 9.12 Are declarative pages leveraged instead of procedural retrieval of information?

Use a Declarative Page to cache datasets that are less than 100 records and frequently accessed. Consider using a Declarative Page to cache datasets that are more than 100 records but small record size and frequently accessed.

9.13 Output a message to log whenever an error occurs to aid debugging. 9.14

Can we do Obj-Browse instead of Obj-Browse, Obj-Open? When key is not known and locking is not required, it is generally less resource intensive to use Obj-Browse to retrieve a BLOB (by selecting any unexposed field) rather than doing an Obj-Browse to determine key fields, followed by an Obj-Open.

9.15 Avoid RDB methods unless the interaction is with an external database, or there is no alternative. They are harder to maintain, and if used inappropriately can cause security concerns – especially around the use of the ASIS keyword.

9.16 Especially avoid RDB-Save as it is not part of the transactional model. Where RDB-Save is used, compensating action rules should be defined, and invoked in a rollback scenario.

9.17 Do not use 'Call Rule-Obj-Listview.ShowView' where UI display is not required. Use the 'Obj-List-View' method.


7

Topic Code


9.18 If you are performing a Commit in an activity that is not part of flow processing, you should perform Rollback if an error occurs. This releases any held locks.

9.19 In most cases, Obj-Open/Obj-Open-By-Handle/Obj-Refresh-And-Lock should have Release on Commit checked. If it is not, and the relevant class supports locking, the Page-Unlock method or Work-.WorkUnlock activity should be invoked to release the lock when it is no longer required.

9.20 Where clause fields in Obj-Browse etc. should correspond to indexed columns. Unexposed properties should never be used as selection criteria in report browses. An exception is if an unexposed column is being selected to force BLOB retrieval and knowing the consequences.

10. Logging Topic Code


10.1 Proper use of logging levels. INFO - informational marks the beginning and end of processing milestones (major processing tasks/steps in the code). Limited number of messages to log but visible always (in Production environment). It helps the support verifying that the system is up and running, conducting its processing as expected and that it is in a healthy state. WARN - Similar to informational but represents warning in the system. ERROR - Depict issues occurring during the processing DEBUG - These messages will be displayed when the user is logged in debug mode INFOFORCED - Use this level sparingly. There is no way to disable these messages in production, and overuse of this ability can result in disk space issues as the log file grows.

10.2 Log messages are not inside of loops (low i/o) and do not contain large messages (i.e. xml or binary dumps).

10.3 Do not include customer/sensitive data in log messages.


8

11. Utility Functions Topic Code


11.1 Is the function componentised and reusable? 11.2 Is the function well commented?

It is unlikely all team members will have strong Java. Make it easier for them to understand how the function works.

11.3 Are oLog messages used appropriately? See Topic 10. Logging

11.4 Are there any empty catch blocks? There should at least be an oLog.error(…) message. See 11.5

11.5 Is there code placed inside a try-catch block? Do not have empty catch blocks in java. At the least, the fact that an exception has occurred should be logged to aid debugging. Returning a blank / null value in error scenarios highlights to the calling activity that an error occurred, but gives the user/developer/calling activity no information on what the error was.

12. Database Topic Code


12.1 Do tables without pzInsKey and pxObjClass exist in PRPC Schema? Avoid creating External tables (without pzInsKey and pxObjClass) in the PRPC schema. Prefer to create fully-exposed internal tables where the objective is to remove the BLOB column. External tables are generally intended to be tables over which the project team has no control. Depending on the version of the product being used, there are some limitations in how External tables can be used.

12.2 Declare Index tables should not have a pzpvstream column and should have index on pxinsindexedkey, pxobjclass. The purpose of the RDI tables is to expose data.


9

13. Agents Topic Code


13.1 Rule-Agent-Queue - All agents should be disabled by defaults. Agents should be explicitly enabled on new jvms using data-agent-queue rather than implicitly enabled for every jvm by rule-agent-queue.

13.2 Check that ‘Queue’ tables are being drained. If you have objects ‘stuck’ in now-processing or ‘broken-process’ the application has errors that must be remediated.


10