B Federation Protocol Cartridges

This appendix provides information about using the Oracle Communications Unified Inventory Management (UIM) federation protocol cartridges, which enable UIM to interface with other external systems via different communication protocols, such as a database connection, JMS, and SOAP.

Note:

This appendix builds upon the information presented in "Using the Federation Framework".

About the Federation Protocol Cartridges

The federation protocol cartridges enable communication with external systems using various protocols. They provide functionality for a database connection as well as JMS and SOAP communication. You use these cartridges when you design a federation solution utilizing a specific type of communication protocol optionally using externally enabled entities.

Understanding the federation protocol cartridges is necessary when extending UIM to communicate with external systems. You can utilize these cartridges for the following communication protocol options:

JMS
SOAP
Database connection

The JMS protocol is asynchronous, and the SOAP and database connection protocols are synchronous. The federation protocol cartridges include:

A set of infrastructure artifacts to use communicating with the external system.
A set of artifacts providing an example implementation illustrating the usage of the infrastructure artifacts.

About the Federation Protocol Infrastructure Artifacts

You can use the federation protocol infrastructure artifacts to enable JMS, SOAP and database connection communication with external systems. The federation protocol infrastructure artifacts include the following:

Protocol Cartridge

The protocol cartridge provides abstract adapter classes for leveraging a variety of protocols in federation integrations. You can extend these adapters to provide your tailored and specific implementation. The cartridge name is OracleComms_UIM_FederationProtocols.
Properties Cartridge

The properties cartridge provides files for managing property settings. For instance, you can configure the following types of information:
- The JMS request queue
- The class name that provides the implementation
The cartridge name is OracleComms_UIM_FederationProperties.
Message Driven Bean

The message driven bean listens for messages on the response queue for the JMS protocol. You must package this MDB file in the custom.ear file. The filename is UIMFederationResponseListenerMBD.jar.
Response Queue Script

The response queue Python script creates the response queue for the JMS bridge. You must update this file to reflect the appropriate host name, port, user name, and password before running the script. The Python script file name is UIMFederationResponseQueue.py.

About the Federation Protocol Implementation Sample

The implementation example provides sample code utilizing the federation protocol infrastructure. This example interfaces with an additional UIM system as the external system.

Note:

This implementation uses UIM as the external system, however using UIM as an external system is not a typical business scenario. UIM is used as the example so you can successfully test the implementation and compare it to your external system selection.

The following set of artifacts provide the implementation example.

The OracleComms_UIM_FederationProtocolsImpl cartridge is an example of using and implementing the OracleComms_UIM_FederationProtocols cartridge and its adapter classes.
The ExternalSystem cartridge is used for the SOAP and JMS testing setup on the external system. This cartridge contains the following:
- Various UIM specifications that the code references
- A ruleset extension point
- Ruleset code to complete a business interaction
- A BIHelper class which has a completeBI() method to look up the response queue and post a reply
ExternalSystemsMDB is the message driven bean that listens for JMS messages on the request queue of the external system.
ExternalSystemQueues.py is the Python script that creates the request and response queues for the JMS protocol on the external system. You must update this file to reflect the appropriate host name, port, user name, and password values.
UIMFederationRequestQueue.py is the Python script that creates the request on queue for the JMS protocol in UIM.
The externalsystem_webservice cartridge is a web service that can be invoked on the external system. The WSDL file is located within the cartridge with the filename ExternalSystemWS.wsdl in the wsdl directory.

The following set of technical documents provide setup instructions and an overview of the implementation:

UIM Reference Implementation JMS Federation_Setup_Guide.docx details the required steps for the JMS protocol setup.
UIM Reference Implementation SOAP Federation_Setup_Guide.docx details the required steps for the SOAP protocol setup.
UIM Reference Implementation Federation_Dev_Guide.docx contains implementation details, such as class level information.

Accessing the Federation Protocol Cartridges

You can access the federation protocol infrastructure artifacts from the UIM Software Development Kit (SDK). Within the UIM SDK, you find these cartridges in the federation_sdk.zip file which is located in the cartridges/sample directory.

See "About the UIM SDK" for more information on the UIM SDK.

You can download the federation protocol implementation sample from the Oracle Software Delivery Cloud. Within the cartridge pack ZIP file, these artifacts will be located in the Federation/Communication Protocols directory.

See UIM Cartridge Guide for instructions on how to download the cartridge pack ZIP file.

Using the Federation Protocol Cartridges

After importing the federation protocol cartridge into Design Studio, you use the technical documents provided in the Federation/Communication Protocols/doc directory of the cartridge pack ZIP file. Refer to the UIM Cartridge Guide for instructions on how to download the cartridge pack ZIP file

These technical documents aid in understanding how to extend, configure and test these cartridges.

Extending the Federation Protocols Cartridge Functionality

You extend the OracleComms_UIM_FederationProtocols cartridge to build your own tailored implementation to federate data in an external system. This cartridge contains the following adapter classes for supporting communication via JMS, SOAP or a database connection. The adapter classes are:

InventoryFederationJMSAdapter
InventoryFederationSOAPWSAdapter
InventoryFederationDBAdapter

