COGNOS (R) ENTERPRISE PLANNING SERIES

2 Product Information This 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 ( Copyright Copyright (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 , or subparagraphs (C) (1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR , as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 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

3 Table of Contents Introduction 5 Chapter 1: The Contributor Datastore 7 Contributor Datastore Objects 8 Static and Dynamic Datastore Objects 8 The Planning Administration Domain Datastore and the Common Datastore 9 The Application Datastore 10 Publish Containers 10 Sizing Tablespaces 10 Tablespace Management 11 Chapter 2: Working with Contributor Applications 13 Creating a Contributor Application 13 Assigning User Access to Data 14 Importing Data into the Contributor Application 15 Go to Production 16 Maintaining the Contributor Application 16 Storing User Data 17 Getting Data Out of the Plan 17 Making Changes to the Model 17 Types of Jobs 17 Backup and Recovery 19 Chapter 3: Datastore Security 21 Generating Scripts 21 Create a Contributor Application 22 Add, Edit, and Delete D-List or D-Cube 22 No Change in Model, but Change in Dimension for Publish for View Publish Layout 22 Changing the DDL Script 23 Chapter 4: Publish Datastores 25 Publishing to a Different Datastore 25 The Table-Only Publish Layout 26 Items Tables for the Table-only Publish Layout 27 Hierarchy Tables for the Table-only Publish Layout 28 Export Tables For the Table-only Publish Layout 30 Annotations Tables for the Table-only Publish Layout 31 Metadata Tables 31 Common Tables 33 Job Tables 33 The objectlock Table 34 The View Publish Layout 34 Items Tables for the View Publish Layout 34 Hierarchy Tables for the View Publish Layout 35 Export Tables for the View Publish Layout 35 Annotation Tables for the View Publish Layout 35 Views 36 Chapter 5: Oracle Datastores 39 Oracle Client Tools 39 Securing the Oracle Datastore 40 Create the COGNOSEP User 40 Database Administrator (DBA) Guide 3

4 Create the LOCKDOWN User 40 Administering the Secured Datastore 42 Sizing Oracle Tablespaces 42 Locally Managed Tablespaces With Uniform Extent Sizing 43 Fine-tune Your Datastore for Better Performance 43 Rename an Application 44 Index 45 4 Cognos Planning

5 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 - Analyst Analyst 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 - Contributor Contributor 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 ( Version and License Requirements With Oracle Cognos supports Oracle Enterprise Edition version and later, (excluding ). 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 Information The following documents contain related information, and may be referred to in this document. Document Analyst and Manager User Guide Contributor Administration Guide Cognos Planning New Features Guide Cognos Planning Best Practice Guide Description Using Analyst to create planning models Creating and administering Contributor applications Describing features that are new in Cognos Planning 7.3. 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. Database Administrator (DBA) Guide 5

6 Introduction Document Get Data User Guide Access Manager Administrator Guide Description Using Contributor Get Data to load data into Contributor Configuring security information Our documentation includes user guides, tutorial guides, reference books, and other materials to meet the needs of our varied audience. Online Help Some 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 Printing Cognos 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. 6 Cognos Planning

7 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. RDBMS Oracle Microsoft SQL Server DB2 UDB Contributor datastore User schema Database Schema Naming Conventions The 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. Metadata Contributor 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. Database Administrator (DBA) Guide 7

8 Chapter 1: The Contributor Datastore Contributor Datastore Objects The 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. PAD Common Planning Administration Domain (PAD) and common datastore Application A Application B Application C Application D application containers publish containers - star schemas Static and Dynamic Datastore Objects You 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. Datastore Object Static / dynamic Planning Administration Domain and common tables Planning Administration Datastore Application datastore static yes no no application tables static no yes no job tables static yes yes yes Publish datastore 8 Cognos Planning

9 Chapter 1: The Contributor Datastore Datastore Object Static / dynamic application configuration tables Planning Administration Datastore Application datastore static no yes no Publish datastore application metadata tables extension component tables static no yes yes static no yes no import tables dynamic no yes no publish tables and views dynamic no no yes 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. Database Administrator (DBA) Guide 9

10 Chapter 1: The Contributor 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 Datastore Publish Containers All 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. When 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 Tablespaces You 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 KB / 1024 = 14,702 KB Divide by 1,024 to get MB / 1024 = 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

11 Tablespace Management Chapter 1: The Contributor Datastore When 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. Database Administrator (DBA) Guide 11

12 Chapter 1: The Contributor Datastore 12 Cognos Planning

13 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 Application There 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 Environment A lockdown environment is one where only a DBA can execute DDL commands. Database Administrator (DBA) Guide 13

14 Chapter 2: Working with Contributor Applications 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 Environment In 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 Table The 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 Data At 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 Data Before 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 Data Access 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

15 Chapter 2: Working with Contributor Applications Importing Data into the Contributor Application The 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 Data The 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 Data You 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 Data The 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. Database Administrator (DBA) Guide 15

16 Chapter 2: Working with Contributor Applications Go to Production Data now exists in the importqueue table. The next step is to process it through the Go to Production process. The 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 Production The 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 Production Establishes 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 Application When 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

17 Storing User Data Chapter 2: Working with Contributor Applications When 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 Plan When 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 Model Types of Jobs The 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. A 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 Annotations tidy Description Deletes user annotations and audit annotations. Database Administrator (DBA) Guide 17

18 Chapter 2: Working with Contributor Applications Job type Cut-down models Cut-down tidy Export queue tidy Import queue tidy Inter-app links Language tidy Prepare import Publish Reconcile Reporting publish Validate users Description 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. Removes any cut-down models that are no longer required. Removes obsolete items from the export queue. Removes model import blocks from the import queue that are no longer required. Transfers data between applications. 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. Processes import data ready for reconciliation. Publishes the data to a view format. 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. Publishes the data to a table-only format. 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. Self Maintaining Jobs The 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 Jobs Some 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. 18 Cognos Planning

19 Chapter 2: Working with Contributor Applications Backup and Recovery The 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. Database Administrator (DBA) Guide 19

20 Chapter 2: Working with Contributor Applications 20 Cognos Planning

21 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). Privileges The 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 Scripts The 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. Database Administrator (DBA) Guide 21

22 Chapter 3: Datastore Security 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 Application These 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-Cube These 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

23 Chapter 3: Datastore Security Run the publish script. For more information about publishing, see "Publish Datastores" (p. 25). Changing the DDL Script When changing the script.sql generated by the Contributor Administration Console, take care not to make invalid changes. Unacceptable Changes The 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 Changes The 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. Database Administrator (DBA) Guide 23