IBM Cognos and Motio Best Practices Blog

How To Use MotioCI “PDF Diff” To Accelerate The Cognos Upgrade Process

Posted by Sammy Ng on Wed, Jun 20, 2018 @ 11:00 AM

Locating errors in report outputs can be a difficult and complex task. It’s especially challenging if your Cognos system hosts a sea of reports! MotioCI can journey deep into your Development, Production, and QA environments to fish out error-filled report outputs.

The “Diff” feature in MotioCI will show you textual and graphical changes in your PDF outputs of reports and present them side-by-side with full documentation. The Diff feature compares and highlights changes between different versions of reports so you can assess any textual or visual differences that may hinder the functionality of your reports before you upgrade. This feature gives you a proactive approach for a smooth transition in Cognos upgrades.

You can choose to compare:

  • Different outputs of the same report
  • Different revisions of the same report
  • Versions of a report from one Cognos environment to another environment

MotioCI PDF Diff can be used along with automated regression testing which is particularly valuable when working through the Cognos upgrade process. The testing feature of MotioCI helps you by identifying the report outputs with errors and alerts you to them with email notifications. These email notifications can even be customized to varying degrees of importance, so you can focus on the most important items in your upgrade process.

Here we will demonstrate how to use PDF Diff to compare a report in a Cognos 10 environment against another report in a Cognos 11 environment through an automated approach with regression testing.

Using Regression Testing with PDF Diff

The following is a one-time setup that will utilize the "Output Stability" and “Output Comparison” assertions used in automated testing to monitor differences between two reports.

  1. Navigate to the object in your Cognos 10 instance and right-click on the object that you want to perform a comparison against. Select "Add Test Case."

    Click to enlarge

  2. In the Test Case Wizard, add a name to your test case. Make sure "Enable Execution" and "PDF" is checked before you select "Next."

    Click to enlarge

  3. Click only on the “Output Stability” checkbox. The “Output Stability” assertion will store the output in Cognos 10 for comparison against the output in Cognos 11. Select “Finish.”

    Click to enlarge

  4. You will notice that your new test case with the “Output Stability” assertion is now located under your report.

    Click to enlarge

  5. Right-click on "Output Stability" assertion and click "Edit" to configure the settings.

    Click to enlarge

  6. In the "Edit Assertion" window, make sure only the "PDF" checkbox is selected. In the “Visual Difference Level” drop-down menu, you can select “warning” if visual differences are not as important to you than the differences in the actual data. This setting will alert you of any failures for data differences.

    Click to enlarge

  7. Right-click on test case and select "Run Test Case."

    Click to enlarge

  8. Now drag this same test case into the Clipboard to copy/paste to your Cognos 11 environment. This will compare how your outputs will behave between the two environments.

    Click to enlarge

  9. Drag your test case into the report in the target environment which is Cognos version 11.0.2 in this example.

    Click to enlarge

  10. Right-click your test case  > "Add Assertion" > "Data Validation" > "Output          Comparison." The output comparison assertion will fail if the output of this report in the Cognos 11 environment is different from the saved output in the Cognos 10 environment. This is a methodical way to identify the report outputs that are changing from your current environment to the upgrade environment so that you can to take action on them.

    Click to enlarge

  11. In the "Add New Assertion" window, make sure only the "PDF" checkbox is checked        in "Instance Name Prompt." Enter the name of your Cognos 11 instance, which is “Development” in this example.

    Click to enlarge

  12. Right-click on your test case and select "Run Test Case."

    Click to enlarge

  13. You will see if your test case has failed or succeeded. Click on the timestamp to view the details of the executed test case.

    Click to enlarge

  14. If you have a "Failure" status, click on "PDF Diff" to view the differences between the two reports.

    Click to enlarge

  15. MotioCI initializes the diff and displays two images of the PDF output. The left side shows the output in your Cognos 10 environment and the right-side shows the output in your Cognos 11 environment. Here you can see that you do, in fact, have differences in the data from Cognos 10 to Cognos 11.

    Click to enlarge


As you can see, MotioCI can expedite your Cognos upgrade process by alerting you to important changes from your current environment to the new. The Diff feature of MotioCI saves you the time and effort of analyzing differences in report outputs by highlighting exactly what's changed between them.

Register for our Cognos Upgrade Resource List to explore our methodology to improving your Cognos upgrade process!

Cognos Upgrade Resource List

If you have any questions, please leave them in the comment section below

Tags: Upgrading Cognos, getting started with MotioCI, Automated Cognos Testing, Cognos management