With the release of Apliqo FPM 2024.01, existing Apliqo FPM customers should migrate their metadata and data from their current installation to the new version. To complete the migration the following steps should be followed:

1. Install or update the Catalog Framework by apply the Catalog Framework patch. The Catalog Framework is improved each release. Releases of Apliqo FPM 2024.01 do not include the Catalog Framework and will need the Catalog Framework to be added to the instance. For subsequent Apliqo FPM instance the latest Catalog Framework is required to execute the latest migration catalogs.

2. Update the Catalog Framework to the Latest Release.

3. Import the Migration Catalog on the source and target Apliqo FPM instances. The Migration Catalog contains the catalogs to migrate the metadata and data of the standard Apliqo FPM objects between source and target Apliqo FPM instances.

4. Execute the Migration - Metadata collection on the source Apliqo FPM instance. Review the catalogs and deselect the catalogs that are not been used by the customer. Then export the metadata of the standard Apliqo FPM objects. Execute the Migration - Data collection on the source Apliqo FPM instance. Review the catalogs and deselect the catalogs that are not been used by the customer. This will export the data of the standard Apliqo FPM objects.

5. Import the Migration - Metadata collection on to the target Apliqo FPM instance. Import the Migration - Data collection on to the target Apliqo FPM instance.

6. Splice the rules in the target Apliqo FPM instance

7. Migrate customisation. On the source Apliqo FPM instance create the “Customisation” collection. These will help for future migrations. For each customisation create a catalog. See Catalog Framework for information on how to create a Catalog. Export these catalogs from the source Apliqo FPM instance. Import these catalogs into the target Apliqo FPM instance. Review the changes in the target Apliqo FPM instance and adjust the catalogs as required.

8. Export and Import the customer’s custom web pages and snippets using the ContentStore Toolkit. Copy any custom html, custom css changes between the existing webapp and the upgraded webapp.

9. Perform reconciliation and functional check to confirm the migration has been completed successfully.

10. Go to production.

Limitations of the Migration

Clients and Groups

The Catalog Framework does not export or import TM1 clients and groups.

Passwords

The Catalog Framework does not export or import client passwords. If the client is using IntegratedSecurityMode=1, passwords will need to be manually reset in the target Apliqo FPM instance. Remember to replicate the new passwords to the contentStore using the UXToolkit. This is not an issue for client using IntegratedSecurityMode=5.

Web Pages

Custom webpages are not migrated. Custom webpages should be migration using the ContentStore toolkit.

Custom HTML, CSS, SCSS

Any change to Custome HTML, CSS and SCSS should be migrated through the file system. Remember to GULP to the webapp to compile the SCSS.

Custom Rule Changes

The Catalog Framework can migrate whole rules files for a specific cube but it cannot migrate individual rule changes within an existing rule file.

Errors in the existing Apliqo FPM instance

The migration steps below copy the metadata and data from the existing Apliqo FPM instance to the upgraded Apliqo FPM instance. A number of processes will be run as part of the migration. If any of these processes are failing in the existing Apliqo FPM instance, they will fail in the upgraded Apliqo FPM instance. This not a problem when exporting the migration catalogs. When exporting the catalog, there are few processes executed and there are no metadata changes. The migration collection can be exported as a whole. This can be a problem when importing the migration catalogs into the upgraded Apliqo FPM instance. Processes that fail can lead to TM1 database rollback the changes. Worst case is a rollback loop that needs to terminated using Pulse or Arc.

Dealing with rollback

Once you have terminated the import process a number tmp_xxxxxx folders will be left behind in the Location: Catalog folder. To identify the catalogs that has failed open the readme.csv file in the temp folder. In the readme.csv is the Catalog Name. To find the error with the catalog, open the }apq.server.catalog.import.json file. At the end of this file is the parameter “Type”. The Type indicates how the catalog import process completed for the catalog. If the type is “Success”, the import process completed without errors. If the type is “danger”, the catalog completed with errors. In the }apq.server.catalog.import.json file are the steps completed when importing the catalog. Look for steps that have the type of “Danger”. This means this step completed with errors.

Dealing with errors

There are two approaches to dealing with errors.

1. Correcting the error in the existing Apliqo FPM instance. Run the process that is error in the existing Apliqo FPM instance confirm that you get the same error. Review the log and correct the data to clear the error. This may mean changing the data in the existing Apliqo FPM instance or exporting missing metadata or data in the catalog.

2. Skip the step in the catalog. This mean the step is not executed when the catalog is exported or imported. Go to the catalog that is in error and check the step to be skipped. The error will exist in the upgraded Apliqo FPM instance after the catalog is re-imported. It needs to be corrected after the migration is completed.

