FFrraammeewwoorrkk

MMaannaaggeerr

MMaannuuaall

Kiran Vemula

2

Chapter 1: Framework Manager

Cognos Framework Manager is a metadata modeling tool. A model is a business presentation

of the information in one or more data sources. When you add security and multilingual

capabilities to this business presentation, one model can serve the needs of many groups of

users around the globe.

The model is packaged and published for report authors and query users. Report authors use

the published package in Cognos Report Studio to create standardized reports. Query users

use the package in Query Studio to create adhoc queries.

To get started with Framework Manager, you should understand

• the objects you work with in Framework Manager

• the recommended workflow for relational metadata or multidimensional metadata

Objects to Work With:

When you work in Framework Manager, you work in a project. A project contains a model,

Namespaces, data sources, and packages.

A model is the metadata layer that you imported from one or more data sources. The model

Provides a business presentation of the metadata.

After you define a Framework Manager Project and namespace, you can publish one or more

Packages containing metadata information to the Cognos ReportNet server for use by authors

and query users.

After a package is published to the Cognos ReportNet server, users can create reports and

queries in the Cognos ReportNet server runtime environment.

Projects:

A project is a set of models, packages, and related information for maintaining and sharing

Model information. Often a single project will span many more data sources or tables than any

set of users requires access to.

Models:

A model is the set of related query subjects and other objects required for one or more related

reporting applications.

The Framework Manager model is a metadata layer that adds value to a data source in several

ways. Most importantly, it provides a business view of the information in the source data to

report authors and query users to simplify building reports and queries. The business view can

• organize data items in folders that represent business areas for reporting

• format data items with numeric, currency, date, time, and other formats

• present multilingual folder and item names, description, tips, and data so that users can

operate in their language of choice

• automate the generation of SQL queries sent to the database

• specify default prompting.

3

This can include having Cognos Reportnet prompt the user with a descriptive name while

actually filtering on a code or key value for improved query performance.

You can modify the Framework Manager model to ensure that queries sent to the data source

are efficient, well formed, and secure. The Framework Manager modeler can

• specify the rules governing query generation

• restrict user access to specific rows or columns of data

• model data relationships to hide the complexity of data from report authors

Namespaces:

A namespace uniquely identifies query items, query subjects and other objects. You

import different databases into separate namespaces to avoid duplicate names.

Packages:

A package is a subset of the query subjects and other objects defined in the project. A

package is what is actually published to the Cognos ReportNet server, and it is used to create

reports and adhoc queries.

Query Items:

For report authors, query items are the most important objects for creating reports. Query

items have more properties than query subjects. These properties are what report authors use

to build the reports they want.

Query items are contained in query subjects. For example, a query subject that references an

entire table contains query items that represent each column in the table.

Query Subjects:

For modelers, query subjects and relationships are the most important objects in the model. In

Conjunction with relationships, you use query subjects to build the queries that get the answers

you want. A project is built upon query subjects.

In most cases, query subjects behave like tables. Query subjects produce the same set of rows

regardless of which columns were queried.

There are several types of query subjects:

• data source

• model

• stored procedure

A data source query subject directly references data in a single data source. When

metadata is first imported, a data source query subject is created by default for each table you

select. You can refine data source query subjects in various ways. For example, you can add

calculations or filters, or you can add or modify relationships between query subjects to define

the query generation rules for report authors.

A single Framework Manager project can contain data source query subjects from one or more

data sources from one or more vendors. This provides heterogeneous database access.

4

The data source columns and calculations returned by the SQL query are referred to as query

items. Model query subjects can contain query items from an arbitrary set of data source query

Subjects. Model query subjects can be enhanced by adding filters or calculations to

create additional query items. You can also use query subjects from other model query subjects.

The stored procedure query subject operates much like a data source query subject in that it

defines a set of query items that are available to the model from the underlying data source.

Stored procedure query subjects cannot be enhanced by filters or calculations.

5

Chapter 2: Designing a Project

A project is a set of models, packages, and related information for maintaining and sharing

model information. You design a project in Framework Manager to organize the metadata and

data you want, in a format that is meaningful to report authors.

When you design a project, consider how to organize it according to business needs. This

includes deciding what information to share and reuse and how to do so. You can create

segments, or extend a project to other users by linking to other projects. One way

of organizing your project is to create namespaces to allow duplicate query subjects or

query items in a project.

After you design your project, you can add and modify objects to better reflect your business

and prepare for reporting.

To design a Framework Manager project, do the following:

❑ Create a new project.

❑ Open an existing project.

❑ Import metadata from one or more data sources.

❑ Set up project management.

Project Files:

When you work in Framework Manager, you work in the context of a project. The Framework

Manager project contains objects that you organize for reporting authors according to the

business model and business rules of your organization. You view these objects in the project

page.

A Framework Manager project appears as a folder that contains a project file (.cpf) and the

specific .xml files that define the project. The files in a project folder are unique to each project.

Create a Project:

Before you can import metadata, you must create a project.

Steps:

1. From the Welcome page, click Create a new project.

2. In the New Project page, specify a name and location for the project.

3. If you want to add the project to a source control repository, click Repository, and then

select the Add to repository check box.

4. Click OK.

5. In the Select Language page, click the design language for the project.

The language you select cannot be changed after you click OK, but you can add others.

6. Click OK.

The Import wizard appears.

7. Choose whether to import your metadata now or later.

• To import, select the import source and click Next.

6

• To delay importing metadata, click Cancel.

You save the project file (.cpf) and all related XML files in a single folder. When you save a

project with a different name or format, ensure that you save the project in a separate folder.

Open a Project:

To import metadata into an existing project, you must first open the project. <project name>.cpf

The Framework Manager project file, which references the .xsd and .xml files used to define a

project model.xml The actual model data created by Framework Manager users Preferences.xml

The preferences for Framework Manager projects customdata.xml The stored diagram

information, such as the diagram layout, notation, font, and color. repository.xml The logged

version history for each project or segment that was added to a repository. This

file exists only if you have added projects to a repository.

Steps:

1. From the Welcome page, click Open a project.

2. Browse to locate the project folder and click the .cpf file.

3. If you want to open a open a project directly from a source control repository, click

Repository.

• In the Connection box, select the repository connection.

• In the Project file in repository box, select the .cpf file for the project you want to add.

• In the Create new local project folder in the directory and select the folder location

for the project.

• Click OK.

4. Click Open.

You may be prompted to upgrade if the model schema version is older than the currently

supported version.

The Project Page:

After you create or open a project , the project page appears. The project page is

the environment in which you design, package, and publish project metadata. This page

contains several panes and views that you can use to view and modify the objects in a project.

Project Viewer:

The Project Viewer shows the objects in a project in a hierarchical view. You can use the Project

Viewer to view, modify, and create these objects:

• query subjects

• data sources

• namespaces

• parameter maps

• folders

• segments

• links

• calculations

• filters

7

• packages

Note: Relationships and imported functions are shown in both the Object Diagram View and

Object Explorer Views.

Object Diagram and Object Explorer Views:

You can use both the Object Diagram and the Object Explorer Views to view, create, and modify

objects and relationships. You can also create folders and namespaces to group objects.

The Object Diagram View shows the relationships between objects in a project in a diagram.

Relationships between query subjects are shown as lines with cardinality notation. You can

expand objects that are grouped in folders to show the object hierarchy and the relationships

between query subjects.

In the Object Diagram View, you can also

• organize objects

Tip: From the Diagram menu, click Auto Layout.

• center a query subject

Tip: Click a query subject and, from the Diagram menu, click Set Focal Point.

The Object Explorer View shows the contents of a project, similar to any file system. Objects

can be arranged by name, class, or description. If you have a large number of objects in a

project, it may be easier to locate them in the Object Explorer.

Properties Pane:

The Properties pane shows the properties of the objects you last selected in either the Object

Explorer View, Object Diagram View, or Project Viewer. Object properties are set during import,

and some property values can be modified during modeling. You can use the Properties pane to

add, modify, or delete the properties of objects.

You can modify the properties for multiple objects at one time. If you select more than one

object, Framework Manager shows only the properties that are common to all the objects. You

can

• sort property values by double-clicking the property heading. An arrow appears to indicate

the direction in which values are sorted. You can toggle between ascending and descending

order.

• filter property values by clicking the arrow to the right of the property heading.

Tip: You can either click a value, or click Custom to define the criteria for the rows you want

to view.

• apply a property value to multiple objects.

Tip: Click the arrow next to the property and drag the highlighted area over the properties to

which you want to apply that value.

• resize the width of the rows and columns by right-clicking the object name in the property

pane.

Summary Pane:

The Summary pane shows the statistics and tasks available for a selected object.

Tip: To select an object, click the object in the Project Viewer, Object Explorer, or Object

8

Diagram.

The Statistics section shows the number of objects, by class, located in the currently selected

object. If the selected object contains a folder, the contents of the folder are included in the

number count. Selected objects include projects, namespaces, and folders. The default selected

object is the project.

The Tasks section shows actions that are applicable to the currently selected object, based on

the object class. If you select a folder, actions for the folder are listed. If you select an object in

that folder, the list includes actions for the object as well as for the folder.

You can find more information about the object classes in the

install_location\templates\bmt\CR1Model\BMTModelSpecification.xsd file.

Search Pane:

When you are working with a large project, it can be difficult to locate the objects that you need

to complete a task. The Search pane lets you quickly find objects by applying different search

criteria. You can either search for the object name alone, or add additional criteria, such as the

location, class, or a condition.

Naming Conventions for Objects in a Project:

All objects in a project must have a unique way to identify them. The reference can consist of

one, two, or three parts, depending upon the type of object. The parts include

• an object name

• a location in the project hierarchy, as expressed in the default language of the project.

Note: If you want to have two query subjects with the same name in a project, the closest

ancestor namespace must have different names.

Two-part Identifiers:

Query subjects and shortcuts to query subjects have a two-part identifier consisting of the name

of the containing namespace and the name of the object. The object name must be unique in

the nearest containing namespace.

For example, you have a GoSales namespace that contains a query subject named Product.

The Product query subject has the following name, where the square brackets and periods are

the syntax Framework Manager uses for object identifiers.[Go Sales].[Product]

One-part Identifiers:

Some objects in a project have a one-part identifier. The one-part identifier must be unique

across the entire project, even if the namespace contains other namespaces. These are the

objects that have a one-part identifier:

• namespaces

• functions

• shortcuts to namespaces

• shortcuts to folders

9

Three-part Identifiers:

Some objects in a project have a three-part identifier based on the identifier of the containing

query subject. Each name must be unique in the containing query subject. These are the

objects that have a three-part identifier:

• query items

• query item folders

For example, you have a GoSales namespace that contains a query subject named Product,

and a query item named Product Code. The Product Code query item has the following name,

where the square brackets and periods are the syntax Framework Manager uses for object

identifiers.

[Go Sales].[Product].[Product Code]

Use Separate Namespaces:

Namespaces are containers like folders. You create a namespace in Framework Manager if you

want to have two objects that have the same name in a project. Objects in a Framework

Manager project must be uniquely identifiable. If you have two objects of the same type that

have the same name, they must reside in two separate namespaces.

For example, you have a database that contains financial data. In the database, there is a set of

tables that represent Forecast and Actual information. Both the Forecast and Actual information

have tables named Accounts Payable and Accounts Receivable. To import these tables into

Framework Manager and use the same table names in the project, you must create two

namespaces. You can name one namespace Forecast, and the other namespace Actual.

Steps

1. Click the project or root namespace and from the Actions menu, click Create, and click

Namespace.

2. Right-click the namespace, click Rename, and give the namespace a descriptive name.

Importing Metadata:

You can import metadata into a new project, or an existing project. Importing metadata is

an operation that can be performed many times to extend the project.

Framework Manager can use the metadata and data from external data sources to build a

project.

To import metadata, you must indicate which sources you want and where they are located. If

you want to add a project to a repository, you must set up the repository connection.

You can import metadata from

• relational databases, such as Oracle, DB2, and Microsoft SQL Server

• SAP BW data sources

• existing Cognos ReportNet models

• Architect models and Impromptu catalogs

• DecisionStream models

• third-party metadata sources

• XML as a data source

10

Import from a Relational Database:

When you import from a relational database, you can import all the metadata or select

particular

object types such as tables, columns, views, synonyms, stored procedures, and functions.

Steps

1. Click the namespace, folder, or segment you want to import into and, from the Actions

menu, click Import Metadata.

2. Follow the instructions in the Import wizard.

• Select a data source connection.

If the data source connection you want is not listed, you must first create it.

• Select the check boxes for the objects you want to import.

• Specify how the import should handle duplicate object names. Choose either to import

and create a unique name, or not to import. If you choose to create a unique name, the

imported object appears with a number. For example, you see QuerySubject and

QuerySubject1 in your project.

• Specify whether joins are generated based on indexes or keys. If necessary, change the

criteria to use to generate relationships.

Import statistics showing a list of objects that could not be imported and a count of objects

that were imported.

3. Click Finish.

After importing, you should check the usage and aggregation property values. Fact

tables can contain numeric columns that should not be aggregated, such as exchange rates.

Import from a Cognos ReportNet Model:

You can import metadata from an existing Cognos ReportNet model.

Steps

1. Click the namespace, folder, or segment you want to import into and from the Actions

menu, click Import Metadata.

2. Click Cognos ReportNet Model and click Next.

3. Locate the Cognos ReportNet model (.cpf file) you want and click Open and click Next.

4. Follow the instructions in the Import wizard:

• Select the check boxes for the objects you want to import.

• Specify how the import wizard should handle duplicate object names. Choose either to

import and create a unique name, or not to import.

If you choose to create a unique name, the imported object appears with a number. For

example, you see QuerySubject and QuerySubject1 in your project.

5. Click Next and click Finish.

Import from an Architect Model or an Impromptu Catalog:

