importUtility script

Import resources that are exported from Sterling B2B Integrator or another Global Mailbox system.

Usage

Use the importUtility to import resources that are exported from Sterling B2B Integrator or another Global Mailbox system. The importUtility script supports two actions: import and report. The import action performs import operations on the target system, creating and modifying resources as required. The report action does not make any changes on the target system and produces a report indicating any errors or warnings that might occur if an import action was performed on the input file. A properties file can be specified as --importSelectionFileName to select the individual resources that are to be imported and to supply application name mappings.

File location

install_dir/MailboxUtilities/admin/bin

Environments

  • Linux® or UNIX (importUtility.sh)
  • Windows (importUtility.bat)

Authorization

You must be a Global Mailbox administrator to view and modify the importUtility command line script.

To use the command line script, you must provide your Global Mailbox administrator user ID and password.

Syntax

With the import action:
importUtility.[sh/bat] import --importFileName= --importFileFormat= --reportFileName= --importSelectionFileName= --mailboxImportMode= --virtualRootImportMode= --eventRuleImportMode= --validateAppUsers --validateEventData  --defaultAppName --adminUser= --adminPassword=
With the report action:
importUtility.[sh/bat] report --importFileName= --importFileFormat= --reportFileName= --importSelectionFileName= --mailboxImportMode= --virtualRootImportMode= --eventRuleImportMode= --validateAppUsers --validateEventData  --defaultAppName --adminUser= --adminPassword=

Option descriptions

--importFileName
The name of the file to be imported. Required.
--importFileFormat
Indicates the format of the file being imported. Valid values are:
  • --importFileFormat=native - for Global Mailbox to Global Mailbox cases. This is the default, and is the XML format produced by the exportUtility script.

  • --importFileFormat=b2bi - for Sterling B2B Integrator to Global Mailbox cases.

--importSelectionFileName
The name of a property file listing the resource instances to be imported and any application mapping to be applied during import. If --importSelectionFileName is not specified, all resource instances contained in file are imported and no application mapping is applied. For the specification of this file, see importSelectionFileName properties file.
--reportFileName
The name of the report file to be generated, listing the resources imported and any errors or warnings during import. If not specified, the report is written to a file named import.rpt in the current directory, overwriting any existing file of the same name.
--mailboxImportMode
Import mode for mailboxes. Valid values are:
  • CREATEONLY - Mailbox import fails if the leaf mailbox already exists, without applying any permissions anywhere in the mailbox path. If the leaf mailbox does not exist, it and any other missing mailbox in the mailbox name are created and permissions within the export file are applied to existing and created mailboxes.
  • MERGE - Any mailbox in the path that does not exist is created and permissions within the export file are applied to existing and created mailboxes. Default.
--virtualRootImportMode
Import mode for virtual roots. Valid values are:
  • CREATEONLY - Virtual Root import fails if the user already has a virtual root, the existing virtual root is not changed. Only creates a virtual root for a user without a virtual root.
  • MERGE - Creates a new virtual root for the user or updates an existing virtual root (changing the mailbox path). Default.
--eventRuleImportMode
Import mode for event rules. Valid values are:
  • CREATEONLY - Event Rule import fails if there is already an event rule of the same name for the same application. Only creates new event rules.
  • MERGE - Creates a new event rule or updates an existing event rule of the same name for the same application. Changes the rule filter and completely replaces any custom data properties. For event rules with a defined set of mailboxes, a MERGE import adds mailboxes to the existing event rule but does not remove any mailboxes. A MERGE import fails if the existing event rule has a different allMailboxes setting than the exported representation. Default.
  • OVERWRITE - Creates a new event rule or updates an existing event rule of the same name for the same application. Changes the rule filter and completely replaces any custom data properties. OVERWRITE imports completely reset the mailbox selection for an existing rule, including changing the existing rule allMailboxes setting.
