logo: Ytria - Essential Tools for IBM Notes and Domino (Lotus)
Ytria Tech Lab
Articles, Tips, and Code for IBM Notes and Domino Administrators & Developers

Can you beat our 3-step solution to scan and report all encrypted emails across all mail files?

on 5/10/17

picture of paper airplanes

One common requirement we hear about from customers preparing to migrate their mail to IBM Connections Cloud—or platforms such as Exchange or Google, for that matter—is the need to find out if there are any encrypted emails present across all user mail files. They need them decrypted before the migration, or else the documents will be inaccessible on the new platform. After this post, you’ll know how to create a full report of encrypted emails across an entire server by using databaseEZ, scanEZ, and the included automation script. Let’s begin.

When it comes to document encryption, there are three possible scenarios:

1.)    Documents (Emails) are encrypted using secret encryption keys: secret keys are used to encrypt and decrypt the message and shared between people allowed to view the message content.

2.)    Documents (Emails) are encrypted using public key(s) of internal users: emails end up encrypted with the selected user’s public keys, to be only decoded using their secret keys stored in their ID files.

3.)    Documents are encrypted with the public key of external users: This is the same as #2, but uses the previously shared public key of an external user.

Thankfully, you can use scanEZ’s built in Document Analyzer tool to easily identify documents that meet any of the above conditions—even across multiple mail files (see fig. 1).

Screenshot of scanEZ's Document Analyzer

Fig. 1 Use scanEZ’s Document Analyzer to identify documents that match any document encryption scenario.

Now that’s great and all, but the real dilemma is how to extend this functionality across multiple mail files. Basically, how can you get a snapshot of your encrypted email situation across all mail files?

The answer lies in the EZ Suite tools’ automation (Ytria API) functionality that we first introduced in version 12.

Yes, there’s a script for that! Using the following automation script, you can get a report of all the documents fitting the above scenarios across as many databases as you want on a given server. This script requires you to have both databaseEZ and scanEZ. You’ll simply use databaseEZ to select which databases, and then have scanEZ do the scanning.

Here’s the script. Just copy/paste it into any text editor and then save it as an XML file to a location of your choice.

<ytriaAutomation Application="scanEZ" ApplicationVersion="16.5">
<!--This line will set the script's behavior when encountering an error. In this case, it will continue.-->
<onerror continue="true"/>
<!--The following List is named 'TreeOptions'. It defines the Document Analyzer categories that will be checked.-->
<list name="TreeOptions" Action="setVar" Option="CategoryEncryptionSecret"/>
<list name="TreeOptions" Action="setVar" Option="CategoryEncryptionPublicListed"/>
<list name="TreeOptions" Action="setVar" Option="CategoryEncryptionPublicUnListed"/>
<!--The following Loop will iterate over all lines in the List 'TreeOptions'. If an error is encountered,
  the process will move on to next line in the List. For each line the Document Analyzer will process
  documents only using the criteria set in the variable of the corresponding List line. A set of If 
  tests will be carried out to check if data has been found in the Document Analyzer.-->
<loop list="TreeOptions" OnError="Next">
  <ExecuteListAction/>
  <echo value="#### {%Option%}"/>
<!--The following variable, 'hasData', is set to 'no' as a base condition against which a 
  quantity of data found can be compared to.-->
  <setvar hasData="no"/>
  <DocumentAnalyzer KeepAlive="false">
    <SetParam field="DesignElements" value="false"/>
    <SetParam field="Documents" value="true"/>
    <SetParam field="TreeOptions" value="{%Option%}"/>		
    <Select Lines="All"/>