To import metadata from an Architect model or an Impromptu catalog, you must first convert

them to XML files.

11

Steps

1. Ensure that you exported the Architect model or Impromptu catalog.

2. Click the namespace, folder, or segment you want to import into and from the Actions

menu, click Import Metadata.

3. Click either Cognos Architect (.xml) or Cognos Impromptu (.xml) and click Next.

4. Locate the Architect or Impromptu XML file that contains the metadata to import and click

Open.

A message in the XML Preview window confirms success.

5. Click Import.

A list of created objects appears.

6. Click Finish.

Import from Decision Stream:

You can use Framework Manager to import metadata from an XML file created by

Decision Stream. The following tables show the mapping of metadata from Decision Stream to

Framework

Manager.

Facts

A DecisionStream fact maps into Framework Manager as a model query subject.

Connections

A DecisionStream connection maps into Framework Manager as a data source. The following

data source attributes are included in the model

Dimension Builds

A DecisionStream dimension build maps into Framework Manager as a top-level Framework

Manager namespace. The following dimension attributes are included in the model.

Hierarchies

A DecisionStream hierarchy referenced by a dimension is mapped into a hierarchy whose

parent is the query subject representing the mapping of the DecisionStream dimension.

The following data source attributes are included in the model.

Conformed Stars

In Framework Manager, conformed stars are mapped into a Framework Manager namespace

that contains shortcuts referencing the dimensions.

The following conformed star attributes are included in the model

Model Properties

The export file contains the following model properties.

Steps

1. Click the namespace, folder, or segment you want to import into and from the Actions

menu, click Import Metadata.

2. Click Cognos DecisionStream (.xml) and click Next.

3. Locate the Cognos DecisionStream XML file that contains the metadata to import and click

Open.

12

A message in the XML Preview window confirms that you chose a valid XML file.

4. Click Import.

A list of created objects appears.

5. Click Finish.

Import from a Third-Party Metadata Source:

You can use Framework Manager to import metadata from a third-party source. Metadata is

imported using a metadata bridge.

You can import both third-party metadata and relational metadata into the same model. We

recommend that you start with a new Framework Manager model and import the third-party

metadata before the relational metadata. This avoids conflicts if you import same named

objects.

Import options are divided into two groups:

• Third-party options

These are used to extract the metadata from the third-party source.

• Framework Manager options

These are used to create the imported objects in Framework Manager.

Tip: Import options are shown in the import wizard. For optimal mapping, always use the

default

values.

Steps

1. Click the namespace, folder, or segment you want to import into, and from the Actions

menu, click Import Metadata.

2. Click the import source and click Next.

3. Click the metadata type to import.

4. In the file name box, locate the XML file that contains the metadata to import and click

Open.

A message in the XML Preview window confirms that you chose a valid XML file.

5. Click Next.

6. In the Third-Party Specific Import Options dialog box, click the options you want.

In the Option Description pane, you see a description of the options available. The options

are based on the selected third-party data source.

Tip: To accept the default options, select the Use Defaults check box.

7. Click Next.

8. In the Framework Manager Specific Import Options dialog box, click the options you

want.

In the Option Description pane, you see a description of the options available.

9. Click Next.

10. Follow the instructions in the Import wizard:

• Choose a data source from the list. If the data source you want is not connected, you

must create it.

• Select the check boxes for the objects you want to import.

• Specify how the import wizard should handle duplicate object names. Choose either to

import and create a unique name, or not to import.

If you choose to create a unique name, the imported object appears with a number. For

example, you see QuerySubject and QuerySubject1 in your project.

13

• Specify whether joins are generated based on indexes or keys. If necessary, change the

criteria to use to generate relationships.

11. Click Import.

A list of created objects appears.

12. Click Finish.

Import Using XML as a Data Source:

You can import XML as a tabular data source in Framework Manager. An XML data file can be

Imported locally or from a remote site through a valid URL. You can import the XML data file

into Framework Manager and use it to model metadata and create a package.

The XML file is validated and parsed at run time, when the query is processed by either Cognos

Report Studio or Query Studio. If you add the VALIDATE=ON option to the connection string,

Framework Manager partially validates the XML file in the <columnList> tag that describes the

metadata.

You must use the xmldata.xsd schema to validate the XML file. The schema is located in the

\crn\bin folder. You do not need to specify the location of the schema in the XML file itself.

To use XML as a data source, ensure that

• you do not use Native SQL to access data in an XML file

• you do not access Binary Large Objects (BLOB)

• you use only sqlColumns() and sqlTables() metadata calls

Other calls return an unsupported function error.

• the XML file is well-formed and valid

Before you import XML as a data source, there must be a connection to the data source.

If the XML data source is on another machine, you must use an account that has proper

permissions to access the data source.

To use XML as a data source, you should understand XML, schemas, and other XML-related

technology.

Steps

Before you can import metadata, there must be a connection to the data source.

1. Click the namespace, folder, or segment you want to import into, and from the Actions

menu, click Import Metadata.

2. Click the XML data source you want to import, and click Next.

Create a Data Source Connection:

When you create a data source, you also create a data source connection so that ReportNet

has the connection and authentication information required to connect to the database.

You can include authentication information for the database in the data source connection by

creating a signon. This means that users need not enter database authentication information

each time the connection is used. The authentication information is encrypted and stored on

the ReportNet server.

The signon produced when you create a data source is available to the

Everyone group. You can later modify who can use this signon or create more signons.

You can create data sources in the portal or in Framework Manager. Because they are stored on

the server, data sources appear in both Framework Manager and the portal, regardless of

14

where they were created. Existing data sources can only be managed in the portal.

The ReportNet administrator can set up the data sources before any models are created in

Framework Manager so that all connections are available in the Framework Manager Import

wizard.

Data sources are stored in the Cognos namespace and must have unique names. For example,

you cannot use the same name for a data source and a group.

Each data source can contain one or more physical connections to databases. The data source

connection specifies the parameters needed to connect to the database, such as the location of

the database and the timeout duration.

Note: The schema name in the connection string for an Oracle database is case-sensitive. If the

schema name is typed incorrectly, you will not be able to run queries.

Before creating data sources, you must have write permissions to the folder where you want to

save the data source and to the Cognos namespace. You must also have execute permissions

for the Administration secured function.

Multiple Data Source Connections:

If you have access to more than one data source connection in a data source, you are prompted

to select a data source connection when you open a Framework Manager project. You can use

multiple data source connections in a single data source to facilitate the migration from one

environment to another and maintain the integrity of a project.

For example, you can use multiple data source connections to work with metadata from a test

data source. You create a new project, using the test data source connection for the GoSales

data source. You create and modify the objects you want in the project, and you test that the

project is modeled the way you want. When you close the session, and reopen the Framework

Manager project, you can select the production data source connection. When you publish the

package to the Cognos ReportNet server, report authors choose which data source connection

they want to use in their report.

Multiple connections to the same data source must be defined in Cognos Connection.

Steps

1. If you are not already using the Import wizard, click the namespace, folder, or segment you

want to import into, and from the Actions menu, click Import Metadata.

2. In the Select Import Source window, click New.

3. In the name and description page, type a unique name for the data source and, if you want,

a description and screen tip. Select the folder where you want to save it, and click Next.

40 Cognos ReportNet(TM) Framework Manager

Chapter 2: Designing a Project

4. In the connection page, click the type of database to which you want to connect, select an

isolation level and click Next.

The connection string page for the selected database appears.

5. Specify any parameters that make up the database connection string, specify the timeout,

15

and select whether to create a signon.

Tip: To test whether parameters are correct, click Test. If prompted, type a user ID and

password or select a signon, and then OK.

6. Click Finish.

The data source appears as an entry in the Directory tool in the portal, and can be selected in

the Import wizard in Framework Manager.

Tip: To test a data source connection, right-click the data source in the Data Sources folder and

click Test Data Source.

If you created a signon, you can now modify the properties of the signon or add more signons.

Connecting to ODBC Data Sources:

When you create data source connections to ODBC data sources, select the data source type

from the Type drop-down menu in the New Connection Wizard. If ReportNet is running under

Windows and you are connecting to an ODBC data source type that does not appear in the

menu, select ODBC. If ReportNet is running under UNIX, select Other type and add the

associated database codes for the database vendor.

Modeling with Multilingual Data Sources:

To enable a project to work with multiple languages, you must set up data sources to support

multiple languages.

Multilingual Relational Data Sources:

For relational data sources, you can support multiple languages by using one or more of the

following:

• Language-specific database tables

The data source should contain the same tables for each supported language. For example,

if the Product table supports English, French, and German, the data source has tables

named Product_en, Product_fr, and Product_de.

• Language-specific columns

A database table should contain the same columns for each supported language. For

example, if the Product table supports English, French, and German, the table has columns

for ProductName_en, ProductName_fr, and ProductName_de.

• Language-specific rows

A database table should contain an additional column to identify the language of each row

of data, such as a column named LANG.

These solutions can make the multilingual data sources large and difficult to manage.

You can model a single relational query subject to represent all possible data source languages

by using parameter maps and session parameters in the query subject definition.

Managing Projects:

You should organize projects in a meaningful way so that you can easily find them. Within

Framework Manager, you can copy , move , rename , and delete projects . You can also perform

these tasks from Windows Explorer or the file system. You can manage your projects in

16

Framework Manager using repository control, segmenting, and linking. These project

management features help maintain version control, organize a project according to business

rules and organizational needs, set run-time processing options, and give other users access to

sections of the project. You can also identify the vendor-specific functions that you want to use

for each data source you import into your project. If your project is segmented, the segments

are treated as standalone projects.

Copy a Project:

When you copy a project, you create a replica of that project in another location. All files in the

project folder, including sub-folders, are copied to the new location. When you make changes to

the project in one folder, these changes are not reflected in copies of the project in other

folders.

Copying a segmented model copies all segments as well as the main project.

You cannot create a copy of a project in the same folder as the original.

Note: We recommend that you do not use the Save As command from the File menu to create a

copy of a project. If you use the Save As command, ensure that you specify a target directory

that does not contain a Framework Manager project, otherwise, you will overwrite the project

in

the target location.

Before you can copy a project, the project must be closed in Framework Manager. If a segment

is open when you copy a main project, the last saved version of the segment is copied.

Steps

1. On the File menu, click Manage Projects and click Copy.

2. In the From text box, click the browse button and select the .cpf file for the project you want

to copy.

Note: The project folder name is shown in the text box.

3. In the To text box, type the new location or click the browse button and select the new

project location.

Note: If the target location is a new folder that does not exist, the copy command creates it.

4. Click OK.

Move a Project:

You may decide to move a project if your folder becomes so full that it is difficult to locate

particular projects. When you move a project, you are actually copying it to a new folder and

deleting it from the current folder. All files in the project folder, including sub-folders, are

moved

to the new location.

Moving a segmented model moves all segments as well as the main project.

Before you can move a project, the project must be closed in Framework Manager.

Steps

1. On the File menu, click Manage Projects and click Move.

2. In the From text box, click the browse button and select the .cpf file for the project you want

to move.

Note: The project folder name is shown in the text box.

3. In the To text box, type the new location or click the browse button and select the new

project location.

17

Note: If the target location is a new folder that does not exist, the copy command creates it.

4. Click OK.

A confirmation box appears to confirm that you want to remove the folder and move its

contents

to the Recycle Bin.

5. Click Yes.

Rename a Project:

When you rename a project, you provide a new name for both the .cpf file and the folder it

resides in. Secondary project files and log files keep their original name.

If a project appears in the recent projects list on the Framework Manager Welcome page and

you proceed to rename it, you cannot open the project by clicking on the link. You must open

the

project using the Open command on the File menu.

Before you can rename a project, the project must be closed in Framework Manager.

Steps

1. On the File menu, click Manage Projects and click Rename.

2. In the From text box, click the browse button and select the .cpf file for the project you want

to rename.

Note: The project folder name is shown in the text box.

3. In the To text box, type the new name for the project and click OK.

If the original project folder and .cpf file have the same name, both the folder and .cpf file are

renamed. If the names are different, only the project folder is renamed.

Delete a Project:

You may decide to delete a project because it no longer satisfies your requirements. When you

delete a project, the project folder and all its contents, including any user files, are deleted from

the file system and sent to the recycle bin.

If your project is segmented and you delete the main project, the segments are deleted as well.

Before you delete a project, ensure that the project and all its segments are closed. Framework

Manager does not support a file locking mechanism so it is possible under certain

circumstances to delete an open project. If you delete an open project, the open project can no

longer be saved.

If you accidentally delete a project, you can restore it from the recycle bin.

Deleted projects still appear in the most recently used list on the File menu.

Steps

1. On the File menu, click Manage Projects and click Delete.

2. In the Project Folder text box, click the browse button and select the .cpf file for the project

you want to delete.

Note: The project folder name is shown in the text box.

3. Click OK.

A confirmation box appears to confirm that you want to remove the folder and move its

contents

to the Recycle Bin.

4. Click Yes.

18

The project folder and all its contents are deleted.

Repository Control:

Use repository control to help manage your projects in Framework Manager. You control

versions of a project to ensure that each version of a file is recoverable. Repository control also

ensures that users in a large organization have access to the most recent changes or versions

of a project or segment.

Segmenting Models:

The main project has access to the entire model, including the segments. This means that you

can make changes to the segments when working in the main project. If the segment is open

when the main project is updated, the potential exists for updates to be lost. The changes that

were last saved to the model overwrite previously saved changes. We recommend that access

to the main project be limited and that you avoid updating segments from the main project.

When you work with a main project and segments in the main project, there are other things to

consider. If you create a main project that contains segments, and the main project is connected

to a repository, any new segments created are automatically added to the repository. If you

have

a project or segment checked in to a repository and you make a change, you are notified that

you must check out the project or segment before you can make the change. If you make

changes in a segment, you are notified in the main project that changes were made in the main

project.

Create a Segment:

You can create a segment so that you can

• organize a project according to business rules and organizational requirements

• share and reuse project information

Before you create segments, you may want to consider dividing your project into business units.

For example, you have a project named GoSales. You can create two folders, one named

Products and the other named Orders. You can divide the GoSales project at the Products folder

and at the Orders folder.

You can also link the segments to other projects that contain the same information to

maintain consistency and reuse information.

You create segments either at the folder or namespace level. You can create a new project in a

new folder, complete with its own associated project files.

When a new segment is created, any existing parameter maps from the main project are copied

to the new segment. After the segment is created, parameter maps are unique to each segment

and cannot be shared between segments. For example, if you are working in the main project,

you can use a parameter map in a query subject belonging to a segment. However, if you open

the segment, the parameter map is not available.

Steps

1. Click the folder or namespace you want to divide, and from the Actions menu, click Create

Segment.

2. In the Create Segment dialog box, change any settings you want.

19

3. Click OK.

The Project Viewer is refreshed and the icons representing the segmented folder or the

segmented namespace are shown.

Create a Link:

A link is a shortcut to an existing project , segment, folder, or namespace. You create links to

help organize work across large projects, to maintain consistency, and to reuse information.

For example, the project named Inventory contains the folder named Products. You can create a

link from the GoSales Products to Inventory Products. If any changes or additions are made to

the Inventory Products folder, they are reflected in the GoSales Products folder.

Links are defined in the project file (.cpf) that owns them. If the main project has a link to a

segment, the link is part of the .cpf file for the main project.

If you link to a namespace and a new data source is added to that namespace, you must add a

link to that new data source.

The projects you link must have the same languages defined and the same design language.

You must create the project, folder, or namespace before you can link to it.

Steps

1. In the Project Viewer, click the object you want to link.

Tip: You can create links only to folders, namespaces, and projects or segments.

2. From the Actions menu, click Link Segment.

3. Locate and click the .cpf file of the segment, folder, or namespace.

4. If you want to add the link to a repository, click the Repository button.

5. Click Open.

6. Choose the project or segment to link to:

• To link to another project, click Add Project, locate the .cpf file and click Open. Select

the project and click Add.

• To link to a segment, click the segment and click Add.

7. Click OK.

A new folder appears in the Project Viewer. Change the location for the segmented project files

Using Functions to Create Expressions;

The Expression Editor provides a list of functions that you can select to create an expression.

This list includes:

• common SQL99 functions

• vendor-specific functions

• functions imported from a data source

• free-form functions

When you import metadata into Framework Manager, you import the functions from the

metadata source. These functions are shown in a folder whose name matches the namespace.

This folder is located at the bottom of the list of folders in Expression Editor.

Choose Function Sets:

A collection of database functions that are vendor-specific is called a function set. When you

create a project that contains relational metadata, the Expression Editor lists the function sets

for all available vendors. However, you can restrict the function sets so that it lists only the

20

vendors that you want to use in your project. You customize the function set by identifying the

specific vendor for each data source defined in the project.

Steps

1. Click Project, Project Function List.

2. Select the Set function list based on the data source type check box.

Tip: To disable this filter, select the Include all function sets check box.

3. In the Function set page, click the appropriate data source row.

4. Select the function set you want to use with this data source.

5. Repeat steps 2 and 3 until finished.

6. Click OK.

Improve Performance by Setting Query Processing Type:

For relational metadata, you can improve performance by selecting the right type of query

processing.

There are two types of query processing:

• limited local

The database server does as much of the SQL processing and execution as possible.

However, some reports or report sections use local SQL processing.

• database only

The database server does all the SQL processing and execution. An error appears if any

reports or report sections require local SQL processing.

Recording Transactions in Log Files:

In Framework Manager, you can capture, view, and play back actions performed on the project.

Each sequence of actions that you perform in Framework Manager is considered a transaction.

Each transaction is recorded in the project or segment action log file.

The action log file is an XML file that is designated by the project or segment name, date, and

time. The log file is stored in the project or segment logs folder. You can save individual

transactions to a separate log file.

Note: If the script has dependencies on the existing project, you must ensure that the project is

aligned with the script transactions to ensure the desired results.

View Transaction History:

You can view the transaction history in a project or segment action log file and then save it as a

script.

Steps

1. From the Project menu, click View Transaction History.

Tip: To make the dialog box larger, double-click the caption. Double-click again to restore its

original size.

2. Click the transaction numbers you want.

3. Click Save as Script, but do not save it in the logs folder.

Tip: To view the details of a transaction, click the plus sign (+) next to a transaction number.

4. Click Close.

21

Play Back Transactions From a Log File:

You can choose to play back a specific transaction or a combination of transactions in a project

or segment action log file.

For example, you make changes to a project in a test environment. When it is time to move the

project to production, you can play back every action, or series of actions, that you performed in

the project in the test environment. This creates an identical project in the production

environment.

Steps

1. From the Project menu, click Run Script.

2. Select the script you want, and click Open.

The Script File box shows the name and location of the script file.

Tip: To locate another log file, click the folder button.

3. To view the details of a transaction, click the transaction.

A list of the transaction details appears in the Status/Transaction Details box.

60 Cognos ReportNet(TM) Framework Manager

Chapter 2: Designing a Project

4. Set the run options that you want.

• To set the starting point for running the script, select the script and then click the Set the

starting point button.

You can do this at any time to skip an instruction or run instructions that have already

been executed.

• To set a stop point for the script, select the script and then click the Set the stop point

button.

You can stop the script to make a manual fix and then continue on from that transaction.

Tip: To remove the stopping point, click the Remove the stop point button.

• To ensure that the project stops on any transaction error, select the Stop on Error

check box.

5. Using the toolbar buttons, choose the run action you want.

The project window is updated as the script is run.

6. Fix any errors encountered by the script either by retargeting objects or modifying the

temporary project as required.

7. When the script has completed, click Accept to accept the changes.

Tip: To return the project to its previous state, click Revert.

22

Chapter 3: Preparing Metadata for Use in Reports

After importing metadata, you must ensure that it is set up to meet your users’ reporting

requirements. Then you can enhance the metadata to provide additional information that your

users require. Enhancements you make in Framework Manager do not affect the original data

source.

You can check the project at any time to ensure that the references between the objects

it contains are valid.

Import View

To ensure that the metadata is set up correctly in the import view, do the following:

❑ Ensure that the relationships reflect the reporting requirements.

❑ Optimize and customize the data retrieved by query subjects. This includes handling

support for multilingual metadata.

❑ Control how data is used and formatted by checking query item properties.

Business View

To enhance the metadata in the business view, do the following:

❑ Add business rules, such as calculation, filter, and prompts, that define the information

users can retrieve.

❑ Create separate views for each user group by creating a series of folders and shortcuts that

reflect the business concepts familiar to your users.

❑ Specify dimensional information.

❑ Create star schema groups.

Verifying Relationships:

Without a clear idea of how your organization uses data, you cannot determine the best way to

connect data in the model. Before importing data, ensure that you understand your users’

reporting requirements and ensure that the necessary relationships exist in the data source.

After importing metadata, confirm that the relationships reflect the reporting requirements.

A relationship describes a connection between two query subjects. Without relationships,

query subjects are isolated pieces of information.

When importing metadata, Framework Manager creates relationships between query subjects

based on the primary and foreign keys in the data source. You can create or remove

relationships between query subjects so that the model better represents the logical structure

of your business. Creating or modifying a relationship in Framework Manager does not change

the structure of the data source.

Cognos ReportNet does not write to the data source.

After you import metadata, verify that the relationships you require exist in the project. To

improve performance, keep or create only the necessary relationships.

If you are importing from a data warehouse, ensure that you verify all relationships and

cardinality. To increase processing speed, many primary and unique key constraints are not

specified in a data warehouse. Without these constraints, Framework Manager cannot generate

23

the necessary relationships between fact tables and dimension tables.

Framework Manager stores relationships in the nearest common parent of the query subjects

that participate in the relationship. The parent can be either a folder or a namespace. If you

move one of the participating query subjects outside the common parent, the relationship

moves to the next namespace that is common to both ends of the relationship. If you move a

relationship to a different folder or namespace, the participating query subjects are also moved

to the same folder or namespace.

Custom Relationship Expressions:

In Framework Manager, you can create complex expressions by taking two or more

relationships and joining them using an operator, such as <, >, or =. Use complex expressions to

create custom relationships that help minimize the complexity of the data in your diagram.

You can specify the operator by selecting one from the list or by manually changing the

expression in the Expression Editor.

Cardinality:

Cardinality indicates the nature of the relationship between two query subjects, query items, or

other model objects. Cardinality is used to ensure that, when the SQL is generated, aggregates

are calculated, derived tables are flattened out, and correct results are returned.

Relationships work in both directions. You often must examine both directions to fully

understand the relationship.

The different types of relationships are

• one-to-one

• one-to-many or many-to-one

• many-to-many

One-to-one relationships occur when one instance of data in a query subject relates to exactly

one instance of another. For example, each student has one student number.

One-to-many relationships occur when one instance of data in a query subject relates to many

instances of another. For example, each teacher has many students.

Many-to-many relationships occur when many instances of data in a query subject relate to

many instances of another. For example, many students have many teachers.

Notation:

Both Crowsfeet notation and Merise notation are available to use. By default, Framework

Manager uses Merise notation. Crowsfeet notation is a pictorial representation of the

relationship. Merise notation marks each end of the relationship with the minimum and

maximum cardinality of that end. Possible end labels are:

• 0..1 (zero or one match)

• 1..1 (only one match required)

• 0..n (zero or more matches)

• 1..n (one or more matches required)

The first part of the notation specifies the type of join for this relationship:

• an inner join (1)

24

An inner join shows all matching rows from both query subjects.

• an outer join (0).

An outer join shows everything from both query subjects, starting with the items that match.

An outer join can be qualified as full, left, or right. Left and right outer joins take everything

from one side of the relationship and only what matches from the other side.

Data in one query subject may have no match in the other query subject.

However, if the relationship is specified with a minimum cardinality of one, an inner join is

always used and these records are ignored. Conversely, if the relationship in the model is

marked with a minimum cardinality of zero, an outer join is always used, although the results

would be the same with aninner join. You must ensure that the data and cardinalities match.

The second part of the notation defines the relationship of query items between the query

subjects (1=1, n=many).

When you interpret cardinality, you must consider the notation that appears at both ends of the

relationship. Analyzing Patterns in Relationships. Databases and the queries that run against

them are often designed to have more than one way to join tables. Framework Manager

interprets the structure of your data source and creates relationships.

Many-to-Many Relationships:

Many-to-many relationships occur when many instances of a query subject relate to many

instances of another. A query written against a many-to-many relationship results in a

cross-product query being performed on the data source. Unless specifically enabled, most data

sources do not permit the execution of such a query.

When you import metadata, Framework Manager identifies many-to-many joins and generates

the model objects that are necessary to resolve potential reporting errors.

Relationships That Can Result in Double-Counting:

Double-counting occurs when data at multiple levels of granularity exist in the same table. It

results in repeated data being aggregated to the internal cardinality of the data in the table.

Double-counting can occur in

• parallel relationships

• hierarchical relationships

• aggregate tables

Parallel Relationships:

A parallel relationship is when several one-to-many relationships fan out from a single query

subject with no direct connection between the query subjects in the fan. This could result in

double-counting. Such patterns must be examined to discover if a critical relationship is missing.

Parallel relationships are often legitimate. Not all of them must be resolved, but all of them

must be examined.

For example, Branch and Employee are related to the Division query subject. A division of the

company contains several branch offices. As well, each division has one or more employees

25

who work for each branch office. Are Branch and Employee themselves related to one another?

It may be necessary to connect the two to track data that is relevant to both of them but is not

relevant to the Division query subject.

When the query engine identifies query subjects at the end of a one-to-many relationship in the

context of the query, the query engine writes a stitched query. A stitched query is a query that

locally combines the results of two or more subqueries by using a locally processed outer join.

If the level of granularity is different between two or more sides of the query, you must specify

dimensional information for the common query subject to prevent double-counting.

Hierarchical Relationships:

Hierarchical relationships occur when a series of query subjects are connected by one-to-many

relationships.

If you use A and C in a query, the query engine automatically uses B when executing the query.

Grouping and aggregation is correctly applied to ensure that double-counting does not occur.

Ambiguous Relationships:

An ambiguous relationship is one that has multiple relationships between one or more query

subjects, leaving multiple options for how to write a query. If appropriate, the database

administrator can choose to remove extra relationships in the data source. You can also resolve

ambiguous relationships in Framework Manager.

Ambiguous relationships can be seen in

• loop joins

• optional relationships

• recursive relationships

• multiple relationships

Loop Joins:

Loop joins have two or more ways to relate data between query subjects. Unless one path is

highly preferable to the other, present your users with both paths.

To resolve loop joins, determine which query path you want used. Create shortcuts to all query

subjects that participate in the relationship and keep the shortcuts in a separate folder or

namespace. Resolve the ambiguity in the separate folder or namespace. Do not publish the

original query subjects. Instead, keep them in a folder or namespace with the original

relationships intact.

The previous loop join is resolved by creating shortcuts to the query subjects and relationships,

and keeping the shortcuts in two namespaces.

The dotted lines in the diagram indicate shortcuts.

Optional Relationships :

An optional relationship is characterized by a (0..1) or (0..n) notation that allows for a potential

break in the linkage of data from one table to another.

To resolve an optional relationship, add an alternate mandatory relationship, if possible.

26

The previous optional relationship is resolved by creating a shortcut to C and linking the shortcut

to B. The original relationship between B and C is then deleted.

The dotted lines in the diagram indicate shortcuts.

Recursive Relationships:

A recursive relationship, or self-join, occurs when you must get two or more different types of

information from the same query subject.

For example, a single employee can manage one or many employees, or can manage no other

