Distribute Client Reports

This section describes how to use Custom Distributions to distribute completed report packages to account owners and third parties.

Distribute Client Reports

To distribute client reports you need to:

  • Define custom distribution methods using Custom Distributions.

  • Assign the custom distribution methods to clients.

  • Assign the clients to client reporting packages using Maintain Batches.

Work With the Custom Distributions Window

To add and maintain custom distribution methods:

  1. From any Eagle window, click the Eagle Navigator button to access the Eagle Navigator.

  2. Enter Reporting in the Start Search text box.

  3. Click the Reporting Center link to access the Reporting Center component.
    You see the Client Reporting workspace.

  4. Open the Client Reporting folder, and double-click the Administrative folder to see the Client Reporting options.

  5. Double-click Custom Distributions.
    You see the Custom Distributions window.

    Custom Distribution Window

Create a Custom Distribution Method

To add a custom distribution method:

  1. Click Add on the Custom Distribution window.
    You see the Add Custom Distribution dialog box.

  2. Complete the options on the Custom Distribution dialog box.

  3. Click Save.
    You can now assign the custom distribution you created to the clients. See the following section Connect to PACE Clients for details.

Connect to PACE Clients

To connect to PACE clients:

  1. From any Eagle window, click the Eagle Navigator button to access the Eagle Navigator.

  2. Enter Clients in the Start Search text box.

  3. Click the Clients (System Management Center) link to access the System Management component.
    You see the System Management Clients window.

  4. Select a client, and click Edit.
    You see the Clients dialog box appears.

  5. Complete the options on this dialog box, including maintaining the list of parties who will receive a copy of a particular client’s reports. You can also designate the preferred method and format for reports, specify the number of copies, and add address information. Each address record records contains a set of communication types, such as email, archive, mobile, and phone. You can assign a value to each communication type so that a client’s email address or phone number is stored. Information related to how a client receives their client reporting packages is stored on the Distribution tab. You can set up this information on a date sensitive basis, so that the client receives their packages using different methods during different times of the year, or as the default distribution directive.

    Clients Dialog Box
  6. Click Distribution.
    You see the Distribution tab.

  7. Create a distribution directive using the settings on the Distribution tab. You can select the address type and contact method (communication type) for the distribution.
    Communication types are stored in the CLIENT_COMMUNICATION table in the RULES database. There is also a default communication type stored in the RULESDBO.CLIENT table. This value is stored in the DEFAULT_COMM._INST column.

  8. Select an optional distribution category from the Category drop down list. Use distribution categories to maintain one set of clients and run separate batches for distribution to different places.
    For example, if a client has one set of reports distributed via email and another set distributed via the Eagle Portal, they can be managed through a single client using multiple distribution categories, regardless of the frequency of the reports.

  9. To establish a distribution directive, select the category under which a directive falls by clicking the Category dropdown. If a client contains a distribution directive with no associated category, all batches are run for clients that call that distribution directive.

    Clients Dialog Box Distribution Tab

    Additionally, when selecting a report package via the Reports tab on the Create New/Edit Batch dialog box, the Client Reporting prompts you to specify a distribution category for each Advanced Report Profile. If the Categories setting is left blank, the batch is sent to all valid distribution methods, regardless of the value you select for the Category on the Clients dialog box.

  10. You can reduce the number of potential recipients of client reporting packages using the CR_FLAG field, which is stored in the RULESDBO.CLIENT_RELATIONSHIPS table in the Clients module. To access the CR_FLAG field, click the Relationships tab on the Clients dialog box. Click Edit Relationship.
    You see the Select Relationship dialog box.

    Select Relationship Dialog Box
  11. Click the More Fields link to display the More Relationship Fields dialog box.
    You see the More Relationship Fields dialog box. If you do not see the CR_Flag field on the More Relationship Fields dialog box, make sure that the Inventory of Fields record for that column has the Show this field in all editing windows setting enabled. The CR_FLAG field allows client records to be ignored by the distribution engine, allowing the engine to run more quickly when there are exceptions to the distribution.

    More Relationship Fields Dialog Box
  12. You can change the CR_FLAG value to Ignore (0) so that the distribution engine does not recognize the relationship record. When a relationship is added to a client that is missing an address, communication, or distribution record, the CR_FLAG value will default to Ignore (0).

Store Distribution Status Information