<!--Here, an If condition will test to see if anything has been found in the Document Analyzer search.
  If any data has been found, the visible row count will be more than 0, and thus the variable 'hasData'
  will be set to 'yes' for later use. All documents found will be placed in a virtual My Selection folder.-->
    <if target="DocAnalyzerGrid" test="VisibleRowsCount" Mode="NotEquals" Value="0">
      <setvar hasData="yes"/>
      <MySelection>
        <Setparam Field="MySelectionName" Value="Selection of {%Option%}"/>
        <Setparam Field="TitleOptionType" Value="Formula"/>
        <Setparam Field="TitleOptionFormula" Value="&quot;{%Option%}&quot;"/>
      </MySelection>
    </if>
  </DocumentAnalyzer>
<!--The following If condition states that if the variable 'hasData' equals 'yes', data has been found
  and thus the following processes can be carried out. If it has not been set to "yes", there will be
  no attempt at processing.--> 
  <if target="var" test="{%hasData%}" mode="equals" value="yes">
    <Select target="Tree" Category="Selection of {%Option%}"/>
    <Focus target="Tree" Category="Selection of {%Option%}"/>
    <echo value="**** {%Option%}"/>
<!--Here, a Values operation will be carried out on the focused My Selection folder. Values for 
  the Subject field, Database Path, and UNID will be added to the grid. All of this information will
  be then exported to an Excel file where each type of encryption status infomation will be reported 
  on a separate page. The report will be saved in the same location as this XML file.-->
    <Values>
      <ShowTypeColumns value="false"/>
      <SetParam Target="SelectDocumentItems" Field="AddItem" value="Subject"/>
        <AddCustomColumn name="Database Path">
          <SetParam field="TitleOptionType" Value="Formula"/>
          <SetParam field="TitleOptionFormula" Value="@Implode(@DbName;&quot;!!&quot;)"/>
        </AddCustomColumn>
        <AddCustomColumn name="Document UNID"> 
          <SetParam field="TitleOptionType" Value="System"/> 
          <SetParam field="TitleOptionSystem" Value="UNID"/> 
        </AddCustomColumn>
        <Evaluate/>
          <Export>
            <SetParam field="FilePath" value="EncryptedMails.xlsx"/>
            <SetParam field="SelectedRowsOnly" value="false"/>
            <SetParam field="ExportType" value="Excel"/>
            <SetParam field="Mode" value="AppendRows"/>
            <SetParam field="ExcelSheetName" value="{%Option%}"/>
            <SetParam field="OpenFileOnceGenerated" value="False"/>
          </Export>
      </Values> 
  </if>	
</loop> 
</ytriaAutomation>

 

Just follow these 3 simple steps to complete your report:

1.)    Open databaseEZ on the server of your choice and load the mail files you’d like to scan.

2.)    Select the mail files you want to scan in the main grid, right-click, and choose the ‘Execute Automation File on… > scanEZ’ context menu option.

3.)    Select your saved automation XML file, click ‘OPEN’, and then sit back until the process goes through all mail files.

A thorough report of all encrypted emails will be exported to an Excel file; the results for each encryption status will be shown on separate pages in the workbook (see fig. 2). You will find your report in the same location the saved XML file.

Screenshot of encrypted email report for migration using EZ Suite

Fig. 2 Your report will be exported to an Excel file saved in the same place as the automation script used. The results for each encryption status will be on separate pages.

How did you like this quick tip?

This is only one of a multitude of tips and scenarios you’ll see in our migration webinar coming up on May 17, 2017. Whether you’re moving to another technology platform or simply thinking about upgrading your current one, this webinar will show you how to assess what your environment contains—and whip it into shape.

For better viewer flexibility we’re running two showings of this webinar, the first at 8:00 a.m. EDT (2:00 p.m. Europe Time), and a second at 2:00 p.m. EDT (8:00 p.m. Europe Time). Don’t miss out!

See the full agenda and save your spot for Informed Domino Consolidation for Microsoft Migration on May 17, 2017.

 

 

Save

Save

Save

Save

Save

Save

Save

Save

Save

Save

Print Friendly, PDF & Email

Leave a Comment

To diplay code in your comment, put the code between these brackets: [cc]your code[/cc]. You can also put inline code by using these: [cci]your inline code[/cci]