These classes all extend from the base class InventoryFederationBaseAdapter.

Configuring the Federation Properties Cartridge

You use the OracleComms_UIM_FederationProperties cartridge to configure property file settings for the external system communication. This cartridge contains the following files that can be configured:

The federation-config.xml file contains information about the external system, such as the connection type the supported entities and the external system access information.
The federation-config-schema.xsd contains the XML schema definition for the federation-config.xml file. Oracle does not recommend altering this file, unless you “clone and own" the cartridges. If you alter this file, you must change the supporting classes to support the changes.

See UIM Cartridge Guide for more information on the “clone and own" topic for cartridges.

In addition to the properties files in this cartridge, you change the UIM system-config.properties file to specify if the configuration file reloads. You must add this property and its setting to the system-config.properties file.

uim.federationProtocols.federationConfigReload=true

By default, this setting is not in the system configuration file and must be added. You use the true setting to reload the values in the federation-config.xml file. This setting is recommended for development when values are changing.

Changing the Entity Type

You can set the entity type within the SupportedEntities section of the federation-config.xml file. This portion of the file shows UIMEntityType field:

<SupportedEntities>
  <EntityInfo>
    <UIMEntityType>Pipe</UIMEntityType>
    <ExternalSystemEntityType>Pipe</ExternalSystemEntityType>
    <UIMEntitySpecification>IH_Local_Loop</UIMEntitySpecification>
    <ExternalSystemSupportedOperationList>Create,Retrieve,Update,Delete
    </ExternalSystemSupportedOperationList>
  </EntityInfo>
</SupportedEntities>

You find the valid values for this setting in the OracleComms_UIM_FederationProtocols cartridge. The Java enum InventoryFederationSupportedEntityTypes in the package:

oracle.com.inventory.federationFramework

defines the valid entities for the UIMEntityType field.

Changing Operations List

You can set the operations list, such as create, retrieve, update, and delete within the SupportedEntities section of the federation-config.xml file. This portion of the file shows the ExternalSystemSupportedOperationList field:

<SupportedEntities>
  <EntityInfo>
    <UIMEntityType>Pipe</UIMEntityType>
    <ExternalSystemEntityType>Pipe</ExternalSystemEntityType>
    <UIMEntitySpecification>IH_Local_Loop</UIMEntitySpecification>
    <ExternalSystemSupportedOperationList>Create,Retrieve,Update,Delete
    </ExternalSystemSupportedOperationList>
  </EntityInfo>
</SupportedEntities>

You find the valid values for this setting in the OracleComms_UIM_FederationProtocols cartridge. The Java enum InventoryFederationSupportedOperations in the package:

oracle.com.inventory.federationFramework

defines the valid entities for the ExternalSystemSupportedOperationList field.

External System Settings

The federation-config.xml also contains the settings to login to the external system. This section provides sample XML file segments for the SOAP, JMS and database connection protocol settings.

SOAP Protocol Settings

Example B-1 shows a portion of the external system metadata information for the SOAP communication protocol:

Example B-1 SOAP Protocol External System Settings

<ExternalSystemMetadata>
  <Property>
    <Name>WS_URL</Name>
    <Value>http://localhost:9001/ExternalSystemWS/ExternalSystemWSHTTP</Value>
  </Property>                             
  <Property>
    <Name>WS_USERNAME</Name>
    <Value>8A2F9B36DE151F1A12C878EE41681F54</Value>
  </Property>
  <Property>
    <Name>WS_PASSWORD</Name>
    <Value>DE59BC74FC2B56C0FF19E0D7BCA8C016</Value>
  </Property>
</ExternalSystemMetadata>

You must update these values in the XML file with the correct values to connect to the external system. To set the user name and password values, you run the rule EncryptText under the Execute Rule option in UIM GUI. Figure B-1 shows the GUI to run a rule and encrypt these values.

Figure B-1 Execute EncryptText Rule UI in UIM

Description of "Figure B-1 Execute EncryptText Rule UI in UIM"

See Base Rulesets for examples of running base rulesets.

JMS Protocol Settings

Example B-2 shows a portion of the external system metadata information for the JMS protocol:

Example B-2 JMS Protocol External System Settings

<ExternalSystemMetadata>
  <Property>
    <Name>CONNECTION_FACTORY</Name>
    <Value>federationQueueCF</Value>
  </Property>
  <Property>
    <Name>REQUEST_QUEUE</Name>
    <Value>federationRequestQueue</Value>
  </Property>
</ExternalSystemMetadata>

You must update the connection factory and the request queue name values in the XML file with your values to connect to the external system.

Database Connection Protocol Settings

Example B-3 shows a portion of the external system metadata information for the database connection protocol:

Example B-3 Database Connection Protocol External System Settings

<ExternalSystemMetadata>
  <Property>
    <Name>JDBC_DATA_SOURCE</Name>
    <Value>jdbc/MssTxDataSource</Value>
  </Property>
</ExternalSystemMetadata>

You must update the JDBC data source value in the XML file with your value to connect to the external system.