Customizing Generated Models

This section provides information about customizing the models, packages and report templates created by Angles for Oracle-Generator.

Customization Methods

product name here provides administrators with a high level of customizability to modify what the generator creates. Before using the customization methods outlined in this section, you should understand how these features fit in with the overall generator architecture. There are multiple methods available to customize and control generator output. You should choose the ones most applicable to your specific needs. The following table briefly describes each of these methods:

NOTE: While it is possible to use custom action log scripts to make almost any modification, the other approaches will usually be more efficient and maintainable in the long term.

Using NoetixViews Hook Scripts

Hook scripts offer a powerful mechanism of suppressing, extending, and modifying the default objects in your NoetixViews schema. Changes you make through hook scripts will affect any downstream processes that rely on these objects. If you use hook scripts to customize generator output, you will need to re-run the appropriate NoetixViews stages prior to running the generator. For more information about creating hook scripts, see the NoetixViews product documentation and training materials.

Using Noetix Metadata Manager

Metadata Manager is often the easiest way to customize the Noetix Analytics content generated into Cognos models. Some generator-specific metadata cannot be modified using this tool. For those items, use one of the other customization methods.

Using Generator Hook Scripts

Angles for Oracle-Generator also provides customization points that can be used to customize the content generated into Cognos models and IBM Cognos Connection. These customization points can be utilized by modifying the stock hook script files that come as part of the installation of Angles for Oracle-Generator.

These hook script files can be found in the [Generator install folder]\Scripts folder and have names starting with “hk_”. Each hook script file will execute any PL/SQL statements contained within the file. These hook script files are executed at the end of the script file with a similar name. For example, the hk_popgvw.sql hook script executes at the end of the popgvw.sql script.

Contact Noetix for more information on utilizing these hook scripts.

NOTE: If the Angles for Oracle-Generator hook scripts are used to customize the content generated by Angles for Oracle-Generator, those files should be backed up in case the computer that Angles for Oracle-Generator is installed on experiences an unrecoverable hardware or software failure.

Creating and Using a Metadata Override File

NOTE: Metadata override files duplicate most of the functionality of generator hook scripts. In practice, hook scripts will usually be easier to maintain and debug for all but the simplest scenarios.

The generator uses a series of SQL SELECT statements to read metadata from the NoetixViews schema. The generator nests some of these SELECT statements to read from views with parent-child relationships. For example, the generation processes multiple records in n_gen_view_columns_v for each record in n_gen_views_v. The default SELECT statements used by the generator are described in a plain text file, MetadataReader.xml, which resides by default in C:\Program Files\Noetix\product name here BI. For example, the XML block:

<Query id="RolesToViews">

<Select>

<Columns>

<Column id="role_name">role_name</Column>

<Column id="view_name">view_name</Column>

<Column id="view_description">view_description</Column>

<Column id="view_essay">view_essay</Column>

</Columns>

<From>n_gen_role_views_v</From>

<OrderBy>role_name, view_name</OrderBy>

</Select>

</Query>

directs the generator to use the SQL:

SELECT     role_name,

            view_name,

            view_description,

            view_essay

FROM         n_gen_role_views_v

ORDER BY role_name, view_name

when organizing the objects in the Noetix Security Groups namespace in the generated Cognos model.

All or part of the MetadataReader.xml file can be customized with an override file. The procedure that follows describes how to create a metadata override file.

If a file is specified, the generator automatically merges the information in your Metadata Override file in with the defaults in MetadataReader.xml. It is not necessary or recommended that you include any redundant data elements in your XML; only include the elements you want to add or replace.

NOTE: Never modify MetadataReader.xml directly. If you do, your changes will automatically be overwritten the next time you reinstall or upgrade the generator. Instead, see the procedure below.

To create and use a metadata override file:

1. Open a text editor, such as Notepad, and create a new XML file.

2. Add XML to the file, using the format found in MetadataReader.xml, to define the SELECT, FROM, WHERE and ORDER BY clauses of the metadata SQL statements that you want to modify. For more information, see Metadata Override File Example.

3. Save the file. This file is now a metadata override file.

4. Close Angles for Oracle-Generator if it is currently open.

5. Open the generation arguments file used for your generation using a text editor. If you do not have a generation arguments file, open the [Generator Install Folder]\DefaultGenerationArguments.xml file.

   NOTE: The Angles for Oracle-Generator graphical user interface no longer allows administrators to specify metadata override files there. They must be specified now by directly editing the generation arguments file. Noetix deemed this feature to be very infrequently used and removed it from the user interface to avoid future confusion.

