Export and Import iProcess Configuration

swadm

The swadm utility provides two commands:

  • EXPORT_IPE_CONFIG to export iProcess Engine and iProcess Technology Plug-ins configuration.

  • IMPORT_IPE_CONFIG to import iProcess Engine and iProcess Technology Plug-ins configuration.

You can use the export and import commands to easily replicate iProcess Engine environments. For example, if you need to create a test environment, which is similar to that of production, then you can use these two commands to export and import the configuration.

Prerequisites

• Import or export is possible only when there are same products installed on both the source and target iProcess Engines. (For example, if source has iProcess Technology Plug-in and EAICOM installed, then the target must also have these two products installed on the system.)
• The export-import must be run by pro user in Linux and administrator in Windows.
• The import file does not import USER values and attributes.
• You must complete and close the pending cases before the import because, any change in the node name from the import file can affect these cases during runtime.
• The system must have proper connectivity to the new database before importing the configuration file, specifically when using the -d option.
• Before you import the Windows Cluster, iProcess Engine must be down in both the cluster nodes.

EXPORT_IPE_CONFIG

EXPORT_IPE_CONFIG generates an output file and a manifest file. This output file serves as an input to the IMPORT_IPE_CONFIG command, which contains the configurations that include configuration files, specific configuration data, and registry entries (Windows). Manifest file is an HTML file that gives an overview of the generated output file.

Note:
• The format of the generated export file is iPEConfig_<yyyymmdd>_<hhmmss>_<MachineID>.dat
• The format of the generated manifest file is manifest_<yyyymmdd>_<hhmmss>_<MachineID>.html

The Export file is a readable text file. It is an output file, which you can use manually or make script modifications to the exported file to fine tune it ready for the target system. For example, changing process attributes to change behavior, changing debug settings for diagnosis, adding or removing processes for performance or resources reasons, changing ports due to firewall settings etc.

Note: The default path of the generated export file is $SWDIR/util. You can place the import file at any location. However, you have to provide the absolute path during the import.

The main purpose of the manifest file is to help you read through the configuration file created and give you an overview.

Warning: The manifest file is not meant for the import activity.

You can see the following Macros in the export file. The swadm utility replaces these macros during the import based on the inputs.

MACRO

Description

$SWDIR$

SWDIR path of iProcess Engine (forward slash)

$SWDIRN$

SWDIR path of iProcess Engine (backward slash)

$SWNODENAME$

Node name of iProcess Engine

$BGUSERNAME$

Background User or Schema

$MACHINENAME$

Machine name of the import machine

$DOMAINNAME$

Domain name of the import machine

$DOMAINUSER$

Domain User of the import machine

$ADMINUSER$

Admin User of the import machine

$FGUSERNAME$

Foreground User or Schema

$DBALIAS$

Database alias user intended to import

$SRVCNODENAME$

Normalized node name used for creating the iPE services (Windows)

$SRVCUSER$

Service User (Windows)

$IPTP_PASSWORD$

iPTP Password (SWPRO password is fetched during the import)

$DBIPADDR$

Utility evaluates the database's IP address based on the database alias provided during the import.

$CONNECTION_STRING$

Connection string is also evaluated based on the database alias provided during the import.
$DBNAME$ The ODBC name that the user intends to import
HOSTNAME The OS_USER_LOCATIONS and IDENTIFY_SPO_MACHINE_BY attributes are replaced with the HOSTNAME as value. You must correct these attributes after the import is completed.

IMPORT_IPE_CONFIG

Usage IMPORT_IPE_CONFIG \{[ -r <Enter the BG and FG passwords in the prompt>] | [-n] | [-p <BGUser Password> -u <FGUser Password>]} [Complete Filename with path] | [-d <Databae Alias>]

The following table describes the various options in the IMPORT_IPE_CONFIG command.

Options

Purpose

Machine A – Export

Machine B – Import

-r

Prompts the user to input passwords for <swpro> and <swuser> and saves those passwords to a password file.

 

Imports users and schema. Imports those passwords with -r.

-n

Preserves the target database details. There is no change in the database details, schema, users, or passwords.

NA

Retains users and schema. There is no change in the password.
-d

Switches to a different database.

 NA Uses the database specified with -d.

-p <swpro passwd> -u<swuser passwd>

Passes <swpro> and <swuser> passwords through command line.

Note: Schema and users are imported from the exported file.

Exports users and schema.

Picks passwords during runtime in the import machine.

<no option>

Imports schema and users from the exported file and there are no changes to the password file (you can use target instance password file).