Client Reporting stores details about the timing and status of the distribution process. The CR_DISTRIBUTIONS table, which resides in the PACE_MASTERDBO database and relates directly to the CR_BATCH_DETAIL table, retains the timestamp when the distribution engine has completed the distribution of a particular package.

The PINSTANCE value in the CR_DISTRIBUTIONS table is equal to the INSTANCE value of the related CR_BATCH_DETAIL record.

The following columns are also part of the CR_DISTRIBUTIONS table:

  • CODE_VALUE

  • SCHED_DEF_INST

  • STATUS

  • END_DATE

The CODE_VALUE column stores the short description of the communication value used to distribute the package. The SCHED_DEF_INST column stores the INSTANCE value from the related SCHEDULE_DEF record. The STATUS column stores the current status value of the distribution request, and the END_DATE column stores the time that the distribution process completed.

Distributions to the Portal

If you select Eagle Portal as the Distribution Type when defining a distribution method, Client Reporting allows distributions to the Portal at the business group and user level as shown in the Custom Distribution dialog box - Portal Distribution Type.

Custom Distribution Dialog Box - Portal Distribution Type

Additionally, the Subtype field is displayed, allowing you to further define how batches that use the distribution method are distributed. The Subtype you select determines the communication types and values that are available for selection on the Address tab of the Clients dialog box. Options include:

  • None. The Portal communication value on the Clients dialog box displays a text field.

  • Pace User. The Portal User communication value on the Client’s dialog box displays a drop down list of PACE users.

  • Pace Group. The Portal BG communication value on the Client’s dialog box displays a drop down list of PACE business groups.

    Clients Dialog Box - Communication Values

Distribute to Business Groups and Users

When a batch is distributed to the Portal at the business group level, the related record in the database is created differently than a report sent to an individual user. When distributed to a business group, the XML_PACKAGE_LOG record has a UPD_USER value of 'SYSPACKAGE' and the GROUP_ID column is populated with the GROUP_ID value from the PACE_USER_GROUPS table for the selected business group.

When distributed to a user, the XML_PACKAGE_LOG record has a UPD_USER value that matches the PACE user selected as the communication value on the Address tab of the Client’s dialog box and the GROUP_ID value is null.

Distribute to Multiple Recipients

Report packages can be distributed to multiple users through a single client and communication value.

To configure a single client to have its reports delivered to multiple recipients in the Portal, the client’s communication value can be configured as a comma or semi-colon delimited string of the recipients via the Address tab on the Client’s dialog box. This string should not contain spaces.

When the distribution engine encounters this string, it parses the values based on the delimiter, and generates an XML_PACKAGE_LOG record for each recipient, so that each selected user is able to view the report via the Portal. Each of these XML_PACKAGE_LOG records references the same XML_REPORTS_LOG record. In this way, there is only one report package file generated. Each recipient views the same file from the Portal.

Client's Dialog Box - Delimited Communication Value

Client Reporting populates the PACE_MASTER.DBO.XML_PACKAGE_LOG table when distributing client reporting packages to the Portal. In the event that a single report result is distributed to multiple recipients in the Portal, Client Reporting creates a single output file, represented by a single record in the PACE_MASTER.DBO.XML_REPORTS_LOG table. Each recipient of that report is represented by a record in the PACE_MASTER.DBO.XML_PACKAGE_LOG table and can access the report through the location specified in the XML_REPORTS_LOG record.

This process is followed whether several clients own the entity selected in the batch, or a single client has multiple recipients configured in its communication value.

Use the Effective Date

Batches distributed to the Portal populate the begin_date and end_date columns in the xml_reports_log table with the begin and end effective dates of the underlying PACE Report profiles rather than the effective date of the batch. These dates are taken from the pcre_rpts table in the batch. In the event that a batch contains more than one record in this table, the first record in the table is used to populate the begin_date and end_date columns in the xml_reports_log table.

The effective date column (Eff_Date) in the pcre_pkg table is populated with the effective date of the batch.

Client Level Batches

Client level batches distributed to the Portal update the PACE_MASTERDBO.XML_REPORT_INFO table with the entities owned by the clients in the batch. This feature allows Portal users to more easily identify the accounts contained in the package of reports they receive via the Portal.

Overwrites

