systemimport(3.3)

systemimport
 [ -s|-skipexisting ] 
 [ -pp|-preservepermissions ] 
 [ -nameconflict re|an|sk ]
 [ -keyconflict re|an|sk ]
 [ -namekeyconflict rn|rk|an|sk ]
 [ -he|-holdexecution [ r|sr|sir|wr ] ]
 [ -nr|-norollback ] 
 [ -no|-newowner ] 
 [ -cp|-configfrompackage ]
 [ -iv|-importextrefvalues ]
 [ -select <xml-selection file> [ -dryrun ]  [ -onerror < ABORT | IGNORE > ]  ] 
 [ -m|-message ] 
 [ -u|-upgrade ]
 [ -dryrun ]
 <export file|directory>
 [password]
----------------------------------------------------
Import Conflict
re  = Replace
sk  = Skip
an  = Add New
rk  = Replace Key conflict
rn  = Replace Name conflict

Holdexecution
r   = Restart
sr  = Stop and Restart
sir = Stop Immediate and Restart
wr  = Wait for completion and Restart

This command imports a ZIP file, an MZP file, or a directory. If an import entry is in conflict with an entry that already exists in the current system, the entry will not be imported. An example of such a conflict might be an identical entry name, but a different ID.

If you try to import exactly the same MZP file or workflow package twice you get an error. The error is given if the checksums of MZP files are identical. Note that if you export exactly the same configuration twice the checksums will differ.

A workflow group that is scheduled to start while an import activity is happening, will not start until the import is complete.

Options

OptionDescription

[-s|-skipexisting]

If you use the skipexisting option, the imported data will not overwrite existing configurations that have the same key, name, type, and folder. This means that repeatedly importing a configuration, does not overwrite the data.

[-pp|-preservepermissions]

When user permissions are modified, set the preservepermissions parameter to prevent user permissions in the current system from being updated while importing a configuration.

[-nameconflict re|an|sk]

Decide what to do when there is a name conflict; replace, add new, or skip. Default is to skip the item when there is a name conflict.


Note

If -nameconflict is not specified and there is a name conflict, the configuration is skipped. To avoid this, use -dryrun to verify before importing.

[-keyconflict re|an|sk]

Decide what to do when there is a key conflict; replace, add new, or skip. Default is to skip the item when there is a key conflict.

Note

If -keyconflict is not specified and there is a key conflict, the configuration is skipped. To avoid this, use -dryrun to verify before importing.

[-namekeyconflict rn|rk|an|sk]

Decide what to do when there is a key or name conflict; replace, add new, or skip. Default is to skip the item when there is a key or a name conflict.

Note

If neither of -namekeyconflict, -keyconflict, or -nameconflict is specified and there is a key or name conflict, the configuration is skipped. To avoid this, use -dryrun to verify before importing.

[-he|-holdexecution [ r | sr | sir | wr ] ]

Use the holdexecution option to prevent scheduled workflow groups from being started while importing configurations.

If a workflow or a workflow group does not stop within 5 minutes (300 seconds) when doing a systemimport with either one of the following holdexecution parameters: sr, sir, and wr, a timeout will occur. You can change the timeout value  by setting the Platform property mz.import.suppress.timeout.

When the import is completed and a workflow group is still running, systemimport -holdexecution [ r | sr | sir | wr ] awaits the current running workflow member to come to a stop, and then restarts the whole group instead of continuing the execution of the member that follows.

If you do not specify any of the r, sr, sir or wr options:

  • A batch workflow or a workflow group will remain suppressed until all the workflows finish executing. Then, the workflow or the members of the workflow group, become idle.
  • A real-time workflow group will return to the running state.

systemimport -holdexecution generates events. To retrieve the events data, configure an Event Notification to transfer it according to your preferences. 

holdexecution Parameters

Select the action that should resolve held executions:

  • r (restart): When the import activity is done, and a workflow group is partly executed, specifying this option will restart that workflow group. Workflow groups that are fully executed, will not be restarted. A workflow that is started manually, will be restarted if it has been stopped.

  • sr (stop and restart): Stops the workflows or workflow groups that are still running after an import is complete, waits for them to come to a stop or finish processing a batch, and then restarts synchronously all the workflow groups and all the manually started workflows that had not executed completely within the timeout boundaries.

    Note!

    A workflow that becomes unreachable after a system import has begun, will be restarted only when and if the contact with the Execution Context that it runs on, is regained while still importing.

    If a workflow is unreachable when system import is started, the import is aborted and the following error message is generated: Abort Import: At least one wf that is Unreachable.

  • sir (stop immediately and restart): Stops the workflows or workflow groups that are still running after an import is complete, even in the middle of processing a batch, and synchronously restarts all the workflow groups and all the manually started workflows that had not executed completely within the timeout boundaries.

    Note!

    An unreachable workflow is restarted once contact with the Execution Context that it runs on, is regained. 

  • wr (wait for completion and restart): After an import is complete, synchronously restarts all the workflow groups and all the manually started workflows that had not executed completely within the timeout boundaries.

    Note!

    Any workflow that runs past the timeout limit is restarted as soon as it completes execution.

Example - Using the holdexecution Option

$ systemimport -s -he r export.zip 
$ systemimport -s -he sr export.zip 
$ systemimport -s -he sir export.zip 
$ systemimport -s -he wr export.zip

[-nr|-norollback]

When you us the systemimport command, a file that contains rollback information will be created. This file contains data about configuration changes during the system import, and is saved in the directory where you apply the command. You use the rollback file to undo a system import and return to the configuration that you had before the system import.

