Deploy

Introduction

Once a reporting and analytical environment has been established, it is important to perform periodic backups of the environment in the event of corruption, accidental deletion or other unexpected loss of content occurs. We strongly recommend that in addition to using the Backup, Restore, or Deploy Modules of MetaManager^TM, you consult the IBM Cognos product documentation for more information on performing full Content Store backups, etc.

In addition to backup up and restore of desired Content Store objects, users may deploy objects from one environment to another.

NOTE: It is strongly recommended that before any changes are made to reports using restore or deploy modules of MetaManager^TM you create a backup of the content pre-change.

Backup

The Backup Module enables users to perform dynamic backups of any available Content Store content. To begin using the Backup Module, you must:

1. Select the ‘Include’ options.

Include Ancestors

Include ancestors option will back up the ancestors (parent, grandparent, etc.) of the selected object(s) within the grid area. This can be helpful in instances where not just the specified objects are desired, but their full ancestry as well.

NOTE: The ancestors option is only effective while it is selected. Selecting items while it is unchecked, then checking it before running the backup will not automatically include the ancestors, only ancestors added while the option is selected, or ancestors selected through other means, will be included.

2. Identify the content you wish to archive.

NOTE: Searches or containers (i.e., folders, packages, accounts) dragged to the Search pane will be stored as dynamic queries rather than a static list. When running from a command line this will ensure that you get any new content.

NOTE: Archiving content with Backup copies the XML specification(s), location, security and various other attributes of objects stored in the content store to the identified backup location.

NOTE: The content selected can be filtered on and include or exclude sub-items.

3. Filter the objects that need backed up.

   Depth – Select the depth you want to backup, to include this item only or all subfolders.
   

   

Filter – Click the filter image to filter on sub-objects that is required to backup (it defaults to backup all types). Selecting only reports or only security objects based on a specific use case will result is small backups and more flexibility to the user.

Apply to all rows – allows the user to make the criteria selection once and apply the filter to all objects in the current grid area.

4. Specify the output file location that will archive the objects to a local or network drive.

NOTE: Once a location and file name is specified, an extension of .mmz will be applied to the backup file name.

NOTE: Specifying an existing archive file name and path will cause the original file to be overwritten. It will not append the new information to the file.

5. Provide any comments on the contents of the archive or any other information to be displayed when restoring or deploying the archived contents.

6. Run the backup.

NOTE: As reports are processed, the results are listed in the Status column.

NOTE: Creating a backup brings all selected information about each object into memory on the local machine. This information can become quite large. If you see out of memory errors you may want to try selecting the option to ‘Allow the use of temp files to conserve memory’ in the performance tab of the options window. More information about this feature can be found in the options window section of this document.

Backup Processing

As Backup is being executed, the Status 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 Backup results are represented in the Status field. See below for more information.

Backup Results

The following table lists the possible backup results.

Restore

The Restore Module enables users to perform partial and / or full restoration of any selected archive file. Restore offers the ability to;

1. Place any or all of the contents of the backup archive back in the same location as it existed at the time of the backup, and / or

2. Place any or all of the contents of the backup archive in any supported other location within the Content Store.

To begin using the Restore Module, you must:

1. Identify the desired backup archive to recover.

NOTE: The Comments text box can be useful in determining if the appropriate archive has been selected, along with the date / time stamp on the archive file.

2. 1.      Determine any / all content within the backup archive to recover.

3. 1.      Determine the location(s) to restore the recovered content to.

NOTE: Archived objects can be restored in several ways

• By dragging them to the bottom right pane (see image below), the objects will be restored to the original location from where they were archived.

• By dragging them to the desired location in the Portal Tree view within the Restore tab, they objects will be restored (copied to) the desired location(s). NOTE: A single object can be restored to multiple locations within one restore.

4. Determine the restoration options desired via the checkboxes and link(s) in the Options section.

   Overwrite	Enables automatic replacement of the currently available objects in the content store with those contained in the archive file. When selected, objects in the archive file will take precedence over those in the Content Store. If unselected, any existing objects in the target location will not change from the backup.
   Restore Security	Enables the security of the objects in the archive file to remain intact when restored. If unselected, the security of the existing objects (if an object of the same name exists) or parent object will be applied on the restored object.
   Set Owner to Current	Enables the owner of the restored objects in the archive file to be set to the user performing the restore. If unselected, the owner of the restored objects will be set to the owner at the time of the backup.
   Security Only	If selected, this will restore only security for the object(s).
   Set Schedule Credentials to Current	If selected, it will restore any schedule credentials with the user currently logged into MetaManagerTM.
   Advanced Security Mapping	Provides the capability to supply a mapping file if restoring objects between environments and the CAMID’s vary between those environments.

5. Run the restore.

