import Command

import [list] [property] ADMIN_TYPE TYPE_PATTERN [OPTION_ITEM [OPTION_ITEM]...]
from file FILENAME [use [FILE_TYPE FILENAME [FILE_TYPE FILENAME]...];

• ADMIN_TYPE is the administrative definition type to be imported. It can be connection or any of the following:

  admin	format	page	relationship	table
  association	group	pathtype	resource	type
  attribute	index	person	role	uniquekey
  channel	inquiry	policy	rule	user
  command	location	portal	server	vault
  customevent	menu	product	site	workspace
  form	package	program	store

  The ADMIN_TYPE can include a TYPE_PATTERN to filter the definitions to be imported.

• OPTION_ITEM is an import clause that further defines the requirements of the import to be performed. It can be any of the following:

  [!]icon	[!]overwrite	continue
  commit N	skip N	pause N
  [!]history

• OPTION_ITEMs can be used in any order before the from file clause. The sections below describe these options.
• FILENAME is the path and name of the existing .mix file from which to import the information.
• FILE_TYPE can be used to specify files to be used to control the import and log files and exceptions. FILE_TYPE can be any of the following:

  map

  exclude

  log

  exception

  The use keyword must be used with any files that are specified: map files, exclude files, log files, or exception files. If more than one file type is to be used, the use keyword should only be stated once. (The use keyword in not used at all in the export command).

• FILE is the name of the file to be used with FILE_TYPE . For example, an exclude FILE would be the name of the existing file that lists any objects which should not be included in the import.

If triggers are attached to an object being imported, they can be executed at the time of import. Therefore, this MQL command must be run before importing objects into a database.:

trigger off; 

List Clause

The List clause of the Import command is used to show on the screen what would be done on import. It enables you to perform a practice run, ensuring that the files to be imported are read correctly. For example:

import list admin * from file c:\admin.mix;

This might output:

vault Standardsvault ...
store Drawingsstore ...
attribute Sheet Countattribute ...
program Cadraprogram ...
type Drawingtype ...
relationship Reportrelationship ... 
format Cadraformat ...
role Managerrole ...
group Salesgroup ...
person Daveperson ...
policy Reportspolicy ...

Overwrite Clause

The overwrite clause is used if objects were incrementally exported. If an object already exists, the overwrite clause tells the import command to modify any objects that are found to already exist. Without the overwrite clause, if an administrative object exists, the import will fail, since it will try to create a new object with the same name as an existing object.

When !overwrite is used, the objects that don’t import because they already exist are written to the exception file (if specified).

When importing, the default for administrative objects is !overwrite . For business objects, the default is overwrite .

Overwrite will not work on administrative objects that are referenced by business objects. This eliminates the possibility editing an administrative object in a development environment, testing, and then importing into a production environment.

Normally when importing types, the new types are added to the mxTNR table. When the overwrite clause is used, the mxTNR table is not updated whether or not it contained a value for the imported types. To ensure that types have unique keys, execute this MQL command after you import types using the overwrite clause:

mod uniquekey mxTNR add type <typeName>;

Skip N Clause

Skip N provides a way not to import the beginning N number of objects in an export file. It is helpful if a previous attempt to import a file was unsuccessful and aborted part way through the process.

Commit N Clause

The commit clause gives you the ability to specify N number of objects to enclose in transaction boundaries. In this way, some progress could be made on the import even if some transactions are aborted. The default is 100.

Pause N Clause

Pause allocates the amount of time in seconds to wait between import transactions. It is used with the commit clause. A pause is beneficial when import is running in the background for an extended period of time. It provides a larger window of opportunity for you to access the database machine’s resources. Import transactions run continuously when this clause is not included.

Continue Clause

The continue clause proceeds with additional imports even if an error is generated. When continue is used, it is helpful to also use the log and exception clauses so that diagnostics can be performed and the data that caused the error is trapped.

Map Clause

The Map clause of the Import command indicates a map file which lists any new locations or names for objects. The map file must use the following format:

ADMIN_TYPE OLDNAME NEWNAME
ADMIN_TYPE OLDNAME NEWNAME

• ADMIN_TYPE can be any of the administrative object types: vault, store, location, server, attribute, and so on.
• OLDNAME is the name of the instance that will be found in the import file.
• NEWNAME is the name that should be substituted for OLDNAME when imported into the new database.

As indicated, each definition to be changed must be delimited by a carriage return.

On Windows, the map file requires a carriage return after the last line in order for the last line to be read. On UNIX, there is no such requirement.

Exclude Clause

Use the Exclude clause of the Import command to indicate a file that lists any objects to be excluded. For example:

import admin TEST* from file teststuf.mix use exclude nogood.obj;

The exclude file for administrative objects must use the following format:

ADMIN_TYPE NAME
ADMIN_TYPE NAME

• ADMIN_TYPE can be any of the administrative object types: vault, store, location, server, attribute, program, type, relationship, format, role, group, person, workspace, policy, form, association, or rule.
• NAME is the name of the definition instance that should be excluded in the import. Wildcard patterns are allowed.

Each definition to be excluded must be delimited by a carriage return.

Log FILE Clause

Apply the Log File clause to specify a file to contain error messages and details for the import process. The output is similar to using the verbose flag, but includes more details.

Exception FILE Clause

Use the Exception File clause to provide a file location for objects to be written to if they fail to import. If a transaction aborts, all objects from the beginning of that transaction up to and including the “bad” object will be written to the exception file.

Syntax

import [list] bus[inessobject] BUSID [OPTION_ITEM [OPTION_ITEM]...] from 
file FILENAME [use [FILE_TYPE FILE [FILE_TYPE FILE]...];

• BUSID is the Type, Name, and Revision of the business object. Wildcard patterns are allowed. (You cannot use OIDs with import bus).
• OPTION_ITEM further defines the requirements of the import to be performed. It can be any of the following:

  [!]attribute	continue	[!] overwrite	pause N
  [!]basic	[!]file	[!]relationship	skip N
  [!]captured	[!]history	!fromrelationship	[!]preserve
  commit N	[!]icon	!torelationship	[!]state
  from vault VAULT_NAME to vault VAULT_NAME

• OPTION_ITEMs can be used in any order before the from FILE clause. The sections below describe these options.
• FILENAME is the name of the file from which to get the exported ASCII data.
• FILE_TYPE can be used to specify files to be used to control the import and log files and exceptions. FILE_TYPE can be any of the following:

  map

  exclude

  log

  exception

  The use keyword must be used with any files that are specified: map files, exclude files, log files, or exception files. If more than one file type is to be used, the use keyword should only be stated once. (The use keyword in not used at all in the export command).

• FILE is the name of the file to be used with FILE_TYPE . For example, an exclude FILE is the name of the existing file that lists any objects which are not included in the import.

For more information, see import Command.

From Vault and To Vault Clauses

One way to redirect the import of business objects into a new location (vault) is to use the from vault clause with the to vault clause. For example, to place all business objects that were in vault Test into vault Prod in the new database, use:

import businessobject * * * from vault Test to vault Prod from file c:\revb.mix;

Another alternative for redirecting business objects during import is to use a map file. For more information, see Map Clause. If you want to import business objects that have revisions and put them into a different vault, you must use a map file or errors will occur.

Excluding Information

When importing business objects, the default is to include everything about the object. However, you can specify that some parts of the .mix file should not be imported. Any information that was omitted during the export cannot be included during import, regardless of the use of this clause.

The table below shows the options which can be used when importing business objects to exclude information:

For example, to import all objects from file mystuff.mix and exclude all checked in files, use:

import businessobject * * * !file from file mystuff.mix;

For captured files, file metadata can be included, without the actual file content by using the !captured option. For more information, see Excluding Files.

To import a single object without including history, use:

import businessobject Assembly “ABC 123” A !history from file obj.mix;

To import a single object without any of its relationships, use:

import businessobject Assembly "ABC 123"A !relationship from file obj.mix;

When importing objects, several options are available with regard to relationship information:

• Include all relationship information (default)
• Exclude all relationship information (! relationship)
• Exclude to relationships ( !torelationship)
• Exclude from relationships ( !fromrelationship).

To import all objects and reset the current state to the beginning of the lifecycle, use:

import businessobject * * * !state from file obj.mix;

Preserve Clause

The Preserve clause is used when importing business objects. It specifies not to change the object’s modification date to the date of the import.

Syntax

extract |bus OBJECTID    | [OPTION_ITEM [OPTION_ITEM]]from file FILENAME |into| file NEW;
        |ADMIN ADMIN_NAME|                                               |onto| 

• OBJECTID is the OID or Type Name Revision of the business object and can include the in VAULTNAME clause, to narrow down the search. If a pattern is listed, the first match is extracted.
• ADMIN is any of the administrative types to be extracted.
• ADMIN_NAME is the name of the administrative object to be extracted.
• OPTION_ITEM can be any of the following:

  remaining

  skip N

  exclude FILE

• FILENAME is an existing export file from which to extract information.
• NEW is the file that extract creates or appends with the requested information.

Remaining Clause

The Remaining clause extracts from the specified object to the end of the file.

Import Business Object

The following command:

• Imports business objects from export.mix
• Commits the import transaction every 5 business objects
• Writes the audit trail to import.log
• Writes exception objects to error.mix

import bus * * * commit 5 continue from file export.mix use log import.log 
exception error.mix;

If an error occurs, you can look at the entries in the import.log to see what went wrong. Once the problem is resolved, the error.mix file could be used to import the objects that were not imported successfully the first time.

When object imports fail, the transaction aborts and rolls back the import of any objects that precede it in the transaction boundary. These are the objects written to the exception file. A new transaction is started with the next object. Using the example above, suppose the third object attempted caused a problem; the transaction is aborted. The first three objects are written to error.mix and a new transaction begins with the fourth object. After the eighth object was imported, the transaction is committed and the new database has five new objects.

Extract from Export File

For example, if all administrative objects were extracted into one file called admin.mix, you can extract all policies into a separate file as follows:

extract policy * from file admin.mix into file policy.mix;

To extract all business object from the fifth entry until the end of the file use:

extract bus * * * skip 4 remaining from file objects.mix into file newobjs.mix;