6. Find the <MetadataOverrideFile /> tag in the <NoetixViewsArguments> tag within the file.

7. Replace the <MetadataOverrideFile /> tag with <MetadataOverrideFile>[Metadata Override File Path]</MetadataOverrideFile>, replacing [Metadata Override File Path] with the path to the actual metadata override file you wish to use.

8. Save the file.

9. Launch Angles for Oracle-Generator and continue with the generation. The generator will utilize the metadata override file, taking into account the overrides specified in the file.

   NOTE: The metadata override file will continue to be used during future generations or regenerations until the generation arguments file is modified again, eliminating the metadata override file specified in the <MetadataOverrideFile> tag.

Metadata Override File Example

This example illustrates how to create a metadata override file. Continuing with the example introduced earlier, suppose you would now like to:

• keep two views out of the folders in the Noetix Security Groups namespace

• make the view essays appear in all uppercase

To do this, you need to direct the generator to use this SQL instead:

SELECT     role_name,

            view_name,

            view_description,

            UPPER(view_essay)

FROM        n_gen_role_views_v

WHERE        view_name NOT IN ('MyFirstExcludedView',

            'MySecondExcludedView')

ORDER BY    role_name, view_name

This is accomplished by creating a separate XML file with the following text:

<?xml version="1.0" encoding="utf-8"?>

<Reader>

<Query id="RolesToViews">

<Select>

<Columns>

<Column id="view_essay">

    UPPER(view_essay)

</Column>

</Columns>

<Where>

view_name NOT IN ('MyFirstExcludedView',

'MySecondExcludedView' )

</Where>

</Select>

</Query>

</Reader>

This is a metadata override file. If you included it in a generation, the generator would automatically:

• add a WHERE clause to the query to filter out the two excluded views

• overwrite the “view_essay” column within the “RolesToViews” query

NOTE: Additional details on applying metadata overrides, including an example on how to override column formats for selected columns, are given in the comment block in MetadataReader.xml

Using Syntax Mapping XML Files

Inspection of the <Column> and <From> nodes in the MetadataReader.xml file will provide insight into the structure of the Oracle views the generator uses to read metadata from the NoetixViews schema. These views, however, are designed for use with multiple Business Intelligence platforms and contain no information that is specific to the Cognos syntax. Instead, the generator must map generic terms (such as the format code “DateShort”) to Cognos-specific format strings.

Four plain-text XML files, CognosFormat.xml,AggregationCodes.xml, PromptTypes.xml, and ChartStyles.xml, describe some of this syntax mapping logic. These files are used to build Cognos format strings and aggregation codes, respectively.

NOTE: Never modify these xml files directly. If you do so, your changes will automatically be overwritten the next time you reinstall or upgrade the generator. Instead, create your own override files, as outlined in the later section.

Overriding and Extending the Syntax Mapping XML Files

When the generator builds its set of mapping rules for column formats, it first populates an internal lookup table using the data contained in ColumnFormat.xml. It then looks for a similarly structured additional file named ColumnFormatOverride.xml in the same folder. If it finds the override file, it uses that file to modify and extend its lookup table.

When a code, for example IntNoThousands, is found in the metadata returned by the data_format column (defined in MetadataReader.xml or an override), it is automatically converted to the corresponding Cognos format string in the internal lookup table.

HINT: To add a new Cognos format string, use IBM Cognos Framework Manager to mark a test Query Item with that format. Then save the model and use a text editor such as Notepad to copy the resulting string to your clipboard.

The table below summarizes and compares the generator files that can be overridden.

The most common reasons to override syntax mapping files will be to direct the generator to support additional format types or chart styles. It is less likely that you will need to override AggregationCodes.xml orPromptTypes.xml.

Extending and Modifying Generated Models

product name here BI supports the addition of custom third party objects to generated models. It also supports modifications to some of the properties of Noetix-owned objects. When existing models are used as regeneration templates, allowable custom objects and modifications to those existing models are preserved.

Custom third party objects are typically Cognos query subjects that you want to include in generated packages, but that use data sources other than NoetixViews or Noetix Analytics. Before introducing custom objects, you should confirm that the same content cannot be made available through customizations to Noetix views itself or by exposing the custom objects in Noetix Analytics using Metadata Manager. For more information about customizing the NoetixViews schema, see the InsightsoftwareNoetixViews Administrator Guide.