NOTE: As reports are processed, the results are listed in the Status column.

Restore Processing

As Restore is being executed, the Status 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 Restore results are represented in the Status field. See below for more information.

NOTE: If restoring an item fails because the Owner no longer exists (or is unavailable) in the security namespace, the owner property will be removed. The item will be restored without specifying an owner.

NOTE: If restoring an item fails because a member of the policies (object security) no longer exists (or is unavailable) in the security namespace, the policies property will be removed. The item will be restored without specifying security.

NOTE: If restoring an item fails because the applicable model and package is unavailable, the metadataModel & metadataModelPackage properties will be removed. The item will be restored without linking to a package.

NOTE: Other properties that cause the restoration to fail may be dynamically removed to successfully restore at least part of the object. If it suspected that occurred, check the log files for more information. A log file will be written for each failing property that is removed.

Restore Results

The following table lists the possible restore results.

An explanation of restore results.

NOTE: Save Log File link, exports detailed information about the restore process.

Context Menus Specific to Restore Items Pane

Within the Archive Content pane, restore has two context menus unique to this module.

Restore

Similar to dragging them to the bottom right pane, the objects will be restored to the original location from where they were archived.

Restore (Exclude Children)

This context menu item is just like Restore, however if a container object is selected, only the object will be restored and not its children.

Deployment

The Deployment Module is designed to deploy objects from one environment to another (a source and a target environment). Optionally a mapping file may be supplied if CAMID’s vary between the two environments.

To begin using the Deployment Module, you must:

1. Determine any objects that will be deployed and drop them onto the canvas area.

2. Select the target server, in which the objects will be deployed.

3. Optionally supply a mapping file if the CAMID’s in the two environments are different.

4. Click “Deploy”

The mapping file is a tab delimited text file that contains a row for each CAMID to map. The first column is the CAMID in the source environment and the second column is the corresponding CAMID in the target environment. This mapping file can be generated automatically using the Extended Module Security Replicator.

It is visible that the Namespace will change, within the CAMID, between the two environments. Accounts, Groups, and Roles can be mapped using this file during the deploy process.

NOTE: In order to successfully deploy, both IBM Cognos environments should have the same naming conventions for data sources, packages, etc. If package names are not the same, after deploying use the Find / Replace module re-link the objects to a new package.

NOTE: Save Log File link, exports detailed information about the deploy process.

Content Extractor

The Content Extractor enables users to extract archived content from scheduled reports that are stored in the Content Store database out to a specified file system location. The content is automatically renamed to reflect the name in IBM Cognos Connection, with the run date / time stamp appended. Using content extractor allows the user to specify which outputs, (within a report, folder or package) they wish to sync to the file system. This module can be run using command line mode.

Folder Structure – The “Tree” option will produce a hierarchy folder structure within the root folder you have provided. The “Flat” option will simple add the documents directly to the root folder provided.

Stream Download – By default Content Extractor will download entire outputs at once. If "Stream Download" is selected, the outputs downloaded will be streamed instead.

Pagelet Blasters

Once an IBM Cognos environment has been established, the goal is to ease the user experience and drive adoption. This can be facilitated through the creation of custom pagelets (“portal tabs”) within IBM Cognos Connection. Creating, distributing and maintaining custom portal tabs aids in the ease of use of IBM Cognos Connection. Pagelet Blasters allows users to distribute custom portal tabs to any and all named users, groups and roles. Pagelet Blasters also allows the user to set the default home page and reorder the pagelets for users.

NOTE: It is strongly recommended that before any changes are made to reports using this and any other module of MetaManager^TM

Providing Easy Access to Content with Portal Tabs

To begin using Pagelet Blasters, you must:

1. Identify the portal tabs you wish to distribute, set as default or remove from users.

2. Determine the order of portal tabs to be distributed.

3. Identify the recipients of the portal tabs, or if appropriate, the users that will have portal tabs removed from their portal.

4. Distribute and / or remove portal tabs.

Pagelets Area

The Pagelet area displays what pagelets are going to be processed for each account.

The Action column can be set to:

The list of portal tabs will be blasted in the order that they are displayed and will be added after any existing portal tabs that each recipient has access to.

• If the recipient is already consuming a portal tab that is in the list to be added, the existing portal tab will first be removed from the user and then re-distributed. This is done so that the portal tab(s) will be blasted in the correct order.

• A portal tab can be removed from the list by selecting the delete button.

• Multiple portal tabs can be removed from the list by selecting them and clicking the Delete key on the keyboard.

• Portal tab rows can be reordered by using the Up or Down arrow buttons in the right most columns.

Accounts Area

The accounts area displays each account that will be updated with the new portal tabs. Accounts can be added to the accounts grid in several ways.

