Customizing Configuration Data Transfer

Configuration Data Transfer > Customizing Configuration Data Transfer

Customizing Configuration Data Transfer

If you want to transfer some of the configuration data rather than all or you want to define system behavior in certain situations, define the action descriptor XML file before transferring. The descriptor XML file specifies which configuration components to export or import and the system response on the existing and non-existing data items. You can either create a descriptor file for exporting or importing data or generate one and edit it to define the rules.

Creating a Descriptor File

Ensure that you create the descriptor file in the required structure as the following examples. For more examples, see Defining Configuration Component Attributes.

• For QXI export

<?xml version="1.0" ?>

<qxiCfgBundleActionDescriptor xmlns="urn:schemas-qad-com:qxtend-configuration">

<action name="export" onNotExist="stop" />

<module name="module_name">

<apiSchemaCfg qdocName="qdoc_name" version="version" type="type"/>

<apiSchemaCfg qdocName="qdoc_name" version="version" type="type"/>

<receiver name="receiver_name">

<receiverApiCfg qdocName="qdoc_name" version="version" type="type"/>

<receiverApiCfg qdocName="qdoc_name" version="version" type="type"/>

</receiver>

</module>

<module name="module_name">

<receiver name="receiver_name">

<receiverApiCfg qdocName="qdoc_name" version="version" type="type"/>

<receiverApiCfg qdocName="qdoc_name" version="version" type="type"/>

</receiver>

</module>

</qxiCfgBundleActionDescriptor>

• For QXO export

<?xml version="1.0" encoding="UTF-8"?>

<?xml version="1.0" ?>

<qxoCfgBundleActionDescriptor xmlns="urn:schemas-qad-com:qxtend-configuration">

<action name="export" onNotExist="stop" />

<sourceApplicationType name="srcApp_name">

<businessObjectCfg name="BO_name">

<profileCfg name="BO_profile_name" />

<profileCfg name="BO_profile_name" />

</businessObjectCfg>

</sourceApplicationType>

<subscriber code="subscriber_code">

<subscriberProfileCfg sourceApplicationType="*" businessObject="*" profile="*" />

<subscriberProfileCfg sourceApplicationType="*" businessObject="*" profile="*" />

<messagePublisher sessionCode="session_code">

<businessObjectRegistrationCfg sourceApplicationType="*" businessObject="*" />

<businessObjectRegistrationCfg sourceApplicationType="*" businessObject="*" />

</messagePublisher>

The descriptor XML files for import and export have similar structure but with different values in the action node. For import, there is an onExist attribute defining the system response on the existing entities in the target system. For more information about system response, see Defining System Response.

• For export

<action name="export" onNotExist="stop" />

• For import

<action name="import" onNotExist="stop" onExist=”stop”/>

Generating a Descriptor File

To generate a descriptor file for exporting data:

1 Locate the qxocfgbundle.sh file at

• <TOMCAT_HOME>/webapps/<QXI webapp>/WEB-INF/scripts for QXI.

• <QXOServer_install_dir>/scripts for QXO.

2 Run the following command.

• For QXI, run

./qxicfgbundle.sh -gd -d [action_descriptor_file]

• For QXO, run

./qxocfgbundle.sh -gd -d [action_descriptor_file]

The descriptor file with the specified name is generated in the export folder. If you do not specify the descriptor file name, the descriptor file is named as qxiCfgBundle.export.xml (for QXI) or qxoCfgBundle.export.xml(for QXO).

Example: If you want to generate a descriptor file named qxo_export.xml, use the command:

./qxocfgbundle.sh -gd -d qxo_export.xml

3 Edit the generated file to scope the configuration components to export. For information on how to edit the descriptor file, see Defining System Response and Defining Configuration Component Attributes.

To generate a descriptor file from a bundle file for importing data:

1 Put the bundle file that you want to generate a descriptor file from in

• <TOMCAT_HOME>/webapps/<QXI webapp>/WEB-INF/import for QXI

• <QXOServer_install_dir>/import for QXO

2 Locate the qxocfgbundle.sh file at

• <TOMCAT_HOME>/webapps/<QXI webapp>/WEB-INF/scripts for QXI

• <QXOServer_install_dir>/scripts for QXO

3 Run the following command.

• For QXI, run

./qxicfgbundle.sh -gd [bundle_file] -d [action_descriptor_file]

• For QXO, run

./qxocfgbundle.sh -gd [bundle_file] -d [action_descriptor_file]

