Update

Report Validator

Once metadata modeling has been updated, the value to end users is realized in the ability to quickly re-validate the existing reports under the newly published package(s). Report Validator allows administrators to easily validate selected reports. Validation errors are provided in detail for any object that returns an exception, warning or error message. If ‘Validate & Save’ is selected, reports that validate with an OK status are automatically re-saved in the newly valid state. If you choose the ‘Validate’ button the items will only be validated, and you will be able to run the report to see it in the new version, but the changes will not be saved to the server, the existing report will not be impacted.

NOTE: It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM you use the Create a Backup button on the module toolbar to back up the content pre-change.

Prompting Options

Report Validator comes with both manual and auto-prompting options to assist administrators in validating prompted reports. These options can be found in the toolbar.

Generate Prompt Report - This option will generate a report of all the prompts used in the selected reports. The design of this report is to provide administrators with a file to feed prompt values back through MetaManager^TM to fully validate a report. This report will list the following fields if available: the report search path, prompt name, prompt type, and prompt model filter item. The Prompt Value column is left blank intentionally. This is done so the administrator can enter valid prompt values* which MetaManager^TM can then read, pass through to the report, and fully validate the report. An example of the report is below.

Set Report Prompts – This option will allow an administrator to enter valid prompt values that MetaManager^TM can then pass through to the report allowing it to fully validate. The values can be entered manually, one-by-one, or they can be loaded in via the Prompt Report file generated from the previous section.

Enable/Disable Auto Completing Report Prompts – This option provides the ability to automatically validate prompted reports without entering a valid prompt value. When the option is enabled, a dummy value based on the prompt type will be passed through to the report allowing it to validate. This can be very valuable to administrators that may not know a valid prompt value for each report in the environment, but still need to validate those reports.

Validate and Save Reports

To begin using Report Validator, you must:

1. Identify the content you wish to validate.

2. Run or preview the validation.

NOTE: As reports are processed, the progress is indicated in the progress column. Results are listed in the Current Status column. Additional information can be found for each validated report in the information pane at the bottom right of the user interface.

Report Validator Processing

As Report Validation is being executed, the report icon on any given Object Row will change to an hourglass while an Object Row is being processed.

1. A triangle marker indicates which step the object row is processing.

2. The validation results are represented in the Current Status field with an icon indicating the status. See below for more information.

Validation Results

The following table lists the possible validation results.

Icon	Validation Result	Description
	OK	Report validated with no problems.
	Exception	Some type of anomaly occurred. Check the Information section to what exceptions caused the failure.
	Prompt	The report requires prompt answers that could not be supplied as part of the validation processing. All other aspects of the report (namely the syntax / specification) are OK.
	Warnings	The report validation was able to proceed, but with errors that may affect the report integrity. Check the Information section to see where the validation encountered errors.
	Errors	Report validation failed. Check the Information section to see where the validation encountered errors.

An explanation of validation results

Context Menus Specific to Report Validator

Within the object rows of the MetaManager^TM grid, Report Validator has one context menu unique to this module.

Fix Report

In very specific instances where a report contains expression parsing errors, a Fix Report feature is enabled on the Object Row’s context menu. An expression error means that a data item is invalid (i.e. when a Framework Manager namespace, query subject or query item has been renamed, moved, etc.).

The Fix Report dialog will determine the package referenced by the report specification and load that package into a metadata tree. The dialog will display each of the invalid data items in a grid, and users can navigate the tree and drag the appropriate “fix” objects from the tree over top of the invalid objects in the grid.

Users can choose the Fix Report button which will resave the report with the adjusted report specification. They can then revalidate the report in Report Validator to see the new status.

Send to Find / Replace

Alternatively, users can choose the Send to Find / Replace option. Send to Find / Replace will send the list of data item changes to the options area within the Find / Replace module. In addition, MetaManager^TM will determine which package the selected report was built from and send a Query Row to Find / Replace. The Query Row will be a built-in search “Find reports related to {package}”.

NOTE: The fix report feature currently only supports Report Studio Reports.

Report Validator Details

The details pane displays the status of the selected Object Row and indicates the specifics of any warnings or errors within a specification. In many cases, the error or warning can be resolved immediately within Report Validator (using the Fix Report feature) or within the Find / Replace module.

NOTE: The boxes are rich text format controls and copy enabled.

Find/Replace

The Find / Replace module provides a powerful and intuitive interface to perform a search and replace across a selectable group of reports. In addition, the Find / Replace module can interface directly with Framework Manager, making it easy to apply all name changes made within a Framework Manager model to the impacted reports. This eliminates the manual steps involved with report specifications breaking when name changes, such as query items, query subjects, or namespaces occur in the Framework Manager model and published package(s).

Use the Find / Replace module to find or change:

• Data Items

• Drill-Through Items

• HTML Items

• Image Paths

• Package / Cube References

• Report Expressions

• Text Items

• Entire Specification*

• XPath

NOTE: Changing the entire specification should be executed with extreme caution, as this will allow changing proprietary XML tags within the specification. It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM you use the Create a Backup button on the module toolbar to back up the content pre-change.

