Generating Models, Packages, and Report Templates

This section provides information about the workflow ofproduct name here BI, the prerequisites, and procedure for generating models, packages, and report templates (NoetixAnswers).

Workflow of product name here BI

The following diagram shows the workflow of product name here BI:

Prerequisites for Generating NoetixViews or Noetix Analytics Metadata

There are a few tasks that are required to be completed before running a generation.

• IBM Cognos Framework Manager is installed and configured for your target server.

• A data source must be manually created in IBM Cognos Connection for each Noetix data source prior to the initial generation. These data sources will be used for their respective generated query subjects. The data source name must correspond to the data source name specified in the model.xml file.

  • For NoetixViews you should create a single Oracle data source to connect to the NOETIX_SYS account.

  • For Noetix Analytics, a Cognos data source should be created for the Noetix Analytics Operational Data Source (ODS) and Data Mart (DM).

• For NoetixViews generations, ensure that the Answer Builder stage (Stage 5) of Insightsoftware NoetixViews Administrator (NoetixViews Administrator ) is run before each generation of product name here BI (Angles for Oracle-Generator). For more information, see the Insightsoftware NoetixViews Administrator Guide.

• For Noetix Analytics generations, the Active Metadata Repository (AMDR) must be populated.

• The “Populate Indexes and Constraints” feature in Noetix Analytics Metadata Manager should be executed to ensure that constraint and index metadata is synchronized with the objects in the data mart and Operational Data Store databases.

• For Noetix Analytics 5.1 - 5.1.1, the generator hookscripts that ship with Noetix Analytics in the Integration folder need to be executed during the generation process. Instructions on doing this can be found in the readme.txt file released with the hookscripts.

  NOTE: These hookscripts are no longer necessary in Noetix Analytics 5.2 and above.

• Columns of CLOB, BLOB, LONG, and RAW data type are not supported by IBM Cognos Framework Manager and therefore are suppressed by the Angles for Oracle-Generator. If you need to load such columns into your reporting layer, convert them to a data type that is supported by your business intelligence (BI) tool.

Configuring the Generator Debug Log

When the generator runs, it will by default write diagnostic information to a text file, debug.log, in the [Generator install folder]\logs folder.

The generator currently has settings for four levels of diagnostic information. In order of increasing verbosity, they are DEBUG, TRACE, VERBOSE, and ALL. DEBUG is the recommended default. You can control this setting by making changes to the log4net/root/level node in the NGCManager-log.config file, in the [Generator install folder] folder. Usually you will only modify this file if directed by Insightsoftware Support.

If you are using the command-line version of the generator, apply these changes to ngc-log.config instead.

Setting Up the Data Source in IBM Cognos Connection

Before running theproduct name here BI, a data source must be manually created in IBM Cognos Connection for each Noetix data source. These data sources will be used for their respective generated query subjects. The template model.xml will contain references to these data sources and the data source and connection names must match the existing objects in IBM Cognos Connection.

For NoetixViews, you should create a single data source, connection, and sign on using the “NOETIX_SYS” user account.

NOTE: The data source must be configured differently when using Global Extension. See “Row Level Data Security” for more information on configuring a data source to provide row level data security.

For Noetix Analytics, you should create two data sources, connections, and sign ons. One will be used for executing queries against the Data Mart and another for executing queries against the Operational Data Store.

IBM Cognos Connection includes a wizard for setting up the data source, connection, and sign on.

To set up a data source connection:

1. From the Launch menu, choose IBM Cognos Administration.

2. Click on the Configuration tab at the top.

3. Click on the Data Source Connections section on the left.

4. Click the New Data Source button at the upper right.

5. Enter a descriptive name for your data source and (optional) description/screen tip values and click Next.

6. Select your data source connection type and click Next.

   1. For NoetixViews choose Oracle.

   2. For Noetix Analytics choose Oracle or one of the three Microsoft SQL Server connection types depending on your ODS/DM database type.

7. Specify the connection details.

   1. For Oracle connections:

• Fill the SQL*Net connect string field with the Oracle TNS name (e.g. “tnsname.world”).

• Fill the User ID and Password fields with your NoetixViews NOETIX_SYS or Noetix Analytics ODS/DM or shared reporting user credentials.

