Managing the Deferred Ticket Cleanup Utility

In this section:

The Managed Reporting Deferred Ticket Cleanup Utility (mrdtcleanup) enables users permitted to Manage Private Resources to clean up (delete) deferred tickets of Managed Reporting users that do not have corresponding report output on the WebFOCUS Reporting Server to which the deferred request was submitted. Running this utility deletes the deferred tickets for deferred report output deleted by the WebFOCUS Reporting Server as specified by the dfm_maxage deferred management parameter. The dfm_maxage parameter defines the maximum number of days that deferred reports are kept on the WebFOCUS Reporting Server after they are created.

Additionally, deferred requests submitted to WebFOCUS Reporting Servers that are not defined in the WebFOCUS Client configuration file (odin.cfg) are also deleted. Before running this utility, it is important to confirm that there have not been any WebFOCUS Reporting Server nodes temporarily removed from the WebFOCUS Client odin.cfg file.

The Deferred Ticket Cleanup Utility (mrdtcleanup) is located in the /ibi/WebFOCUS80/utilities/mr directory. On Windows, there is a mrdtcleanup.bat file and on UNIX-based platforms there is a mrdtcleanup script file. You can run the Deferred Ticket Cleanup Utility in interactive mode, silent mode, or help mode. Silent mode is useful for overnight batch processing. For information on running the utility in all modes, see Running the Managed Reporting Deferred Ticket Cleanup Utility.

Note: On IBM i platforms, the Deferred Ticket Cleanup Utility is only supported in silent mode.


Top of page

x
Deferred Ticket Cleanup Utility Processing

The Deferred Ticket Cleanup Utility processes the information within the WebFOCUS Repository configured for the WebFOCUS Client. All active and inactive deferred tickets of Managed Reporting users within the specified WebFOCUS Repository are processed.

Deferred reports for each Managed Reporting user are processed individually. During processing, deferred tickets in deleted domains are removed because the domain does not exist. The remaining deferred tickets for the user are then processed by making a single connection to each WebFOCUS Reporting Server to which the user has submitted deferred tickets. If the WebFOCUS Reporting Server is not defined in the WebFOCUS Client configuration file (odin.cfg), the deferred tickets submitted to that node are deleted from the WebFOCUS Repository because the WebFOCUS Client cannot make a connection to that server to process the deferred tickets.

When a successful connection is made to the WebFOCUS Reporting Server, it returns status information for each of the deferred tickets submitted to that server. The WebFOCUS Client processes the status information to confirm the existence of deferred report output. Deferred tickets, for which report output does not exist, are deleted from the WebFOCUS Repository.

If the WebFOCUS Reporting Server is defined in the WebFOCUS Client configuration file (odin.cfg), but the WebFOCUS Client cannot establish a connection, the users deferred tickets for that WebFOCUS Reporting Server are not deleted. Deferred tickets are only deleted upon confirmation that deferred report output does not exist.

Each time the Deferred Ticket Cleanup Utility runs, a log file and a backup of the HTML file for each user are created. For information on the log file and backup files that the Deferred Ticket Cleanup utility creates, see Deferred Ticket Cleanup Utility Log File.


Top of page

x
WebFOCUS Repository and User Credentials

The Deferred Ticket Cleanup Utility processes the default WebFOCUS Repository in the WebFOCUS Client configuration. The user running the Deferred Ticket Cleanup Utility must be authorized to Manage Private Resources. When running in interactive mode, the utility prompts for Managed Reporting credentials. When running in silent mode, the Managed Reporting credentials must be passed as parameters to the utility. For more information, see Running the Managed Reporting Deferred Ticket Cleanup Utility.


Top of page

x
WebFOCUS Reporting Server and User Credentials

How to:

Reference:

For one or more WebFOCUS Reporting Servers, user credentials can be optionally specified in the site.wfs file for running in interactive mode and are required in site.wfs for running in silent mode. You can edit the site.wfs settings in the WebFOCUS Administration Console from the Custom Settings panel available near the bottom of the Configuration section. There is an option in the console to encrypt the site.wfs file, which is recommended to secure the user credentials.



x
Syntax: How to Specify Server Credentials in Site.wfs

Edit the site.wfs file using the following syntax:

<ifdef> IBIMR_dtcleanup
WF_CCREDENTIALS=node1:id1:pwd1|node2:id2:pwd2|...
<endif>

where:

node1

Is a WebFOCUS Reporting Server node name (NODE) that must be defined in the WebFOCUS Client odin.cfg configuration file (/ibi/WebFOCUS80/client/etc/odin.cfg). This file is accessible in the WebFOCUS Administration Console from the Remote Services panel under the Reporting Servers menu.

You can use an asterisk (*) for the node name if you want to specify the same user ID and password for all server nodes, which is useful if there are servers in a cluster. You can also use a combination of asterisk (*) and specific node names for some WebFOCUS Reporting Servers.

id1

Specifies the WebFOCUS Reporting Server user ID for the first server node specified.

pwd1

Specifies the password for the WebFOCUS Reporting Server user ID.

The Deferred Ticket Cleanup Utility reads the odin.cfg file to obtain the WebFOCUS Reporting Server node connection information. In interactive mode, the user may specify a different WebFOCUS Reporting Server user ID and password and additional WebFOCUS Reporting Server node names and credentials than those specified in the site.wfs file. In silent mode, the WebFOCUS Client automatically attempts to log on to the WebFOCUS Reporting Servers without prompting for credentials.



x
Reference: Validation of Server Credentials in Silent Mode

Validation of WebFOCUS Reporting Server credentials is not performed when a user initially specifies credentials. Validation is not performed because the WebFOCUS Reporting Servers to which the deferred tickets were submitted are not determined until the utility processes Managed Reporting user deferred report information. Additionally, there may be WebFOCUS Reporting Servers running that are not in secure mode, making credentials unnecessary for establishing a connection. Not performing validation when the utility begins processing eliminates the unnecessary overhead of connecting to servers to which no Managed Reporting users have submitted deferred requests.



x
Reference: WebFOCUS Reporting Server Processing

The deferred ticket information for each Managed Reporting user is processed separately. The number of times a connection is made to a WebFOCUS Reporting Server depends on the number of Managed Reporting users that have deferred tickets for that server. Only one connection is made per user for the processing of deferred tickets for each server.



x
Reference: Trusted Reporting Server Connection Restriction

Because the Deferred Ticket Cleanup Utility is a standalone program, you cannot run the utility in an environment that uses a Trusted connection to the Reporting Server. As a standalone program, the Deferred Ticket Cleanup Utility is unable to retrieve credentials to connect to the Reporting Server. If you must cleanup deferred tickets with a Trusted Reporting Server connection, use the Deferred Status Interface.


Top of page

x
Deferred Ticket Cleanup Utility Log File

Reference:

Each time the Deferred Ticket Cleanup Utility runs, the WebFOCUS Client creates a log file that contains processing details.



x
Reference: Deferred Ticket Cleanup Utility Log File

The log file contains processing details, such as timestamp information, at the beginning of each file. All information is included, and the Managed Reporting user credentials are written to the file with the password masked for security reasons. The file name of the log file is in the following format:

mrdtcleanup_date_time.log

where:

date

Is the date the log file was created in Year Month Day (YYYY-MM-DD) format.

time

Is the time the log file was created in Hour Minute Second (HMS) format.

Log files are created in the drive:\ibi\WebFOCUS\logs directory and can be viewed by clicking the MR Deferred Ticket Cleanup Utility option on the Traces menu under the Diagnostics section of the WebFOCUS Administration Console, as shown in the following image.

To view information for a log file, in the right pane of the console, click the link for the log file with the desired date and time. To delete a log file, select the check box next to the log file and click the Delete button at the bottom of the console. You can also use the Select All and Deselect All options, as needed, or click the Refresh option to ensure that the latest information appears in the console.

The following is an example of a log file created in interactive mode.



