Chapter 10   Reports


This chapter provides information for configuring the Actuate report writer, creating new reports, and modifying existing BuyerXpert/SellerXpert reports.

---

Note	For overview material on reports, refer to the Concepts document or the online Help for the BuyerXpert/SellerXpert User interface.

---

This chapter contains the following sections:

• About Administering Reports

• Administrator's Report Tasks

• Configuring Actuate Reports for BuyerXpert/SellerXpert

• Creating New Reports

• Modifying Existing Reports

• Adding Reports to the BuyerXpert/SellerXpert Framework

• Making Reports Available

About Administering Reports

---

Three types of BuyerXpert/SellerXpert reports are created using the Actuate report writer:

• User reports

• Administrator reports

• Manager reports

An extensive set of these reports is supplied with BuyerXpert/SellerXpert, but users cannot access them until you have configured Actuate for BuyerXpert/SellerXpert and set up the report business rules. The reports are listed in Concepts and in the User interface Help.

Before doing any reports administration, the following must be true:

• Actuate Developer Workbench is installed and operational. If it is not, follow instructions in the Installation Guide.
  

  ---

  Note	The Actuate instance must be on the same machine as the BuyerXpert/SellerXpert instance or the installation script will not function properly.

  ---

  
  

• The BuyerXpert/SellerXpert database is installed and operational.

Administrator's Report Tasks

---

To perform the tasks in this chapter, you must have basic knowledge in:

• Actuate Developer Workbench (Actuate documentation provided)

• How databases work

• BuyerXpert/SellerXpert database schema

Table 10-1 contains a list of your report tasks. The right-hand column provides information about where to find instructions, guidelines, or tools for performing that task.

Table 10-1    Administrator's Reports Tasks 

Task	Location of Instructions/Guidelines/Tools
Configure Actuate.	Configuring Actuate Reports for BuyerXpert/SellerXpert section
Set up reports business rules.	Chapter 5 "Setting Up Business Rules"
Create new reports.	Creating New Reports section
Modify reports.	Modifying Existing Reports section
Integrate reports to BuyerXpert/SellerXpert.	Adding Reports to the BuyerXpert/SellerXpert Framework section
Publish reports.	Making Reports Available section

Configuring Actuate Reports for BuyerXpert/SellerXpert

---

The following tasks are required to configure the Actuate reports for BuyerXpert/SellerXpert:

• Creating a New Actuate User

• Creating the Folder Structure

• Setting Up Folder Permissions

• Setting Up User Preferences

These tasks are explained in the following sections.

Creating a New Actuate User

To create a new Actuate user:

1. Log into the Actuate Administrator application. The first time you log in, the Report Encyclopedia Login screen displays.

   
   
   

2. Enter user name, password, and volume.

   The Actuate Administrator Desktop displays. This is where you can add folders and users. Reports and roles will be added to the server by an installation script.

   
   
   

3. Right click User and select New User from the drop down box.

   The properties - New User box displays.

4. Enter the following information in the Properties - New User fields:
   • User name: anonymous

   • New password: <blank>

   • Confirm password: <blank>

   • e-mail address: <blank>

   • Web viewing: Dynamic HTML (DHTML)

   • Personal folder: <blank>

5. Leave the rest of the tabs as the default (specify later).

6. Click OK.

   The user you have created displays in the frame furthest to the right.

Creating the Folder Structure

After creating a new Actuate user, you are ready to set up the folder structure.

---

Note	It is important that you name the folders exactly as specified here or BuyerXpert/SellerXpert will not be able to access the Actuate reports.

---

To create the folders:

1. Click the main Library.

   Your reporting instance displays. In the example, it is called Cheunger.

2. Select New Folder from the drop down box.

   
   
   

3. Name the folder BXreports.

4. Create two sub-folders under BXreports called Reports and Output.

   
   
   

Setting Up Folder Permissions

After creating the folder structure, you are ready to set up folder permissions.

Folder permissions are crucial for sustaining BuyerXpert/SellerXpert reports security. One folder provides users with execute privileges and the other folder serves as a temporary storage area for previously-run reports. The temporary storage folder does not have read privileges. This prevents users from accessing reports they are not authorized to view.

To set up permissions for a folder:

1. Right click the folder.

2. Select properties.

3. Select the Privileges tab.

4. Select Show Only Users.

Set up the permissions for the new Actuate user according to Table 10-2.

Table 10-2    Report Folder Permissions

Permission	Folder Name	Description of Folder
Read	BXreports	Main directory
Execute	BXreports/Reports	Contains report executables
Write	BXreports/Output	Contains previously run reports

Setting Up User Preferences

User preferences allow users to view reports in DHTML and will disable email notification.

To set up user preferences:

1. Click User.

2. Right click the anonymous user.

3. Choose Properties. A properties box displays

4. In the General tab, choose Dynamic HTML (DHTML) from the viewer preference section.

5. Select the Notification tab and un-check all the boxes.

6. Click OK.

Creating New Reports

---

The following topics are addressed in this section:

• Understanding Page Layout Sections

• Creating a Framework with the Report Wizard

