IBM® DB2® Content Manager OnDemand is an automated archival/retrieval system that is used to store printed output such as reports, statements, invoices, and image documents. The printed output is processed and stored onto various types of storage media including hard disks, optical platters, and tapes. Index values are extracted from the printed output and stored in a relational database. Once the printed output and index values are stored, any of the OnDemand client programs can be used to query and retrieve documents.
Report Distribution is an optional priced feature of IBM DB2 Content Manager OnDemand for Multiplatforms Version 7.1.1. Report Distribution provides an easy way to automatically group reports and portions of related reports together, organize them, convert the report data into different formats, and send them through e-mail to multiple users or make them available for printing.
The Administrative client is used to perform system administrative tasks such as defining users and reports to the OnDemand system. After the Report Distribution feature is installed, you also use the Administrative client to define distributions. In this article I describe how to set up and use the Report Distribution feature using the Administrative client. Also included are hints and tips and other useful information for setting up and maintaining distributions.
Report Distribution provides many of the same functions as other parts of the OnDemand system such as querying the database for documents, retrieving the documents from various types of storage media, and providing the ability to print them on a server printer. If these functions are already available in OnDemand, why would you want to use Report Distribution? The answer is simple: automation. Report Distribution automates the process of querying and retrieving documents as well as sending the documents to a printer or to one or more users via e-mail. Not only is the process automated, you can specify when the documents will be delivered. Another benefit to using Report Distribution is you can select and combine documents from different reports and organize them by defining their order and separating them using banner pages.
Normally when you think of an archival/retrieval system, the first thing that comes to mind is that large numbers of documents are stored but a small number of documents are retrieved. So what benefit does automation and scheduling provide? The biggest benefit is that as reports are being loaded into OnDemand on a regular basis, they can be delivered automatically to one or more users soon after they're loaded. Also, once the distribution has been set up, no other changes are required such as changing the document selection criteria to identify the latest data that is loaded. For example, a company creates monthly sales reports and archives them in OnDemand. The reports are needed by sales managers to analyze the results and to plan for future sales and inventory. By using Report Distribution, the delivery of the monthly sales report can be automated so that the sales managers receive the report via e-mail once a month as soon as the report is available in OnDemand. Other examples include auditing that is performed on a periodic basis and workflow items such as processing overdue accounts for credit cards, utility bills, or doctor's bills. The applications for using Report Distribution are endless but the basis for using it is the same; namely documents are loaded on a regular basis and are needed by one or more users as they become available in OnDemand. Now that you have a better idea as to why you would use Report Distribution, let's look at a specific example.
Acme Art Inc. is a company that sells artwork and art supplies. Each month a sales report is created for each region and is archived in OnDemand. Once the reports have been archived, the regional sales managers need a copy of the reports for planning purposes and for restocking inventory. In Figure 1 the Windows client is shown with a list of monthly sales reports that have been archived in OnDemand. As you can see, there are two regional sales reports (Midwest and Northwest) for the months of July, August, September, and October.
Figure 1. List of monthly sales reports for Acme Art Inc.
In this example, even though there are separate regional sales reports per month, they are loaded at the same time so there is only one load per month. This information is important when you are determining the best way to set up the distribution. Before a distribution is set up, you should ask yourself the 4 Ws:
- What documents are needed?
- Who will receive the documents?
- When will the documents be retrieved and delivered?
- Where will they be delivered?
For the example, the documents that are needed are the regional sales reports. How do you identify the regional sales reports you need from the hundreds of thousands of documents stored in OnDemand? In general, you identify the documents by creating a database query using index fields and values that uniquely identify the documents you want to retrieve. For Report Distribution, another method can be used to identify the documents you want to retrieve. Instead of querying the database, you can simply retrieve all or some of the documents as they are being loaded. To illustrate this, let's take a look at the example again. Once a month, regional sales reports are loaded into OnDemand. Since the load contains all the documents that are needed, we can identify and retrieve all of the documents from the load. Later, when I describe how to set up a distribution using the Administrative client, I will go into more detail about how to define a set of documents that will be delivered.
Who will receive the documents?
The regional sales managers need a copy of the regional sales reports every month. To identify the sales managers to OnDemand, an OnDemand user must be created for each sales manager. Depending on how the documents will be delivered, an e-mail address or a server printer must be specified in the user definition.
When will the documents be retrieved and delivered?
Each month, the regional sales managers would like to get the regional sales reports as soon as they are available in OnDemand. In Report Distribution, documents can be scheduled for delivery on a daily, weekly, or monthly basis as well as delivering the documents once or delivering the documents a short period of time after they have been loaded into OnDemand. For this example, delivery will be scheduled based on the availability of the documents after they have been loaded.
You might ask why this type of schedule would be used rather than a monthly schedule since the reports are loaded on a monthly basis. When a "load-based" schedule is used, the extraction and delivery of the documents is triggered when the data is loaded. In other words, Report Distribution periodically looks to see if data has been loaded. If it has, then the documents are extracted and delivered. When a monthly schedule is used, the extraction and delivery process will be performed on a specified day of the month. If for some reason the data hasn't been loaded by the specified day, the delivery will fail.
The other reason for using a load-based schedule is that the delivery of the documents may be more timely since they are delivered a short time after they are loaded. Depending on when data is loaded and what day of the month is used for the monthly schedule, there could be several days between the time the documents are loaded and the time the documents are delivered rather than a matter of hours or minutes.
The regional sales reports can be delivered to the regional sales managers either via e-mail or to a server printer. In this example, the reports will be delivered via e-mail. By using this delivery method, the reports can either be viewed or they can be printed at a later time.
To support the administration of Report Distribution, 5 new areas have been added to the Administrative client. Figure 2 shows an example of an OnDemand server with the Report Distribution areas.
Figure 2. OnDemand server with Report Distribution
The five new areas are:
- Reports: A report provides a way to identify which documents will be extracted from OnDemand. You can identify the documents by creating a database query using index fields and values that uniquely identify the set of documents you want to retrieve. Alternatively, instead of querying the database, you can retrieve some or all of the documents shortly after they are loaded into OnDemand.
- Banners: A banner is an informational page that is created in the same format as the report data (i.e. line, AFP, PDF). The contents of the banner page is customizable and it can include information such as the report name, the report description, the name of the user that is receiving the distribution, etc. Three different types of banner pages can be used, a header banner, a separator banner, and a trailer banner. The header banner is the first page in the distribution. The trailer banner follows the last page of the last report in the distribution. The separator banner precedes the first page of every report in the distribution.
- Bundles: A bundle is used to specify which reports will be delivered, the order the reports will be included in the bundle, the format of the report data, and if banner pages are used, which banner pages will be used. See Figure 3 for an example of the contents of a bundle.
- Schedules: A schedule is used to initiate the extraction and delivery of the reports. Reports can be scheduled for delivery on a daily, weekly, or monthly basis as well as one time, or shortly after they have been have been loaded into OnDemand.
- Distributions: A distribution is used to identify the bundle of reports that will be delivered, who will receive the reports, when the reports will be delivered, and where they will be delivered.
Figure 3. Bundle contents
Now that you have the basics, let's take a look at how to set up a distribution for the delivery of the monthly regional sales reports from the example. In general, to set up a distribution, you will need at a minimum, a user, a report, a bundle, a schedule, and a distribution. This assumes you've already loaded data into OnDemand so an application, application group, and folder have already been defined. For the example we will include banner pages, multiple reports, and the reports will be sent to multiple users.
So where do we begin? What needs to be defined first? Since a bundle and a distribution include other Report Distribution objects in their definition, there is a logical order for defining the objects. I like to use the 4 Ws (Who, What, When, Where) as a guide for defining the objects. Based on this, the order is the following: users/groups, reports, banners, bundle, schedule, distribution. Some of these objects may already be defined so they may already be available for use. For example, users and groups are already used in OnDemand so you may not have to define these objects. Also, if this isn't the first distribution you're defining, you can use existing banners, bundles, schedules, and reports if appropriate.
For the example, I'm going to assume the users have already been defined. However, each sales manager that will receive the monthly regional sales reports must have an e-mail address specified for their userid since they will be receiving the reports via e-mail. If you don't have to create new userids, you'll want to make sure e-mail addresses or server printers are specified for each user. Figure 4 is an example of a user that has an e-mail address and a server printer specified.
Figure 4. User with an e-mail address and server printer specified
The next step is to define the reports to OnDemand. For the example, two reports will be defined, one for the Northwest regional sales report and one for the Midwest regional sales report. When the report dialog is displayed, there are 3 report types to choose from: Load, SQL, and Named Query. The report type determines the method used to identify which documents will be retrieved. Figure 5 shows an example of the report dialog with information for the Northwest regional sales report.
- Load: Some or all of the documents are retrieved shortly after they have been loaded into OnDemand.
When documents are loaded into OnDemand, the load identifier is stored in a database table and a list of documents that have been loaded during the load is created and saved along with the data. The load identifier and the document list are used to retrieve all of the documents for the load. If several loads have been processed, there will be multiple load identifiers and multiple lists of documents to process for the report
If you don't want to retrieve all of the documents that were loaded, an SQL query can be used to limit the number of documents to retrieve within the loads that are being processed.
When distributions are set up to be load-driven (i.e. reports use the Load report type and the distribution is scheduled using a Load Based schedule), Report Distribution periodically checks the load identifier database table to see if there are any load identifiers in the table (i.e. data has been loaded). If there is, than Report Distribution begins extracting documents for the report. - SQL: An SQL query string is used to query the database. The SQL query string consists of index fields and values that uniquely identify the documents you want to retrieve.
- Named Query: A public named query is used to query the database. It contains the database query information that uniquely identifies the documents you want to retrieve.
To use this method, the named query must have been created prior to defining the report and it must be a public named query rather than a private named query. A public named query is created from the Windows client.
Figure 5. Report dialog for the Northwest regional sales report
For the example, the Load report type with an SQL query is used. Figure 5 shows the report dialog with an SQL query. Since the regional sales reports are in the same load, an SQL query is not necessary. However, by using the SQL query, the reports can be retrieved separately and placed in the bundle in any order. Separator banner pages can also be added to identify each report in the bundle. Another reason for creating separate reports is that it gives you the flexibility to deliver the regional sales report to the appropriate regional sales manager rather than sending both reports. This would require creating a separate bundle and distribution for each report.
Along with selecting the report type, you'll need to select an application group where the data is loaded. The application group needs to be selected before the SQL query can be defined since the application group database field names are needed to build the SQL query. In Figure 6, an SQL query string is defined for the Northwest region by selecting application group database fields and operators to create the SQL query string. A segment date field can also be specified so that the query is limited to a smaller number of database tables.
Figure 6. SQL Query dialog for the Northwest regional sales report
Once all of the information has been filled in for the report, the report can be added by selecting the OK button. The second report can be created in a similar way so I won't go into the details here. Later, when I discuss how to create a bundle, the second report will be available so it can be included in the bundle.
The next step is to create the banner pages. For the example, a header banner, a separator banner, and a trailer banner will be used. Banner pages, regardless of their type, are created in the same way. The difference between the various banner pages is their location in a bundle and the information that is contained on the page. Figure 7 shows the banner dialog for a separator banner.
Figure 7. Separator Banner dialog
When the banner type is selected, the list of information that can be included on the banner page is displayed in the Available Information list. You can add one or more lines of information to the banner page. The information can be placed in any order where the order is defined by the order you place the information in the Selected Information list. Once you're satisfied with the contents and the order of the information, the OK button can be selected to add the separator banner. The header and trailer banners can be added in a similar way. Later when I discuss how to create a bundle, the header and trailer banners will be available so they can be included in the bundle. Figure 8 shows an example of a separator banner for the Northwest regional sales report.
Figure 8. Example of a separator banner
The next step is to create a schedule. There are 5 different schedule types: once, daily, weekly, monthly, and load based. Documents can be scheduled for delivery on a daily, weekly, or monthly basis or they can be delivered once. Load based schedules can only be used with reports that are defined using a report type of load. For the example, a load based schedule must be used since the reports are defined using a report type of load. Figure 9 shows the schedule dialog for a load based schedule.
Figure 9. Schedule dialog
As part of the schedule definition, a start date, end date and delivery time is specified. In the case of a load based schedule, the start date is the first day you want Report Distribution to start looking for documents that have been loaded into OnDemand beginning at the specified delivery time. For example, starting on January 19th, 2004 at 10:00 AM, Report Distribution periodically queries the load identifier database table to see if any regional sales reports have been loaded.
A Report Distribution parameter determines how frequently to look for schedules to process. See Figure 16 for an example of the Report Distribution parameters dialog. In the case of load based schedules this essentially means how often the load identifier database table is queried. Once the processing of the load based schedule begins, it will be processed until midnight. At that point, processing of the schedule will stop until the next day starting again at the specified delivery time. If you know what time your data is usually loaded, you can set the delivery time to the same time or shortly after so that Report Distribution doesn't look for the data before it is loaded. Once you've filled in the schedule information, the OK button can be selected to add the schedule.
The next step is to create a bundle. Figure 10 is the General tab for the bundle dialog. This is where you specify the output format of the data. For the example, the format of the regional sales reports is ASCII line data so Line Data is selected. If you include more than one report in the bundle, the format of every report must be the same and must match the output format. If the input format is different than the output format, you must use a transform program to convert the report data to the output format. For example, you could use the AFP2PDF transform program to convert AFP reports to PDF. In this case, you would specify an output format of PDF.
E-mail notification messages can be sent to one or more users during bundle processing. The message types are error messages, warning messages, progress messages, and completion messages. If you want to notify more than one user, a group can be used. A progress message is sent after the bundle has been processed for each recipient in the distribution. A completion message is sent after the bundle has been processed for all of the recipients.
Figure 10. General tab of the Bundle dialog
Figure 11 shows the Bundle Contents tab of the bundle dialog. This is where you decide which reports will be included in the bundle and if banner pages are used, which banner pages to use. The bundle for the example contains a header banner, a separator banner, and a trailer banner as well as the two reports that were created earlier. The first report in the bundle is MidWest Monthly Sales Report and the second report is NorthWest Monthly Sales Report. The reports can be included in the bundle in any order and is determined by how you add them to the Bundle Contents list. You can change the order of the reports by moving them up and down in the list.
Figure 11. Bundle Contents tab of the Bundle dialog
The inclusion of a manifest in the bundle is optional. The manifest is similar to a banner page in that it contains information about the bundle. Specifically, it contains the name of the distribution, the time the distribution was processed, and a list of files containing report data that were included in the bundle. If the manifest is included, it is always added to the end of the bundle.
The field titles on the banner pages and manifest can be created in many different languages. The choices are: Arabic, Chinese (Simplified), Chinese (Traditional), Danish, Dutch, English, Finnish, French, French Canadian, German, Italian, Japanese, Korean, Norwegian, Portuguese (Brazil), Spanish, and Swedish. One thing you should consider when selecting a banner language is that the banner pages are converted to the code page of the data. With this in mind, selecting a language such as Korean to use with data that is in a single byte code page will not work correctly.
Once all of the selections have been made for the bundle, the bundle can be added by selecting the OK button.
After you've created the report, banners, bundle, and schedule, it's time now to put it all together by creating a distribution. Figure 12 shows the General tab of the distribution dialog. The available delivery options are e-mail and server printer. For the example, the delivery method that will be used is e-mail.
E-mail notification messages can be sent to one or more users during distribution processing. The message types are error messages, warning messages, progress messages, and completion messages. If you want to notify more than one user, a group can be used. Progress messages are sent after each recipient in the distribution has been processed. A completion message is sent after the distribution has been processed for all of the recipients.
Figure 12. General tab of the Distribution dialog
Figure 13 shows the Bundle tab of the distribution dialog. Only one bundle can be selected for the distribution and once the distribution is added, it cannot be changed. For the example, the bundle that was created previously called Monthly Sales Reports, is selected.
Figure 13. Bundle tab of the Distribution dialog
Figure 14 shows the Schedule tab of the distribution dialog. When you're creating a distribution, a schedule doesn't have to be selected or one can be selected but not activated. Of course, if the distribution doesn't have an activated schedule, the reports in the bundle you've selected for the distribution won't be delivered. For the example, the schedule called Load Based Schedule that was created earlier is selected and activated.
Normally, once a schedule has been selected for the distribution, a different schedule can't be selected. However, if the schedule has expired (i.e. today's date is greater than the end date defined in the schedule), Report Distribution will remove the schedule from any distributions that use the schedule. If this occurs, a new schedule can be selected for the distribution. The schedule can be deactivated for the distribution at any time.
Figure 14. Schedule tab of the Distribution dialog
Figure 15 shows the Recipients tab of the distribution dialog. This is where you select the recipients that are going to receive the reports. For the example, the regional sales managers will receive the reports so the userids of the managers have been added to the Selected Recipients list. If there are several users that require the same set of reports, you can choose to add the users to a group and add the group to the Selected Recipients list. The two regional sales managers could have been added to a group and then the group would have been used instead of the individual userids.
The check mark next to the userid of each recipient in the list indicates the recipient is active for the distribution. If the check mark is removed from the box, the recipient is deactivated and won't receive the reports. You can use this feature to temporarily deactivate the recipient, if for example, the recipient is on vacation and doesn't need the reports. However, you cannot deactivate the only recipient in the distribution. Also, there must be at least one activated recipient in the distribution and all of the recipients must have an e-mail address defined if the delivery method is e-mail. If the reports are going to be sent to a server printer, all of the recipients must have a default server printer defined.
Figure 15. Recipients tab of the Distribution dialog
Once all of the selections have been made for the distribution, the OK button can be selected to add the distribution. All of the steps required to set up the extraction, bundling, and delivery of the regional sales reports have been completed. Start the Report Distribution program on the server, and you're ready to begin receiving the regional sales reports after they are loaded into OnDemand!
Report Distribution parameters
There are several parameters that control the Report Distribution process. Figure 16 shows the Report Distribution Parameters dialog. To display the dialog, point to the Report Distribution main icon and click the right mouse button. From the pop-up menu select the Parameters menu option.
Figure 16. Report Distribution Parameters dialog
Report Distribution can be deactivated so that it temporarily stops processing distributions. Distributions that are in progress are completed but no new distributions are processed until Report Distribution is activated again. Other options you can specify include how often Report Distribution looks for distributions that are ready to be processed and how many times an operation should be retried before the operation fails.
Messages that are generated during the extraction, bundling, and delivery stages of Report Distribution can optionally be logged and are viewable using the Windows client by opening one of the folders that were created during Report Distribution installation.
If you're going to use the e-mail delivery option or send e-mail notification messages, you'll need to specify an SMTP server address that will process the e-mail messages that are generated by Report Distribution. You can optionally specify address information that is specific to your company such as a return e-mail address and an e-mail address to use for correspondence. A file containing company-specific information or other types of information that you want to include with the delivery of the documents can be used as well. If a global attachment file is specified, it will be attached as a separate file to the e-mail message that contains the documents that were extracted.
- A load based schedule can only be used with reports that are defined using the load report type and vice versa. The load based method can only be used for data that was loaded using IBM DB2 Content Manager OnDemand for Multiplatforms Version 7.1.1 or later. Data that was loaded with a prior version can be retrieved using the time based method.
- Once documents have been delivered using a load based schedule, they cannot be delivered again using a load based schedule. For example, if the January monthly sales report was delivered using a load based schedule, it cannot not be delivered again by a load based schedule. However, when the monthly sales report for February is loaded, it will be extracted and delivered by the load based schedule. If for some reason you need to deliver the January sales report again, a schedule with a schedule type of "Once" can be used.
- If you've loaded several months of data and now want to start delivering the documents using a load based schedule starting with the latest month, you can add a date to the query so that documents from prior months will not be delivered the first time the schedule is processed. For example, the sales report has been loaded for the last 4 months and now you want to set up the distribution of the sales report starting with the latest month. You can include information in the SQL query that will start the search for the documents with the latest month. From this point on, reports from new loads will be processed.
- If a daily, weekly, or monthly schedule is used, Named Query type reports should be used if new data is loaded on a regular basis and retrieved. A named query lets you set up a date range based on the current date whereas an SQL query requires a specific date or date range in the query string. If an SQL query string is used, the dates in the SQL query string would have to be changed so that only the latest data is retrieved. For example, if data is loaded on a monthly basis and the data is loaded by the 3rd of the month, a monthly schedule could be set up to run on the 3rd of the month and the Named Query would specify a date range of "t - 3d" to "t" for the report date. "t - 3d" means today's date minus 3 days. This would mean that Report Distribution would look for reports that have a report date for the 1st, 2nd, or 3rd day of the month. For example, to extract the report for the month of January, the query will match documents that have a report date of January 1, January 2, or January 3. Assuming the date in the report data is January 1, the report data for the month of January will be extracted and delivered.
- If a distribution is scheduled for delivery using a "Once" schedule and the starting date is in the past, the distribution will be delivered immediately (i.e. the next time Report Distribution scans for active schedules). For example, if the starting date of the schedule is January 18, 2004 and the current date is January 20, 2004, the distribution will be processed immediately.
- Normally the only way an OnDemand system definition (i.e. user, group, report, bundle, etc.) is updated is when a user uses one of the administrative programs to update the definition. An exception to this is that when a schedule expires and it is being used in one or more distributions, Report Distribution automatically removes the schedule from all of the distributions that are using the schedule. In other words, the schedule is no longer selected in the distribution.
- To determine which distributions are scheduled for delivery, the search option can be used. You can select the search option by clicking the right mouse button on the Distribution icon in the tree view of the Administrative client. When the Search for Distributions dialog is displayed, remove the check from the No Schedule and Disabled Schedule check boxes and click on the OK button. Only the distributions that are scheduled for delivery will appear in the list of distributions. Figure 17 shows an example of how to search for scheduled distributions.
Figure 17. Search for Distributions dialog
- Since the distribution definitions can be updated by the Report Distribution program, you may want to update the distribution information before searching for scheduled distributions. To refresh the list, select the Distribution icon in the tree view of the Administrative client and then select Refresh List from the View Menu. You can also press the F5 key after the Distribution icon has been selected. The Search for Distributions dialog also provides a way to identify which distributions use a specific schedule or a specific bundle. You can also identify which distributions will be delivered to a specific recipient.
- The search option is available for the other Report Distribution areas. For bundles, the search option can be used to determine which bundles contain specific reports or banners. You can use the banner search option to search for banners with a specified banner type, the report search option to search for reports with a specified report type, and the schedule search option to search for schedules with a specified schedule type.
The recommended method for delivering reports that are loaded on a regular basis is the load-based method for the following reasons:
- When a load-based schedule is used, the extraction and delivery of the documents is triggered by when the data is loaded. When a time-based schedule is used, the extraction and delivery process will be performed on a specified day of the month. If for some reason the data hasn't been loaded by the specified day, the delivery will fail.
- The delivery of the documents may be more timely since they are delivered a short time after they are loaded. Depending on when data is loaded and what day is used for the time-based schedule, there could be several days between the time the documents are loaded and the time the documents are delivered rather than a matter of hours or minutes.
- Since a load-based schedule is driven by when data is loaded, document selection is automatically limited to the documents in the load whereas a time-based schedule must be used in conjunction with a database query to limit the search to the documents that were loaded most recently, usually by report date.
- IBM Content Manager Portfolio.
- OnDemand product page.
-
OnDemand: Designing a Solution for Performance and User Satisfaction, Eric Hann and Benjamin Boltz
-
Choosing a Model for IBM Content Manager OnDemand System Administration, Debbie Wagner
-
Customizing the IBM Content Manager OnDemand Administrative Client, Debbie Wagner
-
IBM Content Manager OnDemand: Report Definition Made Easy, Debbie Wagner
Table of contents
Next steps from IBM
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