Example: Sample Log File Created in Interactive Mode
0:=================================================================
1:   user log opened Mon Mar 18 07:34:52 EDT 2013
2:=================================================================
3:createWFLog(WFContext.java:2393):Starting WebFOCUS log-file for mrdtcleanup
4:main(MRDTCleanup.java:210):The Utility to delete Unknown Deferred Report Tickets has started...
5:isSilentMode(MRDTCleanup.java:294):as there was no option "-s" passed checking if silent mode is set in site.wfs file.
6:isSilentMode(MRDTCleanup.java:297):Silent mode not set in site.wfs
7:main(MRDTCleanup.java:212):Utility is running in interactive mode
8:isAuthenticatedUser(MRDTCleanup.java:524):Authenticating User: admin
9:runInInteractiveMode(MRDTCleanup.java:422):MR user is authenticated for MR Repository.
10:isMRAdministratorUser(MRDTCleanup.java:536):Authorizing User: admin
11:runInInteractiveMode(MRDTCleanup.java:439):User is authorized for MR Repository.
12:checkWFCCredentials(MRDTCleanup.java:559):Checking WF credentials information...
13:checkWFCCredentials(MRDTCleanup.java:579):No WF Reporting Server credentials specified in site.wfs WF configuration file.
14:checkWFCCredentials(MRDTCleanup.java:580):The Utility will prompt for the credentials to be provided by user
15:runInInteractiveMode(MRDTCleanup.java:476):Finished running utility in the interactive mode.
16:main(MRDTCleanup.java:223):MRDTCleanup utility finished processing.
17:=================================================================
18:   user log closed Mon Mar 18 07:41:49 EDT 2013
19:=================================================================

Top of page

x
Running the Managed Reporting Deferred Ticket Cleanup Utility

How to:

Reference:

The Deferred Ticket Cleanup Utility is an operating system-specific command program (mrdtcleanup) that calls a Java program named MRDTCleanup and is installed in the /utilities/mr directory under the WebFOCUS Client installation.



x
Reference: Requirements for Running the Deferred Ticket Cleanup Utility

The following are the requirements for running the Deferred Ticket Cleanup Utility:



x
Reference: Managed Reporting Deferred Ticket Cleanup Utility File Comments

The .bat and UNIX script files contain comments with the following sections clearly identified:

Parameters. Contains information on parameters accepted by the utility from the command line.

Purpose. Explains functional purpose of the utility.

Requirements. Explains information required for running the utility, and user authorization and authentication requirements.

Usage Notes. Contains information about arguments that the Java program (MRDTCleanup) accepts. You can obtain the help information by specifying '-h' as the first parameter.

Variable Definition. Variables created and used by the utility reside in the following files:

Interactive Mode. Command block for running in interactive mode. This is the default mode of execution.

Silent Mode. Command block for running in silent mode.

Help Mode. Command block for running in help mode to get usage information for the Java utility.



x
Procedure: How to Run the Managed Reporting Deferred Ticket Cleanup Utility

To run the Managed Reporting Deferred Ticket Cleanup Utility in silent mode or help mode, you must supply appropriate parameters. If no parameters are supplied, the utility runs in interactive mode and you are prompted for each parameter.

From the /utilities/mr directory under the WebFOCUS Client installation (for example, on UNIX: /ibi/WebFOCUS80/utilities/mr), enter the following on the operating system command line:

mrdtcleanup mode userid password

where:

mode

Is the mode in which the utility is run. If no value is entered, the default is interactive mode.

-I runs the utility in interactive mode.

Note: If you use this mode, do not include userid/password since you will be prompted for them.

-s runs the utility in silent mode.

-h returns argument information for the Java program (MRDTCleanup).

userid

Is the value of the Manage Private Resources user ID, which is required for silent mode.

password

Is the password for the Manage Private Resources user ID, which is required for silent mode.



x
Procedure: How to Run the Managed Reporting Deferred Ticket Cleanup Utility in Silent Mode

When you run the Deferred Ticket Cleanup Utility in silent mode, the Manage Private Resources user ID and password and the WebFOCUS Reporting Server node names and user credentials, must be provided because there is no user interaction while the utility is running.

To run the utility in silent mode, from the /utilities/mr directory under the WebFOCUS Client installation (for example, /ibi/WebFOCUS80/utilities/mr on UNIX), enter the following on the operating system command line:

mrdtcleanup -s userid password

Informational messages appear, informing you of processing status. Review the log file created by the utility to confirm that processing completed successfully.



x
Procedure: How to Run the Managed Reporting Deferred Ticket Cleanup Utility in Interactive Mode