1. The user can drag accounts to the grid from the portal tree.

2. The user can drag a group or role from the portal tree. All accounts associated with the selected group or role will be loaded and displayed in the grid

3. The user can drag a folder, favorite or search to the grid area. Any accounts contained in these queries will be added to the grid.

4. Users can right-click on an existing portal tab object in the portal tree and select Find Pagelet Consumers. The results or any subset of the results can be dragged to the accounts area.

5. Users can remove accounts from the grid by clicking the delete button in the right most column or by selecting multiple rows and selecting the delete key on the keyboard.

Pagelet Blasters Processing

While processing, the account icon will change to an hourglass.

1. The list of accounts is inspected to determine if any accounts are missing an IBM Cognos profile.

   1. If any accounts are missing a profile, the user performing the blast is prompted to either force distribution or skip these users.

   2. If the account does not have a profile and force distribution is selected, the account profile is created by MetaManager^TM.

   3. If the account does not have a profile and force distribution is not selected, the account is skipped.

2. The results are represented in the Status field. See below for more information.

The following table lists the possible distribution / removal results.

Preferences Blasters

The Preferences Blasters Module enables administrators to distribute preferences to any user, group or role within a Cognos environment. The preferences that can be distributed are the preferences found in Cognos Connection under My Area >> My Preferences >> The General Tab. Unlike the IBM Cognos interface of changing preferences one account at a time, MetaManager^TM’s Preference Blaster has the ability to blast preferences to any number of users, groups, and roles at once. Simply drag and drop from the Portal Tree into the canvas area and select Update.

Setting Preferences to Distribute

Separate in List View – Allows the user to separate entries within their Public Folders and My Folders

• Check the box next to Separate in List View in order to enable the option to be blasted.

• This option is selected by using the drop-down box to pick a separator.

Styles – Allows the user to apply a uniformed look and feel within the Cognos 8 Suite.

• Check the box next to Styles in order to enable the option to be blasted.

• This option is selected by using the drop-down box to pick a style.

• Custom styles can be added to the list by selecting the pencil icon.

Product Language – Allows the user to select any supported language that is displayed in the Cognos 8 user interface.

• Check the box next to Product Language in order to enable the option to be blasted.

• This option is selected by using the drop-down box to pick a language.

Time Zone – Allows the user to select a time zone.

• Check the box next to Time Zone in order to enable the option to be blasted.

• This option is selected by using the drop-down box to pick a time zone.

Report Format – Allows the user to select the format in which the report will be viewed.

• Check the box next to Report Format in order to enable the option to be blasted.

• This option is selected by using the drop-down box to pick a format.

Number of Columns in Details View – Allows the user to set the max number of columns that will be displayed for the details view.

Content Language – Allows the user to select any supported language that will be viewed or produced within Cognos 8 Suite.

Show the Welcome Page at Startup – Allows the user to select if they would prefer the Welcome page to be displayed at startup.

• Check the box next to Show the Welcome Page at Startup in order to enable the option to be blasted.

• Check the box to the right in order to display the Welcome Screen at startup.

• Unselect the box to the right to skip the Welcome Screen at startup.

Show a Summary of the Run Options – Allows the user to select if they would prefer to show the summary of the run options when a report is not run interactively.

• Check the box next to Show a Summary of the Run Options in order to enable the option to be blasted.

• Check the box to the right in order to show the summary of run options.

• Unselect the box to the right to skip the summary of run options.

Default View – Allows the user to select, which view (List or Details) they would prefer as their default.

• Check the box next to Default View in order to enable the option to be blasted.

• Select the radio button of the default view that is preferred.

Automatic Refresh Rate in Seconds – Allows the user to select the refresh rate, in seconds, of the portal interface within Cognos 8.

• Check the box next to Automatic Refresh Rate in Seconds in order to enable the option to be blasted.

• Enter the amount of seconds preferred to trigger a refresh.

Number of Entries in List View – Allows the user to select the max number of rows that will appear in the list view.

• Check the box next to Number of Entries in List View in order to enable the option to be blasted.

• Enter the amount of entries preferred in the list view.

Schedule Blaster

The Schedule Blaster Module has the ability to Replicate, Blast and Edit multiple report schedules in bulk. Schedule Blaster is intended to copy the schedule information from a source object to a target object. Schedule Blaster also has the ability to clear multiple reports of their schedules.

• Report

• Analysis

• Query

• ReportTemplate

• JobDefinition

Replicate Mode

The Replicate tab was designed to bulk replicate an object schedule to several other objects. This technique will copy and replace all schedule settings to the target objects.

The user can drag any supported target object from the Portal Tree to the top grid area they wish to inherit the schedule from the source report.

Drag and drop a report to the source report text box. The text box will display the base class’s name and the schedule details will be displayed below. If there is no schedule associated with the object in the source textbox it will be stated in the display area below.