• Adding Additional Data to Reports

• Verifying a New Report

Understanding Page Layout Sections

There are many page layout sections in each report. An understanding of the following sections is necessary for correctly displaying your information.

• After—This information appears at the end of the report. PageFooter information does not appear in HTML reports.

• Before—This places information at the very beginning of the section. This information does not repeat.

• Content—This is the area where you enter your detailed content.

• GroupSection—This helps you logically organize your information into groups. All the information that a particular user creates is kept together.

• PageFooter—This information is repeated at the end of every page in the report.

• PageHeader—This information is repeated at the top of every page in the report. If any information exists for a Before section, the PageHeader follows. PageHeader information does not appear in HTML reports. All labels and field headers appear in this section.

• Subpage—This section is for content unrelated to your report. For example, this is where a logo or a disclaimer could be added to the end of every report.

Scenario: New Report
You are creating a report that provides details on all the orders that were created within a week, categorized by user. You want to know the order number, the description of what was ordered, and the total cost of the order. Totals should be at the user level and the report level. The following are the sections, with associated content, that you must provide to create the report:

• Report:Before—Nothing.

• Report:PageHeader—Enter the standard header information such as title, report parameters, company logo, and the field labels.

• GroupSection1:Before—Enter the user name because the report is required to be categorized by each user. This allows all the information created by a each user to appear together.

Creating a Framework with the Report Wizard

The Actuate report wizard is a tool that simplifies the task of creating a report framework.

---

Note	Do not attempt to create an entire report in the report wizard. The report wizard is only used for preparing the report framework.

---

Before using the report wizard, the following must be true:

• A development database must be set up on a staging server.
  

  ---

  Note	The production database should not be used to build or test reports.

  ---

  
  

• The Oracle client must be installed on your staging server and the tnsnames.ora file must be properly configured to access the Oracle database.

To create a report using the report wizard:

1. Select New Report Wizard from the pop up screen that appears when you open Actuate, or select New from the file menu.

2. Click OK.

   The New Report Wizard appears with the About Wizard tab displayed.

3. Click Next.

   The Connection screen appears.

4. Set up the database connection as follows:
   • ConfigKey = <blank>

   • DisplayNamE = Oracle Connection

   • DllPath = OCIW32 or default

   • HostString = your Oracle database name

   • Password = development password

   • Username = development username

5. Select among the following tabs:
   • Tables and Views—Choose the tables and views you want to report on.

   • Sorting and Grouping—Choose the groups you want in the report. This creates extra sections in the report to assist you in the logical organization of your data.

   • Fields—Select this to add fields to the report, which can be customized later.

   • Page Styles—Skip this by selecting Finish.

Adding Additional Data to Reports

If you are expecting data that you cannot find using the selection criteria, you need to go into the data source for the report:

1. Click somewhere in the Component Editor.

2. Select View - Datasource, or click the icon for the data source.

3. Select additional data fields.

For more information refer to Actuate online Help at:

http://www.actuate.com/customer_zone/install_doc.asp.

Verifying a New Report

After the report is complete, run it against a database with enough data so you can see how the report will look. You may need to modify the width of the fields so they fit the width of the page.

Modifying Existing Reports

---

To modify an existing report, first make a copy of the report, then make modifications to the copy as follows:

1. Open Actuate Administrator Desktop.

2. Log in as Administrator.

3. Select the Reports folder.

4. Right click the folder.

5. Select New Report Item.

6. Select the modified file and click OK.

7. Make your modifications.

8. Rename the report.

9. Verify your modifications by running the report against a database that contains enough data so see can how the report will look.
   

   ---

   Note	You may need to modify the width of the fields to fit the width of the page.

   ---

   
   

10. Return the modified report to the Actuate Administrator Desktop.

    The reporting architecture finds the new report in the directory where you place report design files. (A design file defines what information a report contains and how that information is presented.) If the modified report is not found in the design file directory, BuyerXpert/SellerXpert defaults to the original report.

Scenario: Modified Report
To specify a different report executable for a specific country, you must add an entry to the reportsInfo.ntv file which is a text file located in the BuyerXpert/SellerXpert configuration directory on the application server. The file is updated to add new or modified reports to the BuyerXpert/SellerXpert framework.

The reportsInfo.ntv file has nested NTVs. The deepest level contains individual ntvs that contain configuration information for individual reports. An NTV file is a configuration file with a listing of variable names and their values. Here is a partial example of a reportsInfo.ntv file:

...

"my_reqs" NTV {

// the parameters required for this report

"params" StrArr [ "start_date", "end_date", "currency" ],

// the "static" field labels which appear in the report

"staticLabels" StrArr ["l_start_date", "l_end_date", "l_total"],

// the report executable file name

"executable" NTV {

"default" Str "moo.rox",

"en_US_Variant" Str "goo.rox",

}

},

...

By adding entries to the executable NTV, you can specify a different executable for a specific locale. All others will use the default executable. The naming convention for the locales is:

language_country_variant

Adding Reports to the BuyerXpert/SellerXpert Framework

---

