This chapter provides information about the Oracle Communications Unified Inventory Management (UIM) federation framework. The federation framework enables UIM to work with other systems, such as Oracle Communications Internet Name and Address Management (INAM), and Oracle Communications MetaSolv Solution (MSS). The federation framework also enables communication with other external systems via different communication protocols.
Federation is ability of different software systems to communicate, cooperate, and exchange information. Federation can present a common user experience or simply convey information about a data object from an external system.
Each federation cartridge pack is a set of sample cartridges and artifacts that provides:
Extension functionality for data domains like IP Address and VLANs interfacing with external systems, such as INAM and MSS. See "About the Federation Data Domain Cartridges" for more information.
Extension functionality providing a database connection as well as JMS and SOAP communication. See "About the Federation Protocol Cartridges" for more information.
The federation data domain cartridges focus on the exchange of different types of data, such as IP Addresses and VLANs. You use these cartridges when you design a federation solution utilizing a specific type of data while leveraging externally enabled entities.
These are the federation data domain ZIP files that contain the cartridges:
IP Address Federation - OracleComms_UIM_IPAddress_Federation
VLAN ID Federation - OracleComms_UIM_VLAN_ID_Federation
Connectivity Federation - OracleComms_UIM_Connectivity_Federation
Objectel Federation - OracleComms_UIM_Objectel_Federation
Note:
The federation protocol cartridges are not utilized in these cartridges. The federation protocol cartridges use an alternative communication infrastructure to interface with the external systems.
See "Federation Data Domain Cartridges" for more information on these federation data domain cartridges.
The federation protocol cartridges focus on enabling communication protocols. They provide 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.
These are the federation protocol cartridges and artifacts:
Protocol Cartridge - OracleComms_UIM_FederationProtocols
Properties Cartridge - OracleComms_UIM_FederationProperties
Message Driven Bean - UIMFederationResponseListenerMBD
Response Queue Script - UIMFederationResponseQueue
See "Federation Protocol Cartridges" for more information on the federation protocol artifacts.
In a federation arrangement, specific data access, data management tasks, and processes are transparently delegated to other systems. For example, UIM manages services, and INAM manages IP addresses. The two systems federate through the use of the ora_uim_ipaddress_cooperation cartridge. When this federation is in place, it is transparent to you that UIM is communicating with INAM to supply the IP address.
The different ways in which systems federate are called external arrangements. The federation framework supports four types of external arrangements:
Federated
Leased In
Leased Out
Shared
Table 14-1 lists the external arrangements used by the IP address, VLAN ID, and connectivity cartridges, and also the federation protocol cartridges.
Table 14-1 External Arrangements and the Federation Cartridges
| External Arrangement Enum | External Arrangement Display in UI | IP Address Federation | VLAN ID Federation | Connectivity Federation | Federation Protocol |
|---|---|---|---|---|---|
|
FEDERATED |
Viewed From |
UIM views IP addresses from INAM. |
UIM views network system and product catalog from MSS. |
Not applicable. |
Not applicable. |
|
LEASED_IN |
Leased From |
UIM leases in IP address from INAM for service assignment. |
Not applicable. |
UIM leases in a connection from an external system for service trail enablement. |
UIM leases in a Local Loop (Pipe) entity reference from an external system. |
|
LEASED_OUT |
Leased To |
Not applicable. |
UIM leases out VLAN ID to MSS for service assignment. |
Not applicable. |
Not applicable. |
|
SHARED |
Shared With |
Not applicable. |
MSS shares service catalog and network system entities to relate to UIM VLAN domains. |
Not applicable. |
Not applicable. |
The federation cartridges fall into one of the following categories:
Transaction-based federation is a point-to-point integrations between UIM business logic and an external system. Transaction-based federation typically revolves around a simple resource, such as a telephone number or IP address.
For transaction-based federation to work, the external system must support a synchronous API that UIM can call. The synchronous transaction has a beginning and an end through the use of the startTransaction method and the endTransaction method.
The IP address federation cartridge and the VLAN ID federation cartridge are examples of transaction-based federation. These solutions use the Custom Object and Custom Network Address entities, which have a generic nature that can model virtually any resource from a foreign system. They are simple and avoid complex requests in UIM.
Order-based federation is a schema-based integration between UIM and an external order management system, such as Oracle Communications Order and Service Management (OSM). Order-based federation involves order requests from UIM to an external system that creates, designs, assigns, activates, and tests resources. The external system then provides a response back to UIM. Order-based federation typically revolves around a multi-phased design and delivery process, such as an OSM order flow. Within the multi-phased process, the external order management system may send requests to UIM to lease data, such as pipe-related data for connectivity.
For order-based federation to work, UIM must support the ability to create an order request and send it asynchronously to an external system. Additionally, UIM must support the ability to listen for, and handle, the asynchronous order response from the external system.
The connectivity federation cartridge is an order-based interface that calls asynchronous APIs provided by external systems to lease connectivity resources. This solution uses the Connectivity (Pipe), Business Interaction, and Service entities. A complex resource such as a circuit can be federated, but UIM does not have a native connectivity understanding of the resource; so, in this type of scenario, it is better to relay the work to the external system through a work order.
Note:
The following subsections build upon information presented in UIM Web Services Developer's Guide, which describes a Service Order, and how the Service Order is saved as a business interaction attachment.
A Service Order is a type of Business Interaction request from an external system for UIM to perform various actions on a Service entity. The actions can affect a service, service configuration, and the life cycles of supporting service configuration item resources. Similarly, a Work Order is a type of Business Interaction request from UIM to an external system to perform various actions on inventory entities in external systems, such as network resources, connections, devices, or services. The work order is used within the context of order-based federation.
The schema used for external systems to communicate with UIM is consistent and extensible. For example, the schema:
Provides a consistent way to organize and group the items and entities related to the order
Supports actions with corresponding parameters or properties at the order, item, and entity level
Defines one structure that is used for both requests and responses, regardless of which system is requesting or responding
Defines the <parameter> element, which makes the schema readily extensible through custom parameter names and corresponding custom parameter values
When a Service Order request is received by UIM from an external system, the XML is saved as business interaction attachment. Similarly, when a Work Order request is sent by UIM to an external system, the XML is saved as a business interaction attachment.
The BusinessInteractionAttachment entity defines the following attributes:
name
The name attribute is used for identifying the entity in UIM.
content
The content attribute supports any generic content for a request or response. The content attribute data type is a BLOB, so the entity attachments can contain formats other than XML requests and responses.
category
The category attribute in an enumeration that distinguishes the different attachment categories. The enumeration values are REQUEST and RESPONSE.
parentAttachment and childAttachments
The parentAttachment and childAttachments attributes make it possible to receive multiple responses per request, such as relating the request to its responses in a hierarchical relationship. As a result, the parentAttachment and childAttachments attributes create a parent-child relationship for the attachments. The childAttachments attribute is an ordered list.
This section builds upon the information presented in "Extending the Data Model".
Externally enabled entities are entities that are part of a federation solution. To support federation in UIM, several entities are defined as externally enabled in the metadata through the use of the <externalEnabled> element. The externally enabled entities are:
BusinessInteraction
CustomNetworkAddress
CustomObject
IPAddress
IPSubnet
Pipe
Service
Note:
The federation protocol cartridges do not require using externally enabled entities. Using externally enabled entities is recommended, but is optional depending on your solution requirements.
UIM requires a consistent way to identify external entities, so their external system identities need to be maintained. The entity external identity may or may not have similar properties to UIM entity identity.
External entity identities and internal UIM entity identities must be correlated for both systems to operate on the same intended entity. In addition, the same entity may have other types of identity. For example, the NativeEMS domain presents another identity that is typically found for network-facing entities.
So, it is possible for an entity to have multiple identities, depending on the perspective used to refer to the entity. This perspective is known as the entity management domain. The entity management domain is the context in which the entity identity is commonly known and used, which is typically the owner of the entity identity.
It is also possible to have a one-to-many relationship from the entity to multiple identities. However, some of the more commonly used identities are defined as attributes on the main entity to improve performance and to support application logic. For example, the application logic that supports federated inventory is dependent on these identities.
Externally enabled entities have the following generated attributes:
externalObjectId
The externalObjectId attribute provides a public unique identity for a business entity within the context of the domain specified by externalManagementDomain.
externalName
The externalName attribute provides a business-meaningful name of the business entity (identified by externalObjectID) within the context of the domain specified by externalManagementDomain.
externalManagementDomain
The externalManagementDomain attribute identifies an external system, domain name, party, or participant in a federation solution.
Note:
externalManagementDomain is not the entity owner. Entity ownership can refer to technical or system ownership, such as MSS or INAM. Entity ownership can also refer to business or ownership, such as AT&T or East Region. These two types of entity ownership are independent of each other, as is the type of entity ownership that refers to entity identification management. An ownership attribute is not supported.
externalArrangement
The externalArrangement attribute is an enumeration that identifies the federation model between UIM and the external party for the given entity. The valid enumerated values are:
FEDERATED
Used when the resource is temporarily retrieved from an external system into UIM views. For example, Network System, Product Catalog, and IP Address; before Network System, Product Catalog, and IP Address are shadowed into UIM.
LEASED_IN
Used when data is leased by UIM from an external system, such as an IP address or a connection.
LEASED_OUT
Used when data is leased by UIM to an external system, such as VLAN ID.
SHARED
Used when data is managed cooperatively between UIM and an external system. For example, Network System and Product Catalog data are shadowed into UIM. That is, the data is stored in both the Network System and in UIM.
Note:
In UIM, the availability of a leased resource, such as connectivity (Pipe) or VLAN ID (Custom Network Address), is based on the entity's Inventory State attribute value of INSTALLED or UNAVAILABLE. The leasing terms for the resources, such as effective dates, are not managed using additional entity attributes. Leasing terms are instead managed by communication with the external system. For example, UIM is responsible for initiating or terminating the lease of the resources, along with a corresponding update to the resource inventory state; updates to the entity start and end date are not necessary.
When planning federation with an external system, you need to consider the following actions.
When planning a federated solution, one of the first decisions you need to make is determining which type solution best suits your needs:
Transaction-based solution
Order-based solution
For the federation data domain cartridges, all of the entities that are used in the provided transaction-based and order-based solutions are defined in the metadata as externally-enabled entities. The federation protocol cartridges use a combination of utilizing characteristics and utilizing externally-enabled entities for persisting data from the external system.
When planning a federation solution, you can use any of these entities in your solution, or you can extend the data model by defining any entity to be externally enabled. See Extending the Data Model for more information.
For additional information on planning a federation solution, see the federation technical white papers, which provide detailed information about these solution approaches, including examples of good approaches, as well as approaches to avoid.
Oracle recommends that you deploy only one version of each of the cartridges into any given UIM environment. All three of the federation data domain cartridges, and all the federation protocol cartridges can be deployed into one UIM environment, but not multiple versions of the same cartridge.
See UIM Cartridge Guide for more information on upgrading and extending cartridges and cartridge packs.
Your federation solution must manage external identifiers (IDs). The IDs in UIM, and the IDs in the federated external system, must be evaluated and included in the solution planning process. During the planning process, consider the following regarding managing external IDs:
If the external system is represented in UIM as a Custom Object, the deployed federation cartridge logic must maintain the UIM ID, ensuring the uniqueness across all Custom Objects. The same principle holds true for all the external enabled entities.
The external system has its own ID for the object. This ID can be used to set the UIM ID for the object. For example, the VLAN ID federation cartridge, which interfaces with MSS, sets UIM IDs to system-component-externalSystemID, where system is MSS, component is an MSS component, and externalSystemID is the MSS native ID for the object. This results in UIM IDs such as MSS-NS-1234 or MSS-PC-1234.
Setting UIM IDs using this type of pattern ensures Custom Objects are unique in UIM. Similarly, the IP Address federation cartridge, which cooperates with INAM, sets the UIM ID to include the unique IP address from INAM. This ensures that the Custom Network Addresses are unique in UIM.
The UIM externalObjectId attribute stores the external system's unique ID for an object. The externalObjectId value must be set for UIM logic, or any ruleset logic, to correctly determine which objects are external, and which are native, to UIM.
When a deployed federation cartridge creates an externally enabled entity in UIM, and wants to utilize the externally enabled entity features, the logic that creates the entity must also set the entity attributes. This includes the externally-enabled entity attributes of:
externalObjectId
externalName (optional)
externalArrangement
externalManagementDomain
The methods to set these attributes are defined on the entity. For example, EntityName.setExternalObjectId(), where EntityName is any externally-enabled entity such as CustomObject, BusinessInteraction, Service, and so forth. See "External Identification" for more information about these attributes.
In addition to setting the attributes, the cartridge logic must declare the entity as external by calling the setExternal(true) method. The setExternal() method then calls the setTemporaryEntityId() method to generate a temporary ID for the UIM internal entity ID. Whenever you persist the external entity in UIM, you must first call the unsetTemporaryEntityId() method to remove the temporary ID for the UIM internal entity ID. You can then safely persist the entity in UIM. These methods are also defined on the entity. For example, EntityName.setExternal(), where EntityName is any externally-enabled entity such as CustomObject, BusinessInteraction, Service, and so forth.
You can extend a federation cartridge by adding custom code in a ruleset, or adding custom Java code that a ruleset calls. The custom logic can call a custom web service, making custom web services part of a new federation solution. For example, the VLAN ID federation cartridge that enables communication between UIM and MSS includes a web service called by MSS to update the status of UIM objects.
You can also extend a federation cartridge by using JMS queues to invoke external web services. Refer to the connectivity federation cartridge ora_uim_connectivity_cooperation and the federation protocol cartridge pack for a sample of this scenario.
See UIM Web Services Developer's Guide for information on creating custom web services.