The descriptor file with the specified name is generated in the import folder. If you do not specify the descriptor file name, the descriptor file uses the bundle file name but with .xml as the extension.

Example: If you want to generate a descriptor file named qxo_import.xml from the bundle file qxo_bundle.zip, use the command:

./qxocfgbundle.sh -gd qxo_bundle.zip -d qxo_import.xml

If you do not specify a name for the descriptor file in the command, it is named as qxo_bundle.xml.

4 Edit the generated file to scope the configuration components to import. For information on how to edit the descriptor file, see Defining System Response and Defining Configuration Component Attributes.

Defining System Response

In the descriptor XML file, onNotExist attribute controls the import and export process and onExist attribute controls the import process only. If you define these attributes in the action node, they work on all items that are specified in the descriptor file. However, they can be overridden by values defined at lower levels.

Example: The attributes in the action node:

<action name="import" onNotExist="skip" onExist="skip" />

You can also use these attributes in the configuration item elements to define specific items. If you do not define the attributes on item level, the system follows the rules defined in the action node.

Example: The attributes on item level:

<module name="QADEE">

<apiSchemaCfg qdocName="bdomain" version="ERP3_1" type="standard" />

<apiSchemaCfg qdocName="bvat" version="*" type="*" onExist="overwrite" />

<apiSchemaCfg qdocName="maintainItemMaster" version="*" type="custom" />

<apiSchemaCfg qdocName="bgl" version="*" type="*" onExist="overwrite" />

</module>

If you do not define the values either in the action node or in the configuration items lines, the system defaults the value for them as stop. For details on the attributes, see onNotExist and onExists Attributes.

onNotExist and onExists Attributes


Attribute	Value	Description
onNotExist	stop	• For export process: If the specified item in the descriptor XML file does not exist in the source QXtend, the system stops the export process and records an error in the .report.txt file. It is the default option. • For import process: If the specified item in the descriptor XML file does not exist in the bundled zip file, the system stops and rolls back the import process. An error is recorded in the .report.txt file. It is the default option.
onNotExist	skip	• For export process: If the specified item in the descriptor XML file does not exist in the source QXtend, the system skips this item and continues with the remaining items. A warning is recorded in the .report.txt file. • For import process: If the specified item in the descriptor xml file does not exist in the bundled zip file, the system skips this item and continues with the remaining items. A warning is recorded in the .report.txt file.
onExist	stop	If the specified item exists in the target QXtend, the system stops and rolls back the import process and records an error in the .report.txt file. It is the default option.
	skip	If the specified item exists in the target QXtend, the system skips this item and continues with the remaining items. A warning is recorded in the .report.txt file.
	overwrite	If the specified item exists in the target QXtend, the system overwrites the item in the target with the item in the bundle file. A warning is recorded in the .report.txt file.
	merge	If the specified item exists in the target QXO, the system merges the item in the target and the item in the bundle file. A warning is recorded in the .report.txt file.

Defining Configuration Component Attributes

In the descriptor XML file, you can specify which configuration components to export or import by defining the attributes. For example, you can define the attributes of API name, version, and type for API schemas to filter out the components that you need. For BOs, you can also define whether to export or import their profiles.

Example:

• Descriptor File for QXI Import:

<?xml version="1.0" ?>

<qxiCfgBundleActionDescriptor xmlns="urn:schemas-qad-com:qxtend-configuration">

<action name="import" onNotExist="stop" onExist="stop">

<bundleRestriction bundleId="3c98e02e-3bd6-423a-a2fb-12a29fb8b1d3"/>

</action>

<module name="QADEE">

<apiSchemaCfg qdocName="allocateSalesOrder" version="eB_1" type="standard"/>

<apiSchemaCfg qdocName="allocateSalesOrder" version="eB_2" type="standard"/>

<apiSchemaCfg qdocName="authorizeKanban" version="ERP3_1" type="standard"/>

<apiSchemaCfg qdocName="bbudgetgroup" version="ERP3_1" type="standard"/>

<apiSchemaCfg qdocName="bbusinessrelation" version="ERP3_1" type="standard"/>

<receiver name="QADERP">

<receiverApiCfg qdocName="allocateSalesOrder" version="eB_2" type="standard"/>

<receiverApiCfg qdocName="authorizeKanban" version="ERP3_1" type="standard"/>

<receiverApiCfg qdocName="bbudgetgroup" version="ERP3_1" type="standard"/>

<receiverApiCfg qdocName="bbusinessrelation" version="ERP3_1" type="standard"/>