Exports users and schema.

Imports users and schema. There is no change in the password.
Note: The assumption is that the <swpro> and <swuser> users exist in the database with correct passwords.

The following table lists the module that exists when importing the configuration file.

Module

Description

$SWDIR$/swdefs

Import includes the RPC Port number, Version, and Language.

NODES

If you choose to modify the node name of iProcess Engine during the import, the NODES table gets updated accordingly. Version entries get imported as the exported file.

$SWDIR$/etc/staffpms

Import includes DATE, TIME format, Database connection details, Custom Log Path, UTF-8 flag, Auto start and so on.

$SWDIR$/etc/staffcfg

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/sysevents.cfg

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/staff.mes

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/staffw.mes

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/stafferr.mes

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/audit.mes

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/english.lng/staffico

Import includes the entire configuration present in the export configuration file.

GLOBAL_VARIABLE

Import includes the entire configuration present in the export configuration file.

AQ_PORT_RANGE_CONF

Import includes the entire configuration present in the export configuration file.

AQ_PORT_RANGE

Import includes the entire configuration present in the export configuration file.

PORT_RANGE_CONF

Import includes the entire configuration present in the export configuration file.

PORT_RANGE_NODES

Import includes the entire configuration present in the export configuration file.

PROCESS_CONFIG

Import includes the entire configuration present in the export configuration file.

MBOX_SET

Import includes the entire configuration present in the export configuration file.

IQL_QUEUES

Import includes the entire configuration present in the export configuration file.

MBOX_SET_GROUP

Import includes the entire configuration present in the export configuration file.

PROCESS_ATTRIBUTES

Import includes the entire configuration present in the file. Few attributes like SWLIB_PATH, IDENTIFY_SPO_MACHINE_BY are handled separately.

SYSTEM_EVENT_CONF

Import includes the entire configuration present in the export configuration file.

$SWDIR$/seo/data/swentobjsv.cfg

Import includes the entire configuration present in the export configuration file.

$SWDIR$/config/notification.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/config/ipac.properties

Import includes the entire configuration present in the export configuration file. IP_ADDR is defaulted to 127.0.0.1.

$SWDIR$/config/log4j.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/tomcat/webapps/ipac/config/ipac.properties.json

Import includes the entire configuration present in the export configuration file. ApiUrl is defaulted to https://127.0.0.1:8443/

$SWDIR$/tomcat/conf/server.xml

Import includes the entire configuration present in the export configuration file.

$SWDIR$/libs/eai_mail.cfg

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/swjmx.properties

Import includes the entire configuration present in the export configuration file. SWJMXConfig.address is defaulted to 127.0.0.

$SWDIR$/etc/swjmx_log4j.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/swjmx_config.xml

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/swjmx_classpath.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/BWInstallerRegistry.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/XMLTransformInstallerRegistry.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/log4j.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/pojo.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/encoding.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/eaijavaplugin.properties

Import includes the entire configuration present in the export configuration file. Password and Database Connection String to connect to the database is evaluated at runtime during the import.

$SWDIR$/eaijava/jmxconfig.properties

Import includes the entire configuration present in the export configuration file. eaijava.db_connection, eaijava.db_user, eaijava.db_password, eaijava.db_schemaowner, eaijava.db_heartBeatSQL are handled separately.

$SWDIR$/eaijava/classloader.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/xmlparser.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/eaijavapooling.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/eaiframework/datetime.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/eaiframework/eaiframework.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/bw/cache.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/bw/jms.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/bw/bwjmscache.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/properties/eaitransform/eaitransform.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/eaijava/jmx/config.xml

Import includes the entire configuration present in the export configuration file. Password and Database Connection String to connect to the database is evaluated at runtime during the import.

$SWDIR$/eaiframework/frameworkconfig.xml

Import includes the entire configuration present in the export configuration file.

$SWDIR$/jmsadmin/javalibs.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/jmsadmin/jmsdb.properties

Import includes the entire configuration present in the export configuration file. jmx_host is defaulted to 127.0.0.1.

$SWDIR$/jmslib/mnemonic.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/iapjms_classpath.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/iapjms.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/etc/iapjms_log4j.properties

Import includes the entire configuration present in the export configuration file.

$SWDIR$/sdks/deploysdk/deploytst.cfg

Import includes the entire configuration present in the export configuration file.

mscluster.cfg

import includes the entire configuration present in the export configuration file. odbc_dsn_name, odbc_ipe_db_name, odbc_sqlsvr_name, and machine name are evaluated at runtime during the import.

Ipac.bat

