Cognos Planning Guide

COGNOS(R) ENTERPRISEPLANNING SERIES C O G N O S P L A N N I N G

DATABASE ADMINISTRATOR (DBA) GUIDE

THE NEXT LEVEL OF PERFORMANCETM

Cognos Planning Database Administrator (DBA) Guide

Cognos Planning Database Administrator (DBA) Guide

DATABASE ADMINISTRATOR (DBA) GUIDE

Product InformationThis document applies to Cognos Planning v 7.3 and may also apply to subsequent releases. To check for newer versions of this document, visit the Cognos support Web site (http://support.cognos.com).

CopyrightCopyright (C) 2005 Cognos Incorporated.

Portions of Cognos(R) software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188 B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2.

While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document.

This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to either the product or the document will be documented in subsequent editions.

U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, or subparagraphs (C) (1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227-19, as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803.

This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated.

Cognos and the Cognos logo are trademarks of Cognos Incorporated in the United States and/or other countries. All other names are trademarks or registered trademarks of their respective companies.

Information about Cognos Products and Accessibility can be found at www.cognos.com

http://www.cognos.com

Table of Contents

Introduction 5

Chapter 1: The Contributor Datastore 7Contributor Datastore Objects 8

Static and Dynamic Datastore Objects 8The Planning Administration Domain Datastore and the Common Datastore 9The Application Datastore 10Publish Containers 10

Sizing Tablespaces 10Tablespace Management 11

Chapter 2: Working with Contributor Applications 13Creating a Contributor Application 13Assigning User Access to Data 14Importing Data into the Contributor Application 15Go to Production 16Maintaining the Contributor Application 16

Storing User Data 17Getting Data Out of the Plan 17Making Changes to the Model 17

Types of Jobs 17Backup and Recovery 19

Chapter 3: Datastore Security 21Generating Scripts 21

Create a Contributor Application 22Add, Edit, and Delete D-List or D-Cube 22No Change in Model, but Change in Dimension for Publish for View Publish Layout 22

Changing the DDL Script 23

Chapter 4: Publish Datastores 25Publishing to a Different Datastore 25The Table-Only Publish Layout 26

Items Tables for the Table-only Publish Layout 27Hierarchy Tables for the Table-only Publish Layout 28Export Tables For the Table-only Publish Layout 30Annotations Tables for the Table-only Publish Layout 31Metadata Tables 31Common Tables 33Job Tables 33The objectlock Table 34

The View Publish Layout 34Items Tables for the View Publish Layout 34Hierarchy Tables for the View Publish Layout 35Export Tables for the View Publish Layout 35Annotation Tables for the View Publish Layout 35Views 36

Chapter 5: Oracle Datastores 39Oracle Client Tools 39Securing the Oracle Datastore 40

Create the COGNOSEP User 40

Database Administrator (DBA) Guide 3

Create the LOCKDOWN User 40Administering the Secured Datastore 42

Sizing Oracle Tablespaces 42Locally Managed Tablespaces With Uniform Extent Sizing 43

Fine-tune Your Datastore for Better Performance 43Rename an Application 44

Index 45

4 Cognos Planning

Introduction

This document provides an overview of the Cognos Planning - Contributor 7.3 datastore structure specifically for the Oracle DBA and provides tips to ensure a successful implementation on Oracle relational database. It also describes the interaction of Contributor with its datastores, and guidelines for the management of an RDBMS server for Cognos Planning applications. It is supplementary to the user documentation supplied with Cognos Planning 7.3, and training courses.

Cognos Planning provides the ability to plan, budget, and forecast in a collaborative, secure manner. There are two major components, both of which you should be familiar with before using this document.

Cognos Planning - AnalystAnalyst is a flexible tool used by financial specialists to define their business models. These models include the drivers and content required for planning, budgeting, and forecasting. The models can then be distributed to managers using the Web-based architecture of Cognos Planning - Contributor.

Cognos Planning - ContributorContributor streamlines data collection and workflow management. It eliminates the problems of errors, version control, and timeliness that are characteristic of a planning system solely based on spreadsheets. Users have the option to submit information simultaneously through a simple Web or Excel interface. Using an Intranet or secure Internet connection, users review only what they need to review and enter data where they are authorized.

For more information about using this product, visit the Cognos support Web site (http://support.cognos.com).

Version and License Requirements With OracleCognos supports Oracle Enterprise Edition version 8.1.7 and later, (excluding 9.0.1.1). To verify whether additional users are authorized under your current Oracle License agreement, contact your Oracle Sales Representative. The License agreement is dependent upon whether you have the original Concurrent Device agreement or the new Named User Universal Power Unit agreement.

Related InformationThe following documents contain related information, and may be referred to in this document.

Document Description

Analyst and Manager User Guide Using Analyst to create planning models

Contributor Administration Guide Creating and administering Contributor applications

Cognos Planning New Features Guide Describing features that are new in Cognos Planning 7.3.

Cognos Planning Best Practice Guide Applying best practice guidelines, troubleshooting tips, focusing on how you can use the new features to get the best out of Cognos Planning 7.3.


Introduction

Our documentation includes user guides, tutorial guides, reference books, and other materials to meet the needs of our varied audience.

Online HelpSome information is available in online help. Online help is available from the Help button in a Web browser, or the Help menu and Help button in Windows products.

Books for PrintingCognos grants you a non-exclusive, non-transferable license to use, copy, and reproduce the copyright materials, in printed or electronic format, solely for the purpose of providing internal training on, operating, and maintaining the Cognos software.

You can also read the product readme files and the installation guides directly from Cognos product CDs.

Get Data User Guide Using Contributor Get Data to load data into Contributor

Access Manager Administrator Guide Configuring security information

Document Description

6 Cognos Planning

Chapter 1: The Contributor Datastore

Cognos Planning - Contributor is a Web-based planning platform that can involve thousands of people in the planning process, collecting data from managers and others, in multiple locations. Complex calculations are performed on the Web client showing totals as soon as data is entered, preventing unnecessary traffic on the server during busy times. Information is then stored in a data repository, providing an accurate and single pool of planning data.

A Contributor application is generated from a Cognos Planning - Analyst model. The model is developed outside of the database environment using Analyst, and the Contributor application is created using the Contributor Administration Console. Users enter data into the Contributor Web application over HTTP. The data is processed and stored within the application datastore. Finally the processed data is published to a separate datastore in star schema format to be used for reporting or incorporation into a data warehouse for use by other applications. The Contributor Administration Console may be used to create a number of Contributor applications.

One Contributor datastore exists for each Contributor application and acts as a simple container for datastore objects. The implementation of a Contributor datastore is RDBMS specific.

Naming ConventionsThe naming convention for datastore objects is SQL1992 compliant. When the enterprise database is not fully SQL 1992 compliant, datastore object names conform to the limitations of the target datastore. That is, the Contributor Administration Console restricts the length of the application or datastore container name during the create application process. From that point on, all datastore object names are fully qualified in DDL script or DML (Data Manipulation Language) using the datastore container name.

Static object names are the same across all applications and do not change during the life cycle of the Contributor application.

Dynamic objects, primarily import tables, publish tables, and views, are named after objects within the Analyst model. Object names correspond to Contributor model object names with a subsystem prefix, subject to database-specific limitations. All dynamic object names are forced to conform to naming conventions as per the Contributor application container. Other datastore object names, for example, indexes, are automatically generated and are not intended to be meaningful.

MetadataContributor application datastores contain the metadata subsystem. The content of the metadata tables is critical to the functioning of the Contributor application. The metadata provides a mapping from internal Contributor model identifiers to the external datastore objects.

DDL scripts may be amended to conform to local storage conventions and may be tailored to suit your hardware. However, data integrity must be maintained. It is essential that you do not amend datastore object names within the DDL script and allow the information contained within the metadata tables to become out of synchronization with the underlying datastore objects.

RDBMS Contributor datastore

Oracle User schema

Microsoft SQL Server Database

DB2 UDB Schema



Contributor Datastore ObjectsThe Contributor datastore is made up of three datastore types: the Planning Administration Domain datastores, application datastores, and publish datastores. Each datastore type performs a distinct function. The Planning Administration Domain datastores are used to store details regarding the location of Contributor applications as well as administration information that may be common to all applications such as macro definitions and administration user access rights. Application datastores contain the actual model definition and settings that apply only to the specific Cognos Planning model. Publish datastores contain a star schema representation of the Planning data and metadata to be accessible for reporting and data warehousing applications.

The following diagram shows the relationships between the three distinct Contributor datastore types.

Static and Dynamic Datastore ObjectsYou can group datastore objects by functionality. Any subsystem must support a minimum functionality in order to operate as a separate datastore. For example, the publish datastore supports a subset of the application datastore in addition to the publish tables and views. You can also categorize datastore objects in the Contributor datastore as static or dynamic. Datastore objects which are the same for each Contributor application are static. Dynamic objects change according to the Contributor application. The number and names of the dynamic objects vary by Contributor application.

Application A Application B Application C Application D

application containers

publish containers - star schemas

Planning Administration Domain (PAD) and common datastore

PAD Common

Datastore Object Static / dynamic

Planning Administration Datastore

Application datastore

Publish datastore

Planning Administration Domain and common tables

static yes no no

application tables static no yes no

job tables static yes yes yes

8 Cognos Planning


The Planning Administration Domain Datastore and the Common Datastore

The Planning Administration Domain is a new datastore in Contributor version 7.3. It is the first store that you create after installing the Contributor Administration Console. All information about other Contributor datastores is held in the Planning Administration Domain, and it also contains configuration information about every application, publish container, job cluster and job server, and subsequent job activities across the whole domain. One Planning Administration Domain datastore is sufficient for a fully working system containing multiple applications. Reasons for having multiple Planning Administration Domains could be: separation of test and production environments, security separation between applications, geographical and latency issues across WANs and LANs. Note that you cannot move data through links between applications in different Planning Administration Domains.

As well as holding configuration information in a centralized store, the Planning Administration Domain is designed to control the security for all the Contributor administration functions, but not the end-user Web client functions.

Contributor version 7.3 allows multiple administrators to simultaneously work on a Contributor application as long as the tasks they are performing are not in conflict. A system administrator deploys access to different applications and different roles within the application to multiple administrators. The system administrator can also cascade to other administrators the ability to deploy access down to other administrators. Administrators can only see applications and functions that apply to them.

The Planning Administration Domain is a very lightweight relational schema. It is optimized for many reads and many writes of small amounts of data. Tablespace allocations and backup and restore policies should take this into account. The data is closely tied to all other datastores referenced by the Planning Administration Domain. As a result, whenever you back up a specific Contributor application, back up the Planning Administration Domain datastore, and Analyst model as well. The Planning Administration Domain contains administrator security settings and platform configuration data which does not change frequently. A Planning Administration Domain can be rebuilt at little cost as long as the application containers are available. Note that this depends on the complexity of the security information across the applications, and the number of applications. The greater the complexity of security and the number of applications, the greater the cost of rebuilding the Planning Administration Domain. The Planning Administration Domain is also closely tied to the Access Manager namespace within a specific LDAP data source. Take this into account with your backup and restore policy.

The common datastore was introduced to support two new cross-application features: administration links and macros, and one common datastore per Planning Administration Domain. Administration links allow administrator to move data between Contributor applications. The common datastore must be monitored by the job subsystem to run the jobs. Macro definitions are also stored within the common datastore and do not necessarily require transaction level recovery as changes should be relatively infrequent and tightly controlled.

application configuration tables

static no yes no

application metadata tables

static no yes yes

extension component tables

static no yes no

import tables dynamic no yes no

publish tables and views

dynamic no no yes

Datastore Object Static / dynamic

Planning Administration Datastore

Application datastore

Publish datastore



The common datatore contains first class data objects (links and macros) which may contain sizeable XML binary blob data that is both written and read at reasonable frequency. Backup and restore of both the Planning Administration Domain and common datastores should be performed at the same time.

The Application DatastoreAll application settings, data, and metadata for each individual Contributor application are stored within the relational tables that make up the Contributor application datastore. This includes the Contributor import tables.

Large Object Types (LOBs)Large object types are used to store the XML documents comprising compressed data. Examples of this are the storage of the Analyst model definition as well as user data for transmission over HTTP. In addition, users are able to submit free format annotations which are formatted into XML documents and stored as large objects. You may have a policy on LOB storage and want to review the default DDL scripts. This is good practice for planning storage and growth, which is essential to a successful long term implementation.

Publish ContainersWhen Cognos Planning data has been submitted, it can be extracted from the application datastore’s XML LOBs into a star schema formatted set of relational views and tables. Contributor refers to this star schema-based collection of views and tables as the Publish container. When published, you can move the planning data into a Data warehouse or other applications for reporting. Contributor provides two options for publishing plan data: View Publish, which is the traditional format for published plan data in Contributor, or Table-only Publish, a star schema that is optimized for reporting purposes.

Contributor Publish containers are a snapshot of the plan, and contain data which meets the selection criteria of a Contributor Administrator. The Publish datastore is populated as required for your Cognos Planning environment and is not transactional in nature. That is, it is not an online transaction processing (OLTP) database. It is not necessary to perform transaction level logging or backup against Contributor Publish datastores.

Sizing TablespacesYou can estimate an initial sizing for a Contributor application using the total number of cells per slice for the application and assuming an average storage utilization of 16 bytes per cell. Actual storage utilization varies based on data types, data density, use of annotations, and datastore management practices.

For example, you can estimate rough storage requirements for an application with 34,849 cells per e.List item slice and an e.List with 27 e.List items as follows:

34,849 * 27 * 16 = 15,054,768 bytes• Divide by 1,024 to get KB15054768 / 1024 = 14,702 KB• Divide by 1,024 to get MB14702 / 1024 = 14.36 MB

We recommend that you allow for approximately 2.8 times more storage than the results of this calculation. This extra storage will account for application growth through contributions as well as the following application behaviors: • During administrative functions (Go to Production, reconcile, import, and publish), the

application temporarily increases the size of the datastore as processing is completed.

• Space for logs and other associated RDBMS functions.

For information about Oracle tablespaces, see "Sizing Oracle Tablespaces" (p. 42).

10 Cognos Planning


Tablespace ManagementWhen Cognos Planning applications are created using Oracle or DB2 UDB, Contributor uses the default Data, Indexes, BLOBs, and Temporary tablespaces. • Tip: You can view the tablespaces used by an existing application in the Contributor

Administration Console: in Development, click Datastore Options, Datastore Maintenance, and then click the Tablespaces tab.

You can customize these tablespaces when creating the application. Both the Oracle and IDB2 UDB datastores require the allocation and ongoing maintenance of tablespace storage requirements.

The storage requirements for a Contributor application grow as contributions are saved by users, administrative jobs are run, and as iterative Go to Production tasks are completed. The use of user and audit annotations also impacts storage requirements based on the size and number of annotations.

Monitor storage utilization for tablespaces used by Contributor datastores on a regular basis to ensure that Contributor does not grow beyond its allocated storage. As a general rule, new applications should be maintained below 40% tablespace utilization. For mature applications, the Contributor tablespace should be increased by 25% whenever utilization reaches 70% of available space.



12 Cognos Planning

Chapter 2: Working with Contributor Applications

The main administration tool for Cognos Planning - Contributor is the Contributor Administration Console. The Contributor administrator creates a Contributor application using a application creation wizard or Contributor macro that links the Administration Console to the Cognos Planning - Analyst model and generates a sequence of DDL and DML statements. These statements are either executed interactively or persisted to local disk storage so that they can be run later by a DBA.

During the Cognos Planning implementation, DBA assistance is necessary to set up the instances, establish the network connections, assist with the data transfers, and perform datastore tuning where appropriate. When Contributor applications are in production and are stable, DBA involvement typically scales down to performing backup procedures and occasional tuning and data transfer.

During the life cycle of the Contributor application, there are two important datastore tables, both stored in a main subsystem of the datastore table:• applicationstate table: This contains the Analyst model persisted as a LOB in XML format.• nodestate table: This contains user data persisted as an LOB in XML format.

The Contributor application life cycle follows these steps:

❑ Create a business model for planning, budgeting, and forecasting using Analyst. This is typically performed by Analyst model builders. There is no datastore interaction. For more information, see the Analyst and Manager User Guide.

❑ Create Contributor applications from Analyst models.

❑ Configure the Contributor application. For more information, see the Contributor Administration Guide.

❑ Assign user access to data.

❑ Import data.

❑ Make the Contributor application live to users using the Go to Production process.

❑ Publish data (p. 25).

Creating a Contributor ApplicationThere are two methods of creating a Contributor application: through the Contributor Administration Console, or by creating and running a DDL script named script.sql.

Using the Contributor Administration Console is lower maintenance and does not require a DBA. Datastore objects are created and populated inside the datastore container's USERS tablespace. The DDL script is executed automatically at the end of the create application process and the package is loaded into the applicationstate table.

The script.sql file is a DDL script and must be edited and run by a DBA. The script allows you to edit and modify tablespace placement and storage settings for each object. After you have edited and run the script, the Contributor administrator can link to the application and upload the compressed model (persisted as XML to local disk) into the applicationstate table.

Lockdown EnvironmentA lockdown environment is one where only a DBA can execute DDL commands.



The Analyst model, named package.xml, is loaded into the applicationstate table after you run the Script.sql. When the DDL script has run, the Contributor administrator can link to the Contributor application and is then prompted to upload the compressed model, persisted as XML to local disk, into the applicationstate table.

If you are using Oracle, you can create a LOCKDOWN user (p. 40).

Open EnvironmentIn an open environment, the Contributor Administration Console interacts directly with the RDBMS through DDL from the administration server and so application creation does not require DBA intervention. The DDL script is executed at the end of the create application process and the package loaded into the applicationstate table. The administration server requires knowledge of the Analyst model to be able to write the development items.

development_items TableThe first time the Analyst model is written to the applicationstate table and every time the model is changed, rows are deleted and inserted into the development_items table. The number of rows is determined by the size of the model and the number of items within each dimension in the model. Note that if a dimension is used more than once in a model, there will only be one entry for it in the development_items table. Dimensions are lists of values and the development_items table contains all the valid values in each list along with the internal reference, a GUID. This information can be used to produce valid metadata to be imported into the Contributor application later. Rows in the development_items table always contain valid values for the most recent version of the development model.

User DataAt this point, there is no user data, and so the nodestate table is empty. Users cannot start to submit data into the application until the application has been configured and the Go to Production process run.

Loading Initial DataBefore users access the Contributor application through the browser-based Web client, background data (named actuals) are loaded from the Analyst model. Actuals is data such as sales or costs figures for previous years. The data volume is application and model specific, and can be very large.

Assigning User Access to DataAccess to data in Contributor applications is controlled by assigning sections of data (named e.List items) to users in the Contributor Administration Console. The Contributor administrator imports text files containing lists of users and access permissions into the Contributor application. Administrators assign responsibility to Web client users for one or more e.List items. An e.List item typically contains all data relating to a geographical location such as a local branch. This does not affect the enterprise datastore security.

e.List items are a common unit of processing throughout Contributor. Typically, data is processed on a per e.List item basis. Access rights within a Contributor application are assigned based on Access Manager user classes, rather than individual user names.

e.List items are arranged in a hierarchical tree. For example, local branch figures may feed into regional and national figures. Leaf e.List items in the tree are called contribution e.List items, as they are the ones that contribute data into the Contributor process. Higher level e.List items are called review e.List items, right up to the top level e.List item. Every e.List item ultimately has a row in the nodestate table containing data ready for download, compressed and stored in an XML document as a LOB. The list of e.List items, called the e.List, is a dimension and is written to the development_items table.

14 Cognos Planning


Importing Data into the Contributor ApplicationThe Contributor administrator imports data into the Contributor application through the import function in the Contributor Administration Console in the following stages:• Copy moves flat files to the application server. • Load uses SQL*Loader to populate the im_cubename tables (these are staging tables).• Prepare matches the test string dimension items to the corresponding CognosGUID.• Go to Production pulls the data into the proprietary XML format, to be viewed and used by

end users.

Each stage can be completed independently if the earlier step is complete.

Copying the DataThe copy process copies the import data file to a file location on the administration server and specifies the cube the data is to be loaded into. The administration server destination is specified in the adminoptions table.

If the import files are large, it is quicker to copy manually the files across to the administration server destination, but you must specify file location and destination one file at a time using the Import Copy function in the Contributor Administration Console.

Loading the DataYou can populate the im_cubename tables with data using either of these methods:• Using the Load function in the Contributor Administration Console, or using a Contributor

macro.This is the standard way to load data from a text file (comma or tab-delimited) into the im_cubename table(s). This process generates a SQL*Loader Control File and executes SQL*Loader.

• Using an ETL tool, such as Decision Stream or a third-party ETL tool. The source could be SAP, PeopleSoft, or other third party application, with the target as the im_cubename in the application datastore. The data is prepared using the Contributor Administration Console, and the final process is completed by running Go to Production in the Contributor Administration Console.These processes can be automated using Contributor Macros. For more information about automation, see the Contributor Administration Guide.

Alternatively you can retain control of the population of the import tables to be able to schedule the data loads at appropriate times. The Direct Path method could be used. This requires the control, command, and ifile to be on the datastore server (the Direct Path method requires the common operating system with the client, Windows, for 8i only). The definition of the import tables can be retrieved from the Contributor metadata.

Preparing the DataThe Contributor administrator uses the Prepare function to process the loaded data. Alternatively, you can create a Contributor macro to do this. The Prepare process creates and runs a Prepare Import job. Import data is pulled down into the MTS layer on an e.List item by e.List item basis, and a job item is created for each e.List item.

No DDL is generated at this stage, only DML is executed, that is, reads and inserts or updates depending on whether a row already exists for each e.List item. The actuals data is extracted by each job item on a per import table basis. The processed data is written as a LOB in XML format to the importqueue table. A single row exists in importqueue for each Contributor e.List item for the current version of the Cognos planning model. Any errors in processing the actuals data are written to the ie_cubename table. An ie_cubename table exists for each import table.

The LOBs in the import queue are often not as large as the user data in the nodestate table, or the package XML stored in the applicationstate table. The applicationstate table still contains the same package.xml inserted during application creation. However in addition to the Contributor model, the package.xml contains lists of e.List items, users and rights. The nodestate table is empty.



Data now exists in the importqueue table. The next step is to process it through the Go to Production process.

Go to ProductionThe Go to Production process makes a Contributor application available to users. Go to Production can be executed from the Contributor Administration Console as a wizard, on demand through an administrator defined Contributor macro, or by using a scheduling tool that runs a Contributor macro from a batch file using the Contributor command line interface. The Go to Production process triggers a reconcile job that establishes the list of e.List items that will be processed by the Contributor job architecture.

The reconcile job processes user data and makes it available for use with the latest version of the Contributor model stored in the applicationstate table. Immediately after application creation, all e.List items require processing. Contributor supports online changes to the Contributor model stored in applicationstate. These changes do not affect users accessing the system because user data is associated with a version of the Contributor model. The currently active version of the Contributor model is not changed. Instead, a copy of it, named the development model, is changed. The updated version only becomes the current version after the Go to Production process is run.

The following steps occur during the Go to Production process:• Pre Production

Blank rows are inserted into the nodestate table for any new e.List items that are added to the updated package.xml. When an application is initially created, a blank row is inserted for all e.List items.

• Go to ProductionThe processing of the updated and old model package.xml in the applicationstate table. This is a critical part of the process. The Web client computer cannot connect to the application datastore to ensure data integrity. The Contributor application is offline but only for a short period of time, typically less than one minute.

• Post ProductionEstablishes which rows in nodestate require processing, that is, which users have data that require updating. A reconcile job is created to carry out this task.

In the application datastore, no DDL is generated, only DML is run. Any existing user data is extracted from the nodestate table and reformatted by the job cluster to be compatible with the incoming (optionally updated) Contributor model stored in applicationstate. Any actuals data in the importqueue is incorporated into the user data at this stage and the compressed data block is stored as a LOB in XML format in the nodestate table. The Contributor e.List item data is aggregated to write review e.List item data during this process.

The end result is a single row in nodestate with two LOB columns: one for data and one for annotations for each e.List item in the system. The format of this matches the Contributor model definition held in the applicationstate table. At this stage, users can start connecting to the Contributor application using the Web client.

Maintaining the Contributor ApplicationWhen the Contributor application is live, the planning process can begin with users entering and reviewing data. This data can be published to be reported on, analyzed, or used in data warehouse systems. It is likely that the structure of the Analyst model will change on an ongoing basis to reflect the needs of the business. As such, the Contributor application must be synchronized so that the application datastore reflects the changed Analyst model.

16 Cognos Planning


Storing User DataWhen a user accesses the data that has been assigned to them, the data is downloaded from the nodestate table into the Web browser via IIS, ASP and MTS components. Users can then start to contribute to the planning process by entering data into cells. The browser-based client encourages users to batch changes and so does not generate excessive datastore updates.

When a user updates the datastore, the figures are aggregated up the e.List, where child e.List items are totaled into parent figures; parents into their parents all the way up the tree until the top level e.List item is reached. This is a very fast process due to the design of the XML document used to store each data block in the nodestate table.

No DDL is generated, only DML is executed (reads and updates). The aggregation of data is carried out inside a transaction to ensure integrity.

Getting Data Out of the PlanWhen users have saved their data, the data can published into a star schema by the Contributor administrator. This data can then be used for reporting and analysis or moved into a data warehouse for use within other systems. Publish extracts the plan data from its stored XML BLOB format into a relational star schema which can be easily queried by reporting tools or any SQL capable application. Publish tasks are defined within the Contributor Administration Console. Administrators can choose to publish the entire plan, subsets of the plan, or just changes to the plan based on pre-defined selection criteria. Publish tasks are processed by Contributor’s job server subsystem, which makes the process of extracting plan data scalable. Contributor provides two formats for the creation of the relational star schema representation of plan data: View Publish and Table-Only Publish. For more information about publishing, see "Publish Datastores" (p. 25).

Making Changes to the ModelThe Contributor application may need to change to reflect changes in the business. These changes are made to the Analyst model and then synchronized in the Contributor Administration Console. This process updates the development model stored in the applicationstate table with changes made in the Analyst model.

To make these changes available to users, Go to Production must be run. This generates a reconcile job which processes all the current data held in the nodestate table to match the new package XML held in the applicationstate table. This process updates all e.List items within the Contributor application, adding new cells and removing redundant data from the data block for each e.List item.

DDL may be generated (this is as a script in a lockdown environment) because changes to the model may require alterations to the dynamic database objects. More DML is executed from the MTS layer via the job architecture. Reads and updates of the nodestate table are executed, but only for e.List items affected by the changes to the model. All processing is carried out by the reconcile job within the MTS layer.

Types of JobsA job is triggered by an administration task such as publish. Jobs run on job servers, which are in turn grouped by job server clusters, and are monitored by the Contributor Administration Console. Jobs are scalable; adding additional job servers speeds up processing of jobs. You can have the following types of jobs.

Job type Description

Annotations tidy Deletes user annotations and audit annotations.



Self Maintaining JobsThe reconcile job is self repairing. It knows which e.List items require a data update to match the Contributor model definition. If a reconcile job fails to complete successfully, for example, due to network outage, then it is possible to create another one to rectify the situation. You do this in the Contributor Administration Console, in the Job Management screen, by double-clicking on the failed job and clicking Repair.

Tidy Up JobsSome Contributor jobs, such as prepare import, have a tidy up mode. At key points they generate jobs to be executed by the job cluster, which help maintain the datastore by removing redundant data.

The Contributor datastore grows for the following reasons:• While the repair and tidy-up jobs remove redundant data, the storage requirements grow as

users contribute data into the application.• Additionally, as actuals are imported, or as the model is expanded (and consequently new

dynamic datastore objects are created), the datastore grows. The Contributor datastores should still be subject to the normal enterprise monitoring. In particular, storage should be monitored on a regular basis. We recommend that you have a lockdown environment to control expansion and growth.

Cut-down models Customized copies of the master Contributor model definition that have been cut-down to include only the specific elements required for a particular e.List item.

Cut-down tidy Removes any cut-down models that are no longer required.

Export queue tidy Removes obsolete items from the export queue.

Import queue tidy Removes model import blocks from the import queue that are no longer required.

Inter-app links Transfers data between applications.

Language tidy Cleans up unwanted languages from the data store after the Go to Production process is run. This job is created and runs after Go to Production is run.

Prepare import Processes import data ready for reconciliation.

Publish Publishes the data to a view format.

Reconcile Ensures that the structure of the e.List item data is up to date. This job is created and runs after Go to Production is run.

Reporting publish Publishes the data to a table-only format.

Validate users Checks to see if the owner or editor of an e.List item has the rights to access the e.List item. The job checks the rights of users, in Access Manager or in the Contributor model as appropriate, and updates the information in the Web browser. This job is created only if a change is made to the Contributor model, and runs after Go to Production is run.

Job type Description

18 Cognos Planning


Backup and RecoveryThe DBA is responsible for backup and recovery. You can use the Contributor Administration Console to back up (export) the application before running the Go to Production process. However, we recommend that you use the datastore tools instead of this option because of the disk overhead for generating the export file.

Ensure that you back up the following datastores:• Contributor application• Planning Administration Domain• common

Back up the related Analyst libraries at the same time. Note that you may have more than one library associated with a Contributor application, the main one from which the application is created, and a common library that contains shared D-Lists.

You do not need to backup the publish datastore or the import staging tables, as these can be recreated.

We recommend that you make an online backup nightly and store archive logs. Export the database users (OWNER=APPLICATION1, APPLICATION2 and COMPRESS=N.)

Exporting the users gives you the ability to remove an individual application and replace it with its backup without taking down the other applications. However, this option does not allow for point-in-time recovery.



20 Cognos Planning

Chapter 3: Datastore Security

Cognos Planning - Contributor is designed to respect local enterprise database best practice. The Contributor datastore containers and associated application datastore objects are defined using XML and created via DDL. Local security restrictions may prevent the Contributor account from executing these statements. DDL scripts can be generated for any action that causes datastore objects to be added or removed, using the Generate Scripts option, or by choosing the Generate datastore scripts and data files option in the Create Application wizard or macro. The DDL script can be executed by a DBA using your own security credentials.

The Contributor Administration Console produces delta (diff) scripts, and datastore objects are added and removed only when necessary on a per object basis.

To decide whether you want to use the generate scripts option to create DDL scripts, consider the following questions. Should Contributor administrators execute DDL against your enterprise datastore without review? Does local policy allow the Contributor security context sufficient privileges to be able to create/remove Contributor application container datastores? If the answer to either of these questions is no, use the Generate Scripts option.

You can also generate DDL scripts to do the following:• tailor to your own storage standards or customize storage clauses• amend or add sizing clauses to the Contributor default DDL

For information about Oracle security, see "Securing the Oracle Datastore" (p. 40).

PrivilegesThe privileges required for the Contributor accounts are specific to each datastore provider and determined by the setting of the Generate Scripts option. If you decide not to use the generate scripts option, and allow the Contributor account to execute DDL interactively, then the Contributor account requires create / remove datastore permissions. The account also requires create / remove permissions on all Contributor datastore objects (as well as the standard SELECT, INSERT, UPDATE and DELETE).

If you prefer to execute the DDL scripts using your own security credentials, you can restrict the Contributor administrator to a standard SELECT, INSERT, UPDATE, DELETE privilege on the Contributor datastore objects. In all circumstances, it is necessary for the Contributor account to have sufficient privileges to carry out a non-logged delete of all data in a table, such as a TRUNCATE table.

The Contributor installation contains sample scripts to create the Contributor account for each supported datastore provider under both an open and Lockdown environment. Contributor can also operate under a regime of trusted security. You can also insert permission granting statements into DDL scripts.

Generating ScriptsThe Generate Scripts option enables you to separate actions that should be performed only by a DBA. These actions include creating or dropping datastore objects from standard reading, writing, inserting, and deleting of data operations (DML), which take place on a day-to-day basis.

When Generate Scripts is used, DDL scripts are generated when the datastore needs to be restructured, for example if tables need to be added or deleted when publishing, and when synchronizing. The DDL script contains a series of instructions to create or drop datastore objects, and can be edited.

A DDL script can also be generated when creating an application.



Set the Generate Scripts option on by setting the Gen_Scripts option to true in the adminoptions table, or set Generate Scripts to Yes in the Contributor Administration Console (Development, Application Maintenance, Admin Options).

Do not drop Contributor datastore objects using your own enterprise database tools unless requested to do so by Customer Support. Use caution to avoid getting the Cognos Planning metadata out of synchronization with the underlying datastore objects.

Look out for errors during the execution of the DDL script. Do not assume that the DDL script execution has worked. Consider synchronizing actions with DBA turnaround times for running scripts. Response may vary.

Executed under SQL*PLUS, the script creates a log file, and aborts on error. Always check the output.

Be careful when creating scripts not to overwrite or confuse two files with the same name. Best practice is to rename scripts and retain them in case you have issues for Customer Support.

Do not execute the same script twice without seeking advice from Customer Support.

Create a Contributor ApplicationThese are the steps you typically perform when create an application in a lockdown environment.

❑ Generate a Create Application script (script.sql) in the Contributor Administration Console.

❑ Modify and run the script.sql.

❑ Add the application to the Contributor Administration Console.

❑ Configure the Contributor application, as required.

❑ Configure the dimensions for publish if creating a Publish View layout.

❑ Run the Go to Production process.

❑ Configure publish, and if creating a Table-only layout, the dimensions for publish.

❑ Click Generate synchronization script for datastore to generate a publish script.

❑ Run the publish script (Publish script.sql).

Add, Edit, and Delete D-List or D-CubeThese are the steps you typically perform when modifying Cognos Planning objects in a lockdown environment.

❑ Make a change to the Analyst model, such as deleting a D-Cube.

❑ In the Contributor Administration Console, synchronize with Analyst and generate a synchronization script.

❑ Run the synchronization script.

❑ Configure the dimensions for publish if creating a View layout.

❑ Run Go to Production.

❑ Configure publish, and if creating a Table-only layout, the dimensions for publish.

❑ Generate the publish script.

❑ Run the publish script.

No Change in Model, but Change in Dimension for Publish for View Publish Layout

These are the steps you typically perform when modifying dimensions for publish for the view publish layout in a lockdown environment.

❑ Configure the dimension for publish.

❑ Run Go to Production.

❑ Generate the publish script.

22 Cognos Planning


❑ Run the publish script.

For more information about publishing, see "Publish Datastores" (p. 25).

Changing the DDL ScriptWhen changing the script.sql generated by the Contributor Administration Console, take care not to make invalid changes.

Unacceptable ChangesThe following changes must NOT be made to the DDL script:• Change the first level qualifier (the application name).

Care should be taken to specify the correct string (subject to it conforming to SQL1992 standards) within the Contributor Administration Console Create Application wizard. That name will then appear within the resulting DDL script file.

• Change table or column names. Dynamic tables have the correct name based on the model definition. If you change the table or column names then the Contributor Administration Console attempts to change them back at the next possible opportunity. Doing so may prevent the Contributor application from functioning.

Acceptable ChangesThe following changes can be made to the DDL script:• Assign datastore objects to tablespaces which conform to their own standards.• Add or amend storage clauses for capacity planning and to conform to local standards. • Add or remove instructions GRANTing privileges on the datastore objects created within the

script to relevant users/roles.



24 Cognos Planning

Chapter 4: Publish Datastores

The Cognos Planning - Contributor publish process extracts numeric and other values for the data from the compressed XML format in which it is stored, and writes it to conventional relational tables for viewing via ODBC links, or loading into a data warehouse. The publish process first writes to intermediate files and then loads the tables using SQL *Loader. The data is stored in tables named et_cubename. The publish function in Cognos Planning 7.3 allows datastore object creation to be controlled by the DBA using the generate scripts option (p. 21). The publish process first creates a script to create the necessary tables. When these tables are created, publish can proceed as before using the Contributor Administration Console. For subsequent publishes, the Contributor Administration Console determines if the objects are the same or if changes are required. If changes are required, a script is created that must be run to drop and/or create the tables in question at the time of publish. Then the publish proceeds as usual from the Contributor Administration Console. If no changes are needed, no DBA intervention is needed because the tables are truncated and repopulated. You can also publish using a Contributor Macro.

There are two types of publish layout:• The table-only layout gives users greater flexibility in reporting on Cognos Planning data. The

table-only layout can also be used as a data source for other applications. This layout is required by the Generate ReportNet Model extension.

• The view layout generates views in addition to the export tables. This layout is required for the Publish to PowerPlay Enterprise Server, Publish to Cognos Metrics Manager, and Publish to Impromptu extensions.

For more information about extensions, see the Contributor Administration Guide.

Publishing to a Different DatastoreYou cannot publish to the application container because the application container holds the transactional planning data in compact XML binary large object (BLOB) format, and must be backed up on a regular schedule based on the life cycle of the transactional application. Instead you must publish to a separate publish container. The publish container contains a snapshot of the planning data in relational form, which is a different life cycle and contains a significantly different storage and performance profile. By having separate publish containers, you can make use of dedicated job servers for publish datastores. The two available publish layouts cannot coexist in a single datastore container.

The publish datastore container is configured in the Contributor Administration Console. The connection is stored in the binary format in the CONTAINERCONNECTION table so the user name and password cannot be seen even via a SQL SELECT statement or utility. The primary benefits of this feature are: • This data does not typically need to be backed up because it can be re-created using the

publish process.• The instance can run in NOARCHIVELOG mode for increased performance.• The archive destination can be cleaned out less frequently.• If a reporting tool is running resource intensive queries on these tables while other processing

is occurring on another application, both applications would see performance decline.

For Oracle, you can place the publish tables in a NOLOGGING tablespace (or set the tables to NOLOGGING); however, redo is still generated for the index on each table.

Steps1. In the Production application, click Publish, and click either Table-only Layout or View

Layout depending on the type of publish container you require.



2. Click the Options tab, and then click the Configure button.3. Select the datastore server where you want to create the publish container.4. Click Create New.5. Click the button next to the Name box.6. Complete the New publish container dialog box:

7. If you have an Oracle and DB2 UDB application, click Tablespace. and then specify the following configuration options:• Tablespace used for data• Tablespace used for indexes• Tablespace used for blobsNote that custom temp tablespaces are supported for Oracle only.

8. Click Create.The publish container must be added to a job server or job server cluster so that the publish jobs are processed.

The Table-Only Publish LayoutThe table-only publish layout• generates data columns in their native order, which preserves the original order when

reporting, as when you publish to a view layout • publishes detail plan data• selects whether to prefix the dimension for publish column names with their data type to

avoid reserved name conflicts

When using the Generate ReportNet Model extension, the table-only publish layout must be used.

The following types of tables are created when you publish using the table-only layout.

Application Name Type a name for the publish datastore. We recommend that you use the name of the current application and append to it a suffix, such as, _view for a view layout, or _table for a table-only layout.

Location of datastore files

Enter an existing location for the datastore files on the datastore server. Required only by SQL Server applications.

Table type Description Prefix or name

Items (p. 27) Describes the D-List items. it_

Hierarchy (p. 28) Contains the hierarchy information derived from the D-list, which is published to two associated tables.

sy_ for the simple hierarchycy_ for the calculated hierarchy.

Export (p. 30) Contains published D-Cube data. et_

Annotation (p. 31) Contains annotations, if the option to publish annotations is selected.

an_ for cell and audit annotationsannotationobject for tab (cube) and model annotations

26 Cognos Planning


Datastore Object NamesDatastore object names are derived from the Planning object names. The maximum length of table and column names are as follows.

Names cannot begin with a number or underscore (_), and can include the following characters:• A through Z and a through z• 0 through 9• @, #, $, and _ (underscore)

Items Tables for the Table-only Publish LayoutOne items table is created for each D-List. It contains one row per item. The name of the table is generated from that of the D-List and the prefix it_.

Metadata (p. 31) Contains metadata about the publish tables.

applicationcolumnappcolumntypeappobjecttypeapplicationobjectdimensionformats

Common (p. 33) Contains tables used to track when major events occurred in the publish container.

admineventadminhistorycontaineroption

Job (p. 33) Contains tables with information relating to jobs.

jobjobitemjobitemstatetypejobstatetypejobtaskjobtype

Object locking (p. 34)

A table used to lock objects in the system when they are being processed.

objectlock

Publish parameter publishparameter

Type of NameMicrosoft SQL Server IBM DB2 UDB Oracle

Column 128 30 30

Table 128 128 30

Table type Description Prefix or name



The items tables have the following columns.

Hierarchy Tables for the Table-only Publish LayoutThe complete hierarchies are published to the cy tables while the simple summary hierarchies are available in the sy_ tables. These tables all have the same format. They contain the following columns for each level of the hierarchy.

Simple hierarchy tables are created by the publish table-only layout. They are intended to be used when there are simple parent-child relationships between D-List items that can be summed. The purpose of this is to allow a reporting tool to automatically generate summaries for each hierarchy level, or for use with applications that do not require precalculated data, such as a staging source for a data warehouse.

In the following examples, D-List items are represented by letters, and the relationships between items are drawn as lines.

Parent D-List items are calculated from child D-List item dependencies. Leaf D-List items do not have child D-List item dependencies.

All D-List items have their values shown in simple parenthesis and in addition, leaf D-List item codes are shown in curly braces.

Column Description

itemid Unique Identifier for the item

dimensionid Unique identifier for the D-List

itemname Name of the Item

displayname Display name of the item

disporder Display order specified in Analyst, which is zero-based

itemiid D-List integer identifier for the item, which is used as the primary key

Column Description

levelLevelNumber_guid Globally unique identifier of the item

levelLevelNumber_iid D-List integer that identifies the item

levelLevelNumber_name Item name

levelLevelNumber_displayname Item display name

levelLevelNumber_order Item order in the hierarchy

D-List Value Description

0 Direct child of a simple sum D-List item.

1 The leaf has multiple parents.

2 The leaf item is part of a sub-hierarchy that has been moved to the root (no parent).

3 The leaf item is an orphan.

28 Cognos Planning


Example 1 - Simple Summaries

The left pane is an example of simple hierarchies with values. The right pane is an example of simple hierarchies with values and leaf D-List item codes.

Example 2 - Leaf D-List Item with Multiple Parents

In the left pane, [E] has more than one parent, so parentage is assigned to the first parent in the IID order. In the right pane, [D] becomes a leaf D-List item, and [F] becomes orphaned and is moved to the root in the right pane.

Example 3 - Non-Simple Summaries

In the left pane, [P] is the product of [S] and [T]. Leaf D-List items of non-simple summaries get moved to the root. In the right pane, [P] became a leaf D-List item, [S] and {T] were orphaned and moved to the root in the right pane.



Example 4 - Sub-Hierarchy of Non-Simple Summary

In the left pane, [B] is the product of [C] and [E]. [C] has its own simple summary hierarchy. Because non-simple sums are not included in the hierarchy, in the right pane, [B] becomes a leaf, [E] and [C] become orphaned and moved to the root, and [C] keeps its sub-hierarchy because it is a simple sum.

Export Tables For the Table-only Publish LayoutCell data for the selected cubes is published to the export tables.

If you select the Include Roll Ups option, the export tables contain all the data, including calculated data.

If you do not select this item, the export tables contain only non-calculated fact data.

Users who report against published data that contains only fact data use the reporting tool to aggregate the calculated items when grouping with the hierarchical dimensions.

You can control how the export tables (prefix et_) are generated as follows. • Publish only uniform cube data. Select the Create Columns With Data Types Based on the

Dimension for Publish option, the data type of each item of the Dimension for publish is used for the columns of the export tables. If individual cell types differ from that of the corresponding columns, the corresponding cell data is not published and an informative message appears.

• Select only data of the specified types. When more than one data type is selected, multiple columns appear for each item in the export tables, one column per data type. For example, if both numeric data and dates are selected, two columns are created per item in the dimension for publish.

• Include the original formatted numeric and date values, which are stored in the text column. This is useful when the original format cannot be easily reproduced in the reporting tool application.

• Publish entire cubes, or publish only leaf data and let the reporting engine perform the rollups. In this way, you control the level of detail of the information to publish. The summary hierarchy as specified in the sy_ tables must be used to perform the rollups. Leaf cells are those that correspond to leaf items of the simple summary hierarchies.

Data Types Used to Publish DataThe following data types are used for publishing data.

Data type MS SQLServer IBM DB2 UDB Oracle

TEXT VARCHAR(8000) CLOB VARCHAR2(4000)

DATE datetime date timestamp

DOUBLE float float float

INTEGER integer int NUMBER(10)

30 Cognos Planning


The prefixes text_, date_, and float_ are used to identify the data types of columns in tables, and the suffix _[count] is used to guarantee name uniqueness.

Annotations Tables for the Table-only Publish LayoutYou can choose to publish user and audit annotations.

Cell and audit annotations are published to the an_cubename table.

Tab and model annotations are published in the annotationobject table.

The an_cubename TableThe columns of the an_cubename table are as follows:

The annotationobject TableThe columns of the an_cubename table are as follows.

Metadata TablesMetadata about the publish tables is maintained in several tables.

The applicationobject TableThe description of each database object created during a publish operation is maintained in applicationobject. The columns of the applicationobject table are as follows.

Column Dimension

HierarchyDimensionName The unique identifier (p. 27) of the e.List items for the coordinates of the cell annotations.

Dimension_DimensionName The unique identifier of the D-List items for the coordinates of the cell annotations.

MeasureDimensionItemName_user_id

The last user who updated the annotation.

DimensionItemName_date The last date the annotation was updated.

DimensionItemName_annotation For a cell annotation, the text of the annotation.

For an audit annotation, the details of the action performed. The text is prefixed with Audit annotation on... followed by the action.

DimensionItemName_value The cell value at the time of the annotation.

Column Dimension

object_id The identifier of the cube or model being annotated.

node_id The e.List item identifier.

user_id The user id of the person who created the annotation.

annotation_date The date and time the annotation was made.

annotation The text of the annotation.

Column Description

objectname Name of the object.



The applicationcolumn TableThe columns of the applicationcolumn table are as follows.

The appcolumntype TableThe types of tables that can exist in Contributor.

The appobjecttype TableThe types of application object that exist.

The dimensionformats TableThe dimensionformats table formatting information for the items of the dimension for publish that is compatible with Cognos ReportNet.

displayname Display name of the associated Planning object.

objectid A globally unique reference (GUID) for the object.

objecttypeid The type of object, for example, EXPORT_TABLE, DIMENSION_SIMP_HIER

datastoretypeid Describes the datastore type: Table.

objectversion This is an internal version number used for debugging.

Column Description

objectname Name of the object.

columnname Name of the column.

displayname Display name of the associated Planning object.

columnid A globally unique reference (GUID) for the object.

objecttypeid Type of Planning object, such as, EXPORT_TABLE, DIMENSION_ITEMS, DIMENSION_SIMP_HIER

columntypeid -

columnorder The order in which the column appears.

logicaldatatype The type of data, such as, epGUID, epTextID

Column Description

objecttypeid The object type, such as a FACT_VIEW

columntypeid -

description A description of the object type

Column Description

objecttypeid The object type, such as ANNOTATION_OBJECT

description A description of the object type

Column Description

32 Cognos Planning


The columns of the dimensionformats table are as follows.

Common TablesCommon tables are created so that you can track the history of events in the publish container.

The adminhistory table stores information about when major events occurred to the publish container.

The adminevents table contains the IDs and descriptions of the event types used in the adminhistory table.

The containeroption table is used for Oracle and DB2 to store tablespace information for blob, data, and index.

Job TablesThe following tables are created to support jobs.

Parameters and failurenotes in Job tables are stored as XML LOBs.

Column Description

dimensionid Globally unique identifier of the dimension for publish

itemguid Globally unique identifier of the item of the dimension for publish

formattype One of percent, number, or date

negativesignsymbol String indicating how negative values must be reported

noofdecimalplaces Number of decimal places for numerical values

scalingfactor Integer for the scaling factor of numerical values

zerovaluechars Characters to use for zero of blank value

Table Description

job Information about the jobs that are running or ran in the application. This information is used in the Job Management screen.

jobitem Each Job Item is represented by a row in the jobitem table. The state of the Job Item is also stored. If a problem occurred while running the Job Item, descriptive text is stored in the failurenote column and is appended to the failurenote column for the job.

jobitemstatetype Job item status types: failed, ready, running, succeeded.

jobstatetype Job status types: canceled, complete, creating, queued, ready, running.

jobtask Where and when the job items ran and the security context it used.

jobtype Job types and their implementation program IDs.



The objectlock TableThe objectlock table supports macros, administration links, and the export queue. It locks objects in the system when they are being processed and contains information about the objects being worked on.

The View Publish LayoutThe view publish layout is used with the following extensions:• Publish to PowerPlay Enterprise Server • Publish to Cognos Metrics Manager• Publish to Impromptu extensions

The following types of publish tables are created when you publish using the view layout.

Database Object NamesDatabase object names are limited to 18 lowercase characters, and are derived from the Cognos Planning object names.

Items Tables for the View Publish LayoutOne items table is created for each D-List. It contains one row per item. The name of the table is generated from that of the D-List and the prefix it_.

Table type Description Prefix or Name

Items (p. 34) Describes the D-List items. it_

Hierarchy (p. 35) Used by reporting tools. The depth of each item in the dimension hierarchy is recorded and display information.

hy_cy_ (calculation hierarchy tables)

Export (p. 35) Contains published D-Cube data et_

Annotation (p. 35) Contains annotations, if the option to publish annotations is selected

an_ for cell and audit annotationsannotationobject for tab (cube) and model annotations

Metadata Contains metadata about the tables. applicationcolumnappcolumntypeappobjecttypeapplicationobjectsannotationobject

Common Contains tables used to track when major events occurred in the publish container.

admineventadminhistorycontaineroption

Job Contains tables with information relating to jobs.

jobjobitemjobitemstatetypejobstatetypejobtaskjobtypeobjectlock

34 Cognos Planning


The items tables have the following columns.

Hierarchy Tables for the View Publish LayoutThere is no model construct for specifying items hierarchies. Instead, hierarchies are derived from user specified equations.

Two types of hierarchies are currently supported; complete hierarchies and simple summary hierarchies.

Complete hierarchies are used to produce reports on the entire contents of cubes. Complete hierarchies are used to organize cube data and are not used to perform rollups and calculations in the reporting engine. The rules that govern the generation of complete hierarchies in the cy_ tables are as follows:• The parent of a given item is the first simple sum that references the item.• If this sum does not exist, it is the first non-sum calculation that references the item.• If neither exists, the item is a top-level item.

Simple summary hierarchies are used when only detail items are published and rollups are performed from the reporting engine. The rules that govern the generation of these hierarchies are as follows:• The parent of a given item is the first simple sum that references it.• If there are there are multiple candidates for the parent of an item, it is assigned to the first

parent in iid order and the other candidate parents are considered to be detail items in the hierarchy.

• In the case where a parent cannot be identified that way and the item is not a simple sum, it is considered to be a root item.

Simple summary hierarchies are not necessarily complete because all items that are part of a D-List may not necessarily be part of the hierarchy.

The starting point for the production of these hierarchies is the graph of items dependencies produced when equations are parsed. This graph specifies all parent/child relationships between items. Because the simple summary hierarchy is limited to simple sums, sub-hierarchies can be detached from the main hierarchy and moved to the top.

Export Tables for the View Publish LayoutCell data for the selected cubes are published to the et_ tables, one row per cell. These tables contain the coordinate for each cell of the cube and the corresponding cell value. One column per D-List stores the item GUID along that dimension. An additional column stores the cell value (published as a blob or varchar depending on the target DBMS). In Cognos Planning, a cell value can contain a date, a double, or text.

Annotation Tables for the View Publish LayoutYou can choose to publish user and audit annotations.

Cell and audit annotations are published to the an_cubename table.

Tab and model annotations are published to the annotationobject table.

Column Description

itemid Unique Identifier for the item

dimensionid Unique identifier for the D-List

itemname Name of the Item

displayname Display name of the item

disporder Display order specified in Analyst, which is zero-based



The an_cubename View Layout TableThe columns of the an_cubename table are as follows.

The annotationobject View Layout TableThe columns of the annotationobject table are as follows.

ViewsThe following views are created in a view publish layout.

An ev_view is created to provide a more user-friendly access to its associated export table (et_table), which contains cube data. In this view, GUIDs are simply replaced by the display name associated with the D-List items, and export value are cast to varchar when published as blobs.

A fact view (with fv_prefix) is created for each cube being published and is limited to numeric values by joining the export values from the et_ table to the items in the hy_ tables for the cube.

Column Dimension

Dimension_DimensionName The unique identifier of the D-List items for the coordinates of the cell annotations.

HierarchyDimensionName The name of the e.List.

annotation_user_gu The globally unique identifier of the last user who updated the annotation.

annotation_date The last date the annotation was updated.

annotation_cell_va The cell value at the time of the annotation.

annotation_is_edit Whether the annotation is editable (0 = no, 1 =yes)

Column Dimension

objectguid The globally unique identifier (GUID) of the cube or model being annotated.

node_id The GUID of e.List item being annotated.

user_id The GUID of the user class that annotated.

annotation_date The date and time the annotation was made.

annotation The text of the annotation.

View name Description

fv_cubename A view on the cell data for a cube that resolves the star schema linking to the flattened out hierarchy for a dimension.

ev_cubename A view on the cell data for a cube that resolves the star schema linking to the items in a dimension.

av_cubename A view on the cell annotations table for a cube that resolves the star schema.

cv_cubename A complete view created for each cube being published.

36 Cognos Planning


A complete view (with cv_prefix) is created for each cube being published and is built by joining the export values from the et_ table to the items in the cy_ tables for the cube.



38 Cognos Planning

Chapter 5: Oracle Datastores

The implementation of a Cognos Planning - Contributor datastore is datastore specific.

Prior to creating a Contributor application using Oracle, create the Oracle datastore with the sizing recommendations (p. 42) and primary login (p. 40) described in this document.

Prepare the Contributor Oracle datastore by deploying the correct Oracle Client tools, applying the appropriate security scenario, and ensuring adequate datastore size for the Contributor application. Maintain the Contributor Oracle datastore by fine-tuning settings for better performance and performing regular backups.

The following table conveys the database terminology used throughout this section and the Oracle equivalent.

Note: In Contributor, application also refers to an Analyst plan that is made available to users on the Web through the Contributor Administration Console. A Contributor application consists of a series of linked cubes that can be used for data entry by many people at the same time.

Oracle Client ToolsOracle client tools are required on all Contributor servers to allow communication to the Oracle server. For information about Oracle Client/Server interoperability support, see document #207303, available from the http://metalink.oracle.com Web site.

Following these recommendations will help you avoid several known problems, primarily COM+ hangs and memory leaks and the issue documented in Oracle bug #3394730.

We recommend that you deploy the following Oracle client tools.• Oracle 9.2.0.1 client tools• Oracle 9.2.0.6 RDBMS Patch to be applied to the Oracle clients (Oracle patch number

3948480)• Oracle 9.2.0.4 OLE DB Patch (Oracle Patch number 3262468)• Oracle Patch Set 3557062

We recommend one of the following client tool and server configurations:• 9.2 client with 10g server• 9.2 client with 9.2 server• 10g client with 10g server

To connect to Oracle, we recommend that you use tnsnames rather than Onames, according to the information in Oracle bug #3209536. Switching to tnsnames avoids intermittent COM+ hanging issues on the Contributor server. Additionally, please see Oracle document # 308804.1 and implement the workaround to avoid memory leaks due to Oracle bug #4234138.

Note that Contributor Publish Table Layout uses a data type that is not supported in Oracle 8.1, for more information, see bug #483808.

Cognos Planning terminology Oracle equivalent

Application Datastore owner or schema.

Datastore Oracle instance. It maps exactly to the TNS Connect String.



Securing the Oracle DatastoreThe Contributor Oracle datastore scenario offers two levels of security through the following administrative users: COGNOSEP and LOCKDOWN. The COGNOSEP user has high-level privileges. You can create, and if allowed, drop applications through the Contributor Administration Console. The LOCKDOWN user provides tighter security.

Create the COGNOSEP UserThe COGNOSEP user enables the user to log in, create, and maintain any applications within that datastore.

To create the COGNOSEP user, do the following.• Run the following SQL:

create user COGNOSEP identified by COGNOSEPdefault tablespace usersquota unlimited on userstemporary tablespace tempquota unlimited on temp;

GRANTCREATE SESSION,CREATE USER,CREATE ANY INDEX,CREATE ANY SEQUENCE,CREATE ANY SYNONYM,CREATE ANY TABLE,CREATE ANY TRIGGER,CREATE ANY VIEW,DELETE ANY TABLE,INSERT ANY TABLE,UPDATE ANY TABLE,SELECT ANY TABLE,DROP ANY VIEW,DROP ANY TABLE /* required to truncate tables */,EXP_FULL_DATABASE /* Optional if backup via Administration Console is desired */,GRANT DROP USER /* Optional for ability to drop applications, or DBA can drop user*/TO COGNOSEP;

Create the LOCKDOWN UserThe lockdown environment minimizes security concerns and replaces the datastore schema environment used in Cognos Planning version 7.2. The schema environment is no longer valid with the introduction of system links and mandatory alternate publish datastores. The lockdown environment requires script generation for DDL operations, which must be run by a DBA. Rather than connecting to each application through a unique datastore, as with the schema environment, the lockdown environment allows the LOCKDOWN user to connect to and administer all applications, the Planning Administration Domain, and publish datastores. The LOCKDOWN user's privileges are restricted to the object level (delete, insert, select, update) for all Contributor datastores. This alleviates the security concerns related to the DROP ANY TABLE system privilege with the COGNOSEP user.

The following steps describe how to create the LOCKDOWN user, and how to generate scripts to create the Planning Administration Domain, Contributor applications, and publish containers. The scripts must be run by a DBA.

Steps1. Create the LOCKDOWN user by running the following SQL query:

create user LOCKDOWN identified by LOCKDOWNdefault tablespace usersquota unlimited on users

40 Cognos Planning


temporary tablespace temp;

GRANT CREATE SESSION to lockdown;

2. Edit the following files on each Contributor server:• epEAdminORA8Resources.xml

Replace "truncate table" with "delete from". Because there is no DROP ANY TABLE privilege, the LOCKDOWN user must delete all rows in a table rather than truncating when all rows must be removed. This impacts performance because deleting is slower than truncating.

• epSQLDDLORA8Resources.xmlReplace "--GRANT SELECT, INSERT, UPDATE, DELETE ON %1 TO "EP_DMLUSER"" with "GRANT SELECT, INSERT, UPDATE, DELETE ON %1 TO LOCKDOWN;". This allows all generated scripts to include the necessary object permission grants.

3. If datastore backups from the Contributor Administration Console are required, grant the EXP_FULL_DATABASE role to the LOCKDOWN user.

4. In the Contributor Administration Console, create the Planning Administration Domain script using the Planning Administration Domain Creation wizard. The wizard appears the first time the Contributor Administration Console is run on a computer. Alternatively, select Tools, Create Planning Administration Domain. In the Planning Administration Domain Configuration options screen, select Generate datastore scripts and data files.

5. Run the script.The LOCKDOWN user can now be used in the Contributor Administration Console.

6. In the Contributor Administration Console, select Tools, click Change Planning Administration Domain and select the Planning Administration Domain that was created.

7. In the Contributor Administration Console, under the appropriate datastore server, right-click Applications, and click Create Applications. Follow the wizard and on the Application Details screen, select Generate datastore scripts and data files, and complete the wizard. This creates an application script.

8. Run the application script. 9. In the Contributor Administration Console, select the appropriate datastore server, right-click

Applications, click Link to Existing Applications, and select the application that was created.10. Configure the Contributor Application as required. For more information, see the

Contributor Administration Guide.11. In the Contributor Administration Console, set the Generate Scripts option to Yes in

Development, Application Maintenance, Admin Options.12. If using Table-only Layout publish, in Application Maintenance, Dimensions for Publish,

select the required data dimension for publish.13. Generate the production version of the Contributor application by running Go to Production.14. In the Contributor Administration Console, in the Contributor application, click Production,

Publish, and either Table-only Layout, or View Layout as required.15. Select the cubes, dimensions for publish if using View Layout, e.List items and all options

except for the Publish datastore. 16. In the Options screen, click Configure. 17. Select the datastore server where the publish container will be held and click Create New.18. Click the Create a New Publish Container button and type the name of the publish container,

and location of datastore files. 19. Click Test Connection, and OK twice to return to the Options screen.20. Click Generate synchronization script for datastore.21. Run this script to make the required changes.22. For pre-existing datastores, grant the LOCKDOWN user the following permissions for all

objects in the datastore: select, insert, delete, and update.

The LOCKDOWN user can now link to all the applications.



Administering the Secured DatastoreThere are a number of SQL queries that can be run to perform some DBA administration tasks.

Show the Applications that a User has Permissions to SelectThe following SQL query creates a view to show the user applications that are on the particular database that the user has permission to select.

create or replace view applicationsas select owner, tablespace_namefrom all_tableswhere table_name = 'APPLICATIONOBJECT';-- optional, but helpfulgrant select on applications to public;create public synonym applications for applications;

Show Detailed Application InformationThe following SQL query shows the application’s size, creation date, and default tablespace.

create or replace view applications_detail asselect owner,round(sum(bytes)/1048576) MB, u.created, u.default_tablespace as default_tsfrom dba_segments s, dba_users uwhere owner=usernameand owner in (select owner from applications)group by owner, created,u.default_tablespaceorder by 2 desc;

Differentiate Cognos Planning Application VersionsThe following SQL query differentiates Cognos Planning 7.2 applications from Cognos Planning 7.3 applications:

select optionvalue AS DB_VERSION from <application_name>.adminoption where optionid='DB_VERSION'

Cognos Planning 7.2 applications return a value of 3.

Cognos Planning 7.3 applications return a value of 4. This represents a new naming convention for the Contributor database version, separate from the Contributor version.

Sizing Oracle TablespacesWith the release of Cognos Planning version 7.3, the administrator can specify some tablespaces. The default for tablespaces is USERS for data and blobs, and INDX for indexes. If using Oracle 10g, either the INDX tablespace must be created manually as it is no longer created by default, or one of the following tablespaces must be used: • Data• Indexes• BLOBs• Temp

You can add four more tablespaces by publishing to a different datastore. The minimum tablespace required is 500 MB in the USERS tablespace (the default). Actual space required is dependent on the size of your organization's model. However, a typical datastore is between 3 and 10 GB per Cognos application.

The Redo LogWe recommend that you have four redo log groups with two members per group of 50-100MB each.

RollbackWe recommend 1 GB tablespace, 10 segments with 1MB initial and next, and 10 min_extents.

42 Cognos Planning


Default Storage Parameters Using Dictionary Managed TablespacesWe recommend 128 KB initial, 8 MB next extents, and a 0 pct_increase. This provides the most efficient use of disk and least number of extents per segment.

Locally Managed Tablespaces With Uniform Extent SizingWhen using locally managed tablespaces, take note of Oracle bug 3019979 (base bug 2944866).

We recommend the following uniform extent sizings.

The following are minimum recommended parameters (init.ora)for Oracle 8i:open_cursors = 300db_block_buffers = 5000 # with 8 KB db blocksshared_pool_size = 10,485,760log_buffer = 163,840sort_area_size = 16,384

The following are minimum recommended parameters (init.ora)for Oracle 9i/10gdb_cache_size = 100 MBshared_pool_size = 100 MBlog_buffer = 1 MB

Fine-tune Your Datastore for Better PerformancePerformance varies depending on your hardware, network and data size. You may find the best results experimenting with various settings. There is no loss or duplication of data by executing multiple sessions of SQL*Loader. If the load fails, re-executing it replaces it. For example, executing 10 loads does not multiply a value by 10 times.

Steps1. In the appropriate Contributor application, go to Development, Configuration, Application

Settings.

Application/ function ContentsUniform Extent Sizing

Application Data Default Data 128 KB

Application Index Default Index 128 KB

Application BLOB Default LOB 128 KB

BLOB_Large (manual) JOBITEM.DATANODESTATE.DATAXMLAPPLICATIONSTATE.DEFINITIONjOB.PARAMETERSIMPORTQUEUE.MIBNODELANGUAGEMODEL.DEFINITION

8 MB

Publish Data Default Publish Data 128 KB

Publish Index Default Publish Index 128 KB

Import/Publish_Data_Large (manual)

Table names: IM%, IE%, ET% 8 MB

Import/Publish_Index_Large (manual)

Indexes for Table names: IM%, IE%, ET% 8 MB



2. Customize the SQL*Loader command line variables in the PUBLISH_OPTIONS field.Increasing the bindsize to 2M-5M, or ROWS can be effective. Try using Direct_Path, but use with caution because this method builds the index after each session, and could cause index corruption due to the large number of SQL*Loader sessions.

Rename an ApplicationYou clone an application/schema to rename it. You can also use the Import/Upgrade function in the Contributor Administration Console to do this. Either method is acceptable. For more information about upgrading, see the Contributor Administration Guide.

Steps1. Export the schema.2. Create a new Oracle user.3. Import the schema, using FROMUSER=SOURCE_NAME TOUSER=TARGET_NAME (the

new Oracle user).4. Edit and recompile the triggers for the target_name, as the source_name is hard coded in the

DDL. Use either a reverse-engineering pl/sql tool, or dba_triggers (columns: description and trigger_body) to get the create statements.

5. Run Go To Production in the Contributor Administration Console.

44 Cognos Planning

Index

Aaccess to data, 14an_cubename table, 31annotation tables

table-only layout, 31view layout, 35

annotationobject Tabletable-only layout, 31

annotationobject view layout table, 36appcolumntype table, 32application datastore, 10applicationcolumn table, 32applicationobject table, 32appobjecttype table, 32

Bbackup, 19

Cchanging the Analyst model, 17cloning, 44Common datastore, 9common tables

table-only layout, 33Contributor application

creating, 13Contributor datastore, 7Contributor Datastore Objects, 8copy data, 15copyright, 2

Ddata types, 30datastore object names

table-only publish, 27datastore objects, 8DDL, modifying, 23development_items table, 14dimensionformats table, 33document

version, 2dynamic datastore objects, 8

Eexport tables

view layout, 35export tables, table-only layout, 30

GGo to Production, 16

Hhierarchy tables


Iimporting data, 15initial data, loading, 14items tables


Jjob, 17, 33job tables

table-only layout, 33jobitem, 33jobitemstatetype, 33jobstatetype, 33jobtask, 33jobtype, 33

Llarge object types, 10load data, 15LOBs, 10lockdown environment, 13

Mmetadata, 7metadata tables, 31

Nnaming conventions, 7

Oobject lock table, 34objectlock table, 34open environment, 14Oracle

security, 40sizing, 42version and license requirements, 5

Oracle client tools, 39


Index

PPAD, 9performance, 43Planning Administration Domain, 9prepare data, 15publish containers, 10publish data, 17

applicationobject table, 32views, 36

publishing to a different datastore, 25

Rrecovery, 19redo, 42

Sscript.sql, 13security

administration, 42CONGOSEP, 40lockdown, 40

sizing datastore tablespaces, 10SQL1992 compliant, 7static datastore objects, 8storing data, 17synchronization, 17

Ttable-only layout

annotation tables, 31appcolumn table, 32applicationcolumn table, 32appobject table, 32common tables, 33data types, 30dimensionformats table, 33export table, 30hierachy tables, 28items tables, 27metadata tables, 31

tablespace management, 11tablespaces, sizing, 10

Uuser access to data, 14

Vversion

document, 2views, 36

46 Cognos Planning

Documents

Cognos Planning Guide