2. For non-ODBC SQL Server connections:

• Fill the Server name field with the name of your SQL Server server (e.g. “server.domain.com”).

• Fill the Database name with the database containing your Noetix Analytics DM or ODS content (e.g. “NOETIXDM”).

• Fill the User ID and Password fields with the SQL Server account credentials for querying the ODS/DM content.

3. For ODBC SQL Server connections:

• Fill the ODBC data source field with the name specified in the IBM Cognos ODBC.ini file. See the associate IBM Cognos documentation for more details about this file.

• Fill the User ID and Password fields with the SQL Server account credentials for querying the ODS/DM content.

8. Click Finish.

About the Generation Steps

product name hereproduct name here BI, you can choose to perform one or all of the following steps:

• Validate metadata (Noetix Analytics only)

• Populate model

• Run custom scripts

• Create security roles

• Publish generated packages

• Generate NoetixAnswers (NoetixViews only)

Validating Metadata

The Validate metadata step is only available for Noetix Analytics generations. This step duplicates some of the validation functionality in Metadata Manager, but reads metadata specific to theproduct name here BI, and takes into account any generator hook scripts which may be in place.

The generator validates Noetix Analytics metadata by running a series of SQL queries embedded in the XML files found in the [Generator install folder]\Analytics Validation folder. If any of these queries returns one or more records, the generator will write detailed warning information and query results to the debug log in the [Generator install folder]\logs folder. It will then cancel all remaining steps in the execution plan.

You may extend this step by adding your own custom validation checks. For each custom check, create a new XML file in the[Generator install folder]\Analytics Validation folder, mirroring the structure of one of the existing XML files installed with the generator.

If the Validate metadata step fails in your environment, you will need to resolve the underlying issues using Metadata Manager or with the help of Insightsoftware Support before continuing.

NOTE: It is strongly recommended that you keep the Validate metadata option checked for all Noetix Analytics generations. Bypassing this step may lead to serious errors in generated Cognos models.

Populating Models

During the Populate model step, query subjects and packages are generated into the Cognos models saved to the Generated Models folder for later publishing.

Running Custom Scripts

During the Run custom scripts step, the custom action log scripts (XML files created by the IBM Cognos Framework Manager or manually edited using the Cognos SDK documentation and placed in the CognosActionLogCustomScripts folder) are run by the generator using the Cognos BmtScriptPlayer.exe utility to automatically apply changes to the individual generated model files. For more information about the custom scripts, see Adding and Running Custom Action Log Scripts in “Customizing Generated Models, Packages, and Report Templates.”

Creating Security Roles

During the Create security roles step, the security roles used to secure portions of the generated models are created/updated in the IBM Cognos Content Store under the Security Namespace specified.

Publishing Packages

During the Publish generated packages step, the previously generated Cognos models in the Generated Models folder are published to the IBM Cognos Content Store.

Generating NoetixAnswers

The Generate NoetixAnswers step is only available for NoetixViews generations. During this step, report templates are created in the Public folder in IBM Cognos Connection. These report templates utilize the query subjects in the packages that were published during the Publish generated packages step. They are meant to be a starting point for report authors when creating new reports against the NoetixViews-based packages.

The generated report templates are organized into folders by their associated organizational unit and NoetixViews role. The roles that were generated during the Populate model step are configured to provide access to the generated report templates as well. Users will automatically be given access to the NoetixAnswers report templates that are associated with the packages they have been granted.

NOTE: Generated report templates are not deleted during regeneration. If you need to remove previously generated report templates, simply delete these objects using IBM Cognos Connection.

Generating Models, Packages, and Report Templates

Generating Large Models or a Large Number of Models

Noetix continues to increase the breadth of reporting capabilities in NoetixViews and Noetix Analytics, which has a direct effect on Cognos model and report template generation times. As an example, NoetixViews 6.5 includes significantly improved List of Values (LoV) capabilities to improve the performance of parameter prompts in reports and dashboards built on NoetixViews. This significant increase in the number of LoVs available directly increases the amount of time required to generate Cognos models and packages.

Increased generation times can be mitigated in the following ways:

• Generate models for NoetixViews Global Extension instead of Standard or Cross-Operations: NoetixViews Standard and Cross-Operations creates one set of views for each organizational unit, such as an operating unit or general ledger. This results in a large number of models and packages in Cognos. NoetixViews Global Extension creates a single set views that can be used to report against all organizational units, which results in a significantly smaller number of models to generate and maintain.

• Generate and publish models iteratively: Instead of generating Cognos models and NoetixAnswers for all of the available NoetixViews roles at one time, perform this task iteratively. Cognos models and NoetixAnswers report templates can be generated in subsets in a phased roll out based on business requirements. This enables users to start reporting before the entire set of models and report templates is available.

• Suppress unneeded views before generating models: NoetixViews is designed to provide broad operational reporting coverage across a large number of Oracle E-Business Suite modules. Certain Noetix views may not be as useful to one organization as they are to another. Insightsoftware NoetixViews Workbench (NoetixViews Workbench), NoetixViews or Angles for Oracle-Generator hookscripts can be used to suppress any views that are deemed unnecessary, resulting in smaller models that require less time to generate.

• Suppress unneeded LoVs before generating models: Similarly, NoetixViews provides a broad set of List of Value views and mappings to ensure that parameter prompts perform well in many reporting scenarios. NoetixViews Workbench, NoetixViews or Angles for Oracle-Generator hookscripts can be used to suppress any LoV views or mappings that are deemed unnecessary, minimizing the amount of time required to generate models.

Performing the Generation

The initial generation of models and publishing of packages will normally be done using theproduct name here BI tool. This tool may also be used to create input scripts for later unattended regenerations with the ngc.exe command line utility.

To generate models, packages, and report templates:

1. Click Start > All Programs >product name here BI >product name here BI. The product name here BI tool is displayed with five tabs. The Execution Plan tab is displayed by default. This tab is used to specify the major steps of the generation.

   

2. On the Execution Plan page, provide the following information:

• In the Generation Target box, select IBM Cognos BI.

• In the Metadata Source box, select either NoetixViews or Noetix Analytics.

• Under Generator Steps, select the steps that should be performed during the generation. The following steps are available:

  • Validate metadata: Runs a series of validation checks against Noetix Analytics metadata before an actual Noetix Analytics generation begins. For more information, see Validating Metadata.

  • Populate model: Generates model files and updates role information in the IBM Cognos Content Store. For more information, see Populating Models.

  • Run custom scripts: Runs the custom action log scripts to automatically apply changes to a given generated model file. For more information, see Adding and Running Custom Action Log Scripts in “Customizing Generated Models, Packages, and Report Templates.”

  • Create security roles: Creates security roles in the IBM Cognos Content Store.

  • Publish generated packages: Publishes the generated models into the IBM Cognos Content Store.

    NOTE: If you have chosen just the Publish generated packages step, the Package Suffix box will be made unavailable on the Target Parameters tab. Packages will not be regenerated. Instead, the existing packages from the previous generation will be published.

  • Generate NoetixAnswers: Generates pre-built report templates for NoetixViews into the IBM Cognos Content Store. For more information, see Generating NoetixAnswers.

    NOTE: Report templates will only be generated for the packages that have been published to the IBM Cognos Content Store. Be sure to execute the Populate model and Publish generated packages steps before executing the Generate NoetixAnswers step.

3. Click the Source Parameters tab. This tab is used to specify the location of the NoetixViews or Noetix Analytics metadata that will be used as the source for the generation.

   1. If NoetixViews selected on the Execution Plan tab, specify the following information:

      

• User Name: Enter the name of the NoetixViews schema.

• Password: Enter the password of the user.

• TNS Name: Enter the Transparent Network Substrate name for the Oracle instance that contains the NoetixViews schema.

• Naming convention: Choose the naming convention to use for general ledger organizational units.

  • Automatic uses the naming convention based on the Oracle E-Business Suite version NoetixViews was generated against, “Ledger” for Oracle E-Business Suite R12 and “Set of Books” for previous versions of Oracle E-Business Suite.

  • R12 (“Ledger”) will create packages and NoetixAnswers folders that use the R12 naming convention.

  • Legacy (“Set of Books”) will create packages and NoetixAnswers folders that use the legacy “Set of Books” terminology.

    NOTE: If you are regenerating packages created by a previous version of Angles for Oracle-Generator, choose the Legacy option to ensure that existing reports continue to work correctly. Choosing a different option will require reports to be migrated to specify the new naming convention.

