CMT Transfer	Top

Overview	Top

When you are ready to transfer configuration changes to another system, you can do so using CMT Transfer.

Transfers (Export) can be initiated in two ways:

The Transfer process includes:

Export

When configuration changes are complete, create the transfer package. You have two options:

The transfer package includes:

Upon execution of the Export, the Export XML file is zipped (<Export>.zip) downloaded to the client.

Import

Once exported, Import the transfer package to the target system. The Import process lets you:

OOB, most SDCs have been configured in the CMT Policy accordingly. However, you may want to make changes such as include additional SDIs or specify available Import Options. See Configuring CMT for detailed information.  

The following sections detail the Export and Import process using a simple SDC as an example. The section Special Transfer Considerations details the special handling of more complex SDCs (such as Property Trees, and Schedule Plans).

Export	Top

Choose to Export an entire Change Request, one or more individual Change Logs, or all Change Logs associated with an SDI. From either the Change Request List page, Change Log List page or the SDI list page, click "Export". This starts the Export Wizard.

Choose to Export all Change Logs associated with a single Change Request, or one or more Change Logs. From the Change Request List page or the Change Log List page click "Export". Exporting from a Change Request or Change Log exports the SDI Snapshot(s) of any associated Change Logs.

The Export Wizard walks you through the following steps:

Click "Next" to set the Export options.

Choose to include additional details by checking "Verbose Log".

Decide whether or not to also export the original Check Out SDI Snapshot (before changes) for each SDI.
When "Yes" matching is initiated during Import. The Source and Target databases are "matched". Any differences between the target system, and the pre-change configuration on the source (Check Out SDI Snapshot) are identified so that you can manage the Import Options for each. This ensures you are aware of any changes made to the target system since Check Out.

Clicking "Next" performs various validations against the Change Request and Change Logs.

All items (SDIs) included in the transfer package are listed. This provides a preview of what will be exported and identifies any Validation errors.

Click "Next" to set options that define the Export file details.

Here you can change the Export file name. The default zip file name appends a current time stamp in the fixed format of yyyy-MM-dd-HH-mm. This ensures that if the same transfer package is exported repeatedly, the most recent file is easily distinguishable.

Optionally, add additional notes to describe the Export.

Clicking "Next" executes the Export SDI Action.

Export progress is shown.

Click "Finish" to close the dialog.

When finished, the Export zip file is downloaded to the client. Following is an example of the contents of the exported file.  

Content	Description
attachments Folder	Contains any Attachments associated with the SDI.   NOTE:   Attachment files are "managed". Note that the attachment file names are obscured.
manifest.json	Provides a manifest detailing the Transfer Package. The two SDI Snapshot "Post_Image" details (the two SDIs included in the transfer package) are highlighted below.
WorkItem_TM_D_1__1.xml SDI Snapshot (Check In)	XML File detailing the content of the Check In SDI Snapshot. When included (during Export), an XML file detailing the pre-change SDI Snapshot is also included.

All transfer packages will by default have a Checksum generated on Export. This checksum is used during the Import process to validate the authenticity of the Package being imported.
There are 2 types of checksum present inside a transfer package.

The "Global - Block Invalid Checksum" CMT Policy option determines whether or not to allow an Invalid Checksum Package to be imported. Regardless of the value selected, a warning will be displayed at Import if the Checksum validation fails. See Checksum Validation for more information.

As a result of exporting, the system creates a Transfer Log (System Admin → System Tools → Transfer Logs).