</receiver>

</module>

</qxiCfgBundleActionDescriptor>

• Descriptor File for QXO Export:

<?xml version="1.0" ?>

<qxoCfgBundleActionDescriptor xmlns="urn:schemas-qad-com:qxtend-configuration">

<action name="export" onNotExist="stop">

<bundleRestriction bundleId="d14d4b2d-32d8-2082-e311-2902cc84bccd"/>

</action>

<sourceApplicationType name="QADEE">

<businessObjectCfg name="AlternateUM">

<profileCfg name="AlternateUM"/>

<profileCfg name="MaintainAlternateUM"/>

</businessObjectCfg>

<businessObjectCfg name="AnalysisCode">

<profileCfg name="AnalysisCode"/>

<profileCfg name="MaintainAnalysisCode"/>

</businessObjectCfg>

<sourceApplication code="QADERP">

<databaseEventCfg tableName="abs_mstr"/>

<databaseEventCfg tableName="absc_det"/>

<databaseEventCfg tableName="absd_det"/>

</sourceApplication>

</sourceApplicationType>

<subscriber code="FileDrop">

<subscriberProfileCfg sourceApplicationType="QADEE" businessObject="AnalysisCode" profile="MaintainAnalysisCode"/>

<subscriberProfileCfg sourceApplicationType="QADEE" businessObject="SalesOrder" profile="SalesOrder1"/>

</subscriber>

<messagePublisher sessionCode="MP1">

<businessObjectRegistrationCfg sourceApplicationType="QADEE" businessObject="AnalysisCode"/>

<businessObjectRegistrationCfg sourceApplicationType="QADEE" businessObject="SalesOrder"/>

</messagePublisher>

</qxoCfgBundleActionDescriptor>

You can use wildcards (*) to define the attributes in the descriptor file. Any of the following syntax is valid for defining attribute values of configuration components:

• name="*"

• qdocName="*SalesOrder*"

• profile="Maintain*Code"

• tableName="*det"

• profile="*Code*Detail"

The following rules are used to determine the most specific match pattern:

• The concrete values without any wildcard characters are the most specific. For example, maintainCall is a more specific than any values with wildcard characters, such as maintain*.

• The later the wildcard character appears, the more specific the value is. For example, shipperDelete* is more specific than shipper*.

• The values that have wildcard characters appended with additional characters are more specific than the same values without additional characters. For example, QADERPSales*Line is more specific than QADERPSales*.

• If there are multiple key fields in a configuration entity, the entity that has the more specific key field appearing earlier is more specific. For example, ReceiverApiCfg (QADEE, QADERP, queryItem, *, *) is more specific than ReceiverApiCfg (QADEE, QADERP, query*, ERP3_1, custom).

• If the configuration entities have parent entities, the system compares the values in order from the top parent entities to the child entities. For example, ReceiverApiCfg (QADEE, *, *, *, *) is more specific than ReceiverApiCfg (QAD*, QADERP, queryItem, ERP3_1, custom).

Example: The user wants to add or replace the business objects starting with Sales and add any other new business objects. The following descriptor meets the requirements. Since “Sales*” is more specific than “*”, when a BO starting with Sales exists in the target system, it will be replaced with the one in the bundle.

......

<qxc:sourceApplicationType name="QADEE">

<qxc:businessObjectCfg name="*" onExist="skip"/>

<qxc:profileCfg name="*"/>

<qxc:businessObjectCfg name="Sales*" onExist="overwrite">

<qxc:profileCfg name="Custom*"/>

</qxc:businessObjectCfg>

</qxc:sourceApplicationType>

......

If an asterisk is part of the name of a configuration entity, you can use a tilde (~) to escape the asterisk. For example, if a subscriber is named FileDrop* in your system, specify in the descriptor file as shown in the following example. It defines that the subscribers named FileDrop* will be exported or imported.

Example:

......

<sourceApplicationType name="QADEE">

<sourceApplication code="QADERP1">

<databaseEventCfg tableName="so_mstr" onExist="merge"/>

<businessEventCfg name="*" object="so_mstr" onExist="merge"/>

</sourceApplication>

<subscriber code="FileDrop~*">

<subscriberProfileCfg sourceApplicationType="*" businessObject="*" profile="*" />

</subscriber>

<messagePublisher sessionCode="MP*">

<businessObjectRegistrationCfg sourceApplicationType="*" businessObject="BD*" />

</messagePublisher>

......