When you run the Deferred Ticket Cleanup utility in interactive mode, it provides prompts and informational messages to help guide you through each step of the process of deleting unknown deferred tickets. To run the utility in interactive mode, perform the following steps.

  1. On Windows, from the \utilities\mr directory under the WebFOCUS Client installation (\ibi\WebFOCUS80\utilities\mr), on the operating system command line enter:
    mrdtcleanup

    On UNIX, from the /utilities/mr directory under the WebFOCUS Client installation (/ibi/WebFOCUS80/utilities/mr directory), on the operating system command line enter:

    mrdtcleanup

    The following messages appear:

    Managed Reporting utility to delete Unknown Deferred Report tickets is
    being called in Interactive Mode.
    The Utility to delete Unknown Deferred Report Tickets has started.

    On IBM i, the interactive mode is not supported. You must run the Deferred Ticket Cleanup utility in silent mode, as described in How to Run the Managed Reporting Deferred Ticket Cleanup Utility in Silent Mode.

  2. The utility prompts you for the WebFOCUS user credentials that are authorized to Manage Private Resources, and the password (with masking on the password). Once entered, the Managed Reporting process validates the credentials and is permitted with the Manage Private Resources privilege. If the Managed Private Resources privilege is not permitted, the following message displays.
    Enter valid WebFOCUS user ID authorized to Manage Private Resources
    of the users defined within the WebFOCUS repository:
    <value> (must be a non-blank value)
    Enter password:
    (press Enter for empty password value):*
    * (blank value permitted and value entered is masked by * for each
    character entered)
    Authenticating User: <user ID>

    You must be authorized to Manage Private Resources to run the Managed Reporting Deferred Ticket Cleanup Utility.

    If credentials are not authenticated successfully, the following message displays:

    Invalid user credentials.
    Would you like to enter another MR User ID and password? (yes/no)
    Enter “no” to skip processing of this repository or 
    press Enter to continue with “yes” value.

    If the WebFOCUS user credentials are not permitted to Manage Private Resources, the following message displays and the utility continues to prompt for WebFOCUS user credentials:

    Enter valid WebFOCUS user ID authorized to Manage Private Resources 
    of the users defined within the WebFOCUS repository:
    <user ID>
    Enter password: *
    Authenticating User: <user ID>
    Provided user is not authorized to manage private resources 
    of users within the WebFOCUS repository. 
    Would you like to enter another WebFOCUS User ID and password?(yes/no)
    Enter "no" to skip processing of this repository or press Enter to continue with "yes" value:
    Enter valid WebFOCUS user ID authorized to Manage Private Resources 
    of the users defined within the WebFOCUS repository:
    <user ID>
    Enter password: * 
    (press Enter for empty password value):*
    (blank value permitted and value entered is masked by * 
    for each character entered)

    When credentials are validated, the following message displays:

    Credentials successfully authenticated.
  3. The WebFOCUS Reporting Server node names are read from the WebFOCUS Client odin.cfg file and verified in the ifdef block of the site.wfs file, which defines the valid WebFOCUS Reporting Servers and user credentials that can be used by this utility. The following prompt displays:
    Checking for WF Reporting Server credentials optionally specified
    in WF Client configuration file (site.wfs)...
    Following WF Reporting Server is configured in odin.cfg:
    Node name : <server name> Host name : <host name>

    If WF Reporting Server nodes are not defined in site.wfs, the following prompt displays:

    No WF Reporting Server credentials specified in site.wfs WF Client configuration file.
    Would you like to provide credentials for WF Reporting Servers? (yes/no)
    Press Enter to continue with "yes" value:

    If WF Reporting Server nodes are defined in site.wfs, the following prompt displays:

    The following WF Reporting Servers have credentials specified in site.wfs
    for this utility:
    <server1 name>
    Would you like to change existing WF Reporting Server credentials or
    provide credentials for another WF Reporting Server?(yes/no)
    Press Enter to continue with "yes" value:
  4. If you want to provide additional WebFOCUS Reporting Server node names and user credentials, enter the appropriate information when the following prompts displays:
    Enter WF Reporting Server name: <server name>
    Enter user ID for WF Reporting Server: <user id>
    Enter password: 
    (press Enter for empty password value):*
    Would you like to provide credentials for another WF Reporting Server? (yes/no)
    Press Enter to continue with "yes" value:

    If WF Reporting Server nodes are not defined in odin.cfg, the following prompt displays:

    The WF Reporting Server name is not defined in odin.cfg WebFOCUS configuration file. Would you like to specify another WF Reporting Server? (yes/no)
    Press Enter to continue with "yes" value:
  5. When you are finished entering and validating WebFOCUS Reporting Server node names and user credentials, the utility begins processing deferred tickets for each WebFOCUS user stored in the WebFOCUS Repository. The following messages display on the screen in both interactive and silent modes.
    WebFOCUS Reporting Server credentials have been successfully validated.
    Starting processing WebFOCUS repository...
    Processing of <IBI_Repos_DB_URL value> starting.
    Processing the repository for all users
    WebFOCUS Manage Private Resources processing started.
    Retrieving deferred report information and verifying status...
    WebFOCUS Manage Private Resources processing completed.
  6. When all deferred tickets for each WebFOCUS user are processed, the following information displays:
    Exiting Managed Reporting utility to delete Unknown Deferred Report tickets.
    To verify results, please review log file mrdtcleanup_130318_073452.log
    The file is located in the /logs directory under WF Client install.
    Press any key to continue . . .