employees. A self-join is used to show this relationship.

When you import metadata, Framework Manager shows recursive relationships in the diagram,

but does not execute them as queries. Although you can view the metadata that defines the

relationship, you cannot edit a recursive relationship in Framework Manager.

To create a functioning recursive relationship, create a shortcut to the query subject and define

a relationship between the query subject and its shortcut.

The dotted lines in the diagram indicate shortcuts.

Another option is to create a model query subject that references the data source query subject

and then define a relationship between the model query subject and the data source query

subject.

Multiple Relationships:

Multiple relationships occur when one query subject has multiple valid relationships between

itself and another query subject. This is often seen in dimensionally modeled data, particularly

for dimensions such as Date and Customer.

To resolve multiple relationships, create a star schema grouping, which results in a new

namespace with shortcuts to the original query subjects. Determine how many valid

relationship shortcuts now exist between the fact table shortcut and the dimension shortcut.

Copy and paste the shortcut to the dimension in the new namespace until you have as many

copies as you have relationships. Name each shortcut for the role it plays. After you clarify

which shortcut will be used for each dimension, keep only the relationship shortcut for each

role-playing shortcut.

For example, the Orders query subject has multiple relationships to the Customer query subject

on keys such as sold_to, ship_to, and bill_to.

It is not possible to write a query between these query subjects because three relationships

from Orders to the same field in Customer will result in no rows being returned.

To resolve this problem, we create three shortcuts named Sold_To_Customer,

Ship_To_Customer, and Bill_To_Customer.

The dotted lines in the diagram indicate shortcuts.Modify a Relationship

Steps

1. Click a relationship and, from the Actions menu, click Edit Definition.

2. Modify the relationship.

3. Click OK.

4. If your metadata is from an OLAP data source, click Close.

27

Create a Relationship:

You create a relationship to join logically related query subjects that report authors want to

combine in a single report. This is useful for relationships between query subjects that were not

selected during metadata import, were not joined in the data source, or are from multiple

sources.

You can directly create a relationship between the query items.

You can also use Framework Manager to automatically generate relationships between

query subjects based on selected criteria.

Note: Relationships for SAP BW metadata are read-only and cannot be modified.

Steps

1. Ctrl+click two or more query subjects or query items.

Tip: In the diagram view, you can also select a query item in a shortcut to create a

relationship.

2. From the Actions menu, click Create, Relationship.

If this relationship is a valid target for a relationship shortcut, Framework Manager asks if

you want to create a shortcut to that relationship.

On the Relationship Expression tab, select the query items, cardinalities, and operator you

want. The query items must have the same data type. Create an additional join

Click the New Link button, and define the new relationship.

Note: The drop-down box is not available if the expression is invalid or too complex or contains

query items from more than two query subjects. Create a complex expression On the

Relationship Expression tab, click the ellipses (...) button, define the expression, and click OK.

On the Relationship SQL tab, identify the number of rows you want returned and click the

Test button.

3. Click OK.

The Relationship Definition dialog box appears. You can use this dialog box to modify the

relationship.

Create a Relationship Shortcut:

A relationship shortcut references an existing relationship. You can use relationship shortcuts to

reuse the definition of an existing relationship. Any changes to the source relationship are

automatically reflected in the shortcut. You can also use relationship shortcuts to resolve

ambiguous relationships between query subjects.

Framework Manager asks whether you want to create a relationship shortcut whenever you

create a relationship and both of the following conditions apply:

• At least one of the ends for the new relationship is a shortcut.

• A relationship exists between the original query subjects.

Steps

1. Ctrl+click the query subjects that you want to participate in the relationship shortcut.

2. From the Actions menu, click Create, Relationship.

Framework Manager asks if you want to create a shortcut to that relationship.

3. Click Yes.

A list appears of all relationships in which one end is a model object and the other end is

either another model object or a shortcut to another model object.

28

4. To retrieve all relationships in which both ends can be either a model object or a shortcut to

a model object, click Find All.

5. Click the relationship that you want to be the target of the relationship shortcut.

6. Click OK.

Detect and Generate Relationships:

You can use Framework Manager to detect and generate relationships between two or more

existing query subjects in your model. This is useful when you import metadata in stages, or

when you want to change the criteria that apply to existing relationships, such as whether they

include outer joins.

When importing star schema metadata, avoid generating relationships based on matching

column or query item names. Data warehouses often apply naming standards to columns, such

as surr_key as the default column name for surrogate keys in dimensions. In this case,

generating relationships that are based on matching column names would generate

inappropriate relationships between all dimension tables.

Steps

1. Ctrl+click two or more query subjects.

2. From the Actions menu, click Detect Relationships.

3. Select the rules you want to apply to each pair of tables.

4. Indicate whether you want Framework Manager to detect relationships

• between the selected query subjects

• between each selected query subject and every query subject in the project that is not

selected

• between the selected query subjects and every other query subject in the project

5. Identify whether you want Framework Manager to create outer joins or inner joins based on

outer joins that exist in the data source.

6. Click OK.

Working with Query Subject:

A query subject is the basic building block in Framework Manager.

Each query subject that is based on relational metadata is defined by an SQL statement that

describes how to retrieve data from the data source.

• relational data source query subjects

• model query subjects

• stored procedure query subjects

Relational Data Source Query Subjects:

Relational data source query subjects directly reference data in a single data source.

Framework Manager automatically creates a relational data source query subject for each table

and view that you import into your model.

Use primary and foreign keys:

Creates joins that are based on primary key and foreign key relationships. The query item names

do not have to match.

29

Use matching query item names that represent uniquely indexed columns:

Creates joins between query items whose names and data types match, if one or both of the

underlying columns are uniquely indexed.

Use matching query item names:

Creates joins between query items whose names and data types match. This option is

recommended if you want to generate as many relationships as possible.

Framework Manager generates query subjects that represent tabular data from the data source.

For example, a query subject that references an entire table contains query items that represent

each column in the table. If the SQL selects only specific columns, only those columns are

represented as query items.

To use multiple data sources for a query subject, use a model query subject that accesses the

data source query subjects or other model query subjects.

Model Query Subjects:

Model query subjects are not generated directly from a data source but are based on query

items in other query subjects. The main purpose of model query subjects is to create query

items that are oriented to reporting needs and that reuse the underlying data source queries.

Because model query subjects are based on the metadata in your model, they let you

• reuse complex SQL statements that exist in the model

• reference objects from different data sources in the same query subject

Stored Procedure Query Subjects:

Stored procedure query subjects are generated when you import a procedure from a relational

data source. When a query subject is based on a stored procedure that returns a result set, the

stored procedure must return a single uniform result set. If a stored procedure returns multiple

result sets, Framework Manager supports only the first result set. Each result set must return

the same form, such as the same number of columns.

To work around this restriction, you can create multiple stored procedures, each with a unique

name, and create a separate query subject for each result set. After you import or create a

stored procedure query subject, you must run it to validate the underlying stored procedure and

specify the projection list. When a stored procedure is updated in the data source, running the

stored procedure in Framework Manager updates the query subject using the newly generated

query items. If you are creating a stored procedure query subject, the name of the stored

procedure itself must not contain any spaces.

Create a Query Subject:

For relational metadata, you can create the following types of query subjects:

• data source query subjects directly reference data in a single data source.

• Model query subjects are based on metadata that exists in your model.

• Stored procedure query subjects are generated from the stored procedures in a relational

30

data source.

Steps

1. Select the namespace folder and, from the Actions menu, click Create, Query Subject.

2. In the Name box, type a name for the new query subject.

3. Select the type of query subject you want to create, and click OK.

4. Do one of the following:

• If the Query Subject Definition dialog box appears, specify which objects will be in the

model query subject.

• If the New Query Subject wizard appears, complete the steps in the wizard. You can

then modify the data source query subject or the stored procedure query subject.

To ensure that the data source is uniquely identified for a data source query subject, do

not exit the wizard before the Finish button appears.

• To control the model area that is visible in the diagram, click the overview button in the

bottom right corner and drag the pointer over the diagram.

Create a Model Query Subject Based on Existing Objects:

In addition to creating query subjects from scratch , you can select existing model objects

and merge them into a new model query subject. This means you can reuse existing metadata

to quickly create query subjects.

The objects you can merge include

• data source query subjects and their shortcuts

• model query subjects and their shortcuts

• query items, filters, and calculations in model and data source query subjects

• relationships and relationship shortcuts between model and data source query subjects

You can merge any number of the same type of objects into a new query in a single operation.

The merge always creates a new model query subject.

Steps

1. Ctrl+click the objects you want to merge into a single query subject.

2. From the Actions menu, click Merge in New Query Subject.

If the query subjects are joined to other query subjects, you are prompted to recreate

relationships with the new query subject.

3. To recreate relationships, click Yes.

Modify a Data Source Query Subject:

When query subjects are based on relational metadata, you can modify them to retrieve

different data. You can test the query subject to view the results that it returns.

When you embed a filter or calculation, the data source query subject must

have a relationship to any query subject referenced by the expression. This relationship is

necessary even if the expression references a model query subject based on the same table as

the data source query subject in which you are embedding the expression.

To create this relationship, do one of the following:

• ensure that there is a join path between the new query subject and the one that contains the

filter or calculation

• base the embedded filter or calculation on a query item that is based on the data source

31

query subject you want

• convert the filter or calculation to a stand-alone filter or calculation, so that it is not part of

the query subject

• create a stand-alone filter or calculation that references the embedded object

Steps

1. Click the query subject you want to modify.

2. From the Actions menu, click Edit Definition.

3. Modify the query subject.

4. Test the query subject to view the results that it returns.

5. Click OK.

Modify a Stored Procedure Query Subject:

After you import or create a stored procedure query subject, you can modify it. To avoid

inconsistencies, the modified query subject should return the same result set structure as the

original.

Note: Multidimensional metadata does not support stored procedure query subjects.

Steps

1. Select the query subject you want to modify.

2. From the Actions menu, click Edit Definition.

3. Modify the query subject.

Tip: Click an existing macro to edit it in the Macro Editor dialog box.

4. Test the query subject to view the results that it returns.

5. Click OK.

Framework Manager runs the stored procedure and, if the query subject returns a result set,

validates the query subject.

You can update the stored procedure query subject if the data source changes .

Update Query Subjects:

If the relational data source changes, you can update the data source query subjects and the

stored procedure query subjects. You do not need to complete a full project synchronization.

Notes:

• The query subject is updated based on the definition in the data source.

• Updating query subjects is available for relational metadata only.

Steps

1. Select one or more query subjects.

2. From the Actions menu, click Update Query Subject.

Modify a Property for Multiple Query Subjects

You can modify a property for multiple objects at the same time. These objects can be either

query subjects or query items.

Steps

1. Select the objects that you want to modify.

Only the properties that are common to all objects are shown in the Properties pane.

2. If you want to sort the property values, double-click the property heading.

An arrow appears to indicate the direction in which values are sorted. You can toggle

between ascending and descending order.

3. If you want to filter property values, click the arrow to the right of the property heading. You

32

can select a value or click Custom to define the criteria for the rows you want to show.

The objects are selected in the Project Viewer.

4. Make any changes to the values of the property.

Test a Query Subject:

You can see the results that a query subject returns by testing it.

Steps to Test a Query Subject

1. Select one or more query subjects.

2. From the Actions menu, click Test Query Subject.

The Test Result box shows the query results. Any result sets that contain Binary Large

Objects are shown as [blob].

3. If you want more information about the results of model and data source queries, click the

Results Information tab.

4. Click Close.

Tip: You can now fix problems. Double-click the query subject to open the Edit Definition

dialog box.

SQL Types:

SQL is the industry-standard language for creating, updating, and querying relational database

management systems. When you edit the definition of a data source query subject that is

based on relational data, you can use

• Cognos SQL

• native SQL

• pass-through SQL

You can add comments to the SQL by using /* before the comment and */ at the end.

Here is an example:

select country /* this is a multiline comment

another line

another line

*/

When choosing the type of SQL in which to generate a data source query subject, you must

weigh the following factors and decide which are most important.

Cognos SQL:

Improves query subject performance; for example, by removing unused elements at query time.

SQL works on any supported database. You can not enter non-standard SQL.

By default, Framework Manager uses Cognos SQL to create and edit query subjects. Cognos

SQL adheres to SQL99 rules and works with all relational and tabular data sources.

In general, using Cognos SQL is preferable because you can create query subjects that

• can contain metadata from multiple data sources

• have fewer database restrictions

• interact more effectively with Cognos applications

33

Here is an example of Cognos SQL using derived tables:

SELECT * FROM

(SELECT SNO C1, AVG(QTY) C2, COUNT(*) C3 FROM SUPPLY GROUP BY SNO) T1,

(SELECT MAX(QTY) C1 FROM SUPPLY) T2

Here is how Cognos SQL turns the above example into a With clause:

WITH T1 AS (SELECT SNO C1, AVG(QTY) C2, COUNT(*) C3 FROM SUPPLY GROUP BY SNO),

T2 AS (SELECT MAX(QTY) C1 FROM SUPPLY)

SELECT *FROM T1, T2

Native SQL:

Native SQL is the SQL the data source uses, such as Oracle SQL. You can not use native SQL

in a query subject that references more than one data source in the project. Performance is

optimized across all related query subjects. You can use SQL that is specific to your database.

You cannot use SQL that the data source does not support for subqueries. The query subject

may not work on a different database type. The SQL may not work on a different data source.

Pass-Through SQL:

Pass-through SQL lets you use native SQL without any of the restrictions the data source

imposes on subqueries. This is because pass-through SQL query subjects are not processed

as subqueries. Instead, the SQL for each query subject is sent directly to the data source where

the query results are generated.

Because each query subject is sent to the data source as a separate statement, rather than

being optimized by Framework Manager, performance is slower.

Therefore, in choosing between native SQL and pass-through SQL you must decide which is