• View essays/Column descriptions: Select an option to specify to what degree view essays and column descriptions are generated into the model. The options available are:

  • None: View essays and column descriptions will not be generated into the Cognos models.

• First Sentence: Only the first sentence of view essays and column descriptions will be generated.

• Max Displayable Size: View essays and column descriptions will be truncated to the maximum limits of those properties in the Cognos models, if necessary.

• Full: The full view essays and column descriptions will be generated into the Cognos models.

  NOTE: The full view essays and column descriptions can always be found in the Insightsoftware NoetixViews Help file or Insightsoftware Noetix Search (Noetix Search).

• Packages to process: Click <Edit List> to open a dialog that allows you to select the packages to populate, publish to the Cognos server, and generate NoetixAnswers for.

  

  NOTE: Select All can be checked to select all packages and roles.

• Maximum wait time: In the text box, specify the time (in minutes) the generator must wait if the NoetixViews generation is in process. This feature is useful when you want to schedule unattended regeneration of NoetixViews and product name hereBI in a sequence. If the NoetixViews generation completes before the set time, then product name here BI continues its generation. Otherwise, the generation by product name here BI fails with an error message stating that the process timed out waiting for the NoetixViews generation to be completed.

1. If Noetix Analytics was selected on the Execution Plan tab, specify the following information:

• User Name: Enter the Noetix Analytics Active Metadata Repository (AMDR) schema. This schema is sometimes also called the IDS schema.

• Password: Enter the password of the user.

• TNS Name: Enter the Transparent Network Substrate name for the Oracle instance that contains the Noetix Analytics AMDR schema.

• Environment: Choose the environment within the AMDR schema that you wish to generate.

• System: Choose the system within the environment that you wish to generate.

• Packages to process: Click <Edit List> to open a dialog that allows you to select the individual packages and relationship sets to generate.

• Table descriptions/Column descriptions: Select an option to specify to what degree table and column descriptions are generated into the model. The options available are:

  • None: Table and column descriptions will not be generated into the Cognos models.

  • First Sentence: Only the first sentence of table and column descriptions will be generated.

  • Max Displayable Size: Table and column descriptions will be truncated to the maximum limits of those properties in the Cognos models, if necessary.

  • Full: The full table and column descriptions will be generated into the Cognos models.

    NOTE: The full view table and column descriptions can always be found in Noetix Search.

4. Click the Target Parameters tab. This tab is used to specify the location of IBM Cognos BI, as well as additional information necessary to generate metadata into IBM Cognos BI.

   

5. On the Target Parameters page, type the following information:

• In the IBM Cognos Connection Information section, type the following information:

• Gateway URI: The Uniform Resource Identifier (URI) of the Cognos Gateway. The drop down box will be populated with the URIs found in each instance of Cognos Configuration that is configured in the FrameworkManagerInstallDirectory setting in the Generator.config file. Select the correct URI for the instance of Cognos you wish to generate against. If the URI desired does not exist in the list, you may type in a new one.

  CAUTION: The URI specified must be identical to the one specified in Cognos Configuration if you want to publish the generated packages to the Content Store. Specifying a different URI will cause the generator to generate roles and report templates to a different Cognos server, which will cause unexpected behavior and may produce errors during generation.

  NOTE: If the Cognos Application Firewall is enabled, requests from the generator will be blocked. The Dispatcher URI for external applications should be specified instead of the Cognos Gateway URI to solve this problem. This value can be found in the Environment section of the Cognos Configuration tool.

• Authentication Namespace ID: The Namespace ID of the Authentication Provider. This value can be found in the Security section of the Cognos Configuration tool.

  NOTE: You may need to open the configuration tool on the Cognos server to see the Security section.

• User ID: The name of a Cognos administrative user. This user must have the ability to create namespace folders in the root Cognos namespace folder and publish packages into the Public Folder.

• Password: The password of the administrative user.

