Applies to:  Cost Transparency on TBM Studio 12 and later, with Template v104 and later(Learn more) 

Upgrade application components to latest version

This article provides general instructions for upgrading Cost Transparency to the latest template version. Complete the steps in this article only after you have upgraded the application to the latest TBM Studio release. The images in this article are for Release 12.5 with an upgrade from Template v104 to v105, but the instructions will work for any template upgrade. These instructions will prompt you at Step 6 to jump to another article for component-specific instructions, then return to this article to complete the upgrade. 

For a list of the data sets that need to be upgraded, see:

•  Master dataset changes for applications on TBM Studio 12.5
• Master dataset changes for applications on TBM Studio 12.6
• Master dataset changes for applications on TBM Studio 12.7

Best practice for parallel development during upgrade process

If you plan to continue with development activities while you upgrade components, the following best practices are recommended:

• Check in all changes prior to creating an upgrade branch. Ideally, it is best to complete the upgrade and merge the branch as soon as possible.
• If development work needs to continue, the following activities can also continue while an upgrade branch is open:
  • Load data and publish to the Dev, Staging, and Production environments
  • Create new custom reports
  • Modify existing customized reports
• Avoid the following activities until after the branch has been merged:
  • Install new components
  • Append and map datasets to master data sets
  • Change model configurations or allocations
  • Modify out-of-the-box (OOTB) reports

The estimated time to complete the upgrade process depends on the number of components being installed, the amount of customization made to your OOTB reports, and the level of validation needed before you can merge the branch. For example, a recent upgrade of 25 components for Cost Transparency (full stack) and Vendor Insights took approximately 1-1/2 weeks.  

Prerequisite configuration

If you need to upgrade the Cloud Service Provider component, the Cloud Invoice Weighting metric must be configured before you begin the upgrade process.

To update the Cloud Invoice Weighting metric prior to beginning the upgrade process.

1. Navigate to TBM Studio, then in the Project Explorer, click Metrics.
   
2. Find the Cloud Invoice Weighting metric and update as follows:
   • In the Metric Type field, select Costing.
   • Ensure that the value in the Value Calculation field is =TimePeriod(Cloud Invoice,-1).
     
3. Check in the updates.
   
   

Step 1: Create a branch

Before performing this step, upgrade to the latest TBM Studio release.

Perform the upgrade process in a separate branch, rather than in a personal Development environment. 

1. Before creating the branch, complete and check in any changes in your main project.
2. On the Project tab, click Create Branch.
   The Create Branch dialog box opens.
3. Enter a new branch name, for example, “Version Upgrade Branch.”
   
4. Click OK.
   The Calculation Queue dialog opens. Wait for the calculations to complete.
   

Step 2: Open the new branch

Upgrade the project in a separate branch. (Learn more)

1. On the Project tab, click Trunk.
2. Select the branch you want, for example, “Version Upgrade Branch.”
   
   After selecting a branch, you will see the active branch in the menu bar.
   
3. Each time you return to TBM Studio, verify that you are in the correct upgrade branch before proceeding. If not, and Trunk is displayed, you will need to re-select the "Version Upgrade Branch". 

Step 3: Change component version

1. On the Project tab, click Project Settings.
   The Edit Project Settings dialog opens.
2. For Component Version, select the latest version (for example, Version 105).
   
3. Click Save.
4. Check in the change and enter a description, such as “Project Settings: change to [upgrade template version].”
   
   

  (Back to top)

Step 4: Review components to upgrade

Confirm that the new component versions are available, then upgrade them:

1. On the Project tab, click Components.
   The Component Configuration dialog opens.
2. View the list of installed components.
   An arrow in the bottom right corner of each installed component indicates that an upgraded version for that component is available.
   
3. Install and upgrade all components for the new template version. Perform the following step (Step 5) for each component that needs to be upgraded.

Step 5: Upgrade individual components and check in the changes

1. In the Component Configuration dialog, double-click a specific component (for example, CTF - Cost Source).
   A component page opens.
   
2. Scroll down below the list of included reports to the Upgrade Available section. 
   • A blue box indicates that no customizations have been made to any items in the component.
   • A yellow box indicates that customizations have been found with the data, calculated metrics, or reports.
     
     NOTE Occasionally, the yellow box remains after you revert all the customizations. To proceed, click the Upgrade button in the yellow box. 
3. If customizations exist, click View Conflicts, or scroll to the bottom of the page.
4. Revert any customized reports and calculated metrics.
   NOTE  Do not revert the datasets. If any of the standard master data set columns or formulas have been customize, you might need to review the configuration after the upgrade to make sure your datasets have the proper columns and configuration.  See Step 6 for more information.
   
5. Click Upgrade, then confirm that the upgrade arrow is no longer displayed. 
   The application will take a few minutes to process the upgrade. After the component page refreshes and returns to the Component Configuration page, you can continue. 
    
   