--validateAppUsers
Enables data validation for mailboxes and virtual roots, validating application users. (no value). Failed validation on virtual roots causes an error and prevents the virtual root from being imported. Failed validation on a mailbox imports the mailbox and produces a warning that the user associated with a permission is not found.
--validateEventData
Enables data validation for event rules, validated custom data. (no value). Failed validation causes an error and prevents the event rule from being imported.
--defaultAppName
A default application name that is applied to imported resources when the imported data format does not include application references. (For example, when importing B2Bi generated export data.)
--adminUser
The name of a Global Mailbox administrative user.
--adminPassword
The password for the Global Mailbox administrative user.

Example importFileName file

The following XML is an example of the input importFileName file, which is the output created by running the exportUtility script on another system:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:GlobalMailboxResources xmlns:ns2="http://www.ibm.com/mailbox/importexport/xml/v1/resources">
    <ResourceHeader Generator="Exporter" Date="201x-03-01T14:14:35.485-05:00"/>
    <Mailboxes>
        <Mailbox parentPath="/" mailboxName="home"/>
        <Mailbox parentPath="/" mailboxName="home/joe_manager">
            <UserPermission mailboxPath="/home/joe_manager">
                <Principal appName="B2Bi" id="joe_manager" name="joe_manager" displayName="joe_manager" admin="false" type="User"/>
                <MailboxPermission permission="VIEW_MAILBOX"/>
                <ApplicationPermission permission="EXECUTE"/>
            </UserPermission>
        </Mailbox>
        <Mailbox parentPath="/" mailboxName="home/joe_employee">
            <UserPermission mailboxPath="/home/joe_employee">
                <Principal appName="B2Bi" id="joe_employee" name="joe_employee" displayName="joe_employee" admin="false" type="User"/>
                <MailboxPermission permission="VIEW_MAILBOX"/>
                <ApplicationPermission permission="EXECUTE"/>
            </UserPermission>
        </Mailbox>
        <Mailbox parentPath="/" mailboxName="home/joe_supplier">
            <UserPermission mailboxPath="/home/joe_supplier">
                <Principal appName="B2Bi" id="joe_supplier" name="joe_supplier" displayName="joe_supplier" admin="false" type="User"/>
                <MailboxPermission permission="VIEW_MAILBOX"/>
                <ApplicationPermission permission="EXECUTE"/>
            </UserPermission>
        </Mailbox>
    </Mailboxes>
    <VirtualRoots>
        <VirtualRoot mailboxPath="/home/joe_manager">
            <Principal appName="B2Bi" id="joe_manager" name="joe_manager" displayName="joe_manager" admin="false" type="User"/>
        </VirtualRoot>
        <VirtualRoot mailboxPath="/home/joe_employee">
            <Principal appName="B2Bi" id="joe_employee" name="joe_employee" displayName="joe_employee" admin="false" type="User"/>
        </VirtualRoot>
        <VirtualRoot mailboxPath="/home/joe_supplier">
            <Principal appName="B2Bi" id="joe_supplier" name="joe_supplier" displayName="joe_supplier" admin="false" type="User"/>
        </VirtualRoot>
    </VirtualRoots>
    <EventRules>
        <EventRule ruleName="ALL_MBX" appName="B2Bi" enabled="true" filter="test.msg" allMailboxes="true">
            <CustomData name="BPNAME" value="HelloWorld"/>
            <CustomData name="USER" value="admin"/>
        </EventRule>
        <EventRule ruleName="MANAGER" appName="B2Bi" enabled="true" filter=".+" allMailboxes="false">
            <MailboxPath mailboxPath="/home/joe_manager"/>
            <CustomData name="BPNAME" value="EDIINTParse"/>
            <CustomData name="USER" value="joe_manager"/>
        </EventRule>
        <EventRule ruleName="SUPPLIER" appName="B2Bi" enabled="true" filter=".+" allMailboxes="false">
            <MailboxPath mailboxPath="/home/joe_supplier"/>
            <CustomData name="BPNAME" value="XMLAParserService"/>
            <CustomData name="USER" value="joe_supplier"/>
        </EventRule>
    </EventRules>
</ns2:GlobalMailboxResources>

Instruction for Global Mailbox container version

importUtility script will need read/write access to the output or input files, therefore for the GlobalMailbox container version, use PersistentVolume configured at /ibm/staging as the input or output file location. PersistentVolume is configured during the deployment stage, for details refer to Setting up PersistentVolume(s).