Migrate Existing Applications & Synchronize User Permissions

Important! The CDA tools DataMigrator, ApplicationContentMigrator and SyncPermission.ps1 are automatically executed by the Release Manager Unified Upgrade tool (see: Release Manager Unified Upgrade). However, the tools can still be used independently.

Migrate the Existing Applications to the ARA.Applications Folder

When upgrading CDA from versions lower than 9, all existing Applications must be migrated from the UC4.Applications folder to the new ARA.Applications folder.

To Migrate Applications

  1. Close all Automation Engine objects related to the Applications to be migrated (if any).
  2. Execute the ApplicationContentMigrator tool (Automic\Release.Manager\Utilities\ApplicationContentMigrator)
  3. Enter the following commands:

    MIGRATE -constr "araconnection" [-dbtype aradbtype] -H aehost -p port -c client -u username -pw password [-apps application names]

    Where:

    • - constr: Connection string to the Release Manager Database. The connection string must be enclosed in quotation marks "connection".
    • - dbtype: Release Manager database type: MSSQL, ORACLE, POSTGRESQL. Default value: MSSQL.
    • - H: AE host or IP
    • - p: AE port
    • - c: client
    • - u: AE Admin user/department. For example, U1/QA
    • - pw: AE Admin password
    • - apps: list of application names to be migrated, separated by a comma. Leave it blank to migrate all Applications in bulk.

    Important! Alternatively, you can define the input parameters in the ApplicationContentMigrator.exe.config file (Automic\Release.Manager\Utilities\ApplicationContentMigrator) and simply run the MIGRATE command.

    The following options can be also used with the MIGRATE command:

    • - help: displays a list of available commands.
    • - force: If you want to migrate all existing Applications (the -apps option is left blank), it may happen that one or more of them are not compliant with the new structure. You can use the -force option to migrate non-compliant Applications to the new folder and AE objects stored in the Application folder.

      The AE objects are moved to the new structure as follows:

      Current locationNew location
      UC4.APPLICATIONARA.APPLICATION
      UC4.APPLICATION/folder ARA.APPLICATION/folder
      UC4.APPLICATION/folder/ Component folder ARA.APPLICATION/folder/Application/Workflow folder

      Important! The migration process cannot be run again once the force option has been executed. For more information, see ApplicationContentMigrator. Some Applications cannot be migrated in the troubleshooting section.

    • - dryrun: this command can be used to dry run the migration process and see the errors that may occur during an actual migration.

    After running the command, a log file is generated in the logs folder of the tool.

Important! If you have migrated Applications contained in two different CDA instances to the latest version of CDA and some of the Applications were available in both instances, you can use two REST API endpoints to map the GUIDs and identify them as a single Application:

  • GET api/data/v1/applications/{id}: Retrieves the name, GUID of the Application and of all related entities from one of the instances.
  • POST api/data/v1/applications/{id}/identity_mapping: Maps the GUID of the Application to the same Application in the other Instance (only the name is used for the mapping)

Notes:

  • If the IDs or the names of the application do not match, the mapping fails.
  • If some components or workflows are missing, the applications are mapped, but a message with a list of missing components is displayed.

Synchronize User Permissions

After migrating the Applications to the ARA.APPLICATIONS folder, you must synchronize the user/user group permissions so that users can access the new folder structure.

To Synchronize User Permissions

  1. Launch Windows PowerShell and navigate to the directory where the script is located: SyncPermissions.ps1 (Automic\Release.Manager\Utilities\ApplicationContentMigrator)

  2. Execute the script with the following command:

    C:\Automic\Release.Manager\Utilities\

    ApplicationContentMigrator\

    .\SyncPermission.ps1 [[-con] <String>] [[-usr] <String>] [[-pw] <String>] [[-users] <String>][[-timeoutsec] <Int>] [<CommonParameters>]

    Example:

    C:\Automic\Release.Manager\Utilities\

    ApplicationContentMigrator\

    .\SyncPermission.ps1 -con http://localhost/ara -usr CLIENT/USER/DEPARTMENT -pw ***** -users CLIENT/USER/DEPARTMENT -timeoutsec 1200

    Where:

    • -con: connection
    • -usr: username. Contains (system name), client, department, and name to log into the CDA system.
    • -pw: password
    • -users: list of users whose permissions will be synchronized. The users must exist both in CDA and in the AE. Otherwise the permissions synchronization will fail.
    • -timeoutsec: time (in seconds) to wait for the request to complete the synchronization of user permissions.

    Notes:

    • You can update the user permissions of all users in bulk by removing the user definition from the command: [[-users] <String>]
    • If the users parameter is not specified in the command, the default value of the timeout parameter (7200 seconds) is applied.
    • If your are using a multi-tenant CDA system, the system name must be included in the command. Admin rights are required.

      Example:

      SYSTEMNAME/CLIENT/USER/DEPARTMENT

    • After executing the script, a log file is generated in the logs folder of the tool.