x
Procedure: How to Run the Managed Reporting Deferred Ticket Cleanup Utility in Help Mode

To run the Managed Reporting Deferred Ticket Cleanup Utility in help mode, from the /utilities/mr directory under the WebFOCUS Client installation (for example: /ibi/WebFOCUS80/utilities/mr on UNIX), enter the following on the operating system command line:

mrdtcleanup -h

The screen displays help information for Java program (MRDTCleanup) arguments. If additional arguments are included, they are ignored.

The argument information returned by the Java program (MRDTCleanup) provides information on the requirements and options for running the program. With this information, you can create a site-customized utility file to process your Managed Reporting deferred report tickets to perform tasks, such as processing multiple Managed Reporting repositories in silent mode.

The following help information is displayed when Interactive Mode is called with mrdtcleanup -h in the Managed Reporting Deferred Ticket Cleanup Utility:

================================================================
Managed Reporting utility to delete Unknown Deferred Report tickets
is being called with -h argument to request usage information.
================================================================
USAGE :
java MRDTCleanup [-?] [-s] -c(wfroot) [-r[userID.pass]]
ARGUMENT (args) FORMAT:
   -(?/h)  Get help; if no arguments, help information is displayed
           If more args after '-?' or '-h', they are ignored.
   -s      If present, turns on the silent mode.
           The WebFOCUS repository defined in the WF Client configuration
           is processed. WebFOCUS Reporting Server credentials MUST be
           specified in site.wfs as:
           <ifdef> IBIMR_dtcleanup
           WF_CCREDENTIALS=edanode1:id:pass|edanode2:id:pass|...
           <endif>
           Credentials information MUST be provided for each WF Server
           node in odin.cfg that deferred tickets have been submitted to.
   -c(wfroot) Fully qualified path to the installation directory
           where WebFOCUS Client is located.
           This parameter MUST be provided.
               -cC:\ibi\WebFOCUSXX
           where 'XX' is the WebFOCUS release number.
   -r(id.pwd) This argument is ignored if this utility is run in interactive mode!
           Credentials (user ID and password) for WebFOCUS repository configured
           in WF Client configuration must have Manage Private Resources privilege
           for all users defined in the WebFOCUS Repository.
   -r.id.password Format to specify WebFOCUS user credentials.
Press any key to continue...

Top of page

x
Troubleshooting

Reference:

The following topics will help you troubleshoot possible error codes, exception messages, and connection failures when running the Deferred Ticket Cleanup Utility.



x
Reference: Deferred Ticket Cleanup Utility Hangs on IBM i

If the Deferred Ticket Cleanup Utility hangs on IBM i platforms, then be sure that you are running it in silent mode. This utility is only supported in silent mode when running it on an IBM i platform.



x
Reference: Trace File

A trace file is available in the WebFOCUS Administration Console to view processing details for the Deferred Ticket Cleanup Utility. You must first turn on the WFServlet trace option, which is turned off by default. A trace file is created each time the utility is executed.

