2 Working with the Service Fulfillment Web Service
This chapter provides information about the Oracle Communications Unified Inventory Management (UIM) Service Fulfillment Web Service.
About the Service Fulfillment Web Service
Note:
For this web service, you need an understanding of the following subjects described in UIM Concepts:
-
Planning (business interactions, business interaction items, and engineering work orders)
-
Services (services, service configurations, and service configuration items)
-
Life-cycle management
-
Service fulfillment
The Service Fulfillment Web Service enables an external system to create new business interactions and change existing business interactions in UIM. Similarly, this web service enables an external system to create new engineering work orders and change existing engineering work orders. The Service Fulfillment Web Service also enables you to create multiple pending configurations for a service. See UIM Concepts for more information.
The Service Fulfillment Web Service also enables you to disconnect a service. When you disconnect a service using the Service Fulfillment Web Service, all the configuration versions on the service transition to Canceled status, and an additional configuration version is created with the current date after the service configuration version that is in Completed status.
Note:
Engineering work orders are a type of business interaction. They are based on a special Business Interaction specification and have the same supported Service Fulfillment Web Service functionality as business interactions.
Through business interactions, an external system can manage services, resources associated with services, and relationships between services.
The Service Fulfillment Web Service enables you to:
-
Plan the addition, change, or disconnection of a service through a business interaction
-
Process business interactions to move planned services into current inventory or change existing services in current inventory, and, through custom rulesets and custom code, create or change service configuration items and allocate resources for services in current inventory
-
Retrieve business interactions
-
Transition business entities through their respective life-cycle states within the context of a business interaction
-
Retrieve configurations
-
Retrieve configuration differences
-
Transition services and service configurations through their respective life-cycle states
Figure 2-1 provides an overview of the Service Fulfillment Web Service and its intended usage.
Figure 2-1 Service Fulfillment Web Service Overview
![Description of Figure 2-1 follows Description of Figure 2-1 follows](img/wsv_sf_overview.gif)
Description of "Figure 2-1 Service Fulfillment Web Service Overview"
The following describes the steps for the Service Fulfillment Web Service usage illustrated in Figure 2-1:
-
Call the CaptureInteraction operation. The request provides details regarding the action to take on a service, and includes a list of parameters that provide information UIM needs to provision the service. UIM creates a business interaction and persists the request. The business interaction ID (or external ID representing the business interaction) is returned to the external system.
-
Call the ProcessInteraction operation. The request includes the business interaction ID. This ID is the external ID representing the business interaction. UIM uses the business interaction ID to retrieve the business interaction and the persisted captureInteractionRequest data.
UIM evaluates the service action on the persisted captureInteractionRequest:
-
When the service action is create, UIM creates a new service and service configuration.
-
When the service action is change, UIM finds the service based on the service ID and creates a new service configuration.
A new service configuration is associated to the business interaction. UIM then calls the automateConfiguration() method. You must extend this empty method through a custom ruleset. This method is intended to design and assign the service. See UIM Developer's Guide for more information on custom rulesets.
Within the automateConfiguration ruleset, you can access the following:
-
Business interaction entity
-
Service configuration entity
-
List of parameters from captureInteractionRequest
-
UIM APIs to call and perform various functions, such as unassigning existing resources on the configuration or creating new resources to assign to the configuration.
After resources are assigned to the configuration, the assignments on the service configuration are set to Pending status.
-
-
Call the UpdateInteraction operation to approve the configuration. This updates the status of the assignments on the service configuration from Pending to Approved.
-
Call the GetConfigurationDifferences operation to get details of changes that resulted from the design and assign during ProcessInteraction.
-
Call the UpdateInteraction operation to issue the configuration. This updates the status of the assignments on the service configuration from Approved to Issued.
-
Call the UpdateInteraction operation to complete the configuration. This updates the status of the assignments on the service configuration from Issued to Completed, and also updates the business interaction status to Completed.
About Business Interactions and Services
Only business interactions that support services and service configurations can be added through the web service. However, after the business interaction is created in UIM, you can use the UI to add business interaction items of any type.
Even though business interactions support only services through the web service, services have service configurations, which can have child configurations, and the web service can support these child configurations. For example, a service configuration may have a child configuration that is a service, logical device, logical device account, network, pipe (representing a pipe or channelized connectivity), or place configuration, and these configurations can be added through the customized ProcessInteraction operation as children of a service configuration. Child configurations can also be retrieved through the GetConfiguration operation, and retrieved and compared through the getConfigurationDifferences operation.
Note:
The configuration-specific operation sections of this chapter apply to all configurable entities: service, logical device, logical device account, network, pipe (representing a pipe or channelized connectivity), and place entities.
A configurable place is actually a GeographicSite specialization of the abstract Place entity; GeographicSite is the only specialization of the Place entity that is configurable. See Oracle Communications Information Model Reference for more information.
About Engineering Work Orders
Engineering work orders are related to and share functionality with business interactions. They are based on special Business Interaction specification that you must install by deploying the ora_uim_workorder base cartridge. Engineering work orders have the same supported functionality as business interactions with the Service Fulfillment Web Service.
See UIM Installation Guide for more information about installing base cartridges. See UIM Concepts for more information about engineering work orders and business interactions.
About the Web Service Packaging
The Service Fulfillment Web Service is packaged in the inventory.ear file, within the InventoryWS.war file. When the installer deploys the inventory.ear file, the Service Fulfillment Web Service is automatically deployed and ready to use.
Note:
The InventoryWS.war file also includes all of the Network Resource Management Web Service operations. See "Working with the Service Fulfillment Web Service" for information about these operations.
The Service Fulfillment Web Service is no longer packaged within the UIMServiceFulfillment.war file. This was previously deprecated and is now removed. The URI for the HTTP protocol is /InventoryWS/InventoryWSHTTP and for JMS protocol is /InventoryWS/InventoryWSJMS.
About the WSDL and Schema Files
The Service Fulfillment Web Service is defined by the InventoryWS.wsdl file and is supported by several schema files. The WSDL file and supporting schema files are located in the UIM_SDK_Home/webservices/schema_inventory_webservice.zip file.
About the WSDL File
Within the ZIP file, the WSDL file is located in the ora_uim_webservices/wsdl directory. The WSDL file defines the CaptureInteraction, ProcessInteraction, GetInteraction, UpdateInteraction, GetConfiguration, GetConfigurationDifferences, and UpdateConfiguration operations. Each web service operation defines a request, a response, and the possible faults that can be thrown. For example, the WSDL file defines the following for the CaptureInteraction operation:
-
CaptureInteractionRequest
-
CaptureInteractionResponse
-
CaptureInteractionFault
-
InventoryFault
-
ValidationFault
The request, response, and faults each define an XML structure that is defined in the supporting schema files. The following excerpts show how an XML structure defined in the WSDL correlates to the supporting schema files.
For example, the WSDL file defines and references the biws namespace (in bold):
xmlns:biws="http://xmlns.oracle.com/communications/inventory/webservice/businessinteraction" . . . targetNamespace . . . <xsd:import namespace="http://xmlns.oracle.com/communications/inventory/webservice/businessinteraction" schemaLocation="./schemas/InteractionMessages.xsd"/> . . . <wsdl:message name="CaptureInteractionRequest"> <wsdl:part name= captureInteractionRequest" element="biws:captureInteractionRequest"/> </wsdl:message>
This tells you that the captureInteractionRequest XML structure is defined in the schema file that defines the specified namespace as its target namespace. A search for the specified namespace reveals that InteractionMessages.xsd defines the referenced namespace as its target namespace.
After you determine which schema file defines the XML structure that the WSDL file references, you can navigate through the schema files to determine child XML structures and elements.
About the Schema Files
Several schema files support the Service Fulfillment Web Service. These schemas are categorized as reference schemas, web service schemas, and business schemas.
Reference Schemas
Within the ZIP file, the reference schemas are located in the ora_uim_webservices/wsdl/referenceSchemas directory. The reference schemas define common elements used by more than one operation. So, the elements are defined in one place and then referenced.
The reference schemas are:
-
InventoryCommon.xsd
-
InventoryFaults.xsd
-
FaultRoot.xsd
Web Service Schemas
Within the ZIP file, the web service schemas are located in the ora_uim_webservices/wsdl/schemas directory. The web service schemas define elements specific to the web service, such as the request structures, the response structures, and any fault structures.
The web service schemas are defined in the following files:
-
InteractionMessages.xsd
-
ConfigurationMessages.xsd
Note:
The web service schemas use the type-mapping.xsdconfig file to map XML namespaces to Java packages.
Business Schemas
Within the ZIP file, the business schemas are located in the ora_uim_business/schemas directory. Each web service operation wraps a call (or multiple calls) to the UIM business layer, which is exposed through APIs. The wrapped APIs are the same APIs that the UIM UI calls in response to user input. The business layer APIs are based on functional area, as are the business schemas.
The business schemas are:
-
Activity.xsd
-
BusinessInteraction.xsd
-
Configuration.xsd
-
Connectivity.xsd
-
CustomNetworkAddress.xsd
-
CustomObject.xsd
-
Entity.xsd
-
InventoryGroup.xsd
-
IPAddress.xsd
-
LogicalDevice.xsd
-
MediaStream.xsd
-
Network.xsd
-
NetworkAddress.xsd
-
Number.xsd
-
Party.xsd
-
PhysicalDevice.xsd
-
Place.xsd
-
Property.xsd
-
PropertyLocation.xsd
-
Role.xsd
-
Service.xsd
-
Specification.xsd
-
Structure.xsd
-
TNBlockModelType.xsd
Note:
The API schemas use the xmlbeans-mapping.xsdconfig file to map XML namespaces to Java packages.
CaptureInteraction
The CaptureInteraction operation plans the addition, change, or disconnection of a service through a business interaction. Business interactions are used for planning inventory resources, prior to making the inventory resources available in current inventory.
captureInteractionRequest defines one order per request. The order can define multiple line items, and multiple child orders. Each child order is defined by the same structure as the order on the request. Each child order can define multiple line items and multiple child orders, and so forth.
captureInteractionRequest must specify an interaction action of CREATE or CHANGE. The interaction action is defined as an enumeration in the BusinessInteraction.xsd schema file. The enumeration defines several actions, but CREATE and CHANGE are the only valid actions for CaptureInteraction.
When captureInteractionRequest specifies the CREATE interaction action, it creates a business interaction to contain the order information sent in the request, and creates an attachment that contains the entire <interaction> element from captureInteractionRequest. CaptureInteraction then associates the attachment to the business interaction.
When captureInteractionRequest specifies the CREATE interaction action, you can specify an external ID for the business interaction. The external ID must be unique within UIM, and the calling system is responsible for enforcing the uniqueness; UIM does not enforce uniqueness on external IDs. When an external ID is specified, UIM captures it and stores it with all of the other request data. A subsequent request can then specify a CHANGE interaction action and supply the external ID to identify the business interaction to be changed.
When captureInteractionRequest specifies the CHANGE interaction action, the request must provide either the external ID or the business interaction ID to indicate the business interaction to change. If the request provides an external ID, CaptureInteraction assumes the external ID was supplied when the business interaction was created. CaptureInteraction then retrieves the business interaction and updates it with the order information sent in the request. CaptureInteraction also creates another attachment with a higher sequence number that contains the entire <interaction> element from captureInteractionRequest, and associates the attachment to the business interaction.
You can view the XML that is contained in the attachment from within the UIM UI. If a business interaction has multiple sequence numbers for an attachment, you can view all of them in UIM.
Associating Business Interactions
In UIM, business interactions can be associated with one another. captureInteractionRequest defines an element that enables you to associate one or more child business interactions to the business interaction you are creating or changing. Furthermore, you can associate one or more child business interactions to each child business interaction, which would be the grandchild business interactions to the business interaction you are creating or changing, and so forth.
CaptureInteraction Logic Flow
Figure 2-2 shows what occurs when the CaptureInteraction operation is called. A business interaction is represented as BI in the figure.
In Figure 2-2, the Validate XML Input box represents the custom ruleset that you can configure to run before the creation of the attachment. See "Validating Input Data" for more information.
CaptureInteraction wraps the BusinessInteraction.captureInteraction() API method. The API method defines two arguments: the parent business interaction, and the XML. When CaptureInteraction calls the API method, the parent business interaction argument is always null. If the interaction action is CREATE, the API method creates a business interaction, creates an attachment, and associates the attachment to the business interaction. If the interaction action is CHANGE, the API method changes the business interaction, creates an attachment with a higher sequence number, and associates the attachment to the business interaction.
If the business interaction defines a child business interaction, the API method is called from within itself. In this scenario, the parent business interaction argument is no longer null. As a result, after the business interaction is created, and the attachment is created and associated, the business interaction is associated to the parent business interaction that was specified by the argument. For example, a request defines one new business interaction that has one child business interaction. CaptureInteraction calls the API method with a parent business interaction argument of null. Business interaction A is created. The attachment is created and associated to business interaction A. Because the parent business interaction argument is null, the Associate BI to Parent BI box does nothing. Next, the first (in this example, the only) child business interaction is processed and calls the API method with a parent business interaction argument (business interaction A). Business interaction B is created. The attachment is created and associated to business interaction B. Because the parent business interaction argument is not null, business interaction B is associated to the parent business interaction argument that was supplied (business interaction A).
Validating Input Data
You can validate the request input data through custom code. The custom code can reside in a ruleset, or in Java code that the ruleset calls. You can configure your ruleset to run at a provided base extension point that defines the createBIAttachment() method. By configuring your ruleset to run before this method, your custom validations run before the attachment is created. If the validation fails, the session rolls back and the business interaction that was created is not committed.
To validate input data:
-
In Design Studio, create an Inventory project.
-
Open the Project editor.
-
Click the Dependency tab.
-
Add the ora_uim_base_extpts cartridge to the list of dependencies.
-
Save the project.
-
Create a ruleset.
Write your custom validations in the ruleset or in Java code that the ruleset calls. For information about writing custom rulesets, see UIM Developer's Guide.
-
Save the ruleset.
-
Create a ruleset extension point and configure it as follows:
-
In Ruleset, select your ruleset.
-
In Point, select the BusinessInteractionManager_createBusinessInteractionAttachment base extension point.
-
In Placement, select BEFORE.
-
Save the ruleset extension point.
-
-
Open the Service Order base specification.
This step assumes you are using the Service Order base specification, and have copied it from the ora_uim_basespecifications cartridge into your project for modifying. If you are not using the Service Order base specification for your Business Interaction specification, open the Business Interaction specification that you are using. See "Business Interaction" for more information about the Service Order base specification.
-
Click the Rules tab.
-
Click Select.
-
Select your ruleset extension point.
-
Click OK.
-
Save the Business Interaction specification.
-
Build the project.
-
Deploy the resultant cartridge.
captureInteractionRequest
Figure 2-3 shows the high-level content of captureInteractionRequest. Each request defines a single interaction, which specifies the data used to create the business interaction. The interaction defines a header and a body. The body defines a sequence of items: each item defines a service, and each service defines a service configuration. The body also defines a sequence of interactions, which specifies the data used to create any child business interactions.
Example 2-1 is a condensed version of captureInteractionRequest that highlights the main content to better understand CaptureInteraction. The example is numbered so that information describing the example can be referenced.
Example 2-1 omits the following:
-
Namespaces, and assumes that they are properly defined
-
Elements such as notes, start and end dates, effective dates, and descriptions
-
Structures that detail an external ID, specification, configuration, and configurationItem
-
Structures and elements within party and place, which are designated with ". . ."
Note:
CaptureInteraction, ProcessInteraction, GetInteraction, and UpdateInteraction all use the same structure for the request and for the response. The only difference is the actual request/response name (line 01 and line 71).
Example 2-1 Condensed captureInteractionRequest
01 <captureInteractionRequest> 02 <invbi:interaction> 03 <invbi:header> 04 <invbi:specification/> 05 <invbi:action/> 06 <invbi:id/> 07 <invbi:name/> 08 <invbi:externalIdentity/> 09 <invbi:state/> 10 </invbi:header> 11 <invbi:body> 12 <invbi:item> 13 <invbi:externalIdentity> 14 <invbi:action/> 15 <invbi:service> 16 <invsvc:specification/> 17 <invsvc:id/> 18 <invsvc:action/> 19 <invsvc:name/> 20 <invsvc:externalIdentity/> 21 <invsvc:state/> 22 <invsvc:place> 23 . . . 24 <invplace:service> 25 . . . 26 <invsvc:party> 27 . . . 28 <invparty:service> 29 . . . 30 <invsvc:configuration/> 31 </invparty:service> 32 </invsvc:party> 33 <invsvc:configuration/> 34 </invplace:service> 35 </invsvc:place> 36 <invsvc:party> 37 . . . 38 <invparty:service> 39 . . . 40 <invsvc:place> 41 . . . 42 <invplace:service> 43 . . . 44 <invsvc:configuration/> 45 </invplace:service> 46 </invsvc:place> 47 <invsvc:configuration/> 48 </invparty:service> 49 </invsvc:party> 50 <invsvc:configuration/> 51 </invbi:service> 52 <invbi:parameter> 53 <invbi:name/> 54 <invbi:value/> 55 </invbi:parameter> 56 </invbi:item> 57 <invbi:interaction> 58 </invbi:header> 59 <invbi:specification/> 60 <invbi:action/> 61 <invbi:id/> 62 <invbi:name/> 63 <invbi:externalIdentity/> 64 <invbi:state/> 65 </invbi:header> 66 </invbi:interaction> 67 </invbi:body> 68 </interaction> 69 <executeProcess/> 70 <responseLevel/> 71 </captureInteractionRequest>
Throughout Example 2-1, the <specification> element that is shown is actually a structure that defines the following elements:
Example 2-2 Specification Structure
<invbi:specification>
<invent:entityNote/>
<invspec:name/>
<invspec:entityClass/>
<invspec:description/>
<invspec:startDate/>
<invspec:endDate/>
</invbi:specification>
Within the specification structure, the <name> element is the name of a specification. This <name> element is not be confused with the <name> element that is specified for the business interaction (line 07) or for the service (line 19). For example, a request that specifies the CREATE interaction action must supply the business interaction specification name (within the specification structure on line 04), and the name of the business interaction being created by the request (line 07). Similarly, a request that specifies the add service action must supply the Service specification name (within the specification structure on line 16), and the name of the service being created by the request (line 19).
Within the specification structure, the <entityClass> element is defined as an enumeration in the Specification.xsd schema file. The enumeration values reflect UIM entity specification types, such as BusinessInteraction, Service, Equipment, and so forth. The Service Fulfillment Web Service does not use the <entityClass> element, so the request does not need to specify it.
Business Interaction
captureInteractionRequest captures one interaction per request (lines 02 through 68). For each interaction, the request captures one or more items (lines 12 through 56), and one or more child interactions (lines 57 through 66).
When calling CaptureInteraction, the request must specify an interaction action (line 05) of CREATE or CHANGE. The interaction <action> element is defined as an enumeration in the BusinessInteraction.xsd schema file.
If the interaction action is CREATE, the request must provide an arbitrary name for the business interaction (line 07) being created, and the business interaction specification name (within line 04) upon which the business interaction is being based. (The specification name is typically Service Order, which is the business interaction specification provided in the ora_uim_basespecifications cartridge.) The request can optionally provide an external ID for the business interaction. You do not need to provide the specification entityClass enumeration value of BusinessInteraction; this is assumed based on the placement of the specification structure within the <interaction> element.
If the interaction action is CHANGE, the request must provide the external ID (within line 08) or the business interaction ID (line 06) to indicate the business interaction to change, and the actual changes.
Business Interaction Item
captureInteractionRequest captures one or more items per interaction. Example 2-1 shows just one item (lines 12 through 56). To include multiple items, replicate the item and place it between lines 56 and 57.
Each item defines an interaction action (line 14), which must be ADD regardless of the request.
Note:
The interaction action must be ADD. It cannot be another action value and it cannot be left blank. If the interaction action is not ADD, the operation errors.
Business Interaction Item Parameter
Each business interaction item optionally specifies one or more input parameters. For these parameters, the complex type ParameterType is defined as the following:
<xsd:element maxOccurs="unbounded" minOccurs="0" name="parameter" type="invbi:ParameterType"> </xsd:element>
The value element definition within ParameterType is the following:
<xs:element name="value" type="xsd:anyType">
For the value element with the anyType declaration, you can use any valid XML schema type that provides the following:
-
An entity in UIM
-
A type of StructuredType, defined in the business schema file Structure.xsd
Use the StructuredType complex type to pass entities with multiple property values. Example 2-3 provides sample XML for using StructuredType with one level of property information.
Example 2-3 Parameter Sample using StructuredType with One Level
<invbi:parameter> <invbi:name>StructuredType Parameter</invbi:name> <invbi:value xsi:type="invstruc:StructuredType"> <invstruc:name>CPE Device 1</invstruc:name> <invstruc:property> <invprop:name>CPE_MAC</invprop:name> <invprop:value xsi:type="xs:string">01-23-45-67-89-ab</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_Model</invprop:name> <invprop:value xsi:type="xs:string">PBS</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_Brand</invprop:name> <invprop:value xsi:type="xs:string">Motorola</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_SerialNumber</invprop:name> <invprop:value xsi:type="xs:string">4TUI-632552</invprop:value> </invstruc:property> </invbi:value> </invbi:parameter>
If you have properties with hierarchical information, you create the parameter list with the StructuredType including a hierarchy. Example 2-4 provides sample XML for using StructuredType including a child element representing hierarchical property information.
Example 2-4 Parameter Sample using StructuredType with Hierarchy
<invbi:parameter> <invbi:name>Structured Param </invbi:name> <invbi:value xsi:type="invstruc:StructuredType"> <invstruc:name>CPE Device</invstruc:name> <invstruc:property> <invprop:name>CPE_MAC</invprop:name> <invprop:value xsi:type="xs:string">1.2.3.4</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_Model</invprop:name> <invprop:value xsi:type="xs:string">MI6</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_Brand</invprop:name> <invprop:value xsi:type="xs:string">Motorola</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>CPE_SerialNumber</invprop:name> <invprop:value xsi:type="xs:string">838373723</invprop:value> </invstruc:property> <invstruc:child xsi:type="invstruc:StructuredType"> <invstruc:name>Channel Pack</invstruc:name> <invstruc:property> <invprop:name>CPE_MAC</invprop:name> <invprop:value xsi:type="xs:string">1.2.3.5</invprop:value> </invstruc:property> <invstruc:property> <invprop:name>code</invprop:name> <invprop:value xsi:type="xs:string">code value A</invprop:value> </invstruc:property> </invstruc:child> </invbi:value> </invbi:parameter>
Service
Each item defines a service, as shown in Example 2-1 (lines 15 through 51). For each service, you must supply a valid Service specification name (within line 16) from which to create an instance of the specification in UIM.
Note:
The <service> element (line 15) is actually defined as a choice in the BusinessInteraction.xsd schema file, with the choices being service, connectivity, and entity. However, the service choice is the only choice you can use in the request. The connectivity choice is not supported by the Service Fulfillment Web Service, and the entity choice is not used in the request; it is only used in the response.
Each service also defines a service action (line 18). The service action is not an enumeration, as are the interaction action and item action. Rather, there are several predefined service actions that UIM code recognizes. You can extend the list of service actions and their corresponding processes through custom rulesets. Service actions are further explored in "Customizing ProcessInteraction".
Specifically, there are some service actions that the core code recognizes. Through a custom ruleset, you can extend the input service actions and map each custom service action to one of the service actions that the core code recognizes.
The service may also specify a place (lines 22 through 35) or a party (lines 36 through 49) to associate to the service.
The request and response use the same structure. Most of the elements are used only by the response, so there are numerous elements that are not used by the request. For example, a service and configuration for the place (lines 24 through 34), a service and configuration for the party (lines 38 through 48), and the configuration for the service itself (line 50).
Associated Business Interaction
captureInteractionRequest captures one or more child interactions per interaction. Example 2-1 shows just one child interaction (lines 57 through 66). To include multiple interactions, replicate the child interaction (lines 57 through 66) and place it between lines 66 and 67.
ExecuteProcess Element
The <executeProcess> element (line 69) is defined after the interaction and applies to the interaction. This element is defined as a Boolean and is used only by CaptureInteraction. When the value of <executeProcess> is true, CaptureInteraction executes and, upon completion, ProcessInteraction executes. This eliminates the need to place two separate web service calls; one for CaptureInteraction and one for ProcessInteraction. When the value of <executeProcess> is false, just CaptureInteraction executes. The default value is false.
ResponseLevel Element
captureInteractionRequest, processInteractionRequest, getInteractionRequest, and updateInteractionRequest define the <responseLevel> element (line 70). This element specifies an enumeration value, as defined by the InteractionResponseLevelEnum enumeration in the InteractionMessages.xsd schema file.
Depending on the enumeration value specified in the request, the level of information returned by the response can vary:
-
INTERACTION
Returns just the interaction information.
-
INTERACTION_ITEM
Returns the interaction and item information.
-
INTERACTION_ITEM_ENTITY
Returns the interaction, item, and entity information.
-
INTERACTION_ITEM_ENTITY_CONFIGURATION (default option)
Returns the interaction, item, entity, and configuration information.
-
INTERACTION_ITEM_ENTITY_CONFIGURATION_EXPANDED
Returns the interaction, item, entity, configuration, and any child configurations.
captureInteractionResponse
captureInteractionResponse returns a varying level of information based on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
captureInteractionResponse always includes the business interaction ID and the current business interaction state. If a new business interaction is created, the business interaction ID generated by UIM is returned. If an existing business interaction is changed, the business interaction ID sent with the request is returned. The valid business interaction states are CREATED, IN_PROGRESS, COMPLETED, or CANCELLED, as defined by an enumeration in the BusinessInteraction.xsd schema file.
captureInteractionResponse returns an error when:
-
The request specifies an interaction action of CREATE with a business interaction ID that already exists.
-
The request specifies an interaction action of CHANGE with a business interaction ID (or external ID) that does not exist.
-
An optional extension point is used to validate the input, and the associated ruleset logs an error. For example, the XML input does not validate.
ProcessInteraction
The ProcessInteraction operation moves planned services into current inventory. The planned service is represented by the <interaction> element, which is stored in UIM as a business interaction attachment, having been placed there by CaptureInteraction.
ProcessInteraction retrieves the business interaction and the attachment with the highest sequence number and, based on the items defined for the interaction, processes each item. Each item creates or updates a service, including any default service configuration items defined by the specified Service Configuration specification.
ProcessInteraction also calls the following methods per service configuration item:
-
BusinessInteractionManager.getEntityAction()
-
BaseConfigurationManager.automateConfiguration()
The ora_uim_baseextpts cartridge provides base extension points for both of these methods, which you can use to run custom code that maps custom service actions and that creates or updates service configuration items. This topic is further explored in "ProcessInteraction Logic Flow" and "Customizing ProcessInteraction".
When calling ProcessInteraction, the request must specify the external ID or the business interaction ID to indicate the business interaction to process.
The request can specify whether to process the entire business interaction, or just specific business interaction items. If the request specifies the external ID or business interaction ID only, the entire business interaction is processed; if the request specifies the external ID or business interaction ID and specific business interaction items, only the specified business interaction items are processed.
ProcessInteraction Logic Flow
Figure 2-4 shows what occurs when processInteractionRequest specifies a CREATE interaction action. A business interaction is represented as BI in the figure.
In Figure 2-4, the light gray boxes represent the work performed by ProcessInteraction, prior to calling the custom ruleset. ProcessInteraction handles the processing of the business interaction. The dark gray boxes represent the work performed by custom code, which handles:
-
Mapping custom service actions to UIM entity actions (optional)
If your implementation uses only existing service actions, this custom code is not needed; if your implementation defines additional custom service actions, this custom code is required.
-
Processing business interaction items (required)
The processing of the business interaction items involves customizations that are necessary to meet the business requirements of providing the specific type of service. This custom code must process service actions, custom service actions, and custom parameters, and calls the appropriate UIM API methods to create the service in UIM.
Service Configuration Association
Regarding the Associate Service Configuration to BI box in Figure 2-4: A service configuration is indirectly associated to a business interaction through the business interaction items. This association is shown by the dotted line in Figure 2-5. To associate the service configuration to the business interaction, ProcessInteraction:
-
Creates business interaction items based on the items for the interaction in the request
-
Associates the business interaction items to the service configuration
Figure 2-5 Association of Service Configuration to BI
![Description of Figure 2-5 follows Description of Figure 2-5 follows](img/wsv_sf_pro_int_assoc_rels.gif)
Description of "Figure 2-5 Association of Service Configuration to BI"
Customizing ProcessInteraction
Customizing ProcessInteraction involves the following:
An example of customizing ProcessInteraction is described in "ProcessInteraction Example".
Modeling the Service in Design Studio
Before you begin customizing ProcessInteraction, you must model your service within an Inventory project in Design Studio. For example, your Inventory project must define specifications that describe your service, service configuration, and service configuration items that fulfill the service in UIM.
See UIM Concepts for information about services and service configurations, and see the Design Studio Help for information about modeling services in Design Studio.
Customizing Service Actions
captureInteractionRequest defines a service action for each service in the request. The service action is not an enumeration; rather, there are several predefined actions (called entity actions) that UIM code recognizes and processes.
The UIM-defined entity actions are:
-
create
-
change
-
delete
-
disconnect
-
suspend
-
resume
-
no_action
Note:
The no_action service action prevents the creation of new service configurations as a part of process interaction flow in UIM. This service action merges the changes into existing service configurations that are in progress. For example, you can use this service action in Revision orders where the service is still in Pending and the existing service configurations should be updated than creating new ones.
The web service recognizes two additional entity actions that enable the web service to perform additional functionality. They are:
-
suspendWithConfiguration
-
resumeWithConfiguration
For example, the suspend entity action suspends a service but does not touch the service configuration. The suspendWithConfiguration entity action suspends a service and creates a new service configuration version. Similarly, the resume entity action resumes a suspended service but does not modify the service configuration. The resumeWithConfiguration entity action resumes a suspended a service and creates a new service configuration version. (For either action, if an existing service configuration version does not exist, an error is thrown because the service configuration must already exist if you are suspending or resuming it.)
Note:
All of the entity actions are case sensitive.
Customizations are based on the service action (Example 2-1, line 18) and parameters (Example 2-1, lines 52 through 55). So, you must establish a finite list of service actions and parameters that can be specified in the request, which can then be recognized by, and processed by, the custom code.
To customize service actions:
-
Determine the finite list of service actions and parameters to process.
If your finite list of service actions includes only UIM-defined entity actions (and no custom service actions), you do not need to perform this procedure.
-
In Design Studio, open the Project editor.
This is the same project that contains the specifications you created to model your service.
-
Click the Dependency tab.
-
Add the ora_uim_base_extpts cartridge to the list of dependencies.
-
Save the project.
-
Create a ruleset.
Write custom code that maps your custom service actions to entity actions. The custom code can be in the ruleset, or in Java code that the ruleset calls. For information about writing custom rulesets, see UIM Developer's Guide.
-
Save the ruleset.
-
Create a ruleset extension point and configure it as follows:
-
In Ruleset, select your ruleset.
-
In Point, select the BusinessInteractionManager_getEntityAction base extension point.
-
In Placement, select INSTEAD.
-
Save the ruleset extension point.
-
-
Open your Service specification.
-
Click the Rules tab.
-
Click Select.
-
Select your ruleset extension point.
-
Click OK.
-
Save the Service specification.
-
Build the project.
-
Deploy the resultant cartridge.
Customizing the Automation of Service Configurations
To customize the automation of service configurations:
-
In Design Studio, open the Project editor.
This is the same project that contains the specifications that your created to model your service.
-
Click the Dependency tab.
-
Add the ora_uim_base_extpts cartridge to the list of dependencies.
-
Save the project.
-
Create a ruleset.
Write custom code that processes the business interaction items, evaluates the mapped entity actions and custom parameters, and calls the appropriate API methods to create the service in UIM. See "Developing the Custom Code" for more information.
The custom code can be in the ruleset, or in Java code that the ruleset calls. For information about writing custom rulesets, see UIM Developer's Guide.
-
Save the ruleset.
-
Create a ruleset extension point and configure it as follows:
-
In Ruleset, select your ruleset.
-
In Point, select the BaseConfigurationManager_automateConfiguration base extension point.
-
In Placement, select INSTEAD.
-
Save the ruleset extension point.
-
-
Open your Service Configuration specification.
-
Click the Rules tab.
-
Click Select.
-
Select your ruleset extension point.
-
Click OK.
-
Save the Service Configuration specification.
-
Build the project.
-
Deploy the resultant cartridge.
Developing the Custom Code
ProcessInteraction triggers events that result in a call to custom code that automates service configurations by calling API methods to fulfill the service in UIM.
See UIM API Overview for code examples that show how to call the UIM API methods from within custom code.
The following information pertains to the custom code:
-
The custom code must handle and process the XML payload based on the domain-specific business rules and models.
-
The custom code must handle the creation or deletion of any dependent resources.
-
The custom code must handle auto-design for new orders and auto-redesign for change orders.
-
The custom code can assume the service and service configuration are already created; the purpose of the custom code is to manage the resources and characteristics.
-
When modifying a subservice with parent input only:
The business interaction attachment typically may not contain specific change request information for a subservice that was created when fulfilling the requested service. For example, a voice mail service created by UIM to fulfill the request for a Mobile GSM service with a voice mail feature. In this scenario, the voice mail service is a subservice assigned to the Mobile GSM service. When the subservice requires a change, the change request and service action are often submitted for the parent service, and not for the subservice.
In such scenarios, the web service operation has to identify that the change service action is for the subservice, and process the change for the subservice. For example, if the custom code needs to act on a subservice, it can build a request based on the subservice, call CaptureInteraction, and recursively call ProcessInteraction until it returns the no action entity action.
ProcessInteraction Example
The following list describes some project content your implementation may require to run ProcessInteraction.
-
Numerous custom specifications and characteristics
At a minimum, your project needs to define a Service specification, a Service Configuration specification, and resource-specific specifications, such as Telephone Number, Physical Device, Logical Device, and so forth. Your project may also require characteristics in which to store resource-specific data.
-
AUTOMATE_MY_CONFIGURATION.ruleset
This is a custom ruleset that is the entry point into the custom code. The ruleset calls the AutomateMyConfiguration() method, which is defined in a custom Java class. In this example, the custom Java class is named MyConfigurationManagerImpl.java, which is also described in this list.
-
AUTOMATE_MY_CONFIGURATION_EXT.rst
This is a custom ruleset extension point that associates the AUTOMATE_MY_CONFIGURATION custom ruleset to the UIM-provided BaseConfigurationManager_automateConfiguration extension point and configures the custom ruleset to run instead of the method that the extension point defines (the BaseConfigurationManager.automateConfiguration() method).
-
MAP_MY_SERVICE_ACTION.ruleset
If you defined custom service actions, this is a custom ruleset that evaluates custom service actions specified in the request and maps them to an entity action that is recognizable to UIM. In this example, there are five custom service actions, so this ruleset evaluates the five custom service actions and maps each one to the appropriate entity action. The entity actions are defined in the Service Fulfillment Web Service code, as described in "Customizing ProcessInteraction".
Table 2-1 provides an example of mapping custom service actions to UIM entity actions.
Table 2-1 Example Mapping of Custom Service Actions
Custom Service Action UIM Entity Action createMyService
create
updateMyService
change
changeAddToMyService
change
disconnectMyService
disconnect
suspendMyService
suspend
-
MAP_MY_SERVICE_ACTION_EXT.rst
This is a custom ruleset extension point that associates the MAP_MY_SERVICE_ACTION custom ruleset to the UIM-provided BusinessInteractionManager_getEntityAction extension point and configures the custom ruleset to run instead of the method that the extension point defines (BusinessInteractionManager.getEntityAction() method).
-
MyConfigurationManagerImpl.java
This is custom Java code that contains a series of if else statements that evaluate the mapped entity action. For each entity action, the code calls another method within the same class. Within each of these methods, the finite set of parameters that are valid for the specific service action that was mapped to the entity action is evaluated.
From there, the custom code calls various API methods to perform the work required to realize any service in UIM.
-
Any additional custom rulesets and ruleset extension points
When the custom code calls API methods, the existing API functionality may need to be extended to realize a service in UIM. So, your project may also have to define any needed rulesets that can be configured to run before or after the API methods that the custom code calls.
processInteractionResponse
processInteractionResponse returns a varying level of information based on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
ProcessInteraction returns an error when:
-
It cannot find the business interaction specified by the calling system.
-
The calling system specifies an input item entity other than Service.
-
Any errors thrown by the custom code that ProcessInteraction calls.
GetInteraction
The GetInteraction operation retrieves a business interaction based on an external ID or business interaction ID. The data returned in the response depends on when GetInteraction is called and on the <responseLevel> value getInteractionRequest specifies.
When GetInteraction is called before ProcessInteraction, the response returns only the business interaction data. In this scenario, service data is not returned because ProcessInteraction has not yet processed the business interaction into current inventory, so there is no service data in UIM yet.
When GetInteraction is called after ProcessInteraction, the response returns the business interaction data and service data. In this scenario, service data is returned because ProcessInteraction has processed the business interaction into current inventory, so there is service data in UIM to retrieve. The level of detail of service data returned by the response depends on the <responseLevel> value getInteractionRequest specifies. See "ResponseLevel Element" for more information.
GetInteraction Logic Flow
Figure 2-6 shows what occurs when the GetInteraction operation is called. A business interaction is represented as BI in the figure.
getInteractionResponse
getInteractionResponse returns a varying level of information based on when the operation is called and on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
GetInteraction returns an error when:
-
The request does not specify an external ID or business interaction ID upon which to base the retrieval
-
It cannot find the business interaction specified in the request
UpdateInteraction
The UpdateInteraction operation transitions UIM business entities through their respective life-cycle states within the context of a business interaction.
When calling UpdateInteraction, the request must specify an external ID or business interaction ID and an interaction action of APPROVE, ISSUE, CANCEL, or COMPLETE. If you want to change the effective date of the configuration version, the request must specify an effectiveDate and an interaction action of CHANGE.
Interaction actions are defined by the BusinessInteractionActionEnum enumeration in the BusinessInteraction.xsd schema file. This enumeration defines several actions, but only the APPROVE, ISSUE, CANCEL, COMPLETE, or CHANGE actions are valid for UpdateInteraction.
UpdateInteraction uses the business interaction ID to find the service and service configuration, and performs the specified action for the service and service configuration. For example, if the interaction action is APPROVE, it approves the service and service configuration associated to the business interaction and performs the action recursively to any child business interactions.
UpdateInteraction does not cascade to child entities assigned to configuration items. For example, if the business interaction is associated to a service configuration, and the service configuration has a service configuration item with a child service assigned to it, UpdateInteraction does not apply the action to the service configuration item child service status.
UpdateInteraction Logic Flow
Figure 2-7 shows what occurs when the UpdateInteraction operation is called. A business interaction is represented as BI in the figure.
updateInteractionResponse
updateInteractionResponse returns a varying level of information based on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
UpdateInteraction returns an error when:
-
It cannot find the business interaction specified by the calling system
-
The request specifies a value for <item> other than <service>
GetConfiguration
The GetConfiguration operation retrieves one of the following, based on a search option specified in the request:
-
Service Configuration
-
Pipe Configuration (representing a pipe or channelized connectivity)
-
Logical Device Configuration
-
Logical Device Account Configuration
-
Network Configuration
-
Place Configuration
A successful response returns the following for the specified configuration:
-
Configuration
-
Configuration properties (attributes and characteristics)
-
Configuration items (including any assigned or referenced resources)
-
Child entities and their child configurations
For example, Figure 2-8 shows the data that can be retrieved, in dark gray, for a requested configuration. GetConfiguration does not retrieve information about relationships to other entities. However, you can customize GetConfiguration to return additional information. See "Customizing GetConfiguration" for more information.
Figure 2-8 Example Service Configuration Retrieval
![Description of Figure 2-8 follows Description of Figure 2-8 follows](img/wsv_sf_get_config_rtn.gif)
Description of "Figure 2-8 Example Service Configuration Retrieval"
Note:
A configurable place is actually a GeographicSite specialization of the abstract Place entity; GeographicSite is the only specialization of the Place entity that is configurable. See Oracle Communications Information Model Reference for more information.
getConfigurationRequest
This section describes getConfigurationRequest, in which you specify a search option that tells GetConfiguration which type of configuration to return. In the request, you can also specify additional request options that tell GetConfiguration what data to include in the response, or to omit from the response.
Request Search Options
In getConfigurationRequest, you specify a search option that indicates the type of configuration to retrieve. The search options, which are defined in the ConfigurationMessages.xsd schema file, are listed and described in Table 2-2.
Note:
For each search option listed in Table 2-2, Entity represents:
-
DeviceInterface
-
Connectivity
-
LogicalDevice
-
LogicalDeviceAccount
-
Network
-
Place
-
Service
Table 2-2 GetConfiguration Search Options
Search Option | Description |
---|---|
EntityConfigurationSearchByConfigId |
GetConfiguration retrieves the configuration based on the specified configuration ID. |
EntityConfigurationSearchByEntityId |
GetConfiguration retrieves the latest active configuration (any state other than CANCELLED) based on the specified entity ID. If there is only one configuration, GetConfiguration retrieves it. |
EntityConfigurationSearchByVersionNumber |
GetConfiguration retrieves the configuration based on the specified entity ID and version number. |
EntityConfigurationSearchByConfigStatus |
GetConfiguration retrieves the latest configuration based on the entity ID and configuration state. States can be IN_PROGRESS, DESIGNED, ISSUED, COMPLETED, PENDING_CANCEL, or CANCELLED. |
EntityConfigurationSearchByEffectiveDate |
GetConfiguration retrieves the configuration based on the specified entity ID and configuration effective date. |
ConnectivityConfigurationSearchByConnectivityIdentifier |
GetConfiguration retrieves the latest active pipe configuration (any state other than CANCELLED) based on the specified connectivity identifier. If there is only one pipe configuration, GetConfiguration retrieves it. This search option is applicable only when getting pipe configurations. |
Request Search Option Examples
Example 2-5 shows getConfigurationRequest with a search option of ServiceConfigurationSearchByConfigId in bold. The element below the search option shows the configuration ID to search for.
Example 2-5 getConfigurationRequest
<con:getConfigurationRequest>
<responseLevel>ENTITY_CONFIGURATION_EXPANDED</responseLevel>
<con:searchOptions xsi:type="con:GetServiceConfigurationType"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<con:configSearchOption
xsi:type="con:ServiceConfigurationSearchByConfigId">
<con:configurationId>123456</con:configurationId>
</con:configSearchOption>
</con:searchOptions>
</con:getConfigurationRequest>
Example 2-6 shows getConfigurationRequest with a search option of ConnectivityConfigurationSearchByVersionNumber in bold. The elements below the search option show the entity ID and configuration version number to search for.
Example 2-6 getConfigurationRequest
<con:getConfigurationRequest>
<responseLevel>ENTITY_CONFIGURATION_EXPANDED</responseLevel>
<con:searchOptions xsi:type="con:GetConnectivityConfigurationType"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<con:configSearchOption
xsi:type="con:ConnectivityConfigurationSearchByVersionNumber">
<con:entityId>1</con:entityId>
<con:versionNumber>1</con:versionNumber>
</con:configSearchOption>
</con:searchOptions>
</con:getConfigurationRequest>
Additional Request Options
In getConfigurationRequest, you can also specify the following options. If an option is not specified in the request, the operation uses the default value.
-
includeTags
-
When set to true, the response includes tags on configuration items, with the tag name and description populated.
-
When set to false (the default), the response does not include tags on configuration items.
For information about tags, see the Design Studio Help.
-
-
includeTagsOtherInfo
-
When set to true, tag name, description, and otherInformation are populated.
-
When set to false (the default), tag name and description are populated; otherInformation is not populated.
Note:
The includeTagsOtherInfo option is only applicable when includeTags is true.
For information about tags, see the Design Studio Help.
-
-
includeNetworkTargets
-
When set to true, the response includes network targets.
-
When set to false (the default), the response does not include network targets.
For information about network targets, see UIM Concepts.
-
Additional Request Options Example
Example 2-7 shows getConfigurationRequest with the additional request options.
Example 2-7 getConfigurationRequest
<con:getConfigurationRequest> <com:header></com:header> <con:searchOptions . . . </con:searchOptions> <con:includeTags>true</con:includeTags> <con:includeTagsOtherInfo>true</con:includeTagsOtherInfo> </con:getConfigurationRequest>
ResponseLevel Element
getConfigurationRequest and updateConfigurationRequest define the <responseLevel> element. This element specifies an enumeration value, as defined by the ConfigurationResponseLevelEnum enumeration in the ConfigurationMessages.xsd schema file. (This element does not apply to getConfigurationDifferencesRequest.)
Depending on the enumeration value specified in the request, the level of information returned by the response can vary:
-
ENTITY_CONFIGURATION (default option)
Returns the entity and configuration information.
-
ENTITY_CONFIGURATION_EXPANDED
Returns the entity, configuration, and any child configurations.
GetConfiguration Logic Flow
Figure 2-9 shows what occurs when the GetConfiguration operation is called.
Depending on which search option is specified, the logic flow may start with the Get Configuration box, or it may start with the Get Entity box. For example, if the search option is EntityConfigurationSearchByConfigId, the entry point to the logic flow is the Get Configuration box. If the search option is any other option, which are all based on an entity ID, the entry point to the logic flow is the Get Entity box.
getConfigurationResponse
getConfigurationResponse returns a varying level of information based on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
GetConfiguration returns an error when:
-
The request specifies a search option other than the valid search options listed in Table 2-2.
-
The request does not specify the data that the search option needs to perform the search.
-
The operation cannot find the configuration ID, entity ID, or connectivity identifier specified in the request.
Customizing GetConfiguration
Note:
This section describes the use of rulesets and extension points to customize GetConfiguration. See UIM Developer's Guide for detailed information about rulesets and extension points.
For your implementation, you may need more information than GetConfiguration returns. For example, GetConfiguration does not retrieve information about relationships to other entities. If you have an assigned entity that is a physical device, you may want GetConfiguration to return the mapped logical device or some of its characteristics. Or, for a device interface, you may want GetConfiguration to return the mapped physical port. For such scenarios, you can customize GetConfiguration to return additional information.
Extension Points
The UIM_SDK_Home/cartridges/base/ora_uim_baseextpts cartridge provides the following specification-based extension points for customizing GetConfiguration:
-
BaseConfigurationManager_populateCustomProperties.rstp, which defines the following method signature:
public Map<String, String> populateCustomProperties(ConsumableResource resource, InventoryConfigurationItem item, InventoryConfigurationVersion inventoryConfigurationVersion)
-
BaseConfigurationManager_populateCustomProperties2.rstp, which defines the following method signature:
public Map<String, String> populateCustomProperties(ConfigurationReferenceEnabled entity, InventoryConfigurationItem item, InventoryConfigurationVersion inventoryConfigurationVersion)
GetConfiguration always calls the populateCustomProperties() methods, which are empty methods that exist for customizing GetConfiguration. Within a configuration, each configuration item represents a resource, which may be assigned or referenced. The populateCustomProperties() methods define different inputs; a consumable resource entity versus a reference-enabled entity. The former method is called during the process of retrieving assigned resources, and the latter method is called during the process of retrieving referenced resources.
Customization Steps
To customize GetConfiguration:
-
Create a ruleset to retrieve any additional assigned resource data that your implementation requires.The ruleset must return a Map containing a name/value pair of the retrieved data name and corresponding data value.
-
Create a ruleset extension point to configure your ruleset to run after the populateCustomProperites() method, using the BaseConfigurationManager_populateCustomProperties.rstp extension point.
-
Create a ruleset to retrieve any additional referenced resource data that your implementation requires. The ruleset must return a Map containing a name/value pair of the retrieved data name and corresponding data value.
-
Create a ruleset extension point to configure your ruleset to run after the populateCustomProperites() method, using the BaseConfigurationManager_populateCustomProperties2.rstp extension point.
-
Configure any applicable specifications with the appropriate ruleset extension point. (The base extension points are specification-based, not global.)
-
Deploy the cartridge or cartridges containing the ruleset, ruleset extension points, and specifications.
-
Call GetConfiguration.
GetConfiguration calls the populateCustomProperties() methods, and your rulesets run afterward, populating the customProperty element in the response. See "Customized Response" for more information.
Customized Response
Example 2-8 shows an excerpt from the Configuration.xsd file, which defines the customProperty element.
Example 2-8 customProperty
<xs:element name="customProperty" type="invprop:PropertyType" nillable="true" minOccurs="0" maxOccurs="unbounded"> <xs:annotation> <xs:documentation> Custom Properties added for the entity Assignment/Reference. </xs:documentation> </xs:annotation> </xs:element>
Example 2-9 shows an excerpt from the Property.xsd file, which defines the PropertyType structure. (The customProperty element references PropertyType in its definition.)
Example 2-9 PropertyType
<xs:complexType name="PropertyType"> <xs:annotation> <xs:documentation>PropertyType holds a single dynamic property as a name-value pair.</xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="name" type="xs:string" /> <xs:element name="value" type="xs:string" nillable="true" /> <xs:element name="action" type="invent:EntityActionEnum" minOccurs="0"> <xs:annotation> <xs:documentation> Action holds the property Action which indicates whether the property needs to be added/deleted/updated. Valid values for this element are defined by EntityActionEnum. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType>
Example 2-10 shows the structure that ends up in the response when customizations are in place.
Example 2-10 Response
<con:customProperty> <invprop:name>customDataName1</invprop:name> <invprop:value>customDataValue1</invprop:value> <invprop:action><invprop:action> </con:customProperty> <con:customProperty> <invprop:name>customDataName2</invprop:name> <invprop:value>customDataValue2</invprop:value> <invprop:action><action> </con:customProperty> <con:customProperty> <invprop:name>customDataName3</invprop:name> <invprop:value>customDataValue3</invprop:value> <invprop:action><invprop:action> </con:customProperty>
GetConfigurationDifferences
The GetConfigurationDifferences operation compares two versions of a service, pipe (representing a pipe or channelized connectivity), logical device, logical device account, network, or place configuration and returns the differences. The type of configuration compared is based on a search option specified in the request. A successful response returns the differences between properties (attributes and characteristics); differences between configuration items, including any assigned or referenced resources; and the differences between any child entities and their child configurations. For example, Figure 2-10 shows the data that is retrieved and compared, in dark gray, for a requested configuration (service, logical device, logical device account, network, pipe (representing a pipe or channelized connectivity), or place) comparison. You can customize GetConfigurationDifferences to return additional information. See "Customizing GetConfigurationDifferences" for more information.
Figure 2-10 Example Service Configuration Differences
![Description of Figure 2-10 follows Description of Figure 2-10 follows](img/wsv_sf_get_config_diffs_rtn.gif)
Description of "Figure 2-10 Example Service Configuration Differences"
Note:
GetConfigurationDifferences calls GetConfiguration, which returns the properties (attributes and characteristics) for all resources, but GetConfigurationDifferences does not compare the returned properties for the resources.
getConfigurationDifferencesRequest
This section describes getConfigurationDifferencesRequest, in which you specify a search option that tells GetConfigurationDifferences which type of configuration versions to compare and return. In the request, you can also specify additional request options that tell GetConfigurationDifferences what data to include in the response, or to omit from the response.
Request Search Options
In getConfigurationDifferencesRequest, you specify a search option that indicates the type of configuration versions. The search options, which are defined in the ConfigurationMessages.xsd schema file, are listed and described in Table 2-3.
Table 2-3 GetConfigurationDifferences Search Options
Search Option | Description |
---|---|
BusinessInteractionConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this business interaction, based on the specified business interaction ID or external ID representing a business interaction. This search option also finds the differences between two configuration versions associated with any child business interactions. |
ServiceConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this service, based on the specified service ID or external ID representing a service. This search option also finds the differences between two configuration versions associated with any child services. |
ConnectivityConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this pipe, based on the specified pipe ID (representing a pipe or channelized connectivity). This search option does not find the configuration differences for child pipes. |
LogicalDeviceConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this logical device, based on the specified logical device ID. This search option does not find the configuration differences for child logical devices because logical devices cannot have a parent/child relationship. |
LogicalDeviceAccountConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this logical device account, based on the specified logical device account ID. This search option does not find the configuration differences for child logical device accounts because logical device accounts cannot have a parent/child relationship. |
NetworkConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this network, based on the specified network ID. This search option does not find the configuration differences for child networks because networks cannot have a parent/child relationship. |
PlaceConfigurationDifferencesSearchOption |
GetConfigurationDifferences finds the differences between two configuration versions associated with this place, based on the specified place ID. This search option also finds the differences between two configuration versions associated with any child places. |
All search options inherit from the abstract ConfigurationDifferencesSearchOption, and all entity-specific search options inherit from the abstract EntityConfigurationDifferencesSearchOption, as shown in Figure 2-11.
The request must specify one of the following:
-
Business interaction ID
-
Entity ID
-
External ID for a business interaction
-
External ID for a service entity
In the above list, the entity ID can be for a service, pipe (representing a pipe or channelized connectivity), logical device, logical device account, network, or place entity. However, the external ID for an entity can only be for a service entity.
Target and Source Configuration Versions
ConfigurationDifferencesEntitySearchOption, from which all search options inherit, defines the following:
-
Target configuration version
-
Source configuration version
The target and source configuration versions indicate the configuration versions to compare. The target configuration is the root of the comparison. Depending on what is specified in the request, the operation does the following:
-
If the request specifies both the target and source configuration versions, the operation compares the two configuration versions.
-
If the request specifies only a target configuration version, the operation compares the specified target configuration version to a defaulted source configuration version. In this scenario, the source configuration version defaults to the latest non-cancelled configuration version that precedes the specified target configuration version.
-
If the request specifies neither, the operation compares a defaulted target configuration version to a defaulted source configuration version. In this scenario, the target configuration version defaults to the latest non-cancelled configuration version, and the source configuration version defaults to the latest non-cancelled configuration version that precedes the defaulted target configuration version.
-
If the request specifies only a source configuration version (which is not recommended), the operation compares a defaulted target configuration version to the specified source configuration version. In this scenario, the target configuration defaults to the latest non-cancelled configuration version that follows the specified source configuration version, if it exists. If the operation is unable to default the target configuration version, the response returns an error.
Request Search Option Examples
Example 2-11 shows getConfigurationDifferencesRequest with a search option of BusinessInteractionConfigurationDifferencesSearchOption in bold. The elements below the search option show the specified business interaction ID to search for.
This request example also shows how you can specify an external ID for a business interaction to search for. In the example, these elements are commented out because you can only specify one or the other when using this search option.
Example 2-11 getConfigurationDifferencesRequest
<con:getConfigurationDifferencesRequest>
<com:header/>
<con:searchOptions
xsi:type="con:BusinessInteractionConfigurationDifferencesSearchOption"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<con:interaction xsi:type="bus:BusinessInteractionType">
<bus:header>
<bus:id>123456</bus:id>
<!--
<bus:externalIdentity xsi:type="invent:ExternalIdentityType">
<invent:externalObjectId>9876543</invent:externalObjectId>
</bus:externalIdentity>
-->
</bus:header>
</con:interaction>
</con:searchOptions>
</con:getConfigurationDifferencesRequest>
Example 2-12 shows getConfigurationDifferencesRequest with a search option of ServiceConfigurationDifferencesSearchOption in bold. The elements below the search option show the specified service ID to search for. In this example, where the search option inherits from the EntityConfigurationDifferencesSearchOption, the request also specifies a source configuration version and a target configuration version.
Example 2-12 getConfigurationDifferencesRequest
<con:getConfigurationDifferencesRequest>
<com:header></com:header>
<con:searchOptions
xsi:type="con:ServiceConfigurationDifferencesSearchOption"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<con:service xsi:type = "ser:ServiceCriteriaType">
<ser:serviceId>2468</ser:serviceId>
</con:service>
<con:targetConfigurationCriteriaType
xsi:type="conf:ConfigurationCriteriaType">
<conf:configurationVersionNumber>2</conf:configurationVersion
Number>
</con:targetConfigurationCriteriaType>
<con:sourceConfigurationCriteriaType
xsi:type="conf:ConfigurationCriteriaType">
<conf:configurationVersionNumber>1</conf:configurationVersion
Number>
</con:sourceConfigurationCriteriaType>
</con:searchOptions>
</con:getConfigurationDifferencesRequest>
Additional Request Options
In getConfigurationDifferencesRequest, you can also specify the following options. If an option is not specified in the request, the operation uses the default value.
-
includeConfigItemDifferences
-
When set to true, the response includes changes on the configuration item itself. For example, adding or removing configuration items.
-
When set to false (the default), the response includes only changes on the resources.
-
-
includeChildConfigDifferences
-
When set to true, the response includes differences for child configurations referenced or assigned to a configuration item on a parent configuration. For example, when a resource-facing service (RFS) is assigned on a customer-facing service (CFS).
-
When set to false (the default), the response does not include these differences.
-
-
includeActionPerformedInTargetVersion
-
When set to true, the response includes the actionPerformedInTargetVersion element within the target configuration item differences. The actionPerformedInTargetVersion element is a Boolean value in the response; when true is returned, it indicates the action taken was performed in the target version; when false is returned, it indicates the action taken was performed in the source version.
For example, when comparing version 1 (source) and version 4 (target), where versions 2 and 3 are not cancelled, and resource A is assigned in version 1: If resource A is modified in version 3, actionPerformedInTargetVersion is set to false; but if resource A is modified in version 4 (the version to compare), actionPerformedInTargetVersion is set to true.
-
When set to false (the default), the response does not include the actionPerformedInTargetVersion element within the target configuration item differences.
-
-
includeTarget
-
When set to true (the default), the response includes the target configuration.
-
When set to false, the response does not include the target configuration.
Note:
The includeTarget option takes precedence over the returnTargetWhenNoChange option. For example, if returnTarget is true and returnTargetWhenNoChange is false, and the configurations versions being compared are the same, the response includes the target configuration.
-
-
includeSource
-
When set to true (the default), the response includes the source configuration.
-
When set to false, the response does not include the source configuration.
-
-
returnTargetWhenNoChange
-
When set to true, and the versions being compared are the same, the response returns an action of Unchanged and populates the target configuration; the source configuration is not populated.
-
When set to false (the default), and the versions being compared are the same, the response returns an action of Unchanged and populates neither configuration (target or source).
-
-
includeTags
-
When set to true, the response includes tags on configuration items, with the tag name and description populated.
-
When set to false (the default), the response does not include tags on configuration items.
For information about tags, see the Design Studio Help.
-
-
includeTagsOtherInfo
-
When set to true, tag name, description, and otherInformation are populated.
-
When set to false (the default), tag name and description are populated; otherInformation is not populated.
Note:
The includeTagsOtherInfo option is only applicable when includeTags is true.
For information about tags, see the Design Studio Help.
-
-
includeNetworkTargets
-
When set to true, the response includes network targets.
-
When set to false (the default), the response does not include network targets.
For information about network targets, see UIM Concepts.
-
Additional Request Options Example
Example 2-13 shows getConfigurationRequest with the additional request options.
Example 2-13 getConfigurationDifferencesRequest
<con:getConfigurationDifferencesRequest> <com:header></com:header> <con:searchOptions> . . . </con:searchOptions> <con:includeConfigItemDifferences>true</con:includeConfigItemDifferences> <con:includeChildConfigDifferences>true</con:includeChildConfigDifferences> <con:includeActionPerformedInTargetVersion>true</con:includeActionPerformedInTargetVersion> <con:includeTarget>true</con:includeTarget> <con:includeSource>true</con:includeSource> <con:returnTargetWhenNoChange>true</con:returnTargetWhenNoChange> <con:includeTags>true</con:includeTags> <con:includeTagsOtherInfo>true</con:includeTagsOtherInfo> </con:getConfigurationDifferencesRequest>
GetConfigurationDifferences Logic Flow
Figure 2-12 shows what occurs when the GetConfigurationDifferences operation is called.
The first two boxes in Figure 2-12 represent functionality that is only performed when applicable, depending on what is specified in the request. For example, if the request specifies a target configuration version, the logic flow would start with Determine Source Configuration Version, and if the request specifies a target configuration version and a source configuration version, the logic flow would start with Get Source Configuration Version.
Figure 2-12 GetConfigurationDifferences Logic Flow
![Description of Figure 2-12 follows Description of Figure 2-12 follows](img/wsv_sf_get_config_diffs.gif)
Description of "Figure 2-12 GetConfigurationDifferences Logic Flow"
If the request specifies a business interaction ID or an external ID for a business interaction, the operation retrieves and compares any associated service configurations with their previous configuration version.
Child Configurations
If the configuration has a child configuration, and includeChildConfigDifferences is set to true in the request, the operation also compares two versions of the child configuration and returns those differences as well. See the description of includeChildConfigDifferences in "Additional Request Options" for more information.
All configurations have a start date and an end date. The operation determines which child configuration versions to compare based on the start and end dates of the child configurations and the start and end dates of the parent configurations.
Specifically, when comparing parent configuration versions P.3 and P.2, the operation determines which child configurations through the following process:
-
Find the first child configuration starting on or after the start date of parent configuration version P.3 and before the start date (if any) of the next configuration version (P.4). If not found, find the first child configuration version starting before the start date of parent configuration version P.3.
-
Do the same for parent configuration P.2:
Find the first child configuration starting on or after the start date of parent configuration version P.2 and before the start date (if any) of the next configuration version (P.3). If not found, find the first child configuration version starting before the start date of parent configuration version P.2.
The following examples show how the operation determines which child configuration versions to compare. In the examples, the parent configuration is represented as P, and the child configuration is represented as C. Versions of the parent configuration are represented as P.1, P.2, and P.3, and versions of the child configuration are represented as C.1, C.2, and C.3.
Example 1
Figure 2-13 shows an example where the start date and end date of the child configuration are on or after the parent configuration start date.
Figure 2-13 Child Start Date Is After Parent Start Date
![Description of Figure 2-13 follows Description of Figure 2-13 follows](img/wsv_sf_getconfdiffs_cv_ex2.gif)
Description of "Figure 2-13 Child Start Date Is After Parent Start Date"
In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.
The process:
-
Starts with parent configuration version P.3, which has a start date of 7/15.
-
Looks for a child configuration version with a start date that is on or after 7/15.
-
Finds child configuration version C.3, which has a start date of 8/15.
-
Proceeds to parent configuration version P.2, which has a start date of 4/15.
-
Looks for a child configuration version with a start date that is on or after 4/15.
-
Finds child configuration version C.2, which has a start date of 5/15.
The operation determines that child configuration version C.3 is compared with child configuration version C.2.
Example 2
In this example, the start dates and end dates of the child configurations are both before and after the parent's configuration start dates, as shown in Figure 2-14:
Figure 2-14 Child Start Date Before and After Parent Start Date
![Description of Figure 2-14 follows Description of Figure 2-14 follows](img/wsv_sf_getconfdiffs_cv_ex5.gif)
Description of "Figure 2-14 Child Start Date Before and After Parent Start Date"
In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.
The process:
-
Starts with parent configuration version P.3, which has a start date of 7/15.
-
Looks for a child configuration version with a start date that is on or after 7/15, but does not find one.
-
Looks for a child configuration version with a start date that is before 7/15.
-
Finds child configuration version C.3, which has a start date of 6/15.
-
Proceeds to parent configuration version P.2, which has a start date of 3/15.
-
Looks for a child configuration version with a start date that is on or after 3/15.
-
Finds child configuration version C.1, which has a start date of 4/15.
The operation determines that child configuration version C.3 is compared with child configuration version C.1.
Example 3
In this example, the same child configuration version is applicable two versions of the parent configuration, as shown in Figure 2-15:
In this example, the operation is comparing configuration versions P.2 and P.3. Configuration P is a parent to child configuration C, so the operation must determine which versions of child configuration C to compare.
The process:
-
Starts with parent configuration version P.3, which has a start date of 7/15.
-
Looks for a child configuration version with a start date that is on or after 7/15, but does not find one.
-
Looks for a child configuration version with a start date that is before 7/15.
-
Finds child configuration version C.2, which has a start date of 3/15.
-
Proceeds to parent configuration version P.2, which has a start date of 4/15.
-
Looks for a child configuration version with a start date that is on or after 4/15, but does not find one.
-
Looks for a child configuration version with a start date that is before 4/15.
-
Finds child configuration version C.2, which has a start date of 3/15.
The operation determines that child configuration version C.2 is compared with the same child configuration version. In this scenario, the response returns an action of Unchanged and may populate the target configuration, depending on what is specified in the request for the returnTargetWhenNoChange option. See the description of returnTargetWhenNoChange in "Additional Request Options" for more information.
Overriding the Process Logic that Determines Child Configurations
The process logic that determines the child configuration versions to compare resides in the BaseConfigurationManager.getEffectiveChildConfiguration() method, and Oracle provides a base extension point that defines this method.
You can override the logic by writing a custom ruleset that contains custom code that retrieves the child configuration versions based on your business requirements. You can then configure the custom ruleset to run at the provided base extension point, resulting in the custom ruleset running instead of the BaseConfigurationManager.getEffectiveChildConfiguration() method. See UIM Developer's Guide for more information about rulesets and extension points.
You can find the BaseConfigurationManager_getEffectiveChildConfiguration base extension point in the UIM_SDK_Home/cartridges/base/ora_uim_baseextpts.jar file.
getConfigurationDifferencesResponse
getConfigurationDifferencesResponse returns a varying level of information based on the options specified in the request, as described in "Additional Request Options".
At a high-level, the response returns the following:
-
Configuration differences []
-
Configuration item difference []
-
Target configuration
-
Configuration specification
-
Configuration item []
-
-
Source configuration
-
Configuration specification
-
Configuration item []
-
-
GetConfigurationDifferences returns an error when:
-
The request specifies a search option other than the valid search options listed in Table 2-3.
-
The request does not specify a business interaction ID, entity ID, external ID for a business interaction, or external ID for an entity that the search option needs to perform the search.
-
The operation cannot find the business interaction ID, entity ID, external ID for the business interaction, or external ID for the service entity specified in the request.
-
The request specifies a target configuration version and a source configuration version, and the source configuration version number is greater than the target configuration version number.
-
The request specifies a source configuration version and the operation is unable to determine a target configuration version.
-
The request specifies a target configuration version that is cancelled.
-
The request specifies a source configuration version that is cancelled.
GetConfigurationDifferences request is for configuration versions in the Designed or Issued state. For instance, the operation returns messages in the following scenarios:
-
If the source or target configuration version requested is invalid, the following error message is given: “Invalid source and target versions. Source and target must be greater than 0, Source Version number cannot be greater that Target Version number. Source is 3 and Target is 0."
-
If the configuration version requested is in the In Progress, Cancelled, Completed, or Pending Cancel state, for example, the following warning message is given and the operation continues processing: “Inventory Configuration 123 is in Completed state. This operation has been requested on a configuration version that is in state that is not designed for this Web Service. Results may be inaccurate."
-
The operation is intended for the requested configuration version to be compared to the previous Completed version. If no previous Completed configuration version exists, or no previous configuration version exists at all, the following message is given and the operation continues processing: “A previous configuration version does not exist."
-
The operation is intended for the requested configuration version to be compared to the previous Completed version. If no previous Completed configuration version exists, or no previous configuration version exists at all, the following informational message is given and the operation continues processing: “A previous configuration version does not exist."
Customizing GetConfigurationDifferences
For your implementation, you may need more information than GetConfigurationDifferences returns. In such scenarios, you can customize GetConfigurationDifferences to return additional information.
Customizing GetConfigurationDifferences is similar to customizing GetConfiguration. See "Customizing GetConfiguration" for more information.
After you customize GetConfigurationDifferences to return any additional data you may need, your code that calls GetConfigurationDifferences needs to be customized to compare the versions that are returned in the response to determine the differences.
UpdateConfiguration
The UpdateConfiguration operation transitions a service or service configuration through its respective life-cycle states.
To transition a service, the request must specify the service action and service ID.
The valid service actions are:
-
COMPLETE
-
CANCEL
-
DISCONNECT
-
SUSPEND
-
RESUME
To transition a service configuration, the request must specify the service configuration action and one of the following:
-
Service ID
-
Service configuration ID
-
Service ID and service configuration version number
If the first option is specified (service ID), the operation transitions the latest active service configuration.
The valid service configuration actions are:
-
APPROVE
-
ISSUE
-
CANCEL
-
COMPLETE
updateConfigurationResponse
updateConfigurationResponse includes a success or failure message regarding the update to transition the service or service configuration. The response returns a varying level of information based on the <responseLevel> value the request specifies. See "ResponseLevel Element" for more information.
UpdateConfiguration returns an error when:
-
The request specifies an invalid service action or service configuration action.
-
The request specifies invalid data for service ID, service configuration ID, or service configuration version number.
Customizing the Web Service Operations
You must customize the ProcessInteraction operation, and you can optionally customize the GetConfiguration and GetConfigurationDifferences operations. See the following sections for more information:
Extending Web Service Requests and Responses
You can extend web service requests and responses by extending GenericHandler.class, which supports the use of SOAP handlers and which is used by the UIM Service Fulfillment Web Service.
To extend a web service request or response:
-
In Design Studio, create a custom Inventory project.
-
Within your custom Inventory project, create a custom Java class that does the following:
-
Imports javax.xml.rpc.handler.GenericHandler.class (include the jaxrpc.jar if necessary)
-
Extends GenericHandler
-
Overrides the handleRequest() or handleResponse() methods, or both, per your specific business requirements
-
-
Build your custom Inventory project.
A successful build of your custom Inventory project creates a deployable custom cartridge, which is a JAR file with the same name as your Inventory project.
-
Deploy your custom cartridge into your UIM traditional environment. If you use UIM cloud native, see "Deploying Cartridges" in UIM Cloud Native Deployment Guide.
-
Update the deployment plan:
-
For the UIM cloud native deployment, see "Customizing Images" in UIM Cloud Native Deployment Guide.
-
For the traditional deployment, update the UIM_Home/app/plan/Plan.xml file to include the following:
-
Add the following <variable> elements under the <variable-definition> tag to define the variables of HandlerName and HandlerClassName, and to define their respective values, which is your custom Java class name and fully qualified custom Java class name:
<variable> <name>HandlerName</name> <value>MyCustomHandler</value> </variable> <variable> <name>HandlerClassName</name> <value>oracle.communications.webservice.ws.MyCustomHandler</value> </variable>
-
Add the following <variable-assignment> elements under the <module-descriptor> element, as shown here:
<module-override> <module-name>InventoryWS.war</module-name> <module-type>war</module-type> ... ... <module-descriptor external="true"> <root-element>webservices</root-element> <uri>WEB-INF/webservices.xml</uri> <!-- ==================== START OF NEW CONTENT ==================== --> <variable-assignment> <name>HandlerName</name> <xpath> /webservices/webservice-description/ [webservice-description-name= "oracle.communications.inventory.webservice.ws.InventoryWSPortImpl"] /port-component/ [port-component-name="InventoryWSHTTPPort"]/handler/handler-name </xpath> </variable-assignment> <variable-assignment> <name>HandlerClassName</name> <xpath> /webservices/webservice-description/ [webservice-description-name= "oracle.communications.inventory.webservice.ws.InventoryWSPortImpl"] /port-component/ [port-component-name="InventoryWSHTTPPort"]/handler/[handler-name="MyCustomHandler"]/handler-class </xpath> </variable-assignment> <!-- ==================== END OF NEW CONTENT ==================== --> </module-descriptor> ... ... </module-override>
-
-
These additions to the Plan.xml file results in the following being added to the webservice.xml file at run-time:
<handler> <handler-name>MyCustomHandler</handler-name> <handler-class>oracle.communications.webservice.ws.MyCustomHandler </handler-class> </handler>
-
-
In the UIM traditional deployment, redeploy the inventory.ear file.
This action redeploys the UIM Service Fulfillment Web Service with the updated Plan.xml file.
In the UIM cloud native deployment, rebuild the image with the modifications performed in the previous step. For details, see "Customizing Images" in UIM Cloud Native Deployment Guide. Also, create the instance with a generated image.
Additional Information
For more information about SOAP handlers, see "Creating and Using SOAP Message Handlers" in Fusion Middleware Developing JAX-RPC Web Services for Oracle WebLogic Server.
Deploying, Testing, and Securing the Web Service
Information about deploying, testing, and securing the web service is described in "Deploying, Testing, and Securing UIM Web Services".