We've all been there: you've diligently built and executed your Automated Test Framework (ATF) tests, and the results are a crucial record of your instance's health and successful upgrades. But then comes the moment when you need to share these results with stakeholders, management, or auditors.
You go to the ATF Test Results, see the list of passes and failures, and think:
- How do I easily compile these into a professional, shareable document?
- How can I include all the critical screenshots and step details for solid evidence?
- Do I have to manually piece together results from multiple test runs for a comprehensive view?
In this blog, we'll explore a custom solution that tackles these challenges head-on. We'll guide you through building an ATF Report Generator that allows you to create clean, professional, and branded PDF evidence reports directly from the ServiceNow platform, whether for a single test result or a combined batch.
This reusable tool will transform how you present your ATF evidence, making it quick to generate, easy to consume, and perfectly aligned with your company's branding.
This tool was demonstrated during July 3rd, 2025 session of Platform Academy, titled "Beyond the Basics: Enhancing ServiceNow ATF with Custom Reports". Post event blog can be found here, and you can watch the session recap here.
Solution Architecture
Our custom ATF Report Generator is built around a few core ServiceNow components:
- User Interface (UI Actions): To trigger report generation directly from ATF Test Result records or lists.
- Application Logic (Script Include): The central engine (ATFReportGenerator) containing all business logic for data retrieval, HTML rendering, and PDF conversion. It's client-callable and leverages core APIs like GlideRecordSecure and sn_pdfgeneratorutils.PDFGenerationAPI.
- Administration & Logging (Custom Log Table & System Properties): A dedicated u_atf_report_log table provides an auditable history of all report generation activities, including who ran the report. System properties allow administrators to easily configure behavior (e.g., atf.report.debug_mode) without modifying code.
- Security Model (Access Roles & ACLs): A full suite of ACLs protects the application's tables, script includes, and properties, ensuring only authorized users can execute reports or modify the configuration. A dedicated role, such as atf_report_admin, controls administrative rights over the application's components.
Prerequisites for Implementation
Before you begin, ensure the following are in place:
- Enable ATF Screenshot Properties: Navigate to Automated Test Framework > Administration > Properties and ensure screenshot capture is enabled during test execution.
- Verify PDF Generation Plugin is Active: The ServiceNow PDF Generation Utilities plugin (com.snc.pdf_generator) must be installed and active on your instance. Check this via System Definition > Plugins.
- Proper UI Action Configuration: For any UI Action you create to trigger report generation, ensure the "Client" checkbox is checked. If it's not, the OnClick function will not execute, and the script will never be called from the browser.
Implementation Guide
Let's follow the structured approach outlined in the flowchart to implement the solution.
Disclaimer: The code provided in this blog post is intended as an example and is provided "as is" without any warranty of any kind, either express or implied. It is the responsibility of the user to thoroughly test the code in their own environment to ensure it meets their requirements and functions as expected. The author and publisher disclaim any liability for any damages or issues that may arise from the use of this code.
Phase 1: Foundation
This phase establishes the core components for data storage and branding.
Create a New Scoped Application (Recommended)
It's always best practice to contain custom development within a scoped application.
- Navigate to System Applications > Studio.
- Click Create Application.
- Name your application, e.g., "ATF Report Generator".
Create Custom Table (atf_report_log)
This table will store a history of all generated reports.
- Create a new table named atf_report_log.
- Add the following columns:
- Report name (report_name, String)
- Generated by (generated_by, Reference to sys_user)
- File (report_file, File Attachment)
- Source record (source_record, Document ID)
- Status (status, Choice: Success, Error)
- Type (type, Choice: Single PDF, Combined PDF, HTML)
Upload Image Asset
For branded reports, you'll need to upload your company logo.
- Navigate to System UI > Images.
- Create a new record.
- Important: Name the image file exactly my_company_logo.png (or company_logo.svg if you prefer SVG and adjust the Script Include accordingly).
- Upload your company logo image file.
Phase 2: Security
This phase sets up the access controls for your application.
Create Access Role
- Navigate to User Administration > Roles.
- Create a new role, for example, atf_report_user. This role will be granted to users who should be able to run these reports.
Create ACLs
- ACLs for atf_report_log table: Ensure read, write, create, and delete ACLs are set for the u_atf_report_log table for the atf_report_user role.
- ACLs for UI Actions: Create execute ACLs on the new UI Actions (to be created in Phase 4), requiring the atf_report_user role.
- Script Include Access: For the Script Include ATFReportGenerator, ensure its "Caller Access" is set to "All application scopes" or "Accessible from: All scopes" if it's in Global, or explicitly define the application scope if it's in a different custom app.
Phase 3: Logic
This phase involves creating the server-side scripting that powers the report generation.
Create Script Include (ATFReportGenerator)
- ATFReportGenerator Script Include: This is the main logic handler, see complete script here. A zip file with all script/files needed for this walkthrough is added as an attachment to this blog, you'll find it at the end.
- Create a new Script Include named ATFReportGenerator.
- Set Client callable to true.
- Copy the provided JavaScript for ATFReportGenerator into the script field.
- Core Public Methods: This script includes generateHTMLReport(), generatePDFReport(), and generateCombinedPDFReport().
Phase 4: UI
This phase focuses on creating the user-facing elements that trigger the report generation.
Create UI Actions
Create the following UI Actions on the sys_atf_test_result table:
Generate PDF Report (Form button)
- Name: Generate PDF Report
- Table: Test Results [sys_atf_test_result]
- Form button: true
- Client: true
- Action name: generate_pdf_report_new
- Onclick: invokePDFReportGeneration();
- Condition: !current.isNewRecord() && current.status != '' && current.test != ''
- Script: Copy the full script here.
Generate Combined ATF Report (List button)
- Name: Generate Combined ATF Report
- Table: Test Results [sys_atf_test_result]
- List button: true
- Client: true
- Action name: generate_combined_atf_report_new
- Onclick: generateCombinedReportFromList();
- Condition: !current.isNewRecord() && current.status != '' && current.test != ''
- Script: Copy the full script here.
Secure UI Actions
This involves applying the ACLs created in Phase 2 to the UI Actions. Ensure that only users with the atf_report_user role can see and click these buttons. This is typically done by configuring the UI Action's "Condition" field or by creating dedicated sys_ui_action ACLs.
Phase 5: Testing
Once all components are in place, it's time to test your solution.
Assign Roles & Test
- Assign Roles: Grant the atf_report_user role to yourself and any other users who will be testing the report generation.
- Test:
- Generate a Single Report: Navigate to an ATF Test Result record (sys_atf_test_result) and click "Generate PDF Report".
- Generate Combined Reports: Go to the sys_atf_test_result list, select multiple records, and use the "Generate Combined ATF Report" button at the bottom of the list.
- View Report Logs: Navigate to ATF Report Logs (your custom table) to see a history of generated reports, including direct links to download the files.
If "Tests Pass?", you can proceed to Deploy. If not, you will need to Fix Issues and re-test.
Deploy
Once testing is complete and successful, you can deploy your application to higher environments.
Future Enhancements
Here are several ways to make this better:
- Intelligent Failure Routing: Utilize Now Assist and Automation Engine to reduce triage time and notification fatigue by ensuring the right person is notified immediately of test failures.
- Flow Designer Integration: Allow report generation to be easily triggered by any platform event, such as the completion of a test suite, using Flow Designer.
- SharePoint/External Storage Integration: Create a centralized, auditable repository for all test evidence outside of the ServiceNow instance attachments.
By implementing this custom solution, you can significantly enhance your ATF reporting capabilities, providing clearer, more professional, and easily accessible test evidence.
How would you improve this to meet your testing strategy needs? Let me know in the comments.
