Integrated Version ControlTM

General Configuration

Integrated Version Control^TM provides versioning, check in/Check out, and self-service deployment capabilities to IBM Cognos Analytics reports.

Integrated Change Management

Integrated Change Management^TM (ICM) is an extension to Integrated Version Control^TM which replaces the standard locking functionality for Authoring Tool objects with a Check In / Check Out workflow. This process is mimicked today by copying a report to My Content, working on it and then moving back on top of the original report. ICM provides an automated process for this, while also locking the report and requiring commentary and tracking ID information.   It also preserves the unique content store ID.

While ICM is enabled, a report in the Report Authoring Tool, that resides in the Team Content is considered locked to Authors by default and must be checked out locally (to My Content) for editing from within Report Authoring Tool.  Unlike locking, SDK applications are permitted to modify public objects that are not checked out.  This is permitted because objects are locked by default and an SDK application is unable to checkout an object to a local area in the same manner that a user can.

ICM only applies to objects that are located in the Team Content.  Reports that are located in the user’s My Content (that are not local checked out copies) as well as other report types are not subject to any type of locking. When working on a new report, it has not been determined if the report will reside in the user’s My Content or in the Team Content.  Therefore this new report is not subject to locking until the report has been saved.  At the time the report is saved in Team Content, the user will be presented with a commentary dialog to provide comments and a tracking ID for the new report.  After the initial save, the report is immediately lock,ed and further modification requires that the report be checked out.

While a report is checked out to the user’s My Content, the author may work on the report for any amount of time and save the report often. Since the report is local, iterative saving will not affect the public copy of the report.  The locked public copy of the report will remain untouched until after the local version is checked in.  This is one of the benefits of Change Management over standard report locking.  Revision history is preserved for the local copy of the report as an author performs iterative saves. However, when the report is checked into Team Content, the local copy is delet,ed and a report version is spiked in Team Content.  Report Authors that have reports checked out have the option to “Check In” a report into the Team Content or “Undo Check Out” which will throw away the local work and unlocks the public copy.  Standard report locking provides a mechanism for unlocking reports on behalf of other users.

Checked Out Objects

Integrated Version Control^TM stores information about an object, such as the name and location along with the revision history. When a report is deleted from the IBM Cognos Analytics Environment, it is permanently deleted from the IBM Cognos Content store, and the object versions will become

External Tracking ID

Tracking IDs are a critical part of tying together work that is performed in the IBM Cognos Analytics Environment with an external system that manages and tracks work to be performed.  If tracking IDs are not applicable in the environment, then this feature can be disabled and the User Interface elements will not display. If a third party change management or bug tracking system is used, enter the preferred report tracking ID label in the text box provided. This label will be used throughout the product wherever tracking IDs are displayed or entered.

Enable Report Tracking ID – The user can turn this feature on and off if they are using an external tracking or ticketing system.  The textbox to enter a Tracking ID will not appear in the Checkin process if this is disabled.

Require Tracking ID – When checking in reports a tracking id can be required by enabling that option.  It forces the users to supply a change request or ticket number to the changes they have made to the report.

External Tracking System URL – If the system is web enabled, then provide the URL necessary to display a Change Request by ID.  Enter this URL into the textbox and place the “{0}” where the tracking ID should be replaced in the URL. Ty,pically this would show up in a query string such as: http://cr/show_cr.cgi?id={0}.

Self Service Deployment

Integrated Version Control^TM provides a Self-Service Deployment feature where a designated user, group or role with the Self-Service Deployment capability will be permitted to deploy a report to a target environment directly from the Revision History screen, or the object’s context sensitive menu or the object’s ellipsis dropdown action menu, in team content. The user is prompted for a tracking ID and commentary when deploying a report.  This information will be used in the source ICS database for auditing and report of deployments history, the information will also be sent to the target server, which if Integrated Version Control^TM is installed and enabled, will be used to spike a version of the report. If the Ticket Management system for modifying a report is the same as the system for deploying reports, it is important that the label provided in the textbox is exactly the same as the one in the “External Tracking ID” text box in the preceding section.  In this situation, when a user deploys a report the tracking ID will automatically be copied to the tracking ID text box in the deploy dialog.  If there are separate systems for modifying reports and for deploying reports, then provide a unique label name.  This will instruct the software to copy the tracking ID into the comments section along with the version commentary and leave the deployment tracking ID text box blank.

Enable one-click deployment – is the most common setting for the self-service deployment feature.  This option assumes that the folder structure between the environments is identical and therefore the user can simply deploy the report with no questions asked.

Enable deploy to specified folder – allows the user to deploy the report to a target folder.  It is recommended that this option be disabled when it is not needed, for instance, when folder structures are mirrored, and asking the user to select a location could result in a mistake.

Include security policies when deploying – will set the default value of this option in Self-Service Deployment and in the Integrated Deployment Manager Edit Project dialog.  Setting this default will reduce the risk of the user making a mistake that is against the security policy. The user has the option during the deployment to select if the object’s security should be deployed to the next environment.   Either the policy is that the security across the environments is exactly the same and therefore security should be deployed, or the policy is that the security is intentionally different and should not be deployed.

Show edit report -- option allows you to show and hide the ‘Edit Report’ menu option for objects in the Team Content drawer.

Report Maintenance

Baseline

Integrated Version Control^TM provides a mechanism for creating a version baseline for every trackable object in the environment.  To use this feature the System Administrator credential must be valid.  When running a baseline every single object in the environment will be resaved, causing the model version to be upgraded, the modification time to be updated and a report version to be spiked.  A comment for the version can be provided in the Baseline Comment text box.

Baseline only new objects without versions – Selecting this option will only spike a baseline version for new objects that do not have versions.  This is useful in new installations or after running a content import of new objects. A content import does not cause a version to be saved

Verify latest version matches content store – The user can opt to compare the Content Store copy of the object to the latest IVC version to ensure that they are in sync, if so the object will be skipped.  If n,ot then the object will be saved and a version spiked.  This is recommended after running a content import over existing objects.  Note that running the baseline process will re-save the object which can have side effects such as upgrading the model or updating the modification time.

Checked Out Objects

The checked out objects table gives you a quick all in one view of all the checked out objects. It also allows you to see when the object was checked out and by who. From this table you have the option to undo any checked out objects you see here.

Orphaned Objects

Integrated Version Control^TM stores information about an object, such as the name and location along with the revision history. When a report is deleted from the IBM Cognos Analytics Environment, it is permanently deleted from the IBM Cognos Content store, and the object versions will become “orphaned” in the ICS repository.  Typically ICS knows immediately when an object becomes orphaned, however a consistency check can be run by selecting the “Run” button, shown below. This long running background process requires System Administrator credential on the Configuration tab.  The regenerate process will compare each object record in the ICS database with each report in the IBM Cognos Content store.  If there is a match for the object record then the object is not orphaned.  If there is no corresponding object then it is considered orphaned.

There are actions that can be taken with an orphaned object.

Recover Version – The object can be recovered, which will recreate the object in its original location in the content store.  Note that the ICS system does not restore security, schedule, object parameters or run history.  For this functionality, enable the Integrated Recycle Bin. 

Repoint Version– This feature (similar to export/import version history) will merge the orphaned object versions with an existing object in the content store.  Use of this option will cause the object versions to be renumbered. 

Delete this version – This option will delete the selected item from the orphaned list.