There are two ways to add a custom third party object.

1. Direct Modification using the Merge Regeneration functionality: After individual models are generated for the first time, perform any customizations needed, either manually through IBM Cognos Framework Manager, or programmatically using Cognos Action Log scripts which you may have maintained for use with previous versions of the generator. The next time you generate, using existing models as regeneration templates, custom objects and customizations of any properties that are not Noetix-owned will be preserved by the generator.
   
   As of generator version 3.1, this is the recommended approach for customizing generated models.

2. Template Customization: Before the initial model generation, place all custom third party objects in the shared template model.xml file. In the template model, include these objects in specially named packages as an indicator to the generator to publish them alongside its generated content.
   
   Prior to the release of generator version 3.1 in November 2010, this was the only way to create custom third party objects without resorting to custom action log scripts. While this functionality is still supported, it is no longer the recommended approach, except in cases where there is a need to push common custom objects into multiple models.

Noetix-owned objects will in have some Noetix-controlled properties and other properties which are not Noetix-controlled and thus treated as custom by the generator. The simplest and most reliable way to customize a Noetix-controlled property is usually through the use of a Generator hook script. See Using Generator Hook Scripts for additional details.

Prior to generator release 3.1, custom properties (those not set by the generator), could only be modified by maintaining a collection of custom Cognos Action Log scripts. While this functionality is still supported, it is no longer the recommended approach. Instead, these properties should be directly modified using IBM Cognos Framework Manager.

Merge Regeneration Functionality

Earlier versions (prior to generator version 3.1) of the product name here BI generated new sets of Cognos models each time, using a small single customizable template file as a starting point, and then creating organization unit level models by inserting NoetixViews metadata into the template. This NoetixViews metadata has always been customizable through generator hook scripts and the metadata override file. However, additional (non-Noetix) customizations to these models could only be made by building and maintaining a library of Cognos action log scripts, which the generator would apply to the freshly generated models prior to publishing.

The merge regeneration feature was designed to eliminate or greatly reduce the need for these action log scripts. By default, the small template model is now used only for the initial generation of any given organization unit level model. After this initial generation, the organization unit level model itself becomes the regeneration template, and the generator automatically preserves the non-Noetix customizations.

Generator Controlled vs. Non-Noetix Objects and Properties

Within any generated model, there will be a mix of objects and properties created and controlled by the Noetix and ones created and controlled manually. The generator will update and overwrite the objects and properties it controls and leave all other objects and properties intact.

Specific rules on which objects and properties are generator-controlled are described later in this document. When considering a modification to any item, it is critical to understand whether that item is generator-controlled or not. Almost all generator-controlled objects and properties can be modified through metadata override files or (recommended) through hook scripts. See Specific Customization and Regeneration Rules for more information on the rules for customizing specific objects in the model.

Enabling the Merge Regeneration Feature

The merge regeneration feature is enabled by default, and displayed in the setting of the “Use existing models as regeneration templates check box in the Target Parameters tab of the generator UI. It can be disabled by modifying the “UseExistingModelsAsTemplates” value of the generator.config file for reverse compatibility.

NOTE: disabling this feature requires, and is equivalent to, manually deleting all previously generated models from the Generated Models folder before the start of each generation.

Upgrading From an Action Log Based Process

If you have a previous version of the generator in a production environment, it is likely that you have a number of legacy action log scripts in place to support your modifications. The following steps are a roadmap for deprecating these scripts and taking full advantage of the new regeneration process.

1. Run a new generation using your existing action log scripts. (Note that there have been some changes and upgrades to the script runner process, including a new script control file.)

2. Regenerate, using the existing models as templates, but without the action log scripts.

3. Evaluate the differences between the results of steps 1 and 2. (Note that the generator now automatically creates a backup copy of your model in a new “History” folder. The number of backup copies maintained is based on a new Generator.config file setting.) You should find that any significant differences between steps 1 and 2 are a side effect of action log scripts that modify generator-controlled properties.

4. Discard the portions of your action log scripts that you no longer need. Specifically, if the generator preserved a given action log based customization between steps 1 and 2, you no longer should need that action log except possibly for new modules.

5. When you are done discarding the unnecessary portions of your action log scripts, you should find that the remaining portions of these scripts are in fact modifying only Noetix-owned objects.