Any new or modified report whose parameters are a subset of the valid parameters described in report_parameters.xls file can be added to the SellerXpert framework. Table 10-3 lists the valid parameters.

Table 10-3    Report Parameters 

Parameter	Type	Label	Description	Validation Rule
start_date	Text box	Starting date	Pre-populated with current date minus 7 days.	Must be a valid date.
end_date	Text box	Ending date	Pre-populated with today's date.	Must be a valid date.
user_org	Hidden		For use in administrator reports to specify a user organization.
currency	Pulldown	Show in currency	Pulldown of supported currencies. The user's default preference is selected.
org_unit	Text box		For use in administrator reports to specify a user organizational unit.
organization	List box	Organization	A list of organizations.
cost_cntr	Text box		Pre-populate with *.	Must be an integer or *.
sku	Text box		Pre-populate with *.
product_description	Text box	Product description	A description of the product.
requisitioner	Text box		Pre-populate with *.
vendor	Text box		Pre-populate with *.
sort	Radio button		Radio button to select ascending or descending.
start_cost_center	Text box			Must be an integer.
end_cost_center	Text box			Must be an integer.
cost_cntr_seg	Text box			Must be an integer or *.
code_segments	Text box
code_contains	Text box		Pre-populate with *.
req	Text box		Pre-populate with *.	Must be an integer or *.
actor	Text box		Pre-populate with *.
approver	Text box		Pre-populate with *.
event	Text box		Pre-populate with *.
status	Text box		Pre-populate with *.
department	Text box		Pre-populate with *.
ship	Text box		Pre-populate with *.
rec_by_dt	Text box		Pre-populate with today's date.	Must be a valid date.
total	Text box		Pre-populate with 0.00.	Must be a valid currency.
acct_code_seg	Text box
user_id	Hidden		The current user's ID.
company	Hidden		The current user's company.
org_unit_list	Hidden		A list of the user's orgUnit and all "child" orgUnits.
round_per_1	Hidden		Used for currency conversion.
round_per_2	Hidden		Used for currency conversion.
round_meth_1	Hidden		Used for currency conversion.
round_meth_2	Hidden		Used for currency conversion.
rpt_type	Hidden		1 = user, 2 = manager, 3 = admin, 4 = superadmin.

Making Reports Available

---

New and modified reports must be made available to BuyerXpert/SellerXpert through the reportsInfo.ntv file. This text file is located in the BuyerXpert/SellerXpert configuration directory on the application server.

To add a new or modified report to the BuyerXpert/SellerXpert framework by updating the reportsInfo.ntv file:

1. Decide which category the report belongs to. The report must fall under one of the main categories of the reportsInfo.ntv file:
   • UserReports

   • ManagerReports

   • AdminReports

2. Add your report to an existing subcategory or to a subcategory that you create.

   Subcategories, which reside under each main category, are numbered sequentially and begin with subcategory1. Each main category can contain any number of subcategories and each subcategory can contain any number of reports. New subcategories are added as NTV entries in the reportsInfo.ntv file.

Example
A reportsInfo.ntv file at the subcategory level:

"subcategory1" NTV {

"reports" StrArr ["my_reqs","my_approved_reqs","my_cancelled_reqs", "my_declined_reqs"],

// each report is represented by an NTV

"my_reqs" NTV {

// the parameters required for this report

"params" StrArr ["start_date", "end_date", "currency", "company", "user_id"],

// the "static" field labels which appear in the report

"staticLabels" StrArr ["lab_adj", "lab_co_name", "lab_cr_dt", "lab_disp_cur"],

// the report executable file name

"executable" NTV {

"default" Str "MyRequisitions.rox",

},

},

3. Define a report by a code within the subcategory. In the previous example the report code is my_reqs. The report code names are arbitrarily created but should reflect of the report's content. The code name must also be included in the reports string array in the subcategory:

   "reports" StrArr ["my_reqs"],

4. Create an NTV entry for the report. The previous example contains the following NTV entry components.
   • Report parameters

   • Static labels

   • Report executable

   • Report parameters—Identified by the params entry. The parameters in the params list tell the framework how to generate the requester form for the report. See the list of available parameters in Table 10-3.

   • Static labels—Optional. Static labels are used to define language specific text fields in reports. For example, in an English report the text specifying price would be different from a Spanish report. These static labels are defined within the messages.ntv file in the static labels section. The messages.ntv file is a local specific configuration file that specifies the language-sensitive text used in Actuate reports and BuyerXpert/SellerXpert.

     To modify a static label, open the messages.ntv file. The syntax for the static labels in the messages.ntv file is:

     "Reports:labels:<label name>" Str "<label text>",

     The <label name> is the static label name and <label text> is the display text that should appear in the report.

   • Report executable—The executable NTV structure defines the .rox Actuate report executable. Report executables can be overridden for a given locale.

     Insert the file name of the report you want to add. For example:

     // the report executable file name

     "executable" NTV {

     "default" Str "<file>.rox",

5. Add an entry into the messages.ntv file for the subcategory title. For the example we have been using the entry in the messages.ntv file is:

   "Reports:userReports:subcategory1:my_reqs" Str "My Requisitions",