The Portal distribution functionality contains an overwrite process. To eliminate the number of duplicate reports delivered to the Portal in the event of report resubmissions, logic exists in the distribution process to match on a number of fields and replace existing report results in the database when a match is found. The match criteria consists of the Client Reporting batch instance value, Effective Date, Begin Date, End Date, Advanced Profile instance, Package Recipient, Accounts contained in the package, Portal Frequency and Portal Category.

Distribution Archives

In the Client Reporting’s distribution archive process, when a package is distributed to the Portal and a Custom Archive Rule is selected in the distribution method, the distributed file is stored in the designated archive location and the XML_REPORTS_LOG record available to the recipient via the Portal also references that location.

AutoApproval and AutoDistribution Interface Generation

To implement a custom distribution operation you must create a distribution class that implements the IPaceDistribute interface. The IPaceDistribute interface is defined in the type library advhelper.tlb. By creating a custom distribution class you may extend the distribution options to include for example, FTP, printing to specific locations, faxing to multiple locations, and email.

The distribution function receives two parameters, the file name of the output file that contains the report package images and a parameter string defined in Parameters field on the Custom Distribution dialog box. Using the information in the parameter string, you may create logical arguments to define the distribution mechanism to employ for the particular report package.

Client Reporting includes automated approval and distribution COM interfaces. You may add a class to your Visual Basic project to implement either of those interfaces. From the Project menu item, select either Add IPACEAutoApproval Class or Add IPACEAutoDistribution Class. This adds the interface and the required methods to your project.

Insert your functional code to create approval or distribution functionality. Alternatively, if you right-click in the project explorer window, you can add both of these classes using the popup menu.

Right click menus

Technical Design

The Auto Approval and Custom Distribution functions handle volume processing. To remove the negative impact of Windows hooks, COM processing in the approval and distribution engines is externalized. This prevents the generation of enough Windows hooks to hang individual engine instances.

The Client Reporting engine passes the INSTANCE value from the corresponding CR_BATCH_DETAIL record to Before Run Auto Approvals. This value enables package level information to be retrieved and used with Before Run Auto Approvals.

Auto Approval Messages

The Auto Approval feature returns a default message to the Approval Status record. The Comments value in the Approval Status record is populated with a default value that indicates the resulting status value and the time the approval status value was modified. If the Auto Approval has been coded to return a separate comment value, that value overrides the default message.

Auto Approvals Pending Status

Client Reporting allows you to change rejected auto approvals to a status of Pending. If the approval process rejects an auto approval, you can set the approval to a Pending status, which allows the auto approval to be processed again. This feature is only available for auto approvals and only for auto approvals with a status of Rejected.

Change Approval Status Dialog Box

Auto Approval Internal Tables for Batch Overrides

The PCRE_PKG table includes two columns to support the client level batch override feature through the auto approval process. These include the VARIATION_ID column, which contains the instance value of the variation selected as the batch override for the selected client, and the CONTACT_OVERRIDE column, which is a boolean value that indicates that one or more of the selected client’s contacts has a batch override selected.

In addition, the PCRE_CLIENT_OVERRIDES internal table contains a row for the current client, as well as a row for each of that client’s contacts. The CONTACT_INST value indicates the contact, and the PROFILE_INST and VARIATION_INST values indicate the selected batch overrides. This table is generated even if no batch overrides are selected.

These tables and columns support auto approvals that are built against batches with overrides to retrieve the appropriate override data.

Custom Batch Image Archiving

In the Client Reporting workspace, you can specify a Custom Archive location for the completed images in a batch. Complete the following procedure to view or select an archive folder.

To view or select an archive folder:

  1. Type Maintain Batches in the Eagle Navigator.
    You see the Maintain Batches window.

  2. Select a batch and click Edit Batch.

  3. Click Next twice to access the Reports tab.
    View the Archive Folder column to see the archive location.

    Edit Batch Dialog Box
  4. Click Finish.

Maintain Custom Archive Rules

You maintain the list of archive folders in the Custom Archive Rules window.

To maintain custom archive rules:

  1. Type Custom Archive Rules in the Eagle Navigator.
    You see the Custom Archive Rules window.

  2. Select a rule and click Edit.
    You see the Edit Archive Rule dialog box.
    Each Archive Rule contains a Directory Rule and a File Rule. The Directory Rule specifies the directory or folder structure to be generated and used by the archive process. The File Rule determines the naming convention of the archived image files.

    Edit Archive Rule Dialog Box
  3. Make any changes to the Archive Rule folders, and click Save.

