Using the Report Library Distribution Option

The Report Library provides secure access to distributed report output stored in the Repository and allows you to save multiple versions of the same report output, set an expiration date, and keep a specified number of versions. The Report Library is only available to users who are authorized to access and view the Library reports in the folder location in which they are stored.

Note:

• You must be authorized to distribute to the Report Library in order to create a schedule that uses Report Library distribution.
• If the ownership of a schedule that uses Report Library distribution has been changed, you must correct the ownership of any associated Library reports to match the new owner of the schedule.

You can send an email notification informing users authorized to access the Library report of its availability. This will notify these users each time a new version is distributed and provide a URL to directly access the new version.

When creating a schedule for distribution to the Report Library, you select the folder to which the report output will be distributed. Using the Advanced button, you can optionally specify a subfolder to which the output will be distributed. If the subfolder does not exist, it is created dynamically during distribution of the initial schedule execution. During subsequent executions of the schedule, reports are distributed to the existing Library item where it is located. You must specify a pattern to be used for the title of the subfolder when the subfolder is created. The pattern can contain text, parameters (amper variables) and, if the scheduled task is burst, the ‘%BURST’ symbol. If the ‘%BURST’ symbol is used, a new subfolder is created for each burst value. You can also select the option to compress a library report when it is stored in the Repository.

You also have the option to specify a Category value to help you further organize the listing of Library reports within the ReportCaster Explorer. In the ReportCaster Explorer, a Category column is available that can be selected to sort Library reports by the Category values.

Note: A Library report in XML format must be opened in a new window.

When scheduling a report procedure (FEX) stored in the Repository, the default location the report output will be distributed to is the same as the report procedure (FEX) being scheduled. The best practice when distributing reports to the Library is to create and specify a different folder location for each Library report to avoid name conflicts when creating multiple schedules for the same report procedure (FEX). This is important so the security access can be defined and managed at the folder level, and when selecting to burst the distributed report output because the burst value is assigned as the title value to each report section that is distributed. The title value is the value that displays in the Resources tree.

For example, the Regional Product Sales (Quarterly) report is located in the Product Information folder. It is scheduled to distribute burst reports by region to the Regional Product Sales (Library Reports) folder, in the Library, on a quarterly basis. The Regional Product Sales (Library Reports) folder contains a library report for each region value included in the report request results. When creating additional schedules for the regional product sales report with the burst option, create and specify a different folder location because the burst report descriptions will be the same region values.

Procedure: How to Use the Report Library Distribution Option

Note: You can use parameters (amper variables) when specifying values for the Library fields of a schedule. These parameters can be system variables, such as &YYMD, or any amper variable for which a value is returned by the Reporting Server when the scheduled procedure is executed. To use the dot file extension separator after a variable, terminate the variable with the '|' character (for example, &YYMD|.htm). Similarly, to use the ampersand character itself, follow the ampersand with the '|' character (for example, Smith&|Jones). If a value for a parameter specified in a schedule is not returned by the Reporting Server when the procedure executes, the schedule will fail with a "No report to distribute" error. If the scheduled task is burst, you can also use the '%BURST' symbol to include the burst value.

1. Right-click a report procedure (FEX), point to Schedule, and then click Report Library.

   The Basic Scheduling tool displays in a new window.

2. Select the Task tab. The Task tab contains the information on where the report procedure is located in the Repository so that the Distribution Server can access it when the schedule runs. Ensure that you complete all the fields in the Task tab.
3. Select the Distribution tab. The Distribution tab contains the information on how the report information will be distributed.
4. Verify that the folder location is the folder to which you want to distribute the report output. You can select a different folder for the report output by clicking the Folder Location button, which displays a dialog box from which a folder can be selected.

   Note:

   • You must be authorized to create content in the selected folder.
   • The default folder location for Library output is the folder from which the scheduling tool is launched, provided that you are authorized to create content in this folder. If you are not authorized to create content there, the default location will be the My Content folder under that folder, if there is a My Content folder. If there is no My Content folder, the default folder location will be your first writable folder.
5. Optionally, click Advanced to set report compression, optional subfolders, version descriptions, and category.

   Use the following information to set these options:

   • Compress Stored Report. Enables you to compress a library report when it is stored in the Repository.

     Note: If you distribute a compressed report to the Library, consider that this may impact the response time in viewing the report. A compressed report must first be decompressed before it is sent. You should evaluate the benefits of saving repository space against the impact of the time it takes to retrieve a compressed report from the Library.

   • Enable Subfolder. Can be enabled to indicate a subfolder to which to distribute a report. If Enable Subfolder is selected, a pattern must be indicated. A pattern can contain text, parameters (amper variables), and the %BURST symbol.
   • Version Description. In the Library Advanced Options dialog box, you can provide parameterized, descriptive text for each version of a report in the Report Library. The Version Description can include text, amper variables, and the ‘%BURST’ symbol if the report is burst. The Version Description is created by the Distribution Server at the time of schedule execution. The description displays next to the version number in the Report Viewer.
   • Category. An optional value that can be used to sort library reports within the ReportCaster Explorer.