more important: performance or using SQL that is not permitted in a subquery.

SQL specified in Framework Manager and processed by the database, whether native or pass-

through, must be completely self-contained. It must not reference anything outside of that SQL,

such as database prompts, variables, or native formatting that would normally be supplied by

the calling application.

Generally, you should use pass-through SQL only if you need to create a query subject that

contains constructs that are specific to a data source and that cannot be used inside a derived

table, such as a With or Order By clause.

Modifying the Properties of Query Items:

Because reports are composed of different query items from one or more query subjects, query

item properties control many aspects of the final report. When you create a model query

subject, the query items inherit the properties of the data source query items on which they are

based.

For relational metadata, you can modify the properties of query items by

• setting Usage and Aggregation properties to reflect the intended use of the query

item

• formatting query items to control how data appears in a report

• identifying a column as a prompt, and controlling how the prompt information is presented to

the report author

34

Query item property Description:

Name The name of the query item.

Description A description of the query item.

Last Changed The date that the query item was last changed.

Screen Tip A description that can appear in the published package for the report authors.

Column Name The name that appears in the data source.

Is Hidden Whether to hide or show the query item in the published package.

Usage The intended use for the data represented by the query item.

Currency Which currency is used.This property cannot be changed in the Property pane.

Data Type The data type that was set in the data source.Because this property is set in the data

source, it is read-only in Framework Manager.

Precision The number of decimal places.Because this property is set in the data

source, it is read-only in Framework Manager.

Scale How many digits are represented in the scale. For example, you can show numbers in

thousands so that 100,000 means 100,000,000. Because this property is set in the data

source, it is read-only in Framework Manager.

Size The size of the query item. Because this property is set in the data source, it is read-only in

Framework Manager.

Is Nullable Whether the query item can contain a null value. Because this property is set in the

data source, it is read-only in Framework Manager.

Define a Prompt Control:

Prompts help users quickly find the information they need in a report. Prompts are generally

defined in the reporting tool. However, you can change the definition of the query subject in the

model so that a prompt appears automatically when report authors create filters. This is useful

for query items, such as ProductTypeCode, whose values are not shown in a report but are

useful for filtering data.

In Framework Manager, prompt behavior is defined through a compound query item property

named Prompt Info. The Prompt Info property contains the following properties that affect how

prompt controls are generated by Cognos ReportNet.

Prompt Types:

The Prompt Type property sets the type of prompt control that the reporting application

generates when running a report, such as an edit box or a pull-down list. Use this property to

have the prompt show one query item but use a different one. For example, the prompt can

show Employee Name but use Employee Number.

The default value for this property is Server Determined.

Parent Item in a Cascade:

The Cascade on Item Reference property indicates that the generated prompt is part of a series

of generated cascading prompts. The query item that you reference in this property is the

parent

item in the cascade. The system prompts the user for the cascade item before prompting them

35

for the current query item.

Value Prompt Control:

Server Determined. The type of prompt controls is based on information in the server, such as

the data type of the query item.

Modifying How Query Items Are Aggregated:

Usage property values are used to drive transformations in Framework Manager, such as the

star schemas. They are also used to set the aggregation rules of query items and calculations.

These rules are applied when the report author creates a report that aggregates this query item

or calculation, unless they override it in the report definition.

When importing metadata, Framework Manager assigns usage and aggregation property values

to each query item you import. When you create a model query subject, each query item

inherits the usage and aggregation properties of the query item on which it is based.

You can change existing Usage and Regular Aggregate property values by either:

• automatically regenerating the values of selected objects

You then know that these values are appropriate for the type of data they represent.

• modifying the values in the Properties pane,

You can select additional aggregation values that are not available through importing, such

as average and maximum. You must understand what the data represents to know which

aggregation rule is required. For example, if you aggregate a part number, the only

aggregate values that apply are Count, Count Distinct, Count Non-Zero, Maximum, and

Minimum.

Usage Property:

The Usage property identifies the intended use for the data represented by each query item.

During importing, the Usage property is set according to the type of data that the query items

represent in the data source. You can change the property.

For relational query items, the value of the Usage property depends on the type of database

object the query item is based on.

Regular Aggregate Property:

The Regular Aggregate property identifies the type of aggregation that is associated with the

query item or calculation when you publish it. The report author can either use this default

setting to perform calculations on groups of data, or use the reporting application to apply a

different type of aggregation.

For example, if the Regular Aggregate property value of the Quantity query item is sum, and the

report author groups it by Product Name, the Quantity column in the report shows the total

quantity of each product.

Semi-Aggregate Property:

For relational metadata, the Semi-Aggregate property value is set to unsupported and is

read-only.

36

Rules Governing the Aggregate Properties

Here are some rules that govern how the Regular Aggregate and Semi-Aggregate properties

are set by Framework Manager:

• if the type of a query item is numeric or a time interval and the item is a fact, the Regular

Aggregate and Semi-Aggregate properties are both set to sum.

• if the type of a query item is numeric or a time interval and the item is a calculation, the

Regular Aggregate and Semi-Aggregate properties are both set to automatic.

• if the type of a query item is numeric or a time interval and the item is not a fact, the Regular

Aggregate property is set to count and the Semi-Aggregate property is set to unsupported.

• if the type of a query item is not numeric or a time interval, the Regular Aggregate and the

Semi-Aggregate property are both set to unsupported.

Regenerate Usage and Aggregation Property Values:

Using Framework Manager to regenerate usage and aggregation property values ensures that

they reflect the transformation rules. It is useful to regenerate these values before you publish a

package to ensure that these properties reflect modifications to your model.

When generating aggregation values, Framework Manager assigns a value that is based on the

usage property value, and the type of model object it is.

Steps

1. In the Project Viewer pane, select one or more query subjects.

2. In the Properties pane, change the following values:

• the Usage property to unknown

• the Regular Aggregate property to unsupported

3. From the Actions menu, click Determine Usage.

4. From the Actions menu, click Determine Aggregation Rules.

Modify a Property for Multiple Query Items:

You can modify a property for multiple objects at the same time. These objects can be either

query subjects or query items.

Steps

1. Select the objects that you want to modify.

Only the properties that are common to all objects are shown in the Properties pane.

2. If you want to sort the property values, double-click the property heading.

An arrow appears to indicate the direction in which values are sorted. You can toggle

between ascending and descending order.

3. If you want to filter property values, click the arrow to the right of the property heading. You

can select a value or click Custom to define the criteria for the rows you want to show.

The objects are selected in the Project Viewer.

4. Make any changes to the values of the property.

37

Create a Calculation:

You can create calculations to provide report authors with calculated values that they regularly

use. Calculations can use query items, parameters, expressions, and expression components,

such as functions.

Punctuation characters, such as the question mark (?), must be in 7-bit ASCII character code. If

you type a punctuation character from a multi-byte enabled keyboard, ensure that you type the

7-bit ASCII representation of the character.

For example, type Alt+063 for the question mark.

At query time, Framework Manager returns a null value for any calculation that contains a

divisor whose value is zero. Framework Manager cannot detect zero-division errors in functions

such as average and mod, because the division operator is not explicit.

Framework Manager supports two types of calculations: stand-alone and embedded.

Stand-alone Calculations:

Use a stand-alone calculation when you want to reuse the expression. You can apply a

stand-alone calculation to one or more query subjects to provide calculated data to a report, or

include it in a package to make it available to your report authors. By moving a stand-alone

calculation or a shortcut to it into a folder, you can better organize your model objects.

Avoid using characters that are used for expression operators in the name of the calculation.

Syntax errors may occur when the expression is evaluated.

For example, a calculation named Margin * 10 causes errors when used in an expression such

as [Margin * 10]< 20.

Embedded Calculations:

You may want to use a calculation with only one query subject. You can create an embedded

calculation when modifying a relational data source query subject , multidimensional data

source query subject, or model query subject.

Avoid using characters that are used for expression operators in the name of the calculation.

Syntax errors may occur when the expression is evaluated.

For example, a calculation named Margin * 10 causes errors when used in an expression such

as [Margin * 10]< 20.

If you start with an embedded calculation, you can later convert it into a stand-alone expression

that you can apply to other query subjects.

tip: Right-click the calculation expression in the query subject editor and click Convert to

Stand-Alone Calculation.

Steps

1. Do one of the following:

• If you want to create a stand-alone calculation, click the model folder and, from the

Actions menu, click Create, Calculation.

• If you want to create an embedded calculation, double-click the query subject that will

contain the calculation, and then click the calculation button.

38

2. Define the expression.

On the Model tab, click a query item, filter, or calculation and click the arrow.

Add functions On the Functions tab, choose a component and click the arrow.

On the Parameters tab, click a parameter and click the arrow.

3. Click OK.

4. Modify the Data Type property to identify the type of data the calculation returns.

The reporting application uses this information to format the data that the calculation

returns.

Test a Calculation:

You can see the results that a calculation returns by testing it.

Steps

1. Select one or more calculations.

2. From the Actions menu, click Test Calculation.

The Test Result field shows the query results.

3. If you want more information about the results of model and data source queries, click the

Results Information tab.

4. Click Close.

Tip: You can now fix problems. Double-click the query subject to open the Edit Definition

dialog box.

Create a Filter:

A filter is an expression that specifies the conditions that rows or instances must meet to be

retrieved for the query subject, calculation, or report to which the filter is applied. A filter

returns a boolean value, equivalent to the predicate in the Where clause in an SQL statement,

so that you can limit the rows returned by a query subject.

For example, you can use the in_range function to create a filter that retrieves data for products

introduced in a specific time frame. The syntax for this example looks like this:

[gosales_goretailers].[Products].[Introduction date] in_range {Feb 14, 1999 : July 14,

2004}

You can restrict the data represented by query subjects in a project by creating a security filter.

The security filter controls the data that is shown to the report authors when they set up their

reports.

You can also apply governors to restrict the data that the queries in a package retrieve.

Framework Manager supports two types of filters: stand-alone and embedded.

Stand-alone Filters:

Use a stand-alone filter when you want to reuse the expression. You can add a stand-alone filter

to one or more query subjects to limit the data that the query retrieves when the filtered query

subject is used in a report, or you can include it in a package to make it available to your report

authors. By moving a stand-alone filter or a shortcut to it into a folder, you can better organize

your model objects. Limit test results Click the options button and change the

39

number of rows that are returned on the Results tab.

Embedded Filters:

You may want to use a filter with only one query subject. You can create an embedded filter

when modifying a relational data source query subject , multidimensional data source

query subject, or model query subject.

If you start with an embedded filter, you can later convert it into a stand-alone expression that

you can apply to other query subjects.

Tip: Right-click the filter expression in the query subject editor and click Convert to

Stand-alone Filter.

Steps

1. Do one of the following:

• If you want to create a stand-alone filter, click the model folder and, from the Actions

menu, click Create, Filter.

• If you want to create an embedded filter, double-click the query subject that will contain

the filter, and then click the filter button.

2. Define the expression.

3. Click OK.

Example - Create and Apply a Filter:

You want to create a query that shows the currency name for a specific country. To do this, you

create a filter that returns data for a specific country code, and apply the filter to a model query

subject that retrieves the currency name for each country.

Note: The following example uses a relational data source.

Steps

1. Open the gosales_goretailers sample model.

It is located in

installation_location/crn/webcontent/samples/Models/gosales_goretailers/gosales_goretail

ers.cpf.

2. Create a filter to limit the retrieval of data to only those country codes in the conversion rate

table whose value is "2":

• Click the Filters folder and, from the Actions menu, click Create, Filter, and name the

new filter ConversionRateCountryCode.

• Click the Model tab.

• In the Available Components box, open the Database view folder and then open the

GoSales folder.

• Select Conversion rate.Country code, click the arrow to add it to the Expression

definition box, and type = '2' at the end of the expression.

• Click OK.

3. Create a model query subject named ISO Code, and apply the

ConversionRateCountryCode filter:

• In the Available model objects box, open the Database view folder.

• Drag Country.Country and Country.ISO 3-letter code into the Query Items and

Calculations box.

• Open the Filters folder, drag ConversionRateCountryCode to the Filters box.

40

4. Click Preview.

The generated SQL contains the filter, even though it does not affect the result set.

5. Change the usage of the ConversionRateCountryCode filter to Optional.

The default usage is Always.

6. Click Preview.

Because the query item in the filter and the query items in the select list are not from the

same, the filter is not visible in the generated SQL.

Using Prompt Values to Filter Data:

You can substitute a prompt for a value so that users can filter data by typing a value when the

report opens.

In general, it is better to use the reporting application to define type-in prompts to make use of

the additional prompt features. However, report authors cannot modify some variables. For

these variables, you can use Framework Manager to define type-in prompts.

You can use prompts in:

• parameter maps

• session parameters

• stored procedure arguments

• expressions, including filters, calculations, and relationships

The syntax for using a prompt as a value is

?<PromptName>?

Create a Parameter Map:

Use parameters to create conditional query subjects that allow for substitutions when the

report

is run. Parameter maps are objects that store key-value pairs. Parameter maps are similar to

data source look-up tables. Each parameter map has two columns, one for the key and one for

the value that the key represents. Keys and values can be manually entered, imported from a

file, or based on existing query items in the model.

All parameter map keys must be unique so that Framework Manager can consistently retrieve

the correct value. Do not place quotation marks around a parameter value. You can use

quotation marks in the expression in which you use the parameter.

The value of a parameter can be another parameter. However, you must enclose the entire