import includes the entire configuration present in the export configuration file. Service Name is evaluated at runtime during the import.
Note: iProcess Engine supports export or import of the configuration file when there are different databases and ODBC names present in Windows and MSSQL, using the $DBNAME$ macro.

What is not Included in IMPORT_IPE_CONFIG?

The following are not included in the import configuration file:

  • Importing Users - the target system is potentially for a different purpose and the users are not configuration

  • No users implies no CDQP definitions

  • Procedures - these are users or application but not configuration

  • IAPJMS MED configuration - this is dependent on procedures and therefore, application

  • UVAPI setup (the binary file)

  • Filter settings that are set for the user (Graph filtering, EAIDB procedure level filtering)

Updating during an Import

When importing the configuration file, you can modify the following details:

  • Node name of iProcess Engine

    After you start importing, you are prompted with a question if you are interested in modifying the node name. If you choose to modify the node name, the import utility updates the files such as swdefs, the NODES table, registry entries and so on. See the macros that you can use.

  • Foreground and background users

    You can modify the foreground and background users in the export file which are tagged as follows:

    ::BGUSERNAME=<swprouser>

    ::FGUSERNAME=<swuser>

    Note: The assumption is that the Database Administrator (DBA) has already created these users and are existing in the database with prior permissions before the import activity.

  • Passwords of both foreground and background users

    Using the options under IMPORT_IPE_CONFIG, you can update the schema user passwords. If you want to modify the password, DBA has to update the password in the database first and then, attempt in the iProcess Engine using this import utility. Passwords are prompted to you during the import configuration activity.

Switching Database during an Import

You can switch from iProcess engine and configure to connect to a different database during an import.

-d is the option to switch to a different database.

For more information on options, see the IMPORT_IPE_CONFIG options.

Post Import Recommendations

• Restart the iProcess Engine installed machine after the import is completed.
• If UVAPI is disabled in the machine where export is run; the exported configuration file does not have UVAPI details given in the staffpms file.
• Enter the client ports such as iProcess Workspace Windows RPC number, JMX port, and so on manually after the import.
• LDAP configuration if present is also imported to the machine from the export file used. You must handle the rest of LDAP synchornization with iProcess Engine, if needed.
• As part of import, you cannot import the watcher or worker ports present in /etc/services. You must perform this as a post import activity after the configuration is imported.

If you do not perform this activity, iProcess Engine picks the default ports.

ORACLE

The database alias must exist in the client $ORACLE_HOME/network/admin/tnsnames.ora, for the iProcess Engine to connect for import.

DB2

The database alias must exist with all the catalogs set for the database connectivity.

MSSQL

ODBC (64-bit) entry must exist ensuring proper connectivity to the database.

Note:
  • You can replace values in the configuration file.
  • It is not recommended to add or delete any entry from the configuration file. You can add an extra entry such as adding a process attribute for the import. (This is completely your risk and any change to the import configuration is not recommended.)

Node Cluster (Linux/Windows) Import

The Machine ID and master flag options present in the import file support import of configuration on a node-node cluster environment. You are not prompted to enter a Machine ID and node name.

Windows Cluster Import

The export file generated must be imported on the primary node. You must not import the configuration file in the secondary node. In the secondary node, run $SWDIR\mscluster\WCSecNodeImport.bat to delete and import the new registry entries and services.

To import Windows Cluster on both the machines, perform the following steps:

1. Import the file by using the swadm IMPORT_IPE_CONFIG command on the primary cluster machine.
2. Verify the post-installation steps mentioned for the Windows Cluster setup in the Admin guide.
3. Set the server name in the nodes entry by using the swadm MOVESERVER utility.
4. Run the WCSecNodeImport.bat file on the secondary node. Running this file takes care of the corrections in the registry, ODBC entries ipac.bat, and other configurations.

Backing Up the Configuration File

iProcess Engine supports configuration backup so that you can export the entire configuration of a system and then import it later date after making some changes to restore it to its original settings.

To take a backup of the configuration file during the import, rename the backup file as - iPEConfig_<yyyymmdd>_<hhmmss>_<MachineID>_bkp.dat and manifest_<yyyymmdd>_<hhmmss>_<MachineID>_bkp.html (where bkp represents that the file is a backup file).

Note:
• The backup file is created without any macros from the import file and has all absolute paths in it.
• When you import a backup file, you can directly upload the backup file without using any options such as -r, -p, or -u.
• During the import of backup file, the node name is fetched directly from the import file but, you must enter the password manually.
• Backup would fail without a proper database connection prior to the import.