Report distribution
IBM Content Manager OnDemand Distribution Facility (ODF) is an optional report distribution feature for IBM Content Manager OnDemand. ODF provides an easy way to automatically group reports and portions of reports and distribute the reports to multiple users. ODF distributions can be printed, created as an output file, or emailed as an attachment.
ODF can distribute reports that are stored in a Content Manager OnDemand server on any platform that is supported by Content Manager OnDemand.
In this chapter, we cover the following topics:
14.1 Introduction to Content Manager OnDemand Distribution Facility
Before Content Manager OnDemand version 9.5, two report distribution components were available:
•OnDemand Distribution Facility for z/OS
•Report Distribution Facility for Content Manager OnDemand for Multiplatforms
Both of these components contained certain strengths and weaknesses. In V9.5, the strengths of both of these components were merged into a single component named OnDemand Distribution Facility (ODF), which offered the following advantages:
•It runs on all Content Manager OnDemand platforms.
•It can run on a separate platform from where the Content Manager OnDemand server is installed.
•Its operation can be monitored through a new graphical monitor, the OnDemand Monitor.
•It includes transform support where Content Manager OnDemand can transform content from one data type to another data type before the content is sent as part of an ODF distribution.
This chapter describes ODF V9.5. For any new installations (on z/OS or AIX) before version 9.5 of Content Manager OnDemand, we suggest that you install ODF.
Figure 14-1 shows the evolution and merger of ODF 9.5 from its predecessors ODF9.0 and Report Distribution System (RDF) 9.0.
Figure 14-1 Evolution of ODF
When you load documents into Content Manager OnDemand, you might need to print these documents or send them to various people in your organization.
Content Manager OnDemand automates the process of sending the documents that are loaded into Content Manager OnDemand to print (or the JES spool), a file (or a z/OS dataset), to a recipient as an email attachment, or to a recipient as an email notification. Another benefit to using ODF is that you can select and combine documents from different reports and organize them by defining their order and separating them by using banner pages.
Figure 14-2 is an overview of the OnDemand Distribution Facility and its interaction with the Content Manager OnDemand server.
Figure 14-2 Content Manager OnDemand Distribution Facility overview
Figure 14-2 shows that the Content Manager OnDemand server and its operation did not change. Reports and documents are loaded into the server, and system users continue to view and print their documents normally. The only addition to the library server is a set of ODF tables that define the documents that are to be distributed to which users and when. The ODF process reads the ODF tables and collects the required documents and bundles them for each recipient. ODF then send out the “bundles” to the appropriate destinations (email, file, and print). Alternatively, ODF can send each recipient (based on system definitions) an email notification that the report and document were loaded and are available for viewing.
Different organizations have different report and document load and retrieval patterns. In certain cases, documents are loaded and never retrieved. In other cases, a loaded document is retrieved multiple times by multiple users. In other cases, it is known that when a specific report or document is loaded, one or more copies must be distributed to one or more destinations. What benefit does automating this distribution process provide?
The biggest benefit is that as reports are loaded into Content Manager OnDemand regularly, they can be delivered automatically to one or more users as they are loaded. Also, after the distribution is set up, no other changes are required, such as changing the document selection criteria to identify the latest data that is loaded.
For example, suppose that your organization generates monthly statements for your customers. You must store these documents in Content Manager OnDemand, and you must print the statements and mail them to the customers. With ODF, you can set up a distribution that automatically retrieves these documents as they are loaded into Content Manager OnDemand and sends them to a spool file for printing.
Another example is a sales team that generates a monthly sales report for each person on the sales team. The sales manager needs a copy of these reports. A distribution can be set up to email the documents to the appropriate sales manager.
The applications for using ODF are endless, but the basis for using it is the same. Documents are loaded regularly and are needed by one or more users as they become available in Content Manager OnDemand. Let us look at a specific example from our fictitious company that was introduced in 1.2.1, “Background information of an example company” on page 6.
AFinancial Co generates monthly credit card statements for all its customers. These customers can choose to receive a hardcopy of the statement or have the statement sent to them as an email attachment.
In this example, even though separate customer statements are created each month, they are loaded into the system at the same time, so only one load occurs each month. This information is important when you are determining the best way to set up the distribution. Before a distribution is set up, ask yourself the following questions:
•What documents are needed?
•Who receives the documents?
•When are the documents retrieved and delivered?
•Where are they delivered?
14.1.1 What documents are needed
In our example, we identified our documents as the customer statements. How do you identify the customer report that you need from the hundreds of thousands of documents that are stored in Content Manager OnDemand? Certain customers might receive multiple monthly statements.
In general, you identify the documents by creating an SQL query that uses index fields and values that uniquely identify the documents that you want to retrieve when they are loaded. You can then define the distribution to include multiple report bundles with different SQL queries for each bundle. If the SQL must retrieve the document that is the same except for a value that identifies the recipient, a single distribution can be used with a recipient list. In this case, the SQL specifies a wildcard value. When processing, ODF fills in the recipient ID in the SQL statement. For example, a recipient list contains recipients 100001, 100002, and 100003 and an SQL statement of “Where branch_id = '$ODF_RECIPIENT'”. When this recipient list is processed, ODF creates a distribution for recipient 100001 with all reports where branch_id = '100001', recipient 100002 will receive a distribution that contains all reports where branch_id = '100002', and so on.
14.1.2 Who receives the documents
In our example, each customer needs a statement copy every month. To identify the customers to Content Manager OnDemand, an ODF recipient must be created for each customer. Depending on how the documents are delivered, a destination must be set up. For example, if a set of documents will be delivered to a recipient by using email, an email address must be specified in the recipient definition.
14.1.3 When the documents are retrieved and delivered
ODF operates throughout the 24-hour day. You can schedule your distributions to be processed at a specific time of day or processed as they are loaded. To specify when the distribution is delivered, choose the method, which is either Loaded, All Ready, Time of Day, Time of Print, or external.
ODF operates on a 24-hour clock: 00:00 to 23:59. If a time of distribution (TOD) of 01:00 is specified and documents are loaded at 23:30, the documents are processed immediately and they do not wait until the next day because the TOD specified was reached for that 24-hour day.
14.1.4 Where are they delivered
You can deliver the distribution to a printer (or the JES spool on z/OS) for printing, a file (or TSO dataset on z/OS), or an email attachment. Alternatively, you can specify that the documents will not be distributed at all and that an email notification that the documents were loaded is sent to the specified recipients. In our example, certain customers specified that they want their statements to be delivered by email, and other customers specified that they want a hardcopy.
14.1.5 Cross-platform access
ODF (running on any supported platform) can access a Content Manager OnDemand instance that is running on any (local or remote) platform that is supported by Content Manager OnDemand. For more information about how to configure ODF, see “Configuring ODF” in the OnDemand Distribution Facility Installation and Reference Guide, SC19-3358.
14.2 Defining the objects with the Administrator Client
After you set up the Content Manager OnDemand (application group and application) objects, you are ready to set up the ODF objects. This section describes the definition of the ODF objects by using the Content Manager OnDemand Administrator Client (Figure 14-3).
Figure 14-3 Administrator Client ODF objects
14.2.1 Adding a recipient
The recipient object contains all of the information about the recipient of the distribution. The only required field is the recipient ID, which, when combined with the distribution name, uniquely identifies the distribution.
Figure 14-4 shows the window where you add a recipient.
Figure 14-4 Add a Recipient
Recipients who receive a printed copy of the distribution can choose to include a banner page in the distribution by selecting Use Banner Page. You can specify up to eight header lines to include in the banner page, as shown in Figure 14-5 on page 321.
Figure 14-5 Specifying banner page information
14.2.2 Adding a recipient list
If several recipients must receive the same reports at the same time, you can create a recipient list. With this list, you create a single distribution that is sent to every recipient in the list.
Recipients are added to the list by selecting the ID on the left and clicking Add, as shown in Figure 14-6 on page 322.
Figure 14-6 Adding a recipient list
14.2.3 Adding a report ID
The next step is to define the reports to ODF. The report ID identifies the application group and application to which the report belongs. Figure 14-7 shows the window where you add the report ID.
Figure 14-7 Adding a report ID
To create a report ID, specify the identifier and then choose the application group and application from the drop-down selection.
Use the reference field to control when a report is available for distribution. The value that you enter in this field is used with a marked index column in the Content Manager OnDemand application group. When a reference value is available, the reference value is matched with the index value of the report. If a match exists, the report is made available for distribution. This tool is useful if several drafts of a report exist and you want to distribute only the final version.
14.2.4 Adding a distribution
Now that the recipients and report IDs are set up, it is time to create the distributions. In the distribution definition, you specify when, where, and how the distribution is delivered. In our example, we create a distribution that is processed while the documents are loaded. The output is sent as an email. For a sample distribution definition, see Figure 14-8.
Figure 14-8 Adding a distribution
Distribution Name
With the recipient or recipient list name, the distribution name uniquely identifies the distribution. For our example, we name this distribution CREDIT CARD STATEMENTS.
Recipient/List
Choose your recipient. For our example, we add the newly created recipient from the drop-down menu.
Status
Two values are valid for status:
•Active indicates that the distribution is processed while the documents are loaded.
•Inactive indicates that the distribution is not processed while the documents are loaded.
Job Name
To improve ODF performance, you can use a submitted job and the persistence feature. When you use a job name on distributions, ODF uses a feature of z/OS that allows jobs to run in created address spaces. The ODF distribution runs under the job name that is specified. For our example, we leave the job name value blank.
Location
The location specifies where the distribution is delivered. We select E-mail for our distribution.
The following options are available for the Location field:
•Print: The output is sent to a JES spool file.
•File: The output is sent to a generation data set (GDS) if a dataset value is specified. Otherwise, it is sent to a TSO dataset.
•None (with “Notify by e-mail” selected): An email is sent to the recipient to notify the recipient that the distribution is available.
•Email: The output is sent as an attachment in an email to the recipient.
|
Note: The “Notify by e-mail” check box is available for use with Location values of Print, File, or None. The selection of the “Notify by e-mail” check box sends an email to the recipient to notify them that the distribution is available.
|
Customer Variables
This field contains any information that you might need to pass to the customizable user exits. For example, if this distribution requires special spool file allocation options, you can enter the information in this field. The preallocation exit can then use the information to change the spool file allocation parameters. For our example, we leave this field blank.
Account
This field is optional. This field specifies the name to use on the JCL job card. For our example, we leave this field blank.
Distribution Method
The distribution method controls the scheduling and processing of the distribution. Because we want the distribution to be processed while the documents are loaded, we select the Loaded method.
The following distribution methods are available:
•Loaded: The distribution is scheduled for processing when the first report bundle is archived or stored in Content Manager OnDemand. The distribution is submitted for print processing when all of the report bundles in the distribution with a Wait/Ignore Indicator of Wait are loaded.
•All Ready: The distribution is scheduled for processing when the ODF address space is started. The distribution is submitted for print processing when all of the report bundles in the distribution with a Wait/Ignore Indicator of Wait are loaded.
•External: A process outside of ODF schedules the distribution. The distribution is submitted for print processing when all report bundles that are defined with a Wait/Ignore Indicator of Wait are loaded.
•Time of Print: The distribution is scheduled when the first report bundle of the distribution is archived or stored in Content Manager OnDemand. Before the Time of Print time, the distribution is submitted for print processing whenever all of the report bundles with a Wait/Ignore Indicator of Wait are loaded. If all of the required reports are not available at the specified time, when the Time of Print time is reached, the distribution is submitted for print processing with whatever report bundles are available.
•Time of Day: The distribution is scheduled at the specified time of day. It is submitted for print processing when all of the report bundles defined with a Wait/Ignore Indicator of Wait are loaded.
•Time: The time when the distribution is processed. The default value is the current time. This field displays only if the distribution method is set to Time of Day, or Time of Print.
Continue/Wait indicator
This option is valid only when the Distribution Method is Time of Day or Time of Print. From the drop-down list, select either Continue to continue processing report bundles as they are available after the Time is reached, or select Wait to wait until the next Time occurrence to print any report bundles that become available.
Continue Max Tries
This value controls the maximum number of attempts that are made to process the report bundles.
Manifest Indicator
This value indicates whether a manifest page, which lists the report bundles that are included in the distribution, must be created. The manifest defaults to a separate file. If you want the manifest in the same file as the report bundles, specify Manifest in Sysout.
Report Break Indicator
This value indicates whether the report bundles must be included in the same file or broken up into separate files.
Print Options tab
Use the Print Options tab to specify the allocation values to use for the JES spool file. These options do not apply to our example distribution.
14.2.5 Adding a report bundle
After you define the distribution, you must define the report bundles that are included in the distribution. To add a report bundle, right-click the distribution that you added and then select Add Report Bundle. See Figure 14-9 on page 326.
Figure 14-9 Adding a report bundle
Distribution Name and Recipient/Recipient List
The report bundle is created as a child object of the distribution. The values are not modifiable and disabled in the window.
Sequence
This value identifies the sequence that the report bundles are included in the distribution. The default is 10, and each new report bundle increments the sequence by 10. This value provides flexibility to add report bundles without the need to renumber any other report bundles.
Report ID
This number identifies the report to include. For our example, we select the previously added report ID from the drop-down menu.
Wait/Ignore Indicator
When more than one report bundle is specified in the distribution, this value tells ODF whether this report bundle must be available before the distribution is processed. A value of Wait indicates that you wait until this report is loaded before the distribution processing begins. A value of Ignore indicates that the distribution is processed even if this report bundle is not available. This function is useful if documents are loaded at different times but you want them to be processed and included in a single distribution instance.
Report Build
This field indicates whether the distribution must include the full report or if a query will be performed and only a portion of the report will be included. When Query is selected, the SQL source option is available to build the query. You can either type the query by using the Keyboard option or build the SQL, as shown in Figure 14-10 on page 327. For our example, we build a query to include only the statements for John Doe.
Figure 14-10 Building the SQL query
Additionally, users can specify a wildcard with a substring in the SQL statement. On execution, ODF will substitute the correct portion of the recipient or recipient list name.
The format of the wildcard is shown:
•$ODF_RECIPIENT(start pos:length) where start pos is the number of the characters to start and length is the number of characters to use. (start pos:length) is optional.
•$ODF_RECIPLIST(start pos:length) where start pos is the number of the characters to start and length is the number of characters to use. (start pos:length) is optional.
Job Name, Location, Dataset Name, and Print Options
These fields can be used to override the values that are specified in the distribution definition. Use this capability to specify the values at the distribution level that apply to most of your report bundles and still customize for individual report bundles.
14.3 Defining the objects by using batch administration
ARSXML provides a batch interface to add, update, delete, or export a list of ODF objects. We show the arsxml command and a sample XML file that is used to create each of the objects that we added earlier.
14.3.1 Recipient
Run the following command to add a recipient:
Arsxml add -h myod -u myuser -p mypwd -v -i /recipientAdd.xml
Example 14-1 on page 328 shows the content of our example recipientAdd.xml file.
Example 14-1 recipientAdd.xml
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfRecipient name="00001"
fullName="John Doe"
email="[email protected]"
addr1="123 Anywhere Place"
addr2="Anytown, AA 11111"
banner="true"
header1="/*************************/"
header2="/* */"
header3="/*************************/" />
</onDemand>
14.3.2 Report ID
Run the following command to add a report ID:
Arsxml add -h myod -u myuser -p mypwd -v -i /reportIDAdd.xml
Example 14-2 shows the content of our example reportIDAdd.xml file.
Example 14-2 reportIDAdd.xml
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfReportId name="CREDIT STATEMENTs"
status="Active"
applicationGroup="Credit Card Statements"
application="Credit Card Statements" />
</onDemand>
14.3.3 Distribution and report bundle
Run the following command to create a distribution and report bundle:
Arsxml add -h myod -u myuser -p mypwd -v -i /distributionAdd.xml
Example 14-3 shows the content of our example distributionAdd.xml file.
Example 14-3 distributionAdd.xml
<?xml version="1.0" encoding="UTF-8" ?>
<onDemand xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ondemand.xsd">
<odfDistribution name="CREDIT CARD STATEMENTS"
recipient="00001" s
tatus="Active"
location="E-mail document"
manifest="Manifest"
reportBreak="false"
distMethod="Loaded" >
<odfReportBundle sequence="10"
reportId="CREDIT STATEMENTS"
reportBuild="Query" >
<sql >WHERE name = 'John Doe' </sql>
</odfReportBundle>
</odfDistribution>
</onDemand>
14.4 Customizable user exits
ODF provides several user exits with which you can tailor the system to meet your installation’s requirements. You can optionally use the sample exits that are provided or customize the exit to meet your specific needs.
14.4.1 arsodfxa: Spool file dataset allocation attributes exit
You can use the arsodfxa spool file dataset preallocation exit to modify the currently defined ODF JES spool file dataset output parameter definitions that are used for dynamic allocation of the report and manifest JES spool file datasets. The arsodfxa exit is called when ODF detects a non-blank Customer Variables field in either the ODF distribution or report bundle definition, but only if the field value is not set to DO NOT SCHED or NOSCHED.
The output parameters that are specified in the report bundle definition and the output parameter string are passed to the arsodfxa exit. The exit can modify the output parameter string. The string that is returned from the user exit is used to allocate the JES spool file datasets for the report bundle and manifest JES spool file datasets.
14.4.2 arsodfxb: Banner, header, and trailer exit
On z/OS, use the arsodfxb exit to customize the banner information that is written to the JES spool file datasets. Banner information is written to the JES spool file dataset when the recipient definition requests that a banner is printed and the location of the report bundle is Print. ODF calls the arsodfxb exit for three different types of banner data:
•Banner page
Information to be written before the first report bundle in the distribution is written to the JES spool file dataset. The exit is called at the start of processing the first report bundle within the distribution with ODFBANER-REQUEST-TYPE = 1 to process banner information.
•Header page
Information to be written before the second and each subsequent report bundle in the information. The exit is called before each subsequent report bundle within the distribution with ODFBANER-REQUEST-TYPE = 2 to process the header information. See Example 14-4 on page 330.
•Trailer page
Information to be written to the JES spool file dataset after the report bundle is written. The exit is called after each report bundle is processed with ODFBANER-REQUEST-TYPE = 3. The exit is passed information about the report bundle and recipient, and the exit uses this information to format the lines to display.
The exit returns a buffer of data. The maximum size is 10,240 bytes. The exit formats the data and adds a new line character x'15' wherever the data must start on a new line in the spool file.
Example 14-4 Banner header page sample output
/********************************************/
/* My Reports */
/********************************************/
****** ***** ****** ****** ******
** ** ** * ** ** ** **
** ** ** ** ***** ***** *******
** ** ** ** ** ** ** **
***** ****** ** ****** ******
*****BANNER PAGE*****
**********************************************************************
* *
* REPORT INFORMATION *
* *
* REPORT ID: CREDIT STATEMENTS *
* REPORT: *
* REPORT DATE: 2013-06-20 *
* *
* PRODUCED FOR: *
* *
* RECIPIENT: 0001 *
* REQUEST DATE: 2013-06-20 *
* REQUEST TIME: 07:46:55 *
* *
**********************************************************************
14.4.3 arsodfxm: Bundle manifest exit
On z/OS, the sample arsodfxm user exit is a COBOL program that enables you to customize the manifest output. The manifest consists of Header and Detail lines. ODF calls the bundle manifest exit with two functions: one function to process the header section of the manifest and the other function to process the detail lines.
When the request type is Header, the exit returns a buffer of data. The maximum size is 1,024 bytes. The exit formats the data and adds a new line character of x'15' wherever the data needs to start on a new line in the spool file.
14.4.4 ODFProcessDist.java: Processed distribution exit
Use the ODFProcessDist.java user exit program to customize the ODF output in several ways. You can customize the email attachment or the email notification content. You can customize the print and file output on platforms other than z/OS.
You can customize the ODF output in the following ways:
•Customize the details and format of the outgoing emails that contain distributions when the value of the distribution location field Location is set to “E-mail” or for any Location value with the “Notify by e-mail” check box selected. For each distribution location type, you can customize the email content and the maximum size for email attachments within a single email.
•Customize the details of distribution output for all other distribution types on Content Manager OnDemand for Multiplatforms servers, and for all distribution types on z/OS except when the Location value is set to Print. Specify your Simple Mail Transfer Protocol (SMTP) server name to use for outgoing email.
•Specify whether to enable the Secure Sockets Layer (SSL) when you use the SMTP server to send email.
•Specify trace parameters.
•On Content Manager OnDemand for Multiplatforms servers, specify the name of the command to use to submit ODF print requests and the name of the printer queue to use.
The ODFProcessDist.java program uses the ARSODF.XML file as input. The ARSODF.XML file allows customization of the ODF output without modifying the ODFProcessDist.java program. ODF includes a complied version of the sample ODFProcessDist.java program. You can use the sample program as-is, or you can modify the sample program and recompile it to further customize outgoing distribution details.
14.5 Status and monitor tool
The OnDemand Monitor is an interactive workstation client program to check the status of distributions that were submitted for processing and to monitor ODF activity on Content Manager OnDemand servers, beginning at version 9.5. Use this tool to issue a reprint or initiate distributions, as needed.
Figure 14-11 shows the view of the OnDemand Monitor.
Figure 14-11 Overall view of the OnDemand Monitor
Figure 14-12 on page 332 shows a snapshot of ODF activity.
Figure 14-12 Snapshot of ODF activity
The filter reflects the values that were selected to populate the rows in the tabbed section (Figure 14-13).
Figure 14-13 Applying a filter
Figure 14-14 show all of the defined distributions and the most recently requested information.
Figure 14-14 Defined distributions
Figure 14-15 shows all of the distributions that match the filter criteria.
Figure 14-15 Requested distributions
Figure 14-16 shows that all of the reports were loaded and that they are available for processing.
Figure 14-16 Scheduled reports
Figure 14-17 shows all of the report bundles that are being processed or were processed.
Figure 14-17 Processed report bundles
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.