Copy Objects in a Batch: Update Packages

In some cases, you may need to update the objects in several folders at once, or at a time when the source project is offline. Object Manager allows you to save the objects you want to copy in an update package, and import that package into any number of destination projects at a later date.

For example, you have several developers who are each responsible for a subset of the objects in the development project. The developers can submit update packages, with a list of the objects in the packages, to the project administrator. The administrator can then import those packages into the test project to apply the changes from each developer. If a change causes a problem with the test project, the administrator can undo the package import process.

If your update package includes any schema objects, you may need to update the project schema after importing the package. For more information about updating the schema after importing an update package, see Update Packages and Updating the Project Schema.

About Update Packages

An update package is a file containing a set of object definitions and conflict resolution rules. When you create an update package, you first add objects, and then specify how any conflict involving the objects is resolved. For more information on resolving conflicts with objects, see Resolve Conflicts when Copying Objects.

In addition to the standard Object Manager conflict resolution rules (see Resolve Conflicts when Copying Objects), two additional rules are available for update packages:

• Force Replace: Replace the object in the destination project with the version of the object in the update package, even if both versions of the object have the same Version ID.
• Delete: Delete the object from the destination project. The version of the object in the update package is not imported into the destination project.

If the object in the destination has any used-by dependencies when you import the update package, the import will fail.

Object Manager supports the following kinds of update packages:

• Project update packages contain application and schema objects from a single project.
• Configuration update packages contain configuration objects from a single project source.
• Project security update packages contain security information about users and user groups, such as privileges, security roles, and security filters, for a single project. Since these update packages involve users and groups, which are configuration objects, they are created at the same time as configuration update packages.
• Undo packages enable you to reverse the changes made by importing one of the other types of packages. You create undo packages based on existing update packages. For more information about undo packages, including instructions on creating and importing them, see Rolling Back Changes: Undo Packages.

Updating Project Access Information for Users and Groups

You can include users and groups in a configuration update package. However, the project access information, such as privileges, security roles, and security filters, for those users and groups is not included in the configuration update package, because this information can be different for each project.

Specifically, configuration update packages do not include the information found in the Project Access and Security Filter categories of the User Editor or Group Editor. All other user and group information is included in the configuration update package when you add a user or group to the package.

To update your users and groups with the project access information for each project, you must create a project security update package for each project. You create these packages at the same time that you create the configuration update package, by selecting the Create project security packages check box and specifying which projects you want to create a project security update package for. For detailed instructions on creating a configuration update package and project security update packages, see Creating a Configuration Update Package.

You must import the configuration update package before importing the project security update packages.

Creating an Update Package

You create update packages from within Object Manager. From the Create Package dialog box, you select the objects to copy from the source project, and the rules that govern the cases when these objects already exist in the destination project.

You can also create update packages from the command line, using rules specified in an XML file. In the Create Package dialog box, you specify a container object, such as a folder, search object, or object prompt, and specify the conflict resolution rules. Object Manager creates an XML file based on your specifications. You can then use that XML file to create an update package that contains all objects included in the container. For more information and instructions, see Creating an Update Package from the Command Line.

To Create a Project Update Package

1. In Object Manager, log in to a project.
2. From the Tools menu, select Create Package.

   

   You can also open this dialog box from the Conflict Resolution dialog box by clicking Create Package. In this case, all objects in the Conflict Resolution dialog box, and all dependents of those objects, are automatically included in the package.

   

Adding Objects to the Package

1. To add objects to the package, do one of the following:
   • Drag and drop objects from the Object Browser into the Create Package dialog box.
   • Click Add. Select the desired objects and click >. Then click OK.
   • Click Add. You can import the results of a previously saved search object.
2. To add the dependents of all objects to the package, click Add all used dependencies.

   If the dependent objects for a specific object do not exist in either the destination project source or in the update package, the update package cannot be applied. If you choose not to add dependent objects to the package, make sure that all dependent objects are included in the destination project source.

3. To add the dependents of specific objects, select those objects, right-click, and select Add used dependencies.

Configuring the Package

1. To change the conflict resolution action for an object, double-click the Action column for the object and select the new action from the drop-down list. For an explanation of the actions, see Resolve Conflicts when Copying Objects.
2. Select the schema update options for this package. For more details on these options, see Update Packages and Updating the Project Schema.
3. Select the ACL options for objects in this package. For more details on these options, see Resolve Conflicts when Copying Objects.