6. After the upgrade is complete, you must manually change any other customized datasets that were not reverted. Refer to one of the following cumulative lists to identify what changes are required:
   • Master dataset changes for applications on TBM Studio 12.5
   • Master dataset changes for applications on TBM Studio 12.6
   • Master dataset changes for applications on TBM Studio 12.7  
     NOTE:  This activity could potentially require time to understand and correctly implement the changes to the master dataset. 
     
7. Do the following procedures as needed to revert your customized datasets:
   
   • To add new columns to an existing master data set:
     
     1. Navigate to Tables and check out Cost Source Master Data.
     2. Add a Formula step before the Append step.
     3. In the new Formula step, add the new columns.
        
   • To upgrade the following Cloud Cost Management (CCM) components, perform the steps outlined here, then return to this article:
     
     • CT Apps - AWS Recommendations
     • CTF - Amazon Web Services
     • CTF - Azure
     • CTF - Cloud Service Provider
     • CTF - Public Cloud MTD
     • CTF - CCM to CT Integration
   • To upgrade the following Vendor Insights components, click the corresponding link below for detailed instructions:
     • Vendor Insight Foundation
     • Vendor Insight PO
8. When you are finished updating your customized datasets, check in the changes related to a single component upgrade one at a time, as follows:
   

   CAUTION  Failure to check in components one at a time could result in an error that causes you to lose your work and restart the upgrade from the beginning. 

   1. Select Projects, then click Check In.
      The Check In dialog opens.
   2. Select All items in the left pane (default).
   3. Enter a description of the items in the Message panel.
      NOTE:  Enter a useful description, such as “Cost Source: revert data set changes, upgraded component.” This is critical for the branch merge activities later in this upgrade process. Review Step 9: Merge changes to understand why this is important.
   4. Click Check In.

Step 6: Component-specific upgrade steps

Some components require special instructions:

• v106 Components - Upgrade all Cloud components with instructions for Upgrade Cloud for Cost Transparency R12.6 (v106), then return to the next step in this article.
• v107 Components - Upgrade the Apptio Value Explorer (AVE) with instructions for Upgrade to Apptio Value Explorer 12.7 (v107).

Step 7: Upgrade the remaining components in the upgrade branch

Repeat Steps 4 and 5, above, to upgrade as many components as needed.

While there's no prescriptive order to the component upgrade, it's recommended that you upgrade components in the same order that the object related to the component is allocated in your models. For example, for Cost Transparency, upgrade Cost Source before IT Resource Towers, and IT Resource Towers before Applications.

The recommendation is to upgrade all installed components to the latest release to ensure that you have the latest features and highest quality content; however, you can choose to upgrade only a select set of components with the features you want. Contact Apptio if you have questions.

1. Open the CT Apps-Application component.
2. In the Customized Elements section, look for the following metrics:
   • App Dev (deleted)
   • App Run (deleted)
   • App Run Budget (deleted)
   • App Dev Budget (deleted)
3. Click each missing metrics to revert to the original (stock) version.  
   
4. Check in the change. 
5. Open the CT-Business Units component.
6. In the Customized Elements section, look for the following metrics:
   
   • CapEx Fixed (deleted)
   • CapEx Variable (deleted)
   • Project Investments (deleted)
7. Click each missing metric to revert it to the original (stock) version. 
8. Check in the change. 

(Back to top)

Step 8: Review upgraded application in the upgrade branch

1. On the Project tab, click Calculation Queue.
   The Builds dialog box opens.
2. Verify that the builds have finished.
   You will see a list of the individual check-ins.
   
3. In the navigation bar, select Cost Transparency from the Application menu.
   
4. Select the upgrade branch (for example, Version Upgrade Branch).
   The home page opens.
   
    

Step 9: Compare previous version to the newest version reports

1. Open the Cost Transparency project in a browser.
2. Select Trunk to view the reports for the older template.
3. Open the Cost Transparency project in another browser.
4. Select the Version Upgrade Branch to view the new reports for the upgraded template.
5. Review reports side-by-side.
   
   
   
6. If desired, re-apply customer-specific changes to the reports directly in the Version Upgrade Branch.
   RECOMMENDATION:  Avoid making changes to out-of-the-box reports so you can minimize the effort involved with future upgrades. 
   RECOMMENDATION:  If report customizations must be made, apply them to the out-of-the-box reports after you complete Step 7 to merge the upgrade changes. This will minimize the amount of time you have to work in the Version Upgrade Branch. Remember, DO NOT make changes (other than data loads) into the main project (Trunk) after you create your upgrade branch.
7. After you verify the latest version of the reports, proceed to Step 9 to merge the changes into your main project.

 (Back to top)