6. Select Private, Published, Shared, or Shared with to specify the groups and users authorized to access the Library report. To view a Library report, the user must be authorized to access the Report Library.
   • Private (Accessible only to the owner). Only the Owner of the schedule is authorized to access the Library report. This is the default value.
   • Published (Accessible according to ReportCaster security policy). All users that are authorized to view the Library report in the folder location it is stored in can access the report. The destination folder of the Library Report must be a published folder and the schedule owner must be authorized to publish content in this folder.
   • Shared (Appears under Shared Content Folder). All users that are authorized to view the Library report in the folder location it is stored in can access the report. The report appears under a Shared Content folder.
     • Note: When working with a Library schedule for which the access option check box 'Shared (Appears under Shared Content folder)' and the Send Email after Report Saved to Library check box are selected simultaneously, ReportCaster will only send email messages to the schedule owner.
   • Shared with (Appears under Shared Content folder according to Library Access List). Only the groups or users defined in the Access List, and the owner of the schedule, are authorized to access the report. The report appears under a Shared Content folder.

   Note: When the Access Option of an existing schedule is changed, it will be applied to all versions of the private Library report the next time a new version is distributed. Access options specified in the Library schedule are not applied to published Library Reports.

7. If you select Access List (Shared with), select the Access List button to invoke the Open dialog box from which you can select an Access List which you are authorized to access. Additionally, when bursting is selected, you can limit distribution of the burst values to the values specified in the Access List by selecting the Limit distribution to values in Access List check box.
8. Select Expire after if you would like the Library report to be deleted after the schedule at a later date. Never Expire is the default selection.
   • version(s). The Report Library stores the output for the most recent number of versions specified. For example, if you specify three versions and the current version is 7, then version 7, 6, and 5 are stored in the library. However, if you delete version 6, then only versions 7 and 5 are stored in the library. If you then distribute version 8 to the library, only version 8 and 7 are stored in the library since you deleted version 6 and version 5 is not among the top three versions.

     Use the up and down arrows to select the number of versions.

     You can store up to 9,999,999 versions of a report in the library.

     Note: The actual number of times a report can be run is 2exp(31) -1.

   • Never Expire. The report remains in the Report Library until it is manually deleted by the owner.
   • day(s). The Report Library stores the report for the number of day(s) specified. Use the up and down arrows to select the number of days.
   • week(s). The Report Library stores the report for the number of week(s) specified. Use the up and down arrows to select the number of weeks.
   • month(s). The Report Library stores the report for the number of month(s) specified. Use the up and down arrows to select the number of months.
   • year(s). The Report Library stores the report for the number of year(s) specified. Use the up and down arrows to select the number of years.

   Note:

   • ReportCaster automatically purges expired reports one hour after the scheduled Log Purge Time. The default Log Purge Time is 1:00 AM. Therefore, the default library purge time is 2:00 AM each day. If you are an authorized user, you can also purge expired Library reports on-demand from the ReportCaster Console.
   • The maximum number of versions of a report scheduled to the library is 9999. If you exceed this limit, the new report will not be stored and you will receive a message in the ReportCaster log file.
9. Optionally, select the Library Notification tab and then select the Send an Email after Report saved to Library option to send an email notification to users that are authorized to access the Library report each time a new version is distributed. The email message also contains the URL report content in the Library. Depending upon the Access Option selected, one or more users will receive a notification email. If the Access Option is Owner, Published, or Shared, the schedule owner will be notified by email when the schedule executes and output is distributed to the Library. If the Access Option specifies an Access List (Shared With), then each user on the Access List is notified when the schedule executes and output is distributed to the Library. Groups in the Access List are not used to retrieve email addresses. Only listed users will receive an email notification.

   When you select this option, the following fields appear:

   • Mail Server Name. This is the host name of the email server that ReportCaster will connect to distribute the Library email notification.
   • Library URL. This is the URL to sign in and open the Report Library. The default value is specified in the ReportCaster configuration. When a user is sent a Library email notification, the email contains a link to the report in the Library that the user is being notified about. That link is created by adding the specific report ID of the notification to the Library URL. When the link is selected, the user is prompted to sign in. ReportCaster security processing determines if the user is authorized to access the Library report.

     Note: You can configure ReportCaster to not send a link containing a URL.

   • From. This can be any value, for example, the name of the person creating the schedule. ReportCaster does not require a value for this field, but your email system may require one.
   • Reply Address. The email address of the sender. This is a required field. If report recipients reply to the notification, then their messages are sent to this address.

     Note:

     • If you are authenticating to the mail server with your user ID and password, then the reply address will be the email address associated with that user ID.
     • If the mail server is configured with authentication and the Reply Address is configured in the ReportCaster Configuration tool, then the Reply Address field in the scheduling tools will be disabled. If a Reply Address is not configured, then the field is enabled to allow a Reply Address to be sent to the email server, however the actual Reply Address of the delivered email will be that of the authenticating account.
   • Subject. The optional text that you want to appear in the email subject line.
   • Message. An optional message you want to appear in the body of the email notification.
10. Select the Notification tab to specify whether to send an email notification of the schedule job status. By default, the value you entered in the schedule Title field is the default Subject value. If you select Always or On Error, then you must specify the Reply Address, Subject, Brief Message To, and Full Message To.
11. Select the Properties tab to specify the Title, Priority, whether to delete the schedule if it will not run again, and whether the schedule is enabled to run.
12. Select the Recurrences tab to specify how often to run the schedule. If you want the schedule to run on the current day, set the Start Date and Start Time to values later than the current time.
13. Click Save & Close to save your changes.