Oracle Workflow Loaders

Using the Workflow XML Loader

The Workflow XML Loader is a command line utility that lets you upload and download XML definitions for Business Event System objects between a database and a flat file. When you download Business Event System object definitions from a database, Oracle Workflow saves the definitions as an XML file. When you upload object definitions to a database, Oracle Workflow loads the definitions from the source XML file into the Business Event System tables in the database, creating new definitions or updating existing definitions as necessary.

The XML definitions for Business Event System objects are structured according to the following document type definitions (DTDs):

Events - WF_EVENTS DTD
Event group members - WF_EVENT_GROUPS DTD
Event subscriptions - WF_EVENT_SUBSCRIPTIONS DTD
Systems - WF_SYSTEMS DTD
Agents - WF_AGENTS DTD
Agent group members - WF_AGENT_GROUPS DTD

XML files uploaded or downloaded by the Workflow XML Loader should have the extension .wfx to identify them as Workflow object XML definitions.

You can download Business Event System object definitions in either normal download mode or exact download mode.

Normal download mode lets you save a generic copy of object definitions from one system that you can use to create similar definitions in other systems. In this mode, the Workflow XML Loader replaces certain system-specific data within the object definitions with tokens. Choose normal download mode, for example, when you want to save Business Event System object definitions from a development system as seed data that can be uploaded to a production system.
Exact download mode lets you save object definitions as they are specified in the database. In this mode, the Workflow XML Loader does not convert most system-specific data to tokens; instead, all values are copied to the XML file. Choose exact download mode, for example, when you want to save Business Event System object definitions from one production system so that you can replicate them to another production system that communicates with the first.

In normal download mode, the Workflow XML Loader uses the following tokens to replace system-specific data within Business Event System object definitions. The tokens are prefixed by #.

#NEW - Replaces the global unique identifier for an agent within an agent definition, or for an event subscription within a subscription definition.
#LOCAL - Replaces the global unique identifier for the local system wherever it appears within an agent or subscription definition.
#OWNER - Replaces the name of the schema that owns a queue when the schema appears as part of the queue name and agent address within an agent definition.
#SID - Replaces the database system identifier (SID) when it appears as part of the agent address within an agent definition.
#WF_IN - Replaces the global unique identifier for the WF_IN agent on the local system when it appears as the Source Agent, Out Agent, or To Agent within an event subscription definition.
#WF_OUT - Replaces the global unique identifier for the WF_OUT agent on the local system when it appears as the Source Agent, Out Agent, or To Agent within an event subscription definition.
#WF_ERROR - Replaces the global unique identifier for the WF_ERROR agent on the local system when it appears as the Source Agent, Out Agent, or To Agent within an event subscription definition.

By converting these system-specific values to tokens, the loader produces template definitions that you can use to create similar objects in other systems. When you upload object definitions that contain tokens to a database, Oracle Workflow replaces the tokens with the appropriate values for that system.

Note: Because the Workflow XML Loader replaces the global unique identifier for a subscription with a token in normal download mode, each subscription must be identified instead by a unique combination of subscribing system, source type, triggering event, source agent, owner name, and owner tag.

However, to ensure the portability of the downloaded Business Event System object definitions, the Workflow XML Loader always identifies events by their event names, regardless of the download mode. It never copies the global unique identifier for an event. Instead, the Workflow XML Loader uses the token #NEW to replace the global unique identifier for an event within an event definition. Additionally, the Workflow XML Loader uses event names to represent event groups and event group members within event group member definitions, and to represent triggering events within event subscription definitions. When an event is uploaded to another database, a new global unique ID is generated for the event in that database, while the event name within the event definition is used to match the event with any related objects.

You can upload Business Event System object definitions in either normal upload mode or force upload mode.

In normal upload mode, the Workflow XML Loader loads the object definitions from the source XML file into the Business Event System tables in the database, but does not update any event or subscription definition with a customization level of User. Oracle Workflow uses this mode to preserve your customizations during upgrades.
In force upload mode, the Workflow XML Loader loads the object definitions from the source XML file into the Business Event System tables in the database and overwrites any existing definitions, even for events or subscriptions with a customization level of User. Use this mode when you want to update the definitions for your own custom events and subscriptions.

See: Access Protection for Business Event System Data and Managing Business Events.