• If InsightsoftwareNoetixViews was selected on the Execution Plan tab, fill out the following field:

• Data Source Name: The drop down box will be populated with a list of the data sources that exist in IBM Cognos Connection. Select the data source that will be used by all the generated query subjects.

• If Noetix Analytics was selected on the Execution Plan tab, click Configure Data Sources to select the Cognos data sources to utilize in the generated models.

  When the Enter Data Source Information dialog appears, select the data sources that will be associated with the query subjects generated for those data sources. Click Save when finished.

  NOTE: If custom data sources have been added to Noetix Analytics and at least one relationship set associated with each of those data sources was selected for generation, they will appear in the dialog alongside the out-of-the-box data sources from Noetix. Select the appropriate data source in Cognos for these custom data sources as well, if you selected to generate custom relationship sets on the Source Parameters tab.

• In the Folders and Naming section, type the following information:

• Security Namespace: Type the name of the namespace into which the NoetixViews or Noetix Analytics roles will be generated in the IBM Cognos Content Store.

  CAUTION: Generating a new schema into an existing security namespace will cause all role information in that namespace to be overwritten. Insightsoftware strongly recommends using separate Cognos servers for test vs. production to avoid this scenario.

• Package Suffix: Older versions of Cognos did not support publishing packages to subfolders in IBM Cognos Connection and would always publish them to the root public folder. Newer versions of Cognos support publishing into a subfolder.

  If you are generating into an older version of Cognos or regenerating packages originally generated by an older version of Angles for Oracle-Generator, a suffix can be added to each package name to guarantee uniqueness in IBM Cognos Connection.

  This is useful if multiple NoetixViews or Noetix Analytics installations (such as Development, Test, and Production) with similar package names must be generated into the root folder of the same IBM Cognos Content Store. This will prevent packages from being overwritten.

  NOTE: Insightsoftware recommends leaving this field blank for new NoetixViews or Noetix Analytics generations into a newer IBM Cognos instance. The Packages Folder and Answers Folder fields below can be used to select a folder to generate Noetix content into, which keeps the root public folder in IBM Cognos Connection uncluttered.

  • Packages Folder: Type in the path to the IBM Cognos Connection folder where the generated packages should be published. This path must be specified in Cognos’ path format, /content/folder[@name=’folder name’]/folder[@name=’subfolder name’] (example: /content/folder[@name=’NoetixViews-Prod’]). Angles for Oracle-Generator will default the Packages Folder to a subfolder under Public Folders that has the same name as the Security Namespace specified earlier. The correct Cognos path will be created automatically using the format described earlier. This value can be overridden and a different path can be specified, if desired. If you prefer to navigate to an existing folder in IBM Cognos Connection, click […] to open a folder selection dialog.

    NOTE: When Angles for Oracle-Generator loads a generation arguments file created by a previous version of the generator, it will default the Packages Folder setting to the root Public Folders location to preserve the existing Noetix content generated into Cognos.

    CAUTION: If the package folder is changed, any reports created against those packages will need to be re-linked to the new package location before the reports will work correctly against the new packages.

  • Answers Folder: Type in the path to the IBM Cognos Connection folder where the generated NoetixAnswers report templates should be created. This path must be specified in Cognos’ path format, /Cognos/folder[@name=’folder name’]/folder[@name=’subfolder name’] (example: /content/folder[@name=’NoetixViews-Prod’]). Angles for Oracle-Generator will default the Answers Folder to a subfolder under Public Folders that has the same name as the Security Namespace specified earlier. The correct Cognos path will be created automatically using the format described earlier. This value can be overridden and a different path can be specified, if desired. If you prefer to navigate to an existing folder in IBM Cognos Connection, click […] to open a folder selection dialog.

    NOTE: When Angles for Oracle-Generator loads a generation arguments file created by a previous version of the generator, it will default the Answers Folder setting to a subfolder in the root Public Folders location with the same name as the Security Namespace. It does this to provide backwards compatibility for existing customers.

• In the Cognos Model Information section, type the following information:

• Template model.xml Path: Type the path of the template model file that will be used as input for the generation. To create a new model file, click the browse button. Navigate to the location where you want to create the file, and then click Open. The Create Template Model dialog box is displayed. Type the following information:

• Model Name: Type a unique name for the model. This value will be written to the final generated model.

  If the metadata source selected on the Execution Plan tab is InsightsoftwareNoetixViews, specify the following information:

• Data Source Name: Type the name of the data source that was created in Cognos for the NoetixViews installation. This must be the same as the data source selected in the Data Source Name box.

• Connection Name: Type the name of the connection associated with the data source. This will typically be the same as the Data Source Name.

• Schema Name: For NoetixViews, type the name of the NoetixViews schema (typically “NOETIX_SYS”). For Noetix Analytics, specify either the SQL Server schema containing the target database (e.g. “dbo”) or the Oracle schema containing the target database.

  • Use existing models as regeneration templates: By default, Angles for Oracle-Generator will only use the template model file for the initial generation of each Cognos model. Subsequent regenerations will modify the generated models in place.

    This behavior can be reverted to the legacy regeneration method that recreated the generated models from scratch using the template model file. If this behavior is desired, change the value of the UseExistingModelsAsTemplates setting in the Generator.config file to “false”.

• Generated Model Folder: Type the path where Angles for Oracle-Generator should save the generated models.

• In the Action Log Scripts section, either specify a custom script control file or simply check the “Auto-generate script control file based on existing scripts” check box. Auto-generated script control files use the default action log script naming convention, which requires that one separate script control file be maintained for each generated model. Custom script control files allow a more versatile mapping between action log scripts and the generated models they act upon. See Adding and Running Custom Action Log Scripts in “Customizing Generated Models, Packages, and Report Templates.” for more details on script control files and action log script naming conventions.

  NOTE: You may ignore the Action Log Scripts section if you did not check the “Run custom scripts” check box on the Execution Plan tab.

• In the Publishing section, type the following information:

• Versions to retain: Type the maximum number of package versions that you want Cognos to maintain when the packages are published into the IBM Cognos Content Store. Choose 0 to indicate an unlimited number of versions.

• Disable model versioning: Check this box if you do not want Cognos to store multiple versions of published packages in the Content Store.

6. Click the Script tab. This tab allows you to inspect and validate input arguments and optionally save them in an XML file for later unattended regeneration using the command line utility, ngc.exe.

   

7. Click the Validate button to confirm that the source and target information provided is valid.

8. If the validation is successful, optionally click the Save button to save the input arguments to a file (typically GenerationArguments.xml). Check Include passwords when saving if you plan on using the generation arguments file to perform an unattended regeneration in the future. Passwords will be saved to the generation arguments file in an encrypted format.

   NOTE: The Open Existing button can be used to load a previously saved generation arguments file into the Angles for Oracle-Generator tool, eliminating the need to manually re-enter values into the user interface.

9. Click the Execute tab. This tab allows you to start and monitor the generation process.

   

10. On the Execute tab, click the Generate button to start the generation process. During the generation, the generator status and errors will be logged to the screen. A message will appear confirming that the generation has completed successfully. If you want to stop the generation at any time, click the Abort button.product name here BI will stop the generation after completing the current task. During the generation, if you try to click the Close button at the upper right of the page, an error message will be displayed stating that the application window cannot be closed when the generation is in process.

You can view the published packages and generated report templates in IBM Cognos Connection. You can also manually load the model into IBM Cognos Framework Manager to review or publish specific packages.

NOTE: Answers will only be generated for NoetixViews packages that have been published into IBM Cognos Connection. If the generator encounters an answer for a package that has not yet been published, it will write out a warning message stating that all answers associated with that package will be skipped.

Creating Generation Export File

A generation export file contains generated metadata-related information, such as the generation arguments, custom scripts, IBM Cognos model files, and instance summary. You can create a generation export file by exporting these details into a single compressed file with a .gex extension.

Note: You can further manage or regenerate the metadata through the Angles for Oracle-Generator application by importing the .gex file into the corresponding environment in the application. For more information, see the product name here for NEM Help.

To create a generation export file

1. Launch theproduct name here BI tool. Theproduct name here BI window will be displayed.

2. Click File > Create Generation Export. The Save as dialog box appears.

3. Save the generation export file. A message appears stating that the file has been exported successfully.