Application Technical Quality Version 1.
A unified technical quality dashboard for all your apps
Table of Contents
Table of Contents ............................................................................................................................................... 2
1. Intended Audience ..................................................................................................................................... 3
2. Component Description ............................................................................................................................. 3
3. Business Problem ....................................................................................................................................... 3
4. Architecture Diagram ................................................................................................................................. 4
5. Compatibility and Prerequisites ................................................................................................................. 4
6. Installation & Preliminary Setup ................................................................................................................ 4
7. Detailed Configuration ............................................................................................................................... 5
7.1 ATQ Server ............................................................................................................................................5
7.2 DEV Server ............................................................................................................................................7
7.3 Service Authentication .........................................................................................................................9
8. ATQ User Dashboard (User Guide) .......................................................................................................... 10
8.1 Initial run.............................................................................................................................................10
8.2 Executive Dashboard ..........................................................................................................................10
8.2.1 Subscribed application ...................................................................................................................... 10
8.2.2 Violation summary ............................................................................................................................ 11
8.2.3 Trend of violation index..................................................................................................................... 11
8.3 Application Dashboard .......................................................................................................................12
8.4 Area of Impact Dashboard ..................................................................................................................12
8.5 Event Management ............................................................................................................................13
8.5.1 Event management without Agile studio integration ....................................................................... 15
8.6 Mapping of Area of impacts and respective review items .................................................................16
9. Additional Configurations ........................................................................................................................ 17
9.1 Agile studio configuration ............................................................................................................17
9.2 Extensions to integrate with other Project management frameworks........................................18
9.3 Job schedulers and their default configurations ..........................................................................19
9.4 Enabling Role/team-based view for the applications ..................................................................19
10. Procedure To Add New Custom Review Items To ATQ ........................................................................... 19
11. Things to know ......................................................................................................................................... 20
12. Sample Data ............................................................................................................................................. 20
1. Intended Audience
• System administrator /Dev leads – To install and configure the application technical quality (ATQ)
application
• LSAs/ Development teams / Delivery managers – To review the application dashboards for
monitoring and tracking of the application(s)
• Account executives – To view the integrated dashboard of multiple applications in the enterprise.
2. Component Description
Application Technical Quality (ATQ) is a development governance application that gives a comprehensive
view of an application’s technical quality in areas like “Low code compliance”, “Best practices”,
“Performance” and other software abilities by doing a static-code analysis. It can also be extended to report
on run-time persisted data (elaborated in the subsequent section). It captures the violations and deviations
from the established technical standards and presents them in a readable and actionable manner. It provides
a platform to execute common utilities that assist development teams in identifying the deviations from the
established development standards and presents them in an easily readable format.
ATQ application can be hosted and configured on a dedicated instance, to monitor the technical code quality
of multiple applications in the enterprise. It is recommended to be hosted on a stand-alone instance if the
applications to be monitored in the enterprise are large in number and data accumulated is expected to
grow at a faster pace. However, it can also coexist with other applications on the same instance for smaller
enterprises.
This application has two parts to it, one deployed on the applications to be monitored and the other on the
dedicated system, to display the identified violations on a dashboard.
i. ATQ Dashboard Application: The dashboard application that needs to be deployed in the
dedicated host server.
ii. AppTechnicalQualityMetrics Component: This is part of the parapets component. This
component must be installed on the application to be monitored. This component is responsible
for collecting all the technical quality metrics from the application and sending them to the ATQ
host server for reporting.
3. Business Problem
• Manual code reviews do not give 100% coverage and takes lot of time and effort.
• With aggressive development and release cycles, there is a need for a robust, reliable, and
governance tool to uphold the development best practices.
• Need for an automated tool to identify violations vis a vis manual verification
• A serious need for a quantifiable way for executives/ manager/ architect / developer to get the
technical quality of applications and be able to see a unified view for all the metrics.
ATQ in combination with Parapets and a few platform utilities like Low code compliance, legacy layout
sections etc., addresses the above business problems, with great elegance. Please go through the document
for more details.
4. Architecture Diagram
Figure 1 : ATQ Architecture diagram
5. Compatibility and Prerequisites
• Tool is compatible with all Pega 8.x versions
• Prerequisite: Parapets component
6. Installation & Preliminary Setup
Follow the steps below to complete the preliminary setup of ATQ:
Important Note: ATQ primarily relies on static code analysis done by Parapets and other platform tools like
Low code compliance, legacy layout sections etc. So, it is strongly recommended to be only used to monitor
the development servers and the violations reported be analyzed and fixed before the code is promoted to
higher environments like QA, staging, production. PDC is designed for production monitoring.
a. Install Parapets in one or more development servers. Hereafter this instance will be referred to as DEV.
Follow the instructions on the Parapets component’s installation document and add the component to
your application
b. Install ATQ application bundle in a dedicated instance. Hereafter this instance will be referred to as ATQ.
Create vanity URLs / Published URL with https enabled for all your DEV instances. This is to secure the calls
between ATQ and Dev applications instances, using TLS/SSL certificates. However, this will be optional if
all the applications are within the same network/Intranet behind firewall.
The scheme of the setup of ATQ and DEV is shown in below figure.
Figure 2 : ATQ and DEV servers
7. Detailed Configuration
This section explains the steps to be followed to configure the ATQ and DEV servers to integrate and
transmit the information.
7.1 ATQ Server
Perform the steps below on the ATQ server.
1. Log in with Pega default administrator credentials (
[email protected]) and enable
“ATQAdmin” operator. Set a new password for this operator as per your organization’s security
guidelines.
2. Logout and login as “ATQAdmin” using the password set in the above step.
3. Open the data type “ApplicationInfo” as shown in below figure. Each record in this data type
corresponds to a DEV server being monitored by ATQ.
Figure 3 : ApplicationInfo data type
4. Add records to this data type for all the dev servers to be monitored, with the following details.
Column Name Value Required/ Sample values
Optional
URL to monitor DEV instance URL (Vanity URL Required https://labXXX.ABC.com/pr
suggested) web or
http://22.22:8080/prweb
Application ID Application rule id (that is to be Required CarRentals
monitored by ATQ)
AppVersion Application version Required 01.01.01
App Full Name Application name (pyLabel) Required Car rentals
App Short Name Short name of the application Required CarRent
is Active True or False; to toggle the Required True
monitoring on and off
Vertical/Domain Not Applicable Optional
External App ID Not Applicable Optional
Dev App The application that is used for Required CarRentStage
development (where you create
branches). This application is used
to check if Parapets is in use.
Dev app Version Dev app version Required 01
Current Version Subscriber application release Required 01
number, please default this to a
number (like 1 ,2 etc.) if your
product doesn’t follow any
versioning for releases. This is to
have tracking of the quality
improvements across such releases.
PDCAppString Not Applicable Optional
PDCSystemNam Not Applicable Optional
e
Column Name Value Required/ Sample values
Optional
ApplicationsCSV Enter all the applications that you Optional CarRental, HomeRental
would like to monitor as a comma
separated value. This list can be
stacked applications following the
dependency or different
applications without any
dependency.
Please note that the built-on apps
would not get automatically added.
Configure this value only if you want
other applications in the server to
be monitored, if not leave it blank.
5. Enable the operator “[email protected]” and update the password based on the security
policies of your organization.
7.2 DEV Server
Perform the steps below on all the DEV servers with which the ATQ server will integrate to collect the
information.
1. Login into the DEV server as an administrate who has access to the Dev studio
2. Enable operators [email protected] and ATQUser. Set the passwords for these operators as
per the security policies of your organization.
[email protected]: This operator will be used for REST service authentication from the ATQ
server.
3. On the operator record of ATQUser, change the access group to that of the administrator access
group of the development application (where you create branches for development).
4. Login with the operator id [email protected] using the password that was set in the earlier
step. Open the current application rule, which will be ATQApplicationsWrapper v8 and add the
application to monitor by ATQ as a built-on application, as shown in below figure (For example:
CarRentals).
Figure 4 : Update the built-on application
5. If your Pega platform version is 8.4 or above → Open Configure → System → General → System
Runtime Context and add ATQApplicationsWrapper, as shown in below figure.
Figure 5 : Update System Runtime Context
If your Pega platform version is below 8. → Update ASYNCPROCESSOR requestor type with
“ATQApps:Admin” access group, as shown in below figure.
Figure 6 : Update ASYNCPROCESSOR requestor type
6. Update DSS “ATQServerURL” with ATQ instance URL, as shown in below figure.
Figure 7 : DSS ATQServerURL to hold the ATQ server URL
7.3 Service Authentication
ATQ Server and the DEV servers communicate and transmit the data using REST Services integration.
Follow the steps in this section to update the authentication details on these servers to facilitate a
successful and mutual integration. Refer the below Figure for a quick understand of the involved operator
ids and authentication profiles.
Figure 8 : Operator Ids and Auth profiles on ATQ and DEV servers, for mutual integration
On ATQ Server
1. Login to the ATQ server with operator id ‘ATQAdmin’
2. Open the Authentication profile ‘ATQAuthentication’.
3. This is a basic authentication profile with operator id ‘
[email protected]’, which will be used to
integrate with the DEV servers. Update the password on this authentication profile with the value
set as password for this operator id in the previous section. This is shown in the below figure.
Figure 9 : Update the password on ATQAuthentication on ATQ Server
On DEV Server
1. Login to the DEV server as an administrator
2. Open the authentication profile ‘ATQService’.
3. This is a basic authentication profile with operator id ‘
[email protected]’, which will be used
to integrate with the ATQ servers. Update the password on this authentication profile with the
value set as password for this operator id in the previous section. This is shown in the below figure.
Figure 10 : Update the password on ATQService on DEV Server
4. Repeat this step on all the DEV servers.
This concludes the mandatory configuration of the ATQ and DEV servers. If you wish to make any other
optional configurations, proceed to this section
8. ATQ User Dashboard (User Guide)
8.1 Initial run
The technical quality information collected by the ATQ application will be synthesized and presented on the
dashboard. On a newly installed ATQ system the dashboard will not show any information until the job to
collect the information from the DEV server is not run. This will be done by the job scheduler. It is
recommended to run the job scheduler manually once to collect the information from all the DEV servers.
8.2 Executive Dashboard
Executive Dashboard is the home page for the ATQ application, which provides a very high level information
on the technical health of the subscribed information. This information is presented in three sections:
1. Subscribed application
2. Violation Summary
3. Trend of violation index
8.2.1 Subscribed application
This section shows a list of all subscribed applications. The following information of each application is
presented.
• Current violation index
• Count of violations
• Percentage changes in the violations from the last run (between n and n-1 run)
• Trend of violation index in the last 4 runs.
Figure 11 : Subscribed applications
8.2.2 Violation summary
This section presents the below charts:
• Pie chart to show the violation distribution by source (Parapets and Platform)
• Heat map to give an overview on the distribution of the violations across application.
Figure 12 : Violation summary
8.2.3 Trend of violation index
This chart represents the trend of the violation index of the applications in the last 4 runs.
Figure 13 : Trend of violation index
8.3 Application Dashboard
Application dashboard provides a complete picture of the technical quality of a specific application. User
can access this page by clicking one of the application tiles under ‘Subscribed applications’.
The information presented here is primarily classified into various Areas of Impacts, such as ‘Low Code
Compliance’, ‘Ease of Upgrade’, ‘Performance’, ‘Security’, ‘Maintainability’ and ‘Best Practices’.
Figure 14 : Application dashboard
A list of all critical violations identified in the latest run are shown.
Figure 15 : Latest critical violations
8.4 Area of Impact Dashboard
Area of Impact (AOI) dashboard provides the details of various ‘review items’ that constitute a particular
AOI. You land on this dashboard by clicking click on the corresponding area of impact tile in the application
dashboard.
Figure 16 : Area of Impact dashboard
Figure 17 : Review item tile explanation
8.5 Event Management
The Event Management module of ATQ provides the work bench to track, trace and fix the violations
identified and reported by ATQ. An Event case is created for each of the violations identified by the
application. Event management enables the development teams to better manage the technical code
quality of the overall product.
ATQ provides integration to Agile studio application, so that you can create Stories / bugs and track your
tech debt. It also provides background jobs to monitor the status of the User stories / bugs created and
takes the next best actions based on the status changes (This is available only for Agile studio customers
as of now).
You can click on on the Review item tile to launch the corresponding event viewer dashboard.
Figure 18 : Event list of a Review item
Below actions can be performed on one or more events:
• Create User Story: (only for Agile studio users) This button is used to select the multiple events and
create a user story in the agile studio.
• Bulk Classify – This button is used to select multiple events and classify them accordingly. Also, this
option provides the ability to tag the events to an existing user story. Validation is performed if User
story exists in case of Agile studio customers.
• Download Review items – Export all the events to excel.
Alternatively, you can click on an individual event case id from the list of events grids and perform an
action on the individual case.
Figure 19 : Event case – review
Figure 20 : Event case - Classify
The below table explains the various ways in which an event case can be classified:
Classification Action Details
App issue – can be fixed In case of a valid violation and planning to fix it through a bug (Agile studio
customers can create bug / tag existing bug from here)
Other application issue To classify the violation as dependent on other built on / dependent application.
(Agile studio customers can create bug / tag an existing bug from here)
Not an issue A false positive. Please be cautious selecting this option as this violation would
be treated as a false positive in all future runs and violation will not be reflected
in any of the ATQ dashboards.
App issue – Limitation This is treated as a justified event. and will be treated as the limitation of the
product.
Tag existing user story This is available only on bulk actions button but not on the individual event. This
is to group the events and tag them to an existing user story.
IMPORTANT NOTE: If an event is classified/tagged to a user story or bug, it will be frozen from making any further
changes/actions. Once the story or bug is addressed/resolved in agile studio, ATQ automatically resolves the
event case. This feature is available only when integrating with agile studio.
8.5.1 Event management without Agile studio integration
In this scenario, the event cases must be resolved manually after classifying and successfully fixing the issue.
Additional action “Resolve the violation” is available for resolving already classified events.
Figure 21 : Resolve Event
8.6 Mapping of Area of impacts and respective review items
S.N Area of impact Review item Severity Platform Potential rule
o. area types
1 Maintainability Rules with inline styles Informational Platform Section
2 Maintainability Potential junk rules Moderate Parapets All
3 Maintainability Deprecated layout sections Severe Platform Section
4 Maintainability Inline java Moderate Parapets All – excluding
properties
6 Maintainability Non-autogenerated UI rules Severe Platform Section
8 Maintainability Recent non-template Moderate Parapets Section
sections
9 Maintainability Custom controls Severe Platform Control
10 Maintainability Legacy layout sections Severe Platform Section
11 Maintainability Potential dead code Informational Parapets All
12 Best Practices Activity type violations Severe Parapets Utility
14 Best Practices Recently added activities Moderate Parapets Activity
15 DX API V1 Harnesses without screen Informational Parapets Harness
Compliance layouts
S.N Area of impact Review item Severity Platform Potential rule
o. area types
16 DX API V1 Sections with visibility Informational Parapets Section
Compliance expressions
17 Ease of Upgrade Rule overrides Moderate Parapets All excluding
properties
18 Low Code Non-autogenerated control Moderate Platform
Compliance
19 Low Code Unsupported control Moderate Platform
Compliance
20 Low Code Embedded section with Moderate Platform
Compliance unsupported page context
21 Low Code No design template Moderate Platform
Compliance
22 Low Code Repeating layout with Moderate Platform
Compliance invalid source
23 Low Code Control with unsupported Moderate Platform
Compliance property source
24 Low Code Custom HTML Moderate Platform
Compliance
25 Low Code Readiness Moderate Platform
Compliance
26 Performance UDF usage Critical Parapets Report definition
27 Security Custom logs Moderate Parapets Activity, Data
transform,
Section, Function,
edit input,
Validate, HTML,
Fragment, JSP and
Control
28 Security Activities with direct Severe Parapets Activity
invocation
9. Additional Configurations
This section explains the additional configurations to be made.
9.1 Agile studio configuration
ATQ provides connectors that are required to integrate with Agile studio (project management application).
If you are using agile studio, please update the following DSS on ATQ server to ‘true’ for enabling the Agile
studio integration.
Figure 22 : DSS to enable Agile studio integration
Also, you can override the following application setting rule to your ruleset and update your corresponding
URLs.
Figure 23 : Application setting to provide the Agile studio URL
9.2 Extensions to integrate with other Project management frameworks
Use the below listed extension rules to integrate with any other Project management frameworks other
than Agile studio.
Class Rule name Rule Type Description
PIA-ATQ-Work-Event PostAnalysis Activity Post action utility to validate and create bugs/user
stories in agile studio based on the classification
PIA-ATQ-Work-Event PostAnalysis Data Post action utility to validate and create bugs/user
transform stories in agile studio based on the classification
PIA-ATQ-Work-Event PostBulkClassify Activity Post action utility for “Bulk Classify” button.
PIA-ATQ-Work-Event CreateUserStory Data Post action utility to validate and create user story
transform in agile studio from “Create User Story” button on
the review events screen. Visible only if agile studio
is in use.
PIA-ATQ-Work-Event ResolveUSEvent Activity Background job utility to resolve the user story
Cases event cases based on the agile studio update.
PIA-ATQ-Work-Event ResolveEventCa Activity Background job utility to resolve the bugs related
ses event cases based on the agile studio update.
9.3 Job schedulers and their default configurations
Following is the list of job schedulers that run on the ATQ server to collect the technical quality metrics from
the DEV servers. The run frequency can be customized as per your organizational requirements.
Job scheduler Frequency Details
ATQMetrics Weekly A run of this job scheduler triggers a call to the DEV
instances to collect and report the required application
quality metric.
If you wish to trigger an ad hoc run (to collect app quality
metrics) on the dev servers, run the activity of this job
scheduler.
ResolveEvents Weekly Disabled by default. Enable if you are an agile studio
customer. Job to resolve the events if the tagged bugs
have been closed in the agile studio.
ResolveUserstory Weekly Disabled by default. Enable if you are an agile studio
customer. Job to resolve the events if the tagged user
stories have been closed in the agile studio.
9.4 Enabling Role/team-based view for the applications
Sample implementation and extension points have been provided for implementing and enabling a role-
based view / team-based view considering your enterprise authentication procedure.
Following data transform can be extended to add your custom logic based on your enterprise authentication
process.
Rule name Rule Type Description
PIA-ATQ-UIPages PreLoadPortal Data Place holder to customize and enable role-based
transform view. That is to display applications based on the
persona logged in. Sample implementation has
been provided based on the LDAP team name
attribute.
PIA-ATQ-Data- TeamMapping Data type Place holder data type for dynamic configuration
TeamMapping of role-based view; depending on the
authentication methodology.
10. Procedure To Add New Custom Review Items To ATQ
To add custom review items, you must add corresponding custom utilities to parapets component first.
Please refer to the parapets user guide for adding custom utilities.
Once you have the custom utility in place in the parapet’s component, please follow the below steps to
include it in the ATQ dashboard for monitoring.
1. Implement save activity to store the collected quality metrics for the review item and include it in the
service activity. Please refer “PIA-ATQ-API . SaveAppMetrics” activity for more details.
2. Update the record for new review item in “Review Matrix” data type. If the new review item is an
addition to the existing “Area of Impact”.
3. Update the record for new “Area of Impact” in “Area of Impact” data type.
11. Things to know
1. If a violation occurs again after successful closure of the event, then the same event will be re-opened.
The count of occurrences will be incremented.
2. The count of recurrences is maintained on each event and is increased by one, for each occurrence
until the event gets resolved.
3. Event cases are not created for some of the potential high-volume violations such as “Rule overrides”,
“Potential dead code”, “Legacy layout sections” and “Low Code Compliance” items.
4. Low code compliance area of impact is available only on Pega Platform 8.6 and beyond.
5. Sample data jar has been provided for understanding the features and demo purposes.
6. “ResolveEvents”, “ResolveUserstory” Job schedulers are disabled. Enable them based on the
requirement.
7. Do not run the job more than once for an application in a day. Violation trend chart might not give the
right representation if it runs more than once in a day.
8. Please wait for at least two full runs to complete to get the data for Overrides, Low code and dead
code violation items.
9. This application is not localizable.
12. Sample Data
Sample data with sample applications are provided as a separate application bundle with the component.
You can use this for testing the features of this application.
