Appendix C: Using the ISM Development Project to Migrate Data

the information in this appendix is copied directly from the ivanti service manager online help it describes how to use the ivanti service manager configuration console to create packages, which can be used when migrating data the online help contains additional information about the ivanti service manager development project, such as cautions and limitations about the using the ivanti service manager development project, terminology, information about logs and validation, and examples you perform these tasks in the ivanti service manager configuration console and not in the operations console this appendix contains the following sections create a project see creating a project docid\ oazckiixxshugjnkpasik optional view the project see viewing a project docid\ oazckiixxshugjnkpasik make changes to ivanti service manager see creating a transaction set docid\ oazckiixxshugjnkpasik optional view the transactions sets see viewing transaction sets docid\ oazckiixxshugjnkpasik create a package see creating a package docid\ oazckiixxshugjnkpasik optional view the package see viewing a package docid\ oazckiixxshugjnkpasik assign transaction sets to a package see assigning transaction sets to a package docid\ oazckiixxshugjnkpasik add an aspect to a package see adding an aspect to a package docid\ oazckiixxshugjnkpasik map a package see adding packages to a master package (mapping) docid\ oazckiixxshugjnkpasik close the package see closing a package docid\ oazckiixxshugjnkpasik optional export a package to another system see about exporting a package docid\ oazckiixxshugjnkpasik optional import a package from another system see importing a package docid\ oazckiixxshugjnkpasik if you get errors, see troubleshooting package import errors docid\ oazckiixxshugjnkpasik optional save the package as a file see saving a package as a file docid\ oazckiixxshugjnkpasik optional delete a package see deleting a package docid\ oazckiixxshugjnkpasik after performing all of these steps, you can migrate the data to the target system for information about the packages that have been migrated, see the "viewing the patch log" topic in the ivanti service manager online help creating a project you must create a project before you make any configuration changes if you do not make any projects, all changes are logged to the default project use projects to organize the changes made to ivanti service manager after you create a project and before you make any configuration changes, always select your project from the project drop down list on the top right follow these steps, on the system (such as staging) on which to make changes, to create a project log in to ivanti service manager using your named account and not as an administrator see the ivanti service manager topic called "about using your named account to log in" for information about why you must use your named account to log in click configure application to go to the configuration console click build > heat development project > projects the system displays the projects workspace click new record the system displays a blank project page enter a name and description for the project and click save click refresh you can now see the new project name under the project drop down menu in the top right section of the toolbar (next to the help link) viewing a project from the configuration console, click build > heat development project > projects to display the projects workspace the system displays a list of all the projects double click a project name to see details of the project click the transaction set tab to see a list of the transaction sets in this project see viewing transaction sets docid\ oazckiixxshugjnkpasik click the transaction detail tab to see the details of each transaction set see viewing transaction sets docid\ oazckiixxshugjnkpasik view the activity history by clicking the activity history tab, any attachments by clicking the attachment tab, or the audit history by clicking the audit history tab creating a transaction set every time you add, delete, or modify the ivanti service manager configuration, the system records the changes these recorded changes are called a transaction set for example, every time that you save changes for a business object, the system records the changes in a transaction set the system tracks every change and assigns each change a sequential number from the configuration console, click build > heat development project > projects to display the projects workspace the system displays a list of all the projects from the project drop down menu in the toolbar, select the project to which the changes you are going to make will belong make changes to ivanti service manager as normal for example, you can create a new business object, form, or list in certain cases, when you make changes to ivanti service manager, you must enter your username and password when you create and later export the transaction set as part of a package, the package file exposes the user name and password to avoid exposing this potentially sensitive information, we recommend using a global constant for the username and password when setting up an integration connection, rather than entering actual values for more information, see the "using global constants to hide login id and password information" topic in the ivanti service manager documentation for example of using a global constant in this situation, see the "viewing, cloning, and deleting web service connections" topic in the ivanti service manager documentation if you do not use a global constant for the user name and password, the system removes that information from the transaction set viewing transaction sets from the transaction sets page, you can view the relevant changes that are linked to a transaction set you can search by transaction set id use the transaction set id when creating a package from the configuration console, click build > heat development project > transaction sets to open the transaction sets workspace the system displays a list of all the transaction sets the system displays the following information field description id the id for this transaction set created on the date when the transaction set was created user id the id of the user who created the transaction set session id the id of the session when the transaction set was created db revision the database revision source specifies where the transaction was made adminui means that the change was made in the configuration console, and a tenant url means that the change was made from a package migration project name the name of the ivanti service manager development project to which this transaction set is attached double click a transaction set and click the transaction detail tab to see the following information field description project name the name of the ivanti service manager development project to which this transaction set is attached transaction set id a sequential number linked to the change a transaction set may contain zero or more changes (a zero change indicates the change was aborted, and was not recorded ) detail id a sequential number linked to the change a detail may contain zero or more changes (a zero change indicates the change was aborted, and was not recorded ) user id the id of the user who created the transaction set operation date time the date and time when the change was recorded operation type the type of operation can be c for new record, u for modification, or d for deleted object type the type for which the change applies the values can be businessobject for a business object change, form for a form change, or a business object name such as accountstatus# for change in its data, etc business object the name of the business object to which the change is linked, if any entity name the key for the business object record itself in some cases, it is the guid and in other case, it is a name, such as a business object name, a form name, or a role name source id the key for the business object record itself in some cases, it is the guid and in other case, it is a name, such as a business object name, a form name, or a role name to publish specifies if this transaction set can be published y the change is packaged n this change is a side effect of another change that is published creating a package follow these steps, on the system (such as staging) on which you have made changes, to create a package from the configuration console, click build > heat development package > packages the system displays the packages workspace click new record the system displays a blank package page enter a descriptive name for the package the name must be unique across the system from the type drop down list, select if this is an incremental or master package you cannot edit the type after you save create the package an incremental package is a single change it can contain a set of metadata changes and can be imported and exported there are two types of incremental packages the first type is exported from the tracked changes in the data and metadata every data and metadata change is tracked with a sequence number, which specified the import order the second type is a result of comparing the full metadata from two tenant instances (such as uat and staging) there is no sequence associated with these changes this content comes from the traditional operations console migration a master package contains one or more incremental, master, or file packages the packages in the master package are called sub packages for example, you may want to create a master package with several incremental packages (sub packages) in it in ivanti service manager release , the predicate field is for internal use only do not enter anything here enter a description click save click refresh to see the close package , save as file , and export package icons on the top and the tabs at the bottom viewing a package from the configuration console, click build > heat development package > packages to open the packages workspace the system lists the ivanti service manager development packages double click a package to view its details the system displays the following tabs transaction set tab (for incremental packages only) see viewing transaction sets docid\ oazckiixxshugjnkpasik transaction detail tab (for incremental packages only) see viewing transaction sets docid\ oazckiixxshugjnkpasik package mapping tab (for master packages only) see adding packages to a master package (mapping) docid\ oazckiixxshugjnkpasik package aspect tab see adding an aspect to a package docid\ oazckiixxshugjnkpasik activity history tab see the "about activity history" topic in the ivanti service manager online help attachment tab see the "adding an attachment" topic in the ivanti service manager online help audit history tab see the "about accessing the audit history" topic in the ivanti service manager online help assigning transaction sets to a package you must create an incremental type package before you can assign transaction sets to it see creating a package docid\ oazckiixxshugjnkpasik follow these steps, on the system (such as staging) on which you have made changes, to assign transaction sets to a package from the configuration console, click build > heat development project > transaction sets to open the transaction set workspace select the transaction sets to include in the package click assign to package use the drop down menu to select the name of the package to which to assign the transaction sets and click ok you can also assign a transaction set to a package by clicking build > heat development package > packages to open the packages workspace, clicking the transaction set tab, and clicking add change set to check that the transactions set are in the package, do the following a click build > heat development package > packages the system displays the packages workspace b open the package (if you do not see it, click refresh ) the system opens the package c click the transaction set tab to view all of the transaction sets to remove a transaction set from a package, do the following a click build > heat development package > packages the system displays the packages workspace b open the package (if you do not see it, click refresh ) the system opens the package c click the transaction set tab to view all of the transaction sets d highlight the transaction set e click remove from package to add a transaction set to another package, do the following a click build > heat development package > packages the system displays the packages workspace b open the package (if you do not see it, click refresh ) the system opens the package c click the transaction set tab to view all of the transaction sets d highlight the transaction set to add to the package e click assign to package f select a package name from the drop down list and click ok adding an aspect to a package you can only add aspects to a package if it is open when you created the package, the system copied the aspects from the original package you can remove the original aspects and add new ones from the configuration console, click build > heat development project > transaction sets to open the transaction sets workspace assign one or more transaction sets to a package click the package aspect tab a package can have zero or more aspects when the package is imported into target tenant instance, these aspects are entered into or removed from the target tenant instance to flag the aspect presence view the following information on the package aspect tab field description to uninstall specifies if the aspect should be removed version numeric whole number for this aspect version the version number for an aspect grows in its development life id a unique name for the aspect vendor name the name of the vendor who provides the aspect an example is (such as feature/component), ivanti software vendor id a unique id that identifies the aspect provider currently, the system uses "ivantisoftware" for aspects provided by ivanti software in future releases, other providers will have a unique vendor id created by the id of the administrator who added the aspect created on the date and time when the aspect was created modified by the id of the administrator who modified the aspect modified on the date and time when the aspect was modified click new package aspect the system displays the new package aspect dialog box check is uninstalled if this package aspect is uninstalled enter the following information version number any number id any text vendor id any text click save adding packages to a master package (mapping) if you have a master package, you can add incremental or other master packages to it in this way, the master package contains many changes this eliminates the need to export incremental packages one at a time from the configuration console, click build > heat development package > packages to open the packages workspace open a master package click the package mapping tab click assign package the system displays the new master package mapping form in the sub package field, click the search icon to display a list of packages that can be mapped select a sub package and click use selected heat release package enter a value into the relative order field this determines the relative order of this sub package compared to other sub packages in the master package the system applies the sub packages to the tenant in this order (when you export and import the package) click save repeat steps 4 through 8 to add additional sub packages to the master package closing a package you must close a package before you can use the operations console to migrate it from staging to production closing a package means that you cannot do any more work on it, such as adding or removing packages, adding or removing predicates, changing aspects, and so on you do not have to close a package to export it we recommend that you only close a package after you have completed testing on it and you are ready to migrate it from either staging or uat to production after you close a package, you cannot reopen it when a package is closed, the system does not display the add change set and remove from package buttons on the transaction set tab, nor does it display the new package aspect and delete buttons on the package aspect tab follow these steps to close a package from the configuration console, click build > heat development package > packages the system displays the packages workspace highlight the name of the package to close click close package at the confirmation prompt, click ok about exporting a package you can export a package of any type as an xml file and send it to another system, even if the package is empty you can export any open or closed package you can use any text editor to view the exported package about compacting export data docid\ oazckiixxshugjnkpasikexporting a package docid\ oazckiixxshugjnkpasik about compacting export data compacting export data is a beta feature use it with caution starting in heat service management release 2016 1, you can compact the transaction sets for a package when you export it if you make multiple changes to one business object consecutively, compacting combines the individual changes into one compact change when you import the package, the system only implements the one compacted change instead of the individual changes, which speeds up the process of importing a package for example, if you changed a quick action 12 times consecutively, then without compacting, the package would have 12 transaction sets with compacting, there is only one transaction set there are a few caveats to this the system only compacts changes to metadata the system does not combine creating a business object and changing a business object into one compact package the system only compacts changes to a business object and in this instance, changing a business object does not include creating it the system only compacts changes to the same business object of the same metadata type if you change two business objects, the system does not compact these two changes together exporting a package from the configuration console, click build > heat development package > packages to open the packages workspace highlight the name of the package to export click export package the system gives you the option of compacting the transaction sets this is a beta feature click yes to compact the export data or no to not compact the export data the system exports the package importing a package you should never import a package into the production environment from the configuration console if you have the operations console in place, as this could cause system instability we recommend that you always back up your database before importing a package importing a package is an irreversible operation and cannot be undone you can import a package that has been previously exported for master packages, the system imports the subpackages in the given relative order the system imports the package if its predicate evaluates to true if the predicate evaluates to false or an error, the system does not import the package or its subpackages after importing the package, the system uses the package aspects to update the tenant starting in heat service management release 2016 1, the system scans the import package and assigns one of three impact levels (high, medium, and low) to each package impact level definition high contains a database schema change deletes a business object updates a stored property for a field of a business object updates the islocalized property for a field of a business object updates the data type, length, or precision for a field of a business object updates a unique property for a field of a business object updates a nullable property for a field of a business object changes the index changes the full text search index adds or deletes an audit field medium contains changes to the metadata for a business object adds a business object changes the metadata of a business object, other than the changes described above changes or overrides a business rule changes or deletes a form, list, layout, quick action, pick list definition, dashboard, chart part, list part, or special part changes or deletes a role changes or deletes branding changes a workflow, counter, view part, global constant, request offering, or report changes the email configuration changes integration settings changes the ldap configuration or authentication provider changes the password policy changes an escalation schedule low does not contain a database schema change or changes to the metadata for a business object, or anything listed above adds a form, list, layout, quick action, pick list definition, dashboard, chart part, list part, special part add a role adds branding unlike in previous releases, starting in heat service management release 2016 1, you can sometimes import a package even when the system is in metadata read only mode when the system is in metadata read only mode, note the following for high impact packages, you can only validate the import package you cannot import the package for medium impact packages, you can validate and import the package, but there may be risks with importing the package we highly recommend that you back up the database first for low impact packages, you can validate and import the package we highly recommend that you back up the database first follow these steps to import a package from the configuration console, click build > heat development package > packages to open the packages workspace click import package click browse to navigate to the import package highlight the file and click open the system displays a dialog box that lists the file name of the import package check show detail to see the details of the changes in the import package and then click preview impact to scan the complexity of the import package depending on the impact of the import package, the system displays a screen that lists the details of the import package impact if you do not check show detail, the system only displays the first high or medium level change in the package click close the system displays the import package dialog box stating that you should back up the database before importing the package, and that this action is irreversible do one of the following select validate to check the integrity of the package without applying it if there are any errors, you can go back and fix them before importing the package select validate and apply if no errors to import the package only if there are no errors note that the system may import the package even if there are errors on the application side the system displays a message stating if there are any errors and where they are, either on the application side or on the validation side select apply without validation we do not recommend this option with this option, you assume all responsibility to correct any errors after the import this imports the package even if there are errors you should always validate the package and understand the errors first, and then select this option only if you agree to ignore the errors click execute at the confirmation prompt, click yes the system starts the import process if the package contains many changes, the import process can take a long time your system may time out or you may accidentally get disconnected from the system due to loss of wifi or vpn if this happens, log in again the system continues to import the package and display the importing message however, the system may not dismiss the importing message, even after the import process has finished in this case, click cancel or refresh to dismiss it the system displays a message about the success or failure of the import, including specifying if there are any warnings or errors if there are any errors, you cannot import the package if you do not understand the impact of the errors, we recommend that you restore your database back to the production environment, as the error may disrupt your production operation see troubleshooting package import errors docid\ oazckiixxshugjnkpasik or contact ivanti software for further information about the errors click close to view the imported package, do the following a click build > heat development project > projects to open the projects workspace b under the name column, double click the project that you just imported, to open it troubleshooting package import errors if you get any errors while importing a package, the package import fails you must correct the errors before importing the package if you get any warnings, the import continues; however, we strongly recommend that you correct the warnings before importing the package the system displays warnings in orange text and errors in red text try the following for troubleshooting import package warnings and errors if the error message references a sequence number, open the package in a text editor such as notepad and look for that sequence number examine the package for information from the configuration console, click build > heat development project > transaction sets to open the transaction set workspace open the transaction set associated with the warning or error examine the transaction set for information saving a package as a file you can save an incremental or master package as a file (but you cannot save a package as a file if it is already a file) so that you can have a record of it at a certain time this is similar to versioning the package you can export or import packages saved as files all aspects in the package are copied to the file, but you can edit them after they are copied to the file follow these steps to save a package as a file from the configuration console, click build > heat development package > packages to open the packages workspace highlight the name of the package to save click save as file enter a new name or description, or leave the default values click save the system saves the package as a file click refresh to see the new file in the file list deleting a package you can only delete a package if it is open and if it is not being used by another package from the configuration console, click build > heat development package > packages to open the packages workspace highlight the name of the package to delete click the delete icon