value in number signs (#). You cannot have a nesting of parameters as values that exceeds five

levels.

Steps to Manually Create a Parameter Map

1. Click the Parameter Maps folder and, from the Actions menu, click Create, Parameter

Map.

2. In the Name box, type a name for the new parameter map.

3. Click Manually enter the parameter keys, and/or import them from a file and click Next.

4. Choose how to enter values:

• To manually enter values, click New Key, type a key, and press Tab to enter a value for

that key.

• To import keys and values, click Import File and identify the location of the appropriate

41

.csv file. You can import from a .txt file only if the values are separated by tabs rather

than commas.

Note: If you are going to use a parameter in a data source query subject, the value must

use English-specific punctuation. This means that you must use a period (.) to represent a

decimal and a comma (,) to separate lists of values.

5. Modify existing parameters as required.

6. Click Finish.

Steps to Create a Parameter Map Based on Existing Query Items:

1. Click the Parameter Maps folder and, from the Actions menu, click Create, Parameter

Map.

2. In the Name box, type a name for the new parameter map.

3. Click Base the parameter map on existing Query Items and click Next.

4. In the Select Query Items for Parameter Map box, select the query item to use as the key.,

and then select the query item to use as the value.

Both query items must be from the same query subject.

5. Click Next.

6. Click Finish.

Example - Using Parameter Maps:

An international company stores its Product and Customer information in both French and

English tables. The company stores its Order information only in an English table. By creating

the following parameter maps, employees can use parameters to ensure that the query

retrieves

data that matches the information the user requires.

LanguageSensitiveStatusTables ProductStatusTables OrderStatusTables

The following query subject retrieves the code and description data that matches the defined

parameter values:

SELECT code, description

FROM #$LanguageSensitiveStatusTables {’p’}#

If the value of the runLocale parameter is fr, this expression is equivalent to

SELECT code, description

FROM FR_ProductStatus

Create a Session Parameter:

A session parameter is a variable that Framework Manager associates with a session. For

example, user ID and preferred language are both session parameters. Because session

parameters are key and value pairs, you can think of each session parameter as an entry in a

parameter map named Session Parameters. You use a session parameter in the same way that

you use a parameter map entry, although the syntax for session parameters is slightly different.

In Framework Manager, you can define additional parameters using session parameters. For

example, the parameter userName could be defined using the account.defaultName session

parameter. The syntax would look like the following:

userName = #$account.defaultName#

42

Key Value

P #$ProductStatusTables {$runLocale}#

O #$OrderStatusTables {$runLocale}#

Key Value

en EN_ProductStatus

fr FR_ProductStatus

<default> EN_ProductStatus

Key Value

en English_OrderStatus

fr Order_Status_FR

<default> English_OrderStatus

There are two types of session parameters: environment and model.

Environment Session Parameters

Environment session parameters are predefined and stored in Content Manager. They are

limited to

• account.defaultName

• account.personalInfo.userName

This is only applicable if a user did not log on anonymously.

• runLocale

Model Session Parameters

If you need a session parameter that does not exist, you can create a model session parameter.

Model session parameters are stored in a parameter map named _env. They are set in the

project and can be published with a package.

Model session parameters must have their values set within the scope of objects in the

Framework Manger model. The scope can include the use of existing environment session

parameters, as well as static values.

Using Parameters with Relational Data Source Query Subjects

Model objects do not reflect changes to the data source objects on which they are based.

Therefore, when you add a parameter to a data source query subject, consider whether you

want to create a model object that references the parameter. If so, you must assign an alias to

the parameterized object in the data source query subject. This ensures that any model query

subjects, filters, or calculations that reference the object return the correct results when the

parameter value changes.

For example, the following SQL defines a data source query subject that contains a session

parameter named runLocale. The runLocale parameter value specifies which column the query

retrieves. The alias behaves like a shortcut so that when a model object references

CountryNameAlias, Framework Manager retrieves the value to which the alias is assigned.

Select

#$ColumnMap{$runLocale}# as CountryNameAlias

From

[GoSales].Country

Using Query Macros to Create Prompts

43

Macros are fragments of code that you can insert anywhere in the Select statement that defines

a query subject. You can include references to session parameters, parameter maps, and

parameter map entries. Parameter values are set when the query is run.

For example, you can use the language session parameter to show only the data that matches

the language setting for the current user.

Macros can be used in these different ways:

• They can be inserted in the SQL.

An example is Select * from Country where Country.Name = #$myMap{$runLocale}#

• They can supply an argument to a stored procedure query subject.

If a value is not hardcoded for the argument, the stored procedure query subject can be

used to return different data.

• They can be inserted in expressions, such as calculations and filters.

An example is a filter [gosales].[Sales staff].[Staff name] = #$UserLookUpMap{$UserId}#

• They can be used to dynamically complete the properties of a data source query subject.

This enables different users to supply different connection information and thus access

different data sources. The properties that can contain macros are: Content Manager

Datasource, Catalog, Cube, and Schema.

An example using the Content Manager Datasource Property is #$DataSourceMap{$UserId}#

• They can be used as a parameter wizard.

Parameters can reference other parameters. An example is Map1, Key = en-us, Value =

#$myMap{$UserId}#

• They can be used in the Session Parameter dialog box.

An example is MySessionParameter, value = #$myMap{$UserGroup}#

Do not insert macros between existing quotation marks or square brackets because Framework

Manager does not execute anything within these elements.

You can replace the following query subject elements with a parameter.

Syntax

Use the following syntax to reference session parameter and parameter values.

When you reference a parameter, you must

• use a number sign (#) at the beginning and end of each set of one or more parameters.

Everything between the number signs is treated as a macro expression, which is processed

at runtime.

• precede each parameter map entry with a dollar sign ($)

• use a name that starts with an alpha character (a..z, A..Z)

You can add the following elements to further define the macro expression.

Object Syntax Example

Session key $session_key #$my_account#

Parameter map key $map{<key>} #$map_one{’abc’}#

Parameter map

entry whose key is

defined by a

session parameter

$map{$session_k

ey}

#$map_one{$my_account}#

Steps

44

1. In the Query Subject Definition dialog box, click the insert macro button to start the Macro

Editor.

2. In the Available components box, click the parameter maps, session parameters, or

functions you want to use, and drag them to the Macro definition box.

3. Insert single quote or double quote functions.

Tip: Click the arrow next to these buttons for a menu of choices for placing the quotation

marks.

4. If you want to edit a parameter map or session parameter, in the Macro definition box, click

it.

The Parameter Map or Session Parameters dialog box appears. You can set override

values for session parameters, add new items, or change values.

5. Check the macro in the Information box.

If a macro is incorrect, an error message appears.

Tip: To clear a macro, click the clear current expression button.

6. Click OK.

45

Chapter 4: Making Metadata Available to

Report Authors

A package is a subset of the query subjects and other objects defined in the project. You then

publish the package to the Cognos ReportNet server so that the report authors can use the

metadata. You can create several packages from the same project, each package used to meet

different reporting requirements.

Before you publish a package, you must create or open a project in Framework Manager and

import metadata into the project. You might also want to refine the project for reporting by

creating and modifying the objects in the project.

To publish a project:

❑ Check the project to ensure that the contents are consistent and do not contain any errors

❑ Set governors for reports

❑ Create custom packages to suit different reporting requirements

❑ Add security to the package

❑ Analyze the effect of any changes you made to a package on the reports that were created

using the published packages.

❑ Specify languages in the package

❑ Publish the package to a location that report authors can access

Check a Project:

At any point in the modeling process, you can check the validity of your project. Before you

publish a package, you can also ensure that there are no invalid objects that can break

queries in the published package.

When you check a project, Framework Manager lists invalid objects and their status. Verifying a

project detects various problems, which you can direct Framework Manager to repair.

Invalid Relationships:

Framework Manager identifies query subjects whose relationships are invalid, so that you can

delete them. Invalid relationships include

• many-to-many relationships

• orphaned query subjects (query subjects with no relationships)

• multiple relationships (or relationship shortcuts) between query subjects (or query subject

shortcuts)

If you do not define relationships for a model query subject because it uses the relationships

defined for the data source query subject, an error is listed when you check the project. You can

define relationships for the model query subject, or you can leave the model query subject as an

orphan.

Invalid References

Invalid references exist when an object references another object to which it does not have

46

access or which no longer exists in the project.

Invalid Object Definition

Framework Manager warns you when your changes to an object will mean it cannot be

executed. If you proceed, these are marked as invalid. When you verify a project, Framework

Manager identifies any query subjects, shortcuts, filters, calculations, and relationships that

were previously marked as invalid so that you can repair them.

Invalid Aggregation Rules

Framework Manager identifies any aggregate settings that are invalid for the data type of the

query items to which they are applied. For example, if Product_Name has a character data type,

its aggregate property cannot be set to either sum, count, or average. To repair the error,

Framework Manager resets the aggregate property to unsupported.

Steps

1. From the Project menu, click Verify Model.

Tip: To check a few objects, right-click the objects and click Verify Selected Objects.

2. Click each error you want to correct.

Tip: The complete error messages are shown in the Message Details box.

3. Click Repair.

A dialog box shows the number of objects repaired, and identifies the number of broken

references that need to be retargeted.

4. To fix broken references, click Yes.

When you repair a filter that contains an invalid reference, you must check its expression to

ensure that the query items it now references do not contain invalid references. Any

expression components that are invalid are underlined in red

5. Identify which references you want to appear:

• To show every reference that exists for the selected object, click Show all references.

Use this option to view valid relationships in which the object participates for more

context about how that object is used.

• To show only the references that are broken for this object, click Show only broken

references.

Use this option to reduce the number of references that are displayed to only those that

need to be repaired.

6. Click the Retarget/Delete Value column, and choose how to fix the broken reference:

• To locate the object you want to reference, click Browse.

• To delete the object that contains the broken reference, click Delete Object.

• To clear an existing value, click None.

• To use a reference that you have assigned to another object during this repair session,

click the name of the reference.

7. Click the Apply to column and choose where you want to apply the reference:

• To apply the change to this object only, click This Reference Only.

• To apply the change to every object that references the same object, click Entire

Project.

8. Click OK.

After fixing invalid relationships, if the relationships still appear as broken in the Verify dialog

box, close and re-open the model.

47

Set Governors:

Governors control SQL generation. Use them to reduce system resource requirements and

improve performance.

You can restrict the number of tables retrieved by a query as well as the number of rows. You

can set time limits for query execution as well as restrict character length on BLOBS. A setting of

zero (0) means no limit is set. You can set limits to the data retrieved in a query subject test or

the report design mode by setting governors.

When you set governors, all packages that are subsequently published use the new settings.

SQL is generated automatically when you

• run a report in Cognos Report Studio or Query Studio

• test a query item or relationship in Framework Manager

• create a new model query subject based on other objects

You can set run-time activities to deny outer joins and cross-product joins, which could produce

large, resource-intensive queries. As a result, outer joins are not automatically generated when,

for example, you test a query item in Framework Manager.

The Outer join governor does not apply to SQL that is generated by other means. If you set this

governor to deny, it does not apply to the permanent SQL found in a data source query subject,

whether the SQL was generated on import, manually entered, or based on existing

object.

You set governors before you create packages to ensure the metadata in the package contains

the specified limits.

Limit Description:

Report table limits: Controls the number of tables that a user can retrieve in a query or report.

Tables are counted as they are retrieved. An error message appears when the preset number of

tables is reached.

Data retrieval limits: Controls the number of rows that a user can retrieve in a query or report.

Rows are counted as they are retrieved. An error message appears when the preset number of

rows is reached. If you externalize a query subject, this setting is ignored when you publish the

model.

Query execution time limits Limits the time that a query can take. An error message appears

when the preset number of seconds is reached.

Large text items limits Controls the size of BLOBS (binary large objects) that a user can retrieve

in a query or report. The BLOB size is

truncated to the size you specify. An error message appears when the preset number of

characters is reached.

48

Steps

1. From the Project menu, click Edit Governors.

2. Specify the limits that you want to use when retrieving data.

3. Click OK.

Create or Modify a Package

You create a package to make metadata available to report authors. A package is a subset of

a project. It must contain all the information that a specific user or group of users needs to

create

reports.

A package contains query subjects whose SQL defines the query items and relationships that

the package retrieves. When you create a package, you select the objects that a user will want

to report on. When you create or modify a package, you can also apply security to the package.

For example, if your data source contains information from different areas of a business, you

might decide to create different package for Human Resources, and Finance. Ensure that your

package meets a broad but related reporting need. Each report can contain information from a

single package only.

Outer joins Controls whether outer joins can be used in your query or report. An outer join

retrieves all rows in one table, even if there is no matching row in another table. This type of

join can produce very large queries and reports.

By default, governors are set to deny outer joins. If you keep the setting as deny, you are

notified only if you create a relationship in the Object Diagram View that includes outer joins.

You are not notified if you create a relationship in a data source query subject that includes

outer joins.

If you set the governor to allow, dimension to fact relationships are changed from inner joins to

outer joins.

Cross-product joins Controls whether cross-product joins can be used in your query or report. A

cross-product join retrieves data from tables without joins. This type of join can take a long time

to retrieve and can produce meaningless results.

Use With clause when generating SQL Enables you to use the With clause with Cognos SQL if the

data source supports the With clause.

If a model query subject references other query subjects, ensure that you include the

referenced

query subjects in the package. For example, if there is a model query subject that references

another query subject in an embedded filter, you must include the referenced query subject in

the package. Otherwise, an error occurs when you run the report.

After a package is published to the Cognos ReportNet server, it is available for use by report

authors.

49

Reusing Packages:

You reuse packages by creating nested packages. When you create nested packages, you

create a master package that is based on other existing packages. Using nested packages

saves you time, and they are easier to maintain. Another advantage of using a nested package

is that you publish only the master package.

For example, you create three separate packages named Canada, Mexico, and the United

States. Each package contains the project objects and security appropriate for that package.

You can create one master North America package and include the packages Canada, Mexico,

and the United States. When you need to publish the package for report authors, you publish

only the North America package.

Select, Hide, Unselect

When you create a package, you can choose whether objects in a project can be selected

based on the requirements of reports authors.

For example, package A has the query subject Country hidden and package B has the query

subject Country selected. If package C includes package A and package B, then Country is

included. However, if package C includes package A and package B, and you override the query

subject Country in package C so that it is unselected, then Country is unselected.

Steps to Create a Package

1. Click the Packages folder, and from the Actions menu, click Create, Package.

2. In the Provide Name page, type the name for the package and, if you want, a description

and screen tip. Click Next.

Option Description

Select The object can be used in reports and can be selected by report authors.

Hide The data within the object can be used in reports, but the object cannot be selected by

report authors. For example, you include a model query subject in a package. Because model

query subjects are dependenton data source query subjects, you must add the data source

query subject to your package. If you do not want report authors to see the data source query

subject, you hide it.

Unselect The object is not published and cannot be used for reports and cannot be selected by

report authors.

3. Specify whether you are including objects from existing packages or from the project and

then specify which objects you want to include.

Tip: If you created other packages, we suggest that you add package references by clicking

Using existing packages.

4. Choose whether to use the default access permissions for the package:

50

• To accept the default access permissions, click Finish.

• To set the access permissions, click Next.

5. Specify who has access to the package, and click Next.

You can add users, groups, or roles.

6. Move the language to be included in the package to the Selected Languages box, and click

Next.

7. Move the sets of data source functions you want available in the package to the Selected

function sets box.

8. Click Finish and choose whether to publish the package.

Steps to Modify a Package

1. Right-click the package you want to modify, and then click Edit Definition.

2. Click the objects you want to add to or remove from the package.

Tip: To toggle through the options for an object, click the object icon, or select an option

from the list.

3. Click OK.

4. If you want to add or remove package references to the package you are modifying, click

Edit.

5. Click OK.

Controlling Access to Metadata and Data

In Framework Manager, security is a way of restricting access to metadata and data across

Cognos ReportNet products. There are different types of security in Framework Manager:

• data security

You create a security filter and apply it to a specific query subject. The filter controls the data

that is shown to report authors when they set up their reports.

• object security

You secure an object directly by allowing users access to the object, denying users access

to the object, or keeping it hidden for all users.

• package security

You apply security to a package and identify who has access to that package.

Each type of security uses users, groups, and roles to define access.

There are business reasons for restricting access to data. For example, you may have data that

contains confidential data, and only specific users are allowed to see it. You may have a variety

of data, and your users only need to retrieve data from specific tables or columns. Or, you may

have a table that contains many records, and your users only need to retrieve a subset of

records from that table.

Before you add security in Framework Manager, ensure that security was set up correctly in

Cognos ReportNet.

Add a User, Group, or Role

51

Users and groups are created for authentication and authorization purposes. You can use users

and groups created in third-party authentication providers, as well as create your own, in

Cognos ReportNet. In Framework Manager, you add data security and metadata security using

these users, groups, and Cognos groups.

Users

A user entry is created and maintained in a third-party authentication provider to uniquely

identify a human or a computer account. You cannot create users in Cognos ReportNet.

Information about users, such as first and last names, passwords, IDs, locales, and e-mail

addresses, is stored in the providers.

Users can become members of groups defined in third-party authentication providers and

groups defined in Cognos ReportNet. A user can belong to one or more groups. If users are

members of more than one group, their access permissions are merged.

Groups and Roles

Examples of groups are Employees, Developers, or Sales Personnel. Members of groups can

be users and other groups. Group membership is part of the users’ basic identity. When users

log on, they cannot select a group they want to use for a session. They always log on with all the

permissions associated with the groups to which they belong.

A role is a special group. It represents a collection of users that have similar responsibilities and

similar privileges in the organization. Members of roles can be users, groups, and other roles.

Role membership is not part of the users’ basic identity.

In Cognos ReportNet, you can use groups created by your organization in third-party

authentication providers, or create new groups in the Cognos namespace.

You create Cognos groups when

• you cannot create groups in your authentication provider

• groups are required that span multiple namespaces

• portable groups are required that can be deployed

• you want to address specific needs of Cognos ReportNet administration

• you want to avoid cluttering your organization security systems with information used only in

Cognos ReportNet

Steps to Create a New Group or Role

1. Right-click the package you want, and click Edit Package Access.

2. Click New.

3. Follow the instructions in the New Group wizard.

4. Click Finish, and then click OK.

Steps to Remove a Group or Role

1. Right-click the package you want, and click Edit Package Access.

2. Click the user, group, or role you want to remove, and click Remove.

3. Click OK.

52

When you remove Cognos groups or roles, you do not delete them from the third-party

authentication provider or Cognos ReportNet.

Steps to Add a Group or Role

1. Right-click the package you want to modify, and click Edit Package Access.

2. Click Add.

Tip: To view all the users in a group, select the Show users in the list check box, and click

the group you want.

4. Click OK twice.

Add Data Security

You can restrict the data represented by query subjects in a project by creating a security filter.

The security filter controls the data that is shown to the report authors when they set up their

reports.

For example, your Sales team consists of a Sales Director, and four Sales Managers. You create

a security filter that includes the groups directors and sales managers, and apply the filter to the

salary query subject. When the package is available for report authors, and a report is

generated for the Sales Managers and the Sales Director, only the Sales Director can see the

salary information for the sales managers.

You can base the security filter on existing security filters. If you choose this option, the security

filter inherits the filter, and all the filter properties.

When you create a security filter, you can also use existing project filters, or create new filters

using the Expression Editor.

Steps

1. Right-click the query subject you want, and click Specify Data Security.

2. To add new users, groups, or roles, click the Add Groups button.

3. If you want to base the group on an existing group, click a group in the Based On column.

Tip: If you do not see the group you want in the list, you must add the group to the security

filter.

4. If you want to add a filter to a group, in the Filter column, click either Create/Edit

Embedded Filter or Insert from Model.

5. Click OK.

Add or Remove Object Security

Metadata security can be applied directly to objects in a project. When you add object-based

security, you apply a specific user, group, or role directly to the object. You choose to

make the object visible to selected users or groups.

If you do not set object-based security, all objects in your project are visible to everyone who

has

access to the package. When you apply security to one object, all objects in the model will also

have security applied to them. They will not be visible to anyone. Once you set security for one

object, you need to set it for all objects.

You can make every object in a main project namespace visible to selected users, groups, or

roles, except relationships. For example, in your project, you may have a Salary query subject.

53

You can make the Salary query subject visible to the Managers group, and keep it hidden from

everyone.

Steps to Add Object-Based Security

1. Right-click the object you want to secure, and click Specify Object Security.

Tip: You can select more than one object and then right-click them.

2. Select the users, groups, or roles you want to change. Or, click the Add button to add new

users, groups, or roles.

3. Specify security rights for each user, group, or role by doing one of the following:

• To deny access to a user, group, or role, select the Deny check box next to the name for

the user, group, or role. Deny takes precedence over Allow.

• To grant access to a user, group, or role, select the Allow check box.

Tip: To allow everyone to see all objects unless specifically denied access, select the Allow

check box for the Everyone role.

4. Click OK.

A list of new and updated object-based packages appears.

Steps to Remove Object-Based Security

1. Right-click the secured object and click Specify Security Rights.

2. Remove security rights by clearing both the Allow and Deny check boxes for all users,

groups, or roles.

3. Click OK.

A list of packages that will be affected by these changes appears.

Add Package Security

You can define metadata security when you create and publish packages in Framework

Manager. You can also define metadata security after creating the package.

A package is a secured subset of a project. A package can be published and can be included in

other packages.

You can add entries that were created in both third-party authentication providers and Cognos

ReportNet as members of a Cognos group.

You can organize your security by specifying which users, groups, and roles have access to

certain parts of the published model.

To add metadata security:

❑ Decide whether the objects can be selected, unselected, or hidden in the package.

❑ Add users, groups, and roles to the package.

❑ Decide which users will have administrative access to a package.

When you apply administrative access to a package, you give access to the user or users who

are responsible for

• republishing a package in Framework Manager to the Cognos ReportNet server.

• ensuring that no reports are impacted when a Framework Manager package is republished

to the Cognos ReportNet server.

Steps

1. Right-click the package you want and click Edit Package Access.

54

2. If you want to create, add, or remove a user, group, or role, click the User Access tab.

3. If you want to grant administrative access to a user, group, or role, click the Administrator

Access tab.

4. Click OK.

Explore a Package

When you have a large number of projects and object-based security in a project, it can be

difficult to keep everything organized. You can use explore packages to see the packages and

roles in a project.

In the Package Explorer, you see a list of all the packages (normal and object-based) in a

project, as well as the objects that were selected, unselected, or hidden for each package.

In the Roles Explorer, you see a list of all the users, groups, and roles in a project, and in which

package the object-based security is applied. You can also see whether the objects in the

project are hidden or visible to that specific user, group, or role.

Steps

1. Right-click the Packages folder and click Explore Packages.

2. Choose what you want to do.

3. Click Close.

View the Distribution of an Object in Packages

When you view the package inclusion of an object, you see, by package, where that object

exists and whether it is selected, unselected, or hidden in that package.

If the object is secured, you will also see the object-based package in which the object exists.

Steps

1. Right-click the object you want to see and click View Package Inclusion.

2. To edit the package, click Edit Package.

3. Click OK.

View the contents of a package: Click the Package Contents tab.

Edit the package: Click the Package Contents tab, select the package and click the Edit button.

View who has access to each Package: Click the Package Access tab.

View the security for each package: Click the Object Security tab and select a package.

Specify Languages

You can specify which languages are published with each package. You can create several

packages based on the same model, each using a different language.

For example, the package for the Mexican sales office includes Spanish and English. The

package for the Canadian sales office includes French and English.

You can also specify the languages for all packages at one time.

You must add languages to the project before you can specify the languages that report

authors require in packages.

Steps for One Package

1. Right-click a package, and click Specify Languages.

55

2. Click one or more languages and use the arrow buttons to move them from the Available

Project Languages box to the Selected Languages box.

Tip: To select more than one language, use Ctrl+click.

3. Click OK.

Steps for All Packages

1. Right-click the Packages folder, and click Specify Package Languages.

2. Select the check box for the language you want for each package.

3. Click OK.

Externalize Query Subjects

When publishing a package, you have the option to externalize query subjects so that you can

use them in Cognos Series 7 Transformer or other applications.

You first define how the query subjects will be externalized. Then you specify that the query

subjects are to be externalized when you publish the package. You have these options

for the externalize method:

• default

The query subject will not be externalized.

• csv

Use to generate a query expression that can be used as a data source in Transformer. The

comma delimited file that is generated contains the metadata. This option is intended for

use only with Transformer. For any other purpose, we recommend that you use the tab

option.

• tab

Use to generate a query expression that can be used directly as a data source. The

generated file contains data based on Unicode using UTF-16 encoding.

• iqd

Use to generate an Impromptu Query Definition file. Native SQL is generated in the

model.xml file as a custom property.

• embedded

Use if the query subject does not require any local processing. To avoid including security

filters in the query, set the design mode to false. Cognos SQL and Native SQL are

generated in the model.xml file as custom properties.

One file is generated for each query subject that is set to be externalized.

Steps

1. Select a query subject.

You set the externalize method for one query subject at a time.

2. In the Properties pane, in the Externalize Method box, select the method you want.

When you publish the package, the query subjects you selected will be externalized.

Publish a Package

You can publish a package to the Cognos ReportNet Server for report authors and

business authors to use. Report authors use the published package in Cognos Report Studio to

create standardized reports. Business authors use the package in Query Studio to create adhoc

queries.

56

You can also publish a package to a network location. The package cannot then be used by

report authors or business authors. Publishing to a network location can be useful for backing

up a package.

To avoid potential problems, before publishing a package, troubleshoot the package by using

the

Verify the package before publishing check box in the Publish wizard to ensure that it is

complete and does not contain any errors.

When you publish a package, you can

• set the number of model versions to retain on the Cognos ReportNet server.

Tip: To see the number of model versions set for a package, select a package and, in the

Property pane, find the Max Versions property.

• externalize query subjects so that you can use them with Transformer.

Reports and Model Versions

When you publish a package for the first time, you create a corresponding package on the

Cognos ReportNet server. The Cognos ReportNet package contains a model but no reports.

When you publish a package, you can select how many versions of the model you want to retain

on the Cognos ReportNet server. The next time you publish the same package, you update the

version of the model, in the existing package on the Cognos ReportNet server.

New or modified reports use the latest version of the model in the package. When a report is

saved, the version of the model used is saved in the report specification. If the package is

republished, a report author is notified that the report uses the newest version of the model in

the package.

The report author must save the report to complete the update. If you open a

saved report after the package it is based on is republished, one of two things happens:

• If the original version of the package still exists, the report runs against the original version.

• If the original version of the package no longer exists, the report is updated to run against

the most recent version.

Steps

1. Select the package you want to publish.

2. From the Actions menu, click Publish Packages.

3. Choose where to publish the package:

• To publish the package to the Framework Manager repository, click Cognos ReportNet

Server.

• To publish the package to a network location, click Location on the network.

4. To enable model versioning, select the Enable model versioning check box.

5. In the Number of model versions to retain box, select the number of model versions of

the package to retain.

Tip: To delete all but the most recently published version on the Cognos ReportNet server,

select the Delete all previous model versions check box.

6. If you want to use query subjects in Transformer, select the Generate the files for

externalized query subjects check box.

When you are externalizing query subjects, you must publish the package to a network

57

location.

7. To troubleshoot the package for errors before publishing, select the Verify the package

before publishing check box.

8. Click Publish.

If you chose to externalize query subjects, Framework Manager lists which files were

created.

9. Click Finish.

Analyze the Effects of Changes to a Package

After you create and publish a package in Framework Manager, you can analyze the effects of

any changes you made to the package on the reports that were created based on it and saved in

the public folder. You can find what changes were made to the package, and see details about

each change and which reports are affected by a specific selected change.

Steps

1. Select the published package you want to analyze and, from the Actions menu, click

Analyze Publish Impact.

2. Choose what you want to view.

3. Click Close.

Goal Action

View the change details for an object :- In the Changed Model Items box, click an item under

Change.

View report dependencies :- For each object you select in the Changed Model Items box,

click Find Report Dependencies. Repeat for each object.

58

Chapter5: Real Time Issues and Solutions If you import from another Framework Manager project, expression syntax is not adjusted for

each language.

For example, you create a Framework Manager project using French as your design language

and you use French-specific syntax in calculations and filters.

You then create a new project using English as the design language and you import the French

project into the new project. Expressions defined in the calculations and filters are invalid.

The solution is to manually adjust the expression after importing.

Selective Import Does Not Handle Dependencies

If you import one model query subject from a model, the model query subject will not work if

you

do not also import the data source query subjects that the model query subject references.

The solution is to import the data source query subjects upon which model query subjects were

created.

If you are importing from Architect, select all three layers -- Data Access Layer, Business Layer,

and Package Layer.

Unable to Query Data From More then One DimensionTable

When querying data from more than one dimension table in Cognos ReportNet, the following

error messages appears:

UDA-SQL-0458 PREPARE failed because the query requires local processing of the data. The

option to allow local processing has not been enabled.

You may receive this error if the report you are running requires local processing and the query

processing type is set to Database Only.

Steps to change the query processing type

1. In the Project Viewer, click the data source you want to change.

2. In the Properties pane, from the Query Processing list, click either Limited Local or

Database Only.

Saving a Model with Save As Removed the Original Project

When you use the Save As command from the File menu to save a project, a new project.cpf file

and the supporting project files are created in the specified directory.

If a project already exists in the directory you are saving to, the supporting project files for the

existing project will be overwritten. The result will be two project.cpf files with one set of

supporting project files.

If you use the Save As command on the File menu, you must specify a new directory for the

project.

59

Unable to View the Result Set of a Stored Procedure

If the result set of a stored procedure contains a CLOB (character large object) or BLOB (binary

large object), you must modify the stored procedure before running it.

Steps to Use CLOBS

1. Insert a Cast or Substring function to calculate a string based on the CLOB.

Steps to Use BLOBS

1. Create a model query subject that references the stored procedure.

2. Remove the BLOB from the Select statement of the query subject.

You can add query items to the Select statement that perform a lookup on the table that

contains the BLOB data.

Errors in Queries That Use Macros

If a data source query subject contains a macro in the projection list, (Select clause) of the SQL

statement, you may get an error when you run a query that uses that query subject. This error

occurs when the macro evaluates to a column name that is different from the Column Name

property of the corresponding query item. The result is that the system is unable to locate item

in the projection list.

The solution is to specify an alias in the SQL that matches the Column Name property of the

query item. Assigning an alias ensures that the name of the item in the projection list remains

constant, as the results of evaluating the macro change.

For example, the following query contains a session parameter, runLocale, whose value

specifies which column the query retrieves:

Select

#$ColumnMap{$runLocale}# as CountryNameAlias

From

[GoSales].Country

Script Error Occurs When Testing Query Subjects

When you test a query subject in Framework Manager, and you do not have the most recent

version of Internet Explorer, you will get a script error.

It is important to apply all required operating system patches and to use only the versions of

third-party software that are supported. Otherwise, your product may not work properly.

For an up-to-date list of environments supported by Cognos products, see the Cognos support

site (http://support.cognos.com).

Unable to See Test Results

You test a query subject and do not see the results of the query in the test window. This may

occur because the data from your data source is greater than the stop at limit of any Runtime

Limits governor. The query stops at the specified limit, but the test result window does not

contain any data.

The solution is to set the governor stop at limits to zero to view your query results.

Unable to Validate a Calculation if SQL Was Invalid Earlier

If you create an embedded calculation in a query subject and the calculation contained invalid

SQL at some point, you will be unable to validate the query subject.

This happens with data source query subjects and model query subjects.

For example, you create an embedded calculation that referenced a query subject that had not

60

been added to the model yet. When the query subject is added to the model, the calculation

appears as broken but really is corect.

The solution for data source query subjects: Open the Expression Editor for each calculation

and click OK in the dialog box to refresh the calculation.

The solution for model query subjects: Recreate the calculation.

Cross-Join Error

A query defined as col1 = (select min(colx) ) may be interpreted as a cross-join. The query

engine then returns an error that cross-joins have been detected and are not allowed.

The solution is to change the report governor setting.

Unable to Find Functions List for Vendor

When creating a package, you are unable to see the functions list for your data source vendor.

Ensure that the functions list has been selected.

Steps

1. Right-click the package and click Specify Package Functions List.

Ensure that the vendor is listed in the Selected function sets on the right. If the vendor is not

listed, add it from the Available function sets on the left.

date

61

Chapter 6: Common Definitions

access permissions

A definition of which resources the members of a group or a user can read, change, or

otherwise use. Examples of resources are reports and folders.

alias

In modeling and database terminology, a secondary name for a database table. Aliases are

used to create a distinct reference to the table in the model, so that self-joins can be created or

ambiguous query paths can be resolved.

cardinality

A property of a relationship that is used to ensure that queries return the correct results.

Cardinality describes the association between two query subjects and is set at each end of the

relationship.

Cardinality is expressed by using the following notation:

• 0..1 (zero or one match)

• 1..1 (only one match required)

• 0..n (zero or more matches)

• 1..n (one or more matches required)

The first part of the notation specifies the minimum required matches that must exist between

tables: 0 indicates that finding a match is optional, and 1 indicates that at least one row must

match. The second part defines the maximum required matches (1=1, n=many).

For example, A and B have an association with one another. The cardinality of 1...1 for table A

means that for each row in table B, there is only one row in table A. The cardinality of 0...n for

table B means that for each row in table A, there are zero or many rows in table B.

characteristics

A property of a relationship that is used to ensure that queries return the correct results.

Cardinality describes the association between two query subjects and is set at each end of the

relationship.

Cardinality is expressed by using the following notation:

• 0..1 (zero or one match)

• 1..1 (only one match required)

• 0..n (zero or more matches)

• 1..n (one or more matches required)

The first part of the notation specifies the minimum required matches that must exist between

tables: 0 indicates that finding a match is optional, and 1 indicates that at least one row must

match. The second part defines the maximum required matches (1=1, n=many).

For example, A and B have an association with one another. The cardinality of 1...1 for table A

means that for each row in table B, there is only one row in table A. The cardinality of 0...n for

table B means that for each row in table A, there are zero or many rows in table B.

constraint

62

A restriction on the possible values that users can enter in a field.

A security specification that denies one or more users the ability to access a model component

or to perform a modeling or authoring task.

Content Manager

The ReportNet service that manages the storage of reporting applications, including

application-specific security, configuration data, models, reports, and report output. Content

Manager is needed to publish models, retrieve or store report specifications, manage

scheduling information, and manage the Cognos namespace.

content store

The database that contains all data that ReportNet needs to operate, such as

• report specifications, published models, and the packages that contain them

• connection information for data sources

• information about the external namespace, and the Cognos namespace itself

• information about scheduling and bursting reports

Design models and log files are not stored in the content store.

The ReportNet service that uses the content store is named Content Manager.

data source

A named set of connections to physical databases. Framework Manager uses the name of the

data source for models. The ReportNet server uses the data source connections to access the

physical databases.

data source connection

The named information that defines the type of the data source, its physical location, and any

signon requirements. A data source can have more than one connection.

dimension

A representation of the data components that reflect specific business structures. Typically, a

dimension is a nested representation of a business concept.

For example, a geographical dimension such as Continent-Country-State-City represents the

location of branch offices of an organization in multiple levels, using direct parent-child

relationships between each level and its preceding level. The resultant structure is sometimes

referred to as a hierarchy or a dimension. Each level may also have a number of attributes,

which can be used to provide additional descriptive data, like Country Long Name and Country

Population as attributes of the Country Level.

In Framework Manager, dimensions may be represented by folders, or may be types of query

subjects. Both the levels and the attributes are represented as query items, with a special usage

property which describes their role in the hierarchy or dimension.

Levels in hierarchies provide useful default behavior for grouping, filtering, prompting, and so on

to Query Studio and Report Studio users.

governor

A set of rules to stop the execution of reports that will take too long, or take too many

resources.

group

63

In security, a list of users or other groups that you use as a single object for setting access

permissions. Groups are usually created in the authentication provider but may be created

within the administration portal.

Users are authenticated as members of the groups they belong to, unless the groups have also

been defined as roles. Users can choose one or more roles when they log on, to change what

data they have authorization for.

In reporting, grouping is the action of organizing common values of a column or query item

together. Grouped items are automatically sorted. Headers and footers often appear after each

instance of a common value in a grouped column.

hierarchy

A description of the order of levels in a dimension.

In Framework Manager, you define hierarchies in the query subject.

identifier

In modeling, a query item that is a primary key in the database. Query items that are identifiers

are used for building relationships in the model and for sorting, filtering, and grouping in the

report.

In report specifications, any grouped item may be considered an identifier.

join

In modeling, a query item that is a primary key in the database. Query items that are identifiers

are used for building relationships in the model and for sorting, filtering, and grouping in the

report.

In report specifications, any grouped item may be considered an identifier.

See also relationship and cardinality.

key

A unique identifier for a row in a table. A table can have more than one key. Keys are also used

to create relationships.

For example, the CUST-ID column is the primary key for the CUSTOMERS table because there

can be only one customer ID for each customer.

Foreign keys are columns that establish relationships between tables. For example, the

CUST-ID column in the ORDERS table is the foreign key that joins the ORDERS table to the

CUSTOMERS table. Each order in the ORDERS table can be associated to only one customer.

key figure

A unique identifier for a row in a table. A table can have more than one key. Keys are also used

to create relationships.

For example, the CUST-ID column is the primary key for the CUSTOMERS table because there

can be only one customer ID for each customer.

Foreign keys are columns that establish relationships between tables. For example, the

CUST-ID column in the ORDERS table is the foreign key that joins the ORDERS table to the

CUSTOMERS table. Each order in the ORDERS table can be associated to only one customer.

In SAP BW, values or quantities such as sales revenue, fixed costs, sales quantity or number of

employees.

In addition to the key figures saved on the database, you can define derived (calculated) key

figures in the query definition in BEx. Examples of derived key figures are: sales revenue by

64

employee, variance as a percentage, and contribution margin.

level

A group of query items that must contain a key query item, so that each member within the

group is unique. Levels may contain other non-key query items. Levels are parts of dimensions.

For example, a geographical dimension might contain levels for country, region, and city.

locale

A code that is used to set

• the language or dialect used for browsers, report text, and so on

• the regional preferences, such as formats for time, date, money, money expressions, and

time of day

In ReportNet, you can specify a locale for the product interface (product locale) and for the data

in the report (content locale). A locale is also stored to record what locale an author used to

create a report specification or a Framework Manager project.

measure

A query item that contains values that can be aggregated to produce meaningful results. For

example, product costs can be treated as a measure because average and total costs have

some meaning, but product codes, though numbers, are not usually treated the same way.

Measures are quantitative performance indicators. Measures give the numbers that usually

appear in the cells of crosstab reports or in the numbers of a chart.

model

A business presentation of the structure of the data from one or more databases. A model

describes data objects, structure, and grouping, as well as relationships and security.

A model, called a design model, is created and maintained in Framework Manager. The design

model or a subset of the design model must be published to the ReportNet server as a package

for users to create and run reports.

model segment

A part of a Framework Manager project that is a shortcut to a second project. Segments can be

parameter maps, data sources, namespaces, or folders. You must make any changes in the

source project, not in the segment.

You use segments to simplify model maintenance or to facilitate multi-user modeling. How you

use segments does not affect the packages that you publish to ReportNet.

namespace

In security, a collection of user accounts and user groups from an authentication provider.

In XML, namespaces uniquely identify element types and attributes. An XML namespace is

defined by a URI (Uniform Resource Identifier) whose purpose is to name the namespace, not

necessarily to identify a location from which to obtain information.

In Framework Manager, namespaces uniquely identify query items, query subjects and so on.

You import different databases into separate namespaces to avoid duplicate names.

normalization

In programming, the process of standardizing the format of information, such as locale codes.

package

65

A container for models, reports, and so on. Modelers create packages in Framework Manager to

publish models to the ReportNet server.

See also query subject, and query item.

portal

A Web site or page that provides a single presentation and a single starting point for a set of

information. Also, the Cognos component that runs the Cognos portal site.

Cognos Web products may use a Cognos portal or may be integrated with other portals.

project

A set of models, packages, and related information for administration, and for sharing model

information. You create projects in Framework Manager.

query item

A representation of a column of data in a data source. It contains a reference to a database

column, a reference to another query item, or a calculation. Query items may appear in a model

or in a report.

query locale

The ISO standard code associated with a query the specifies the language and formatting of

what part??? of the report results. A representation of a column of data in a data source. It

contains a reference to a database column, a reference to another query item, or a calculation.

Query items may appear in a model or in a report.

query subject

One of the types of objects inside a model. A query subject can be

• defined as a collection of references to items of other query subjects

• expressed as an SQL expression that represents selected query items, which will be

retrieved from objects such as tables, synonyms, views, and so on

Query subjects contain query items. Query subjects may be part of folders in the model. The

query subject is the basis of a query in Report Studio and in report specifications.

relationship

A connection that explains how the data in one table relates to the data in another. When you

create a relationship, you define the cardinality of each end of the relationship.

For example, a one-to-many relationship between table A and table B means that for each row

in table A, there can be 1 or more row matches in table B. Therefore, table B has a many-to-one

relationship with table A.

report specification

An XML representation of the queries, prompts, layouts, and styles in a report. You create

report

specifications by using Cognos Report Studio or Query Studio, or by writing your own report

specifications in XML.

role

A special group that users can choose when they log on to change what groups they are

authenticated as members of, so that they change what data they have authorization for.

66