Regardless of the approach the catalogs in error, the changes to the catalogs needs be re-exported from the existing Apliqo FPM instance. This can be done by clicking on the Create Catalog button on the Create Catalog tab. Once the all the catalogs that are in error have been re-exported, the collection needs to be imported into the upgraded Apliqo FPM instance. To avoid further rollbacks each catalog in the collection should be individually imported. This can be done in the Collection tab by click on the Import button next to the catalog. Ideally the catalogs should be executed in ordger. Once a catalog has successfully been imported, the change is committed. Most catalogs are self contained some catalogs need to be executed in order.

Apliqo FPM Migration

Prerequisite

• To complete the migration, you will need enough system resources to have both the existing Apliqo FPM and the latest Apliqo FPM running. This can be split over different servers with a shared folder that will contain the migration catalogs.

• TM1RunTI is correctly configure on both Apliqo FPM instances.

• The Rule-Splicing-Tool is correctly configure on both Apliqo FPM instance.

Step 1: Install the Catalog Framework in the existing Apliqo FPM.

On the existing Apliqo FPM instance we need to establish the code changes to establish the Catalog Framework. This will require an outage to promote some catalog process to the data folder of the existing Apliqo FPM instance.

1. Acquire the Catalog Framework.7z catalog. This is the catalog that has the latest catalog framework.

2. On your local machine uncompress the Catalog Framework.7z to a folder, Catalog Framework. If upgrade is been done on a Linux OS it important the processes and subset file names are in lower case. On your local machine rename,

   1. The process in the \Catalog Framework\processes\* folder.

   2. The subset folders and the subsets in the \Catalog Framework\subsets\* folder.

   3. The files in the in the \Catalog Framework\files\* folder.

3. Copy the Catalog Framework folder to the server that hosts the existing Apliqo FPM instance.

4. Save and stop the existing Apliqo FPM instance.

5. From the Catalog Framework folder, copy the files under the follow folders.

   1. …\Catalog Framework\processes\* to the data folder.

   2. …\Catalog Framework\subsets\* to the data folder.

   3. For Linux OS, copy …\Catalog Framework\files\catalog_copy_s3.sh, catalog_rename.sh to the batch folder.

6. Restart the existing Apliqo FPM instance.

7. In ARC run the process }APQ.Server.Catalog.Import. For the pRoot parameter enter the full file name to the Catalog Framework folder. An example on a Linux operating system would be /mnt/data_import/catalogs/framework/catalog framework/. Accept the default values for the other parameters. Run the }APQ.Server.Catalog.Import process. The will import the remaining changes to establish the Catalog framework into the existing Apliqo FPM instance.

8. Using the ContentStore Toolkit, import the webpage a701.z4. The source file can be found in the source data folder under existing Apliqo FPM instance. The webapp should appear in the Administration menu.

The Catalog page item will appear under Administration. The catalog for the Catalog Framework can be seen under the Framework collection.

Open

Go to Settings tab and check the settings are correct for the instance. Most of the settings will have been populated as part of setting up the existings Apliqo FPM. If this is the first time using the Catalog Framework following must set:

• Location: Catalog: Required. This is the directory on the local machine that the catalogs will be export to and import from. If you are using the standard Apliqo FPM files system layout the folder is named “\tm1models\fpm\catalogs” which is on the same level as the data folder.

• Network: Catalog: Optional. Is an alternative directory that catalog files will be stored instead of the Locataion: Catalog directory. This may be a network drive. If the Network: Catalog directory is set the catalogs will be moved between the Network: Catalog and the Location: Catalog whenever the catalog is exported or imported into the Apliqo FPM instance. The Location: Catalog local directory will only be used as a staging directory to compress and uncompress the catalog files.

You have installed the Catalog Framework into the existing Apliqo FPM instance. Continue to Step 2.

Step 2: Install the Catalog Framework on the upgrade Apliqo FPM.

The Catalog Framework is included in the current Apliqo FPM instance. However there have been improvements to the Catalog Framework since the release. To ensure the Catalog Framework is the same between the existing Apliqo FPM instance and the upgraded Apliqo FPM instance it recommend the catalog framework patch applied to the existing Apliqo FPM instance in step 1 to be applied to the update Apliqo FPM instance. Follow the procedure outlined in step 1 to patch the upgrade Apliqo FPM instance. Once that is done continue to Step 3.

Step 3: Import the Migration Catalog

The Migration Catalog has the catalog definition to migrate the metadata and data from the existing Apliqo FPM instance to the update Apliqo FPM instance of all the standard Apliqo FPM objects. Import the Migration Catalog into both the existing Apliqo FPM instance and the upgraded Apliqo FPM instance.

To import the Migration Catalog follow these step:

1. Save the Migration Catalog.7z filt to \[catalog location]\framework\ directory.

2. Go to Administration > Catalog. Click on the Import Catalog tab.

3. This is the first time the Migration Catalog has been imported. Go to Import Catalog tab. In the Import Catalog from File widget enter the full file name for the Migration Catalog.7z file as the Directory parameter value. Leave the remaining options as default and click on the import catalogue button.

   Open

   