Column	Description
Transfer Id	Auto generated identifier for this Transfer.
Transfer By	User who performed the Transfer.
Transfer Date	Date on which the Transfer was performed.
Transfer Name	Name that identifies the transfer. The combination of Transfer Type, Date and Transferred By User id creates a unique name for this transfer.
Status	Status of the Transfer. Transfers with a status of "Started" have been started but not completed. If you had begun to address validation issues and clicked "Save for Later" your progress is saved.
Checksum Icon	Displays the status of the Checksum. Since a Checksum validation is not performed on during Export these icons are meaningful for Import Transfer Types only. All Export Transfers will show the yellow clock icon. Field Description Checksum is unknown or not evaluated. Checksum validation was successful.  Checksum validation failed.
Transfer Type	Type of Transfer, Whether the listed log is the result of an Import or Export. In addition, remote server Check In, Check Out and Update are considered transfers (between the local server and the master repository). These transfers are listed accordingly (Remote Check In, Remote Check Out".
Log Notes	Any defined Log Notes are displayed
Last Transfer By	Identifies the User who performed the most recent (or last) transfer of the associated file.
Last Transfer Date	Identifies the most recent (or last) time the associated file was transferred.
File	Clicking the File icon displays a hyperlink. When clicked, the associated file is downloaded.
Transfer UUID	The UUID generated to specifically identify this transfer.

To Export all Change Logs associated with an SDI navigate to the SDI list page and click "Export" (Other Tasks menu).

With the SDI selected, click "Export".

Verify that you are exporting the correct SDI and click "Next" to set the Export options.

Here you can choose to perform a "Minimum" transfer (SDI Snapshot only) or a "Full" transfer (configured in the CMT Policy).

Minimum Transfer		Full Transfer

Clicking "Next" brings you to the Preview and Resolve Validation Errors step. When performing a "Minimum" transfer the Export Wizard proceeds in the same way as described above. 

The following sections describe additional features when performing a "Full" transfer.

When performing a "Full" transfer items linked (or referenced) to the selected SDI are identified with an "*", as seen in the example below.

Checking "Ignore all checked out validation errors" lets you proceed with the Export regardless of Check Out validation errors. Check In is required for Export, however you can choose to ignore those errors (Export anyway) by checking this option.

Export progress shows the details of the full transfer.

Import	Top

Using the Import Wizard, Import the transfer package to another system.

Upon Import the following occurs:

A "Save for Later" option can be utilized allowing you to save Import options and return later to complete the Import.

To Import a transfer package navigate to System Admin → System Tools → Import, the Import Wizard displays.

When importing a "CMT" transfer package ("CMT" is specified in the CMT Policy as the default Transfer Tool), choose "CMT" as the import file format in the "Specify format of import file" field.

Browse for, or Drag the exported transfer package into the Wizard. 

Click "Next" to define options for parsing the Import File.

Using the Parse Import File page verify the details of the Import file and manage Import Options.

Field	Description
Import Description Import Notes	The date on which the Import was performed and by whom.
Ignore Missing Objects	When checked, any data model references (such as tables or columns) found in the Import file, that do not exist on the target system, are ignored. This is helpful when exporting from a system with User defined columns, and when importing to a system that does not have exactly the same schema.
Checksum Validation	During Import, the system will check the authenticity of the package: • The manifest checksum is always validated. • The individual SDI Snapshot checksum is validated if the Exporter chose to include the original Check Out SDI Snapshot (before changes) for each SDI. See Set Export Options for more details about this option. If no issues are found the following message is displayed: If issues are found the following message is shown with details about the error: The "Global - Block Invalid Checksum" CMT Policy option determines whether or not to allow an Invalid Checksum Package to be imported. Regardless of the value selected, a warning will be displayed at Import if the Checksum validation fails.
Snapshot Items	Lists the contents of the transfer Package. Field Description SDC ID The SDC Id of the SDI(s) to be imported. SDI to Import The SDIs included in the transfer package. Clicking the hyperlink opens the SDI Viewer where you can visualize the Check In SDI Snapshot. Matched SDI       The system needs to determine whether the SDI is new, or a change to an existing SDI. When the Check Out SDI Snapshot (before changes) is included in the Export, the source database (pre-changes) is compared to the target database. An attempt is made to match the SDI on the target system. When a match is found, the SDI on the Target database that matches the modified SDI in the Import package is listed here. When matching, the system checks the target system for matching versioned SDIs, or auto-key generated SDIs. It first tries to match the UUID, if not found it checks for an Alternate Id, if neither of those are found it checks for the keyid(s) (excluding the versionid). If no matches or multiple matches are found pre-configured Import Options allow you to manage how the changed data is imported. Show Diff When a successful match is made, the "Show Diff" hyperlink opens the "View Diff With Target" page. This view is a comparison of the source system (Check In SDI Snapshot from the Import file) and the current configuration on the target system. NOTE:   The CMT Import Wizard caches the SDI Snapshot from the import file and specifies the targetsdikey to compare against. This allows you to preview the changes to be imported and the current status of the target. Matched By Matched By lists the UUID, Alternate Key, or the Key ID (such as "s_productid AND versionstatus=P") that was matched. If more than one possible option is found choose an appropriate Import Option. Change Log Check Shows the status of the target system: If the target system is also under Change Control this shows the status of the SDI within the target. If checked out, you are offered options for proceeding. If the source Check Out SDI Snapshot (before changes) was included during Import, it is compared to the target configuration. If matching issues are found, those errors are identified. Import Options (defined in CMT Policy) let you manage how to proceed.
Import Option	The available Import options are determined by CMT Policy configuration for each SDC accordingly.
Import	A green check indicates the SDI will be included in the Import.
Save For Later	Allows you to save managed Import Options and complete the Import at a later date. The next time you attempt to Import the same file, any changes to Import details have been saved.

The ImportSnapShot Action validates Foreign Keys (FK) at the end of the Import process (before commit) and generates an error message when the first foreign key validation is violated.

Each Import from a single file is in a single transaction, with deferred FK constraint in Oracle, and no database FK in MSS.

All FK links defined in DDT are validated including detail table FK links.

When you are satisfied with the data to be imported click "Next".

As the file is imported, progress is shown in the Validate/Process dialog.

Click "Finish" to close the dialog.

Once the Import is complete, a Change Log is generated detailing the Transfer (when the target system is under Change Control). This Change Log provides full traceability as it tracks where new SDIs came from.

 Clicking the From Transfer icon opens the View Transferlog page.

The Import is also listed on the Transfer Log (System Admin → System Tools → Transfer Logs) of the Target system. 

Special Transfer Considerations	Top

Following are the special considerations made when transferring the items using CMT.

Attachments stored in the sdiattachment table transfer like any other sdixxx table.
Attachment files (that may be located in the Attachment Repository) are included as part of the export. On import, that file is stored in a repository on the target system. The target system does not need to match the source system's repository.

Consider the following when transferring Attachments (along with an SDI).

CMT can easily transfer a complex Biobanking Study. The Study, along with all of its details can be exported from the Study list page.

OOB, the Study node in the CMT Policy has been configured to include all necessary Embedded SDCs, Detail Tables and any Additional SDCs required to transfer a Study.

The following hierarchy is pre-configured in the CMT Policy.

See CMT Policy to review the detailed OOB configuration of each node. 

At the time of this publication the link between the Group Gizmo and other Gizmos is defined within a Property Tree. This type of link is not currently supported by CMT. Therefore, when a Group Gizmo is transferred, any defined Gizmos within the Group are listed, but not created on the target.

SDCs containing hierarchical paths (such as Anatomic Sites or Locations) offer additional options when transferring.

During Export, choose to:

This applies to all hierarchical SDCs in the system.

OOB, Notes associated with SDIs are not transferred. If you choose to configure the CMT Policy to include Notes when transferring an SDI, consider that any Notes found on the target system will be replaced. It will be up to the User to ensure that Notes are protected on the target.

Many configuration objects are stored in a Property Tree (such as Policies, Elements, Page Types, Gizmos). When transferring Property Trees you can transfer the entire Property Tree, individual Nodes, the Root node, and/or the Definition structure of the Property Tree.

Consider the following when transferring Property Trees.

Since there is no need to transfer Adhoc Queries from the source system to the target system, Adhoc Queries cannot be exported.

When transferring an SDC (SDC definition) there are several things to consider during Export and Import.

When an SDC is exported, the following items are also included as Referenced Items:

Consider the following when importing SDCs:

The entire Storage Unit (Physical Store) structure can be transferred using CMT. This lets you easily configure a Freezer in a development environment then transfer the entire structure to a production environment.

Consider the following when exporting Storage Units:

Consider the following when importing Storage Units:

Given the sensitive nature of the User SDI special care has been taken in CMT to ensure that a User's credentials are handled properly.

When transferring User SDIs the following exceptions are made:

Note that the following tables are not transferred:

The following User columns are not transferred:

The following User Profile properties are included in the SDI Snapshot:

The following table describes what happens when exporting a versioned SDI (Provisional or Current) to the target system when the SDI version on the target is either Provisional or Current.
The "Target Import Versioned SDI Option" in the CMT Policy determines how versioned SDIs are handled during Import. Two cases are presented depending on the Version Handling Rule.

Matching/Generating UUIDs	Top

When supported, a UUID (universally unique identifier) column is added for an SDC. The UUID value is automatically generated and populated for an SDI on creation. This is done by the Audit trigger. The Audit Method must not be set to none for the SDC.

Whether or not UUID is supported for an SDC is determined by the "Support UUID" definition option for the SDC. This option is enabled automatically for Auto-keyed and versioned SDCs OOB. Therefore, all SDCs should have auditing enabled.

When transferring SDIs, this UUID is used first to match SDIs on the target system with SDIs from the source system when the Transfer Option is "Override Existing". If no match is found the imported SDIs keep the same UUID. This is useful when the same autokeyed SDI or versioned SDI is repeatedly transferred from the source system to the target system.

If the Transfer Option is "Always Create a New Version" or "Regenerate Auto Key", the source SDI UUID is ignored. New SDIs are created on the target system to avoid having the same UUID for different SDIs if the same SDI is imported multiple times.