Find and Replace Within Specifications

To begin using Find/Replace, you must:

1. Identify the content you wish to modify.

2. Determine what to modify within the selected content.

3. Determine what to replace the found items with.

4. Choose the appropriate location within each specification to perform the update.

5. Preview the changes to ensure that the desired results are achieved.

6. Apply the modifications.

NOTE: The following exceptions to the above exist due to limitations in how the IBM Cognos products work:

• PowerPlay Reports and PowerPlay Cubes do not support validating modified specifications.

• PowerPlay Reports and PowerPlay Cubes do not support previewing modified specifications.

• PowerPlay Studio Reports do not support validating current or modified specifications.

• PowerPlay Studio Reports do not support previewing modified specifications.

Find and Replace Options

The Options tab allows users the ability to specify one or more search and replace criteria to be performed on the selected content.

1. Search Text - This represents the text to search for within the specification(s). This field is required and in certain instances supports the wildcard “*”.

2. Replace Text - This represents the field to replace the text with within the specification(s).

   NOTE: Leaving this field blank is a valid value.

3. Location - This represents the scope of the specification search for. For more information on this field, see the section later in this chapter.

4. Set Properties - When selected, the Find and Replace text will be run through the .NET Regular Expression Engine. The RegEx option allows you to specify more complex search strings using regular expressions, which allow searching for patterns rather than static text.

NOTE: This is an advanced feature. Refer to http://en.wikipedia.org/wiki/Regular_expression for more information on RegEx. In addition, there are a number of tools available to help author RegEx (i.e. Expresso - http://www.ultrapico.com/Expresso.htm, a free download that comes with a tutorial and lots of samples).

NOTE: It is recommended that users copy report specifications and use a utility like Expresso to build and debug the regular expression.

5. Case Sensitive – This specifies whether the Search and Replace syntax should be treated as case sensitive.

Find / Replace supports an unlimited number of entries, and users can add more entries by entering in the desired information into the top row then pressing the enter key. Similarly, users can remove an entry by selecting the delete button in the rightmost column or by selecting the row(s) and pressing delete on the keyboard.

NOTE: The Find / Replace entries are executed in the order that they are listed in the grid. This can be important in many instances and should be reviewed before modifying content. Users can change the order of the entries by using the Up and Down buttons in the columns to the right of any row.

NOTE: Invalid entries will be removed from the grid when the Update or Preview buttons are pressed. Invalid rows are rows that contain blank search text.

NOTE: Any changes to the options area will immediately reset all previewed and saved reports to their initial state.

NOTE: Find / Replace supports multi-line changes, however multi-line editing is not supported directly in the UI. Therefore, the user must type the multi-line change in a text editor and then copy and paste it into the Search Text or Replace Text area.

NOTE: For some use cases the user may need to navigate to areas of the portal to copy text such as an object’s SearchPath or account’s ID, to be used as search or replace text. The property grid beneath the portal tree provides quick access to a number of properties which may be helpful when developing the Find / Replace entries.

NOTE: Regarding Package / Cube Reference location:

• Users can drag a package from the portal tree to the Find / Replace options area.

• When dropped, a new row will be added to search for “*” and replace with the path to the latest model for that package in the Package Reference location.

• The search text “*” is supported for this location type only and will replace any existing package reference value with the new value.

NOTE: This is useful when selecting a number of reports to link to a specific package regardless of what package they currently point to.

• The user can change the search text “*” to a specific package if desired.

Processing

As Report Validation is being executed, the report icon on any given Object Row will change to an hour glass while an Object Row is being processed.

1. A triangle marker indicates which step the object row is processing.

2. The validation results are represented in the Current Status field with an icon indicating the status. See below for more information.

Preview

The processing steps for Preview are:

1. The selected report specifications (may come from cache) are loaded into memory.

2. The specifications are then validated against the applicable package in the Content Store.

3. Each Find / Replace entry is executed sequentially on the report specifications.

4. The new specifications are then validated against the applicable package in the Content Store.

NOTE: When Preview is used rather than Update, any desired Object Row can be selected, and the specification can be previewed through the right-click menu. This allows for a visual comparison to the stored specification in the Content Store, which can be run through the right-click menu, Run option.

They can also be previewed textually using the compare Changes right-click menu.

Update

The processing steps for Update are:

1. If the Preview has been performed, execute steps from 1 to 4 above.

2. Save the modified specifications in place of the current specification within the Content Store.

Validation Results

The following table lists the possible validation results.

Icon	Validation Result	Description
	OK	Report validated with no problems.
	Exception	Some type of anomaly occurred. Check the Information section to see what exceptions caused the failure.
	Prompt	The report requires prompt answers that could not be supplied as part of the validation processing. All other aspects of the report (namely the syntax / specification) are OK.
	Warnings	The report validation was able to proceed, but with errors that may affect the report integrity. Check the Information section to see where the validation encountered errors.
	Errors	Report validation failed. Check the Information section to see where the validation encountered errors.

