Your SlideShare is downloading. ×
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
 Guidelines and Best Practices for OSS Solution Development
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Guidelines and Best Practices for OSS Solution Development

840

Published on

Guidelines and Best Practices for OSS Solution Development

Guidelines and Best Practices for OSS Solution Development

Published in: Technology, Business
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
840
On Slideshare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
0
Comments
0
Likes
2
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. GUIDELINES AND BEST PRACTICES OSS Solution Development January 2013
  • 2. GUIDELINES AND BEST PRACTICES Page 1 Guidelines and Best Practices OSS Solution Development, Release 7.2.2 Copyright © 2005, 2012, 2013 Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
  • 3. GUIDELINES AND BEST PRACTICES Page 2 Contents Introduction........................................................................................................7 Purpose................................................................................................................7 Mobile GSM Solution as a Baseline for OSS Solution Development .......7 Concept-to-Activation and Application Specific Terminology..............7 Service Fulfillment Solution Architecture and OSS Suite Applications ....7 Service Fulfillment Components Associated to OSS Applications.......8 Application Integration Architecture.....................................................8 OSM Central Order Management..........................................................8 OSS Suite Application Roles and Integration Interfaces ........................9 OSM Automated Tasks with JMS Transport Web Services ............10 OSM Automated Tasks with non-JMS Transport.............................10 OSM Manual Tasks with HTTP Transport Web Services...............11 OSM Service Order Management.............................................................11 Using OSM to Provision Multiple Types of Services........................11 About Services ........................................................................................11 About Customer Order to OSM Service Order Transformation ...12 About OSM Service Actions.................................................................15 About OSM Service Order Orchestration..........................................16 Modeling Services and Resources in OSS Suite Applications ..............17 Modeling Services and Configurations................................................17 Modeling Service Features.....................................................................18 Modeling Third Party Services..............................................................19 Modeling Geographically Designated Resources in UIM ................19 Managing Pooled Resource Capacity in UIM ....................................20 Managing Owned Telephone Number Capacity in UIM.................20 Managing Port-Out Telephone Numbers in UIM ............................21 Managing Port-In Telephone Numbers in UIM................................21 Managing Subscribers in UIM ..............................................................21 Managing Subscriber Resources in UIM.............................................22 Modeling Modular Services and Resources ........................................22 Designing Service Configurations.............................................................22 Automated Design in UIM ...................................................................22 Manual Design in UIM..........................................................................23 Automated Design Task to Use Other Systems ................................23 Manual Design Task to Use Other Systems.......................................23 OSM Technical Orders, Actions, and Delivery Plans ...........................24 Modeling OSM Technical Order Work Dependencies ....................24 Grouping Related Work Items into Single Order Components......24 Grouping Work per Activation System...............................................24 ASAP Service Activation............................................................................25 Abstracting Services from Network Technology and Software ......26 Decoupling Service Order Management from ASAP.......................26 Decoupling ASAP Service Model from Vendor/Software Loads..26
  • 4. GUIDELINES AND BEST PRACTICES Page 3 GSM Solution Service and Network Cartridge Design Goals.........26 ASAP Service Model Design Patterns .....................................................27 Designing ASAP Service Cartridge Service Actions..........................27 Designing ASAP Service Cartridge Atomic Actions.........................27 Designing ASAP Service Cartridge Action Processors.....................28 Java Guidelines for ASAP..........................................................................29 Propagating Updates to Customer Orders ..................................................30 Handling Errors in OSM Service Orders ................................................30 Retrying Current Activity ......................................................................31 Retrying the Failed Activity...................................................................31 Resuming After Resolving Errors........................................................31 Triggering Customer Order Fallout.....................................................32 Canceling a Service Order.....................................................................32 Packaging an OSS Solution............................................................................32 OSS Solution Development Desktop Tools and Applications.................32 Software Requirements...............................................................................33 Preparing the Design Studio Workspace.................................................34 Collaborating in Teams...................................................................................34 Executing Tests................................................................................................34 Developing Orchestration Cartridges...........................................................35 Designing OSM Cartridges........................................................................35 Order Template.......................................................................................35 Cartridge Separation and Packaging.....................................................35 OSM Order Recognition Rules and Relevancy ......................................36 Recognition and Relevancy in the Mobile GSM Solution................37 Order Recognition Rules in Multiple OSM Implementations.........37 Testing XQuery Scripts..............................................................................38 Testing Customer Order to Service Order Transforms....................38 Testing Order Item Specification – Order Action ............................38 Testing Automation Scripts ..................................................................38 Important OSM URLs ...............................................................................38 OSM Tips, Tricks, and Pitfalls ..................................................................38 Extending the Mobile GSM Solution...........................................................40 Analyzing Extension Requirements..........................................................40 Creating New Types of Services Using the Reference Implementation .41 Creating New Service Actions Using the Reference Implementation.....41 Actions in the Service Order .....................................................................41 Creating a New Action in the Data Schema.......................................41 Updating the OSM Order Item Specification ....................................41 Updating the OSM Order Component Specification .......................41 Updating OSM Orchestration components .......................................41 Updating OSM Manual Tasks...............................................................42 Updating OSM Automated Tasks........................................................42 Updating OSM XQuery Scripts............................................................42 Creating New Sample Orders to Test New Service Actions............42 Extending Shared Libraries............................................................................42 Updating the GSMLibraryModule.xqy script.....................................42 Updating the XML Schema ..................................................................42 Updating the GSMDataMapping.xml..................................................42 Actions in the Technical Order.................................................................42 Calculating Technical Actions...............................................................43 Adding Technical Actions in the Data Schema .................................43
  • 5. GUIDELINES AND BEST PRACTICES Page 4 Updating Order Item Specification......................................................43 Updating the Orchestration Components ..........................................44 Creating New OSM Activation Tasks .................................................44 Creating New OSM Manual Tasks.......................................................44 Update OSM XQuery Scripts...............................................................44 Actions in the Inventory ............................................................................44 Actions in the Activation Order ...............................................................44 Activating Services on the Network using ASAP.......................................44 Activating HLR Devices ............................................................................44 Activating VMS Devices............................................................................45 Activating Other Types of Devices..........................................................45 Extending the Solution Installer....................................................................45 Developing Product Variations of Services.................................................46 Customizing the Mobile GSM Solution.......................................................46 Localizing Telephone Numbers................................................................46 Localizing Geographic Addresses.............................................................46 OSS Solution Development Methodology ..................................................47 Roles and Skills Required for OSS Solution Development ..................47 Engagement Model for OSS Solution Development ............................48 Project Template .........................................................................................49 Document Artifacts ....................................................................................49 Design Template .........................................................................................49 Performance Considerations..........................................................................52 Oracle Database RAC.................................................................................52 Design Intelligence versus Transaction Throughput Tradeoffs...........52 Resource Facing Service Modeling Approach Tradeoffs......................53 Transaction Boundary Tradeoffs..............................................................54 Security Considerations...................................................................................54 Selecting an Authentication Provider.......................................................54 Enabling Transport Layer Security...........................................................54 Web Services Security Policy.....................................................................55 Maintaining an OSS Solution.........................................................................55 Upgrading Cartridges..................................................................................55 Deploying OSS Suite Applications................................................................56 Database Server Deployment....................................................................56 Deploying OSS Applications into a Single Database........................56 Deploying OSS Applications into a RAC Database..........................56 Application Server Deployment................................................................56 Deploying OSS Applications to a Single Domain .............................57 Deploying OSS Applications to Multiple Domains ..........................57 Deploying OSS Applications to Application Server Clusters ..........58 Deploying the Mobile GSM Solution ......................................................59 Configuring the Mobile GSM Solution Installer................................60 Troubleshooting...............................................................................................60 Troubleshooting ASAP..............................................................................60 Initialize the Environment ....................................................................60 Run asap_utils for a List of Existing Work Orders...........................60 ASAP Logging.............................................................................................62 Troubleshooting OSM ...............................................................................62 OSM Logging..........................................................................................62 OSM Frequently Encountered Problems ...........................................63 Troubleshooting UIM ................................................................................64
  • 6. GUIDELINES AND BEST PRACTICES Page 5 UIM Logging...........................................................................................64 Troubleshooting Web Services .................................................................64 Logging JSM Messages ..........................................................................64 WebLogic Infrastructure Logging........................................................65 Troubleshooting Order Execution...........................................................65 Correlating between Orders..................................................................65 Correlating between Products, Services, Resources..........................66
  • 7. GUIDELINES AND BEST PRACTICES Page 6
  • 8. GUIDELINES AND BEST PRACTICES Page 7 Guidelines and Best Practices OSS Solution Development Introduction This document is intended to present an architectural recommendation for provisioning Operations Support Systems (OSS) solutions, along with a set of guidelines and best practices for developing and deploying such solutions. The topics covered by this document range in detail from solution architecture and solution development methodology to troubleshooting. Purpose The content in this document is based on experience gained during the development of the mobile GSM solution for service provisioning and the OSS Suite of applications for service fulfillment, as well as anecdotal experience from developing other solutions on these applications. This document is expected to be updated to reflect the lessons learned as experience is gained. The purpose is to share knowledge with solution developers to accelerate their projects, improve the quality of implementation, and provide insights into how to get the most value from the software. Mobile GSM Solution as a Baseline for OSS Solution Development Any OSS service provisioning solution can use the mobile GSM solution as a reference implementation. The reference implementation provides an architectural foundation and concrete implementations of the patterns to build on. Although the reference implementation does not satisfy every architectural problem, it provides a solid basis. Table 1 lists the reference implementation mobile GSM solution components. Table 1 – Reference Implementation Mobile GSM Solution Components Solution Component License Status OSM cartridges for mobile solution unlicensed UIM technology pack for GSM licensed ASAP cartridge for Ericsson HLR licensed ASAP cartridge for Comverse VMS licensed ASAP cartridge for mobile solution unlicensed Mobile solution installer unlicensed For more information about the mobile GSM solution, see Oracle Communications OSS Mobile Solution Uptake Guide. Also each OSS Suite application, including Design Studio, has a Concepts and Developer’s Guide that you can reference for more information about using the specific application for solution development. Concept-to-Activation and Application Specific Terminology Table 2 lists and describes the types of fulfillment orders using Concept-to-Activate (C2A) and application specific terminology. Table 2 – Types of Orders for Fulfillment Concept-to-Activate Terminology Application Terminology Order Contents Customer Order Sales Order (Siebel, AIA, OSM COM), Provisioning Order (AIA) product actions Service Order Provisioning Order (OSM SOM) CFS actions Technical Order Delivery Order (OSM SOM) RFS actions or resource actions Activation Order Work Order (ASAP) RFS actions or resource actions This document uses the C2A terminology for conceptual descriptions and application specific terminology when describing implementation artifacts. Service Fulfillment Solution Architecture and OSS Suite Applications
  • 9. GUIDELINES AND BEST PRACTICES Page 8 Figure 1 shows the service fulfillment solution and where OSS suite applications reside within it. Figure 1 – Fulfillment Solution As part of the solution architecture for service fulfillment, the provisioning function is the responsibility of the OSS suite of applications. Order and Service Management (OSM) is responsible for the orchestration of service orders to execute the processes and activities of provisioning. Unified Inventory Management (UIM) is responsible for the inventory (for example, life cycle management, capacity management, configuration management) of services and resources, and the design and assign function. ASAP is responsible for the activation of the services in the network by configuring the network elements that are under its management. Design Studio is responsible for the definition time user experience for developing service provisioning solutions. Service Fulfillment Components Associated to OSS Applications The following sections describe fulfillment applications and components associated with OSS suite applications. Application Integration Architecture Application Integration Architecture (AIA) provides a framework for integrating application components into solutions that implement business processes that perform work across distinct business functions in an enterprise. This mechanism is used for architectural consistency, and to take advantage of the domain knowledge and solution design expertise that have been built into Process Integration Packs (PIPs). For a detailed description of the role of AIA, refer to the Rapid Offer Design and Order Delivery (RODOD) white paper. The service provisioning solution accepts an AIA Provisioning Order EBM, which is submitted from OSM Central Order Management (COM) to OSM Service Order Management (SOM). This EBM is immediately transformed into a service order for OSM SOM. OSM Central Order Management CRM (customer order management) submits a customer order (sales order) that contains actions on product offerings that will be fulfilled after the order capture process is completed. OSM, in the role of Central Order Management (COM), orchestrates the fulfillment of this customer order. AIA integrates between CRM and COM, as well as between COM and other BSS/OSS applications.
  • 10. GUIDELINES AND BEST PRACTICES Page 9 The fulfillment of the customer order involves activities like the following for the relevant product offerings: 1. Synchronize the customer account information between CRM and other systems that require customer account information, like billing. 2. Provision services in the network as a result of fulfilling the actions on product offerings. The SOM performs this function. 3. Ship physical goods to the customer through Supply Chain Management (SCM). 4. Notify billing that actions on product offerings have been fulfilled. For each product offering, CRM can be notified with status updates and service design details resulting from provisioning. See Propagating Updates to Customer Order for more information. For a detailed description of the role of OSM COM, see the Rapid Offer Design and Order Delivery (RODOD) white paper. OSS Suite Application Roles and Integration Interfaces The OSS suite applications, including OSM, ASAP, UIM, and Design Studio, are responsible for the service fulfillment business function. These applications have the following roles:  Service Order Management (SOM): the responsibility of OSM. This role includes the orchestration of service orders to execute the processes and activities of provisioning.  Inventory Management: the responsibility of UIM. This role includes life cycle management, capacity management, and configuration management of services and resources. This also includes the ‘design and assign’ function.  Technical Order Management (TOM): the responsibility of OSM. This role includes the orchestration of technical orders to execute the processes and activities for services in the network according to what was designed. This is a function that is delegated from the provisioning process that is managed by SOM.  Activation: the responsibility ASAP. This role includes configuring the network elements that it manages.  Service Definition: the responsibility of Design Studio. This role includes the definition time user experience for developing service provisioning solutions. Figure 2 shows the OSS suite application roles. Figure 2 – OSS Suite Application Roles
  • 11. GUIDELINES AND BEST PRACTICES Page 10 Although OSM performs multiple roles, for example COM, SOM, and TOM, you do not require a separate deployment for each role. A single deployment of OSM can perform multiple roles. Naming these roles helps to clarify the OSS suite application roles and responsibilities and do not imply any deployment configuration. The OSS suite applications are integrated directly to take advantage of definition time synergies within Design Studio and run time synergies between the application servers. AIA integrates applications that perform distinct business functions; usually such applications are not developed to work together. The OSS suite applications work together, and are often sourced as a single pre-integrated service fulfillment system. At definition time, these synergies are seen in the manner in which products, services, and resources are defined across OSM, UIM, and ASAP to support the end-to-end provisioning process. These definitions are then built into implementation artifacts that are deployed to the run time environment, where the process integration takes advantage of the application programming interface (APIs) to support both automated and manual OSM tasks in the work flow. Figure 3 shows the OSS suite application integration interfaces. Figure 3 – OSS Application Integration Interfaces OSM Automated Tasks with JMS Transport Web Services OSM automated tasks require reliable asynchronous delivery of messages to guarantee that requests and replies are handled properly by both the sender and receiver. Automated tasks must be resilient to temporary server and network failures, so that processing can automatically resume upon recovery. The Java message service (JMS) provides the transport mechanism that meets these requirements. OSM automated tasks automatically invoke operations between OSS suite applications using the simple object access protocol (SOAP)/JMS Web Services. Asynchronous delivery in OSM also increases the volume of orders that can be run concurrently. A thread of execution is busy only while a request message is being produced and while a reply message is being consumed. During the period between the request and its corresponding reply, a thread is not blocked waiting; the thread that sent the request becomes available to perform other work within the server. This approach maximizes the work that OSM can perform and helps achieve higher scales of order throughput under load. There is no significant delay for calling operations using JMS transport compared to HTTP. The transactions performed by operations (application logic) typically outlast any delay caused by message transport overhead for non-trivial Web Service. Reliability and scalability are more important than the resulting delay. OSM Automated Tasks with non-JMS Transport Oracle recommends implementing an adapter when integrating with other applications outside the OSS suite applications that do not offer interfaces that use JMS transport. These adapters should wrap the foreign interface into one that is based on XML messages delivered over a JMS transport. For example, if a foreign application offers SOAP/HTTP Web Services, it is possible to implement a Message-Driven Bean (MDB) that accepts the same SOAP requests through a JMS Queue, calls the operation
  • 12. GUIDELINES AND BEST PRACTICES Page 11 synchronously on the foreign application through SOAP/HTTP, and sends the SOAP response or fault message to the JMS reply-to destination. Using this approach, automated tasks can use XQuery for producing request messages and consume response messages. JMS transport provides the benefits described in “OSM Automated Tasks.” OSM Manual Tasks with HTTP Transport Web Services OSM manual tasks can involve rules that invoke operations (for example, queries and calculations) on other applications to populate information to present, populate context information into links for browser navigation, and populate fields with values to submit on a form. These interactions are synchronous and message delivery can be less reliable because the human user is capable of retrying on failure. For these reasons, the OSS suite applications rely on SOAP/HTTP Web Services as the mechanism for manual tasks to invoke operations between applications. Use caution to avoid synchronously calling operations that perform lengthy transactions (for example, where the latency is greater than a second). High latency operations should be called asynchronously through JMS using an automation task, as described in “OSM Automated Tasks.” Automated tasks can be combined with manual tasks for human interaction in a work stream. OSM Service Order Management OSM, when performing in the role of SOM, receives a provisioning order containing the subset of a customer order that requires services to be provisioned. These actions on product offerings must be decomposed and transformed into actions on OSM customer facing services (CFSs). In the mobile GSM solution the reference implementation performs this decomposition and transformation in the order request processor (ORP), which pre-processes the inbound order, and produces an order in the OSM native format suitable for execution. This works best if OSM operates in both the COM and SOM roles, by having the task that is responsible for submitting the provisioning order immediately perform the customer order to service order transformation, so that a service order is received by SOM. This avoids performing two order transformations during one message exchange: once to transform the customer order (native format) from OSM COM into an AIA provisioning order, and once in SOM to transform the AIA provisioning order into a service order (native format) for OSM SOM. For more information, see “About Customer Order to OSM Service Order Transformation.” Using OSM to Provision Multiple Types of Services A single deployment of OSM SOM can provision multiple types of services where a service order carries order items with any mix of actions for any of those types of service. You can maintain separate deployments of OSM SOM so that each deployment is responsible for a distinct set of services. This can be required due to administrative, organizational, or regulatory reasons. In this situation, OSM COM is responsible for submitting separate provisioning orders to each OSM SOM deployment, such that each order would contain only product actions that can be provisioned by that particular deployment. About Services The service provisioning solution implements actions that are ordered for services. A service provides a communication subscription to a subscriber. The term CFS refers to a service, which is directly composed of products and offered for sale to customers. A CFS has the following qualities:  It delivers to a subscriber something of commercial value that is realized by the resources in the network of the service provider.  The subscription is visible and useful to the subscriber.  The subscription can stand on its own as a product offering without being bundled with another product offering to act as the container or vehicle. For example, call waiting cannot stand on its own as a service, but mobile (GSM) can. Features, options, or resources are more granular aspects of a service.
  • 13. GUIDELINES AND BEST PRACTICES Page 12 A CFS represents an abstraction of something provided in the network of value that a recipient would subscribe to use. A specification of a CFS would be defined to subsume every variation of that abstraction that shares the following qualities:  The service supports actions that can be ordered.  Each action is parameterized to reflect the ways in which it can vary – it has a signature.  Each action is provisioned through the same process and activities with little to no variation.  Each action is designed by producing a configuration using the same algorithms and policies.  The actions are realized by activating the same types of resources, including Resource Facing Services (RFSs), in the network. This rule of thumb is not strictly true in all cases. About Customer Order to OSM Service Order Transformation Product offerings are commercial bundles and variations of services and their features. The term “features” is used loosely to include supplemental services, bandwidth parameters, quality of service (QoS) parameters, resources, and child services. Features are like characteristics of the service configuration or entities (for example, resources, and services). Variations can be implemented by defining separate product specifications to set a parameter to a default value.
  • 14. GUIDELINES AND BEST PRACTICES Page 13 Figure 4 shows an example of product actions to server actions transformation. Figure 4 – Example Product to Service Transform On the left, the customer order is depicted using a numbering scheme that reflects the hierarchical structure of the order items. The root item 1 carries the New action for the Mobile Bundle product offering. The root item decomposes into the service action Add Mobile. The Mobile Bundle has descendants that contribute to parameters of the service action; these parameters control the features of the service. The 1.5 New Premium Internet Access product offering also exhibits another unique pattern of setting the GPRS QoS Profile number to 401. In this case there can be another product offering (for example, Basic Internet Access) that corresponds another level of the same QoS definition. This customer order transformation produces a service order containing actions on a service. The transformation is done in the Order Recognition Rule of the MobileGSMProvisioning order. Table 3 lists and describes the three files that are used during the transformation. Table 3 – Customer Order to OSM Service Order Transform Artifact Description MobileGSMResources/ resources/Specifications/MobileSpecifications.xml This file contains a list of supported products and their identifying information (as required by the transformation).  Unique identifier: This can be any value. It does not need to come from the enterprise business message (EBM). This is the key that links this product definition with the logic for processing it (as found in the GSMDataMapping.xml file).  fic and typecode: These should match the EBM line item and are used to distinguish between products. The fic should be edited to match a product class.  ExtensibleAttribute: This specifies which extensible attributes this product line carries. The name specified here should match exactly the name of the extensible attribute in the EBM.  CustomAttribute: This is used when there is information on a product line that is not stored in the extensible attributes. The name on this attribute is not used.  CustomerFacingServiceSpecification: This element can be ignored. It is not used at this time. To extend the mapping, you need to add product details to this file.
  • 15. GUIDELINES AND BEST PRACTICES Page 14 MobileGSMProvisioning-Orchestration / resources/xquery/MobileEBMPO_ORR_Transform.xqy This is the XQuery script that you run to do the transformation. The result of this transformation is found in the OSM order template as Transform/ServiceOrderItem. The generic ServiceOrderItem structure is specified as the Order Item Selector. The XQuery script loops through product order lines and processes them according to the strategy defined for it in the GSMDataMapping file. The script performs the following actions:  Uses the bundle definition (GSMDataMapping) to find the corresponding order line containing a product bundle.  Uses the bundle LineID to match potential child or grandchild products.  Finds the product order line representing the service and keeps the Line ID to find appropriate child products.  Runs through the following processing strategies and finds the products that fall into each category:  Boolean strategy: The presence of a product order line with this strategy transforms into a Boolean attribute. Call Waiting is an example. If that product is found, it is created in the ServiceOrderItem as a Boolean attribute.  Lookup strategy: This strategy is used for products that contain values that will be translated into the parameters of a service action. A SIM card product is an example. The SIM product line has an ICCID that becomes a parameter of the mobile service action. The data to be found is always in the ExtensibleAttribute section of the product order line and the value is populated on the service order.  Custom strategy: This strategy is used to extract data out of a product order line from some custom place. For the most part, relevant data is in the extensible attributes but there are exceptions. In Mobile, the TN is a good example. Service providers have traditionally preferred the TN to identify the product bundle, rather than to be stored in an extensible attributes. The TN is found instead on the order line containing the product bundle, and its value is located at OrderItemInstance/Identification/ID. The XQuery script also extracts data such as correlation ids, action codes, and so on, from the order line. To transform additional Mobile products or a set of products that follow the simple processing strategies supported by this XQuery script, you should not need to edit this file. MobileGSMResources/ resources/GSMDataMapping.xml This metadata drives the transformation logic. This file is where the following processing strategy for a product is defined:  bundle: This attribute has a product spec id that maps to the MobileSpecifications file and point to the correct product. Any other kind of transformation, such as action codes (DELETE on product becomes disconnect on service), is specified here.  Service: This attribute has a product spec id that maps to the MobileSpecifications file and points to the correct product. The service also contains the breakdown of processing strategies and which products fall into which category. The attribute names specified here should match the names of the elements that will be populated in the OSM service order. For example, “Class Of Subscriber” on the EBM (MobileSpecifications) populates the “classOfSubscriber” element on the OSM service order. To support another type of service, you need to add the specifics for that service. You should enhance this file, as opposed to creating a new one. The XQuery script should loop through the “bundle”
  • 16. GUIDELINES AND BEST PRACTICES Page 15 definitions in this file, thereby supporting more than one type of service. About OSM Service Actions An action on a service is a request that is captured on an order and is fulfilled by configuring the network to deliver the service. A service order can carry many such actions for provisioning – one action per order item. UIM processes these service actions to perform the design and assign function. ASAP also processes service actions to perform the activation function against the network. The intent of the reference implementation is to have the same OSM service abstraction (CFS) and service actions be understood by the ASAP and UIM applications for fulfillment (provisioning). A simple action is identified by a verb, such as Add, Change, and Disconnect. Sometimes an action has variants with different meanings, and these are identified by a verb phrase, such as Add Site, Add CE Router to Site, and Add Site to VPN. An action has a signature comprised of the following:  Input parameters: information that must be captured as input on the order to provide the details about what is requested to be provisioned in the network. These information elements can represent features, options, preferences, and identities or qualities that describe resources and RFSs that are relevant to the service.  Output parameters: information that is fed back to the original requester, after resource configuration in the network is designed or completed.  Configurations: information about how the service is to be configured in the network, which can involve resources, RFSs, and information that governs how they are configured to deliver the service to the subscriber according to its features, options, and preferences. You must determine what attributes, features, options, and resources related to the service should be transformed into input parameters that will be required from the customer or CSR or some function performed in the OSM COM central fulfillment orchestration prior to performing the provisioning function. You must clearly define input parameters so that CRM users can define product specifications and offerings by modifying such parameters. For example, the mobile GSM solution home location register (HLR) supports a global system for mobile communications (GSM) subscriber profile, which is identified by a profile number (for example, 43). This number corresponds to a collection of subscriber configuration information that is administered in the HLR in readiness (before provisioning subscribers). This configuration information defines the following:  A default feature set (for example, caller ID, call waiting, and so on) that is common for all subscribers who will use this profile.  A default set of Intelligent Network (IN) triggers, which are behaviors that are performed at specific events in the call flow. IN triggers enable the service provider to do things in real-time, such as check the subscriber's account balance as a condition of authorizing a call to be established and remain connected. The full set of technical descriptions for IN triggers to properly handle the behavior for every event in the call flow for a particular class of subscriber requires a large amount of modeling in the network. This level of abstraction should not be exposed to the CRM. The customer or CSR needs to know only the different sets of IN triggers in the GSM subscriber profiles. So the mobile GSM solution introduces a concept of class of subscriber (distinct from class of service, which refers to the traffic on the network), which refers to how the subscriber is to be charged for their service. This option has values like prepaid and postpaid that correspond to the specific set of IN triggers on the subscriber profile. Most parameters do not require the same degree of effort at the OSS layer to hide the network details. Many network parameters do not need an abstraction layer because they are customer-facing elements of the service (for example, call waiting). Some network concepts, such as SMS-MT and SMS-MO, are abstracted slightly for only SMS or Text Messaging, because exposing the terminate (receive) and originate (send) functions of SMS is not commercially desirable. You can determination this based on experience.
  • 17. GUIDELINES AND BEST PRACTICES Page 16 About OSM Service Order Orchestration Because the service order contains any number of order items, each with a service action whose provisioning activities (for example, design and assign tasks) can be different than the others, the solution uses orchestration to execute the service order, instead of relying on a static process definition. Orchestration analyzes the items of the service order to generate an orchestration plan. The order items are decomposed into order components, each of which becomes a function that is performed on a fulfillment target (an application) by a task or subprocess. Most functions are developed to handle a set of order items (usually all items on the service order) as a single activity, rather than using a separate activity (thread of execution) per order item, for improved efficiency and performance. Figure 5 shows a simplified view of the OSM activities involved in the SOM component of the service provisioning solution. The orange boxes are the high level fulfillment functions that make up the orchestration plan. Dependencies, granularity, and target systems are not included. The pale blue boxes are the processes that are executed for a function, and the purple boxes within are the automated tasks. For the most part, each of these tasks represents a message exchange (request/response) with another application component. Figure 5 – Orchestration Functions for Provisioning Table 4 lists and describes the orchestration functions for provisioning. Table 4 – Orchestration Functions for Provisioning (Detailed) Orchestration Function Purpose Activity Details Design design and assign Capture Interaction  Call captureInteraction on UIM to capture the actions and input parameters from the service order onto a business interaction Process Interaction  Call processInteraction on UIM to auto- design the service configurations  Enrich the service actions on the service order with the configuration information from UIM Approve design is done and approved Approve Interaction  Call updateInteraction in UIM to transition service configurations to approved Calculate Delivery Plan deliver design for implementation Issue Interaction  Call updateInteraction in UIM to transition service configurations to issued Calculate Delivery Plan  Calculate the technical order based on the service actions that have been enriched with configuration information Create Delivery Order  Submit the technical order to OSM SOM for
  • 18. GUIDELINES AND BEST PRACTICES Page 17 execution Activate activate services in network Activate  Call createOrderByValue on ASAP to submit the activation order for execution  Wait for events from ASAP to indicate whether order execution succeeded or failed Complete provisioning is complete Complete Interaction  Call updateInteraction in UIM to transition the business interaction to complete Figure 6 shows the logical progression a service order takes through the tasks. Figure 6 – Provisioning Activities The CalculateDeliveryPlan activity submits a technical order to OSM SOM for execution as a child of the service order. This extra degree of complexity is necessary to trigger another orchestration plan to be generated and executed based on the technical actions that are calculated from the design and assign sub-process. The configuration information that results from design and assign then drives the implementation activities that follow. In OSS Suite R1, the only mechanism in OSM SOM for generating an orchestration plan, while already executing an order, is to submit a child order. Modeling Services and Resources in OSS Suite Applications The OSM Service Order Management section describes how service actions are represented on a service order, and how they are decomposed from the product actions on a customer order. This section provides more detail about the inventory representation of services and resources, how the service actions are designed, and how these designs are used to realize the service in the network. Within inventory, a service action is “designed” during the provisioning process (within the context of fulfilling a service order that is being orchestrated as a part of fulfilling a customer order) to produce a pending configuration of a service – that is, a service configuration version that is not yet realized in the network. This pending configuration is the plan for what activities must be executed to realize the services in the network. Modeling Services and Configurations When defining a CFS, you must define at least one service configuration specification. The service configuration plans how various resources in the network must be configured to realize the service. A service specification can have multiple service configuration specifications that represent alternative types of solutions that you can design. For example, a Broadband Internet Access CFS can be provided by a DOCSIS service configuration or by a DSL service configuration, each representing how the service is realized by a particular network technology. A service configuration is composed of a tree of configuration items. The tree structure logically organizes the information. Usually, each subtree represents a grouping of closely related information. However, for some types of service, it can be advantageous for a subtree to represent something real within the network, like a site and its resources. A configuration item can be populated with one of the following options:  Assignment: An allocation of a resource or an RFS for use by the service.  Reference: Identification of a resource or an RFS for context.  Characteristics: Additional service-specific configuration information. Often when a resource is allocated, there is additional service-specific information that must be configured on that resource to activate it. It is preferable for such service-specific configuration information to be represented on the service configuration, and not on the resource, especially if the resource is reusable (for example, a DSL interface).
  • 19. GUIDELINES AND BEST PRACTICES Page 18 During the design process of provisioning a service action, an instance of the service configuration specification (called a service configuration version) is created in UIM. Instances of resources that are specified for the configuration items can be referenced by or assigned to the service, and tracked on the configuration. Characteristics in the configuration can be populated with values. The service configuration version, the characteristics, and associated resources (including RFSs) represent the design, as requested by an action on a service. For example, you can design a request to add mobile service (including the teleservices, bearer services, and calling features) by using a service configuration version containing configuration items and characteristics. Resources such as a SIM Card and MSISDN are assigned to the service. Resources such as HLR and voice mail server (VMS) are referenced by the service, and these are represented as configuration items on the service configuration version. Modeling Service Features The OSM Service Order Management section described how features, options, and preferences are modeled for a service with respect to the actions that are captured on a service order, and how those actions are decomposed from the product actions on a customer order. Collectively, these are all referred to as service features. There are several approaches to modeling service features in OSM. The use of each approach is outlined below, ordered by increasing modeling complexity: 1. Modeling characteristics of a service: Use this approach when a feature is best described by a small set of simple types and the values do not change over the life of the service instance. For example, the service provider who is delivering the service to the subscriber. 2. Modeling characteristics on a configuration item of the service configuration: Use this approach when a feature is best described by a small set of simple types and the values vary over the life of the service instance. For example, call waiting. 3. Modeling a resource: Use this approach when a feature is best described by a resource entity (for example, a logical device) and its relationships to other entities in the inventory. The life cycle of the resource may or may not be bound to the service; it may or may not be shared across multiple services. The resource can be referenced (possibly hosting other resources that are used) or assigned (used) by the service. Usually this is the best option when a technology pack for a technology domain provides a resource that you have the opportunity to reuse. For example, a localized telephone number. 4. Modeling a sub-service: Use this approach when a feature is best described by a service entity and its configurations. The life cycle of the sub-service may or may not be bound to the service; it may or may not be shared across multiple services. Usually, this is the best option when a technology pack for a technology domain provides a service that you have the opportunity to reuse. For example, voice mail service. The following steps provide guidance to determine what information and resources are useful as configuration items: 1. A device that is a target for activation should be referenced by a configuration item. It provides context for other information and resources that activation must configure onto that device. 2. Any logical resource (for example, device interface, subscriber account, telephone number, network address) that must be activated on the device should be a resource assignment that is visible as a configuration item. The assignment tracks the utilization of the resource, and it drives the generation of a unit of work for activation. 3. Many simple RFSs, like voice mail, email, and content services, use the following pattern of configuration items: a. A reference to a device that hosts the RFS (subscription). b. An assignment of a logical device account that represents the subscriber specific configuration information as its attributes and characteristics. 4. Factor into service profiles logical groupings of simple options that are common across entire classes of subscribers and services. One of these can be referenced from a configuration item. Because only a few service profiles are instantiated across all services to represent the permutations in options, the storage and computational overhead per subscriber is low.
  • 20. GUIDELINES AND BEST PRACTICES Page 19 5. A device or piece of equipment that must be shipped to the subscriber or installed by a technician should be a resource assignment that is visible as a configuration item. The assignment tracks the use of the resource, and drives the generation of a unit of work for SCM or work force management. 6. An RFS provided by a third party, such as an unbundled local loop or an access service, should be a service assignment that is visible as a configuration item. The assignment tracks the use of the service, and drives the generation of a unit of work for a supplier/partner gateway, such as an ASR/LSR order management system. For more information see the “Design Intelligence versus Transaction Throughput” and the “Resource Facing Service ” sections of this document. Figure 7 shows the service features modeled for the mobile GSM solution. Figure 7 – Mobile Service Configuration Modeling Third Party Services A service that is provided by a third party is an RFS assigned to a CFS and tracked as an item of its configuration. For example, a service provider might require an unbundled local loop to support a fixed wire-line service. This third party service can be modeled as an RFS and the RFS can have its own service configuration, if that level of detail is required. Often, the only information that is visible to the CFS is the order (product actions) that is submitted through the supplier/partner gateway. This RFS instance tracks the identity of the order, so that it can be managed (for example, revised, canceled, monitored for status). Attributes and characteristics on the RFS instance are sufficient. The RFS does not need to be designed to track these few elements of information. If the third party service is unique for each CFS, it can be created and assigned to each service as a subservice. The life cycle of third party service can be bound to the parent service. This third party service should be disconnected when the parent service is disconnected. If the third party service has a life cycle that is decoupled from customer-facing services, it can be created during service readiness, and the same third party service instance can be reused by referencing it from the configurations of customer- facing services. Modeling Geographically Designated Resources in UIM When resources need to be organized geographically in readiness for provisioning, because the policies for allocating these resources are dependent upon the service address, you can model geographical serving areas. Figure 8 shows the structure for one mobile serving area with one HLR, one short message service center (SMSC), one voiceMailServer, and one usTelephoneNumberBlock serving one usZipCodeArea. Typically, this serving area has more than one usTelephoneNumberBlock serving more than one usZipCodeArea. There can be more than one HLR, more than one
  • 21. GUIDELINES AND BEST PRACTICES Page 20 SMSC, and more than one voiceMailServer, if the number of subscribers in this serving area is large (for example, greater than 200, 000). Figure 8 – Mobile Serving Area The structure depicted above supports the following queries:  Search for an available telephone number to reserve based on the zip code of the customer’s service address.  Search for an HLR to use based on the zip code of the customer’s service address.  Search for a VMS to use based on the zip code of the customer’s service address.  Search for an SMSC to use based on the zip code of the customer’s service address. Managing Pooled Resource Capacity in UIM A pool of resources is an organizational structure that groups a set of resources into a collection. Available resources are allocated out of this pool when they need to be used to deliver services. The Modeling Geographically Designated Resources section provides an example of a pool of resources based on geographical location. In UIM, a pool is implemented by defining an Inventory Group specification. This specification defines a type of pool for organizing any number of other entities (of any type) as members of the pool. The pool can also have characteristics and relationships to places and parties, if those are useful in selecting resources from the pool. The design and assign logic for selecting an available resource constructs a query (or a chain of queries) that makes use of the Inventory Group characteristics and relationships to find the matching pool, and then find an available resource within it. For example, the following queries must be performed to find an available telephone number from the mobile serving area depicted in Figure 8: 1. Use the service address of the subscriber to find the mobile serving area associate with a matching zip code. 2. Find all usTelephoneNumberBlock resources within the mobile serving area and fetch their ids, which represent the prefixes for matching usTelephoneNumber instances within those blocks. 3. Find an available usTelephoneNumber resource which has an id whose prefix matches any of the prefixes of the usTelephoneNumberBlock resources found in the mobile serving area. Managing Owned Telephone Number Capacity in UIM The relationship between the usTelephoneNumber and usTelephoneNumberBlock in Figure 8 – Mobile Serving Area illustrates the pattern for managing large volumes of owned telephone numbers. Using a telephone number block makes managing telephone numbers less tedious when compared to grouping large quantities of individual telephone numbers as members of a serving area.
  • 22. GUIDELINES AND BEST PRACTICES Page 21 Owned telephone numbers should be created in readiness for service fulfillment using UIM. UIM typically manages a large number of owned telephone numbers and assigns a telephone number to a subscriber based on the subscriber’s geographical location. As described in the Modeling Geographically Designated Resources section, a mobile serving area can be used to organize a pool of telephone numbers for allocation to services. For example a serving area can contain one or more zip code areas and one or more telephone number blocks. A service location can be created in UIM for each zip code and made part of the mobile serving area. A telephone number block is created based on the country-specific telephone number block specification. The telephone number for the block represents the prefix for all the telephone numbers that are members of the block. For example, the block “214-388-1” is the prefix for all telephone numbers starting with “214-388-1”. When a mobile subscriber requests a service, the serving area can be determined by matching elements of the subscriber’s service address, such as the zip code. From the serving area, the telephone number blocks can be determined. A query using the block prefix can then retrieve the first available telephone number within those blocks. The telephone number retrieved can then be reserved for the subscriber during order capture. Managing Port-Out Telephone Numbers in UIM When an owned telephone number is assigned to a service, and the service is disconnected with port-out option enabled, the telephone number undergoes a change in state to indicate that it is ported out. This means that the telephone number remains in use by the subscriber, who has activated service at another service provider. The telephone number is not available for reuse for any other service, while it is ported out. There are two ways in which the ported out telephone number can become owned again.  The subscriber disconnects the service outright at the competing service provider, where the telephone number is ported in. The telephone number is "snapped back," so that it is returned to this service provider for reuse.  The subscriber activates service again with this service provider, porting in the telephone number that was previously ported out. This scenario is known as a win-back for this service provider. Managing Port-In Telephone Numbers in UIM Port-in telephone numbers have a life cycle that begins and ends with the service to which it is assigned. When the ported in telephone number is unassigned, and snapped back to its owner, its state is transitioned to end of life to ensure that it does not remain available for reuse by this service provider. Managing Subscribers in UIM The subscriber is the recipient of a service. The subscriber can be distinct from the customer, who is financially or administratively responsible for the service. Figure 9 – Subscriber The subscriber is normally represented as a party. A role can optionally be used to tag the party as a “subscriber”, if there is a need to make that distinction, such as if the service involves multiple parties participating in different roles (for example, customer, subscriber). In the reference implementation, the individual party specification represents only the basic information, such as populating the name with the customer account ID for correlation to the account in CRM. If additional information needs to be stored with the subscriber, you can define a party specification with characteristics for the information elements that will be populated. Such information either needs to be carried from the customer order to the service order; or central fulfillment needs to enrich the order with the subscriber information by retrieving it from CRM, Billing and
  • 23. GUIDELINES AND BEST PRACTICES Page 22 Revenue Management System (BRM), or another BSS application. The captureInteraction operation on UIM can receive a party entity and its characteristics in the request used to create the service and party instance. Managing Subscriber Resources in UIM Subscriber-specific resources are typically created in UIM to inventory a subscriber account for a subscriber on a service register. Such a resource has a lifecycle that is bound to the life of the service. For example, a voice mail account is created to activate a subscriber account on a VMS, and the account expires when the service is disconnected. This prevents the resource from being assigned to another service. This can be achieved in UIM by moving the object status of the resource to ‘deactivated’. Modeling Modular Services and Resources Oracle recommends separating services and resources into modular components in the form of cartridges to reuse these components to develop higher level services, where possible. For example, the telephone number cartridges and voice mail service can be reused to develop any type of telephony service (mobile, VoIP, POTS). Include rules and Java code that implement domain-specific behaviors for designing service configurations and managing or assigning resources in the same cartridge as the model artifacts. Package Java code as a class library (jar file) that exposes a published API (Java interfaces with documentation written in Javadoc). Assign each module its own Java package, which conforms to standard Java naming conventions. All packages under oracle are reserved for code provided by Oracle Corporation including the following packages:  The oracle.communications.activation package is reserved for the ASAP application.  The oracle.communications.ordermanagement package is reserved for the OSM application.  The oracle.communications.inventory package is reserved for the UIM application.  The oracle.communications.consulting package is reserved for Oracle Consulting. Designing Service Configurations The process of designing service configurations can include:  Automated design in UIM  Automated calls to third-party inventories, provisioning systems, and other applications (for example, supplier/partner gateways)  Manual tasks for a person to perform work in UIM or other applications Automated Design in UIM UIM implements automated design by calling operations on the Service Fulfillment Web Service. The captureInteraction operation starts a BusinessInteraction in UIM to represent the context within which the service order in OSM is executing. The service actions and their input parameters as captured on the service order are attached to this BusinessInteraction to drive subsequent design activities, which can be any mix of automated and manual tasks. UIM uses a Drools ruleset for the rules that govern the auto-design of a service configuration. You can add service-specific design rules to extend core UIM logic at specific methods in the Java API called extension points. The ruleset contains one or more rules with calls to Java methods. The ruleset defines the extension points as part of the seed data in UIM base cartridges. For more information about extending UIM through rulesets and extension points see the Unified Inventory Management Developer's Guide. In the case of automated design for service configurations, the auto-design ruleset is associated to the BaseConfigurationManager.automateConfiguration extension point at design time. This setup serves as an extension to the processInteraction Web Service operation. While the processInteraction operation is responsible for creating the top level service instance and configuration version, the remaining steps in the auto-design activity, like processing the configuration
  • 24. GUIDELINES AND BEST PRACTICES Page 23 items, resource life cycle management (for example, creation or end of life), and allocation (or de-allocation) are delegated to the auto-design ruleset. Implement specific auto-design behavior for each service action (for example, add, change, suspend, resume, and disconnect) implemented using a combination of rulesets and Java code that is called from these rules. You can implement the majority of the business logic in Java to benefit from the code debugging tools in Design Studio using the Eclipse IDE. The ruleset can be used as a pass through mechanism to call the business logic implemented in the Java code. The GSM technology pack for UIM includes a class library (ora_uim_commonLib.jar) that provides reusable operations for developing resource- and service-specific cartridges with logic for design and assign. Leverage these methods as much as possible. Oracle recommends that you package additional domain agnostic methods that you create as reusable class libraries to separate this logic from domain-specific code. This practice allows modularity and reuse. The operations provided by the class library are documented in the Unified Inventory Management GSM 3GPP Technology Pack. Manual Design in UIM After the design process calls captureInteraction, a manual task can enable a user to navigate to a UIM Web page in the context of the BusinessInteraction that corresponds to the service order. This manual task can be in addition to an automated task that calls processInteraction on UIM for auto-design or it can be used instead of auto-design, if design is done completely by hand. Typically a manual task is used to delegate a limited set of responsibilities to a person, when the task cannot be easily automated. This manual task can be introduced before calling processInteraction or after. A manual task can be inserted between automated tasks that call processInteraction twice, once before the manual task, and once again after, if the auto-design rules are written to do further process based on the information enriched by the manual task. The separation of concerns between captureInteraction and processInteraction gives you the flexibility to intermix manual design tasks with auto-design tasks and automated tasks that involve other applications as participants in design and assign. UIM Web pages support a URL format that allows you to hyperlink to the page in the context of a relevant instance of an inventory entity. For example, when the id of the relevant inventory entity is appended to the following URL: http://host:port/Inventory/faces/InventoryUIShell?fnd=/WEB-INF/MasterFlow.xml%23MasterFlow;id= It links to the Web page in context to view and edit that inventory entity with tools in UIM that are specific to the type of entity. Automated Design Task to Use Other Systems The service provisioning solution provides a pre-design function and a post-design function, which are placeholders for integrating with third-party applications that participate in the design of service configurations. Such participation can be in various forms:  A third-party inventory management application can be responsible for managing only the capacity of resources (or RFSs). The application supports the allocation, de-allocation, and life cycle management of those resources. These resource allocations are contributed as items on the service configuration that is managed by UIM. The provisioning process in OSM retains responsibility for implementing the service as a configuration of those resources in the network.  A third-party provisioning application can be responsible for both the capacity management of resources (or RFSs) and the implementation of the service as a configuration of those resources in the network. Manual Design Task to Use Other Systems The approach described in the "Manual Design in UIM" section can be applied to performing manual work in other applications that participate in the design process. It works best if the application supports a URL format where you can append a parameter to indicate the context (for example, an entity in the application that corresponds to the current service order). A key consideration is how to retrieve the configuration information that was designed and assigned in the other application, so that it can be updated on the service order. Ideally, the application provides a Web Service to access this configuration information. Alternatively, the manual task can allow the user to input this configuration information into the service order
  • 25. GUIDELINES AND BEST PRACTICES Page 24 through the editor. Unfortunately, this double entry method is subject to human error, so Oracle recommends the method that relies on Web Services, wherever possible. OSM Technical Orders, Actions, and Delivery Plans The OSM technical order is represented in the reference implementation by a delivery order (MobileGSMDeliveryOrder). The contents (technical actions) of the technical order are the plan of work for delivering the service configurations into the network. The reference implementation calls these delivery actions. Despite the difference in terminology, the concepts are equivalent. Table 5 lists the technical order C2A terminology and the equivalent mobile GSM solution reference implementation terminology. Table 5 – OSM Technical Order and Reference Implementation Terminology Concept to Activate Terminology Reference Implementation Purpose Technical Order Delivery Order An order for realizing the service configurations in the network. Technical Action Delivery Action A unit of work for realizing a change in the service configurations in the network. Delivery Plan The set of actions on the order and their dependencies Modeling OSM Technical Order Work Dependencies When executing a technical order (MobileGSMDeliveryOrder) to deliver configurations, which were designed and assigned in the inventory, each technical action on the technical order can generate orchestration functions that can be dependent on each other. For example, provisioning a CPE device resource can require shipping the device to the service address from the supply chain before the device can be managed so that services are activated. The orchestration plan for the technical actions on the technical order sequences the functions based on their dependencies. These dependencies can be modeled between order components (orchestration functions) defined on a fulfillment pattern (represented as a product specification in OSM). Grouping Related Work Items into Single Order Components Certain types of work are best performed by collecting the items (actions) from the technical order that should be performed together as a single order component. For example, it is inconvenient to schedule separate appointments for a technician to install each video set top box; it makes sense to collect all video set top boxes into a single order component, so that they are all installed by the technician in a single appointment. Grouping Work per Activation System An OSS solution needs to consider and accommodate multiple activation system instances. Large mobile providers have several ASAP instances for their mobile services. Therefore, the OSS application topology needs to be flexible and must be able to determine which activation system a request goes to. Adding an instance of an activation system to an OSS application topology should require minimal configuration and not impact the existing processes (topology decoupled).
  • 26. GUIDELINES AND BEST PRACTICES Page 25 ASAP Service Activation Figure 10 shows a simplified view of the ASAP activation architecture. Figure 10 – ASAP Activation Architecture The ASAP mobile GSM solution cartridge provides:  Service actions, also called the common service description layer (CSDL), that are referenced by incoming work orders.  Atomic actions, also called the atomic service description layer (ASDL), and Action Processors (APs) that provide an intermediate layer between the ASAP core and the ASAP mobile GSM solution network cartridge. Note: The vertical component of the mobile GSM solution cartridge in the diagram above represents the service actions that are available for use by upstream systems. The horizontal component represents the intermediate layer that allows for re-use of existing cartridges. Table 6 shows a sample ASAP activation service model. Table 6 – ASAP Activation Service Model Scenario Service Action (CSDL) Atomic Action (ASDL) Add Mobile C_GSM_ADD_SUB A_VAL_GSM_ADD_SUB A_HLR_CREATE_SUBSCRIBER A_HLR_ACT_CAW A_HLR_ACT_CFU A_HLR_ACT_CLIP A_HLR_ACT_TS21 A_HLR_ACT_TS22 A_VMS_CREATE_SUBSCRIBER Change Mobile C_GSM_MOD_GPRS A_VAL_GSM_MOD_GPRS A_HLR_ADD_GPRS A_HLR_REM_GPRS Suspend / Resume Mobile C_GSM_MOD_OBA A_VAL_GSM_MOD_OBA A_HLR_ACT_OBA A_HLR_DEACT_OBA Disconnect Mobile C_GSM_DEL_SUB A_VAL_GSM_DEL_SUB
  • 27. GUIDELINES AND BEST PRACTICES Page 26 A_HLR_DEL_SUBSCRIBER A_VMS_DEL_SUBSCRIBER Abstracting Services from Network Technology and Software The following sections provide information about abstracting services from network technology versions and software loads. Decoupling Service Order Management from ASAP To decouple the SOM and activation components, the upstream interface of the service model in activation is vendor and software load agnostic. Abstracting services from the network minimizes the impact on the overall solution, when support for a new vendor or software load of a network element is needed. For example, adding support for the Nokia HLR requires an update only to the Activation component’s Mobile GSM cartridge, and little or no changes are required to the SOM and inventory components. The network technology and software load in activation (ASAP) and inventory (UIM) are decoupled from SOM (OSM). This allows the SOM component to be network vendor technology agnostic and prevents impacts from propagating to activation and SOM. It facilitates introducing new versions of the activation cartridges due to new instances of the same NE type, NE software load changes (for example, Ericsson HLR R12-1), and devices from a different vendor (for example, Nokia) that perform the same function (for example, HLR). Decoupling ASAP Service Model from Vendor/Software Loads In ASAP service cartridges, the activation service model (service actions and atomic actions) can be vendor and software load agnostic. You can map atomic actions to the vendor and software load specific APs from the ASAP network cartridges. This allows the new vendors of the same NE type to be introduced more readily, and also insulates the service model from software load version changes for the same vendor’s device (for example Ericsson HLR R12-0 and R12-1). For example, Table 1 – Reference Implementation Mobile GSM Solution Components lists the following ASAP service cartridge and network cartridges.  ASAP service cartridge (vendor and software load agnostic): o ASAP cartridge for mobile solution  ASAP network cartridges (vendor and software load specific): o ASAP cartridge for Ericsson HLR o ASAP cartridge for Comverse VMS Oracle offers network cartridges as products to accelerate solution development. The mobile GSM solution demonstrates how you can leverage ASAP network cartridges by developing a service cartridge that abstracts the vendor and device specific atomic actions and their APs into service actions. For more information, see the "Designing ASAP Service Cartridge Action Processors" section. GSM Solution Service and Network Cartridge Design Goals Oracle developers used the following design goals when developing the mobile GSM solution, ASAP service, and network cartridges:  Service actions (CSDLs) are vendor and version agnostic. This goal, as explained in the previous section, decouples the activation layer from the other layers. This is the main driver for creating service abstraction cartridges.  All of the existing Network cartridges (for example, Ericsson HLR and Comverse VMS) are sealed. This maintains the integrity of the productized Network Cartridges. It also reduces the ongoing maintenance effort because updated versions or patches of the Network Cartridges can be incorporated with no changes to the service abstraction cartridge.
  • 28. GUIDELINES AND BEST PRACTICES Page 27 ASAP Service Model Design Patterns Figure 11 shows the two main design patterns that Oracle developers used when designing the ASAP activation service model. The service action and atomic action components were developed the same way but the AP level is different. Figure 11 – Mobile Service Activation Designing ASAP Service Cartridge Service Actions In both patterns, a CSDL is created for each externally visible operation. For example, the ASAP mobile GSM service cartridge provides a separate CSDL for each scenario, such as C_GSM_ADD_SUB for the add mobile scenario. Each CSDL consists of a unique name and a set of input parameters, which are available to upstream applications through the OSM Activation Task and configured in Design Studio. Note: CSDL parameters are not defined in the CSDL itself. Instead, the parameters are defined in associated ASDLs, and are automatically linked to the CSDL. The result is that the CSDL parameter list is a superset of the parameters from all its associated ASDLs. Designing ASAP Service Cartridge Atomic Actions In both patterns, one or more ASDLs are developed for each CSDL. Typically, a separate ASDL is created for each low-level operation required on the target network element. For example, the C_GSM_ADD_SUB CSDL is associated with eight ASDLs, with each performing a specific function, such as add mobile subscriber, add call waiting, and add voice mail, and so on. This is also where both the CSDL and ASDL parameters are defined. To minimize the number of parameters at the CSDL level, it is important that a consistent set of CSDL parameter names be used across all of the ASDLs. For example, one ASDL should not use IP_ADDRESS and another use IP_ADDR since this creates two separate and redundant parameters at the CSDL level. Instead, choose one of the names and use that name across all of the ASDLs.
  • 29. GUIDELINES AND BEST PRACTICES Page 28 Note: Instead of creating new ASDLs in the ASAP Mobile GSM service cartridge, you can associate the Mobile GSM CSDLs directly to ASDLs from the Ericsson HLR and Comverse VMS network cartridges. However, the Oracle developers did not use this approach because it would have greatly reduced the flexibility and extensibility required for a service abstraction cartridge. For example, since the network cartridge ASDLs already come with a predefined set of CSDL parameter names, it would not be possible to rename any of the CSDL parameters in the Mobile GSM cartridge. As a result, it would not be possible to extend the Mobile GSM cartridge to support other network cartridges (for example Nokia HLR) because they would have an incompatible set of predefined parameter names. Designing ASAP Service Cartridge Action Processors APs contain the Java-based business logic for the associated ASDL. For example, the AP for the Add Call Waiting ASDL contains Java code that issues the command to enable call-waiting on the target Network Element. This is also the main extension point when adding support for other vendors. There can be multiple APs associated to an ASDL, with each AP providing the business logic for a different vendor. For example, all of the HLR-related ASDLs in the ASAP Mobile GSM service cartridge are currently associated with only a single AP from the Ericsson HLR network cartridge. However, if support for Nokia HLR’s was needed, a second association can be added to all of the HLR-related ASDLs, and the new associations could be to APs from the Nokia HLR network cartridge The main difference between the two design patterns also occurs at the AP level, and involves the way in which the ASDLs leverage the existing business logic from the network cartridge APs. In the first case, ASDLs in the Mobile GSM cartridge are directly associated with APs in the network cartridge. In the second case, the ASAP Mobile GSM cartridge contains an extra AP layer. This AP directly invokes the Java implementation of the network cartridge AP. The first case is simpler from an implementation perspective, but it can be used only when the associated ASDL parameters match what the existing APs in the network cartridge expect. Specifically, the following conditions need to be met:  The parameter names must match.  The ASAP parameter types must match (for example, scalar, compound, and so on).  The semantics of the parameters must match (for example, the semantics do not match if the incoming value from the ASDL contains ‘Y’ or ‘N’, but the AP expects ‘YES’ or ‘NO’). If any of these conditions are not met, you must use the second approach. Pattern 1: Referencing the Action Processor When using this option, the ASDL in the ASAP Mobile GSM service cartridge is associated with an existing AP in the network cartridge through the standard Design Studio functionality. Nothing extra is required. As mentioned above, this option can be used only when the above conditions are met, which typically occurs only for the first device type being supported. In the ASAP Mobile GSM service cartridge, Oracle developers used this pattern for several of the Ericsson HLR APs. The reason it is applicable for the first device type is that the ASDL parameters can be set to match the expectations of the APs. However, this is no longer possible when adding support for a second device type because changing the ASDL parameter names to match the APs in the new cartridge often breaks the associations made for the original device type. Pattern 2: Directly invoking the Action Processor’s Java implementation When using this option, an AP is created in the ASAP Mobile GSM service cartridge that acts as an intermediary between the ASDL and the Network Cartridge’s business logic. The Java code in the Mobile GSM AP directly invokes the associated Java code in the Network Cartridge AP.
  • 30. GUIDELINES AND BEST PRACTICES Page 29 This pattern is used in the ASAP Mobile GSM service cartridge for two cases where the conditions listed above were not met. In one case, there was a type mismatch where the ASDL parameter was defined as a scalar, but the network cartridge AP expected a compound. The intermediate Mobile GSM AP is responsible for converting the parameter from a scalar to a compound before invoking the network cartridge AP. In another case, the semantics did not match because the ASDL parameter was defined to accept ‘Y’ or ‘N’, but the network cartridge AP expected ‘YES’ or ‘NO’. The intermediate Mobile GSM AP is responsible for translating the ‘Y’ to ‘YES’ and ‘N’ to ’NO’ before invoking the network cartridge AP. Java Guidelines for ASAP When implementing the Java business logic for an AP in a service cartridge, there are a few guidelines that you must follow to invoke existing network cartridge AP code from the service cartridge code: 1. When creating the AP in Studio, you must choose the Java Action Processor option and then create the Java implementation separately. The Java Action Processor (with Code Generation) option does not work in the ASAP mobile GSM service cartridge. Note: The Java Action Processor (with Code Generation) option works in a service cartridge only if all network cartridges used by the service cartridge also use code generation. The network cartridges referenced by the ASAP mobile GSM service cartridge do not use code generation. 2. The Java class for the newly created AP must extend from the JProcessorHelper class that is included in the Mobile GSM service cartridge. This class contains helper methods needed for setting and retrieving the context of the network cartridge Java objects at runtime. 3. The Java method for the given AP should: a. Instantiate the Java object that is associated with the target network cartridge AP. b. Perform the necessary parameter renaming, type conversion, and/or semantic translations. c. Call the JProcessorHelper’s setChildContext() method to initialize the object. d. Invoke the Java method that is associated with the target network cartridge AP. e. Call the JProcessorHelper’s getChildContext() method to retrieve the results from the call in the previous step. The code in EricssonProcessor.Java located in the Mobile GSM service cartridge shows where the translation happens for the incoming value of the LMU parameter and also shows the createSubscription() method call from the Ericsson HLR cartridge. public void createSubscriber() { HLRProvisioning ericssonProcessor = new HLRProvisioning(); // the LMU parameter needs to be modified slightly since the Ericsson HLR // cartridge expects 'YES' or 'NO' instead of the incoming 'Y' or 'N' String value = getParam(LMU); if (value != null) { if (value.equalsIgnoreCase(YES_VALUE)) { getAllActionParams().setProperty(LMU, "YES"); } else if (value.equalsIgnoreCase(NO_VALUE)) { getAllActionParams().setProperty(LMU, "NO");; } } // initialize the child processor setChildContext(ericssonProcessor); // invoke the child processor ericssonProcessor.createSubscription(); // retrieve the results from the child processor getChildContext(ericssonProcessor); }
  • 31. GUIDELINES AND BEST PRACTICES Page 30 Propagating Updates to Customer Orders During service order execution, when provisioning has finished delivering the configuration changes into the network, the final activity is responsible for performing all the completion steps, which include: 1. Complete the Business Interaction that mirrors the service order in UIM. 2. Notify OSM COM that the provisioning function has completed executing the service order. 3. Notify OSM COM to update the customer order with the output parameters of each service action, so that information can be returned upstream. This information can be customer facing or it can be relevant to subsequent service fulfillment functions that depend on provisioning finishing first. Handling Errors in OSM Service Orders OSM tasks can fail during service order execution. When a task fails, generally the work flow is redirected to an error handling task that is specific to the context (failed task) for human intervention. This allows the problem to be resolved and then the user can control the subsequent flow of work based on the failure resolution path. This section describes all the possible options for problem resolution. Not every resolution path is relevant to every task.
  • 32. GUIDELINES AND BEST PRACTICES Page 31 Figure 12 shows an OSM design process with failure resolution paths. Figure 12 – Design Process Retrying Current Activity Sometimes an automated task does not fail due to an actual error condition. Instead, the task never progresses beyond the “accepted” state, and the application that is being called by the task does not appear to receive a request. You can recognize when this situation occurs when the order takes too long to execute. The process history for the order shows that the execution has stalled at an automated task in the “accepted” state. Knowing the operation performed by the task (for example, captureInteraction), you can investigate what happened in that target application given the context (the service order). If there is no indication that the operation was performed, and no request message is still queued to call that operation, the most likely cause is that the message was never delivered. The resolution to this problem is to force OSM to send the request again. Do this by changing the state of the task back to “received”, so that execution of the task restarts. You do not need to do anything special to enable this option for an automation task. Retrying the Failed Activity Automated tasks generally fail because a fault (error) message is received in reply to a request for an operation to be performed. Upon receiving the fault message, OSM saves the error code and description in the service order, so that it can be reported to the user who investigates the failure. The task is completed with a failure status to redirect the work flow to the error handling task. You can model this error handling task to support a retry completion status that flows back to the task from which the failure originated. In the reference implementation, the task that calls processInteraction on UIM is an example of this pattern. When processInteraction (auto-design) fails, certain failures can be resolved by the user by making edits to the inventory and retrying the processInteraction call. For example, if a reserved telephone number was captured on the order, and the reservation cannot be redeemed because it does not exist (for example, the reservation has already expired), the problem can be resolved by creating the reservation in the inventory, before retrying auto-design. An important consideration in this pattern is that the error handling task is not reusable at a different activity in the process. The “retry” transition needs to loop back to the original task that failed. Resuming After Resolving Errors For situations where the error is not significant, the process flow can continue as if there was no error. When the work flow is directed to the error handling task, the user can select the “resume” status to continue to the next task in the process. Some kinds of errors can also be resolved by making edits to the inventory and subsequent edits to the service order to reflect the configuration information that was designed and assigned to the service(s). For example, if a service order adds a mobile
  • 33. GUIDELINES AND BEST PRACTICES Page 32 service for a subscriber who resides at an address outside any serving area that is set up in readiness for provisioning. This resolution path bypasses auto-design by performing the design and assign solely through human intervention. In all of these situations, the task completion status directs the work flow to the error handling task. For example, the “HandleDesignFallout” task in the mobile GSM solution handles errors from the task that calls “processInteraction”. A failure in design allows you to solve the problem manually and resume execution at the next task (approve the business interaction). Although this task is named as though it is handling fallout, it is actually handling errors or failures. The concept of order fallout handling is intended to address incorrect information on the customer order. The error handling task is not reusable at a different activity in the process. The “resume” transition must flow to the successor to the original task that failed. In the mobile GSM solution, the “HandleDesignFallout” task is the error handling task for a design error. The “HandleActivationFallout” is the error handling task for an activation error. Both error handling tasks have resume and retry completion statuses, but the tasks to which these transitions redirect are specific to the original task that failed. Triggering Customer Order Fallout For situations where the error cannot be handled within the OSM SOM, the error can be propagated upstream to trigger the customer order to fallout. This is necessary if the information captured on the customer order is incorrect and the workflow must be directed back to order capture. Fallout must be triggered on the customer order so that you can make the determination that the problem must be resolved by redoing order capture. When you submit the revised customer order for fulfillment, the order redoes the provisioning function by amending the service order. Alternatively, if no resolution is possible, the customer order can be canceled. This action propagates the cancelation downstream to the service order that is still in progress. Canceling a Service Order Sometimes there is no acceptable resolution path from the error handling task and the order must be undone. In this case, you should cancel the service order. To cancel a service order: 1. In the worklist, select the order that you want to cancel. 2. Right-click the order and select Cancel. If any of the tasks in the order are modeled to support “undo” compensation, these undo tasks execute in backwards sequence. When the order has finished compensating, it returns to the creation task at which point the order can be deleted or resubmitted for execution. You can create one generic error handling task to trap failed orders that can be resolved only by canceling that task. For example, a “FalloutToCancel” task can be created for this purpose. For any task in a process where the logic dictates that cancel is the only option, those tasks transition to “FalloutToCancel” when an error occurs. Warning: Oracle does not recommend this option. Cancelations should be initiated from the customer order in the CRM, after triggering order fallout (see "Triggering Customer Order Fallout"). The cancelation should propagate downstream to the service order. Packaging an OSS Solution See "Design Studio Packaging and Integrated Cartridge Deployment" in Design Studio Concepts for information about packaging and deployment of an OSS solution. OSS Solution Development Desktop Tools and Applications The following sections describe the desktop tools and applications required for developing OSS solutions.
  • 34. GUIDELINES AND BEST PRACTICES Page 33 Software Requirements The following applications must be installed and configured:  Oracle Fusion Middleware 11g R1 PS5 (WLS 10.3.6)  JDeveloper 11g – the security modules are needed by the OSM SDK for password encryption  OSM 7.2.2 SDK  Eclipse IDE (Indigo)  Oracle Communications Design Studio Platform  Oracle Communications Design Studio Domain Modeling  Oracle Communications Design Studio for Activation SRT  Oracle Communications Design Studio for Activation UI  Oracle Communications Design Studio for Inventory  Oracle Communications Design Studio for Order and Service Management  Oracle Communications Design Studio for Order and Service Management Integration  Oracle Communications Design Studio for Order and Service Management Orchestration  Oracle Communications Design Studio for Order and Service Management Orchestration Application Integration Architecture (AIA) It is mandatory that the Design Studio plugins for Activation, Order and Service Management, and Inventory are installed together to take advantage of the Mobile GSM solution reference implementation. You can also install the following optional tools. These tools are helpful for readiness, testing, and other administrative activities.  soapUI – test tool for calling Web Services  HermesJMS – test tool for sending and receiving JMS messages  SQL Developer – utility for maintaining the database  XQDT for Eclipse or oXygen XML Developer – XQuery Editor  Apache ant for build management  Hudson for continuous integration
  • 35. GUIDELINES AND BEST PRACTICES Page 34 Preparing the Design Studio Workspace How you prepare a Design Studio workspace depends on the solution you want to develop. This section summarizes the steps to create a Design Studio workspace for a mobile solution. Detailed steps that are subject to change for each new software release can be found in the Oracle Communications OSS Mobile Solution Uptake Guide (section on "Solution Development Desktop"). To prepare a Design Studio workspace: 1. Import the following ASAP cartridges from the Mobile Messaging cartridge media pack for ASAP:  Comverse VMS  Ericsson HLR 2. Import the following dictionary cartridge project available from the GSM technology pack for UIM:  ora_dict_mobile 3. Import the ASAP cartridge project for the mobile solution. 4. Import the OSM cartridge projects for the mobile solution. 5. Make the UIM class libraries available to Design Studio cartridge projects through the classpath variable UIM_LIB. Import all base cartridge projects for UIM. Configure the Design Studio class path variable for WL_LIB to point to the WebLogic Server lib directory. 6. Import all cartridge projects from the GSM technology pack for UIM. Collaborating in Teams See "Collaborating in Teams" in Design Studio Concepts for more information. Executing Tests Table 7 lists testing activities, tools, and recommendations. Table 7 – Testing Activities, Tools, and Recommendations Test Activity Tool Recommended Approach Unit and integration testing for ASAP solution components Design Studio for ASAP (manual); soapUI (automated)  Configure ASAP to run in development/test and loopback mode with respect to network elements.  Use the createOrderByValue request to submit an order for execution.  Represent each test case by the CSDLs that are captured on the order and submitted to ASAP for execution.  Use HermesJMS to listen for events from the JMS Topic to validate whether an order executed successfully. Unit and integration testing for OSM solution components Design Studio for OSM (manual); soapUI (automated)  Configure store-and-forward (SAF) queues in OSM to forward to emulators (mock implementations that reply with pre-recorded results) for UIM and ASAP. Mocking is optional. It can be advantageous to call UIM and OSM in an integration test environment, if mocking is unavailable.  Represent each test case by the product actions captured on the AIAProvisioningOrderEBM and submitted to OSM for execution. Unit and integration testing for UIM solution components soapUI  Create a test case with test steps that call the Web Service operations (captureInteraction, processInteraction, updateInteraction) in sequence. The captureInteraction request carries the inputs for auto-design into the business interaction. The processInteraciton response returns the result of auto-design. Use XPath expressions to validate the correct functioning of the auto-design logic. Manual integration and system testing for end-to- end scenarios Design Studio for OSM  In a fully integrated test environment, submit customer orders as AIA ProvisioningOrder EBMs that have coverage of the end-to-end scenarios.
  • 36. GUIDELINES AND BEST PRACTICES Page 35 Automated integration and system testing for end-to- end scenarios soapUI  In a fully integrated test environment, submit customer orders as AIA ProvisioningOrder EBMs that have coverage of the end-to-end scenarios. Automated testing is preferred to manual testing. Testing an integrated OSS solution is a complex task. Answer the following questions:  Do the line items decompose into the correct orchestration plan?  Does the correct sequence of activities occur?  Do JMS messages get sent to the correct queues? Use emulators in place of external systems so that the focus can remain on these fundamentals. At this point, emulators do not need to do anything more complex than receive messages from queues and return responses. When the mechanics of the order are working smoothly, the content of the messages can be developed and refined. The creation of JMS requests and processing of JMS responses can be tested, and the flow of information through the provisioning process. The response messages the emulators send back can be enhanced to reflect actual content from the external systems. After functional testing is completed with emulators, you can move on to fully integrated system testing. At this point the emulators are “un-hooked” from the solution and replaced with actual external system integration. Developing Orchestration Cartridges For more information about OSM best practices for orchestration, see Oracle Communications Order and Service Management Concepts. Designing OSM Cartridges The following sections provide information about designing OSM cartridges. Order Template Before OSM 7.0, order templates were defined at the order level. OSM 7.x now provides support for the order template contribution feature. This feature is a design practice that encourages localized definitions of order template data structures on the entity that best defines its structure. Design Studio generates the order level template by aggregating all the localized order template definitions with any definitions defined at the order level. Use localized order templates for the following entities:  Order Item Specification: Define ControlData/OrderItem and all the order item properties.  Order Component Specification: Define ControlData/Functions/FunctionName and any other data needed by the tasks in the process that execute this component. Cartridge Separation and Packaging OSM cartridges should be organized and packaged in a modular way. This allows you to re-use the provisioning patterns without needing to unseal the base cartridges. The mobile GSM solution reference implementation does not yet provide full support for such modularity. As a result, to extend the solution you must make changes directly to the source, which makes the uptake of new source cartridges more difficult.
  • 37. GUIDELINES AND BEST PRACTICES Page 36 OSM Order Recognition Rules and Relevancy OSM creates orders in response to a ‘CreateOrder’ call to the OSM Web Service. When a ‘CreateOrder’ request is submitted, the first point of processing within OSM is the Order Request Processor (ORP). The ORP recognizes orders and maps them to the correct order specification so they can be processed. Figure 13 shows the OSM order submission process. Figure 13 – OSM Order Submission An order recognition rule (ORR) is the design time entity that you configure for ORP processing. Relevancy and Recognition are important aspects of ORRs.
  • 38. GUIDELINES AND BEST PRACTICES Page 37 Figure 14 shows how an ORP operates at run time. Figure 14 – ORP at runtime This process includes the following steps: 1. The ORP gets all currently deployed recognition rules with a given relevancy, beginning with the most relevant - 1. 2. For each ORR found at this relevancy, OSM tries to execute the recognition against the incoming order to see if there is a match. 3. OSM continues this process for all recognition and all relevancies until a matching Order Recognition Rule is found. There is an inter-play between relevancy and recognition that you must consider at design time for all orders that are intended to share a runtime environment. The recognition for each of these rules must be specific enough to match only the order it intends to process. A general recognition that shares relevancy with another rule might match to orders that it should not process. Recognition and Relevancy in the Mobile GSM Solution There are two ORRs in the mobile GSM solution:  An ORR to recognize orders processed by the MobileGSMProvisioning cartridge.  An ORR to recognize orders that are processed by the MobileGSMDelivery cartridge. The relevancy of both recognition rules is set to 3. These rules share the same relevancy, but are each configured to recognize a different type of incoming order. The ORR for MobileGSMProvisioning recognizes the namespace of an EBM order and a fulfillment mode of ‘DELIVER’ while the ORR for MobileGSMDelivery recognizes an order with a namespace specific to GSM delivery and a fulfillment mode of ‘DELIVER’. Order Recognition Rules in Multiple OSM Implementations ORRs are global entities in an OSM runtime environment. Whether you are designing or deploying the solution, you must ensure that ORRs from separate OSM implementations can co-exist in a runtime environment. If cartridges cannot be designed with recognition that is specific to the order details, these solutions must be deployed into separate OSM instances.
  • 39. GUIDELINES AND BEST PRACTICES Page 38 Testing XQuery Scripts During solution design and development, execute XQuery scripts outside the runtime environment for efficiency. Also some changes may have to be made to the XQuery scripts for testing. Ensure that you maintain two versions of the XQuery scripts for testing and source control. The two versions must be in sync when you make changes. There are many third-party tools that enable developers to run transformations on an xml file using an XQuery script. The MobileGSMResources cartridge has a /resources/testing directory that contains useful samples to get you started with solution development. Testing Customer Order to Service Order Transforms When an ORR recognizes an AIA provisioning order, it goes through a customer order to service order transformation. The order is changed from an AIA format into a generic service order structure suitable for provisioning. An XQuery performs this transformation that can be difficult to debug. This transformation mechanism can be tested and debugged in a third-party tool using the samples files provided as a basis located in the resources/testing/ORR_Transform directory. Testing Order Item Specification – Order Action Another XQuery script populates the provisioning line item property – OrderAction. The OrderAction node contains all the service specific data that comes from order capture and populating it correctly requires debugging skills. Samples files located in the resources/testing/OrderAction directory are provided for executing this script using a third-party tool. Testing Automation Scripts XQuery is used extensively for task automation. Automated senders and receivers use XQuery scripts to create JMS messages and process JMS responses. These XQuery scripts are difficult to debug because of the combination of library imports, xml catalogs, and references to Java classes. Because of the complexities associated with individual implementations, no sample scripts are provided. Important OSM URLs The following list provides important OSM URLs (where hostname is the WebLogic server hostname and port is the port number for the OSM instance):  hostname:port/OrderManagement/admin/log4jAdmin Use this link to change the log levels for OSM components. The WebLogic username must be a member of the OMS_log_manager group in the WebLogic security realm. A logger (for example, CaptureBI logger) must be instantiated before it is available in log4j. Run an order through to completion to make all of the loggers available.  hostname:port/OrderManagement Use this link to access the OSM Order Editor to create orders, view worklists, and transition manual tasks.  hostname:port/OrderManagement/orchestration Use this link to access the 7.0 Web UI which contains the list of orchestration orders and applicable details such as the orchestration plan and order line items. OSM Tips, Tricks, and Pitfalls The following list describes OSM tips, tricks, and pitfalls:  The OSM default namespace is http://urn:com:metasolv:oms:xmlapi:1  On the Web UI (7.x) the left hand panel of the screen should contain at least one order item  To send a Web Service request to OSM, the string property URI must be set to /OrderManagement/wsapi  OSM uses a no-namespace DOM for behaviors. When using XPath in a behavior do not specify namespaces.
  • 40. GUIDELINES AND BEST PRACTICES Page 39  If the activation task is used to communicate with ASAP, there are string limitations imposed by ASAP when naming both OSM cartridges and activation tasks. The “apiClientId” field of the CreateOrderByValue request has a maximum length of 64 characters. The activation task creates the value of this field by concatenating the cartridge name, cartridge version, and task name. If the cartridge and task names are too long, the ASAP request is rejected.  In a development environment, set the redelivery limit and override on JMS queues to 5000 and 2, so they do not keep retrying. If you do not set this, a message might sit in a queue and never be processed. In this situation, OSM tries to process the message and continually logs error messages.  ControlData/OrderItem – any data that needs to be set before orchestration starts needs to be modeled as an order item property. It can be data that is contained within a larger group. As an example in the mobile cartridge, the orderAction is a property and an XQuery populates all of the data that is contained in that parent node.  To turn on the catalog.xml functionality for a given cartridge, the file “enableXMLCatalogSupport” must be added to the cartridge. Edit the catalog.xml file within the >xmlcatalogs>core folder. Each cartridge should have a catalog enabled.  The catalog.xml file is GLOBAL, so namespaces should be unique.  Order Recognition Rules are GLOBAL.  Try to model data in the dictionary as a reusable base type. It allows a place where you can change type or maximum length in one place and have it propagated to all areas that use it.  Prepend OSM entities with something recognizable for your cartridge. This is because all entities within your workspace are accessible and it makes it easier to identify the correct item when you are selecting from a large list.  Group order component specifications into a folder. Without doing this you cannot select “all” of the items in a group when editing the orchestration stage. If you want all, you can select the folder in which they belong and by default they are all selected.  When modeling data in the dictionary, if you declare a base type that has a subfolder, anything that declares itself of that type cannot add to the subfolder. As an example: ActionType/Service/Servicename. If you create an AddMobile (of ActionType), you cannot add to the Service folder. You can only add new elements under your root.  On the OrderComponent tab (in ProductSpec, Orch Plan tab), if you want to put a condition on an individual function, you need to make sure that your group is not selected. For example, GSM_BaseFunction needs to be unselected to put a condition on GSM_PreDesignFunction.  In Design Studio, when one library module imports another and both of these are used in the main XQuery, you might get errors about “Duplicate function exception”. You can ignore these. Open the library module files in Design Studio, go to the XQuery menu, and select “Clear Validation Markers”.  When a task is working at whole order granularity, the task should have access to the /ControlData/OrderItems folder. This means that when updating OSM data, a key must be defined on some data element that is unique. In the mobile GSM solution, this field is the line ID. When the order update is created, the key needs to be used to ensure OSM is updating the right value. Go to MobileGSMProvisioningOrder > Order Template tab > Select the order item > Properties window > Key tab.  If a task is working at the order item granularity, the task should be getting its view of the order data through the reference (for example, ControlData/Functions/function/orderItem/orderItemRef). This ensures that the task is seeing only the line item that it should.  If you make changes to the order template or data schema, undeploy existing cartridges from your environment before deploying the new changes. If you do not, you might get errors when you run an order, usually about a missing or extra node.
  • 41. GUIDELINES AND BEST PRACTICES Page 40  When working with Order Recognition Rules, there can be many problems with no meaningful way to resolve the issues. The error: oracle.communications.ordermanagement.ws.InvalidOrderSpecificationFault: No matching Order Recognition rule found can be the result of a compile problem with the XQuery that handles the transformation. The OSM server log file shows whether this is the case. It is always a good idea to use the test samples provided (MobileGSMResources/resources/testing/ORR_Transform) to test your XQuery changes in this area.  It used to be the case that every external receiver had to have a dedicated queue to receive response messages correctly. Improvements were made to OSM core so that one response queue can be shared by many receivers. It is up to OSM to figure out which receiver should process a message. The only problem remaining is that OSM cannot decipher the difference between a DO and an UNDO response. For an automated task, if there are two external receivers, you need a separate response queue for one of them.  Logging JMS message content from your XQuery files is essential for debugging purposes, but these messages should be not be logged above the debug level. It is also important for security that, when logging JMS message content, the security header be removed from the log statements. Extending the Mobile GSM Solution The mobile GSM solution for service provisioning provisions a limited set of features and actions for GSM as a reference implementation. The reference implementation does not implement a complete set of features and actions for the GSM domain and is not a comprehensive mobile GSM solution. The reference implementation provides a starting point to accelerate system integration and solution development. The mobile GSM solution supports extensibility. This section describes the dimensions of extensibility involved in solution development. See Table 11 for more information about design activities and corresponding components. Analyzing Extension Requirements OSS solution development starts with an analysis of the requirements and includes the following aspects:  Gain an understanding of the service domain(s).  Identify the types of CFSs.  Identify the actions that a customer can request for services on an order. For more information, see "About OSM Service Actions".  Identify the input parameters of each action by determining information elements.  Describe the steps in the business process (for example, work that is performed and network elements that are configured) for how each action is realized in the network.  Identify the types of resources and RFSs that drive the business process and realize the actions in the network.  Describe the administrative policies (for example, capacity management) and behaviors (for example, life cycle, searching and selecting an instance of a resource for use by a service) for how each resource is managed.  Describe how the resources can be organized in the inventory in readiness for provisioning.  For steps in the business process that involve application integration beyond what is already supported by the reference implementation, identify the interfaces and protocols for integration.
  • 42. GUIDELINES AND BEST PRACTICES Page 41 Creating New Types of Services Using the Reference Implementation Each CFS identified in the analysis can translate into the definition of a type of service. Implement types of services in the following ways:  Each element in a service-specific model cartridge must represent the data structures and properties of the service and its actions. These definitions must be consistent across every component that implements some dimension of the solution.  The OSM cartridge for the service order must have a product class with a product specification (service fulfillment pattern) and orchestration plan.  The UIM cartridge for the service inventory must have a service specification.  The ASAP service cartridge must be created for the service abstraction of network cartridges. Determine whether actions for the service can be requested on the same order as mobile service. If so, the mobile GSM solution must be extended to accommodate the additional actions; otherwise, a new type of service order must be developed using the mobile GSM solution as a basis. Creating New Service Actions Using the Reference Implementation The following sections describe common changes for developing new service actions. Actions in the Service Order The mobile GSM solution implements a service order called the MobileGSMProvisioningOrder in the MobileGSMProvisioning OSM cartridge. Creating a New Action in the Data Schema The verb or verb phrase that identifies the action is called the action code. Add the action code to the list of enumerated values for the service action. The base type is found in the Service Provisioning cartridge: TransformedServiceItemType > ServiceAction. You can define a specialization of ActionRequestType for the action at the root level of the data schema (for example, see ResumeMobileActionRequest). This request type must contain elements for all the information (for example, input parameters, output parameters, and configuration information) carried out by the service order to provision the action. You can add the action request type as a child of OrderAction defined at the root level of the data schema. Updating the OSM Order Item Specification Update the OSM order template for a new order item specification to reflect the new action request under OrderAction. Updating the OSM Order Component Specification Update the order template for any applicable order components to reflect the new action request. Updating OSM Orchestration components Add any orchestration plan changes that may be required for new actions. For example, decomposition rules, orchestration plan on the product specification, and service fulfillment function dependencies must be updated if the new action requires the orchestration plan to use a new fulfillment function. Typically, complex changes such as these are required for adding a completely new service and are not required to support new service actions.
  • 43. GUIDELINES AND BEST PRACTICES Page 42 Updating OSM Manual Tasks Update the creation task and add any relevant behaviors to support the fields in the new ActionRequest. Update the query task and fallout tasks to show any new data fields. Updating OSM Automated Tasks Update task data to include new service action data for all automated tasks invoked by the orchestration plan for the new action. Updating OSM XQuery Scripts Update the following XQuery scripts:  MobileOrderAction.xqy: Update this script to populate the fields applicable to the new action request.  GSMOrderDataLibraryModule.xqy: Add any action specific data fields to the accessor methods and shared accessor methods.  GSMInventoryLibraryModule.xqy: Add methods to access any new data returned from UIM from the processInteractionResponse. Creating New Sample Orders to Test New Service Actions Create new sample orders for testing the additional service actions. Extending Shared Libraries The mobile GSM solution includes a MobileGSMResources cartridge, where XQuery shared libraries and resources (for example, XML documents) reside. Updating the GSMLibraryModule.xqy script To update the GSMLibraryModule.xqy script: 1. In the GSMLibraryModule.xqy script, make the following edits:  Add the new action to the string constants.  Update the order data update that happens in response to the ProcessInteraction call to UIM. (Starting in function “createOrderDataUpdateForDesignInteraction”.)  Update the CaptureInteractionRequest so that the right information is sent to UIM. (Starting in the function “createItemForCaptureRequest”.)  Update the function that creates the delivery order items. (Starting in the function “createDeliveryOrderItems”.) Updating the XML Schema Update the XML schema for an order if any changes are made to the structure of the delivery order to support the new action request. (These are found in MobileGSMResources > schemas.) Updating the GSMDataMapping.xml Add the new action into the <actionMap> list to properly transform the action during the product-to-service transformation. The <pac> should be the value as it appears in the AIA order. The <sac> should be the value as it is defined in the OSM order data. (For example, DELETE vs disconnect.) Actions in the Technical Order The mobile GSM solution represents a technical order as a MobileGSMDeliveryOrder in the MobileGSMDelivery OSM cartridge. The technical order contains any number of order items, each one carrying a technical action, including its parameters.
  • 44. GUIDELINES AND BEST PRACTICES Page 43 A technical action refers to a unit of work that must be performed against the network to realize one or more elements of the service configurations. Technical actions typically act on resources and RFSs. The mobile GSM solution takes a more straightforward approach by passing the service actions from the service order as technical actions on the technical order. This simplification is possible because mobile service does not require granular control over resources; only a HLR and a VMS needs to be targeted by activation. Calculating Technical Actions The reference implementation does not provide mechanisms for performing a more advanced calculation of technical actions. The computation for service configurations that derive an advanced plan of work should be done in the inventory by analyzing the service configuration currently designed, and comparing it to the previous version of the configuration. Each difference translates into one or more units of work. The type of information involved in the difference determines what technical actions to derive. The following are hypothetical examples:  Derive two add Video Receiver technical actions when adding two video receivers to the configuration. The orchestration plan for these technical actions can generate functions for ship Video Receivers and register Video Receivers into CPE Management System. Perform both functions by collecting the two items into one order component so that a single activity performs the function on both items at the same time (see §Grouping Related Work).  Derive two remove Video Receiver technical actions when a video receiver has been removed from the configuration.  Derive a change Mobile Subscriber on HLR technical action when the Caller ID feature has been enabled and the Call Waiting feature has been enabled on the configuration. In the reference implementation, the Calculate Delivery Plan task has a place holder for automating the calculation. In the absence of complex delivery scenarios that are more complicated than executing an activation order, this place holder completes the task by doing nothing. The Create Delivery Order Task provides an XQuery script that performs a one-to-one mapping from the service actions to the technical actions. Complex scenarios require stateful inventory information (such as for those examples described above) to resolve dependencies and references that go across orders, services, and the complex relationships among resources (for example, device interfaces are contained by a logic device, and they can be pooled for administrative purposes according to point of presence). To meet these requirements, OSM can call a Web Service operation on UIM to do this calculation, but this Web Service operation must be developed as an after-market solution component until such time as UIM provides it. Adding Technical Actions in the Data Schema Add actions into the list of enumerated values for the service action on both the incoming order and the order item. (To do this, go to: OrderAction>ActionCode and DeliveryOrder>DeliveryOrderItem>ServiceActionCode). Define a specialization of ActionRequestType request for the action. This request type must contain elements for all of the information (input parameters, output parameters, and configuration information) carried by the technical order to deliver that action in the network. For example, see DeliverChangeMobile. The new action request type would need to be added as a child of OrderAction. If new fields were added to the delivery order, they must be at the appropriate place in DeliveryOrder>DeliveryOrderItem>MobileSubscription. Updating Order Item Specification Update the order item spec order template to reflect the new action request under OrderAction.
  • 45. GUIDELINES AND BEST PRACTICES Page 44 Updating the Orchestration Components Update decomposition rules, the orchestration plan on the product specification, and dependencies of the service fulfillment function if the new technical action causes differences in the orchestration plan (such as using a new service fulfillment function). Typically, such complex changes are required for adding a completely new service and are not required to support new technical actions. Additionally, if the new technical action requires interaction with an external system during the delivery process (as is the case for touching the service bureau when the action is add and TNType is portedin), these entities must be enhanced. If an emulator is provided in place of that external system, the emulator must be created. Creating New OSM Activation Tasks Add the new service action and establish the request data mappings. Creating New OSM Manual Tasks Update the creation task to support the fields in the new ActionRequest. Update the query task and fallout tasks to show relevant data fields. Update OSM XQuery Scripts Update the MobileDeliveryOrderAction.xqy script. Actions in the Inventory Structural modeling of actions is not yet supported in UIM through any explicit mechanism. The actions are recognized in the auto-design rule set for the service configuration. The rules and logic expect each action on the request that attached to the business interaction (mirroring the service order) to carry input parameters that conform to their expected types (specifications). In the reference implementation, the MobileManagerImpl Java class delegates each service action to a distinct operation for processing that item of the request. These operations make use of the Java API for inventory to implement the auto-design logic. Additional utility classes found in the oracle.communications.inventory.techpack.common package provide operations to help you manipulate services, configurations, resources, and resource allocations. As you develop additional services and resources, Oracle recommends factoring code into class libraries for modularity and reuse. Actions in the Activation Order As the solution is enhanced to implement additional services and actions, you must add or enhance an ASAP cartridge to implement new actions as CSDLs. Activating Services on the Network using ASAP The mobile GSM solution activates the Ericsson HLR and Comverse VMS Insight network elements using ASAP. A communications service provider can choose to deploy a different vendor and model of device that performs an equivalent function in the network. Activating HLR Devices Deploy the ASAP cartridge for the chosen model of HLR device to the ASAP server. Do the following procedure with appropriate changes for the chosen devices: 1. Deploy the ASAP cartridge for the device. 2. Enable ASAP to manage certain types of network elements. 3. Configure ASAP with network elements and information about their management interfaces that are under the management of ASAP.
  • 46. GUIDELINES AND BEST PRACTICES Page 45 The service actions (CSDLs) in the ASAP mobile service cartridge remain unchanged. However, the HLR-related atomic actions (ASDLs) must be updated and associated with the appropriate APs from the chosen vendor-specific device cartridges for the HLRs. This includes the HLR atomic actions starting with “A_HLR” (for example, A_HLR_ACT_CAW), and the validation atomic actions starting with “A_VAL” (for example, A_VAL_GSM_ADD_SUB). The associations can be established using one of the following approaches:  Direct association: The atomic action from the service cartridge is directly associated to an AP from the vendor specific device cartridge.  Indirect association: The atomic action from the service cartridge is associated to a newly developed AP in the service cartridge, and the new AP is then associated to an AP in the vendor specific device cartridge. These two approaches are discussed in detail in the OSS Solutions Integration document. Consult that document to determine which approach is best for the chosen vendor-specific device cartridge. No changes are required to the OSM tasks or processes. Activating VMS Devices Adding support for another type of VMS device follows the same pattern as described for choosing am HLR in the preceding section. The main difference is that the VMS-related atomic actions (A_VMS and A_VAL) must be updated in the ASAP mobile service cartridge to associate to the AP in the vendor-specific device cartridge. Activating Other Types of Devices If the mobile GSM solution is enhanced to support Multimedia Messaging Service (MMS) without authorization by the HLR, provisioning must activate the service directly on the MMSC. The service actions in the ASAP mobile service cartridge must be altered with additional parameter to control the enabling or disabling of MMS. This parameter is similar to the one that enables or disables SMS. A set of MMSC-related atomic actions must be developed (A_MMS and A_VAL) to support this MMS parameter. When a particular vendor and model of MMSC is chosen in the network, the atomic actions are associated (directly or indirectly, as described in "Activating HLR Devices") to the AP in the vendor-specific device cartridge for the MMSC. Extending the Solution Installer To enhance the solution installer, you must know the Python programming language. The solution installer is a Python WebLogic Scripting Tool (WLST) script that configures application server resources into the admin server of each WebLogic domain that participates in the integrated OSS suite. This includes JMS servers, JMS destinations, SAF agents, SAF remote contexts, SAF imported destinations, and Message Bridges. Update this installer to accommodate additional SOAP/JMS Web Services that need to be integrated into the mobile GSM solution. Each SOAP/JMS Web Service requires the following updates:  A JMS system module targeting OSM, SAF Remote Context, and SAF Queue to forward request messages to the Web Service implemented by the application.  In that same JMS system module targeting OSM, a JMS reply-to destination for automation tasks to receive response and fault messages.  A SAF Agent, SAF Remote Context, and a SAF imported destination targeting the application server that hosts the Web Service. This enables forwarding of the response and fault messages in reply to OSM.  If the application being integrated also publishes events to a JMS topic, this topic requires the following application server resources: (This pattern is used to integrate the ASAP event topic with OSM.)  A JMS Queue targeting OSM for automation tasks to receive event messages.
  • 47. GUIDELINES AND BEST PRACTICES Page 46  A SAF Queue targeting the application server hosting the application being integrated to forward event messages to OSM.  A Messaging Bridge to copy event messages from the application’s Topic to the SAF Queue. Developing Product Variations of Services As variations of a service are modeled as product offerings in the product catalog, these product offerings generally do not require development work in the OSS layer, when these product offerings represent specializations of product classes that are already recognized by the customer order to service order transformation. However, when product classes are introduced into the product catalog for the first time, this requires corresponding changes to the customer order to service order transformation. See "About Customer Order to OSM Service Order Transformation." Customizing the Mobile GSM Solution The following sections describe mobile GSM solution customizations that may be required. Localizing Telephone Numbers A telephony service relies on a telephone number to identify the subscriber for directory and dialing purposes. A telephone number has a standard (E.164) format. The country code and the decomposition of a telephone number into its components (for example, area code, and subscriber) are governed by rules that are specific to the locale. These structural components and rules are encoded as a localized telephone number cartridge for UIM. The following telephone number cartridges are bundled with UIM.  Canada  Norway  Saudi Arabia  UK  US If a solution needs to accommodate another locale, you must develop an additional locale-specific telephone number cartridge using one of the existing cartridges as an example of the patterns. Here is a summary of steps to create a telephone number for a country. 1. Create a UIM Telephone Number specification. 2. Create a UIM Ruleset and define the Telephone Number format for the country. The format is defined using the “edit mask” variable. Use an existing UIM cartridge as an example. 3. Define a UIM Ruleset Extension Point to trigger the extension logic implemented in the Ruleset. The Ruleset should be associated to the SpecManager_getEditMask UIM Base Extension Point. 4. Add the Telephone Number specification to the list of Specification Options defined in the Primary MSISDN UIM Configuration Item. Localizing Geographic Addresses A service usually has relationships to geographic places (for example, service address, and point of presence). Geographic addresses generally have locale-specific formats and rules. These structural components and rules are encoded as a localized geographic address cartridge for UIM.
  • 48. GUIDELINES AND BEST PRACTICES Page 47 The following geographic address cartridges are bundled with UIM.  Canada  Norway  Saudi Arabia  UK  US If a solution needs to accommodate another locale, you must develop an additional locale-specific geographic address cartridge using one of the existing cartridges as an example of the patterns. Here is a summary of steps to create a Geographic Address for a country 1. Create a UIM Place Specification. 2. Create and add UIM Characteristics to the Place Specification for each address component. The UIM Mobile Technology pack determines the serving area based on the value of the US zip code. This logic should be customized to determine serving area based on criteria that depend on the locale. OSS Solution Development Methodology The following sections describe OSS solution development methodologies. Roles and Skills Required for OSS Solution Development Table 8 lists and describes roles and skills required in an OSS solution development project team. Table 8 – Roles in Project Team Role Skills Responsibilities Project Manager  Project Management  Plans, coordinates, and tracks all of the solution development work. Network Expert  Network Subject Matter Expert  Requirements Analysis  Must have knowledge of how services are realized in the network.  Must have knowledge of the management interfaces for provisioning services onto devices in the network. Fulfillment Expert  BSS/OSS Subject Matter Expert  Requirements Analysis  Must have knowledge of the end-to-end business processes for how each product action is fulfilled, including how service actions are provisioned in the network. OSS Solution Architect/Designer  BSS/OSS product, service, and resource modeling  Requirements Analysis  Must apply the service provisioning solution architecture, best practices, and guidelines to design the service provisioning solution that integrates all the various components to realize the end-to-end business processes.  Must coordinate the partitioning of the solution into common and application components.  Must provide design coordination across application components for consistent definitions of services, resources, and their actions.  Must coordinate the definition of integration points between OSS applications including the Web service interfaces and JMS integration.  Must coordinate the definition of the Design Studio common data model for the solution. ASAP Solution Developer  ASAP service modeling  ASAP device modeling  Java  Must implement service actions as network actions that apply configuration changes to specific devices through their management interfaces.  Must design, code, and test (unit and integration) the components that will be deployed to ASAP. OSM Solution Developer  OSM order and workflow  Must implement service actions and their design and delivery
  • 49. GUIDELINES AND BEST PRACTICES Page 48 modeling  OSM task automation  XQuery behaviors.  Must implement transformations from product actions to service actions.  Must design, code, and test (unit and integration) the components that will be deployed to OSM. UIM Solution Developer  UIM service and resource modeling  UIM service configuration auto-design and resource auto-assign  Drools  Java  Oracle PL/SQL  Must models services and their configurations with respect to resources.  Must implement service actions and their auto-design behaviors.  Must design, code, and test (unit and integration) the components that will be deployed to UIM. Release Engineer  Ant  Test Automation  Manages the solution development and test environment.  Automates the building and packaging of the solution and cartridges.  Automates solution testing. OSS Solution Tester  ASAP, OSM, UIM setup and administration  ASAP, OSM, UIM user interface  Test automation  Must design and code the system test cases (end-to-end scenarios) that will be executed against the integrated solution.  Must execute the system test cases.  Must report bugs.  Must evaluate quality metrics for readiness to deploy. Oracle Communications Design Studio Concepts has a description of the Design Studio Roles that complements the roles described in Table 8 and also provides more details for some roles. The role of the OSS Solution Architect can be divided into Data Modeler for the solution and Solution Designer. The role of an application level developer can be divided into application level Data Modeler, Cartridge Designer, and Developer. A project team can be composed of team members who can take on multiple roles; Table 8 does not imply a one-to-one relationship between an individual and a role. Depending on the project, the work break-down can require only a single person to take on multiple roles or it can require multiple people per role. For example, one work break-down for solution development might be by application, where the team members do not have to take on multiple roles. Another work-break down might be by service action, where one team member takes on multiple roles to design, code, and test more than one application component for each service action. Table 9 shows the composition of the mobile GSM solution project team. Table 9 – Mobile Team Composition Persons Roles 1 Project Management 0.5 Network Expert Fulfillment Expert OSS Solution Architect 0.5 ASAP Solution Developer 1 OSM Solution Developer 1 UIM Solution Developer 0.25 OSS Solution Tester Engagement Model for OSS Solution Development A team for OSS solution development can also be a virtual team with representatives from the CSP and one or more Solution Integrators (SI). The below table illustrates a subset of possible engagement models. Table 10 – Engagement Model Engagement Model Description Single SI The entire solution is developed by one SI who is responsible for all the roles listed in Table 9. The CSP accepts the solution after implementation through a User Acceptance Test.
  • 50. GUIDELINES AND BEST PRACTICES Page 49 Multiple SI – Customer Managed The Project Manager, Network Expert, and Fulfillment Expert may be from the CSP. The OSS Solution Architect, ASAP solution developers, OSM solution developers, and UIM developers can be one or more SIs. Multiple SIs – SI Managed The CSP interfaces with a single SI who provides a Project Manager, Network Expert, and Fulfillment Expert. The OSS Solution Architect, ASAP solution developers, OSM solution developers, and UIM solution developers can belong to one or more SIs. The CSP accepts the solution through a User Acceptance Test. Project Template See "Operations Support Systems Methodology" in Design Studio Concepts for more information about project phases and associated tasks during OSS solution development Document Artifacts See "Operations Support Systems Methodology" in Design Studio Concepts for more information about document artifacts that your team can create and share among stakeholders during solution development. Design Template Table 11 lists and describes a design template of development activities and corresponding solution components involved in these activities. Table 11 – Design Template Development Activity Solution Component Description Identify type of service common What is the customer-facing service that is being provisioned? Give this service a name that is precise and meaningful. For example, Mobile. Create a model cartridge for this service domain. This data schema is used to define data elements that are shared among the various solution components. Identify service actions common What are the actions that a customer can order for a service? Give each action a name that is precise and meaningful. For example, Add, Change, Suspend, Resume, and Disconnect. In the data schema, define a data element to represent each service action. Each of these elements carries the definition of its signature in terms of its input parameters, output parameters, and configuration information needed to drive the provisioning process. Define service action signature common What customer-facing information needs to be input from Order Capture or enriched by the OSM COM prior to provisioning? In the data schema, under the service action element, define a child element for each input parameter. What customer facing information needs to be output from provisioning for communicating to the customer or the CRM? In the data schema, under the service action element, define a child element for each output parameter. Define service action OSM Edit the order template for the service order to add the service action signatures as order actions.
  • 51. GUIDELINES AND BEST PRACTICES Page 50 Define service inventory model UIM Define the type of service as a service specification. Define a configuration specification for the service. Define configuration items for organizing and representing all the configuration information, including references and assignments of resources, which you need to realize the service (and the execution of its actions) in the network. If the configuration has many characteristics, consider defining service profiles with logical groupings of information, such that each instance of a service profile represents a configuration that is common to a segment of the subscriber base. This pattern exhibits storage efficiency (for better design and assign performance), and it enables policy based management of subsets of the subscriber base. Define resource inventory model UIM Define each type of resource as a specification. Edit the configuration specification for the service to associate the resource specifications as options for the appropriate configuration items. Define readiness procedures for how instances of these resources are organized in the inventory to support the design and assign logic (for example, search algorithms for selecting a resource to allocate to a service). Define service action auto-design logic UIM Define an auto-design rule set at the BaseConfigurationManager_automateConfiguration extension point. Edit the rule set to delegate each service action to a separate rule. Each rule should start with a skeleton that corresponds to the patterns for Add, Change, Suspend, Resume, or Disconnect. The allocation of resources should attempt to reuse established policies that have been encoded as Java class libraries. If additional policies are necessary, try to encode these modularly into reusable Java class libraries. Through this approach, a rich set of class libraries is built up to reduce the effort involved in developing the next type of service. Add configuration information to the service action definition common, OSM What configuration information that is produced by design and assign will need to be fed to the delivery process for realizing the service action in the network? Edit the service action definitions in the data schema to include the configuration information relevant to each action. To simplify the transformation between the UIM service configuration and the OSM service order, it is advantageous to use a common definition across UIM specifications (for example, service profiles) and the OSM order template through the data schema. Edit the order template of the service order to include the expanded definition of the service actions. Define service action design orchestration OSM Define the orchestration of the service order (based on the Mobile provisioning order) to perform the design and assign functions appropriate for each service action. This should follow the established pattern of calling captureInteraction, processInteraction, and updateInteraction to approve the design. In addition to these functions, if other applications need to participate, the Pre-Design and Post-Design functions are placeholders for where such additional applications would be integrated into the workflow. Edit the task data (view) for each task to include the service action parameters and configuration information that are relevant to the provisioning of that action. Create an XQuery library with functions that encapsulate the transformation between the service order and the UIM representation of inventory entities (for example, services, resources). Edit the XQuery script for sending the captureInteraction request to call the functions from the library to populate the request with the service action input parameters. Edit the XQuery script for sending the processInteraction response to call the functions from the library to update the service order with the configuration information produced by auto-design. Define service action delivery orchestration OSM Define the orchestration of the technical order (based on the Mobile delivery order) to perform the delivery functions appropriate for each service action. This should follow the established pattern for calling createOrderByValue to submit an order to ASAP for execution. Define activation service model ASAP Define a CSDL for each service action. Use the service action definition from the data schema to define the CSDL parameters. Define activation command mapping ASAP
  • 52. GUIDELINES AND BEST PRACTICES Page 51 Define activation task mapping OSM Edit the activation task to define the mapping from the service order to the CSDLs. The configuration information elements would map to the parameters of the CSDL for each service action. Define customer order to service order transform OSM Add JMS integration to solution installer installer Edit the solution installer WLST script to add any additional JMS modules, JMS reply-to destinations, SAF resources, and Message Bridges to integrate with other applications and SOAP/JMS Web Services beyond those already supported by the reference implementation.
  • 53. GUIDELINES AND BEST PRACTICES Page 52 Performance Considerations The following sections provide performance recommendations and considerations. Oracle Database RAC Load balancing across an Oracle Real Application Cluster (RAC) database enables an application to distribute its transaction processing across the nodes of the cluster to achieve near linear horizontal scalability. However, an application must be implemented with RAC in mind, such as applying partitioning in a way that is most appropriate to the application behavior, to avoid major performance degradation of inter-node communications overhead associated with synchronizing data updates across the cluster. The OSS suite of applications has implemented such optimizations, although the nature of the transaction processing does incur some degree of inter-node communications. For example, two RAC nodes do not perform at twice the transaction throughput as a single node. Deploy RAC if you require high availability rather than horizontal scalability. Design Intelligence versus Transaction Throughput Tradeoffs One activity in provisioning is design and assign. The structure of the service configuration is important for design and assign performance. The degree of complexity exhibited in configuration items has a direct impact on the database storage requirements for the service configuration and transaction throughput. Greater complexity degrades transaction throughput. The following list provides information about sources of complexity for designing service configurations:  Each configuration item on a configuration adds a small performance cost.  Each characteristic on a configuration adds a small performance cost.  Each resource that must be life cycle managed (installed or uninstalled) and tracked on a configuration adds a large cost, growing with the complexity of the resource itself with respect to its characteristics, relationships to entities, and its configuration (such as, for a network, pipe, or place), if any.  Each resource that must be selected and assigned, or unassigned and aged for reuse adds a large performance cost, growing with the search complexity of selecting a resource.  Each resource that must be selected and referenced or unreferenced adds a large performance cost, growing with the search complexity of selecting a resource.  Each service profile that must be selected and referenced or unreferenced adds a large performance cost, growing with the search complexity of selecting a service profile.  Each RFS that must be managed on a configuration adds a large performance cost. There are special considerations, which are addressed separately in "Resource Facing Service ." The complexity of a search is affected by the following:  The number of relationships traversed to arrive at the result. Counting as traversals are joins, self-joins, sub-queries, and using the result from one query as a term in the next.  The number of characteristics to be matched. Characteristic matching is not able to take advantage of indexes. There are tradeoffs between maintaining a rich, accurate representation of the network versus minimizing the computational and storage cost of performing the design and assign of the configuration when modeling a service, its configuration, its resources, and RFSs. Reduce complexity in the model of the service configuration to achieve higher order throughput. To minimize complexity, reduce the configuration to only the information necessary to derive the work and realize the service actions in the network. For example, factoring information into service profiles is a good technique for reducing complexity while maintaining a sophisticated model of configuration information. These service profiles can be pre-fabricated in readiness before services are ordered and provisioned. This method assumes that it is possible to define service profiles, which represent classes of service or
  • 54. GUIDELINES AND BEST PRACTICES Page 53 subscribers who share an identical set of configuration information. During order execution, the design and assign logic would only need to select a service profile corresponding to the desired class of service or subscriber. When making these tradeoffs, keep in mind that as the model is reduced in complexity, the loss of richness may result in loss of functionality (likely unrelated to provisioning). With a less faithful (or more abstract) representation of the configuration information and resources in the network, there may not be enough detail maintained in the inventory about the service to support other areas of the service provider’s business, such as service assurance or the analytics against the subscriber base to support trending, forecasting, and planning network build-outs to satisfy future demand. Consider business requirements and priorities carefully in making the proper tradeoffs (design intelligence versus order throughput). Resource Facing Service Modeling Approach Tradeoffs An RFS is a service that is used as a resource that is embedded as an item of the configuration for a CFS. There are two approaches for modeling an RFS. Each approach has merits and drawbacks when considering functional and performance qualities. Table 12 lists and describes the RFS modeling approaches. Table 12 – Resource Facing Service (RFS) Modeling Approach 1 Approach 2 Name Hierarchy Embedded Description An RFS is represented as a service instance and assigned to a CFS. An RFS has a configuration of its own. Together the CFS and its RFSs form a hierarchy of services and configurations. An RFS is represented as a pattern of configuration items embedded in the configuration of the CFS. Together the CFS and its RFSs form a single configuration and carry the union of configuration items. When Applicable  The RFS can have a life that is decoupled from the CFS and other RFSs.  Service adds and disconnects do not dominate the order mix.  Service change actions dominate the order mix.  The RFS has a life that is constrained by the life of the CFS.  Service adds and disconnects dominate the order mix.  Service change actions do not dominate the order mix. Advantages  The RFS can be found by searching for a service.  Changes that affect only the configuration of an RFS remain isolated to the RFS.  Lower computational and storage overhead for minor changes.  A single business interaction incurs the minimum of overhead for coordinating the design and assign of the configuration for the CFS and all its RFSs.  Lower computational and storage overhead for adds and disconnects. Disadvantages  Each service instance (CFS or RFS) incurs a significant cost in terms of fixed overhead with respect to a business interaction to coordinate the design and assign of its configuration.  Higher computational and storage overhead for adds and disconnects.  The RFS cannot be found by searching for a service.  Changes that affect the configuration of an RFS require the entire configuration of the CFS and all its RFSs to be copied to a new version.  Higher computational and storage overhead for changes. When developing an RFS, use the following principles:  Define a service specification and a configuration specification for the RFS in support of Approach 1. If Approach 2 is chosen, these specifications are not used at run time.  Define the configuration items (structures) that appear on the service configuration, regardless of whether it is the configuration of the RFS (Approach 1) or the CFS (Approach 2).  Define the design and assign logic to expose an interface that is capable of processing the service actions against a configuration, where the configuration items appear in the expected pattern, regardless of whether the configuration is for the RFS (Approach 1) or the CFS (Approach 2). This allows the same logic to work for both approaches.  Define an artifact (properties file) as a configuration resource with a property that controls whether Approach 1 or Approach 2 is chosen for deployment.
  • 55. GUIDELINES AND BEST PRACTICES Page 54  Define the CFS and its configuration to reflect the chosen approach. If Approach 2 is used, code the design and assign logic for the CFS to directly call the design and assign logic for the RFS (passing the configuration of the CFS). In the mobile GSM solution, the voice mail service, its configuration, and its design and assign logic are a good example of how an RFS is developed according to these principles. Transaction Boundary Tradeoffs The design and assign logic for service configurations with higher complexity must interact with many configuration items, characteristics, resources (and RFSs), and their assignments or references. The more information that needs to be touched within the same transaction, the more locks must be held in the database for concurrency control, and also the more time the transaction must remain open, holding those locks. The more locks held by the same transaction, the greater the risk for concurrent threads of order execution to deadlock or roll back heuristically. The longer these locks are held by a transaction, the slower other concurrent threads of order execution runs due to lock contention and the consequent transaction serialization. The following considerations list tradeoffs for developing optimal transaction boundaries (points in the design and assign logic where the open transaction is committed and a new transaction is started):  Smaller transactions with more frequent commits take more time to execute end-to-end. Order execution can be delayed while waiting for the commits to flush to storage.  Do not make transactions too small, such that the work performed within a transaction no longer constitutes a logical unit of work.  Larger transactions allow more work to be done before flushing to storage on commit. Order execution delays are improved by deferring input/output until more work is ready to be committed.  Larger transactions hold more locks, and this results in greater lock contention. Order throughput suffers due to concurrent threads of execution having to wait for locks (transaction serialization). Balancing these opposing forces requires careful consideration. The design and assign logic for each service action must identify the logical units of work. Combine several logical units of work into the same transaction to improve order execution latency. The transaction should not be so big that it impairs concurrency and risks deadlock. A great deal of performance and scalability testing must be done at significant load and with concurrency to validate these decisions. Security Considerations The following sections provide security recommendations and considerations. Selecting an Authentication Provider The OSS suite of applications relies on the WebLogic Server security realm for authentication. The system administrator should decide at deployment time how the security realm is configured with respect to authentication providers. By default, WebLogic Server implements an embedded LDAP repository of users, passwords, and groups. A production environment may need to be configured with an authentication provider that delegates to an enterprise identity management system. Enabling Transport Layer Security Transport Layer Security (TLS) for HTTPS and T3S should be enabled to support secure channel communication. This protects sensitive information, such as user names and passwords, from being exposed to network traffic monitoring tools. Some types of information that applications use can also require this privacy, such as social security numbers, credit card numbers, and customer addresses. Enabling secure protocols does not force users to use them. Browser-based users should be directed to URLs that use the HTTPS protocol. Applications should be integrated using Web Services over transports based on the HTTPS and T3S (for JMS) protocols. See Oracle Fusion Middleware Securing Oracle WebLogic Server - Setting Up SSL: Main Steps.
  • 56. GUIDELINES AND BEST PRACTICES Page 55 Web Services Security Policy The applications deploy a default WS-Policy attachment with WS-SecurityPolicy assertions that require authentication through a user name and clear text password token. Although no assertion is declared to ensure the transport is encrypted (for example, over TLS), deploy a production environment with TLS enabled, and ensure all URLs (see "Configuring the Mobile GSM Solution Installer") use a TLS-enabled protocol (for example, HTTPS or T3S). An encrypted transport is essential for protecting the clear text passwords from being compromised. TLS is recommended over message encryption due to performance considerations. Several server platforms provide hardware acceleration of encryption and decryption for TLS, and message encryption is unlikely to take advantage of hardware acceleration. Maintaining an OSS Solution The following sections provide information about maintaining an OSS solution. Upgrading Cartridges While developing the solution, you can use as-is certain cartridges supplied by Oracle, while making modifications to others; or use source code and models from Oracle-supplied cartridges as the basis. When upgrading the Oracle-supplied software (applications and cartridges), the cartridges used as-is are the least complicated to upgrade. Oracle tries to maintain backward compatibility, so that upgrades do not break third-party components that are developed to use it. Known issues, including compatibility issues, are documented to assist in resolving such issues. In some cases, such compatibility issues can require a data migration during the upgrade, and this data migration must be incorporated into the plan for deploying the upgraded solution to the production environment. If Oracle-supplied cartridges have been modified or cloned and extended, Oracle recommends that all solution components (cartridge projects) are maintained in a software configuration management (SCM) system (see "Error! Reference source not found."). Oracle recommends always using SCM for every project, as a good software development practice. However, when modifying or cloning and extending Oracle-supplied cartridges, this practice is especially important, so that differences can be calculated between versions of the same artifacts or derivations (branches). When upgrading to a new release of the Oracle-supplied reference implementation, you must first identify the artifacts that have changed. Choose a differencing tool for this task. For example, WinMerge for Windows users, diff for Unix users (including cygwin for Windows). Not all of the folders in a cartridge project need to be checked for updates. The comparison can be limited to the following directories:  /dataDictionary  /model  /resources  /samples  /schemas  /src  /xmlCatalogs – specific to OSM Running a comparison on each of these folders identifies the files that have been changed. When a changed file is identified, the next step is to do a “diff” on the individual file versions to identify the lines that have changed. Any changes need to be reconciled and merged to create a new file version. The diff tool for UNIX is capable of producing differences in a format that is suitable for merging the differences into the modified or extended artifact through the patch tool. (See Comparing and Merging Files.) Using diff and patch is suitable for source code for Java, XQuery, Drools, and most other textual programming languages. However, XML documents (for example, model artifacts for Design Studio) cannot
  • 57. GUIDELINES AND BEST PRACTICES Page 56 be saved with “pretty” line breaks, which are not considered significant between many tags. There are XML specific differencing tools for this purpose. For XML documents representing model artifacts (for example, OSM order definitions, OSM process definitions, UIM service specifications) use an XML diff to visually inspect the changes, and mimic those same changes using the appropriate editors in Design Studio. Textual or XML merge tools are not appropriate for editing the model artifacts; such tools should be used only for source code that is written in a textual programming language. Deploying OSS Suite Applications This section covers the various deployment configurations that can be used to set up a server environment for the OSS suite applications. See also "Packaging an OSS Solution See "Design Studio Packaging and Integrated Cartridge Deployment" in Design Studio Concepts for information about packaging and deployment of an OSS solution. OSS Solution Development Desktop" and "Error! Reference source not found." for other considerations. Deploy cartridges using Design Studio during solution development and use a cartridge deploy script or tool for deploying to production. Database Server Deployment ASAP 7.2, OSM 7.2, and UIM 7.2 reside on a single database instance with distinct schemas for each application. The applications have been tested to run properly with a common set of configuration parameters to enable co-residency in the same database instance. The applications can be deployed on separate database instances, if that is preferred for administrative reasons. The applications can be deployed with Oracle Database Enterprise Edition in a single database node or with RAC on multiple nodes. Deploying OSS Applications into a Single Database A database server running as a single node without RAC is a low-cost database deployment configuration. However, this option forgoes the following benefits:  Horizontal scalability: The ability to increase transaction processing capacity by adding nodes to a cluster.  High availability: The ability to transparently fail over database access to a redundant node in a cluster.  Load balancing: The ability to transparently distribute database transaction processing (client connections) across nodes in a cluster. If you choose to start with a low-cost initial deployment configuration that is also capable of expanding in future to accommodate larger scales, high availability, and load balancing, a single node RAC environment is a good option. This enables a natural path to expanding to multiple RAC nodes, as necessary. A single node cluster is functionally equivalent to deploying a single non-clustered server. The only difference is extra license cost to enable RAC. Deploying OSS Applications into a RAC Database Database servers running with RAC enabled are capable of horizontal scalability, high availability, and load balancing. The OSS suite applications have been optimized to take advantage of RAC through partitioning, which enables transaction processing to incur less inter-node communication, which is a major performance consideration. Application Server Deployment The application servers that host ASAP 7.2, OSM 7.2, and UIM 7.2 can be configured to share a single administrative domain. Alternatively, a separate administrative domain can be dedicated to each application.
  • 58. GUIDELINES AND BEST PRACTICES Page 57 The application server deployment configuration is independent of the database deployment configuration. Although RAC is not required to support application server clustering, the need for server redundancy at each layer is usually motivated by availability requirements that apply at every tier of the architecture. Deploying OSS Applications to a Single Domain Figure 15 shows the OSS applications deployed to a single domain. In this example, cartridges are deployed from a desktop using Design Studio, which is recommended during solution development but not for a production environment. Figure 15 – Single Domain Deployment When all applications reside in the same administrative domain, the following application server services are shared:  Administrative server: The same administrative server administers all managed servers through a single centralized administrative console. Domain level log messages are collected and monitored on this administrative server.  Security realm: The same authentication and authorization provider enables the same repository of users, groups, roles, and authorization policies to be shared across applications. A single domain is preferred over a multiple domain deployment to minimize complexity and for ease of administration. Deploying OSS Applications to Multiple Domains Figure 16 shows the OSS applications installed on separate domains. Figure 16 – Multiple Domain Deployment
  • 59. GUIDELINES AND BEST PRACTICES Page 58 When applications reside each in their own distinct administrative domain, they do not share a common administrative server and security realm. It is possible for two of the applications to be deployed in one domain, while the other application is deployed in a second domain. The motivation to deploy the applications across multiple domains is driven by the need for isolating applications and their servers, because of non-technical concerns, such as how roles and responsibilities are separated across the service provider’s organization. Deploying OSS Applications to Application Server Clusters OSM and UIM can be configured independently to target an application server cluster (instead of a single application server). ASAP does not support application server clustering; it should target a managed server. By targeting a cluster, the following additional benefits become available:  Horizontal scalability: The ability to increase computing capacity by adding nodes to a cluster.  High availability: The ability to transparently fail over application processing to a redundant node in a cluster.  Load balancing: The ability to transparently distribute load (client connections) across nodes in a cluster. The lowest cost option of deploying an application on a single application server can scale only to the hardware limits of the single node. This option is not capable of transparent fail over or load balancing. This option is appropriate for small scale test environments, non-mission-critical deployments, such as for solution development, a proof of concept, or a demonstration or trial. This option is not appropriate when an availability of 99.999% or higher is required. Application server clustering of multiple redundant nodes is necessary for transparent failover, which is essential to achieving availability of 99.999% or higher. If the choice is to start with a low cost initial deployment configuration that is also capable in future of expanding to accommodate larger scales, high availability, and load balancing, the application can target a single node application server cluster. Because the cluster configuration is already set up, the cluster can easily be expanded with additional nodes at a future date to accommodate larger scale, higher availability, and increased load. (Note that a single node cluster is functionally equivalent to deploying a single non-clustered managed server. The only difference is extra license cost to enable clustering in the application server.) Figure 17 shows the OSS applications installed on separate domains with a RAC database and WebLogic clustering enabled.
  • 60. GUIDELINES AND BEST PRACTICES Page 59 Figure 17 – High Availability Deployment Deploying the Mobile GSM Solution The steps for deploying the service provisioning solution into the server environment and solution development desktop are detailed in Oracle Communications OSS Mobile Solution Uptake Guide. The following is a summary of the major steps: 1. Deploy the database (see the Database Server Deployment section). 2. Deploy the application server (see the Application Server Deployment section). 3. Install the OSS suite of applications (ASAP, OSM, UIM) according to the installation guide for each application. 4. Install Packaging an OSS Solution See "Design Studio Packaging and Integrated Cartridge Deployment" in Design Studio Concepts for information about packaging and deployment of an OSS solution. 5. OSS Solution Development Desktop. 6. Install ASAP cartridges (network and service) for the solution. 7. Install UIM cartridges (base and service) for the solution. 8. Run the solution installer for the solution-specific application server resources (see "Configuring the Mobile GSM Solution Installer" section). 9. Install OSM cartridges (and emulators for testing) for the solution. 10. Execute the readiness procedures to load the solution-specific seed data into the inventory. 11. Execute the readiness procedures to load the solution-specific configuration (network elements under management) into ASAP. The above steps for the OSS suite of applications do not include additional steps that might be required to integrate into the provisioning function of OSM COM.
  • 61. GUIDELINES AND BEST PRACTICES Page 60 Configuring the Mobile GSM Solution Installer Before you run the mobile GSM solution installer, configure it with the environment details for each OSS application that is integrated. This includes the file system location of each WebLogic domain, administrative account information for configuring application server resources, the URL for accessing the application server, and deployment targeting information. See the discussion about the mobile GSM solution installer in Oracle Communications OSS Mobile Solution Uptake Guide for a full description of each property, and detailed procedures for performing a full deployment of the mobile GSM solution. If the solution has been extended to integrate with additional applications and/or Web Services, the solution installer must be enhanced to set up the application resources that support the integration. For more information, see "Extending the Solution Installer" section. Troubleshooting The following sections provide troubleshooting information. Troubleshooting ASAP The following sections provide ASAP troubleshooting information. Initialize the Environment Before running any of the ASAP diagnostic tools, you must first log in to the ASAP server and source the ASAP Environment_Profile file: # cd <ASAP_DIR> # . Environment_Profile Run asap_utils for a List of Existing Work Orders Run asap_utils option 1 to see the status of all work orders in the ASAP system to start debugging a failed work order. The results can be sorted numerically so that they appear in chronological order: # asap_utils -d 1 | sort –n Search the WO_ID column to find the row that corresponds to the work order that you are trying to debug, and then find the associated status from the WO_STAT value. For example, below is the output for a work order called JSRP-1000 that is in state 253: SRQ_ID WO_ID WO_STAT SRQ_STAT LAST_HOST_NE PRIO DUE_DATE ACT COMP_DATE 2 JSRP-1000 253 13 TEST_DEV 3 12:00:00PM C 11:55:50AM The order is typically in one of the following states:  102: WO_INIT: The work order is in the Initial state waiting provisioning.  103: WO_IN_PROGRESS: The work order is currently being provisioned.  104: WO_COMPLETE: The work order has been completed.  253: WO_FAILED: The work order provisioning has failed.  255: WO_TRANSLATION_FAIL: The work order translation failed in the SRP. See ASAP Developer’s Guide for a complete list of error codes. State 102 – WO_INIT If the work order is stuck in the initialization state, it usually means that the work order has been scheduled for a future time that has not yet arrived. Wait a few more minutes to see if it completes or check the scheduled date using the following SQL:
  • 62. GUIDELINES AND BEST PRACTICES Page 61 # echo "select SCHED_DTS from tbl_wrk_ord where WO_ID like 'WO_ID';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` where WO_ID is the work order ID that you are debugging. For example: # echo "select SCHED_DTS from tbl_wrk_ord where WO_ID like 'JSRP-1000';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` SCHED_DTS 20111201 12:00:00 State 103 – WO_IN_PROGRESS If the work order is stuck in the in-progress state, it usually means that ASAP is not connecting to the target Network Element (NE). You can run asap_utils option 7 to see the current status of the NEs: # asap_utils -d 7 If the State column continuously shows a value of “Connecting” for the associated NE, it confirms that there is an issue. In most test systems, ASAP runs in loopback, which means NE connection errors are not expected. However, this problem can still occur if the production mode setting (for example, ‘PROD’ or ‘TEST’) selected during the ASAP installation does not match the mode used during NE configuration. Check this by comparing the value of the ASAP_SYS environment variable with the values in the TBL_ASAP_SYS.ASAP_SYS column in the SARM database: # echo $ASAP_SYS TEST # echo "select ASAP_SYS from TBL_RESOURCE_POOL;" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` ASAP_SYS TEST TEST ... If the values in the database do not match the $ASAP_SYS environment variable, update the database and restart ASAP. State 104 – WO_COMPLETE If the work order was successful, no further action is required. However, if you want more details about the processing of the work order, you can use the diag_merge tool, which is explained later in this section. State 253 – WO_FAILED If the work order failed, use the following query to see the reason: # echo "select FAILURE_REASON from tbl_wrk_ord where WO_ID like 'WO_ID';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` where WO_ID is the work order ID that you are debugging. For example: # echo "select FAILURE_REASON from tbl_wrk_ord where WO_ID like 'JSRP-1000';" | sqlplus $SARM_USER/`GetPassword $SARM_USER 2` FAILURE_REASON FAIL:The following validation errors have occurred: Parameter CALLER_ID must be 'Y' or 'N' (received: Yes); If the returned failure reason is empty or does not contain enough information to determine the cause, the diag_merge tool can be used to investigate in more detail. The diag_merge tool is described in more detail later in this section.
  • 63. GUIDELINES AND BEST PRACTICES Page 62 State 255 – WO_TRANSLATION_FAIL Translation failures usually occur when the ASAP service model has not refreshed completely. Make sure that all of the necessary cartridges are deployed successfully and that ASAP has restarted. If the problem persists, make sure that the work order contains the proper CSDL name. ASAP Logging There are two types of log files in ASAP:  Log files  Suffix: *.log  Location: $ASAP_BASE/DATA/logs  Ex: $ASAP_BASE/DATA/logs/SARMENV1.log  Diagnostic files  Suffix: *.diag  Location: $ASAP_BASE/DATA/logs/<DATE>  Ex: $ASAP_BASE/DATA/logs/20111101/SARMENV1.diag In most cases, it is best to go directly into the diag files because they contain more details about individual work orders. However, it can be difficult to trace the flow of an order because the messages can jump back and forth between different files as the processing of a work order switches between various components in ASAP (for example, SARM to NEP to JNEP to NEP, and so on). For cases like this, it is easier to use the diag_merge tool to help consolidate the diag messages. The diag_merge Tool The diag_merge tool simplifies debugging by consolidating all of the diag messages for a work order into a single file, and the messages are sorted in chronological order. Run it by entering: # diag_merge DIAG_DIRECTORY OUTPUT_FILE SEARCH_PATTERN For example, you can use the work order ID as the search pattern: # diag_merge DATA/logs/20111101 diag.txt JSRP-1000 The resulting output file typically contains enough information to determine why a work order succeeded or failed. If it does not, manually search the log or diag files for other messages that do not contain the work order ID in them. Troubleshooting OSM The following sections provide OSM troubleshooting information. OSM Logging When developing a service provisioning solution, a large proportion of the effort is spent on task automation. Debugging service order execution and task automation in particular often involves tracing the steps through server-side logging. To enable logging at finer levels of detail, the log levels of individual automators can be edited to produce more detailed output about the request and reply messages they send and receive. A copy of the request and reply message is logged at severity level “debug”. See the following sections of Oracle Communications Order and Service Management System Administrator's Guide:  Monitoring and Managing OSM o Configuring the log4j.xml file o Configuring Log Levels Temporarily
  • 64. GUIDELINES AND BEST PRACTICES Page 63 OSM Frequently Encountered Problems This section describes the following frequently encountered OSM problems:  Order gets created but you cannot open the order with any view SOLUTION: a. In Design Studio, open the Order specification and go to the Permissions tab. b. Add your role, and then go to the Query tab. c. Add a view that contains the data you want to see.  Order gets created, you see the order data populated but control data is not populated and there is no orchestration plan. Additionally, the left panel of the screen contains no order items. SOLUTION: In Design Studio, open the orchestration plan and look at the order item selector. This namespace should match the namespace in the incoming order. It should then specify the element that corresponds to the order item. Also check the order item specification and make sure that the definition for each item property has the same namespace defined and is operating on the input message.  Orchestration plan gets created but only gets to the first step of generic function grouping. SOLUTION: Check the product specification and make sure ONLY the functions are selected and not the genericFunction grouping. If the grouping is selected then it needs to be selected in the decomposition rule as well.  Message is sitting in the response queue, but OSM does not deliver it to the automator SOLUTION: In Design studio, the response plugin has the Message Property Selector set by default. Remove this and redeploy. (for example, %{DEFAULT_MESSAGE_PROPERTY_SELECTOR} )  When you open up an order in the UI to view the details, you get a null pointer error and you cannot see the data tab. SOLUTION: Check the order-permissions tab to see if your role is there. Also, on the query tab a view should be set with all three check boxes ticked. This view should contain all possible data. Go and check this view to make sure it contains everything, including the orderItemRef child elements in the ControlData  When using emulators, the message is sitting in the external system request queue, but external system is not picking it up. SOLUTION: Check the weblogic-ejb-jar.xml file of the emulator project and make sure the request queue name is correct.  When trying to submit an order, if you get an error “cannot find node with mnemonic [foo]”, chances are the specified element is missing from the order creation task. ControlData/OrderItem is created correctly (as seen in the WebUI), but in the left panel there are no order items showing and no orchestration plan. SOLUTION: Turn on debug level logging for all orchestration.generation classes and look closely at the ControlData/OrderItem that gets created. There might be something wrong with one of the order item specification properties.  Your cartridge builds without errors, but you get a deployment error. SOLUTION: Undeploy your existing cartridge first. Then try to deploy again.  Order gets submitted properly but completes immediately without decomposing into any fulfillment functions. Order items are also created accurately. SOLUTION: Check the orchestration stages have their dependencies set.  WebLogic error: com.mslv.oms.automation.AutomationException: com.mslv.oms.security.OSMSecurityException: ORA-20098: Specific task is not assigned to workgroup. SOLUTION: In the OSM Administrator, add the oms-automation user to your workgroup.
  • 65. GUIDELINES AND BEST PRACTICES Page 64 Troubleshooting UIM The following sections provide UIM troubleshooting information UIM Logging Edit the log4j.xml configuration file, found in the wls_domain_home/UIM/config directory, to enable messages to be logged from the Web Services, Java API, extensibility, and rule set subsystems: <logger name="oracle.communications.inventory.api" additivity="false"> <level value="error" /> <appender-ref ref="stdout"/> <appender-ref ref="rollingFile"/> </logger> <logger name="oracle.communications.inventory.sfws" additivity="false"> <level value="error" /> <appender-ref ref="stdout"/> <appender-ref ref="rollingFile"/> </logger> <logger name="oracle.communications.inventory.extensibility.rules" additivity="false"> <level value="error" /> <appender-ref ref="stdout"/> <appender-ref ref="rollingFile"/> </logger> <logger name="RuleSetLogger" additivity="false"> <level value="error" /> <appender-ref ref="stdout"/> <appender-ref ref="rollingFile"/> </logger> The level can be set to one of (in increasing level of granularity and verbosity): off, fatal, error, warn, info, debug, trace, or all. Troubleshooting Web Services The following sections provide Web Services troubleshooting information. Logging JSM Messages When developing additional Web Services (for example, for UIM) or debugging the message delivery for integrating applications into the solution, it is sometimes necessary to capture the request and reply messages so that they can be examined for problems. This can be done using the WebLogic admin console by editing the SAF imported destinations and JMS destinations to enable messaging logging. The following should be enabled for each destination:  Enable Message Logging  All Headers  All Properties  All Body – this enables logging of the SOAP message, which carries all the interesting content. Oracle recommends that message logging be enabled for the following destinations.  Each SAF Queue that forwards to a Web Services request queue.  Each JMS reply-to destination and event destination on which an automated task receives messages. The logged messages can be found in:  domain/servers/managed_server/logs/jmsServers/jms_server/jms.messages.log  domain/servers/managed_server/logs/safagents/saf_agent/jms/jms.messages.log Message logging should not be enabled normally in production, because of its unlimited storage overhead and the high cost of serializing the messages and input/output overhead. This technique is useful to diagnose basic integration problems and
  • 66. GUIDELINES AND BEST PRACTICES Page 65 functional problems, where incorrect information is being communicated across applications, but message logging should be enabled only when testing with the execution of a single order at a time. When multiple orders are executed, it is very difficult to inspect the logs to match each message with its order and task contexts. WebLogic Infrastructure Logging When developing additional Web Services, it is sometimes necessary to debug problems that are deeply buried in the implementation code. It can be useful to enable logging within the Web Services infrastructure of WebLogic Server. Do this by editing the managed server startup scripts to append the following system property to the JAVA_OPTIONS environment variable. -Dweblogic.wsee.verbose=* Troubleshooting Order Execution When a server order encounters a problem, execution can be redirected to an error handling task; or execution does not progress beyond some automated task. See "Handling Errors in OSM Service Order" for information about how to resolve problems encountered during service order execution. In the course of diagnosing a problem from an error handling task, do the following: 1. Determine which task failed. In Process History, look for a task that completes with a failure status, resulting in the transition to the current error handling task. 2. Inspect the service order in the Order Editor. The error code and reason are usually informative. This is probably enough information to determine whether the problem is due to the information input from the customer order, or the problem is caused by the processing in a downstream application. 3. If the problem is due to the upstream customer order: a. Identify the customer order. (See "Correlating between Orders.") b. Trigger order fallout. (See "Triggering Customer Order Fallout.") 4. If the problem is due to a downstream application: a. Knowing the failed task, you should know the application where the error originated. Each automated task is responsible for making a call to a single operation on the application to which the task integrates. b. Look at the target application using the appropriate identities to correlate from the server order to the entity within the integrated application. (See "Correlating between Orders.") c. If the user interface in the integrated application does not reveal enough information to diagnose the problem, look at the target application server logs. d. Resolve the problem using one of the resolution paths described in "Handling Errors in OSM Service Order." 5. If the problem cannot be diagnosed, because the server logs are not logging messages at a detailed enough level, adjust the logging levels. Also another customer order – similar to the failed one – must be submitted to facilitate a deeper investigation. This may need to be done in an integration test environment to avoid introducing undesirable side effects in the production environment, which affect actual services that impact subscribers. Sometimes, an error is first discovered in an application (for example, UIM, ASAP) that is integrated with OSM. In this case, it is necessary to correlate from an application-specific entity to the service order or customer order. Correlating between Orders The Customer Order in OSM COM is identified by the sales order number in CRM. The Service Order (MobileGSMProvisioningOrder) in OSM SOM is identified by the order reference, which carries the same sales order number in CRM. The OSM order id is used to identify this order in the OSM server logs.
  • 67. GUIDELINES AND BEST PRACTICES Page 66 The Business Interaction (mirroring the Service Order) in UIM is identified by the external entity id, which carries the same sales order number in CRM. The Business Interaction id is used for correlation from the Service Order in OSM SOM to the Business Interaction in UIM. The Business Interaction id is used to identify this entity in the UIM server logs. The Technical Order (MobileGSMDeliveryOrder) in OSM SOM is identified by the order reference, which carries the same sales order number in CRM with the suffix “-del” appended. The OSM order id is used to identify this order in the OSM server logs. The Technical Order (Activation work order) in ASAP is identified by the order id of the OSM SOM Technical Order (MobileGSMDeliveryOrder) with a suffix beginning with a colon (:) appended. The Activation work order id is used to identify this order in the ASAP server logs. Correlating between Products, Services, Resources An Asset (product instance) in Siebel is identified by an Asset Integration ID. A CFS (service instance) in UIM is identified by a Service ID. It is correlated to the Asset by carrying the Asset Integration ID on the External Entity ID. A resource in UIM is identified by its own entity ID. It is correlated to the service through an Assignment, which is tracked by a configuration item on the service configuration.

×