Using the XML Import/Export Application

15 Using the XML Import/Export Application

This chapter provides information about the XML Import/Export application (XMLIE), which is used to manage data and metadata in the Oracle Communications Order and Service Management (OSM) database schema.

About the XML Import/Export Application

XMLIE is included with the OSM SDK Tools component that can be installed with the OSM installer. For more information about installing the OSM SDK Tools component, see OSM Installation Guide.

There are two types of information in an OSM database schema:

Metadata: Information that defines the order model. For example, the definitions of processes, orders, and tasks.
Data: Information that represents orders. For example, order nodes, attributes, and values.

Using XMLIE, you can perform actions such as import and export metadata, purge metadata and data, and migrate data. You can also use XMLIE to validate the metadata model and to create a graphical representation of the metadata.

Note:

Although actions such as importing and exporting metadata, purging both metadata and data, and migrating data can be done using XMLIE, Oracle Communications Design Studio is the preferred application for running these functions.

Note:

XMLIE can work with a localized database, but the application must also be localized. See OSM Developer's Guide for information on localizing OSM, including localizing XMLIE.

If you are running the OSM application on a UNIX or Oracle Linux platform, you must run XMLIE by using a set of Ant scripts. If you are running the OSM application on a Windows platform, you must run XMLIE by using a set of batch scripts.

About Using the XML Import/Export Application

The following steps provide a high-level overview of using XMLIE:

Configure the XMLIE environment files:
- For Ant commands, configure the SDK/XMLImportExport/build.properties file. See "Configuring the build.properties File for Ant Commands."
- For batch scripts, configure the SDK/XMLImportExport/config.bat script. See "Configuring the config.bat Script for Batch Scripts."
Copy the SDK/XMLImportExport/config/config_sample.xml file and rename it to SDK/XMLImportExport/config/config.xml in the same directory.

Note:

The SDK/XMLImportExport/config/config_sample.xml file is a sample XMLIE configuration file that can be used as a template for the config.xml configuration file.

The config.xml file name is arbitrary. If you customize the name of the config.xml file, ensure that you substitute the customized name wherever you must specify the config.xml file (for example, when using the import and export commands in the import.bat and export.bat scripts).

This chapter uses the default config.xml file name in all examples.
Configure the SDK/XMLImportExport/config/config.xml file.

Both the XMLIE Ant commands and batch scripts use this file to define:
- Connections to other components
  
  For example, database connection XML node that provides the OSM schema user name, password, and connection details.
- How the Ant commands and batch scripts work
  
  For example, the import.bat script is configured using the import node in the config.xml file. This node contains elements that specify whether the imported data is validated, what actions to take if the database is not empty, and what actions to take if the XML model you are importing already exists in the database.
- The data or metadata on which the commands are to act
  
  For example, you can configure a selective import that only imports one specific element into an existing OSM cartridge using the selection element.
See "Configuring the config.xml File XML Import/Export Nodes and Elements."
You can create an empty text file with an .xml extension and then use the export.bat script or the ant export command to populate the file. Then you can edit it for use with other batch scripts or Ant commands.

Note:

This chapter uses xmlModelFile as the documentation placeholder name for this file.
Run the Ant command or batch script.

Deploying Cartridges to the OSM Database Using XMLIE

You can deploy cartridges to the OSM DB directly using XMLIE while OSM is still running or shut down. This approach is strongly recommended for controlled environments such as production, pre-production or UAT, and for environments managed using a CI/CD pipeline. It is also the preferred approach for semi-formal environments, such as test systems.

You can perform certain cartridge deployment actions on your OSM running instance while orders from a cartridge that you deployed earlier are still being processed.

For instructions and more information about deploying cartridges to the OSM DB directly using XMLIE in offline and online modes, see "Deploying Cartridges to the OSM Database Using XMLIE" in OSM Modeling Guide.

For instructions about deploying cartridges using Design Studio, see Design Studio Modeling OSM Processes.

About XML Import/Export Batch Scripts and Ant Commands

The following sections describe the XMLIE batch scripts and Ant commands.

About XML Import/Export Ant Commands and Syntax

OSM supports the following Ant commands and syntax for UNIX and Linux systems:

ant export: exports all cartridges, all cartridges within a given namespace, or one specific cartridge.
ant import: imports the XML model.
ant purge: completely purges the target database.
ant undeploy: undeploys the given cartridge if no pending orders exist.
ant forceUndeploy: forces to undeploy the given cartridge including pending orders.
ant convert: upgrades the old XML model to latest version.

Note:

This command is deprecated. Use the ant import command instead because it automatically upgrades models during an import.
ant refresh: refreshes the metadata in the WebLogic Server.
ant htmlModel: converts an XML metadata document to HTML and graphical format.
ant userAdmin: adds users from WebLogic groups and OSM workgroups.

For more information about the ant userAdmin command, see "Using the XML Import/Export Application to Administer Users and Workgroups."

Before you can run these Ant commands, you must configure the Ant environment build.properties file and the config.xml file. For more information see "Configuring the XML Import/Export Environment Files" and "Configuring the config.xml File XML Import/Export Nodes and Elements."

You can use the following scripts to encrypt passwords:

EncryptPasswords.sh: This encrypts passwords in the config.xml file. For more information, see "Using the EncryptPasswords Utility."
CreateEncryptPasswords.sh: This encrypts passwords for use in the userAdmin and credStoreAdmin credential store commands. For more information, see "Using the CreateEncryptPasswords Utility."

About XML Import/Export Batch Scripts and Syntax

OSM supports the following batch scripts for Windows systems in the OSM_home/SDK/XMLImportExport folder:

import.bat: Imports an XML metadata document into an OSM database.
export.bat: Exports an OSM database to an XML metadata document.
migrate.bat: Migrates order data from one version of a cartridge to another version of the same cartridge.
purge.bat: Purges the entire OSM schema (metadata and orders) or undeploys a specific cartridge.
orderPurge.bat: Purges orders that satisfy purge criteria; can be run on an immediate or scheduled basis.
validate.bat: Validates an XML model document.
modeldoc.bat: Converts an XML metadata document to HTML and graphical format.
EncryptPasswords.bat: Encrypts passwords contained in the config.xml file. For more information, see "Using the EncryptPasswords Utility."
CreateEncryptPasswords.bat: Encrypts passwords for use in the userAdmin and credStoreAdmin credential store commands. For more information, see "Using the CreateEncryptPasswords Utility."
convertmodel.bat: Migrates a model from older versions and uses the following syntax:
```
convertmodel.bat xmlModelFile
```
Note:

This script is deprecated. Use the import.bat script instead because it automatically upgrades models during an import.
userAdmin.bat: Adds users to WebLogic from WebLogic groups and OSM workgroups based on an XML definition.

For more information about the userAdmin.bat script, see "Using the XML Import/Export Application to Administer Users and Workgroups."

Note:

Passing an unencrypted password as a command line argument to the XML Import/Export tool scripts is no longer possible. The -p db_password and -clientpassword xmlAPI_password arguments, which were previously deprecated, have now been removed. You must either use encrypted passwords in the config.xml file (using the EncryptPassword utility) or interactively provide the unencrypted password when prompted. For security recommendations, see "Configuring the config.xml File XML Import/Export Nodes and Elements."