Step 10: Merge changes into the main project (Trunk)

TIP: Refer to Branching, Hotfix, and Branch best practices in Product Central.

NOTE: Do not merge all changes in one step.  If you do, the merge process will fail.  The recommendation is to merge small batches of check-in records (up to 5 records) at one time.  This will require keeping notes to ensure that all check in records get merged into the trunk in the proper order.  

1. Return to TBM Studio.
2. Select the upgrade branch (for example, Version Upgrade Branch).
3. On the Project tab, click Check In History.
4. Scroll down to the bottom of the list, then click and begin with the first item above the “bootstrap” entries. (This should be the “Project Settings: change to [new template version]” check-in.)
   NOTE: You can select additional items to check in as a single merge, but select no more than 5 items at one time.
   

   CAUTION Merging more than 5 items in a single check-in could cause the application to fail. 

5. Right-click the line item and select Merge changes to branch.
   This example uses the CT-F Cost Source merge item.
6. Select Trunk as the recipient of the merge.
   
   The Merge Changesets dialog box opens.
7. Select all items for merge (default).
   NOTE:  Do not de-select any individual items. 
8. Click OK.
   
   RECOMMENDATION:  Manually track your merged steps as you upgrade the components because the Check In History dialog won't indicate which items have been merged. If you attempt to check in an item twice and the following message appears, click Cancel, then proceed with a different component. 
   
9. After complete, the window should switch to Trunk. If not, change to Trunk to check in the merged item in your project.
10. To verify that the change has propagated to the Development environment:
    1. In the navigation bar, select the In Development environment.
    2. Click the Project tab.
    3. Click Components.
    4. Verify that the component no longer displays the upgrade arrow, as in this example, for the CTF- Cost Source component.
       
11. From the Environment menu in the navigation bar, select Staging.
12. In the Project ribbon, ensure that the Locked icon is grayed out (not locked).
    You need to do this only once.
13. From the Environment menu in the navigation bar, select In Development, then click Check In.
    The Check In dialog opens.
14. Select all items in the left pane (default). 
    This should be limited to the merged items.
15. Enter a description of the items in the Message panel.
    RECOMMENDATION:  Use a useful description such as “Merge – CTF- Cost Source: revert Service Costing report customizations, upgrade component.”  
16. Click Check In.
    
    Wait for the build to complete.
    
17. Verify that the expected change from the branch merge step is applied to the Staging environment.
    In this example, on the Project tab, click Components to verify that the new template version s now active.
    
18. Return to the upgrade branch (for example, Version Upgrade Branch) to proceed with the next item to merge.
19. Repeat the above steps to continue merging up to 5 individual upgrade branches (at one time) and subsequent Trunk check-ins (in Development) until all have been merged.

 (Back to top)

Step 11: Validate latest version reports in the main project (Trunk)

1. Open the Cost Transparency project in one browser.
2. Select Trunk to view the upgraded reports.
3. Open the Cost Transparency project in a second browser.
4. Select Version Upgrade Branch to compare.
5. Compare and review reports side-by-side.
   
6. If desired, re-apply customer-specific changes to the reports directly in the main (for example, Trunk) branch.
   RECOMMENDATION  Avoid making changes to the out-of-the-box reports to minimize the effort involved with future upgrades.  

Step 12: Upgrade the Production environment

After you finish verifying the reports, push the upgraded application to Production.

1. Go to TBM Studio.
2. Select the Staging environment.
3. On the Project ribbon, click Lock.
   A brief pop-up message will indicate that the environment is locked. The environment is now ready to promote to Production.
   
4. On the Projects ribbon, click Promotion Options, then do one of the following:
   • Click Promote Now. The upgrade is pushed to Production immediately.
   • Click Promote Later to schedule wehn the upgrade will be published to Production.
     
5. On the Project ribbon, click Calculation Queue to verify the production build.
6. Compare the build numbers for the Development, Staging, and Production environments.
   
    

Step 13: Close the upgrade branch

1. Select the Version Upgrade Branch.
2. On the Project ribbon, click Close Branch.
   The Confirm Close dialog opens.
3. Click OK to close the branch.
   
4. Confirm that "Trunk" is no longer displayed in the navigation bar. 
   
   
   RECOMMENDATION:  Close the upgrade branch as soon as possible. The branch consumes the same amount of resources as the main trunk project. Closing the upgrade branch will free up resources and improve the overall performance.
   
   

Step 13: Make Infrastructure reports visible

Beginning with TBM Studio 12.6 (and Template v106), the Infra Server and Storage reports moved to the Infrastructure Insights report collection. Because of this change, the default in Frontdoor shows that the reports are viewable by “Nobody,” which can create confusion when you try to access your old reports. To correct the navigation, see Update visibility of Infrastructure reports after v106 upgrade. 

 (Back to top)