An explanation of validation results

Find and Replace Details

The details pane displays the status of the selected Object Row and indicates the specifics of any warnings or errors within a specification. In many cases, the error or warning can be resolved immediately within the Find / Replace module.

NOTE: The boxes are rich text format controls and copy enabled.

Load Framework Manager Project

The Load Framework Manager Project option within Find / Replace allows for the application of all “name changes” made within a Framework Manager model that can have a negative impact on report specifications (i.e. namespace, query subject, query item, etc.). This eliminates the manual steps involved when report specifications break due to Framework Manager model and associated published package modifications.

When executed this proprietary feature will load a list of changes and associated packages from any selected Framework Manager project and import them into the Find / Replace options screen.

Users may select individual or multiple rows in the Changes or Packages list view and delete them using the delete keyboard button or by clicking the “Remove Selected” link label to remove them from the list.

NOTE: The model name changes are populated from the available Framework Manager project log files, and therefore it may load many historical items. The items are sorted in date / time descending order, so the old items that are no longer applicable can be easily removed. The order of the model changes is important as it is the order in which they were performed in Framework Manager.

NOTE: Model Name Changes will be imported into the Find / Replace options area as case sensitive data item changes.

NOTE: Any specifications (Public and / or personal My Folders) built from the Available Packages will be imported into the grid area as search Query Rows. This makes it easy to automatically fix broken specifications from within the entire content store.

Meta Editor

The Meta Editor module enables administrators to update the various objects and attributes within a Cognos Framework Manager model in an easy-to-use interface, reading the contents of any Framework Manager model and saving changes back to the model once complete. Objects that can be updated include Folders, Namespaces, Packages, Query Items and Query Subjects.

Update Metadata Properties

To begin using Meta Editor, you must:

• Select a Framework Manager project file.

• Select objects to enhance and modify.

• Save changes.

  Optionally, you can set options to help limit your search for metadata items. Specifically, you can:

• Use Quick Filters.

• Define Advanced Filters.

  In order to ease navigation in Meta Editor, several toolbar icons are available.

	Open a Framework Manager project file (.cpf).
	Save changes to Framework Manager project. Selecting this icon will apply all changes made to the model.xml of the applicable Framework Manager project and create an associated Framework Manager model log file.
	Close a Framework Manager project file (.cpf).
	Lock or unlock a Framework Manager model. By locking the model, other modelers may open the model in Meta Editor, however they will be unable to save their changes until the locked model is unlocked or closed. On the contrary, the model cannot be opened in Framework Manager when locked in Meta Editor. If a developer tries to open the model in FM while it is locked, the following error will be received. "The action 'Loading project' has failed. 1 error(s), 0 warning(s). BMT-MD-5065 The upgrade action failed. BMT-MD-0001 Invalid parameter."
	Import/Export - Users can export spreadsheets, manipulate them and import them back into the model. To do this, setup the grid with the information, then click the export button to create a .csv file. Open the spreadsheet in Microsoft Excel and delete, edit or reorder the rows and columns (the first column cannot be edited). Then you can save and use the import button to import those changes back into Meta Editor.
	Hide or show the project tree hierarchy. The tree may be hidden in order to maximize the available real estate for using Meta Editor.
	Synchronize the project tree hierarchy to the active row. This can be useful when a large number of objects have been selected into the grid on the right. By selecting any object in the grid and clicking this button, the tree will expand to the exact reference object.
	Copy the contents of the grid to clipboard. This can be useful if you want to place the contents of the grid into another application such as Microsoft Excel.
	Clear all project tree hierarchy selection(s), thus clearing the tree on the right.

Select a Framework Manager Project File

1. From the Module Sidebar, select Meta Editor. Alternatively, you may select the View menu and click Meta Editor

2. On the Meta Editor toolbar, click Open

3. Click a Framework Manager project file (.cpf) and click Open.

4. In the hierarchical list of objects, select items.

Selected items appear in the right pane where metadata can be edited. Individual metadata items are listed in cells. Items that can be edited are a lighter shade of blue than non-editable items.

Tip: To clear all selections, on the Meta Editor toolbar, click Clear selection
Tip: To hide or show the hierarchical list of project file items, on the Meta Editor toolbar, click Hide or show project hierarchy.
Tip: To synchronize your position in the hierarchical list with highlighted items in the metadata pane at right, click Synchronize project hierarchy to active row.
Tip: To lock or unlock the model, click Lock/Unlock Model.

Edit and Save Changes

Metadata items that can be edited appear with a different background color than items that cannot be edited. Editable items appear with a white background, while non-editable items appear with a darker grey background. After an item has been edited, it appears in a light-yellow color to show that the item is changed. To record the changes to an item and save it back to the model.xml, you must save changes before exiting Meta Editor.

1. To add or change the contents of a cell single-click the cell and type in the cell. Alternatively, you may double-click on the cell to edit the contents within the cell. Leaving the cell commits changes to that item, however, you must select save after you have finished making changes (or during the course of making changes).