Before you can run these scripts, you must configure the environment config.bat script and the config.xml file. For more information see "Configuring the XML Import/Export Environment Files" and "Configuring the config.xml File XML Import/Export Nodes and Elements."

Configuring the XML Import/Export Environment Files

The following sections describe the files you need to edit to configure the environment for the XMLIE Ant commands and batch scripts.

Configuring the build.properties File for Ant Commands

The paths to the config.xml file and the XML model document, along with cartridge and environment properties used by the XMLIE Ant commands, must be specified in the SDK/XMLImportExport/build.properties file. Unlike the XMLIE batch scripts, you do not have to specify these paths in the command line.

To configure the build.properties file for Ant commands:

Open the SDK/XMLImportExport/build.properties file.
Update the following variables:
```
middlewareHome=MW_home
java.maxmemory=java_max_memory
xmlie.root.dir=root_dir
xmlie.root.modelDocument=model_document
xmlie.root.configDocument=config_document
xmlie.root.namespace=namespace
xmlie.root.version=version
xmlie.root.htmlDir=html_dir
```
where:
- MW_home is the location where Oracle Fusion Middleware was installed
- java_max_memory is the maximum heap to be used by JVM
- root.dir is the path of XMLIE directory
- model_document is the path for XML model document
- config_document is the path for config.xml
- namespace is the OSM cartridge namespace
- version is the cartridge version
- html_dir is the path for HTML model directory
  
  Note:
  
  You can also refer to the README.txt file found under SDK/XMLImportExport for information on configuring the build.properties file for Ant scripts.
For example:
```
middlewareHome=C:/oracle/middleware
java.maxmemory=512m
xmlie.root.dir=./
xmlie.root.modelDocument=./data.xml
xmlie.root.configDocument=./config/config.xml
xmlie.root.namespace=test
xmlie.root.version=4.0
xmlie.root.htmlDir=./htmlModel
```
If you want to configure order purge parameters in the build.properties file, see "Running Ant with the orderPurge.xml file On UNIX or Linux to Purge Orders."
If you want to configure cartridge migration parameters in the build.properties file, see "Configuring and Running an Order Migration."

Configuring the config.bat Script for Batch Scripts

To configure the batch script environment, go to the SDK/XMLImportExport directory and configure the user-configurable variables (for example, JAVA_OPTS) in the config.bat file.

Configuring the config.xml File XML Import/Export Nodes and Elements

To configure the config.xml file:

Open the SDK/XMLImportExport/config/config_sample.xml file.
Create a config.xml file by copying config_sample.xml to config.xml.

Note:

The sample_config.xml file contains references to absolute paths that start with "C:\". Be sure to configure these paths to reflect your environment.
Configure the database connection node in the config.xml file. This node is required for most Ant commands and batch scripts.
```
<databaseConnection>
   <user>osm_schema</user>
   <password>osm_schema_pwd</password>
   <dataSource>jdbc:oracle:thin:@ip_address:osm_db_port:osm_db_sid</dataSource>
</databaseConnection>
```
where:
- osm_schema and osm_schema_pwd are the OSM schema user name and password.
- ip_address, osm_db_port, and osm_db_sid are the OSM database IP address, port number, and SID.
Note:

To export or import the symbols, change the character set and database connection to something like the following sample:
```
<encoding>UTF-8</encoding> 
<dataSource> jdbc:oracle:oci:(description=(address=(host=host1.example.com)(protocol=tcp)(port=1521)) (connect_data=(SID=ORASID)))
</dataSource>
```
Configure the XML API connection node to specify the connection information to be used by operations that utilize the XML API. For example, migration Ant commands or batch scripts require this node.
```
<xmlAPIConnection>
   <user>weblogic_user</user>
   <password>weblogic_pwd</password>
   <url>http://ip_address:port</url>
</xmlAPIConnection>
```
where
- weblogic_user and weblogic_pwd are the user name and password of the user performing the migration. This user must have access to all source orders being migrated and to target order's type/source order entry task (if closeSource set to true, see "About Migrating Orders" for details).
- ip_address, and port are the WebLogic Administration server IP address and port number.
Configure the WebLogic Administrator credentials and connection information node. This node is required for Ant commands and batch scripts that modify OSM user credentials:
```
<j2eeAdminConnection>
   <j2eeServiceName>weblogic</j2eeServiceName>
   <user>weblogic_user</user>
   <password>weblogic_pwd</password>
   <protocol>protocol</protocol>
   <hostname>ip_address</hostname>
   <port>port</port>
</j2eeAdminConnection>
```
where
- weblogic_user and weblogic_pwd are the user name and password of the WebLogic with Administrator privileges.
- protocol is the protocol to use to connect to the WebLogic server. If not included, the t3 protocol will be used. If you would like to connect to the WebLogic server using SSL, set this value to t3s.
- ip_address, and port are the WebLogic Administration server IP address and port number.
Configure the XMLIE log file location node:
```
<log logFileUrl="file:/filename_path" overwrite="boolean"/>
```
where:
- filename_path is the path to the log file that includes the file name of the log file.
- boolean can be true or false. If set to true (default), XMLIE overwrites the log file every time the application starts. If set to false, XMLIE creates a cumulative log by saving the log from session to session and adding new messages to it.
Do one of the following:
- For exporting metadata from an OSM database, configure the export node. See "About Exporting Metadata."
- For importing metadata to the OSM database, configure the import node. See "About Importing Metadata".
- For purging metadata and order data in an OSM database, configure the purge node. See "About Purging MetaData and Data."
- For migrating orders between OSM cartridges, configure the migrate node. See "About Migrating Orders."
- For validation Metadata from an existing XML file, configure the validation node. See "About Validating the Metadata Model and Data."
- For creating a graphical HTML representation see "About Creating a Graphical Representation of the Metadata Model."
(Optional) If XMLIE is to be run unattended, secure the EncryptPassword utility and the configuration file that contains user credentials.

For enhanced security, each of the XMLIE operations that require user passwords prompts you for those passwords during invocation. If XMLIE is to be run unattended, you can alternatively encrypt those passwords and store them in the XMLIE configuration file (typically config.xml).

If passwords are to be stored in the XMLIE configuration file, do the following:
1. Set the permissions of the configuration file to be readable only by select administrative users. Refer to your OS documentation for instruction.
2. Run the EncryptPassword utility so that user name and password credentials for all XMLIE users are encrypted for safe storage. For more information, see "Using the EncryptPasswords Utility."
Note:

If you plan to run XMLIE in an unattended mode, you must first run the EncryptPasswords utility; otherwise, you cannot perform many of the application functions and OSM gives an error indicating that you must run the EncryptPasswords utility.

Using SSL Connections

You can use a secure connection in XMLIE. To do this, configure the config.xml file for a secure connection (by setting the j2eeAdminConnection element in the config.xml file to use the "t3s" protocol), and then make the certificate available to the XMLIE scripts.

To configure the config.xml file for a secure connection, see step 5 in "Configuring the config.xml File XML Import/Export Nodes and Elements."

To make the certificate available to the XMLIE scripts on UNIX and Linux, run the following command, located in the OSM_home/SDK/XMLImportExport directory:

ImportCertificate.sh server port

where server is the name of the host that the WebLogic administration server is running on and port is the SSL port for that Weblogic administration server.

To make the certificate available to the XMLIE scripts on Windows:

Do one of the following to get a copy of the certificate:
- Download and use a tool like OpenSSL
- Connect to the SSL port for the administration server in your browser. You can connect by accessing either the WebLogic Server Administration console or one of the OSM web clients. Once you have connected, the certificate will be stored in your browser. Consult the documentation for your browser for information about how to export a certificate. Export the certificate in Base-64-encoded X.509 format (sometimes known as X.509 PEM format).
Import the certificate into your Java keystore by doing the following:
1. Set your JAVA_HOME environment variable to the location of the instance of Java that you will be using for the credStoreAdmin or userAdmin command.
2. Run the keytool command (located in %JAVA_HOME%/bin) with the following syntax:
```
keytool -import -trustcacerts -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -alias osmalias -file filename
```
  where:
  
  osmalias is an alias for the certificate that is unique within the instance of Java
  
  filename is the path and name of the file to which you exported the certificate.
  
  For example:
```
keytool -import -trustcacerts -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -alias osmserver -file C:\OSMSec\osmdomainCert.crt
```
3. You will be prompted for the password for the keystore. The default is changeit, so use that value unless you have changed the password for your keystore.

About Importing and Exporting Metadata

You can transfer metadata from one OSM database to another when setting up a new OSM environment. For example, you may want to set up multiple OSM environments of the same version, such as development, test, and production environments. Or, you may want to set up a new version of an OSM production environment based on a previous version of an OSM production environment.

Transferring metadata from one OSM database to another is a combination of an export from the one OSM database followed by an import to another. You can also import and export selected parts of the metadata, as opposed to all of the metadata.

Note:

The actions that XMLIE runs are supported in Design Studio. Any metadata changes made using XMLIE will be overwritten when deploying the same cartridge using Design Studio.

The following sections describe import and export commands and configurations.

About Exporting Metadata

XMLIE provides the export.bat script or the ant export command, which is used to export metadata from an OSM database. Exported metadata is stored in an XML file (the xmlModelFile). You can export metadata using Design Studio; however, this functionality remains available through XMLIE as well.

You can export the entire metadata database, or you can use the export selection element to specify the metadata to export based on:

All entities or selected entities from a specific cartridge
All cartridges in a namespace

Each OSM cartridge is uniquely identified by namespace and version, so exporting all of the cartridges in a namespace includes all versions of the cartridge within the namespace.

Note:

A selective export exports all of the data, then it applies a filter according to the selection. Consequently, selective exports take the same amount of time as full exports.

About the Order of Exported Metadata

When the order of the resulting list makes no logical or significant difference, XMLIE places the metadata files in ascending alphabetical order. This ensures that when you do repeated exports of the same database, the metadata files will always appear in the same order, which makes it easier to merge metadata changes with future development.

In Example 15-1, the definition of entities (for example, each state) is now sorted alphabetically by name:

Example 15-1 Definition of Entities (each state) Sorted Alphabetically by Name

<state name="accepted">
<description>Accepted</description>
</state>
<state name="assigned">
<description>Assigned</description>
</state>
<state name="completed">
<description>Completed</description>
</state>
<state name="received">
<description>Received</description>
</state>
...

In Example 15-2, the references to entities (for example, each state) is now sorted alphabetically by name:

Example 15-2 References to Entities (states or statuses) Sorted Alphabetically by Name:

<task name="enter_payment_information" xsi:type="genericTaskType">
<description>Enter Payment Information</description>
<state>accepted</state>
<state>completed</state>
<state>received</state>
<status>back</status>
<status>next</status>
</task>

In Example 15-3, the Import/Export application does not sort by name because the order matters (that is, there is a logical difference). Country appears after last_name because the designer specified country to appear after last_name:

Example 15-3 Not Sorted By Name

<masterOrderTemplate>
<dataNode element="account_information">
<dataNode element="first_name"/>
<dataNode element="last_name"/>
<dataNode element="country">
<viewRule xsi:type="eventRuleType">
<event>value-changed</event>
<action>refresh</action>
</viewRule>
</dataNode>

About Export Layout Options

When you perform a selective export, you can specify different export layouts by using the export command to create one or multiple files, and where to put the files. You have the following options:

Use the singleDocument layout to export to a single file that contains all of the exported entities.
Use the cartridge layout to export to one main document and a single folder for each exported cartridge. Each cartridge folder contains a version folder.

Figure 15-1 shows the cartridge layout.

Figure 15-1 Cartridge Layout

Description of "Figure 15-1 Cartridge Layout"
You can use the entity layout to export to:
- One main document
- A folder for each cartridge included in the export (you can specify that the export include entities from more than one cartridge)
- A folder for the cartridge version
- A single folder for each entity type exported. Under the entity type folders are the individual entity XML files
  
  Figure 15-2 shows the entity layout.
Figure 15-2 Entity Layout

Description of "Figure 15-2 Entity Layout"

Keeping the ID Integrity in SQL Rules

Note:

This section is applicable only if you are upgrading up to OSM 7.0 from a previous release. SQL rules and text rules were replaced in OSM 7.0. SQL rules are supported in Design Studio. The SQL rule is imported as a separate file that can be edited as a text document.

The SQL based rule type in OSM can contain entity IDs (mostly node IDs), which must be replaced with new IDs during data migration. IDs must be exposed as entity attributes, helping the application find them in SQL based rules, and replace them with new ones while importing them into a fresh environment. IDs in a document otherwise serve no purpose and should be ignored. You can set this feature to false by setting the exposeEntityID, in the config.xml file for XMLIE, to false, thereby reducing the model document size.

Note:

This is a function of the export behavior.

Text rules can reference any entity ID. Generally, however, node IDs used in these known patterns for other possible entity ID conversion routines require user assistance to tokenize the rule text for proper parsing and conversion. A token suggested before the ID must be tokenized for IDs except known patterns (all node functions and stored procedures in om_ordinst_value_pkg package):

 /*$entityType*/

Example 15-4 Original Rule

declare val1 date;
delay_flag    varchar2(10);
begin
select timestamp_out into val1
from om_hist$order_header hist, om_task task, om_state st
where hist.task_id = task.task_id 
and node_id = /*$dataNode*/76983
and hist.hist_order_state_id = st.state_id and st.state_mnemonic = 'completed'
and hist.order_seq_id = :order_seq_id;

delay_flag := om_ordinst_value_pkg.get_node_value_like(:order_seq_id,76983,:coord_set_id);
if  ( rtrim(delay_flag)='yes' ) or (val1 &lt;= (sysdate - 2/24)) then
:rule_result := 'true';
else 
:rule_result := 'false';
end if;
end;

Example 15-5 Modified Rule

The import operation detects IDs and replaces them with new IDs.

declare val1 date;
delay_flag    varchar2(10);
begin
select timestamp_out into val1
from om_hist$order_header hist, om_task task, om_state st
where hist.task_id = task.task_id 
and node_id = /*$dataNode*/new_id
and hist.hist_order_state_id = st.state_id and st.state_mnemonic = 'completed'
and hist.order_seq_id = :order_seq_id;

delay_flag := om_ordinst_value_pkg.get_node_value_like(:order_seq_id, new_id,:coord_set_id);
if  ( rtrim(delay_flag)='yes' ) or (val1 &lt;= (sysdate - 2/24)) then
:rule_result := 'true';
else 
:rule_result := 'false';
end if;
end