The file name of the trace file is in the following form:

00100_mrdtcleanup_WFAPI_date_time.trace

where:

date

Is the date the trace file was created in Year Month Day (YY-MM-DD) format.

time

Is the time the trace file was created in Hour Minute Second (HMS) format.

To view the resulting trace files, click the MR Deferred Ticket Cleanup Utility option on the Traces menu under the Diagnostics section of the WebFOCUS Administration Console, as shown in the following image.

To view information for a trace file, click the link with the desired date and time and .trace file extension that is listed in the right pane of the console. To delete a trace file, select the check box next to the file and click the Delete button. Click the Refresh option to ensure that the latest information appears in the console.



x
Reference: WFROOT Error

The WebFOCUS Client installation program installs the following mrdtdcleanup utility files under the drive:\ibi\WebFOCUS80 directory.

The installation program also substitutes the {wfinstallroot} value in drive:\ibi\WebFOCUS80\utilities\setenv\utilprodvars.bat.

When running the Managed Reporting Deferred Ticket Cleanup Utility, if the value of WFROOT is not the valid directory path to the directory where the WebFOCUS Client is installed, then the utility displays error exception information

Exception in thread "main" java.lang.NoClassDefFoundError: ibi/tools/MRDTCleanup

which occurs because the ibi.tools/MRDTCleanup java class could not be found. There is no log file available for troubleshooting because the log file is only created upon successful initialization of the utility.

If you encounter this error, edit the utilprodvars.bat file on Windows, or the utilprodvars script file on UNIX, located in utilities\setenv under the WebFOCUS Client installation directory, and manually correct the WFROOT variable setting to be the fully qualified path to the directory where the WebFOCUS Client is installed:

set WFROOT=installation_drive:\ibi\webfocus80


x
Reference: WebFOCUS Reporting Server Connection Failure

When deferred tickets are processed and the credentials provided are not valid, the WebFOCUS Reporting Server is unavailable, or there are no available agents on the server, no tickets for that server are deleted. The log information states that processing for that server failed because a connection could not be made to the WebFOCUS Reporting Server. The WebFOCUS Administrator can then investigate the processing failure, make adjustments, and run the utility again.

The Deferred Ticket Cleanup Utility receives the standard error codes and exception messages returned to the WebFOCUS Client for failed connections. The WebFOCUS Client file, /ibi/WebFOCUS80/client/wfc/etc/xxwebfoc_strings.lng (where xx is the language prefix), maps each error code with an explanation. For example, the following sample log file contains error code 32033, which appeared when attempting to connect to WebFOCUS Reporting Server EDASERVE:

27:deferredExecution(WFMRActions.java:3011):executing deferredGetStatus()
failed for the WF Server EDASERVE 
28:deferredExecution(WFMRActions.java:3012):WFErrorException has been
thrown!
29:deferredExecution(WFMRActions.java:3013):Exiting deferredExecution()
with the error code 32033 
30:deleteUnknownDeferTickets(WFMRRepository.java:2168):deleteUnknownDefer
Tickets: MR Error has occurred!
31:deleteUnknownDeferTickets(WFMRRepository.java:2169):WFMRError code:
32033
32:deleteUnknownDeferTickets(WFMRRepository.java:2170):WFMRError message:
Error occurred, rc = 32033
<ERROR 32033>
<ERROR 32034>
<HTML>
<HEAD><Title>WebFOCUS Message: Security Violation
</Title></Head>
<Body>
<H2>
Invalid Credentials
</H2>
</Body>
</HTML>
</ERROR>

In the WebFOCUS Client error file, \ibi\WebFOCUS80\client\wfc\etc\ENwebfoc_strings.lng, search for the error code to view more detailed information about the error.

err_32033=WebFOCUS Message: Security violation. Invalid credentials.
err_32033_1=Security violation. 
err_32033_2=Invalid credentials.


x
Reference: Silent Mode Failure

When you run the utility in silent mode and receive an error for WF Reporting Server nodes or user credentials, check that the WebFOCUS Client configuration file, site.wfs, contains WebFOCUS Reporting Server node name and user credentials information. Review the site.wfs file and confirm the following:


WebFOCUS