2. For items with a predefined list of valid values, you may type the exact syntax, copy and paste it from another cell, or double-click within the applicable cell and choose a value from the dropdown list.

3. After you have finished making changes, click Save.

Use Filter Options Use Quick Filter

Use quick filters to help locate "like" classes of items. For example, select Show Namespaces to display all namespace objects within the Framework Manager model in the grid on the right.

1. On the Meta Editor toolbar, click Quick Filter.

2. Select one of the display options to return all "like" items in the Framework Manager model to the metadata pane on the right.

Define Advanced Filters

Define advanced filters to help limit results to items with specific characteristics. The Advanced Filter controls work by checking items in the hierarchical list. Checked items then appear in the grid to the right of the list and under the filter controls.

1. On the Meta Editor toolbar, click Advanced Filter.

   The Advanced Filter controls appear.

2. Select the type of object from the combo-box next to Advanced Filter.

3. Construct a query by defining one or more filters. For each filter, select the attribute, such as Name, Description, or Last Changed. Select the comparison type, such as Contains, Starts With. or Equals. Finally type the filter criterion, which is the text to evaluate the field.

4. To add filters, click More.

5. To remove a filter, click Remove.

6. To change the behavior of the filters, click Settings.

The Advanced Filter Settings dialog box appears.

7. Choose whether to have the query replace previous selections in the list.

   1. To clear previous selections, set the Replace Existing Selection check box.

   2. To make the results of this query select additional items in the list, clear the Replace Existing Selection check box.

8. Choose whether to have case sensitivity turned on or off.

   1. To make case-sensitive matches, set the Case Sensitive Match check box.

   2. To make matches regardless of case sensitivity, clear the Case Sensitive Match check box.

9. Choose an Operator.

   1. To choose the more restrictive “And” operator, click And - All filters must match.

   2. To choose the less restrictive “Or” operator, click Or - Any filter can match.

10. After you have made settings, click OK.

11. Click Apply.

Tip: To hide the Advanced Filter controls, click Close at the top right corner of the Advanced Filter controls.

Tip: If you select the Query Subject item you can use SQL Query as one of your filters. Although SQL Query is not displayed in the grid, it may be used as a filter. This provides the ability to filter on Query Subjects that derive from a specific table in a database.

Set Locales

Select locales to change display labels and names to a different language. The list displays the available locales for that model.

On the Meta Editor toolbar, click Set Locale, and then select the locale.

Tips and Other Features

1. In order to sort a column within the grid in ascending or descending order, simply single-click on the column heading.

2. In order to copy, paste, delete or cut the contents of a cell, right click on any cell within the grid and select the applicable choice.

3. In order to improve the ability to locate objects in the FM tree on the left, various right click options existing from any object in the tree.

   1. Select All Namespaces

   2. Select All Children

   3. Select All Query Subjects

   4. Select All Query Items

   5. Select All Filters

   6. Select All Calculations

   7. Select All Shortcuts

   8. Settings - allows you to control if the selections replace the current selection in the right-side grid or append to them.

   9. De-Select All Children

Note: The popup will be disabled (canceled) if you right click on an object that does not have any children.

Meta Editor Notes

1. In the Meta Editor grid, the Name column will remain frozen as the first column so that scrolling to the right to see the various attributes within the grid retains the Name in the first column regardless of how far you scroll.

2. Selecting items in the hierarchical tree of different types, such as a Query Item and a Query Subject causes the grid to display only the common set properties for these items.

3. In order to save changes to the Model, BMTScriptPlayer.exe is needed. It only needs to be selected once. It is usually located in the <Install location>/bin directory.

Object Editor

The Object Editor Module enables administrators to update a defined set of properties to any specified object in the Content Store,
including the ability to edit and save an object’s raw XML giving the ability to change any supported property within that object.

NOTE: It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM, the user should create a backup of the environment or anything else that is about to change, using the Backup Module.  Transaction Manager does support this module and can be used to revert inadvertent changes.

The objective of this module is not only to change multiple properties, but also to change those properties in multiple objects at the same time. Drag any supported object to the drop area and apply any of the options that have been selected.  
To enable one or more updates, select the checkbox next to “Enable This Option”, the enabled options will be bolded in the panel.

Click the ‘Update’ Button in order to make these changes. A status of “Success” will be displayed if the options were updated without Error.

Report

• Automatically Relink Package – This will automatically re-link an object(s) in the canvas area to their original package.
  NOTE: If the model no longer exists, the report is left broken.

• Clear Report Alert List – This will clear the report subscription alert list.

• Convert to Report Studio/Workspace Advanced – Converts Query Studio and Analysis Studio objects in to Report Studio and Workspace Advanced compatible objects. You have the option to update the name of either the converted, or deprecated reports as well.  This option is designed to allow organizations to stay ahead of any deprecation to Query Studio or Analysis Studio in future releases of Cognos. 

• Link to Package – This will change the package reference of any supported reports.

  • A Package can be dropped from the tree onto the textbox.

    • The Package name will then be displayed within the textbox.