NOTE: If “Update” is clicked while a report in the source textbox has no schedule, any object in the top canvas area will have their schedules cleared.

Click “Update” to complete the schedule replication.

Blast Mode

The blast tab was designed to let the user blast other users or email addresses on the recipient list for a scheduled report. The user can drag users to different fields and select all reports to blast this report to. The fields that are available to drag users, accounts or email addresses are To: CC; BCC: and a field to Remove objects.

The user can drag any supported object from the Portal Tree to the “Reports to update:” grid area they wish to blast the content to the target objects. Then drag and drop accounts to the fields they wish to blast. The user has a few different options before blasting the content.

Add Email Addresses – This link will display a pop-up and allow you to type any email address to insert into a location you select from the dropdown box. The dropdown box will allow you to select:

Replace – By selecting this option you will completely replace (remove/add) all of the schedule’s emails with the selections made to the email fields.
Append – By selecting this option you will not replace, only add users to the fields you chose in the email fields.
Remove – By selecting this option it will enable the “Remove Recipients:” field. Any account or email you add to that filed will allow the user to delete that email from the target objects, schedules.

Edit Mode

The Edit tab was designed to facilitate the bulk appending or replacing of recipients on a list of scheduled objects. The target must already have a schedule before it can be edited in this mode.

The user as the option to Drag an Account or supported object to the grid area to edit. The object must have a schedule in order to be edited.

After an Account is added to the grid you are able to see any schedules, they are receiving emails from. The user then has the option to edit that or add new scheduled objects, by dragging and dropping directly under the user. To edit the “Field” you must select the scheduled object and click the “Toggle Field” link. Make the appropriate changes and click the “Save Changes” link in the bottom right corner.

In the same way as the Blast Mode, the user is able to drag and drop accounts and enter emails manually to a scheduled object that was added to the grid. Again, click the “Save Changes” link to update.

Job Runner

Job Runner is designed to enable the execution of IBM Cognos Jobs from either the MetaManager^TM user interface or from command line. This enables scheduling systems the ability to execute Jobs based on the outcome of the job execution results.

The module was written for the purpose of receiving a Return Code. When run from command line, a job status code is returned enabling other scheduled tasks to be executed based upon the success or failure of the job. This is useful when running multiple scheduled tasks that depend on the outcome of the previous task.

Compare

Compare is designed to allow a quick visual comparison between objects within two different IBM Cognos environments.  This is especially helpful when troubleshooting issues between environments before and after deployments/promotions.

The user can also use an mmz file as the source to compare against a target environment.

Clicking the arrow icon next to a folder will expand the folder to view contents.

To begin, select a Source Environment and Target Environment from the dropdown menu at the top of the page.

By default, the entire content store will be compared, but using the “Select Base Folder…” link allows the user to limit the compare to a smaller subset of objects.

By selecting an object from the Source or Target Environment, the object will be highlighted and MetaManager^TM will provide a quick comparison of common properties between the object in two environments.  If the object exists only in one environment, it will not show up on the list.  A green icon indicated the property is the same, while the red icon indicates a difference. 

MetaManager^TM also shows the specific XML coding for the selected property.

Right clicking on an object gives the user several additional options:

• Edit Report

  • Selecting “Edit Report” will open up the Specification Editor Module.

• Inspect

  • Selecting “Inspect” will open up the Object Editor module.

• Deploy

  • Selecting “Deploy” will open the Deployment module.

• Diff

  • Selecting “Diff…” invokes the Diff feature if a 3rd party file comparison program has been supplied. The 3rd party file comparison program is specified in the options screen.

Compare Reports

The Compare Reports module allows you to compare a report, set of reports, or folder of reports against the same subset of reports in another environment.

Select a Source environment, navigate down through the portal tree, and drag a report to the upper right panel.  Select the Target tab, select a target environment and navigate through the portal tree and drag the report you wish to compare to the upper right panel.  If you want to compare more than one report, or a folder of reports, repeat the steps above adding additional reports or folders.

Click Compare to run the comparison.  When finished, click the small triangle next to the report to expand the tree to see four different report outputs, XML, PDF, HTML, and CSV.  Each of these versions will show if it is equal or not equal to the output in the other environment. 

Note: PDF and HTML versions often appear as different because of date/timestamps.

As with the compare module, you can see a full comparison of all report properties, with a Quick Compare and XML view. 

If you wish to output the comparison results, enter an output file location at this time and click the Excel Output icon in the toolbar.

The Excel output is especially helpful if you are comparing several reports, as it gives you a quick reference to find multiple outputs which are unequal.

There is also functionality to Diff any two outputs by right clicking on a report output to launch a Diffing tool.