Note!

Use the importrollback command only to revert the systemimport command and not for the purpose of a system rollback. For further information see importrollback(3.3).

To suppress the creation of the rollback file, provide either a nr or a norollback option.

[-no|-newowner]

Change ownership of the configuration on import. The user must match an user already defined in the Access Controller.

[ -cp|-configfrompackage ] 

Add this option if you would like to import the Workflow Package (MZP) as configuration instead of a Workflow Package.
[ -iv|-importextrefvalues ]

Add this option if you would like to import the values from External References.

[-select <xml-selection file>
[-dryrun ]
[-onerror < ABORT | IGNORE > ] ]

Note!

Do not use -select for Workflow Packages (MZP files).

The -select <xml-selection file> parameter enables you to:

  • Provide systemimport with an XML file that specifies your selection of configurations and workflow tables.
  • Use [ -dryrun ] to test data compatibility prior to actually importing

    Note!

    Dry run is only applicable to ZIP file and directory.

  • Use [ -onError < ABORT | IGNORE > ] to manage an occurrence of an error

XML Selection File

This selection information that you find in the XML selection file corresponds to the selection information that you specify on the System Import tool view, in the Desktop user interface.

The XML selection file consists of two main tags:

  • <configurations>: contains your configuration import selections
  • <workflows>: contains your workflow tables import selections

<configurations>

Select configurations from the <Export file|directory> that systemimport imports.

  • Use the 
  • resolveDependencies attribute to either include (true), or ignore (false), dependent configurations. See the following example:

Example - The resolveDependencies attribute

<import> 
 <configurations>
<!-- Ignoring dependencies of the Default.x configuration-->  
 <configuration name="Default.x" resolveDependencies="false"/>
<!-- Including dependencies of the Default.y configuration--> 
 <configuration name="Default.y" resolveDependencies="true"/>
<!-- Ignoring dependencies of the Default.z configuration--> 
 <!-- Note: Equal to selection of Default.x above --> 
 <configuration name="Admin.C07E02_DEMO_BWF"/>
<!-- Ignoring dependencies of  
  configurations within the folder --> 
 <configuration foldername="systemunits"/>
<!-- Including dependencies of all the  
  configurations in the folder --> 
 <configuration foldername="billing"  
  resolveDependencies="true"/>
</configurations> 
 </import>


  • To import all the configurations that are included in a specific folder, include the following text in the XML file:
    <configuration foldername="myFolder"/>

    Note!

    If you specify configuration selections in the XML file that do not exist in the Export file, a warning is generated. 

<workflows>

This XML tag enables you to use systemimport [-select <xml-selection file>] to import both workflow configurations and their CSV file in one action.
Use this tag to associate workflow tables with CSV data files.

Note!

  • Set the keepOld attribute to true in order to prevent removal of workflow table data which has no match in the export file. Use false to overwrite the data. This parameter is only used during import, and has no effect during export.
  • The onError attribute can either be set from the XML selection file, or from the systemimport in-line command. If set from both, the XML selection file attribute is the value that applies. For further information about the values that you can choose from, see onError. This parameter is only used during import, and has no effect during export.
  • Set the encryptPassword attribute to the workflow configuration password if the workflow configuration is password protected.

Example - The XML selection tags

<import> 
  <configurations> 
  <configuration name="myFolder.DB_PROFILE"/>  
  <configuration name="myFolder.APL_PROFILE"  
  resolveDependencies="true"/> 
  <configuration foldername="myFolder"/>  
  </configurations> 
  <workflows > 
  <workflow name="Mobile.FTP_workflow"  
  wfTable="/home/user1/FTP_workflows.csv"/>  
  <workflow name="Mobile.SFTP2_workflow"  
  wfTable="/home/user1/SFTP2_workflows.csv"  
  resolveDependencies="true"/> 
  <workflow name="Mobile.GGSN1_workflow"  
  wfTable="/home/user1/GGSN1_workflows.csv"  
  resolveDependencies="true"  
  onError="ask"/> 
  <workflow name="Mobile.GGSN3_workflow"  
  wfTable="/home/user1/GGSN3_workflows.csv"  
  resolveDependencies="true"  
  onError="ignore"/> 
  <workflow name="Mobile.GGSN4_workflow"  
  wfTable="/home/user1/GGSN4_workflows.csv"  
  resolveDependencies="true"  
  onError="abort"/> 
  <workflow name="Mobile.GGSN5_workflow" 
  wfTable="/home/user1/GGSN5_workflows.csv"  
  resolveDependencies="true"  
  keepOld="false"  
  encryptPassword="password"  
  onError="ask"/>  
  </workflows> 
 </import>
[ -m|-message]

If you want to add a comment when using the systemimport command, the -m or -message option can be used as in the following example:

Example - message

$ systemimport -m "My Import" /home/Directory/<file to import>.zip

"My Import" will be the commented.

The comment will replace the default information saved when making a system import, and will both be included in the System Log message that is generated, as well as visible when selecting to view history in any of the configurations in the imported data.

[-u|-upgrade]

When exports have been made in a previous version of , they may have to be upgraded. In this case you can use the -u or -upgrade option as in the following example:

Example - upgrade

$ systemimport -u <file to import>.zip

The configurations will then be upgraded.

[-dryrun]

To test data compatibility prior to actually importing.

Note!

Dry run is only applicable to ZIP file and directory.

<export file|directory>Specify the path to the directory or ZIP file that contains the configurations you want to import.
[password]To import encrypted configurations, provide a password.