• Run in Advanced Viewer – By default, Cognos BI reports run with limited interactivity. This option will make the reports run with full interactivity.   

• Set Base Report for Report View – Changes the base report for the specified report view.

• Supported types that can be dropped here are:

  • Report Studio Reports

  • Analysis Studio Reports

  • Query Studio Reports

  • Report Templates

• The object being updated must be a reportView for this option to work.

• Set the default execution action – Users can set one of the default actions and apply that property to any supported object(s) dragged to the “Distribute options to” area on the canvas.

• Select the default action within Cognos Connection for selected object(s)

• Drag any supported object into the drop area from the Portal Tree

• This is the list of supported objects:

  • Report Studio Reports

  • Analysis Studio Reports

  • Query Studio Reports

  • Report Templates

  • Report Views

Set the default execution format - Users can set the default format for any supported object(s) dragged to the “Distribute options to” area on the canvas.

• Select the format from the dropdown box that will be the selected object(s) new default.

• This is the list of supported objects:

  • Report Studio Reports

  • Analysis Studio Reports

  • Query Studio Reports

  • Report Views

Set the default execution language – Users can set the default language property for any supported object(s) dragged to the “Distribute options to” area on the canvas.

• Select the language from the dropdown box that will be the selected object(s) new default.

• This is the list of supported objects:

  • Report Studio Reports

  • Analysis Studio Reports

  • Query Studio Reports

  • Report Views

Set Run History Retentions– Ability to select the number of occurrences or duration of time to retain run histories for any supported object(s).

• Select either Occurrences or Duration

  • NOTE: Only Integers are allowed to be entered into the boxes.

• The run history of an object(s) will be updated if:

  • The selected text box contains a valid integer.

  • The selected object supports the Run History property.

Set Report Output Retentions – Ability to select the number of occurrences or duration of time to retain output versions for any supported object(s).

• Select either Occurrences or Duration

  • NOTE: Only Integers are allowed to be entered into the boxes

• The outputs of an object(s) will be updated if:

  • The selected text box contains a valid integer.

  • The selected object supports the output versions property.

Parameters

The Parameters functionality allows users to copy, edit, or remove saved prompt values in bulk. These values would usually be set in IBM Cognos Connection under the Report Properties:

There are two modes in Parameters, the ability to remove store parameters, and to add/update stored parameters.

Remove Stored Parameters – Remove mode allows the user to remove either all prompt parameters from a report, or the parameters specified. To remove all, keep “Remove all parameters” selected, drag your target reports to the bottom grid, and click “Update”. To remove specified parameters, you can either drag a source report to the “Remove specified parameters” textbox, or you can add them manually using the “Add…” button.

When you click the “Add…” link you will be prompted to enter the name of the parameter you would like to add to the textbox.

After you drag a source report to the textbox, you can remove individual parameters from the textbox list by clicking on them to select them and then clicking the “Remove selected” link.

Once you have all of the parameters added to the textbox you can click the “Update” button to update the reports. If the target reports have any of the parameters listed in the “Removed specified parameters” textbox they will be removed from the target report.

• Update Stored Parameters - Allows the user to replace existing parameters, add parameters, or update matching parameters.  The user can either drag a source report to the source report grid or can create new prompts from scratch using the “Add a parameter…” link.

The user can also edit existing saved prompt values. Edit prompts by clicking the edit button:

A new form will open, allowing you to edit the values of the prompt.  In the form you can edit the name of the saved prompt value parameter. You can change the type of the parameter and edit its values. For a text-based parameter. You can edit the Use and Display values by typing directly in the list. You can also reorder and delete them by using the appropriate buttons. You can change the parameter type to be a Simple range, or a Date range. For either type you can select a specify range, or a lowest or highest values for that type of range.

• Replace existing parameters will replace any existing parameters with parameters included in the grid.

• Add all parameters will add all parameters that are currently non-existent to the report.

• Update matching parameters allows the user to choose a source report and copy the saved prompt values from that report to other target reports. Any prompt values in the target reports will be overwritten by the saved prompt values in the source report. To select a source report, drag it from the grid to the Prompt Source textbox. The grid will be populated with the saved prompt values from the source report.

When you are ready, you can click “Update” to update the selected reports.

Routing

Update routing set list – Ability to set the routing hints on an account, group, role, package, or dashboard.

• Type routing sets that are to be appended, separated with a semi-colon.

Clear routing set list– Ability to clear the routing hints on an account, group, role, package or dashboard.

• Drag the account, group, role package or dashboard you want to clear and click update.

Job

Set the job submission mode – Jobs can be run in bulk or in a sequence.

When “All at once” is chosen and the job is executed, all of the reports listed will be run at the same time. This option cannot halt if a report fails because all of the reports are running at the same time.

NOTE: This may result in quicker job completion but will cause more load on the server.

When “In Sequence” is selected the job will execute each report in the order that it is listed in the canvas area. Each report is executed after the prior once completes.

If the “Continue on error” option is selected and the job fails to complete a report, it will continue onto the next report, otherwise it will stop early.

Schedule