6. As soon as feasible, migrate your remaining action log scripts to generator hook scripts. In practice, you will probably find that most of the generator-controlled properties in question will map to database fields in your NOETIX_SYS schema, specifically those in the N_GEN_VIEWS, N_GEN_VIEW_COLUMNS, N_GEN_DIMENSIONS, and N_GEN_DIMENSION_LEVELS tables. These can be modified by adding UPDATE and INSERT statements to the appropriate generator hook scripts. Work with Noetix as needed during this process.

7. Make appropriate changes to your backup and version control systems. For example, if you use a source control system, you should add your generated models into this system if you have not done so already. (You should also add your generator hook scripts and any metadata override files that you are using.)

Specific Customization and Regeneration Rules

Regeneration rules for namespaces

[All Objects].[Noetix Security Groups]

The only objects that should reside at the root level of the Noetix Security Groups namespace are Noetix owned namespaces corresponding to individual NoetixViews roles. These namespaces will contain Noetix owned shortcuts to Noetix query subjects and dimensions. Any other objects found at this level may be deleted upon regeneration by current or future versions of the generator.

Custom objects may be placed within these Noetix owned security group namespaces. These objects may include folders and namespaces. Additional custom shortcuts may be placed within these custom folders and namespaces.

Non-English names, descriptions, and screen tips, as well as custom <property> items, may be added to all Noetix owned objects (both namespaces and shortcuts) in the Noetix Security Groups namespace.

[All Objects].[Noetix Query Subject Definitions]

The only objects that should reside within the Noetix Query Subject Definitions namespace are Noetix owned query subjects, dimensions, and relationships. Any other objects found within this namespace may be deleted upon regeneration by current or future versions of the generator.

Certain modifications may be made to Noetix owned query subjects and dimensions, as discussed in Customizing Individual Noetix Owned Objects. For example, if a custom security filter is added to a Noetix owned query subject, it will be left intact upon regeneration. Similarly, non-English names, descriptions, and screen tips may be added to Noetix owned objects in this namespace.

[All Objects].[Custom Objects]

Any objects within this namespace will be treated as custom and will be preserved by the generator upon regeneration.

Other Namespaces

Any objects within all other namespaces will also be treated as custom and will be preserved by the generator upon regeneration. For example, a relationship between a Noetix object in the Noetix Query Subject Definitions namespace and a custom object in the Custom Objects namespace will be stored by IBM Cognos Framework Manager at the lowest common ancestor folder, namely the All Objects namespace. This relationship will be preserved on regeneration.

Regeneration Rules for packages

Each generated model will typically have 3 packages. One package will contain links to Noetix objects, a second will contain links to custom objects, and a third, the Noetix owned publishable package, will simply contain links to the 2 other packages.

In addition, customers who upgraded from previous versions of the generator may have additional packages which contain links to custom objects and are also included in the Noetix owned publishable package.

Noetix Owned Generated Content package