Configuring and Running an Export

To configure and run an export:

Configure the config.xml file for use with the ant export command.
```
	<export validateModel="validation" exposeEntityID="entityID" layout="layout_action" readOnlyFileAction="readOnly_action">
	</export>
```
where:
- validation: Options are:
  - true: Validates the XML model before performing the export.
  - false: Does not validates the XML model before performing the export. (default).
  Caution:
  
  Oracle recommends you do not skip the model validation, so this parameter should always be set to true.
- entityID: Options are:
  - true: Exposes the EntityID in the exported file. (default)
  - false: Conceals the Entity ID in the exported file.
- layout_action: Options are:
  - singleDocument: Exports everything to a single file. (default)
  - cartridge: Creates a single file for each cartridge exported.
  - entity: Creates a single file for each entity exported.
- readOnly_action: Options are:
  - ignore: The Export operation will not overwrite read-only files. (default)
  - replace: The Export operation will overwrite read-only files.
(Optional) Add the selection element within the export node to export targeted entities to OSM metadata using an XPath expression. Use the following syntax to define the selection element:
```
	<export validateModel="validation" exposeEntityID="entityID" layout="layout_action" readOnlyFileAction="readOnly_action">
     <selection>/oms:model/oms:cartridge[@namespace="namespace" and @version="version"]/oms:entity</selection>
     <selection>/oms:model/oms:entity</selection>
</export>
```
where
- namespace: The namespace for the cartridge.
- version: The cartridge version.
- entity: The entity you are targeting. For example, workgroup, region, and schedule.
Do the following:
1. If you using Ant, run the following command:
```
ant export
```
2. If you using a batch script, run the following command:
```
export.bat xmlModelFile config/config.xml
```

About Importing Metadata

XMLIE provides the import command, which is used to import metadata into an OSM database. If you import metadata, make sure that the elements you import do not conflict with existing metadata that is part of a Design Studio OSM cartridge. Otherwise you may encounter version conflict, overwrite existing elements, and create other discrepancies.

You can import the entire metadata database using the import node or you can use the import selection element within an import node to specify the metadata to import based on:

All entities or selected entities from a specific cartridge
All cartridges in a namespace

Each OSM cartridge is uniquely identified by namespace and version, so exporting all of the cartridges in a namespace includes all versions of the cartridge within the namespace.
System level parameters

By enabling selective imports, you can grant concurrent access to a single model or cartridge for multiple developers. Using this method, developers can import just the entities on which they are working at that moment, which gives other developers access to other entities within the cartridge.

The import operation is performed in one transaction. Consult your Oracle Database Administrator (DBA) for the appropriate setup for the rollback segment.

Note:

User workgroups are not part of the metadata model, so they must be re-entered after an import.

Note:

After importing or exporting a cartridge, you must remap the e-mail notifications that were associated with individual users. For best results, associate notifications only with workgroups because user names differ between environments.

Configuring and Running an Import

To configure and run an import:

Configure the config.xml file:
```
<import validateModel="validation" nonEmptyDatabaseAction="database_action"entityConflictAction="entity_action">
</import>
```
where:
- validation: Options are:
  - true: Validates the XML model before performing the import.
  - false: Does not validates the XML model before performing the import. (default)
  Caution:
  
  Oracle recommends you do not skip the model validation, so this parameter should always be set to true.
- database_action: Options are:
  - ignore: The import completes even if it detects that the database is non-empty. (default)
  - abort: The import terminates if it detects that the database is non-empty.
  - purge: The import purges the existing database if it detects that the database is non-empty.
  If a model includes some changes for existing entities in the database, the import checks for order dependency. If those changes do not violate database constraints for pending orders, the import completes successfully. If the modified entities violate the existing orders, the violation is reported as known application exceptions with descriptive messages.
- entity_action: The entityConflictAction import parameter value specifies the import behavior when the application encounters a conflict for an existing entity in the database. For example, a conflict occurs if you import a new model that contains one or more entities that already exist in the database. Options are:
  - abort: If an entity conflict exists, the import process stops.
  - replace: The import replaces conflicted entities, that is, entities that already exist. (default)
  - ignore: The import does not replace conflicted entities.
(Optional) Add the selection element within the import node to import targeted entities to an OSM cartridge using an XPath expression. Use the following syntax to define the selection element:
```
<import validateModel="validation" nonEmptyDatabaseAction="database_action"entityConflictAction="entity_action">
     <selection>/oms:model/oms:cartridge[@namespace="namespace" and @version="version"]/oms:entity</selection>
     <selection>/oms:model/oms:system_entity</selection>
</import>
```
where
- namespace: The namespace for the cartridge.
- version: The cartridge version.
- entity: The entity you are targeting. For example, workgroup, region, and schedule.
Do the following:
1. If you using Ant, run the following command:
```
ant import
```
2. If you using a batch script, run the following command:
```
import.bat xmlModelFile config/config.xml
```

Sample Procedure for Adding a New Workgroup Definition (Role)

You can add a new workgroup definition (a workgroup is called a role in Design Studio) without having to redeploy a cartridge by using XMLIE.

Note:

The workgroup definition is a system level entity that can be applied to multiple different cartridges. If you add a new workgroup using XMLIE, make sure you do not overwrite existing workgroup definitions.

To add a new workgroup definition using XMLIE:

In the SDK\XMLImportExport\config\config.xml file, add a selection element to an export node that targets the workgroupDefinition entity.

For example:

<export validateModel="false" exposeEntityID="false" layout="singleDocument"
 readOnlyFileAction="ignore">
     <selection>/oms:model/oms:workgroupDefinition</selection>
</export>

Save and exit the file.
In the SDK\XMLImportExport\ folder, create an XML document to store the XML workgroup information from the cartridge you are targeting. For example: workgroupDefinition.xml.

Run the SDK\XMLImportExport\export.bat script:

For example:

export.bat C:\osminstall\SDK\XMLImportExport\worgrkoupDefinition.xml C:\osminstall\SDK\XMLImportExport\config\config.xml

When the export is complete, open the XML file containing the workgroup information and add a new workgroupDefinition element and all child elements. For example:

<?xml version = '1.0' encoding = 'ISO-8859-2'?>
<model xmlns="http://www.metasolv.com/OMS/OrderModel/2002/06/25"
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.metasolv.com/OMS/OrderModel/2002/06/25
 file:///D:/OSMSTA~1/SDK/XMLIMP~1//models/OmsModel.xsd">
  <workgroupDefinition name="newWorkgroup">
    <description>newWorkgroup</description>
    <permissions>
      <createdVersionedOrders />
      <exceptionProcessing />
      <onlineReports />
      <priorityModification />
      <referenceNumberModification />
      <searchView />
      <taskAssignment />
      <worklistViewer />
    </permissions>
    <calendar>
      <weeklyWorkHours>no_schedule</weeklyWorkHours>
      <region>no_region</region>
    </calendar>
  </workgroupDefinition>
</model>

Save and exit the file.
Run the SDK\XMLImportExport\import.bat script:

For example:
```
import.bat C:\osminstall\SDK\XMLImportExport\worgrkoupDefinition.xml C:\osminstall\SDK\XMLImportExport\config\config.xml
```
Note:

In this scenario, the XML model file contains only those elements that need to be imported. If the model file contained other elements that did not need to be imported, you can add a selection element to the import node in the SDK\ XMLImportExport\config\config.xml file that targets the workgroupDefinition entity in the model file.

For example:
```
<import validateModel="false" nonEmptyDatabaseAction="ignore"entityConflictAction="replace">
  <selection>/oms:model/oms:workgroupDefinition</selection>
</import>
```

Sample Procedure for Adding a Task to a Workgroup (Role)

You can add a task to a workgroup (a workgroup is called a role in Design Studio) without having to redeploy a cartridge by using XMLIE.

Note:

This procedure assumes that you have already created the task that you want to assign to a workgroup.

To add a task to a workgroup using XMLIE:

In the SDK\XMLImportExport\config\config.xml file, add a selection element to an export node that targets the workgroup entity in the cartridge you want to add a task to.

For example:

<export validateModel="false" exposeEntityID="false" layout="singleDocument"
 readOnlyFileAction="ignore">
   <selection>/oms:model/oms:cartridge[@namespace="bb_ocm_demo" and @version="1.0.0.0.1"]/oms:workgroup</selection>
</export>

Save and exit the file.
In the SDK\XMLImportExport folder, create an XML document to store the XML workgroup information from the cartridge you are targeting. For example: workgroup.xml.

Run the SDK\XMLImportExport\export.bat script:

For example:

export.bat C:\osminstall\SDK\XMLImportExport\worgrkoup.xml C:\osminstall\SDK\XMLImportExport\config\config.xml

When the export is complete, open the XML file containing the workgroup information and add a new task element. For example:

<?xml version = '1.0' encoding = 'ISO-8859-2'?>
<model xmlns="http://www.metasolv.com/OMS/OrderModel/2002/06/25"
 xmlns:osm="http://xmlns.oracle.com/communications/ordermanagement/model"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.metasolv.com/OMS/OrderModel/2002/06/25
 file:///D:/OSMSTA~1/SDK/XMLIMP~1//models/OmsModel.xsd">
   <schemaVersion>7.2.0</schemaVersion>
<version>
   <label>7.2.0.0.366</label>
   <majorVersion>1.0</majorVersion>
</version>
<cartridge namespace="bb_ocm_demo" version="1.0.0.0.1">
   <description>BB OCM Demo</description>
   <default>true</default>
   <timestamp>2012-05-28T13:05:12</timestamp>
   <workgroup name="demo">
      <column name="Phone #">
         <path>/subscriber_info/primary_phone_number</path>
      </column>
      <column name="Name">
         <path>/subscriber_info/name</path>
      </column>
       <permissions>
         <orderEntry>
            <orderType>add_adsl_siebel</orderType>
            <orderSource>add_adsl_siebel</orderSource>
         </orderEntry>
         <task>activate_dslam</task>
         <task executionModes="do">add_adsl_siebel_creation</task>
         <task>add_capacity</task>
         <task>assign_port</task>
         <task>demo_query</task>
         <task>send_customer_survey</task>
         <task>ship_modem_self_install_pkg</task>
         <task>verify_adsl_service_availability</task>
         <task>verify_order</task>
         <task>new_task</task>
      </permissions>
   </workgroup>
</cartridge>
</model>

Save and exit the file.
Run the SDK\XMLImportExport\import.bat script:

For example:
```
import.bat C:\osminstall\SDK\XMLImportExport\worgrkoup.xml C:\osminstall\SDK\XMLImportExport\config\config.xml
```
Note:

In this scenario, the XML model file contains only those elements that need to be imported. If the model file contained other elements that did not need to be imported, you can add a selection element to the import node in the SDK\ XMLImportExport\config\config.xml file that targets the workgroup entity in the model file.

For example:
```
<import validateModel="false" nonEmptyDatabaseAction="ignore"entityConflictAction="replace">
  <selection>/oms:model/oms:cartridge[@namespace="bb_ocm_demo" and @version="1.0.0.0.1"]/oms:workgroup</selection>
</import>
```

About Purging MetaData and Data

XMLIE provides the purge.bat, purgeOrder.bat scripts and ant purge, ant undeploy, and ant forceundeploy commands, which are used to purge metadata and data from an OSM schema. For example, you may need to purge an existing schema prior to importing a new model, or you may need to purge the data from a test environment at the beginning of each new phase of testing.

Using the purge.bat script or purge Ant command, you can remove everything (all metadata and data) from the schema, or you can remove data from a specified cartridge. Using the purgeOrder.bat script or ant purge command, you can remove all the data. The purgeOrder.bat script and ant purge command do not affect metadata.

Oracle recommends that you purge all order data related to a cartridge before purging a cartridge. Purging large amounts of order data or cartridges should only be done during off-peak hours.

Note:

You must shut down the WebLogic Server before executing the purge command or an exception is thrown.

The purge.bat script and ant purge command are not transactional so any unexpected failure may leave the schema in an invalid state. If this occurs, repeat the purge.bat script or ant purge command until it completes successfully.

Undeploying Cartridges and Purging the Database Schema

You can undeploy a cartridge using either fast undeploy or undeploy. When you use fast undeploy, which is the default functionality, the cartridge is undeployed from OSM, but cartridge metadata and order data are not purged from the database. The fast undeploy functionality is useful in development and test environments where you need to deploy and undeploy cartridges frequently.

When you use the undeploy functionality (where the fast_cartridge_undeploy parameter is set to False), the cartridge is undeployed and its metadata and order data are purged from the database, which can be time-consuming depending on how complex the cartridge is and whether it has a significant number of orders.

For information about changing the fast_cartridge_undeploy parameter in the oms-config.xml file, see "Configuring OSM with oms-config.xml."

To purge the entire schema (metadata and orders) or undeploy a specific cartridge using Ant commands:

Consult "Online vs. Offline Maintenance" to ensure that the system is in the appropriate state (online or offline) for the operation you intend to perform.
Do one of the following:
Note:

You can target an entire schema for the undeploy, forceundeploy, and purge commands, or you can specify a namespace or a namespace and version by configuring the following build.properties parameters:
- xmlie.root.namespace
- xmlie.root.version
For more information about these parameters, see "Configuring the build.properties File for Ant Commands."
- To purge a target schema, run the following command:
```
ant purge
```
- To undeploy a cartridge using fast undeploy, but only if no pending orders exist, run the following command:
```
ant fastUndeploy
```
- To undeploy a cartridge, but only if no pending orders exist, run the following command:
```
ant undeploy
```
- To undeploy a cartridge using fast undeploy, even if pending orders exist, run the following command:
```
ant forceFastUndeploy
```
- To undeploy a cartridge, even if pending orders exist, run the following command:
```
ant forceUndeploy
```
If you used the fast undeploy option and OSM was online, refresh the metadata for OSM. See "Refreshing OSM Metadata" for more information.

To purge the entire schema (metadata and orders) or undeploy a specific cartridge using batch scripts:

Consult "Online vs. Offline Maintenance" to ensure that the system is in the appropriate state (online or offline) for the operation you intend to perform.
Do one of the following:
- To completely purge a target schema, use the following batch script:
```
purge.bat config\config.xml force 
```
  If you run this script without the force attribute, the purge.bat script fails if any pending orders exist on the cartridge you are purging. If you run this script with the force attribute, the script purges the cartridge and all pending orders.