Enable/Disable a Schedule – Ability to enable or disable selected scheduled objects.

• Select either Enable or Disable to set the desired action for the selected schedules.

Update Schedule Credentials – Ability to change the credentials of a schedule.

• An account must be dropped from the tree onto the textbox.

  • The Account name will then be displayed within the textbox.

NOTE: The Account must already have an existing Credential

General

Set Owner – Ability to change the Owner of any supported object(s).

• An account must be dropped from the tree onto the textbox.

  • The Account name will then be displayed within the textbox.

Set Contact – Ability to set a contact as an account or by using an e-mail.

• To set an account as the contact:

  • Click the button next to Select Contact

  • Drag and drop an account from the Portal Tree to the textbox.

• To set an e-mail as the contact:

  • Click the button next to Enter Email

  • Type an e-mail address into the textbox.

Find/Replace – This option will give a user find and replace capabilities in the locations specified below.

• Search text must be populated.

• This option can search and replace in 20 different property Locations.

Advanced

Update a property with XML - This interface exposes the raw xml properties of any IBM Cognos object and gives the ability to make changes to the raw xml in bulk.

CAUTION: Editing any XML could have serious harmful and irreversible effects to the Cognos environment. We suggest backing up the entire Content Store before using this tab.

• Raw – This selection in its simplest form will simply replace the specific object in the content store with the user provided XML field.

• Update / Append – This option will add new items or simply change their values (if they already exist) in the target location provided.

• Remove – The items provided by the user XML text will be removed and all others will be left intact.

• XPath Key – This text is used to help break down the user provided text and allow MetaManager^TM find the individual elements to act upon.  When being used Update/Append or the Remove commands, this text will indicate what object (if any) will be manipulated.

  • Examples:  If working on the NAME object and additional names will be provided in different language formats, then the key would read “descendant::locale”.  If the OPTIONS object was provided, then it may read “descendant::name”.  In these examples you can see that we are asking for the descendant items and the key names for each of the fields (name for Options and local for the Name properties).

• XML Body – In each of these cases, the user provided XML will instruct what will change in the content store object.  If the properly formatted XML provided uses the “NAME” object as the ROOT, then the content within that text along with the actions selected (from above) will tell MetaManager^TM how to proceed.

• Update a property with XPath – This generic interface provides the ability to update object properties in bulk, provided that the object supports the property, and the property is currently assigned a value.

• Select a property to update from the Property Name drop down.

  NOTE: Many common properties and their corresponding xpaths have been provided, however any property or xpath may be entered manually if desired.

• Select an XPath from the Property XPath drop down (or enter one in manually)

• Select either the Set Value or Find/Replace Value radio button.

  • o   Search Only will allow the user the ability to only search for and not update the properties.

  • o   Set Value will set the property’s value to whatever is entered in the Value text box

  • o   Find/Replace Value will replace all occurrences of the value in the Search text box with the value in the Replace text box within the property’s value.

  • Remove Result Nodes gives the user the ability to remove the properties from the object(s) selected.

NOTE: Please use extreme CAUTION when using this feature as it is highly advanced and complex. Should you have any questions, please send an email to support@bspsoftware.com describing your use case and we will be happy to help you determine the appropriate values. A demonstration of this functionality is available on our web site (www.bspsoftware.com) under Support >> Podcast Channel >> “3.2: Update almost anything in bulk in MetaManager’s new Object Editor Advanced Tab”.

Run a custom script - allows Object Editor to execute custom MetaManager^TM scripts created with the Script Runner module.  Must own Script Runner to use this functionality.

Object Editor’s “Run Script” functionality can be used to perform various processes in bulk by using input script files. Each function requires a set of arguments. You may specify as many function calls in one script file as you wish, but each script file should be limited to one type of function, i.e. the file would contain only update functions, or only move functions. A set of sample script files are included in the MetaManager^TM installation directory under examples\object editor scripts.

Escaping commas - The input script files are Comma-Separated Value (csv) files. Because of this, if any of your arguments include a comma you will need to enclose that argument in quotes. For example, this search path would need to be enclosed in quotes:

This line would result in a parsing error: CAMID("Local:u:Ari")/folder[@name=‘My Folders’]/report[@name=‘Actual Sales, Target Sales’]

This line is correctly escaped:“CAMID("Local:u:Ari")/folder[@name=‘My Folders’]/report[@name=‘Actual Sales, Target Sales’]”

Supported Functions

1. Update - Can be used to update simple properties. Simple properties are those that have a simple value such as defaultScreenTip. Simple properties have underlying xml that looks similar to this:

Syntax - Update,PropertyName,ObjectSearchPath,Value
Example: Update,defaultDescription,CAMID("Local:u:Ari")/folder[@name='My Folders']/report[@name='Actual Sales against Target Sales'],Actual Sales against Target Sales

2. UpdateRaw – can be used to update more complex properties by supplying a filename that contains the raw xml for the property as one of the arguments.

Syntax - Update,ObjectSearchPath,PathToFile
Example: The file to specify as an argument should contain the raw xml of the property (as viewed in Object Editor’s Advanced Mode).