Saving the Package

1. Enter the name and location of the package file in the Save As field. The default file extension for update packages is .mmp.

   You can set the default location in the Object Manager Preferences dialog box, in the Object Manager: Browsing category.

2. To save a log file containing information about the package's contents in the Object Manager directory, from the File menu select Save As Text File or Save As Excel File.
3. When you have added all objects to the package, click Proceed.

Creating a Configuration Update Package

A configuration update package contains configuration objects from a project source, instead of application and schema objects from a single project. As such, configuration update packages are created at the project source level.

If you choose to include users or groups in a configuration update package, project access information (such as privileges, security roles, and security filters) is not included in the configuration package. To migrate project access information about the users or groups, you must create a project security update package for each project at the same time you create the configuration update package. For more information about project security packages, see Updating Project Access Information for Users and Groups.

To Create a Configuration Update Package

1. In Object Manager, log in to a project source.
2. In the folder list, select the top-level project source.
3. From the Tools menu, select Create Configuration Package.

   You can also open this dialog box from the Conflict Resolution dialog box by clicking Create Package. In this case, all objects in the Conflict Resolution dialog box, and all dependents of those objects, are automatically included in the package.

   

Adding Configuration Objects to the Package

1. To add configuration objects to the package, click Add Configuration Objects.
2. Search for the objects you want to add to the package.
3. When the objects are loaded in the search area, click and drag them to the Create Package dialog box.
4. When you have added all the desired objects to the package, close the Configuration - Search for Objects dialog box.

5. To add the dependents of all objects to the package, click Add all used dependencies.

   If the dependent objects for a specific object do not exist in either the destination project source or in the update package, the update package cannot be applied. If you choose not to add dependent objects to the package, make sure that all dependent objects are included in the destination project source.

6. To add the dependents of specific objects, select those objects and click Add used dependencies.

Creating Packages for Project-Level User and Group Access

1. If your project includes users or groups, and you want to include project-level information about those users or groups, select the Create project security packages check box. For information about project security packages, see Updating Project Access Information for Users and Groups.
2. In the Projects area, select the check boxes next to the projects you want to create project security packages for.

Configuring the Package

1. To change the conflict resolution action for an object, double-click the Action column for the object and select the new action from the drop-down list. For an explanation of the actions, see Resolve Conflicts when Copying Objects.

   If you are creating project security update packages, you must select Replace as the conflict resolution action for all users and groups. Otherwise the project-level security information about those users and groups is not copied into the destination project.

2. Select the ACL options for objects in this package. For more details on these options, see Resolve Conflicts when Copying Objects.

Saving the Package

1. Enter the name and location of the package file in the Save As field. The default file extension for update packages is .mmp.

   Project security update packages are named ProjectSource_ProjectName.mmp, and are created in the same location as the configuration update package.

2. To save a log file containing information about the package's contents in the Object Manager directory, from the File menu select Save As Text File or Save As Excel File.
3. When you have added all objects to the package, click Proceed.

Creating an Update Package from the Command Line

You may want to schedule the creation of an update package at a later time, so that the project is not locked during normal business hours. Or you may want to create a package containing certain objects on a specific schedule. For example, you may want to create a new package every week that contains all the new metrics from the development project.

You can use Object Manager to create an XML file specifying what objects are to be included in the update package. That XML file can then be used to create the package from the command line.

The XML file specifies a container object in the source project, that is, a folder, search object, or object prompt. When you create the package from the XML file, all objects included in that container object are included in the update package, as listed in the table below:

If the XML file specifies a...	The update package contains...
Folder	All objects in the folder
Search object	All objects returned by the search
Object prompt	All objects returned by the prompt

To create an XML file for a configuration update package, see Manually Creating an Update Package Creation XML File. You cannot create a configuration update package XML file from within Object Manager because container objects do not exist at the project source level.

To Create an XML File for Creating an Update Package from the Command Line

1. In Object Manager, log in to a project.
2. From the Tools menu, select Create Package.

Adding a Container Object to the Package