This package is named {#MODELNAME# – GeneratedContent}. It is entirely controlled by Noetix and should not be edited.

Custom Non-Noetix package

This package is named {Custom Non-Noetix}. It is created by the generator with an initially empty definition, and then left alone to preserve any custom modifications.

Any custom objects that need to be included in the published package should be included in this package. Note that objects in this package will only become visible to end users if object level security is properly specified for the objects.

Name-decorated includable packages

Deprecated functionality – use {Custom Non-Noetix} instead.

Noetix Owned Publishable Package

This package is named #MODELNAME# <OPTIONALSUFFIX>. It is implemented as a linked package, and thus includes all objects in the packages listed above. It should not be modified directly, except to add non-English names, descriptions, and screen tips.

Customizing Individual Noetix Owned Objects

Adding non-English strings

CAUTION: There are some known issues with how the generator works against multi-language models on regeneration. If you are planning to add languages other than English to a generated model, please contact Insightsoftware Support for detailed status and workarounds.

Shortcuts, namespaces, packages, query subjects, query items, dimensions, hierarchies, levels, and measures all have localizable names, descriptions, and screen tip strings. By default, the English versions of these strings are controlled by the generator, and should only be customized using hook scripts or metadata override files. Exceptions are listed below.

Specially named namespaces

Specially named namespaces such as [All Objects].[Noetix Query Subject Definitions] and [All Objects].[Noetix Security Groups] have hard coded English names and initially hard coded English descriptions and screen tips. As long as the English names of these namespaces are not changed, the English descriptions and screen tips may be modified in the model at any time. In addition, non-English names, descriptions, and screen tips may be added to these model objects.

Hard coded descriptions and screen tips

Certain objects, such as dimensions, hierarchies, and levels, as well as List of Value query subjects, currently have hard coded English descriptions and screen tips (sometimes these are simply empty strings) which cannot be modified without applying post-generation action log scripts. If you encounter a case where you need to customize a hard coded string with an action log script, please contact Insightsoftware Support to request that this string be moved into the Noetix metadata layer to support customizability in a future release or hotfix.

Non-English names, descriptions, and screen tips may always be added to Noetix owned objects, whether or not the English versions of these strings are hard coded.

Adding Custom <property> tags

The “Noetix owned” flag which appears on most Noetix-generated objects is created using the XML <property> tag. While properties such as this flag cannot be created directly through IBM Cognos Framework Manager, they can be created using the Cognos SDK.

If you apply additional custom properties to Noetix owned items, the generator will preserve them on regeneration.

Modifying Query Subjects

The following properties of query subjects are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. SQL (Note: this may in practice limit your ability to add custom query items to a Noetix query subject.)

3. Data source reference

Custom modifications to other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Filters

5. Security Filters

6. Determinants

7. Status

8. Query item folders

9. Non-Noetix query items (subject to constraints of Noetix-generated SQL)

Modifying Query Items

Non-Noetix query items (those which whose “Noetix owned” flag is false or non-existent) will be not be modified by the generator. Their English names must not collide with Noetix owned query items coming from the metadata.

The following properties of query items are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. External Name

3. Usage

4. Format

5. Data Type

6. Precision

7. Scale

8. Size

9. Nullable flag

10. Prompt info

11. Regular Aggregate code

12. Roles (e.g. _businessKey, _memberCaption, _memberDescription. Used only within dimensions)

Custom modifications to other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Hidden flag

5. Display type

6. MIME type

7. ISO Currency code

8. Semi-Aggregate code

9. Unsortable flag

Modifying Measure Dimensions

The following properties of measure dimensions are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. SQL (Note: this may in practice limit your ability to add custom measures to a Noetix measure dimension.)

Custom modifications to other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Filters

5. Security Filters

6. Status

7. Non-Noetix measures (subject to constraints of Noetix-generated SQL)

Modifying Measures within Measure Dimensions

Measures within measure dimensions are treated using the same logic as query items within query subjects.

Modifying Regular Dimensions

The following properties of regular dimensions are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. SQL (Note: this may in practice limit your ability to add custom measures to a Noetix measure dimension.)

Custom modifications to other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Security Filters

5. Preview Filters

6. Status

7. Non-Noetix measures (subject to constraints of Noetix-generated SQL)

Modifying Hierarchies within Regular Dimensions

The following properties of hierarchies are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. Root MUN

3. Root Caption

4. Levels (Only Noetix levels are supported as children of Noetix Hierarchies.)

Custom modifications to all other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Care should be taken modifying other properties to ensure that modifications do not clash with Noetix controlled property settings.

Modifying Levels within Hierarchies

The following properties of levels are controlled be the generator and will be overwritten if you modify them using IBM Cognos Framework Manager:

1. English description and screen tip

2. Manual flag

3. Unique flag

4. Levels (Only Noetix levels are supported as children of Noetix Hierarchies.)

Custom modifications to all other properties, including the following, will be preserved on regeneration:

1. Non-English names, descriptions, and screen tips

2. Comments

3. Custom properties (other than the “Noetix owned flag)

4. Care should be taken modifying other properties to ensure that modifications do not clash with Noetix controlled property settings.

Modifying Query Items within Levels

Query items within dimension hierarchy levels are treated using the same logic as query items within query subjects.

Adding Custom Third-party Objects Using Template Customization

This approach is usually no longer required or recommended. It is included for reverse compatibility with previous generator versions. When performing new customizations, please refer to Extending and Modifying Generated Models.

1. Perform an initial test generation to learn what you expect the generator to create from your NoetixViews or Noetix Analytics source system. It is not necessary to publish any packages at this point.

   Next, use IBM Cognos Framework Manager to study the generator results in the “Generated Models” folder. For more information on performing a generation, see Generating Models, Packages, and Report Templates.

2. Using IBM Cognos Framework Manager, open the model.xml file used as input to the generator. The path for this file was specified in the Template model.xml Path box on the Target Parameters tab of the Generator tool. The model.xml file has the following namespace structure under the All Objects namespace: Noetix Security Groups, Noetix Query Subject Definitions, and Custom Objects. Import or manually create your custom query subjects under the Custom Objects namespace. These can be at the root level or in separate namespaces or folders.

   If the custom query subjects reference objects from data sources other than the ones already present in the template model, new data sources should be added to the model before creating the custom query subjects. These data sources will be retained in the generated model files.

   NOTE: Namespaces must be unique within any Cognos model. Ensure not to create namespaces whose names will clash with those created by the generator.

3. If custom query subjects need to be joined to generated NoetixViews query subjects observed in the generated model from step 1, create each join relationship in the following manner:

   1. Within the Noetix Query Subject Definitions namespace, create a placeholder query subject with the same name as the generated query subject you intend to join to. Add a query item to that query subject with the same name as the column you intend to join to, remembering that names are case-sensitive.

      NOTE: This placeholder query subject will not persist in the generated model files; it will be replaced by the generated version of the query subject. As a result, the source for the query items created on the placeholder query subject does not need to be valid.

   2. Right click on either the placeholder query subject or the custom query subject, and then click Create > Relationship to create a relationship between the two objects.

      NOTE: This new relationship will persist in the generated model files, and will connect the custom query subject with the generated query subject that replaces the placeholder version.

4. The custom query subjects should be included in the packages that are created during generation. Custom query subjects should be added to packages in the following manner:

   1. Manually create a custom package in the model.xml file with a name similar to the Noetix-generated package in which you want to include the custom object, but without any suffix. In addition, the package’s name should be placed within braces. For example, if the Noetix-generated package name is Application Object Library <Test 3>, the custom package’s name should be {Application Object Library}.

   2. Include the custom query subjects in the package. The generator will incorporate the custom query subjects into the generated version of the package created in step a.

   3. Repeat steps a and b for any additional custom packages that are needed.

5. Specify object security on the custom query subjects created earlier. This will typically mean granting it to one or more of the Noetix roles created in your initial generation. If you want the query subject to be visible to everyone who opens its containing packages, you may grant it to the Cognos ‘Everyone’ role or to one or more generated Package Viewer roles.

NOTE: If you skip this step, users will not be able to see the custom object.

6. Save the model. Optionally, you may reformat your model.xml using the FormatModel.exe tool or an XML editor. This is recommended if you are managing your model in a source control system.

7. Use the product name here BI to perform regeneration.

   After the regeneration completes, the custom query subjects will appear in the generated model files. In addition, the generation process will create the following items:

   1. The custom packages that were defined in the model.xml file earlier.

   2. The original packages that make the generated query subjects available. These packages will now be enclosed in braces and will have “- GeneratedContent” as a suffix. For example, the Set of Books: Vision Operations package that would be generated before custom packages were added will now be generated with the name {Set of books: Vision Operations - GeneratedContent}.

   3. A package that merges the original and custom packages together. This package will contain the generated query subjects and custom query subjects created earlier and can be published during the generation process.

The custom query subjects should now appear alongside the generated query subjects in IBM Cognos Query Studio and IBM Cognos Report Studio.

Adding and Running Custom Action Log Scripts

This approach is usually no longer required or recommended. It is included primarily for reverse compatibility with previous generator versions. When performing new customizations, please refer to Extending and Modifying Generated Models.

A custom action log script is an XML file, created by IBM Cognos Framework Manager or hand-edited using the Cognos SDK documentation, which can be run by the Cognos BmtScriptPlayer.exe macro utility to apply automated edits to a given model. When appropriately referenced, these scripts are also played by the generator to edit individual generated model files during the Run custom scripts step.

In general, you should only use custom scripts as a last resort, after you have determined that you cannot obtain the same outcome using techniques such as custom hook scripts (to modify objects and properties controlled by the Angles for Oracle-Generator) and direct modification of generated models (to modify custom objects and properties).

The generator will reference custom action log scripts using a Script Control File. The Script Control file is an XML file containing mappings between model names and action log file paths. Scripts are run in the sequence they appear in the script control file. A single script may be run on multiple models, and multiple scripts may be run on a single model.

The generator will, by default, auto-generate a simple script control file in the CognosActionLogCustomScripts folder, under the Generated Model Folder. This file, AutoGeneratedScriptControl.xml, can be used as a template for more complex script control files.

Before attempting to create a script control file from scratch, you should first run a generation with the “Auto-generate script control file based on existing scripts” check box on the Target Parameters tab checked. During the Run custom scripts step, the generator will then look through the CognosActionLogCustomScripts folder for action log script files named using the format <Package Name>.ActionLog.xml, where Package Name is the name of the corresponding Cognos Project File, without the extension, in the Generated Models folder for which the action log is to be applied (for example, an action log for the Set of Books_ Vision Operations.cpf file should be named Set of Books_ Vision Operations.ActionLog.xml).

When the generator finds such a script, it includes it in the auto-generated script control file. It then uses this file to control calls to the Cognos BmtScriptPlayer utility to apply the script to the generated model, which is later published during the Publish generated packages step.

CAUTION: While custom scripts are relatively straightforward to create and implement, Noetix makes no guarantee that a custom script which works against one version of the generator will continue to work against subsequent versions.

To add and run a custom action log script using the auto-generated script control file:

1. Perform an initial generation, preferably in a test environment, to learn what the generator will create from your NoetixViews or Noetix Analytics source system. It is not necessary to publish any packages at this point.

2. Using IBM Cognos Framework Manager, browse to your Generated Models folder and open <Package Name>.cpf, where PackageName is the name of the package containing items you want to modify before the publication step.

3. Edit the generated model, making the same changes you want to have the generator make automatically with each generation.

4. Save your steps into an action log script. In version 8.3 of IBM Cognos Framework Manager, this may be done using the Project > View Transaction History menu option. Your script must follow the naming convention PackageName.ActionLog.xml and be stored in the CognosActionLogCustomScripts folder. For more information on working with action logs in IBM Cognos Framework Manager, see the Cognos documentation.

5. Manually inspect this script and test it using the Cognos BmtScriptPlayer.exe tool, as outlined in the Cognos SDK documentation, or test it with the Project > Run Script menu option in IBM Cognos Framework Manager.

6. Perform a fresh generation using the product name here BI, first deleting previously generated models, and then selecting the Populate model and Run custom scripts steps. Inspect the generation log on the Execute tab for errors after the generation completes.

   NOTE: The generator will not always programmatically detect script player errors. Review the generation log carefully.

7. Re-open the newly re-created Cognos Project File for the package using IBM Cognos Framework Manager and confirm that the script was properly applied.

8. Perform another regeneration using the product name here BI, this time choosing only the Publish generated packages step. Verify that the customized package or packages can be published successfully to complete your testing.

   The scripts will be re-run on your generated Cognos models during future regenerations when the Run custom scripts check box is selected.

   NOTE: When you use the “Use existing models as regeneration templates” option (recommended) in conjunction with legacy action log scripts, you may encounter regeneration errors when these scripts attempt to create duplicate objects. This is by design, as the generator now preserves custom objects added directly to models. Action logs that re-create custom objects now preserved by the generator are now redundant and can be removed.

To apply a single action log script to all generated models:

1. Create an action log script, e.g. C:\MyActionLog.xml, that you wish to automatically run on all generated models.

2. Create a new script control file by making a copy of the AutoGeneratedScriptControl.xml described above. Give it a different name to prevent it from being overwritten by the generator.

3. Open the new script control file using a text editor or XML editor, and add the following XML node, as a child of the<ModelToActionLogMappings> node:

   <ModelToActionLogMapping>

       <ActionLogs>

           <ActionLog>C:\MyActionLog.xml</ActionLog>.

       </ActionLogs>

       <Models>

           <Model>*</Model>

       </Models>

   </ModelToActionLogMapping>

   Note that paths in this file may be relative or absolute. See the comments in the auto-generated file for details.

4. Save the new script control file.

5. Generate, this time un-checking the “Auto-generate script control based on existing scripts” check box and selecting the new file.

To apply multiple action log scripts to multiple generated models

The procedure here is similar to that for applying a single action log script to all models, except that, within each <ModelToActionLogMapping> block, you must specify the model or models on which you wish to run the script or scripts. See the comments in the auto-generated file for more details and examples.

NOTE: Model names will not always be the same as file names, since file names strip out illegal characters such as colons. Thus a valid model name might be:<Model>Operating Unit: Vision France (Item validation: None)</Model>, whereas <Model>Operating Unit_ Vision France (Item validation_ None)</Model> would be incorrect.

Customizing NoetixAnswers

The report templates generated during the Generate NoetixAnswers step can be customized. The following types of customizations are supported:

• Customizing the look and feel of the report templates.

• Customizing the columns, parameters, filters, and other attributes of the report templates.

The report templates should never be modified using IBM Cognos Connection or IBM Cognos Report Studio. Instead, they should be modified using the methods outlined in this section and then regenerated using product name here BI.

Customizing Report Look and Feel

The look and feel of the report templates is governed by a skin file, which describes the cascading style sheet attributes and text to apply to the report templates during generation. Skin files are defined as XML, with the following format:

<?xml version="1.0" encoding="utf-8"?>

<Skin>

<Description></Description>

<CSS>

<header></header>

<body></body>

<footer></footer>

<columnTitle></columnTitle>

<columnBody></columnBody>

<page></page>

<table></table>

</CSS>

<text>

<headerText></headerText>

<footerText></footerText>

</text>

</Skin>

The tags in the file are defined as follows:

• <Skin>: This is the outer tag of the file that contains all of the information related to the skin.

• <Description>: This tag contains a text description of the skin. This value is not used in the report templates and is meant as a way for the administrator to note what the skin is for so that it can be easily interpreted later.

• <CSS>: This tag contains all of the cascading style sheet attributes that will be assigned to the report.

• <header>: This tag allows the administrator to define styles that will be applied to the header of all report pages.

• <body>: This tag allows the administrator to define the styles that will be applied to the body of all report pages.

• <footer>: This tag allows the administrator to define the styles that will be applied to the footer of all report pages.

• <columnTitle>: This tag allows the administrator to define the styles that will be applied to the column titles displayed in a report’s results table.

• <columnBody>: This tag allows the administrator to define the styles that will be applied to the portion of the report result’s table that displays the data returned in the report.

• <page>: This tag allows the administrator to define the styles that will be applied to each report page.

• <table>: This tag allows the administrator to define the styles that will be applied to the HTML tables displayed on all of the report pages.

• <text>: This tag contains the specific areas of the report that can have custom text applied.

• <headerText>: This tag contains any custom text that should be displayed on the report page’s header.

• <footerText>: This tag contains any custom text that should be displayed on the report page’s footer.

Example:

<?xml version="1.0" encoding="utf-8" ?>

<Skin>

<Description>

    This is the default skin file.

</Description>

<CSS>

<header>background-color:#999999 </header>

<body>background-color:#DDDDDD </body>

<footer>background-color:#999999 </footer>

<columnTitle>background-color:#AAAAAA </columnTitle>

<columnBody>background-color:#BBBBBB </columnBody>

<page>background-color:#666666 </page>

<table>background-color:#666666;color:#FF0000 </table>

</CSS>

<text>

<headerText> MyCompany </headerText>

<footerText>

This report displays confidential material. Do not

distribute it.

</footerText>

</text>

</Skin>

To construct a skin file:

1. Copy the XML structure outlined above, and then paste it in Notepad.

2. Add a description for the skin in the <Description> tag.

3. Add cascading style sheet attributes to the tags within the <CSS> tag to modify the colors, borders, and other attributes of the associated sections of the report templates. If you are unfamiliar with cascading style sheets, there are many good tutorials and reference documents available on the Internet.

4. Add text to the <headerText> and <footerText> tags to make custom text appear at the top or bottom of each report page.

   NOTE: Custom text will not be displayed on any prompt pages.

5. Leave any tags that you do not want to use empty. Do not delete any of the tags. The skin file is required to have all of the XML tags referenced earlier.

6. Save the skin file.

To apply a skin file:

1. Open Windows Explorer and navigate to the installation folder for product name here BI.

2. You must back up the existing ActiveSkin.xml file before you replace it with another skin file. Therefore, find the existing ActiveSkin.xml file, and rename it.

3. Copy the skin file you want to use to this directory, and then rename it as ActiveSkin.xml.

4. Start the generation. The generator will load and use the ActiveSkin.xml file it finds in the installation directory.

5. To use a different skin file in the future, replace the current ActiveSkin.xml file with the new one.

Customizing Report Attributes

The attributes (columns, filters, parameters, etc.) of the generated report templates can be modified using NoetixViews hook scripts, Generator hook scripts, or a metadata override file. For more information on creating hook scripts, see the NoetixViews product documentation and training materials. For instructions on creating Generator hook scripts or a metadata override file, see Using Generator Hook Scripts and Creating and Using a Metadata Override File sections in “Customizing Generated Models, Packages, and Report Templates.”