Importing migration catalogue will add 2 collections, “Migration - Metadata” and the “Migrate - Data”, to the catalog framework. Click onthe Collection tab to review the Migrate - Metadata and Migrate - Data catalogs.

Open

Open

Step 4: Export the Metadata and Data from the existing Apliqo FPM

The catalogs within the collection are organised by Apliqo FPM module.

1. For the Migrate - Metadata and Migrate - Data collections, review the catalogs. Ensure the catalogs that are used in the existing Apliqo FPM instance are selected. Unselecting the catalogs that are not used in the existing Apliqo FPM instance. For example, if FIN BSEG 3 and FIN BSEG 4 are not being used by the existing Apliqo FPM instance then these catalogs can be left unselected. The standard element for the FIN BSEG 3 and FIN BSEG 4 are included in the upgrade Apliqo FPM package. Special note, Exporting the Revenue and Expense Profiles is done in three catalogues. They should be treated as one catalog when deciding to include or to exclude these catalogues.

2. Review the General Ledger catalog. This catalogue will export the standard archive snapshots from the FIN General Legend cube as individual files. This is done in parallel to save time and manage file size. Additional archive snapshots should be added to this catalog.

   Open

   

3. Export the collection. The entire collection can be exported by clicking on the Export button next to the collection name. Individual catalogs can be exported as well. The catalogs will be export to the \[catalog location]\migrate - metadata directory and \[catalog location]\migrate - data directory.

The time to export the catalogs will depend on the amount of data in the model.

Step 5: Import the Metadata and Data from the existing Apliqo FPM

1. If you are not using a common directory between the existing Apliqo FPM instance and the updated Apliqo FPM instance move the files to the catalog location for the updated Apliqo FPM instance.

2. For the Migrate - Metadata and Migrate - Data collections, review the catalogs. Ensure the catalogs that are used in the existing Apliqo FPM instance are selected. Unselecting the catalogs that are not used in the existing Apliqo FPM instance. This should be the same as Step 4. If you are familiar with the Catalog Framework the Framework\Migration Catalog, catalog can be exported from the existing Apliqo FPM instance and imported to upgrade Apliqo FPM instance.

3. Import the collection. The entire collection can be imported by clicking on the Import button next to the collection name. Individual catalogs can be imported as well.

Step 6: Splice the rules

The upgraded Apliqo FPM instance rules need to be spliced so that rules apply to the same versions, years and months, and currencies that are applied in the existing rules.

1. Click on the Splicer popup.
   
   

   Open

   

2. The Dimensions parameter should be left as Select. Click on the Update Rules button to splice the rules.

Step 7: Customisation

1. On the existing Apliqo FPM instance create a collection called “Customisation”. This collection will be used to create catalogs to migrate the customer's customisations. Create a catalog for each customisation. Add the steps to the catalog to make the changes required for the customisation. For more information about how to create a customisation is Catalog Framework.

2. Export the Customisation collection from the existing Apliqo FPM instance.

3. Import the Customisation catalogs to the updated Apliqo FPM instance. The first time the Customisation catalog is imported into the upgraded Apliqo FPM instance you will need to use the Import Catalog from File. When the catalog is imported the details of the catalog are added to the catalogue framework. Subsequent importation of catalog can be done via the collection tab.

Repeat steps two and three until the catalog is complete.

Step 8: Other Migration Tasks

The migration catalogues will migrate the bulk of the metadata and the data from the existing Apliqo FPM instance to the upgraded Apliqo FPM instance. But not all migration tasks are covered by the Catalog Framework.

• Custom web pages and snippets can be migrated using the Content Store toolkit.

• Custom html, css and scss can be copied through the file system.

• Custom rules need to be added to the cube rules.

• Copy clients private views and subsets from the existing Apliqo FPM instance to the upgraded Apliqo FPM instance via the file system.

Step 9: Check for Accuracy and Completeness

Common sense needs to be used here. Reconcile the movements and the closing balances in the FIN General Ledger cube between the existing Apliqo FPM instance and the upgraded Apliqo FPM instance. Complete month end procedures. Rebuild the chart of accounts and Business Segments. Reconcile reports and dashboards between the existing Apliqo FPM and the upgraded Apliqo FPM.

If you fo find differences then you may need to review the appropriate catalog and adjust as required. Alternatively a custom catalog may be required to make the changes. The process of exporting and importing the metadata and data can be repeated as many times as required to complete the migration.

Step 10: Go to Production

Once you've completed all your checks for accuracy and completeness are complete you can go to production. This may require one last refresh of the metadata and data between the existing Apliqo FPM instance and the upgraded Apliqo FPM instance. Once you satisfied the metadata and data is the same both Apliqo FPM instances are saved and shut down. The data directory of the existing Apliqo FPM instances is archived and the data folder of the upgraded Apliqo FPM instance is coped to production. The production instance is restarted.