1. Click Add.
2. You need to specify what to use as a container object. You can use a search object, object prompt, or folder. To specify a search object or object prompt as the container object:
   • Make sure the Import selected objects option is selected.
   • In the Available objects area, browse to the search object or object prompt.
   • Select the search object or object prompt and click >.
3. OR, to specify a folder as the container object:
   • Select the Import folder and children recursively option.
   • Type the name of the folder in the field, or click ... (the browse button) and browse to the folder.
4. Select the Return as a container to create XML checkbox.
5. Click OK.
6. To add the dependents of all objects to the package, select the Add all used dependencies check box. All dependent objects of all objects included in the container object will be included in the package when it is created.

   If the dependent objects for a specific object do not exist in either the destination project or in the update package, the update package cannot be applied. If you choose not to include dependent objects in the package, make sure that all dependent objects are included in the destination project.

Configuring the Package

1. To change the conflict resolution action for an object, double-click the Action column for the object and select the new action from the drop-down list. For an explanation of the actions, see Resolve Conflicts when Copying Objects.
2. Select the schema update options for this package. For more details on these options, see Update Packages and Updating the Project Schema.
3. Select the ACL options for objects in this package. For more details on these options, see Resolve Conflicts when Copying Objects.

Saving the XML File

1. Enter the name and location of the package file to be created by this XML in the Save As field. The default file extension for update packages is .mmp.

   You can set the default location in the Object Manager Preferences dialog box, in the Object Manager: Browsing category.

2. Click Create XML. You are prompted to type the name and location of the XML file. By default, this is the same as the name and location of the package file, with an .xml extension instead of .mmp.
3. Click Save.

To Create an Update Package from an XML File

Creating a package from the command line locks the project metadata for the duration of the package creation. Other users cannot make any changes to the project until it becomes unlocked. For detailed information about the effects of locking a project, see Lock Projects.

Call the Project Merge executable, projectmerge.exe, with the following parameters:

Effect	Parameter
Use this XML file to create an update package (required)	-fFilename.xml
Log into the project source with this password (the login ID to be used is stored in the XML file)	-spPassword
Log into the project with this password (the login ID to be used is stored in the XML file)	-smpPassword
Suppress status updates (useful for creating an update package in the background, so that the status window does not appear)	-sup

Manually Creating an Update Package Creation XML File

You can also create the XML file to create an update package without opening Object Manager. To do this, you first copy a sample XML file that contains the necessary parameters, and then edit that copy to include a list of the objects to be migrated and conflict resolution rules for those objects.

This is the only way to create an XML file to create a configuration update package.

Sample package creation XML files for project update packages and configuration update packages are in the Object Manager folder. By default this folder is C:\Program Files (x86)\MicroStrategy\Object Manager\.

The XML file has the same structure as an XML file created using the Project Merge Wizard. For more information about creating an XML file for use with Project Merge, see Merge Projects to Synchronize Objects.

High-Level Steps to Manually Create an Update Package Creation XML File

1. Make a copy of one of the sample XML files:
   • To create a project update package, copy the file createProjectPackage.xml.
   • To create a configuration update package, copy the file createConfigPackage.xml.
2. Edit your copy of the XML file to include the following information, in the appropriate XML tags:
   • SearchID (project update package only): The GUID of a search object that returns the objects to be added to the project update package.
   • TimeStamp (configuration update package only): A timestamp, of the form MM/DD/YYYY hh:mm:ss (am/pm). All configuration objects modified after that timestamp are included in the update package.
   • PackageFile: The name and path of the update package. If a package with this name already exists in this path, the creation timestamp is appended to the name of the package created by this file.
   • AddDependents:
     • Yes for the package to include all dependents of all objects in the package.
     • No for the package to only include the specified objects.
   • Location: In a three-tier system, this is the name of the machine that is used to connect to the project source. In a two-tier system, this is the DSN used to connect to the project source.
   • Project (project update package only): The project containing the objects to include in the update package.
   • ConnectionMode:
     • 2-tier for a direct (2-tier) project source connection.
     • 3-tier for a server (3-tier) project source connection.