To Download Business Event System XML Definitions from a Database:

To download Business Event System object definitions from a database to a flat XML file, run the Workflow XML Loader by running Java against oracle.apps.fnd.wf.WFXLoad. You must specify your CLASSPATH pointing to the Java Runtime Environment, the directory containing the Workflow JAR files, the Oracle JDBC implementation, and the following Workflow JAR files:

wfjava.jar - Workflow Java utilities
wfapi.jar - Workflow Java APIs
fndctx.jar - Application Object Library services

Note: The Workflow JAR files are normally located in the $JAVA_TOP/oracle/apps/fnd/jar directory.

For example, on UNIX, use the following command to run the Workflow XML Loader:

java -classpath "$<JREPATH>/rt.jar:$<Workflow_JAR_file_directory>:
$<Workflow_JAR_file_directory>/wfjava.jar:
$<Workflow_JAR_file_directory>/wfapi.jar:
$<Workflow_JAR_file_directory>/fndctx.jar:
$<ORACLE_HOME>/jdbc/lib/classes111.zip:" 
oracle.apps.fnd.wf.WFXLoad -d[e] <user> <password> 
<connect_string> <protocol> <lang> <output_file> <object> <key> 
OWNER_TAG <owner_tag>

On Windows, use the following command:

java -classpath ";<JREPATH>\rt.jar;<Workflow_JAR_file_directory>;
<Workflow_JAR_file_directory>\wfjava.jar;
<Workflow_JAR_file_directory>\wfapi.jar;
<Workflow_JAR_file_directory>\fndctx.jar;
<ORACLE_HOME>\jdbc\lib\classes111.zip;" 
oracle.apps.fnd.wf.WFXLoad -d[e] <user> <password> 
<connect_string> <protocol> <lang> <output_file> <object> <key> 
OWNER_TAG <owner_tag>

When running the Workflow XML Loader, use either the -d option or the -de option to specify the download mode that you want.

-d - Normal download mode. The loader converts system-specific data within the object definitions to tokens prefixed with #, where appropriate.
-de - Exact download mode. The loader copies the object definitions as they are specified in the database and does not convert the system-specific data to tokens.

Additionally, replace the variables in the download command with your parameters as follows:

<user> - The user name of your database account.
<password> - The password for your database account.
<connect_string> - The connect string for the database. The format of the connect string depends on the JDBC driver type.
- For a JDBC OCI8 driver, the connect string should be the database name as specified in its TNSNAMES entry, in the following format:
```
<database_name>
```
- For a JDBC THIN driver, you can use two different types of connect string. For the first type, the connect string should include the host name, port number, and database system identifier (SID) in the following format:
```
<host_name>:<port_number>:<database_SID>
```
  For the second type, the connect string should include an Oracle Net name-value pair with the host name, protocol, port number, and SID in the following format:
```
(description=(address=(host=<host_name>)(protocol= <protocol>)
(port=<port_number>))(connect_data=(sid=<database_SID>)))
```
<protocol> - The JDBC driver type you want to use to connect to the database. The JDBC driver type can be either oci8 or thin.
<lang> - The abbreviation for the language of the XML file. This parameter is case insensitive. Use the standard language abbreviations for the Oracle Database, such as US for American or JA for Japanese. For a list of the standard language abbreviations, see: Locale Data, Oracle National Language Support Guide.
<output_file> - The name and full path of the output file to which you want to save the definitions. The output file should have the extension .wfx.
<object> - The type of object definitions you want to download.
- EVENT_GROUPS - Event group definitions
  
  Note: This object type includes only the definitions of the event groups themselves, without any information about their member events.
- EVENTS - Event definitions for individual events and definitions for those events' memberships in any event groups
- SUBSCRIPTIONS - Event subscription definitions
- AGENTS - Agent, agent group member, and system definitions
Note: The Workflow XML Loader only downloads event subscription, agent, agent group member, and system definitions that belong to the local system.
<key> - An optional key to restrict the definitions that are downloaded. If you specify a key, the loader retrieves definitions only for those objects whose internal names include that key. The key value is case sensitive and cannot contain any spaces. To retrieve all object definitions of the specified type, you can omit this parameter.
OWNER_TAG <owner_tag> - An optional application short name or program ID code for the application or program that owns the object definitions you want to download. This value is case sensitive and cannot contain any spaces. If you pass this parameter, you must include the OWNER_TAG marker before the owner tag value to identify the parameter.

