Migration

Merging Migration Packages

Pulse allows you to merge existing packages if they haven't already been executed. This allows you to aggregate multiple changes into one large package that can be provided to your operations or run team to upgrade your test and/or production system.

You can merge both Live or Offline packages but you can only merge into the same type. 

Overview

The merge package page lists all of the packages and provides a panel on the right that has the order in which one or more packages are merged. The first package in the list is where all of the subsequent packages will be merged into, the target. Only packages that have not been executed can be the target package. This is to ensure that the history of execution matches the contents of the package. If the package has already been executed it will be displayed in pink to show that it is invalid and can't be merged.

The packages listed below the target package will be merged in order from top to bottom. This is carried out one package at a time, if there are the same objects in 2 or more packages they will be overwritten as the package is merged. This means that the most important package is at the bottom.

A package that has already been executed can't be merged into:

 

Use a Empty Package to Create a Master Package

To maintain the history of packages as they are created in is recommended that you create a empty package and then merge the rest of the packages into this one.

To create an empty package follow these steps:

  1. Go to Migration > Create Package
  2. Select the Manual option (the instance isn't important)
  3. Don't select any objects and click Next.
  4. Click Next on the Review Changes step.
  5. Click Next on the Dependencies step.
  6. Add a Name and Description.
  7. It is important that you select the correct package type, you can only merge packages of the same type.
  8. Click Save.

The package is now ready for packages to be merged into to it.

Merging a Package

  1. Go to the package you want to merge into and click Merge.
  2. Find each package you want to merge into the target and click Merge checkbox.
  3. Repeat until all packages have been added.
  4. Reorder as necessary, the packages at the end of the list will override existing items if they already exist.
  5. Click on the Merge button.

Executing a Migration Package

One of the major benefits of the Pulse migration feature is that you can apply changes to your TM1 instance while it is running. This is especially important if your TM1 instance takes a long time to restart. It also checks for what changes need to be applied and only applies the incremental changes. This reduces the amount of time it takes to apply updates therefore reducing the overall impact.

IMPORTANT: Although Pulse only applies changes incrementally the usual locks and operations will occur just as if the changes were applied manually. This means that the system may become locked and unusable while changes are applied. The largest possible impact is saving rule files with a large number of feeder rules.

Before you can execute a migration package against a target instance of TM1 you first need to meet the following requirements:

  • The package must be installed on the target Pulse instance: Pulse can only execute packages that have either been created on the same server or must be imported into the target server.
  • The target instance of TM1 must be running: Pulse applies changes to TM1 while the server is up and running through a combination of Turbo Integrator functions and API calls.

Now that you are ready to execute the migration package follow these steps:

Options.png
  1. Log into Pulse.
     
  2. Click on Migration > View Packages
     
  3. Find the package you want to execute and click Execute. If it doesn't exist you must download it from the source server and import the package.
     
  4. Now you need to select the instance (only running instances are shown) and the options you want to use to execute the package.
     
    • Backup Data Directory: When ticked Pulse will first run a Save Data All then create a zip file of the whole data directory. This provides backup in case the migration fails. You can change the location of the backup directory on the Configuration page. WARNING: If you have a large data directory it can take a long time to zip up the contents of the directory.
    • Update Documentation Before Compare: Pulse in most cases will automatically track changes in your TM1 model, in rare cases a change may be missed. This option will update all of the model documentation before a comparison is made between the package and the TM1 target model. This means that the comparison will be complete and only the required changes will be applied.
    • Update Documentation After Execution: This option runs the full documentation process after the package has completed ensuring all information is up to date.
    • Update Dependencies Only When Missing: When ticked (default) Pulse will only update dependencies if they do not exist. This is turned on by default so that you do not have unintended consequences from running a migration package. For example you could update a rule and if unticked Pulse will also check and update dimensions associated with that cube. If your dimensions are different in your production environment or are loaded from a database you do not want your development dimension overriding the production one.
    • Refresh Security After Execution: Runs a Security Refresh after the package has completed, this is important if you are migrating rules used in security cubes. It is ticked by default.
    • Exclude Process Credentials in Compare: Each TM1 process has a unique encrypted value that stores the ODBC credentials and other information. Each time you save a process this value is changed. By default Pulse ignores this value when comparing to see if processes are different to updates when only this value has changed. You need to provide ODBC credentials each time you update a process anyway.
    • Line Change Sensitivity (Rules Only): By default this is set at 5 lines, it is used to separate changes in a rule file. The default value (5) will combine changes into one if a change is within 5 lines on either side of another change. If you want to separate all changes use a value of 1.
       
  5. Click Next and Pulse will compare the contents of the package against the target TM1 instance. 
     
    • Untick items you don't want to update.
    • View the individual changes that will be applied to each object by clicking on the double chevron icon on the left.
    • For rule and process changes you can click on the View Changes link and the individual line changes will be displayed in the diff format.
       
  6. Click Next to accept the selected changes.
     
  7. You will then be presented with the Execution page. If you have either a process with an ODBCdatasource or are an Excel TM1 application file you will have two more options to complete before executing the package:
     
    1. For any process with ODBC credentials you need to provide both the user name and password to access the data source.
    2. If you have an Excel file that is being uploaded to an Applications directory you have the option of using the Find & Replace. This option allows you to update instance references within the Excel file before it is uploaded. Only cells that contains strings will be updated, if the cell contains a formula Pulse cannot update this value.
       
  8. Now you can Execute the package. 
     
  9. Displayed will be the status of all of the changes, you can download an Excel version when the package is complete via the Download Log link.

Migrating Documentation Between TM1 Instances

Pulse enables you to not only migrate TM1 objects but also the documentation you have entered into Pulse to describe these objects. This allows you to document your system in one place, i.e. development, and then as you add these objects to your test and production environments the documentation is also updated.

By default the documentation is moved across as part of all of the migration package options. You can also just migrate the documentation if you have objects that already exist on multiple instances and you want to copy the documentation.

To do this follow the steps below:

Source.png
  1. Login into Pulse.
     
  2. Go to Migration > Create Package.
     
  3. Select Documentation Only as the source and the TM1 instance.
     
  4. Click Next to see a list of documentation for every TM1 object.
     
  5. Remove any items you do not what to update and click Next.
     
  6. Now Save the package adding a name and description


Creating a Migration Package with Manual Selection

You can move objects between your TM1 instances by manually selecting the objects you want to migrate. This option gives you 100% flexibility to decide on what is included in the migration package. It also means that you can inadvertently miss some items that are may have been changed, because of this it is recommended that you use the source option whenever possible. 

Below are the steps to create a migration package using the source control.

  1. Go to Migration > Create Package
     
  2. Select the Manual as the source for the package.
     
  3. Select the instance you want to migrate items from.
     
  4. Now you can select which objects you want to include in your package. Toggle between the different objects type using the radio buttons and then select the items using the checkbox in theIncluded column. Alternatively you can select objects in bulk by using the Filter and Add Filtered andRemove Filtered buttons.

    To remove items either uncheck the box in the left hand panel or click on the X in the Selected Objects panel.
     
  5. You will be presented with a list of changes that have been identified matching the items selected in Step 4.
     
  6. Here you can review the files that are going to be included in the package, there can be 1 or 2 files depending on the type of object selected. 
     
  7. After clicking Next you will be presented with the dependencies that Pulse has found for each object in the package. Pulse recursively finds dependencies so there may be many dependencies for each object selected. You have 3 options:
     
    1. Add or update the dependency on the target server.
    2. Add the dependency if the objects doesn't exist (default)
    3. Ignore the dependency. If you choose to ignore the dependency it is possible that the package will fail to execute.
       
  8. You can choose to include/exclude dependencies as required, however it is recommended that you include all dependencies. 
     
  9. Now you can save the package, you must provide a name for the package and also a description. There are two types of packages that can be created:
     
    1. Live Update (Hot Promote): Creates a package that can be executed on a running TM1 instance. These packages do not migrate cube data, views or subsets but provide less down time as a restart is not required.
    2. Offline Update (Cold Promote): Creates a package that contains the native TM1 files that can be copied to the target data directory once TM1 has been stopped. Cube data, views, subsets and all of the other TM1 objects can be migrated in this way. This is the traditional way TM1 objects have been migrated and allows Pulse to fit into your existing process.