3. AuthenticationMode: The authentication mode used to connect to the project source, either Standard or Windows.
4. Login: The user name to connect to the project source. You must provide a password for the user name when you run the XML file from the command line.
5. For a project update package, you can specify conflict resolution rules for individual objects. In an Operation block, specify the ID (GUID) and Type of the object, and the action to be taken. For information about the actions that can be taken in conflict resolution, see Resolve Conflicts when Copying Objects.
6. Save the XML file.
7. When you are ready to create the update package from the XML file, call the Project Merge executable, projectmerge.exe, as described in To Create an Update Package from an XML File.

Editing an Update Package

You can make changes to an update package after it has been created. You can remove objects from the package, change the conflict resolution rules for objects in the package, and set the schema update and ACL options for the package.

You cannot add objects to an update package once it has been created. Instead, you can create a new package containing those objects.

To Edit an Update Package

1. In Object Manager, log in to a project or project source.
2. From the Tools menu, select Import Package or Import Configuration Package.
3. In the Selected Package field, type the name and path of the update package, or click ... (the browse button) to browse to the update package.
4. Click Edit. The Editing pane opens at the bottom of the dialog box, as shown below.

   

5. To change the conflict resolution action for an object, double-click in the Definition Rule column for that object and, from the drop-down list, select the new conflict resolution rule.

   When you edit a package, the Create New action is changed to the Replace action.

6. To rename an object in the destination project, double-click in the Rename column for that object and type the new name for the object.
7. To remove an object from the update package, select the object and click Remove.
8. You can also change the schema update options (for a project update package only) or the access control list conflict resolution options. For information about the schema update options, see Update Packages and Updating the Project Schema. For information about the ACL conflict resolution options, see Resolve Conflicts when Copying Objects.
9. To create a text file containing a list of the objects in the update package and their conflict resolution actions, click Export.
10. When you are done making changes to the update package, click Save As. The default new name for the update package is the original name of the package with a date and time stamp appended. Click Save.

Importing an Update Package

An update package is saved in a file, and can be freely copied and moved between machines.

Importing a package causes the project metadata to become locked for the duration of the import. Other users cannot make any changes to the project until it becomes unlocked. For detailed information about the effects of locking a project, see Lock Projects.

You can import an update package into a project or project source in the following ways:

• From within Object Manager: You can use the Object Manager graphical interface to import an update package.
• From the command line: MicroStrategy provides a command line utility for importing update packages. You can use a scheduler such as Windows Scheduler to import the package at a later time, such as when the load on the destination project is light.

  The command line Import Package utility only supports Standard and Windows Authentication. If your project source uses a different form of authentication, you cannot use the Import Package utility to import an update package.

  You can also create an XML file to import an update package from the command line, similar to using an XML file to create an update package as described in Creating an Update Package from the Command Line.

• Using a Command Manager script: You can also execute a Command Manager script to import an update package without using Object Manager. Command Manager is an administrative tool that enables you to perform various administrative and project development tasks by using text commands that can be saved as scripts. For more information about Command Manager, see Automating Administrative Tasks with Command Manager.

To Import an Update Package from Object Manager

1. In Object Manager, log in to the destination project or project source.

2. From the Tools menu, select Import Package (for a project update package) or Import Configuration Package (for a configuration update package).

   

3. In the Selected Package field, type the name and path of the update package, or click ... (the browse button) to browse to the update package.
4. In the Undo Package Options, select whether to import this update package, generate an undo package for this update package, or both. For more information about undo packages, see Rolling Back Changes: Undo Packages.
5. To create a log file describing the changes that would be made if the update package were imported, instead of importing the update package, select the Generate Log Only checkbox.

6. Click Proceed.

   Any objects that exist in different folders in the update package and the destination project are handled according to the Synchronize folder locations in source and destination for migrated objects preference in the Migration category in the Object Manager Preferences dialog box.

7. If the package made any changes to the project schema, you may need to update the schema for the changes to take effect. To update the project schema, from the Object Manager Project menu, select Update Schema.

To Import an Update Package from the Command Line

Call the Import Package executable, MAImportPackage.exe. By default, this file is located in C:\Program Files (x86)\Common Files\MicroStrategy. Use the following parameters:

Only Standard Authentication and Windows Authentication are supported by the Import Package utility.