Batch Distributions Window

The Batch Distributions window displays detail on all batch distributions, including the name of the batch, Advanced Report Profile, client/contact, distribution category, communication value, status, communication type, and distribution time.

Batch Distribution Window

Recall One or More Distributions to the Portal

The Recall Distributions link on the Batch Distributions window allows you to recall one or more reports that were distributed to the Portal. This involves deleting the physical file that was distributed, and deleting the database records that indicate an Inbox item in the Portal. This functionality automates file retrieval if a package is distributed in error.

You can recall the distribution if at least one package in a batch status record has moved past the distribution stage and the Portal is the destination.

To recall one or more reports that have been distributed to the Portal:

  1. Select one or more clients on the Batch Distributions window.

  2. Click the Recall Distribution link.
    The reports that have been distributed for the selected clients are deleted from the Portal.
    Once the distribution is recalled, the status column on the Batch Distributions window displays Recalled. The related records are deleted from the following tables:

  • XML_PACKAGE_LOG

  • XML_REPORTS_LOG

  • XML_REPORT_INFO

  • XML_REPORTS_LOG_DETAIL

  • XML_REPORT_STATUS

If a batch was cancelled and some of the packages were distributed, the Recall Distribution link is still available.

Recall All Distributions to the Portal

To recall all reports that have been distributed to the Portal, click the Recall All Distributions link on the Batch Distributions window.

Filter Batch Distributions

You can filter the batches on the Batch Distributions window by distribution type, status, and distribution time. Right-click on the Batch Distributions window and select Filter Batches from the popup menu. You see the Filter Batch Distributions dialog box.

Filter Batch Distributions Dialog Box

View Event Details

The Event Details link displays the Event Details dialog box, which provides information on the Schedule Def Id, Schedule Queue Id, Start Time, Stop Time, and Duration. There is also a link to the App Server Log.

Event Details Link

Use the Engine Locations Link

The Engine Locations link displays the Client Reporting Engine Locations dialog box. This dialog box displays a list of engines used by Client Reporting. It provides information on the engine location and lets you know if it is configured to run in a clustered environment. In a clustered environment, a concurrent value of Yes indicates the engine can run on any server. A value of No indicates the engine only runs on the Master server. This feature is also available on the Maintain Batches window.

DOT Net Approval and Distribution Tool

The Approval and Distribution tester tool, NetApprDistrTester.exe, is available with Eagle PACE V10.0 and later for Dot Net version of approvals and distributions in the \\server\dotnet folder on the advanced reporting server machine. This tool is also provided with the Visual Studio 2008 add In installation. Use this tool to troubleshoot issues with approvals and distributions created in the DOT Net version.

Test a PACE Approval DLL

To test an approval or distribution dll, retrieve a client reporting mdb that contains the data you are looking for in the dll.

To test a PACE Approval DLL:

  1. Double-click the NetApprDistrTester.exe to open it.
    You see the .Net Approval and Distribution DLL Tester dialog box.

    .NET Approval and Distribution DLL Tester
  2. In the Report File field, enter the location of the .mdb file. Click ... to locate the file.

  3. In the Select DLL Type To Test section, select Test IPACEApproval DLL.

  4. Click the ... button to select a DLL. After selecting an approval DLL, the Run and Save and Exit buttons are enabled.

  5. Click Test to verify that you have entered a valid approval DLL.

  6. Enter any additional entity or client information.

  7. Click Run.

Test a PACE Distribution DLL

To test a PACE Distribution DLL:

  1. Double-click the NetApprDistrTester.exe to open it.
    You see the .Net Approval and Distribution DLL Tester dialog box.

    Net Approval and Distribution DLL Tester Dialog Box - PACE Distribution DLL
  2. In the Report File field, enter the location of the .mdb file. Click ... to locate the file.

  3. In the Select DLL Type To Test section, select Test IPACEDistribution DLL.

  4. Click the ... button to select a DLL. After selecting an approval DLL, the Run and Save and Exit buttons are enabled.

  5. Click Test to verify that you have entered a valid distribution DLL.

  6. Enter any additional parameter values in the Enter Parameter Values section.

  7. Click Run.