- To undeploy every version of a cartridge with a specified namespace, but only if no pending orders exist, use the following batch script:
```
purge.bat config\config.xml -n namespace
```
  where namespace is the OSM cartridge namespace.
- To undeploy a specified version of a cartridge, but only if no pending orders exist, use the following batch script:
```
purge.bat config\config.xml -n namespace -v version
```
  where namespace and version are the OSM namespace and cartridge version.
- To undeploy every version of a cartridge, run the following batch script:
```
purge.bat config\config.xml force -n namespace
```
  where namespace is the OSM cartridge namespace.
- To undeploy a specific cartridge version, use the following batch script:
```
purge.bat config\config.xml force -n namespace -v version
```
  where namespace and version are the OSM namespace and cartridge version.
- To undeploy every version of a cartridge using fast undeploy, but only if no pending orders exist, use the following batch script:
```
fastUndeploy.bat config\config.xml -n namespace
```
  where namespace is the OSM cartridge namespace.
- To undeploy a specific cartridge version using fast undeploy, but only if no pending orders exist, use the following batch script:
```
fastUndeploy.bat config\config.xml -n namespace -v version
```
  where namespace and version are the OSM namespace and cartridge version.
- To undeploy every version of a cartridge using fast undeploy, even if pending orders exist, use the following batch script:
```
fastUndeploy.bat config\config.xml force -n namespace 
```
  where namespace is the OSM cartridge namespace.
- To undeploy a specific cartridge version using fast undeploy, even if pending orders exist, use the following batch script:
```
fastUndeploy.bat config\config.xml force -n namespace -v version
```
  where namespace and version are the OSM namespace and cartridge version.
If you used the fast undeploy option and OSM was online, refresh the metadata for OSM. See "Refreshing OSM Metadata" for more information.

About Purging Orders

OSM provides the following ways to remove orders:

XMLIE order purge - You can purge orders using criteria such as one or more order states, purge before date, order source, order type, namespace, version, start date, and stop date using XMLIE order purge.
Dropping old partitions that contain completed orders.

Note:

Oracle recommends dropping old partitions that contain completed orders as the best way to purge orders (see "Dropping Partitions (Offline Only)" for more information). If you cannot use this method because of pending orders, you can use the XMLIE order purge script as a slower alternative.

Purging Orders with the orderPurge.bat Script on Windows

You can configure the orderPurge.bat script to:

purge orders based on one or more order states
purge orders from a specific cartridge (namespace/version) or all cartridges
schedule the purge to run during off-peak hours or run it immediately

Use the following commands to perform the indicated order purge operation.

Use the following syntax to run an immediate order purge:
```
orderPurge.bat xmlConfigFile doPurge "purge_before=before_purge"
"order_states=order_states" "namespace=namespace" "version=version
"order_type=order_type" "order_source=order_source" "commitCount=commitCount" 
"orderIdLessThan=order_id_upper" "orderIdGreaterOrEq=order_id_lower"
"parallelism=op_number"
```
Note:

All date parameters must be specified in the format:

yyyy-mm-ddThh24:mi:ss Z

For example: 2011-06-28T13:39:00 EST

Where:
- before_purge: Use this data parameter with the order_state parameter. For example, to purge orders completed 30 days ago, specify order_state="COMPLETED" and purge_before=2011-06-28T13:39:00 EST (or a date that is 30 days before the current date). Options are:
  - all: All orders that were created before this date are considered for the purge
  - any closed state: All orders whose completion date is before this date are considered for the purge.
  - any open state: All orders that were created and transitioned to the state specified before this date are considered for the purge.
  If no purge_before date is specified, the date is set to 5 seconds before the purge starts.
- order_states: An order state must be specified. Options are one or more of the following comma separated values:
  - all
  - open
  - not_running
  - running
  - not_started
  - suspended
  - cancelled
  - compensating
  - amending
  - cancelling
  - closed
  - completed
  - aborted
  - in_progress
  - waiting_for_revision
  - waiting
  - failed
  For example: "not_started,completed"
- namespace: Must be specified. Valid values are either a namespace mnemonic or ALL (applies to all cartridges). For example, to purge all orders regardless of other conditions, specify order_state="ALL" and namespace="ALL".
- version: If namespace is ALL, version is ignored. If namespace is specified but no version is specified, the purge applies to all versions of the namespace.
- order_type: The order type mnemonic. If specified, only orders with this type are purged.
- order_source: The order source mnemonic. If specified, only orders with this source are purged.
- commitCount: The number of orders to purge before committing the transaction to the database. If specified, this can improve the performance of the order purge by breaking it up into smaller transactions.
- order_id_upper: The order ID number used with the orderIdLessThan parameter which specifies the exclusive upper order ID bound to purge.
- order_id_lower: The order ID number used with the orderIdGreaterOrEq parameter which specifies the inclusive lower order ID bound to purge.
- op_number: The number of purge operations to run in the database in parallel. The value can be a power of two of the set 1, 2, 4, 8, 32, or 64.
For example:
```
orderPurge.bat config/config.xml doPurge "purge_before=2011-01-01T23:59:59 EST"
"order_states=COMPLETED,NOT_STARTED" "namespace=abc" "version=1.0" 
"order_type=x" "order_source=y" "commitCount=10" "orderIdLessThan=10"
"orderIdGreaterOrEq=50" "parallelism=64"
```
Use the following syntax to run a scheduled order purge:

Note:

The syntax for the scheduled order purge is identical to the immediate order purge except for the start_date and stop_date attributes.
```
orderPurge.bat xmlConfigFile doPurge "purge_before=before_purge"
"order_states=order_states" "namespace=namespace" "version=version
"order_type=order_type" "order_source=order_source" "commitCount=commitCount" 
"orderIdLessThan=order_id_upper" "orderIdGreaterOrEq=order_id_lower"
"parallelism=op_number" "stop_date=stop_date" "start_date=start_date"
```
Where the parameters match the ones in step 1, with the addition of the following:
- stop_date: The time when the purge should stop, even if all orders satisfying the purge criteria have been purged (for example, stop the purge before peak hours). If no stop_date is specified, the purge stops when all orders satisfying the purge criteria have been purged.
- start_date: For scheduled purges only - the time when the purge should start (must be later than the current time). When the start_date is reached, the purge starts automatically. If no start_date is specified, the purge is immediate.
For example:
```
orderPurge ./config/config.xml schedulePurge "purge_before=2011-01-01T23:59:59 EST" "order_states=COMPLETED,NOT_STARTED" "namespace=abc" "version=1.0" 
"order_type=x" "order_source=y" commitCount=10 "start_date=2007-01-01T23:59:59 EST"
```
Use the following syntax to list all scheduled order purges that have not started:
```
orderPurge.bat xmlConfigFile listPurges
```
For example:
```
orderPurge.bat ./config/config.xml listPurges
```
Use the following syntax to remove an order purge that has not started:
```
orderPurge.bat xmlConfigFile removePurge "job_id"
```
where job_id is the job ID of the scheduled purge.

For example:
```
orderPurge.bat config/config.xml removePurge "job_id=12345"
```

Running Ant with the orderPurge.xml file On UNIX or Linux to Purge Orders

To purge orders from an OSM schema using Ant:

Open the SDK/XMLImportExport/build.properties file.
If you want to perform an immediate purge of some or all orders before a certain date using the immediateOrderPurge attribute for the ant purge command, edit the following arguments:
```
xmlie.orderPurge.purgeBefore=before_purge
xmlie.orderPurge.orderStates=order_states
xmlie.orderPurge.namespace=namespace
xmlie.orderPurge.version=version
xmlie.orderPurge.orderType=order_type
xmlie.orderPurge.orderSource=order_source
xmlie.orderPurge.commitCount=commitCount
xmlie.orderPurge.orderIdLessThan=order_id_upper
xmlie.orderPurge.orderIdGreaterOrEq=order_id_lower
xmlie.orderPurge.parallelism=op_number
```
Where
- before_purge: Use this data parameter with the order_state parameter. For example, to purge orders completed 30 days ago, specify order_state="COMPLETED" and purge_before=2011-06-28T13:39:00 EST (or a date that is 30 days before the current date). Options are:
  - all: All orders that were created before this date are considered for the purge
  - any closed state: All orders whose completion date is before this date are considered for the purge.
  - any open state: All orders that were created and transitioned to the state specified before this date are considered for the purge.
  If no purge_before date is specified, the date is set to 5 seconds before the purge starts.
- order_states: An order state must be specified. Options are one or more of the following comma separated values:
  - all
  - open
  - not_running
  - running
  - not_started
  - suspended
  - cancelled
  - compensating
  - amending
  - cancelling
  - closed
  - completed
  - aborted
  - in_progress
  - waiting_for_revision
  - waiting
  - failed
  For example: "not_started,completed"
- namespace: Must be specified. Valid values are either a namespace mnemonic or ALL (applies to all cartridges). For example, to purge all orders regardless of other conditions, specify order_state="ALL" and namespace="ALL".
- version: If namespace is ALL, version is ignored. If namespace is specified but no version is specified, the purge applies to all versions of the namespace.
- order_type: The order type mnemonic. If specified, only orders with this type are purged.
- order_source: The order source mnemonic. If specified, only orders with this source are purged.
- commitCount: The number of orders to purge before committing the transaction to the database. If specified, this can improve the performance of the order purge by breaking it up into smaller transactions.
- order_id_upper: The order ID number used with the orderIdLessThan parameter which specifies the exclusive upper order ID bound to purge.
- order_id_lower: The order ID number used with the orderIdGreaterOrEq parameter which specifies the inclusive lower order ID bound to purge.
- op_number: The number of purge operations to run in the database in parallel. The value can be a power of two of the set 1, 2, 4, 8, 32, or 64.
For example:
```
xmlie.orderPurge.purgeBefore=2006-06-30T23:59:59 EST
xmlie.orderPurge.orderStates=COMPLETED
xmlie.orderPurge.namespace=default
xmlie.orderPurge.version=1.0.0.0.0
xmlie.orderPurge.orderType=ot
xmlie.orderPurge.orderSource=os
xmlie.orderPurge.commitCount=10
xmlie.orderPurge.orderIdLessThan=10
xmlie.orderPurge.orderIdGreaterOrEq=50
xmlie.orderPurge.parallelism=64
```
If you want to schedule a purge of some or all orders on a certain date using the scheduleOrderPurge attribute for the ant purge command, edit the following additional arguments:
```
xmlie.orderPurge.startDate=start_date
xmlie.orderPurge.stopDate=stop_date
```
Where:
- stop_date: The time when the purge should stop, even if all orders satisfying the purge criteria have been purged (for example, stop the purge before peak hours). If no stop_date is specified, the purge stops when all orders satisfying the purge criteria have been purged.
- start_date: For scheduled purges only - the time when the purge should start (must be later than the current time). When the start_date is reached, the purge starts automatically. If no start_date is specified, the purge is immediate.
For example:
```
xmlie.orderPurge.purgeBefore=2006-06-30T23:59:59 EST
xmlie.orderPurge.orderStates=COMPLETED
xmlie.orderPurge.namespace=default
xmlie.orderPurge.version=1.0.0.0.0
xmlie.orderPurge.orderType=ot
xmlie.orderPurge.orderSource=os
xmlie.orderPurge.commitCount=10
xmlie.orderPurge.orderIdLessThan=10
xmlie.orderPurge.orderIdGreaterOrEq=50
xmlie.orderPurge.parallelism=64
xmlie.orderPurge.startDate=2007-01-01T00:01:01 EST
xmlie.orderPurge.stopDate=2007-12-31T23:59:59 EST
```
If you want to remove an scheduled order purge that has not started using the removeOrderPurge attribute for the ant purge command, edit the following arguments:
```
xmlie.orderPurge.jobId=job_id
```
where job_id is the job ID of the scheduled purge.

For example:
```
xmlie.orderPurge.jobId=0
```
Note:

Orders that satisfy the purge criteria are purged and related details such as the number of orders purged are logged in the XMLIE log file (as configured in config.xml). If an error occurs, the purge stops. Errors and exceptions are output to the command line and are logged in the log files.
Use the following syntax to run an immediate order purge:
```
ant immediateOrderPurge
```
Use the following syntax to run a scheduled order purge:
```
ant scheduleOrderPurge
```
Use the following syntax to list all scheduled order purges that have not started:
```
ant listOrderPurges
```
Use the following syntax to remove an order purge that has not started:
```
ant removeOrderPurge
```

About Migrating Orders

XMLIE provides the ant migrate command and a migrate.bat script to migrate (copy) orders from one version of a cartridge to another. You can only migrate orders between versions of the same namespace, not between different namespaces. You can also migrate order data, reference numbers, remarks, attachments and specify a single order type/source to migrate, or all order types/sources within the cartridge.

For example, you may need to migrate orders within a cartridge when upgrading to a new version of OSM. Migrated orders are placed at the first process task, regardless of where the original order was in the process flow.

You cannot migrate orders across environments, for example, from a production environment to a test environment.

XMLIE migrates orders in three steps:

Create a new order and copy data from the source order to the target order.

All order field data is copied provided the field has a value in the source order and the field is defined in the target order's creation task data. Order reference numbers and remarks/attachments are also copied if copyReference and copyRemarks are set to true. The migrated order is placed at the first process task, not at the equivalent task in the original order.
Once the copy is complete, close the source order (closeSource set to true).

Note:

If you choose to close the source order, the Exception Processing function must be associated with your workgroup.
Submit the target order (submitTarget set to true).

Orders are migrated individually. If an error occurs in any of these steps and errorAction is set to abort, processing stops immediately. Prior steps are not rolled back. If errorAction is set to ignore, any remaining steps are skipped and the process starts over at step 1 with the next available order to be migrated.

Note:

Order migration should only be done within a window where no other order processing will occur.

It is extremely important that the target order creation task data contain all of the fields in the source order. The fields must be the same data type and have the same mnemonic and length to be considered equal. Any field that exists in the source order but not in the target creation task data is ignored. Fields that are defined in the target creation task data that have no associated data in the source order remain blank.

The most common failure scenarios are:

The specified target version or type/source combination does not exist. This is a fatal exception because no orders can be migrated. Processing halts immediately regardless of the errorAction setting.
The target order does not submit because the target creation task data contains mandatory fields that were not set in the source order.

Configuring and Running an Order Migration

To configure and run an order migration:

Configure the config.xml file migrate and userInteraction elements.
```
<migrate submitTarget="submitTarget" closeSource="closeSource" copyReference="copyReference" copyRemarks="copyRemarks" errorAction="errorAction"/>
<userInteraction confirmation="confirmation"/>
```
where:
- submitTarget: Options are:
  - true: Submits the target order following migration. (default)
  - false: Leaves the target order in the creation task.
- closeSource: Options are:
  - true: Closes the source order following migration. If you choose to close the source order, the Exception Processing function must be associated with your workgroup. (default)
  - false: Leaves the source order unchanged by the migration operation.
- copyReference: Options are:
  - true: Sets the order reference number of the target order to that of the source order. (default)
  - false: Leaves the target order reference number empty.
- copyRemarks: Options are:
  - true: Copies the source order remarks and attachments to the target order. (default
  - false: Does not copy remarks and attachments.
- errorAction: Options are:
  - abort: Stops processing immediately. (default)
  - ignore: Attempts to migrate the next available order.
- confirmation: Used for validation while migrating, so if there are any warnings/errors it might ask user for confirmation. Options are:
  - true: Confirms the warning/error message if any.
  - false: Does not confirm the warning/error messages if any.
If you are using batch scripts, use the following syntax to migrate an order from one version of a cartridge to another version of the same cartridge:
```
migrate.bat config/config.xml -sourcenamespace namespace -sourceversion version sourceordertype type -sourceordersource source -targetversion version
```
where:
- namespace: Must be specified. Valid values are the namespace mnemonic.
- version: Must be specified. The versions of the source namespace and the target namespace.
- type: The order type mnemonic. If specified, only orders with this type are migrated.
- source: The order source name. If specified, only orders with this source are migrated.
For example:
```
migrate.bat config/config.xml -sourcenamespace default -sourceversion 1.0 -targetversion 2.0
```
and
```
migrate.bat config/config.xml -sourcenamespace default -sourceversion 1.0 -sourceordertype request for long distance -sourceordersource client care -targetversion 2.0
```
If you are using the ant migrate command, do the following:
1. Open the SDK/XMLImportExport/build.properties file.
2. Edit the following arguments:
```
xmlie.root.namespace=namespace
xmlie.root.version=version
xmlie.root.sourceordertype=type
xmlie.root.sourceordersource=source
xmlie.root.targetorderversion=version
```
  where:
  - namespace: Must be specified. Valid values are the namespace mnemonic.
  - version: Must be specified. The versions of the source namespace and the target namespace.
  - type: The order type mnemonic. If specified, only orders with this type are migrated.
  - source: The order source name. If specified, only orders with this source are migrated.
  For example:
```
xmlie.root.namespace=bb_ocm_demo
xmlie.root.version=1.0.0.0.0
xmlie.root.sourceordertype=Add Order
xmlie.root.sourceordersource=Add Order
xmlie.root.targetorderversion=1.0.0.0.1
```
3. Use the following syntax start a migration from one version of a cartridge to another version of a cartridge:
```
ant migrate
```

About Validating the Metadata Model and Data

XMLIE provides the validate command, which is used to assure metadata model validity for an OSM schema. Using the validate command, you can perform the following:

Model validation: The XML schema model defines most entity relationships and constraints.
Pending order validation: This validation is applied during the import process (import.bat). It performs validations that have not been covered by validate.bat.

Note:

When you perform a validation, you must supply a well-formed model, otherwise you may encounter undefined exceptions.
The application applies an XML schema validation as well as some additional rules that could not be implemented in the XML schema. You can use any XML application to validate the model against the schema, but for additional validations, the explicit validation (using validate.bat) or implicit validation (before import or after export), assures model correctness and completeness.

You can validate the metadata model before the import takes place, or change config.xml so that the validation takes place during the import.

Configuring and Running an XML Document Validation

To configure and run a validation:

Configure the config.xml file.
```
<validation validateAgainstDB="validateAgainstDB" validateDocument="validateDocument" validationReportURI="filename_path"/>
```
where:
- validateAgainstDB: Options are:
  - true: Validates the XML document against existing orders in the database schema to ensure it is compatible. (default)
  - false: Does not perform an XML model validation against the database schema.
- validateDocument: Options are:
  - true: Validates the XML document against the OSM XML schema to ensure it is well formed. (default)
  - false: Does not perform the XML document validation.
- filename_path is the path to the validation log file that includes the file name of the validation log file.
Do one of the following:
1. If you are using Ant commands, do the following:
```
ant validate
```
2. If you are using batch scripts, do the following:
```
validate.bat xmlModelFile config\config.xml
```

Validating an XML Document During the Import or Export Process

To validate an XML document during the import or export process, set the configuration file validateModel parameter to true. See "Configuring and Running an Import" and "Configuring and Running an Export" for syntax information and examples.

About Creating a Graphical Representation of the Metadata Model

XMLIE provides the modeldoc command, which is used to convert an OSM metadata XML document into an HTML presentation. The HTML presentation is a graphical representation of the metadata model which is much easier to understand and navigate than the metadata XML document. You can use the resulting HTML presentation to view the relationships between and dependencies of the various metadata elements using standard HTML presentation navigation methods.

If you are going to use the modeldoc.bat script or the ant htmlModel command to create HTML representations of cartridge metadata, some configuration needs to be set up in order for Graphviz to support these commands and scripts.

Configuring and Creating a Graphical Representation of a Metadata Model

To configure and create a graphical representation of a metadata model:

Download and install GraphViz. For more information see OSM Installation Guide.
Update the SDK\XMLImportExport\config.bat script with an environment variable containing the path to the third-party GraphViz library.

For example:
```
set GRAPHVIZ=C:\Applications\ATT\Graphviz\bin
```
If you are using the SDK\XMLImportExport\modeldoc.bat script, update the Java command line in the modeldoc.bat file with an entry referring to the environment variable containing the path to the third-party GraphViz library:
```
%JAVA_HOME%/bin/java %JAVAOPTS% -classpath %CLASSPATH% %APP_PROPERTIES% com.mslv.oms.metadatahandler.operation.ModelDocOperator %XML_MODEL% %GRAPHVIZ% ./modeldoc
```
Note:

The modeldoc.bat script, due to external limitations, is not case sensitive. Because of this, it does not work if two entities' documents go into the same directory and their names are differentiated only by capitalization, for example two tasks in the same process with names like IsDebugOn and isDebugon.

This limitation is only for the modeldoc.bat script, not for the ant htmlModel command, used on UNIX and Linux systems.
If you are using the ant htmlModel command, configure the graphiz property in the SDK\XMLImportExport\build.xml file to specify the directory where the third-party GraphViz software is installed. For example:
```
<property name="graphiz" value="./bin/ATT/Graphviz/bin"/>
```
If you are using batch scripts, run the following script:
```
modeldoc.bat xmlModelFile HTMLModelDirectoryPath
```
where HTMLModelDirectoryPath: Specifies the path to the directory for the HTML model files for the modeldoc.bat script.
If you are using the ant htmlModel command, run the following command:
```
ant htmlModel
```

Viewing the Graphical Representation

To view the HTML presentation, open the resulting HTML index file and begin navigating through the metadata model using the automatically generated hyperlinks.

Note:

To view the HTML presentation, your browser must support Adobe SVG Viewer.