UpdateRaw,CAMID("Local:u:Ari")/folder[@name='My Folders']/report[@name='Actual Sales against Target Sales'],c:\policies.txt

3. Move - Can be used to move objects from one location to another in the content store.

Syntax - Move,SearchPathOfObjectToMove,SearchPathOfTargetLocation Example: Move,CAMID("Local:u:Ari")/folder[@name='My Folders']/report[@name='Actual Sales against Target Sales'], CAMID("Local:u:Ari")/folder[@name='My Folders']/folder[@name='Samples']

4. Add - Can be used to add new objects in a specified location (typically folders).

Syntax - Add,SearchPathOfTargetLocation,NameOfNewObject,folder
Example: Add,CAMID("Local:u:Ari")/folder[@name='My Folders'],Testing,folder

5. Copy - Can be used to copy one or more objects to a specified location. The Children Only argument can be used to specify whether or not to copy only the children of the specified object. For example, if you wanted to copy only the contents of a folder, but not the folder itself you would specify “true”.

Syntax - Copy,ChildrenOnly,SearchPathOfObjectToCopy,SearchPathOfLocationToCopyTo
Example: Copy,True,CAMID("Local:u:Ari")/folder[@name='My Folders']/folder[@name='Samples'],CAMID("Local:u:Ari")/folder[@name='My Folders']/folder[@name='Testing']

6. Query - Can be used to check for the existence of an object. When the process is complete a log file will be created in the same location as the script file with “_log” appended to its name. The log file will include all the search path entries from the script file, with a true or false to indicate the objects existence.

Syntax - Query,SearchPathOfObject
Example: Query,CAMID("Local:u:Ari")/folder[@name='My Folders']/folder[@name='Samples']

7. Error Handling - You may also supply an additional line of text in your script file to specify if you would like MetaManager^TM to continue processing additional commands if an error is encountered. MetaManager^TM stops processing additional commands by default.

Syntax - ContinueOnError,true

The number of “columns” in the csv script file must be consistent, so you must add additional commas to the end of the ContinueOnError command to be consistent with the other functions you are using in the file. For example, if you are using the Query function, there are only 2 “columns”:

Example: ContinueOnError,true Query,CAMID("Local:u:Ari")/folder[@name='My Folders']/folder[@name='Samples']

If you were using the Update function, you will need to specify 2 additional commas:

Example: ContinueOnError,true,, Update,defaultDescription,CAMID("Local:u:Ari")/folder[@name='My Folders']/report[@name='Actual Sales against Target Sales'],Actual Sales against Target Sales

Object Viewer

Object Viewer provides the capability to edit any Report Studio, Query Studio or Analysis Studio Report specification directly in an XML text editor. The tabbed interface makes it easy to work on multiple reports simultaneously. Object Viewing includes the ability to view XML, Specifications, Parameters and Policies.  Start by double-clicking an object in the Portal Tree, or dragging it over to the editing area. This will create a new tab and show a few of the object’s properties.

The XML View exposes the raw xml properties of any IBM Cognos object. Properties can be viewed, compared, and even edited.

CAUTION: Editing any XML could have serious harmful and irreversible effects to the Cognos environment.

The Properties Area is a set of checkboxes to the right, next to the tabbed interface. There will be a default amount of properties already checked. Any number of properties may be checked. Once selected, the properties will appear as XML in the tabbed interface.

The “Select All” and “Select None” buttons located directly below the properties area makes it easy to select and clear all the properties at once.

The Specification tab provides features for Validating, Diffing & Previewing report modifications before saving them to the content store. To start using these features, search for a report in the Portal Tree and double click the report or drag it to the editing area. The report information will now appear in the canvas area. With the reports specification now visible in the canvas area, a user has the ability to make changes to the specification and save them to the Content Store.

WARNING: Making changes to a reports specification can cause irreversible and detrimental effects to the content. It is recommended to click the Validation button on the tool bar (green check mark) before saving any changes. The Validation results will appear at the bottom of the canvas area.

Parameters

This tab will only show up and populate if the selected object has parameters.  The user can edit existing saved prompt values. Edit prompts by clicking the edit button (see Update Stored Parameters - for more details):

Policies

This tab will only populate if you have access to Security Editor.  On this tab, you can edit the access permissions on this object, adding Users, Groups, or Roles by dragging them over from the content tree.  You can edit the specific permissions by clicking the boxes for Read, Write, Transverse, etc. 

Right-Click Options

There are a variety of right-click options within the canvas area of Object Viewer to make changes and save specifications. Right-click on the tab of a report to view the options below:

Right-click on the XML View tab within the XML for the following edits options:

Right-click on the Specification tab within the specification for the following edits options:

Object Viewer Toolbar

The toolbar for the Object Viewer module enables advanced functionality.

From left to right, the icons are as follows:

Template Blasters

Once a reporting and analytical environment has been established, it is often critical to standardize the look and feel of the environment so that corporate standard templates, etc... can be applied. Template Blasters allows users to easily replicate the look and feel of a standard template to existing reports (public and private).

