Example: Creating a Custom Report (With Overwrite)

In this example, you will create a custom report that uses the :overwrite option to specify that only a single mark is written to the message log each time for any given key. You can add :overwrite for reports in which you only want one entry written to the report, regardless of how many actions were triggered by a single message.

This report will keep track of the number of messages sent to managers in an organization. In the example organization, there are three levels of managers: executives, middle managers, and team managers. There is a policy list associated with each level of management, and list membership is as follows:

  • executives belong to all three policy lists: executives, middle-managers and team-managers
  • middle managers are members of: middle-managers and team-managers
  • team managers belong to their list only: team-managers

Using :overwrite will ensure that the custom report will count each message recipient only once, regardless of whether the recipient belongs to multiple policy lists.

  1. Edit the PureMessage Policy

    Marks for custom reports are not logged unless you an add an action for each value that you want reported. You can add a policy mark action to an existing rule, or, if necessary, create a new rule. Although this example shows the lines that you must insert in the policy.siv file, you can also modify the policy as necessary using the Policy Constructor. For more information, see "Editing the Policy" in the Manager Reference. This custom report requires the following rules:

    
    # attr NAME=Recipient is a team manager
    if envelope :memberof  "to" "team-managers" {
         pmx_custom_mark :overwrite "list_member" "TeamMan";
    }
          
    # attr NAME=Recipient is a middle manager
    if envelope :memberof  "to" "middle-managers" {
         pmx_custom_mark :overwrite "list_member" "MiddleMan";
    }      
          
    # attr NAME=Recipient is an executive
    if envelope :memberof  "to" "executives" {
         pmx_custom_mark :overwrite "list_member" "Exec";
    }

    Notice that the last line of each rule contains a pmx_custom_mark action. This example uses the :overwrite option, which specifies that only a single mark is written to the message log each time for any given key. The key specified in all cases is list_member. In this case, because the action for executives is processed last, any other marks are overwritten if the message is sent to a person who belongs to more than one list.

    Note
    It is important that you apply :overwrite to all pmx_custom_mark actions for a specific key, or not at all. Failure to do so will affect the accuracy of the report. For more information, see the pmx_custom_mark man page.

    The key that you enter in the next step must match this key (list_member) exactly. Each action has a unique value (for example, "MiddleMan"), which must also exactly match a corresponding entry you will enter in step 2.

  2. Register the Report

    Now that you have created the necessary logic in the PureMessage policy, you must use the pmx-reports-custom tool to register the report. This must be done at the command line, as the PureMessage user ("pmx6" by default).

    1. The values (categories) for the report must be added by way of an external file. At the command line, create a file called Mgr_Message_Report that includes these values:
      
      TeamMan
      MiddleMan
      Exec
    2. Register a report that contains the values shown below. At the command line, run:
      pmx-reports-custom add --key list_member --title "Messages to Management" --file /tmp/Mgr_Message_Report

      The --key must exactly match the key specified in the corresponding policy marks. The --title is the name of the report that will be displayed on the Reports page. The --file is the path to file containing the report values.

      The --key that you assign must be lowercase. If not, you are prompted to change it. You are then prompted to run pmx-profile sync-to-db --force --resource=reports_config.

      If you want to modify the values of the report, edit the file (in this case, Mgr_Message_Report), and run pmx-reports-custom update. For a complete list of commands see the pmx-reports-custom man page.

  3. Synchronizing Servers with the Database

    This step is required to update the database and any edge servers in your deployment:

    pmx-profile sync-to-db --force --resource=reports_config
  4. Restart the Mail Filter

    To add the changes performed in the previous steps, you must restart the mail filter. At the command line, run:

    pmx-milter restart
  5. Test the Report with Mail

    To ensure that the custom report is working as expected, process some messages that are designed to trigger pmx_custom_mark actions, and then gather new data for the message log.

    1. Pass mail through your PureMessage deployment that will trigger report actions.
    2. At the command line, run:
      pmx-reports-consume-message-log --v2
      Note
      Depending on when this default scheduled job was last run, it could take several minutes to consume the report data.
    3. Navigate to the Reports page in the Groups Web Interface. The custom report is displayed in a new section at the bottom of the Report Types sidebar.
  6. [Optional] Schedule the Mailing of Custom Reports

    Use the pmx-reports-mailer-v2 command to run and mail custom reports.

    pmx-reports-mailer-v2 --custom "Messages to Management"  --mailto me@example.com

    For more information, see "Managing Scheduled Jobs" in the Manager Reference.