Note: To report more extensive debugging information in the program output, you can run the Workflow XML Loader in debug mode by including the DebugMode argument just before the -d or -de option. For example, use the following command:

java -classpath <classpath> oracle.apps.fnd.wf.WFXLoad 
DebugMode -d[e] <user> <password> <connect_string> 
<protocol> <lang> <output_file> <object> <key> 
OWNER_TAG <owner_tag>

To Upload Business Event System XML Definitions to a Database:

To upload Business Event System object definitions from an XML file to a database, run the Workflow XML Loader by running Java against oracle.apps.fnd.wf.WFXLoad. You must specify your CLASSPATH pointing to the Java Runtime Environment, the directory containing the Workflow JAR files, the Oracle JDBC implementation, and the following Workflow JAR files:

wfjava.jar - Workflow Java utilities
wfapi.jar - Workflow Java APIs
fndctx.jar - Application Object Library services

Note: The Workflow JAR files are normally located in the $JAVA_TOP/oracle/apps/fnd/jar directory.

For example, on UNIX, use the following command to run the Workflow XML Loader:

java -classpath "$<JREPATH>/rt.jar:$<Workflow_JAR_file_directory>:
$<Workflow_JAR_file_directory>/wfjava.jar:
$<Workflow_JAR_file_directory>/wfapi.jar:
$<Workflow_JAR_file_directory>/fndctx.jar:
$<ORACLE_HOME>/jdbc/lib/classes111.zip:" 
oracle.apps.fnd.wf.WFXLoad -u[f] <user> <password> 
<connect_string> <protocol> <lang> <source_file>

On Windows, use the following command:

java -classpath ";<JREPATH>\rt.jar;<Workflow_JAR_file_directory>;
<Workflow_JAR_file_directory>\wfjava.jar;
<Workflow_JAR_file_directory>\wfapi.jar;
<Workflow_JAR_file_directory>\fndctx.jar;
<ORACLE_HOME>\jdbc\lib\classes111.zip;" 
oracle.apps.fnd.wf.WFXLoad -u[f] <user> <password> 
<connect_string> <protocol> <lang> <source_file>

When running the Workflow XML Loader, use either the -u option or the -uf option to specify the upload mode that you want.

-u - Normal upload mode. The Workflow XML Loader loads the object definitions from the source XML file into the Business Event System tables in the database, but does not make any updates to events or subscriptions with a customization level of User.
-uf - Force upload mode. The Workflow XML Loader loads the object definitions from the source XML file into the Business Event System tables in the database and overwrites any existing definitions, even for events or subscriptions with a customization level of User.

Additionally, replace the variables with your parameters as follows:

<user> - The user name of your database account.
<password> - The password for your database account.
<connect_string> - The connect string for the database. The format of the connect string depends on the JDBC driver type.
- For a JDBC OCI8 driver, the connect string should be the database name as specified in its TNSNAMES entry, in the following format:
```
<database_name>
```
- For a JDBC THIN driver, the connect string should include the host name, port number, and database system identifier (SID) in the following format:
```
<host_name>:<port_number>:<database_SID>
```
<protocol> - The JDBC driver type you want to use to connect to the database. The JDBC driver type can be either oci8 or thin.
<lang> - The abbreviation for the language of the XML file. This parameter is case insensitive. Use the standard language abbreviations for the Oracle Database, such as US for American or JA for Japanese. For a list of the standard language abbreviations, see: Locale Data, Oracle National Language Support Guide.
<source_file> - The name and full path of the source file from which you want to upload definitions. The source file should have the extension .wfx.

Each subscription definition that you want to upload must include a phase number, owner name, and owner tag. The Workflow XML Loader cannot upload a source file containing subscription definitions that are missing this information.

If the source file contains subscription definitions downloaded in exact mode, the subscriptions are loaded into the Business Event System tables according to their global unique identifiers. However, if the subscription definitions were downloaded in normal mode, using tokens, each subscription is identified instead by a unique combination of subscribing system, source type, triggering event, source agent, owner name, and owner tag.

java -classpath <classpath> oracle.apps.fnd.wf.WFXLoad 
DebugMode -u[f] <user> <password> <connect_string> 
<protocol> <lang> <source_file>