NOTE: It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM you use the Create a Backup button on the module toolbar to back up the content pre-change.

Standardize Reports

To begin using Template Blasters, you must:

1. Identify the content you wish to standardize.

2. Identify a source report to use as the template.

3. Determine whether headers, footers, prompt page headers and / or prompt page footers are desired in the application.

4. Preview the changes to ensure that the desired results are achieved.

5. Apply the modifications.

Template Blasters Options

The Options tab allows users the ability to specify the criteria to be blasted and the source report to be used for the blast.

The options pane contains a text box that is the drop target for the source report.

NOTE: Only a Report Studio Report can be dragged to this text box.

Other Options include:  

Template Blasters Processing

As Template Blasters is being executed, the report icon on any given Object Row will change to an hourglass while an Object Row is being processed.

1. A triangle marker indicates which step the object row is processing.

2. The validation results are represented in the Current Status field with an icon indicating the status. See below for more information.

Preview

The processing steps for Preview are:

1. The selected report specifications (may come from cache) are loaded into memory.

2. The specifications are then validated against the applicable package in the Content Store.

3. Each option is executed on the target report specifications.

4. The new specifications are then validated against the applicable package in the Content Store.

NOTE: When Preview is used rather than Update, any desired Object Row can be selected, and the specification can be previewed through the right-click menu. This allows for a visual comparison to the stored specification in the Content Store, which can be run through the right-click menu, Run option.

They can also be previewed textually using the Diff Changes right-click menu.

Update

The processing steps for Update are:

1. If the Preview has been performed, execute steps 1 to 4 above.

2. Save the modified specifications in place of the current specification within the Content Store.

Validation Results

The following table lists the possible validation results.

Icon	Validation Result	Description
	OK	Report validated with no problems.
	Exception	Some type of anomaly occurred. Check the Information section to see what exceptions caused a failure.
	Prompt	The report requires prompt answers that could not be supplied as part of the validation processing. All other aspects of the report (namely the syntax / specification) are OK.
	Warnings	The report validation was able to proceed, but with errors that may affect the report integrity. Check the Information section to see where the validation encountered errors.
	Errors	Report validation failed. Check the Information section to see where the validation encountered errors.

An explanation of validation results

Template Blasters Details

The details pane displays the status of the selected Object Row and indicates the specifics of any warnings or errors within a specification. In many cases, the error or warning can be resolved immediately within the Find / Replace module.

NOTE: The boxes are rich text format controls and copy enabled.

Cube Connector

This module is designed to create data source connections for PowerPlay MDC files located on the file system either in a single folder or in a more defined folder structure. By using variables for folder and filenames, datasources can be created and named dynamically for mdc files that follow a strict folder structure. For example, assume a folder existed for 2010, 2011 & 2012. Inside each folder is a Q1, Q2, Q3 & Q4 subfolder, which in turn contains a “actual” and “forecast” mdc files. Using Cube Connector, these 24 cubes can be created in bulk following the naming conventions created by the folder names, such as 2010_Q3_Actual & 2012_Q2_Forecast.

Creating Connections

There are 2 options within the interface:

1. The mapping of all MDC files within a folder structure to an existing data source in IBM Cognos

2. The ability to create new datasources in bulk for all cubes in a folder location..

Mapping to Existing Datasources

To begin, drag a data source to the work grid:

If the datasource doesn’t have existing connections the bottom row for Connection Name will be blank.
In the work grid the root folder containing the cubes needs to be defined. This is the root folder on the file system that contains the mdc files to be created as datasource. As a shortcut you can drag and drop the windows folder to this cell to load the path.
Options can also be defined for the naming convention; the drop-down menu provides the correct syntax for the folder name and filename.

The Default Cache size can be set during the creation of the Connections or can be amended after the connections have been created. The Default Depth determines the level of the folder structure to be traversed when searching for the cubes to be added.

By using the Preview option for the connections to be created can be reviewed and refined if required. The status will show as ‘Pending Creation’.

Using the Update button will commit the Connections to the data source and the status will change to Created.

Creating Datasources from MDC Files

Datasources with Connections can be created in bulk by using the Create Datasources link.

When selected a prompt is displayed to browse the folder structure for the location of the cubes.

Selecting OK will auto populate the grid with data source names and connections.

Select preview to review and refine before updating to commit the new data source connections.

Cube Find/Replace will enable you to quickly re-point your PowerCube data source connections within IBM Cognos Connection to the new location if the Windows or Unix file location of Powerplay cubes has changed.

Updating Connections

It is strongly recommended that before any datasources are changed a backup is created using the Backup module.

The connections to be changed can be dragged from the portal tree view to the main grid. The existing and new file locations are specified in the Search Text and Replace Text boxes. Finally select Windows or Unix for the folder location.

 By selecting preview, the status will update to confirm if the data source connections are impacted.

If the changes are correct, simply select Update to apply. The status will change to Updated.

The cubes can now be deleted from the old path.