3. Framework Manager Manual
-
Upload
bhupathi-reddy -
Category
Documents
-
view
69 -
download
1
Transcript of 3. Framework Manager Manual
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