Effect	Parameter
Import package into this project source (required)	-n ProjectSourceName
Log into the project source with this MicroStrategy username and password, using standard authentication (required unless you are using Windows authentication)	-u UserName -p Password
Import this package into the specified project source (required) The location must be specified relative to the Intelligence Server machine, not relative to the machine running the Import Package utility.	-f PackageLocation
Import the package into this project (required for project update packages)	-j ProjectName
Log information about the import process to this file The location of the log file must be specified relative to the machine running the Import Package utility.	-l LogLocation
Force a configuration or project lock prior to importing the package. This lock is released after the package is imported. For more information about project and configuration locking, see Lock Projects.	-forcelocking

A full list of parameters can be accessed from a command prompt by entering importpackage.exe -h.

To Import an Update Package Using an XML File

Create the XML File

1. In Object Manager, log in to the destination project or project source.
2. From the Tools menu, select Import Package (for a project update package) or Import Configuration Package (for a configuration update package).
3. In the Selected Package field, type the name and path of the update package, or click ... (the browse button) to browse to the update package.
4. Select the Save import package XML file checkbox.
5. Click Proceed. You are prompted to type the name and location of the XML file. By default, this is the same as the name and location of the package file, with an .xml extension instead of .mmp. Click Save.
6. When you are ready to import the update package, call the Project Merge executable, projectmerge.exe, with the following parameters:

Effect	Parameter
Use this XML file to import an update package (required)	-fFilename.xml
Log into the project source with this password (the login ID to be used is stored in the XML file)	-spPassword
Log into the project with this password (the login ID to be used is stored in the XML file)	-smpPassword
Suppress status updates (useful for importing an update package in the background, so that the status window does not appear)	-sup

To Import an Update Package Using Command Manager

Call a Command Manager script that contains the following command:

IMPORT PACKAGE "Filename.mmp" [FOR PROJECT "ProjectName"];

where "Filename" is the name and location of the update package, and "ProjectName" is the name of the project that the update is to be applied to.

If the package made any changes to the project schema, you need to update the schema for the changes to take effect. The syntax for updating the schema in a Command Manager script is

UPDATE SCHEMA [REFRESHSCHEMA] [RECALTABLEKEYS] [RECALTABLELOGICAL] [RECALOBJECTCACHE] FOR PROJECT "ProjectName";

Update Packages and Updating the Project Schema

If a project update package contains new or replacement schema objects, then when the package is imported the user must update the in-memory definitions of these objects. This is done by updating the project schema.

When you create an update package, you can configure it to automatically perform the following schema update functions:

• Recalculate table keys and fact entry levels, if you changed the key structure of a table or if you changed the level at which a fact is stored.
• Recalculate table logical sizes, to override any modifications that you have made to logical table sizes. (Logical table sizes affect how the MicroStrategy SQL Engine determines which tables to use in a query.)

The update package cannot recalculate the object client cache size, and it cannot update the schema logical information. These tasks must be performed manually. So, for example, if you import an attribute that has a new attribute form, you must manually update the project schema before any objects in the project can use that attribute form.

You can update the project schema in the following ways:

• In Object Manager, select the project and, from the Project menu, select Update Schema.
• In Developer, log into the project and, from the Schema menu, select Update Schema.
• Call a Command Manager script with the following command:

UPDATE SCHEMA [REFRESHSCHEMA] [RECALTABLEKEYS] [RECALTABLELOGICAL] [RECALOBJECTCACHE] FOR PROJECT "projectname";

Updating the schema can also be accomplished by unloading and reloading the project. For information on loading and unloading projects, see Setting the Status of a Project.

For more detailed information about updating the project schema, see the Optimizing and Maintaining your Project section in the Project Design Help.

Rolling Back Changes: Undo Packages

You can use undo packages to roll back the changes made by an update package. An undo package is an automatically created update package consisting of all the objects in an update package, as they are currently configured in the destination project. For example, if you create an undo package for an update package containing a new version of three metrics, the undo package contains the version of those three metrics that currently exists in the destination project.

When you import an update package, you have the option of creating an undo package at the same time as the import. Alternately, you can choose to create an undo package without importing the associated update package.

You import an undo package in the same way as you import any update package. When you import an undo package, the Version ID and Modification Date of all objects in the undo package are restored to their values before the original update package was imported.

The Intelligence Server change journal records the importing of both the original update package and the undo package. Importing an undo package does not remove the change journal record of the original update package. For more information about the change journal, see Monitor System Activity: Change Journaling.