Your SlideShare is downloading. ×
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
Integration of Oracle Communications IPSA with OSM
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

Integration of Oracle Communications IPSA with OSM

684

Published on

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

No Downloads
Views
Total Views
684
On Slideshare
0
From Embeds
0
Number of Embeds
10
Actions
Shares
0
Downloads
0
Comments
0
Likes
1
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. Oracle© Communications IP Service Activator Version 7.2 Guidelines and Best Practices Integration of Oracle Communications IP Service Activator with Oracle Communications Order and Service Management August 2012
  • 2. Oracle Communications IP Service Activator Guidelines and Best Practices, Release 7.2 Copyright © 2012, 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. Best Practice Guidelines Page 2 of 65
  • 3. Table of Contents Introduction ...................................................................................... 5  Purpose..................................................................................................... 5  Audience ................................................................................................... 5  Rapid Service Design and Order Delivery........................................................ 5  References................................................................................................. 6  Deployment Considerations............................................................... 8  IP Service Activator Web Services ................................................................. 8  Single Domain Deployment....................................................................................8  JMS Message Forwarding.......................................................................................9  Multi-Product Deployment Considerations....................................................... 9  Cross-Product Alignment on Purging OSM Orders and IP Service Activator Transactions..9  Coexistence of ASAP and IP Service Activator......................................................... 10  Integration Solution Design Overview............................................. 11  Target Solution..........................................................................................11  Development Strategy for an OSM to IP Service Activator Solution....................12  Step 1: Order Structure Design ............................................................................ 12  Step 2: Design Activation Strategy ....................................................................... 13  Step 3: Grouping Service Actions into Fulfillment Functions and Activation Tasks......... 15  Step 4: Build the OSM Order Template.................................................................. 18  Step 5: Identify Supplementary Information for Activation ....................................... 19  Step 6: Design OSM Tasks to Acquire Information or Transform Order Data................ 21  Step 7: Compose Activation Requests Through the Activation Task............................ 21  Step 8: Handle Failures if Activation Fails .............................................................. 23  Using Design Studio Effectively ....................................................... 24  Studio Project Organization .........................................................................24  Working with Activation Tasks .....................................................................24  Activation Task Request ...................................................................................... 25  Activation Task Response .................................................................................... 29  Activation Task Run-Time Overview ...................................................................... 31  Order Enrichment ......................................................................................32  Adding to OSM Order Data by Manually Selecting Data Choices................................. 33  Augmenting OSM Order Data ............................................................................... 33  Using Order and Service Management Effectively............................ 35  Orchestration ............................................................................................35  Choosing Orchestration Over Static Process Flows................................................... 35  Compensation ...........................................................................................37  Choosing a Compensation Strategy for Activation Tasks........................................... 37  Recognizing Compensation Failures....................................................................... 37  Dealing with Compensation Failures...................................................................... 38  Using IP Service Activator in a Workflow Environment ................... 39  Workflow Applications.................................................................................39  IP Service Activator Readiness ............................................................................. 39  Operations Not Recommended for Automation........................................................ 39  Vendor Cartridge Pre-check and Post-check Use.............................................40  Configuration Policy Use .............................................................................40  Best Practice Guidelines Page 3 of 65
  • 4. Service Actions for Productized Configuration Policies .............................................. 41  Service Actions for Custom SDK Configuration Policies............................................. 41  About the CONTENTVALUE Parameter Binding for Service Actions ............................. 42  Specialized Service Actions for vlanDefinitions and vlanInterface............................... 43  Interface and Sub-interface Creation..................................................................... 43  CTM Template Use .....................................................................................45  About CTM Template Service Action Parameters ..................................................... 46  Managing Installed CTM Templates ....................................................................... 46  Rollback of CTM Template Instances ..................................................................... 48  Capabilities Objects Manipulation .................................................................48  Quality of Service ......................................................................................49  Pre-Defined Quality of Service Profiles................................................................... 49  Custom Quality of Service Policies ........................................................................ 50  Failure Handling ........................................................................................54  Handling Failures Automatically or Manually........................................................... 54  Rolling Back Transactions .................................................................................... 55  Additional Rollback Considerations........................................................................ 56  Performance Considerations ........................................................................56  Transaction Size Versus Number of Transactions..................................................... 56  Scope of Activation Request: Applying Policies to Target Objects and Role Matching in IP Service Activator................................................................................................ 57  Multi-OIM Usage ................................................................................................ 57  Troubleshooting .............................................................................. 59  Troubleshooting Installations.......................................................................59  Database Schema Privilege Check Error During OSM Installation............................... 59  Unresolved Application Library references When OSM Managed Server Restarted After OSM Installation ................................................................................................ 59  Cannot Create File System at Attachments When OSM Managed Server Restarted after OSM Installation ................................................................................................ 59  NoClassDefFoundException When You Run OSM SDK Script credStoreAdmin.bat ......... 60  Failed to Acquire an EomSession When a Test Order Submitted to OSM ..................... 60  FailedAuthentication When a Test Order Submitted to OSM ...................................... 60  Activation Task Remains in Progress Indefinitely..................................................... 61  Troubleshooting IP Service Activator Interactions ...........................................61  Activation Task Generates a Non-Unique Transaction Name...................................... 62  Empty Request Message When Retry Activation Task............................................... 62  Order Submitted to OSM Results in No Corresponding IP Service Activator Transaction 62  Activation TASK Response: Exception Messages...................................................... 62  Activation TASK Response: Reasons for Failed Transaction ....................................... 63  Debugging IP Service Activator Commands from Execution of an Activation Task......... 63  Debugging Createorderbyvaluerequest Sent from Activation Task in OSM to IP Service Activator Web Service......................................................................................... 63  Adopting OSM-IP Service Activator ................................................. 64  Migration to an OSM-IP Service Activator Integration ......................................64  Glossary .......................................................................................... 65  Best Practice Guidelines Page 4 of 65
  • 5. Introduction This document describes key concepts and recommendations for integrating and deploying Oracle Communications Order and Service Management (OSM) and Oracle Communications IP Service Activator for flow-through activation of IP-related services driven by an upstream order. Purpose This document is intended to provide general guidance in configuring integrations between OSM and IP Service Activator to support specific service fulfillment solutions. A separately documented reference implementation provides a detailed example of how to apply these guidelines to a specific situation. For more information, see Solution Uptake Guide for MPLS VPN with Ethernet Access on My Oracle Support. The integration of OSM and IP Service Activator is commonly part of a more extensive service fulfillment solution, such as Oracle Communications Rapid Service Design and Order Delivery solution architecture, in which OSM and Design Studio are key components. This document describes the use of OSM and Design Studio as it applies to integration considerations between OSM and IP Service Activator. In particular this document focuses on the aspects of OSM and IP Service Activator that are specific to integrating these products in the context of an end-to-end flow-through solution, rather than describing generic product concepts. It is assumed that you have completed a planning phase, which has included analyzing business and system requirements, defining an end-to-end solution architecture, specifying expected network configuration, and identifying incoming orders that require activation using IP Service Activator. The guidelines in this document apply to features available in version 7.2.0 or later of Oracle Communications products OSM and IP Service Activator, and Design Studio 7.2.1 or later. Environment components for IP Service Activator also include any required custom configuration policies or CTM templates. Audience This document is intended for Communications Solution Designers. It is expected that this role is filled by one or more individuals who collectively have expertise in OSM and IP Service Activator. Rapid Service Design and Order Delivery Oracle Communications Rapid Service Design and Order Delivery (RSDOD) is the Oracle Communication comprehensive service fulfillment solution that enables communications service Best Practice Guidelines Page 5 of 65
  • 6. providers to rapidly and efficiently design, launch, and deliver any type of service for any network domain. RSDOD Solution Architecture In the RSDOD solution architecture, there is a clear distinction between Central Order Management (COM) and Service Order Management (SOM). COM coordinates sales orders that are essential for billing, workforce management, supply chain management, and provisioning systems. SOM receives provisioning orders from COM and interprets them as reusable service components. The SOM layer coordinates detailed design-and-assign activities for each service and then issues Technical Orders to drive activation of services and resources in the network, as well as relevant workforce and supply chain management operations driven by the service design. Sales orders, which are associated with COM, are defined as line items based on “product definitions,” whereas service orders, which are associated with SOM, are defined in terms of “customer facing service definitions.” Making this distinction decouples the architecture allowing for the ongoing definition of product variations without affecting the service implementation. From the perspective of OSM to IP Service Activator integrations, an incoming OSM order may be considered either a Service Order or a Technical Order, depending on the overall solution design. An incoming Service Order requires coordination of design-and-assign activities across several systems, including IP Service Activator. In the case of a Technical Order, it is expected that almost all design-and-assign activities occur before the order reaches this layer, and therefore the technical order is fully qualified. In both cases, OSM converts relevant actions contained in the order to activation orders, which drive IP Service Activator and possibly other downstream activation systems. References Best Practice Guidelines Page 6 of 65
  • 7. This guide assumes that you are familiar with the OSM, IP Service Activator, and Design Studio products. In addition, Best Practices and Guidelines for OSS Solution Development provides complementary material to that found in this guide. Documentation Location IP Service Activator Documentation Available from the software delivery Web site (Oracle Communications IP Service Activator 7.2.0 Media Pack > Oracle Communications IP Service Activator 7.2.0 Documentation) IP Service Activator Developer Documentation Available from the software delivery Web site (Oracle Communications Service Activation Developer Documentation Pack > Oracle Communications IP Service Activator Developer Documentation) Best Practices and Guidelines for OSS Solution Development [ID 1446340.1] Available as a knowledge article from the Oracle Support Web site: https://support.oracle.com Order and Service Management Documentation Available from the software delivery Web site (Documentation for Oracle Communications Order and Service Management 7.2.0 Media Pack) Design Studio Documentation Available from the software delivery Web site (Documentation for Oracle Communications Order and Service Management 7.2.0 Media Pack → Oracle Communications Design Studio 7.2.0 Documentation) Best Practice Guidelines Page 7 of 65
  • 8. Deployment Considerations OSM and IP Service Activator are supported on common platforms and share several underlying technology components. This section provides recommendations that leverage this commonality to ensure effective and efficient deployments. For broader deployment considerations that take into account other Oracle Communications products, see “Deploying OSS Suite Applications” in Best Practices and Guidelines for OSS Solution Development. These deployment recommendations assume a single instance of OSM and IP Service Activator. Deployments involving multiple instances of OSM interacting with IP Service Activator Web Services have not been considered, and it should be noted that only a single IP Service Activator instance is supported from an OSM instance. IP Service Activator Web Services OSM and IP Service Activator both use the WebLogic Server as a key technology component. Within a WebLogic domain, OSM can reside within a single managed server or a cluster of managed servers. For large-scale OSM deployments, where resiliency and scalability are important considerations, a clustered environment is recommended; however, a clustered environment is not always required for small-scale OSM deployments. IP Service Activator Web Services do not support a clustered environment; however, multiple integration managers (OIMs) can be configured for the IP Service Activator Web Service. At least two OIM instances are recommended: a dedicated read-only OIM, and a read-write OIM. For more information, see “Multi-OIM Usage” in this document. Single Domain Deployment It is recommended that you create a single WebLogic domain to accommodate all applications (OSM and IP Service Activator Web Service). Each application resides in its own managed server or cluster within this single domain. The managed server for each application should be named uniquely across domains. For example, OSM_MS1, IPSA_MS1. Uniqueness of server names is required for proper forwarding of JMS messages. Do not use a default name of AdminServer for each server. The figure depicts the single domain deployment. Best Practice Guidelines Page 8 of 65
  • 9. Single Domain Deployment JMS Message Forwarding When the IP Service Activator Web service is deployed in a managed server that is separate from OSM, a JMS message forwarding mechanism is required to enable JMS message delivery between applications. The recommended approach is to use Store and Forward (SAF). The SAF service provides reliable message delivery across managed server instances outside an application server cluster. If a remote destination is temporarily not available, messages are stored locally and forwarded to the remote destination when it becomes available. Multi-Product Deployment Considerations Cross-Product Alignment on Purging OSM Orders and IP Service Activator Transactions Configure IP Service Activator to preserve adequate transactions to ensure that they are available to open OSM orders. Access to these transactions is needed when a transaction is canceled and all operations in that transaction must be undone. In IP Service Activator, the archive limit can be set to specify the number of transactions to store. This is applicable during rollback for a transaction with a failed provisioning status, when rollback on transaction failure is enabled as either a Best Practice Guidelines Page 9 of 65
  • 10. system-wide default or in an individual activation task. This also applies during order cancelation or compensation. For more information, see “Setting the Archive Limit for Transactions” in IP Service Activator Administrator’s Guide. If OSM cartridges are purged and then redeployed, the OSM order ID is automatically reset. Because IP Service Activator transaction name generation is based on the OSM order ID, it is necessary to purge IP Service Activator transactions to eliminate transactions with duplicate names. For more information, see “Activation Task Generates a Non-Unique Transaction Name” in this document. Coexistence of ASAP and IP Service Activator Oracle Communications ASAP is an activation product that is optimized for high volume stateless activation. Like IP Service Activator, ASAP supports an order interface based on OSS/J standards that can be used over Web services. The use of a common interface enables both ASAP and IP Service Activator to integrate with OSM using similar design patterns and uses common elements of Design Studio, such as the Activation Task and Data Dictionaries. In field deployments, the strengths of IP Service Activator and ASAP complement each other, while a common integration environment allows both systems to be driven from a common upstream order. This allows stateless activation operations to be coordinated with the complex stateful service configurations supported by IP Service Activator. Note: Although an ASAP-IP Service Activator Process Integration Pack (ASAP-IPSA PIP) is available, it is recommended that you use OSM to directly coordinate activation operations for ASAP and IP Service Activator. Best Practice Guidelines Page 10 of 65
  • 11. Integration Solution Design Overview The steps in this section outline a suggested high-level strategy for developing an Order and Service Management solution that delegates activation of IP-related services to IP Service Activator. For additional information about planning and designing a general OSM implementation, see Order and Service Management Developer’s Guide. Target Solution It is assumed that the solution you are designing will use OSM to process well-structured incoming orders. The target solution can be as simple as a single OSM process with a single activation task, and a manual task for failure handling, or more typically, an OSM orchestration process that is structured using a composite cartridge. The orchestration processing capabilities of OSM direct appropriate order lines within the order to a set of sub processes designed to deal with IP service activation. If one or more of the incoming order lines require enrichment prior to activation, a sub process designed to enrich the order lines is invoked. Similarly, specific sub processes are invoked to activate sets of order lines, honoring any required dependencies between the sub processes. Each sub process that deals with IP service activation is typically a simple process that includes an activation task to create activation orders that use the IP Service Activator Web Service to perform specific network configuration using IP Service Activator, and a manual task for failure handling. The process may include activation tasks, automated tasks, and manual tasks, such as an automated task to transform order data, or an additional activation task to query IP Service Activator. The results of each activation order reflect the results of the underlying transaction in IP Service Activator. Unsuccessful activation orders result in a failure of the corresponding activation task in OSM where appropriate order processing behavior is triggered. Solution Design Sequence: 1. Define the incoming order structure. 2. Design an activation strategy to translate order line items into IP Service Activator service actions and attributes. 3. Group Service actions into Fulfillment Functions and Activation Tasks. 4. Build the data schema for the OSM solution and OSM order template. 5. Identify sources for supplementary information that is missing from an order but is required for activation. 6. Design OSM manual tasks, activation tasks, and automated tasks to acquire supplementary information or transform order data. Best Practice Guidelines Page 11 of 65
  • 12. 7. Compose activation requests through the activation task. 8. Design fallout handling for activation failures. Development Strategy for an OSM to IP Service Activator Solution Step 1: Order Structure Design Within the overall solution, an order must be defined that delivers the required order elements and data to OSM. It is assumed that defining details of the upstream order structure incoming to OSM is within the scope of the solution design. At the end of this step, a schema should be defined that specifies the structure of incoming orders. It is recommended that the order be designed so that each line item corresponds to a self- contained product action, such as adding a layer 3 MPLS VPN site. Analysis and design should then be done on a per-line-item-basis to determine the IP Service Activator actions involved, the dependencies between those actions, and the dependencies between line items. This facilitates the design of the OSM fulfillment functions and the orchestration plan. At run time, the dynamic orchestration will combine the fulfillment functions based on the line items that are present in the incoming order. The incoming order is an xml document with a customized schema and content specific to the needs of the solution design. The structure includes an order header and a line item structure. Order Header The order header structure must contain at least the following information: Order ID: Uniquely identifies each order. Order Number: Identifies an order across revisions. When an order is revised (or canceled) this value stays the same. OSM can use this value to identify the base order. Revision: A revision sequence number; together with order number, it represents the user key to an order. Fulfillment Mode: Qualifies the nature of orchestration required for a particular submission of an order with values, such as: DELIVER (fulfill order) or CANCEL (cancel entire order). In addition it is recommended that a fulfillment priority attribute be included in the order header. This enables the use of order priority in OSM to establish relevant priorities of order fulfillment across orders. Best Practice Guidelines Page 12 of 65
  • 13. Order Line The order line structure must contain at least the following information: Line ID: Identifier of the order line item, which is unique across orders and order revisions. Base Line ID: Reference to base order's line that is revised (or canceled) by this orders' line. Action Code: Denotes the type of order, with values such as ADD (provide new service), UPDATE (in-life service change), DELETE (stop service), NONE (no change; line item included to provide context for another line item). Order Item Name: Name of the product (name or orderable item). Order Item Type: Type of the product (type of orderable item). Fulfillment Item Code: Include either a fulfillment item code attribute, which enables a direct mapping to a Design Studio recognized product specification entity, or enough information on the order line that a mapping rule can be designed to locate a product specification entity for each order line. A structure for name/value pairs to provide parameters for the order item from the upstream system, which are relevant to activation. Parent Line ID: Line items may require this attribute. The Parent Line ID references the Line ID of another order line in the same order. For example, when adding an L3 MPLS VPN site to an existing L3 MPLS VPN, an order line that represents a site references its parent VPN through the Parent Line ID. In this case, the VPN order line is provided for context and would have an Action Code NONE when the VPN exist, otherwise an Action Code of ADD when the VPN is to be created. In addition, several other attributes may be included in the order line: Including parent/child relationships in the order enables the use of order item hierarchies in OSM. Including a Requested Delivery Date Time on the order line enables the use of future requested delivery date functionality in OSM. Otherwise, delivery is as soon as possible. Including attributes for order dependencies enable the enforcement of the relevant dependencies in OSM (Depends on Line ID, Depends on Order ID, Parent Order ID) Step 2: Design Activation Strategy This step analyzes incoming order lines and maps them to sequences of Service Actions on IP Service Activator objects to fulfill the order line items. At the end of this step, the OSM cartridge Best Practice Guidelines Page 13 of 65
  • 14. developer should know the configuration that must be sent to the network for each order line, as well as the complete set of IP Service Activator Service Actions that are required for the configuration. To define an activation plan: i. Identify the IP Service Activator operations that are needed to activate the required configuration. ii. Group these operations into natural and logical transactions for IP Service Activator. iii. Target one IP Service Activator activation task for each group. This process also uncovers any order enrichment required for activation purposes. At the end of this process, the OSM cartridge developer should have a comprehensive activation plan for each incoming product action. The strategy should identify: the sequence of OIM CLI commands and CTM template instantiation commands required for each order type all the attributes, which are grouped into transactions the mapping of order data to the attributes in the IP Service Activator OIM and CTM commands additional data required for order enrichment Any required custom CTM templates Any required custom configuration policies Any required specific IP Service Activator configuration (such as Network Processor cartridge option settings) The following is a suggested strategy for defining an IP Service Activator activation plan. 1. For each order line item, identify the steps a human operator would take to activate the required configurations. If IP Service Activator is already in use as the activation system, these steps would be performed in IP Service Activator (for example, on the OIM command- line interface). Alternatively, it might be the manual steps performed on individual network elements. 2. For manual actions performed directly on network elements, identify IP Service Activator objects and actions that result in the desired configuration. Best Practice Guidelines Page 14 of 65
  • 15. 3. If the steps in the IP Service Activator user interface for activating the required configuration are known, the OIM CLI commands can be determined by following these recommendations: Perform the steps using the IP Service Activator user interface. Examine the resulting transactions: In the user interface, select the transaction, right-click and view its properties; the Operations tab shows the detailed operations involved in the transaction. Use these operations (and the kinds of objects involved) as starting points into IP Service Activator OSS Integration Manager Guide, to find the required OIM CLI operations. Test the OIM CLI operations. 4. The initial analysis might indicate a need for customizing or extending IP Service Activator. To control command variants and configuration styles, modify the options files of the IP Service Activator Network Processor cartridges. For more information, see related documentation on those components. To deliver a custom configuration, CTM templates or Configuration Policies may need to be developed using the IP Service Activator cartridge SDK. 5. Retain the relative ordering of the various steps, in addition to the details of the steps themselves. Step 3: Grouping Service Actions into Fulfillment Functions and Activation Tasks This step defines the processes required to deal with each order line, the organization and orchestration of the processes that apply to each order line, the sequence of tasks within each process. At this point, it is expected that you have a clear understanding of the services to be manipulated and the operations to be performed on them. The IP Service Activator activation task in Design Studio can now be used to specify sequences of service actions and parameters and invoke the appropriate commands in the context of an IP Service Activator transaction.  Orchestration Design Best Practice Guidelines Page 15 of 65
  • 16. It is recommended that you first analyze each incoming order line variant in isolation, and then take dependencies into account, and finally optimize the overall design by determining if processes can be reused to handle multiple line items. Incremental Service Additions To incrementally support new services without affecting existing design and implementation, new processes should be developed and invoked by the orchestration plan. Fulfillment Function Dependencies The sequencing of service actions within an activation task is defined at design time and does not change based on the ordering of line items within the incoming order. If there are dependencies between line items in the incoming order, ensure that fulfillment functions are invoked in the correct sequence by defining dependencies between the fulfillment functions. At run time, the dynamic orchestration will combine the fulfillment functions in the correct sequence based on the dependencies defined between the fulfillment functions and the line items that are present in the incoming order. Process Design When multiple activation tasks are required in the orchestration plan, it is possible for activation tasks to be sequenced within a single process. Following are some considerations. Can they all operate at the same processing granularity? The process is invoked by the granularity order component, so the tasks must share the same processing granularity. Does the runtime execution of these tasks happen in sequence, or do the steps need to be broken up by service actions in other processes? Consider Task A, Task B and Task C. Do dependencies with other processes mean that work has to happen in between Task B and Task C? If so, these tasks must be broken out into separate processes. Is there complexity introduced at the process level that is better managed by orchestration? If, for example, supporting multiple activation tasks within a process means that complex rule checking and branching is required, it might be a case to move some of those dependencies into a higher level of decomposition. Multiple Serial Activations Required It is recommended that you keep the number of activation tasks low in order to minimize the number of IP Service Activator transactions. Multiple IP Service Activator transactions means that another IP Service Activator user or activation order can change the state of IP Service Activator objects between transactions. A single runtime execution of an activation task corresponds to a single IP Service Activator transaction. Multiple activation tasks may be required in some instances, such as the following: Device discovery, or re-discovery, is required. Best Practice Guidelines Page 16 of 65
  • 17. There is an order dependency between CTM Template and other configurations delivered as part of the activation task. There is an order dependency between two services that are implemented in different service cartridges at the Network Processor level. If the IP Service Activator deployment includes one or more service cartridges for a device or vendor type, any inter-dependency (in the form of sequencing of commands to the device) between cartridges must be addressed by controlling the sequencing explicitly using multiple transactions. One exception is where the inter-dependency is between an interface (or sub-interface) creation policy and services that reside on that interface. This kind of dependency is automatically handled by the IP Service Activator Network Processor framework. There is a benefit to designing additional processes for incremental service additions. There is a benefit to isolating failures. Commands That Require Separate Activation Requests Some commands do not use a transaction. These include discovery and query operations. These types of commands cannot be mixed with commands that require a transaction. For example, modifying objects in IP Service Activator cannot be mixed with discovery since the modify operations are done as part of a transaction but the discovery operations are not. Separate transactions are required for operations that involve: Device discovery or device re-discovery. Device state changed between managed and unmanaged states, or change of device command delivery modes. Capabilities reset/refresh. Certain inter-dependencies between different operations, typically involving CTM Templates or custom Configuration Policies. See “CTM Template Use” in this document for more information. IP Service Activator Operation Dependencies There are specific cases in which multiple commands need to be in the same IP Service Activator transaction in order to succeed. For example, an MQC PHB group requires at least one PhbMqc child object. Design Complexity To reduce design complexity and improve maintainability, you can use separate activation tasks to maintain a manageable set of service actions with fewer conditions in each activation task. Failure Isolation and Recovery Best Practice Guidelines Page 17 of 65
  • 18. Isolating activation failures is a consideration for the granularity of activation. The OSM cartridge design requires the introduction of OSM manual tasks to assess failures and decide on resolution actions. See “Failure Handling” in this document for more information. Compensation Strategies Service actions with different compensation strategies cannot be combined in a single transaction. Use a single IP Service Activator transaction to fulfill an order where possible. If multiple transactions in the fulfillment of an order are necessary consider the compensation requirements of the operations to determine whether the groupings are appropriate. For example, create customer should not be undone during compensation or order cancellation when there are subsequent transactions in fulfillment of the order. Subsequent transactions give the opportunity for other orders, with no order-to-order dependency, to create services for the customer before the order is completed. For more information, see the section about Compensation in this document. Mass or Batch Activations Required A single order might cover multiple instances of a service. For example, an order might result in activating many VPN sites for a new enterprise customer. It is recommended that this be handled by making use of orchestration. Refer to Orchestration in the section “Using Order and Service Management Effectively” in this document. Step 4: Build the OSM Order Template OSM maps an external order format into its internal template. Although, if possible, the external order structure should be well aligned with the internal template, the definition of the internal template provides an opportunity to align data structures with those needed by IP Service Activator. At the completion of this step an OSM data template should be defined that supports the Activation parameters required for IP Service Activator. IP Service Activator requires specific data when creating or modifying objects. The objects have attributes that are typed, have enumerations, or ranges. While the core product validates these attributes, the OIM interface is untyped, meaning that the attribute definitions in the interface do not fully restrict the data values to those accepted by the attribute. Given these IP Service Activator requirements, it is recommended that the workflow designer build and maintain a data schema for the OSM solution, and an OSM order template, with the data elements as well-defined as possible to: ensure the type correctness of the attributes passed to IP Service Activator centralize the definition of IP Service Activator objects and describe the attributes of each object provide a convenient template for information gathering prior to activation Best Practice Guidelines Page 18 of 65
  • 19. provide a basis for understanding IP Service Activator responses when the response consists of one or more objects and their attributes ease the binding to IP Service Activator service action parameters in activation tasks The Design Studio project for IP Service Activator includes a data schema containing the definitions for service action parameters provided for modeled IP Service Activator objects. Also included are data schemas for productized configuration policies, which are modified from the original schemas to use primitive data types supported in Design Studio. For the identified set of IP Service Activator objects, examine IP Service Activator OSS Integration Manager Guide and identify the object attributes required for the creation and modification operations dictated by the order item activation requirements. You can create an activation task in OSM and add a service action. The mandatory parameters are indicated with an asterisk (*) beside the name, and all parameters available for binding to order data, for data input to the activation order, are listed. If necessary, use the OIM CLI to examine an object of the required type, created using the IP Service Activator User Interface. At the end of this step, the OSM cartridge developer should have an OSM order template that contains all the objects in IP Service Activator that were identified in the Activation Plans. For each of these objects, the order template should contain the attributes of interest and any mandatory attributes as per IP Service Activator OIM documentation, and as per mandatory parameters in the IP Service Activator service actions, and the CTM template definitions. Step 5: Identify Supplementary Information for Activation Depending on the completeness of the order provided by the upstream system, orders may require local enrichment using manual and/or automated tasks coordinated by OSM. At the end of this step, the OSM cartridge developer should have activation plans where all data required for the IP Service Activator object attributes have been gathered; there is a source for each of these items and a mechanism to obtain the data in the context of each order. The following types of enrichment and supplementary information sources may exist: Order Enrichment from Service Instance and Low-Level Resources Order enrichment happens while executing a detailed design of a service instance and allocating low-level resources. For example, an order requiring the creation of a VPN site needs business logic to derive the name of the VPN and the type of membership the site has to possess. In addition, various resources must be identified and consumed, for example the order may indicate a specific circuit on a network element as the access point, and require a set of IP addresses to use in the configuration. These can come by querying the operator in OSM, by designing OSM manual tasks, or by automatically accessing an external system. Best Practice Guidelines Page 19 of 65
  • 20. Refer to Order Enrichment under the heading Using Design Studio effectively for order enrichment considerations in Design Studio. Order Enrichment from Activation System or NE Requirements Order enrichment results from the requirements and needs of the activation system or network element itself. For example, the various object IDs and paths required to identify objects in IP Service Activator OIM are sources of enrichment. The order specifies the network element, either by name or management IP address, but the activation request to IP Service Activator must refer to this device using its IP Service Activator ID or its full path in IP Service Activator. Based on the nature of the data requirements, some data is external, and other data is internal to the OSM solution. External data is sourced externally from OSM, such as when it is provided in the incoming order, or retrieved from an external system. It may it be used as provided, or it may be modified to an internal representation based on the solution requirements and needs of the activation system. Internal data can be created with automated logic. An example of external data is an interface description that might be provided in the upstream order. However, it might be desirable to automatically create a consistent description based on the customer name, VPN name, and site location to aid in troubleshooting at the network level. The description, which is created with automated logic, is an example of internal data. Discovering a Device If a solution requires IP Service Activator to discover the network devices using out-of-box IP Service Activator mechanisms, it is recommended that devices be manually discovered into IP Service Activator as part of "Service Readiness" activities (for example, by manually using the IP Service Activator User Interface) and not in the context of flow-through activation. Despite this recommendation, device discovery (or device re-discovery) can be an integral part of the activation flow-through process. For example (Scenario 1), an FR sub-interface could be created and some QoS applied on the resulting DLCI L2 object. The issue with this scenario is that IP Service Activator does not see the DLCI L2 object until the device is re-discovered. Or (Scenario 2) a Serial interface could be switched from PPP to FR. The issue with this scenario is that IP Service Activator does not recognize the interface as frame-relay, for the purposes of validating QoS, until the interface capabilities are refreshed. The recommended approaches to deal with these two scenarios within the flow-through activation context are: Scenario 1: As part of the transaction that creates the FR sub-interface, the DLCI can also be created. Scenario 2: As part of the transaction that switches the Serial interface from PPP to FR, pre-prepared interface capabilities objects can be linked in place of the existing capabilities objects. Best Practice Guidelines Page 20 of 65
  • 21. If these methods are not usable, the discovery service action can be used. The first consideration, aside from the performance impact, is the need to monitor the completion of discovery. IP Service Activator does not allow the client to track the completion of the discovery service action directly. One method to deal with this issue is to use a delay timer. Another method is for the post-discovery task to monitor for the result of the discovery (for example, the appearance of the DLCI object under the FR sub-interface). The second consideration is the introduction of multiple transactions in the activation phase of the workflow; a discovery operation cannot be requested while a transaction is being composed. Step 6: Design OSM Tasks to Acquire Information or Transform Order Data At completing this step, all OSM tasks should be designed that populate the internal order template for all order scenarios. The information populated in the order template must be adequate to perform activation. The following list provides recommendations to workflow designers for designing OSM tasks to acquire information or transform data: Based on the order items and using the results of the mapping investigations, the workflow designer should know the set of IP Service Activator services to be manipulated for each order line item. Using the results of the supplementary information investigation, the workflow designer can identify the additional information required to activate the services, as well as design the tasks to gather and validate that information. This can involve operations that fetch information from IP Service Activator, where IP Service Activator is being used as a network and/or service repository. In addition, other external systems may need to be accessed to provide order line parameters. Activation Tasks may be used to formulate queries to IP Service Activator with the results returned in order response details. For more information, see Activation Task in this document for details. It may also be necessary to modify the order data or the collected data to suit the activation requirement. Using a data schema, which is modeled to reflect IP Service Activator objects, as the data model can minimize the impact of this step, but this may not always be feasible, especially in terms of influencing the inbound order data from upstream. OSM provides an opportunity to transform and augment the incoming order prior to execution of the creation task in the Design Studio order recognition rule entity by specifying an expression for the order data rule. Step 7: Compose Activation Requests Through the Activation Task Best Practice Guidelines Page 21 of 65
  • 22. Refer to the Activation Task section in this document for an overview of working with the activation task in conjunction with IP Service Activator Web services. Additional considerations for specific types of IP Service Activator objects are described below. Types of IP Service Activator Configuration Objects The components of a “service” in IP Service Activator are driven by IP Service Activator Configuration Objects, such as Access Rules, Configuration Policies, and so on. There are three broad categories of such objects, each with their own operational behavior requirements in OSM: Configuration Policies CTM templates Other Configuration Objects OSS Integration Manager Guide describes the interaction requirements of configuration objects and policies. For Configuration Policies and CTM templates, however, there are additional considerations in the context of flow-through integration with OSM. Creating and Modifying Objects IP Service Activator distinguishes between creating and modifying all objects in its model. This is enforced by having different methods for these operations. In addition, some objects have attributes that can be set only during creation. These attributes cannot be modified after the object is created. Such attributes can be found in IP Service Activator OSS Integration Manager Guide, with the Access Type listed as “RC” (read/create) or “CO” (create only). An example would be the attribute “Type” of the object “Site.” This can be set during creation and only queried thereafter. There are also specific considerations to manipulate Configuration Policies and CTM Templates. The modification of objects can follow one of two patterns: Re-specifying all attribute values for the object Specifying only the attribute values that have changed The factors to be taken into consideration to select the appropriate pattern are: Type of IP Service Activator object: Ensure that creation-time attributes contained in IP Service Activator objects (as described above) are not specified during modification. On the other hand, objects like Configuration Policies require full re-specification. Best Practice Guidelines Page 22 of 65
  • 23. Storage of service-related data: If the overall solution uses an external entity as the service inventory, all attribute values should be modeled there. In such a situation, it is usually less complex to re-specify the object fully for modification. Simultaneous access: If multiple IP Service Activator sessions manipulate the same object simultaneously, specifying only the attribute values that have changed lets IP Service Activator exercise proper recognition of any conflicts, while re-specifying the whole object gives this responsibility to the solution. If the object data is being sourced from an inventory, the normal inventory mechanisms for parallel access should prevent problems. However, if the object data is being sourced from IP Service Activator, there is a risk of simultaneous operations overwriting some of the attributes of the object; this is due to the time that elapses between reading the original object data and performing the modify operation with the updated object data. Configuration Policies See “Configuration Policy Use” in this document for specific considerations about manipulating configuration policies, including those for service configuration, and interface and sub-interface creation. CTM Templates For considerations and recommendations about using CTM template, see CTM Template Use in this document. Capabilities Objects Refer to Capabilities Objects Manipulation in this document for specific considerations to manipulate capabilities. Step 8: Handle Failures if Activation Fails For activations that time out or fail, the minimum recommended handling is to capture the failure information coming out of IP Service Activator, enrich it with workflow and task information, and reflect this in the order data. Further action is dependent on each scenario. Complex automated recovery actions require careful technical as well as cost-benefit analysis. For more information, see “Failure Handling” in this document. Best Practice Guidelines Page 23 of 65
  • 24. Using Design Studio Effectively Studio Project Organization Proper structuring of projects in Design Studio is important for the efficient development, maintenance, and extensibility of integration projects. Design Studio offers many features to help with effective project organization. Consult Design Studio online Help and Oracle Communications Order and Service Management Developer’s Guide when structuring a project. You can use a composite cartridge to assemble an OSM solution from a collection of component cartridges for modular design. Component cartridges might include: OSM component cartridges involved in processing of specific line items OSM component cartridge containing orchestration entities for provisioning OSM component cartridge containing the product classes for the solution OSM component cartridge containing the product specifications for the solution OSM component cartridge containing solution resources OSM component cartridge containing the orchestration entities for solution topology Refer to Modeling OSM Orchestration in the Oracle Communications Design Studio online Help for more information about composite cartridges, and effective use of Design Studio entities for OSM orchestration. Working with Activation Tasks Activation tasks can be added to an OSM process to integrate between Oracle Communications Order and Service Management (OSM) and Oracle Communications IP Service Activator Web services. An IP Service Activator Design Studio cartridge is available, which contains service actions corresponding to operations and attributes documented in IP Service Activator’s OSS Integration Manager Guide. You need to import the project as an archive into the workspace that contains the OSM solution cartridges. Importing the project makes the IP Service Activator service actions available for use in activation tasks in OSM processes at design time. To work with an IP Service Activator activation task at run time, you must install and configure IP Service Activator Web services. This allows OSM to communicate with IP Service Activator. The following are design-time considerations when using IP Service Activator service actions: Best Practice Guidelines Page 24 of 65
  • 25. Activation Task Request You design each activation task to either create a single IP Service Activator transaction, or perform a command outside a transaction, or invoke some special commands that are not contained within a transaction, such as a query or device discovery. Avoid mixing service actions that do not result in an IP Service Activator transaction, such as device discovery and find operations, with those that do, such as create, update, delete, link/unlink, and use/unuse operations. Design Studio online Help describes working with activation tasks in general. IP Service Activator OSS Integration Manager Guide describes the IP Service Activator objects and attributes, and the set of commands that are exposed through not only the command line interface, but also exposed through the IP Service Activator service actions available for use in an activation task. At design time, you create an Activation Task entity to configure a request to send to IP Service Activator. This configuration includes service actions to perform, which may be conditional based on run-time order data. You must sequence service actions in an activation task according to the order in which the operations need to be executed during the runtime of the corresponding IP Service Activator transaction. This configuration also includes bindings of OSM order data to service action parameters for the request data, and the response mapping to OSM order data. Service action parameter bindings may be simple or complex, and use pre-computed and gathered data, and can be organized using elements of an IP Service Activator data schema. Service Action Sequencing When multiple service actions are used within a single activation task, service action ordering can be used to help fulfill dependencies between them. For example, a Site must be created before it can be linked to a VPN. The two service actions can be contained within the same activation task, but the IPSA_CREATE_SITE service action would be listed above the IPSA_LINK. Correlating with OSM When an automated/activation task communicates with an external system for the purposes of order enrichment, there needs to be a way of correlating the response data to the specific line item (in OSM) requesting the enrichment data. Keeping in mind that there may be hundreds of line items on the OSM order, yet only one of those may have requested a piece of enrichment data. In order for the activation task to update the OSM order data correctly, it needs a way to identify to OSM core, which line item gets the update. The only IPSA service actions which are used for order enrichment are the queries. For each query service action, a unique piece of data from the OSM line item (line ID) is sent as the REFERENCE_ID parameter. This value will be echoed back in the InfoParm section of the response data. The activation task will extract the value and use that as the data to identify the Best Practice Guidelines Page 25 of 65
  • 26. correct line item in OSM. This parameter should always be used when data returned from IPSA is to be updated onto a specific line item. Using Conditions for Service Actions in Activation Request The use of conditions in the service action binding allows the design of an activation task to handle variations of activation requests based on OSM order data. For example, a single activation request can be designed to handle various actions for a product specification, such as to provide a new service (ADD), modify an existing service (UPDATE), or stop a service (DELETE). You can restrict the inclusion of service actions in the activation request based on the action code, and product specification such as: osm:ServiceActionCode/text()='ADD' and osm:ProductSpec/text()='Service.L3MPLS.VpnSite' Another use might be to skip the creation of an object when a query has determined that the object already exists. For example, an activation task may create a VPN, and implicitly create the VPN’s parent customer object, if the customer does not already exist in IP Service Activator. An activation task, which is executed before the VPN creation, performs a query and updates the OSM order data with the customer object ID, if found. The IPSA_CREATE_CUSTOMER service action binding in the subsequent activation task has a condition to skip creation of the service action if the customer ID exists: not(osm:Vpn/osm:Customer/osm:ID) Simple Binding of OSM Order Data into Service Action Parameters Construct a simple parameter binding using XPath expressions, such as to bind RipPassiveInterface in the OSM order data to the RIPPASSIVEINTERFACE parameter in the IPSA_MODIFY_INTERFACE service action: osm:VpnSite/osm:PEInterface/osm:InterfaceRIP/osm:RipPassiveI nterface and an optional conditional expression can be used, such as to restrict the inclusion of the RIPPASSIVEINTERFACE parameter in the activation request to when it is appropriate based on the order data. It is conditionally included when the routing protocol includes RIP, and the value is not empty: (osm:VpnSite/osm:VpnSiteRoutingProtocol/text()='RIP' or osm:VpnSite/osm:VpnSiteRoutingProtocol/text()='EBGP_RIP') and (osm:VpnSite/osm:PEInterface/osm:InterfaceRIP/osm:RipPassive Interface/text()!='') Best Practice Guidelines Page 26 of 65
  • 27. Complex Binding of OSM Order Data into Service Action Parameters Construct complex parameter bindings using XLST. This XSLT snippet uses the numeric ID of an object, if available in the OSM order data, and otherwise uses the full path for the OBJECT_ID parameter. IP Service Activator can process IDs more efficiently, and this allows the use of the IDs when available in the OSM order data. <xsl:choose> <xsl:when test="osm:VpnSite/osm:ID/text()!=''"> <mslv-sa:serviceValue xsi:type="mslv- sa:ASAPServiceValue"> <mslv-sa:name>OBJECT_ID</mslv-sa:name> <mslv-sa:value><xsl:value-of select="osm:VpnSite/osm:ID"/></mslv-sa:value> </mslv-sa:serviceValue> </xsl:when> <xsl:otherwise> <mslv-sa:serviceValue xsi:type="mslv- sa:ASAPServiceValue"> <mslv-sa:name>OBJECT_ID</mslv-sa:name> <mslv-sa:value><xsl:value-of select="osm:VpnSite/osm:Path"/></mslv-sa:value> </mslv-sa:serviceValue> </xsl:otherwise> Complex parameter bindings enable greater use of OSM order data, which is augmented by loading a mapping of incoming order data to pre-defined IP Service Activator objects. This XSLT snippet uses the name of a quality of service profile, and a hard-coded interface direction (Inbound) to look up the ID of a policy object to use for the POLICY_OBJECT_ID parameter of an IPSA_USE service action. The ID is looked up from a mapping table in the OSM order data. <xsl:variable name="qosProfile" select="./osm:VpnSiteQoS/osm:QoSProfileName/text()"/> <xsl:variable name="interfaceDirection" select="'Inbound'" /> <mslv-sa:serviceValue xsi:type="mslv-sa:ASAPServiceValue"> Best Practice Guidelines Page 27 of 65
  • 28. <mslv-sa:name>POLICY_OBJECT_ID</mslv-sa:name> <mslv-sa:value><xsl:value-of select="../../../../../osm:QoSProfileMapping/osm:L3SiteQoSPr ofile[osm:QoSProfileName/text()=$qosProfile and osm:PEInterfaceDirection/text()=$interfaceDirection]/osm:Use MqcPhbGroupID"/></mslv-sa:value> </mslv-sa:serviceValue> Bind OSM Order Data into Configuration Policy XML CONTENTVALUE Parameter A structure in the OSM order data can be created by selecting a desired subset of elements from a configuration policy schema. Drag and drop the structure onto the corresponding service action CONTENTVALUE parameter to automatically generate the XSLT snippet for the parameter binding. Refer to Configuration Policy Use in this document, and Mapping OSM Data to Service Action XML Parameters in Design Studio online Help, for additional information. Referencing Newly Created Objects in the Scope of an Activation Task All IP Service Activator service actions that are used to create a new object in IP Service Activator, such as IPSA_CREATE_VPN, and IPSA_CREATE_RTNUMBER, have a parameter called TAG_NAME, in addition to parameters that correspond to the object’s attributes. The tag name is optional and a convenient method for referencing a newly created object in subsequent service actions in an activation task. Alternatively, the full path can reference a newly created IP Service Activator object. Note that existing IP Service Activator objects can be referenced by either their numeric ID or full path. Numeric IDs are preferable to full paths, when available, because IP Service Activator processes them more efficiently. The example below shows how a tag name, such as ${newVpnRef}, can be a placeholder for the full path of a newly created VPN in the scope of an activation task. Alternatively, construct the full path in the form /Policy:"Policy"/Domain:"IPSA_DOMAIN_NAME"/Customer:"CUSTOMER_NAME"/Vpn:”VPN _NAME”. In this case, the activation task sends a request to IP Service Activator to perform the following actions in a single IP Service Activator transaction: create a VPN without any default route targets, and create a custom route target for the newly created VPN. IPSA_CREATE_VPN PARENT_ID (numeric ID or full path of customer in the form /Policy:"Policy"/Domain:"IPSA_DOMAIN_NAME"/Customer:"CUSTOMER_NAME") NAME TAG_NAME (newVpnRef) CREATEDEFAULTRTNUMBERS(False) IPSA_CREATE_RTNUMBER PARENT_ID (${newVpnRef}) NAME (RTHIGHORDER-RTLOWORDER) Best Practice Guidelines Page 28 of 65
  • 29. RTHIGHORDER RTLOWORDER MESHBEHAVIOUR Activation Task Response Activation response data for a query operation includes the results of the query. Response Data Mapping in the activation task Response Data tab in Design Studio is appropriate for use with query operations to bind results to arbitrary OSM order data. Whereas Set Data Location uses a fixed structure for the response, and is appropriate for other event and exception data. Activation responses for discovery are not monitored to ensure they completed successfully. For activation transactions that are initiated through an OSM activation task, IP Service Activator Web service uses the resulting transaction provisioning status to confirm that activation is successfully applied to network elements. Full transaction status monitoring in the IP Service Activator policy server is turned on by default, and must not be disabled when using IP Service Activator Web services. Transaction status monitoring ensures that, when a transaction is not completed within the period of time configured in the policy server (whether successfully or with failures), the transaction times out. See the IP Service Activator User’s Guide for more information about the meaning of provisioning statuses returned by the transaction status monitor, and configurable transaction status monitor parameters, including TransactionMonitoringTimeout value. Activation responses for service actions, which result in an IP Service Activator transaction, are described in the table below. Activation Task Response Event/Exception Provisioning Status (determined by transaction status monitor) Meaning Recommended Practice orderCompleteEvent Succeeded The transaction changes are saved to the database, and related configuration changes (if any) are propagated to the network. Notification indicates successful creation, modification, or uninstallation of corresponding configuration. The response mapping in an activation task is typically configured to transition to a success status to continue OSM processing at the next task in the process when orderCompleteEvent is received. Note: Configuration changes may not propagate to all interfaces where they Best Practice Guidelines Page 29 of 65
  • 30. were expected to because, for example, devices are in an unmanaged state, or inadequate roles applied to devices or interfaces in IP Service Activator, which affects role matching. orderFailEvent Failed Transaction changes are saved to the database, and related configuration changes propagated to the network, and notification indicates the creation, modification, or uninstallation of corresponding configuration is rejected. The activation response includes the reason for failure. Generally, the response mapping in an activation task would be configured to transition to a failed status to handle activation task failure when orderFailEvent is received. Note: This event does not apply to Query and Discovery service actions. orderTimeoutEvent Timeout Transaction changes are saved to the database, and related configuration changes propagated to the network, and success or failure notification is not received in the transactionMonitoringTimeout period. Generally, the response mapping in an activation task would be configured to transition to a failed status to handle activation task failure when orderTimeoutEvent is received. An investigation in IP Service Activator can determine whether or not activation has succeeded after the timeout period. Note: This event does not apply to Query and Discovery service actions. createOrderByValueEx ception Not applicable due to failure to create transaction IP Service Activator is unable to commit a transaction due to either the accumulated operations having an invalid impact on the object model or the net effect of the service actions being no changes to the IP Service Activator object Eliminate such exceptions in design as much as possible. For example, ensure solution configuration data (if any) references objects that exist in IP Service Activator, and order data Best Practice Guidelines Page 30 of 65
  • 31. model. The activation response includes the exception message. meets IP Service Activator data restrictions, including adhering to valid parent/child relationships in the IP Service Activator object model. The response mapping in an activation task is typically configured to transition to a failed status to handle activation task failure when createOrderByValueExcep tion is received. Activation Task Run-Time Overview An overview of the run-time stages of an activation task is as follows: Create a single IP Service Activator transaction (if required for the service actions) o The activation task uses a transaction naming convention that correlates an activation task in an OSM order to an IP Service Activator transaction to provide the ability to roll back the transaction. The IP Service Activator transaction name is generated in this format: ws_[order Key]_[type] where [order Key] is a string made up from two separate components, the OSM order ID and OSM order history ID, and the [type] is either “submit,” “cancel,” “replace,” or “rollback.” The OSM order ID is common among all activation requests made for the same OSM order. The order history ID is unique for each activation request made for a given order ID. The combination of the two results is a unique key for each activation request. The original creation of an activation order results in the “submit” type. If this activation request is later rolled back, a new transaction is created with the “rollback” type. If the activation order is canceled or replaced, the “cancel” or “replace” types are used. Perform transaction operations o Execute the service actions required, such as create/modify/link/unlink/use/unuse/delete. Best Practice Guidelines Page 31 of 65
  • 32. o Existing objects are referenced either by IP Service Activator object ID or by their full path for objects that are to be created. Objects to be created are those that will be created by the ongoing transaction. For example, if the first step is to create a sub-interface object and link it to an Interface Policy Registration object (to create a managed sub-interface), the implicit configuration policy that gets created on commit can be accessed using its path+name within the same transaction. Alternatively, all CREATE service actions also have an optional TAG_NAME parameter. The TAG_NAME is a convenient way to reference the newly created object in subsequent operations in the same activation task without needing to construct the path+name directly. Commit IP Service Activator transaction o The activation task is successful when the transaction is committed, with updates made to the IP Service Activator object model, as required by the service actions, and network activation succeeds without error faults. o A successfully committed transaction does not imply successful network activation. If network activation fails with error faults, IP Service Activator rolls back the configuration changes on the network devices. Whether the IP Service Activator transaction is rolled back or not depends on the activation task order header setting for rollbackIfFailure, and, if not specified, the system-wide default setting for RollbackOnFailure in the configuration GUI. o Transaction commit can fail if the accumulated operations have an invalid impact on the IP Service Activator object model (for example, the transaction contains a link operation that attempts to link a sub-interface object to a device object). If this happens, the transaction is not retained in IP Service Activator and its operations are not performed. In an OSM process context, such a situation typically points to an error in the OSM cartridge or in assumptions made about IP Service Activator. Another source for such failure can be invalid attributes for an object, or invalid values for an object’s attribute. These failures should be eliminated in design by adhering to a properly crafted data schema describing the IP Service Activator objects. Order Enrichment The OSM order may need supplementary information that is missing from a service order or technical order, which is submitted to OSM, but is required for activation. Refer to the topic in this document ‘Identify Supplementary Information for Activation’ for sources of supplementary information. Best Practice Guidelines Page 32 of 65
  • 33. Adding to OSM Order Data by Manually Selecting Data Choices This section is about adding to OSM order data by manually selecting data choices retrieved from IP Service Activator Web services. You can define data providers with the built-in SOAP adaptor in conjunction with data instance behaviors. Add to OSM order data by retrieving information from IP Service Activator Web services. At run time, use an OSM manual task to make selections from among the results returned for an IP Service Activator Web services query. See Design Studio online Help for information about defining data providers and data instance behavior in Design Studio. See IP Service Activator OSS Integration Manager Guide for information about finding and retrieving data using the Web services interface. The query must include sufficient filtering criteria to restrict the volume of results. For example, finding an object in IP Service Activator may include the parent or child object from which to begin the search, and/or specified attribute values on the object to find. Use multiple queries to limit the results. For example, a query to find sub-interfaces on a device produces too many results on large devices. However, multiple queries, each with values supplied for filtering criteria at each stage can be designed to successively drill down from a device selection to an interface selection, and then to a sub-interface selection. Note: IP Service Activator Web services can also be invoked in upstream systems to support design and assign activities that occur in creating the original incoming order. Augmenting OSM Order Data This section is about augmenting OSM order data by loading a mapping of provisioning order data to pre-defined IP Service Activator data. You can define data providers with the built-in XML file adaptor in conjunction with data instance behaviors to augment OSM order data by retrieving data from an XML file. For example, a solution configuration file can provide a mapping of data values provided in a provisioning order to data, which is pre-defined in IP Service Activator. This applies to objects in IP Service Activator, which can be treated as constants, for example, objects that are created once using the IP Service Activator User Interface, and then referenced many times using the flow- through implementation. For example, a provisioning order might specify marking for QoS policies as one of the following: Realtime, Interactive Video, Transaction Data, Best Effort. The values can be mapped to pre-defined packet marking in IP Service Activator, such as EF, AF41, AF21, and BE. Another example is a mapping of QoS profile names to object IDs of MQC PHB Group definitions, or custom roles in IP Service Activator. For more information, see “Pre-defined Quality of Service Profiles” in this document. Best Practice Guidelines Page 33 of 65
  • 34. Tip: A solution configuration file in xml format is a resource in OSM. Resources in OSM can be referenced by URI locators. XML catalogs in OSM provide redirection from a URI to another URI. By redirecting the resource URI locators, XML catalogs insulate the cartridge solution from environment configuration, for example having separate solution configuration for test and production environments. Another example is to add QoS profiles without having to rebuild and redeploy the solution cartridges. See Oracle Communications Order and Service Management Developer's Guide for more information about using XML catalogs in OSM. Best Practice Guidelines Page 34 of 65
  • 35. Using Order and Service Management Effectively Orchestration A single order typically includes multiple order line items that request multiple services and fulfillment actions. To process the order, some line items need to be fulfilled before others. You can use orchestration to handle all of the fulfillment actions in the most efficient way possible, taking into consideration all of the dependencies between the actions. You can create orchestration plans for services for various fulfillment modes, such as to deliver services or cancel an in-flight-order. Please refer to the OSM documentation for a detailed discussion on the benefits of choosing orchestration. Choosing Orchestration Over Static Process Flows Dynamic view of order items One of the most powerful aspects of orchestration is the ability to group order items (the view) dynamically at runtime and have process execution tailored to each set. Orchestration provides this functionality through multiple stages of decomposition. The framework can be tailored to any arbitrary breakdown that is required, but two well known examples of such additional decomposition are for Target System and Processing Granularity. Flexibility of Target System For example, within the Rapid Service Design and Order Delivery (RSDOD) solution architecture, a technical order delivers actions against resources and resource facing services after upstream design-and-assign operations are complete. The technical order actions change the network to match the service design and are realized by one or more fulfillment functions coordinated with an orchestration plan. Fulfillment functions can represent: supply chain management to ship equipment; work force management to install equipment; activation to activate specific configuration in the network; and update operations to update inventory. Activation can be implemented by one or more activation systems, each with its own interface. Best Practice Guidelines Page 35 of 65
  • 36. Converged Technical Order Management and OSM-IPSA Orchestration Sequences In the RSDOD context, the orchestration plan for incoming technical line items is created by decomposing the set of order lines through multiple processing stages to determine applicable fulfillment functions, fulfillment systems, and the specific process invoked by the executable order component to achieve the requested functionality. For technical line items that apply to activation, these line items are associated with the activation fulfillment function, with decomposition rules further subdividing these lines into sets applicable to specific activation systems, such as IP Service Activator and ASAP. For IP Service Activator, a further decomposition stage identifies the specific executable order components and associated processes responsible for delivering each line item to IP Service Activator. Line items destined for other activation systems use other processes to interface to downstream systems. Flexibility of Processing Granularity Line items that are alike not only get directed to the same fulfillment function, but you may want to have a subset of site line items processed together, which means an additional decomposition stage for processing granularity. Taking site lines as an example, you might process all sites together (whole order granularity), process only those sites that share a common parent line item (bundle granularity), or process each site line individually (order item granularity). The process would be executed once for each granularity grouping. Performance or debugging reasons may dictate that the optimal processing granularity may be at the bundle level instead of whole order (that is, all site lines sharing the same parent VPN). Example 1: If an activation task processes with whole order granularity (all site lines), a failure or timeout for any one line item results in the failure of the entire task. The failures that are reported back may be for only the first one or two faults. You must then fix the first problem, retry the request, find the next failure, retry, and so on. If the activation task processes order items at a more granular level, it allows activation to succeed or fail for a smaller grouping of lines, making it easier to isolate failures for that group. Best Practice Guidelines Page 36 of 65
  • 37. Managing Sequencing and Dependencies Without orchestration, complex logic is often required in the OSM process to manage sequencing and dependencies. Example 1: The dependency between two services can be different depending on the fulfillment action. Deletion of hierarchical objects is one such example because the objects must be deleted in the reverse order that they are created. A specific example is the dependencies between VPNs and VPN Sites during creation and deletion. During creation, the VPN object must be created before the VPN site object. During deletion, it is the VPN site object that must be deleted before the VPN object. The complex conditional dependencies between the VPN and VPN site line items are more easily managed using orchestration. Example 2: Application of QoS to interfaces in a VPN is dependent on the VPN being created first. In order to ensure that the fulfillment functions for creating the VPN and configuring the QoS are executed in the correct order, dependencies between the fulfillment functions must be defined. At run time, if the incoming order contains a line item for QoS, the dynamic orchestration ensures that the fulfillment function for creating the VPN is executed before the fulfillment function for configuring the QoS. Compensation Choosing a Compensation Strategy for Activation Tasks An IP Service Activator activation task offers different compensation options than an activation task configured for ASAP. The available options for undo include: Ignore: applicable for activation tasks that include service actions that do not need to be undone, such as query/discover tasks. Manual: used if manual intervention is the only way to undo the work of an activation task. Cancel original order: sends a request to the IP Service Activator Web service to cancel a previous transaction ID. This option is configured for the ActivateL3SiteConfiguration task in the reference implementation. Create new order to undo: sends a new work order to IP Service Activator, with different service actions, to undo the work done previously. In some situations it is more practical to issue a new command to clean up resources in IP Service Activator than to cancel the transaction. One of the design principles mentioned previously is to group service actions that have a similar compensation strategy. This is to ensure that a compensation configuration for a task makes sense for all of its service actions. Recognizing Compensation Failures Best Practice Guidelines Page 37 of 65
  • 38. All OSM order data that was contributed during normal processing is removed from the query view during undo execution. When viewing the completed order, you must go to the Activity tab (in the orchestration client) to find activation results to help you determine what went wrong. Dealing with Compensation Failures Manual cleanup of IP Service Activator would be required. From an OSM perspective, failures of the rollback work order do not impact the remaining undo execution path. In normal execution, a task’s completion status can be used to direct processing. If a task completes with a failed status, this could be configured to navigate the flow to a manual task. In undo execution mode, this is not the case. The undo sequence is executed, regardless of any individual task’s completion status on the undo. Best Practice Guidelines Page 38 of 65
  • 39. Using IP Service Activator in a Workflow Environment Workflow Applications Workflow applications are expected to be used in a Service Fulfillment environment to improve the speed, consistency and quality of services configured in the network. This involves automating operations that result in service configuration delivery. Not all of the IP Service Activator OIM objects and operations, as described in IP Service Activator OSS Integration Manager Guide, are well suited for an automated (or largely automated) flow-through environment. In general, those operations that directly result in configuration delivery should be considered for flow-through scenarios. IP Service Activator Readiness IP Service Activator readiness refers to data that is pre-configured in IP Service Activator, outside workflow applications, such as using the IP Service Activator User Interface, to prepare the environment for automated operations. The majority of IP Service Activator readiness activities are not well suited to automation. It is recommended that devices are manually discovered into IP Service Activator as part of IP Service Activator readiness activities. See “Discovering a Device” for special considerations if you choose to include device discovery or re-discovery in an automated flow-through implementation. Operations Not Recommended for Automation It is recommended that all operations of an administrative nature be avoided in an automated flow-through implementation. These include: IP Service Activator user management: Creating, modifying, deleting users; changing passwords IP Service Activator permissions management: Specifying object permissions or modifying them Device management: Manage, unmanage, change command delivery mode, change command threshold values CTM template management: Add/remove templates, enable/disable templates Note: CTM template management is not applicable to CTM template use in a workflow application because service actions for CTM templates directly create configuration policies without first loading templates into the CTM request Best Practice Guidelines Page 39 of 65
  • 40. server. CTM template management is applicable to CTM module use within the IP Service Activator User Interface. Role Management Some objects in IP Service Activator are specified once and then referenced many times. One example is Device Role and Interface Role objects. Such objects should be created once, outside the flow-through implementation, such as using the IP Service Activator User Interface, and then referenced using the flow-through implementation. In addition, the IP Service Activator object IDs for these objects, in the form of numeric IDs or full paths, can be provided to the OSM activation tasks as configuration, avoiding frequent look-ups. See “Performance Considerations” section in this document for recommendations related to applying policies to target objects and role matching. Quality of Service Policy Management IP Service Activator allows for a flexible policy-based view of services. Depending on how this feature is implemented in a particular deployment, other objects may also be candidates for such treatment. For example, a set of standard QoS objects are defined and then “applied” to individual interfaces or devices by the use of roles. Another example is the use of Capabilities Objects that are defined once, outside of the flow-through implementation, and then linked to individual interface objects using the flow-through implementation. Vendor Cartridge Pre-check and Post-check Use IP Service Activator vendor cartridges may have pre-checks or post-checks enabled. Pre-checks execute commands to check and validate existing configuration on the device prior to activating configuration changes. Post-checks execute commands to validate the configuration applied to the device after activating configuration changes. At runtime, a service action which results in the execution of a pre-check or post-check may succeed or fail. A pre-check or post-check failure will result in an activation task orderFailEvent response in OSM. The activation response will include the reason for failure. Configuration Policy Use Configuration Policy objects have two layers of attributes. The top layer describes metadata about the object, such as its type and name. The inner layer – represented by the value of the ContentValue attribute – contains the actual service definition data required for activation. This content takes the form of an XML document conforming to the published XSD schema for that type of configuration policy. Modification of configuration policy instances must follow the “re-specify all values” pattern with respect to the contents of the ContentValue attribute. Best Practice Guidelines Page 40 of 65
  • 41. Service Actions for Productized Configuration Policies Specialized service actions for configuration policies include a create and modify service action for each of the productized configuration policies, such as IPSA_CREATECP_vlanSubInterfaceData, and IPSA_MODIFYCP_vlanSubInterfaceData for the vlanSubInterfaceData configuration policy. Use the IPSA_DELETE service action for delete operations. Use the IPSA_LINK service action to link device roles and interface roles to newly created configuration policies. To use this functionality: Pre-requisite: Load the policy files, corresponding to configuration policies in use, into a domain in IP Service Activator, and install any necessary vendor cartridges in IP Service Activator prior to runtime use of the service actions in OSM. The Design Studio project for IP Service Activator, which contains the service actions available for use in an activation task, also contains the data schemas for the productized configuration policies. They are modified from the original schemas to use primitive data types supported in Design Studio. You can select a subset of elements from the configuration policy schema, corresponding to the service action, into your OSM order template, and activation request data such as selecting elements from ‘vlanSubInterfaceData’ when using the service action IPSA_MODIFYCP_vlanSubInterfaceData. See the section below for information about the CONTENTVALUE parameter binding for the service actions. Service Actions for Custom SDK Configuration Policies Service actions for custom configuration policies include a create and modify service action, IPSA_CREATE_RULEGENERIC, and IPSA_MODIFY_RULEGENERIC. Use the IPSA_DELETE service action for delete operations. Use the IPSA_LINK service action to link device roles and interface roles to newly created configuration policies. To use this functionality: Pre-requisite: Create your own configuration policy to create a GUI form for IP Service Activator, and a schema to collect data for a service. You must also create service cartridges to implement the service on specific devices. Refer to IP Service Activator developer documentation for more information. Load the policy into a domain in IP Service Activator, and install the service cartridge prior to runtime use of the service actions in OSM. You can import a schema file, corresponding to a configuration policy, into Design Studio. S. Then select a subset of elements from the imported data schema into your OSM order template, and activation request data such as selecting elements from ‘staticRoutesSample’, or ‘bannersSample’ when using the sample SDK configuration policies. The value for the CONTENTTYPE parameter must be set correctly to the registered policy type such as ‘staticRoutesSample’ or ‘bannersSample’. See the section below for information about the CONTENTVALUE parameter binding for the service actions. Note: Do not import custom configuration policy schema files into the sealed Design Studio project for IP Service Activator, which contains the productized configuration policy schemas. Best Practice Guidelines Page 41 of 65
  • 42. Note: Design Studio does not support all possible data types and schema constructs. See data schemas in the IP Service Activator Design Studio cartridge for examples of supported constructs and data types. You can import data schemas into Design Studio by changing to the resource perspective, and dropping a schema file into the dataDictionary node of an Order and Service Management project. Before doing so, make a copy of the configuration policy schema file, and make the following changes: Ensure all primitive data types are changed to those that Design Studio supports. For example, Design Studio does not support xs:unsignedInt, but it supports xs:long, so change all occurrences of xs:unsignedInt to xs:long. For string data types, which do not have a maximum length assigned, set a maximum length, if necessary. Otherwise, Design Studio uses a default string length of 40. Keep in mind that Design Studio does not support importing pattern values to restrict strings based on regular expressions. After importing the schema file into Design Studio: Verify that none of the data elements specify primitive type ‘none’ For each string data type that has enumerated values, manually enter the enumerated values, copied from the original schema file, into the Enumerations tab in Design Studio. About the CONTENTVALUE Parameter Binding for Service Actions This section is about CONTENTVALUE parameter binding for service actions for productized and custom SDK configuration policies After you select nodes from the OSM order template into an activation task request data, the CONTENTVALUE parameter binding can be generated by use of specialized behavior in the activation task in Design Studio for XML data type service action parameters. For more information, see “Mapping OSM Data to Service Action XML Parameters” in Design Studio online Help. For example, drag and drop an OSM template node, such as 'vlanSubInterfaceData', ‘staticRoutesSample’, or ‘bannersSample’ onto the CONTENTVALUE service action parameter. You may need to edit the CONTENTVALUE parameter binding after it is generated by Design Studio. This is necessary when the structure includes Boolean data types. OSM Boolean Yes and No values must be converted to true and false for IP Service Activator. Tip: When you select nodes from various data dictionaries into an OSM order template, you may encounter name conflicts with nodes that already exist in the OSM order template. It is recommended that you do not unseal the sealed cartridges, and instead rename nodes in the OSM order template. This may require modifications to the service action parameter bindings to ensure configuration policy xml content for the ContentValue parameter specifies element names that are Best Practice Guidelines Page 42 of 65
  • 43. recognized by IP Service Activator. You use Design Studio to automatically make the necessary modifications to the parameter binding for the CONTENTVALUE service action parameter by dragging and dropping the corresponding node from the OSM order template onto the CONTENTVALUE service action parameter. Specialized Service Actions for vlanDefinitions and vlanInterface For information about the specialized service actions provided to support add/remove VLAN IDs from vlanDefinitions, and vlanInterface configuration policies in IP Service Activator, see OSS Integration Manager Guide. Interface and Sub-interface Creation IP Service Activator uses PolicyType objects as a directory of Configuration Policies available for use. In addition, it uses InterfacePolicyRegistration objects to designate the availability of specific configuration policies to create interfaces and sub-interfaces on the network devices. To use this functionality: Pre-requisite: Load the InterfaceManagementPolicyTypes.policy file into a domain in IP Service Activator, and create InterfacePolicyRegistration objects using IP Service Activator User Interface or by post-installation administrative activity. It is recommended that the IP Service Activator object IDs or full paths for these objects be extracted and made available to the activation tasks as configuration; these objects are long lived and their IDs can be treated as constants without having to look them up each time. Configure an ordered sequence of service actions in a single activation task. The sequence below is an example of service actions and parameter values for VLAN sub-interface creation using the vlanSubInterfaceData configuration policy. 1. Create a stub interface or sub-interface under the appropriate device or interface. The NAME of the subinterface and the PARENT_ID are mandatory. The PARENT_ID must be the numeric ID or full path of the device or interface. Optionally, specify a tag name, such as newSubInterfaceRef, so the newly created object can be referenced in the same activation task without having to construct the full path. IPSA_CREATE_SUBINTERFACE NAME (GigabitEthernet5/0.300) PARENT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN_NAME" /Network:"IPSA_DOMAIN_NAME"/ Device:"DEVICE_NAME"/Interface:"GigabitEthernet5/0") TAG_NAME (newSubInterfaceRef) Best Practice Guidelines Page 43 of 65
  • 44. 2. Link the InterfacePolicyRegistration object (as child) to the stub interface or sub- interface (as parent). Sample IPSA_LINK CHILD_OBJECT_ID (/Policy:"Policy"/InterfacePolicyRegistration:"VLAN subinterface creation") PARENT_OBJECT_ID (${newSubInterfaceRef}) 3. IP Service Activator automatically creates a RuleGeneric object of the correct type under the stub interface or sub-interface when this transaction is eventually committed. This object’s ContentValue attribute must be set to the XML document representing the computed Configuration Policy data. Compose “modify” command referencing the to-be-created RuleGeneric by path and name and providing the attributes and values needed to be modified. The auto-created name for this RuleGeneric object is the interface or sub-interface name with the suffix “-Data”. IPSA_MODIFYCP_vlanSubInterfaceData OBJECT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN_NAME"/Network:"I PSA_DOMAIN_NAME "/Device:"DEVICE_NAME"/ Interface:"GigabitEthernet5/0"/SubInterface: "GigabitEthernet5/0.300"/RuleGeneric:" GigabitEthernet5/0.300-Data) CONTENTVALUE (xml content for the configuration policy conforming to the ‘vlanSubInterfaceData’ structure) 4. Link the desired interface role (as child) to the stub interface or sub-interface (as parent). IPSA_LINK CHILD_OBJECT_ID /Policy:"Policy"/RoleInterface:"Access") PARENT_OBJECT_ID (${newSubInterfaceRef}) Interfaces and sub-interfaces created using the IP Service Activator user interface have their auto- created Configuration Policy object named the same as the interface or sub-interface name, without the “-Data” suffix appended during creations performed using OIM. You must consider this if flow-through processing needs to modify or manipulate interfaces or sub-interfaces created by IP Service Activator operators. Best Practice Guidelines Page 44 of 65
  • 45. CTM Template Use The Configuration Template Module (CTM) is a customizable configlet activation module. CTM replaces manual configuration on network devices and ensures configuration consistency for tasks of a repetitive nature. CTM automates the creation of data-entry GUIs from simple XML configuration templates to incorporate user input into the service configuration when used in an interactive mode by using the CTM client GUI. CTM can incorporate input from various data sources in a flow-through environment. See IP Service Activator Concepts for more information about CTM in IP Service Activator. Note the following pre-requisites for using CTM templates: The following policy file must be loaded into the domain in IP Service Activator to enable use of CTM service actions: ConfigletPolicyTypes.policy Each activation task that includes a CTM service action must also include subsequent IPSA_LINK service actions to link a device role and interface role to the configlet configuration policy created by the CTM service action. For use in flow-through, you can import a CTM Template into Design Studio to create a service action for use in an activation task. The service action will include parameters for the widget definitions in the CTM template. Use the service action in an activation task, and bind the service action parameters to OSM order data. As with any OSM order data, the data can be derived from various sources including incoming order data, or manual order enrichment using the OSM Web client. In this case, you do not need to load the CTM template into the CTM request server. See Design Studio online Help for more information about importing CTM templates into Design Studio. At runtime, the activation task takes care of transporting the XML template and the service action parameters to IP Service Activator Web services. At runtime, IP Service Activator Web service substitutes the parameter values into the template and creates a configlet configuration policy to instantiate the template on the desired object in IP Service Activator. It is recommended that you avoid designing a workflow that automatically retries the activation if a CTM template activation fails. Such an approach would proliferate template instantiations because each retry creates a new template instantiation. If there is an explicit sequencing requirement between the CTM-delivered configuration and the rest of the configuration in the IP Service Activator transaction, there should be more than one transaction. For example, the CTM template adds some configuration to an OSPF routing instance that is being created as part of the transaction. In this case, there are three possible transactions: one that creates the pre-requisite configuration using a normal IP Service Activator transaction, one activation task with a service action to instantiate the selected template, and possibly a third activation task to complete any configuration that requires the CTM- delivered configuration to be pre-existing. Best Practice Guidelines Page 45 of 65
  • 46. Some optimization may be possible in more complex multi-transaction workflows, based on dependencies between standard services, CTM templates, and device discovery operations. CTM template instances do not have meaningful modify operations; their behavior is stateless. The instances can be only created and deleted. About CTM Template Service Action Parameters CTM templates use the following service action parameters: OBJECT_NAME: the name of the configlet configuration policy. The value of this parameter must be a unique name for the configuration policy. PARENT_ID: the numeric ID or full path of the target where the configlet configuration policy object is linked, such as a device or interface. Example: /Policy:"Policy"/Domain:"IPSA_DOMAIN"/Network:"IPSA_DOMAIN"/Network:"cust omer1 network"/Device:"rot3640-1" TAG_NAME: the same as TAG_NAME for all other CREATE service actions. Specify a tag name such as ctmTemplateRef. The reference ${ctmTemplateRef} can be used in place of full path of the configlet configuration policy in subsequent service action parameters (such as PARENT_OBJECT_ID parameter in IPSA_LINK service action) which reference the configuration policy created by the CTM service action. The remaining service action parameters reflect the fields in the corresponding CTM template (that is, the CTM template that was imported to create the service action). It is recommended that you give descriptive names for the "key" attribute of each field in the CTM template. This must be done prior to importing the template in Design Studio. The key name becomes the element name, as well as the display name for the element in the data schema, which is created upon import. Note: The widget name is not used as the display name for imported fields because each widget in a CTM template can have multiple fields. You can select the elements from the new data schema, into the OSM order template, and into activation request data to use for the data binding to the CTM service action parameters. Tip: When you select nodes from various data dictionaries into an OSM order template, you may encounter name conflicts with nodes that already exist in the OSM order template. Do not edit imported entities in the Activation IPSA project, and instead use refactoring to rename nodes in the OSM order template. Managing Installed CTM Templates CTM templates are used to deliver configuration commands directly to the network device using instantiations (which take the form of Configlet configuration policies). Because there is no modeling of the service represented by those commands in IP Service Activator, the template instantiations have limited purpose after they have completed successfully. They: Best Practice Guidelines Page 46 of 65
  • 47. Serve as a reference of the current configuration delivered by IP Service Activator Are included in a full device audit (“audit –showAll …”), if the device is managed by the Network Processor On the other hand, each template instantiation counts as an object in IP Service Activator and the resulting concrete as another object. The size of the object model becomes a performance factor as the number of instantiations grows with time. The options available to deal with installed template instantiations (regardless of whether the templates were instantiated using the CTM Client GUI or the recommended flow-through method) are: Clean up Immediately: After successful installation, remove the template instance in a subsequent transaction that is still part of the same order flow. Use the IPSA_DELETE service action. This has the advantage of never leaving any template instances in IP Service Activator after they have done their job – delivering configuration to the device. On the other hand, the presence of this configuration is not reflected in the IP Service Activator object model in any way other than historical trace in the transaction records. Also, if there are no other IP Service Activator activation tasks in the workflow, this approach results in a new IP Service Activator activation task becoming part of the OSM flow, which increases the time it takes to complete order processing. If there is already another IP Service Activator activation task in the flow, the template instance removal can be included with that task’s operations. Clean up Later: Leave installed templates in place until they are superseded or no longer required. A template instance can be deemed superseded if a subsequent template instance modifies the configuration delivered by the first instance. A template instance is no longer required if the configuration delivered is to be removed. Note that removing a template does not remove the configuration it generated when it was first applied. This approach has the advantage of presenting the current configuration representation fully in IP Service Activator, while at the same time, capping the sizing load on the IP Service Activator object model by avoiding accumulation of unused/expired template instances. In practice, the implementation of such an approach tends to be more complex because each activation must account for pre-existing template instances and correctly delete them. Clean up Offline: Separate template instance clean-up from order activation – perform template clean-up in a separate periodic process run from outside the context of the OSM- IPSA integration. Best Practice Guidelines Page 47 of 65
  • 48. This approach greatly simplifies the order activation in OSM – the tasks only need to deliver template instances and not clean-up activities. In addition, the separate clean-up allows for more flexibility. It can be simple (remove all installed template instances) or complex (identify expired template instances and remove only those). The disadvantage with this approach is that a simple clean-up can remove “current” instances as well as expired ones, while a complex clean-up might require additional context information to decide what is expired and what is current. Some CTM templates may not deliver configuration commands, but instead deliver operation commands to the device (for example, to zero certain statistics counters). These cannot really participate in an audit and do not reflect the configuration, and so, can be cleaned up immediately. Similarly, CTM templates that delete configuration (say, to undo a previously installed template that delivered the configuration) can also be cleaned up immediately after installation for the same reasons. Rollback of CTM Template Instances For other IP Service Activator objects, the act of reversing the operation on the object results in appropriate configuration changes on the network devices. However, the act of removing a CTM template instance (the configlet type configuration policy) does not lead to the removal of the commands introduced by the template from the network device. The workflow designer must examine the need to roll back the CTM templates. It is not required if the standard rollback deletes the context of the commands in the template. For example, if the activation transaction created an OSPF routing instance for a VPN site and used a CTM template to add commands to this routing instance, no specific removal might be necessary for the template. The removal of the OSPF routing instance as part of a normal rollback removes all subordinate commands including those delivered by the CTM template. For CTM templates that need to be explicitly rolled back, each template must be paired with a rollback template that executes the commands required to undo the template. Capabilities Objects Manipulation IP Service Activator device, interface, and interface policy registration objects are linked to capabilities objects. See IP Service Activator OSS Integration Manager Guide for more information about the linkages and the different types of capabilities objects. Capabilities objects are not deleted using activation tasks. When they are not needed by the parent object (for example, the interface), they must be unlinked from the parent. The capabilities object might still be used by other parents. IP Service Activator core cleans up the object if the unlink operation results in its being orphaned. Best Practice Guidelines Page 48 of 65
  • 49. For the same reason, these objects must never be modified. Any modification immediately applies to all parents and affects the services configured on them. If interface capabilities need to be updated in flow-through (for example, due to a change in the protocol of the interface), the recommended way is to have a pre-computed set of capabilities objects ready in IP Service Activator and simply link them to the interface after unlinking the existing capabilities objects from IP Service Activator. The simplest way to do this is to create a dummy Interface Registration Policy (keep it disabled to prevent its actual use) and set it up with the desired capabilities by stealing them from an interface of the desired type as a one-time setup task (see Oracle Support Knowledge article 1268094.1). Now the workflow can use these capabilities objects over and over, by linking to their IP Service Activator object IDs. Their IDs can be provided to the service actions using configuration parameters. Quality of Service Pre-Defined Quality of Service Profiles MQC-PHB Group definitions, such as those used to apply standard quality of service policies at the PE interface, can be defined once in IP Service Activator, outside the flow-through implementation, such as using the IP Service Activator User Interface and then referencing them many times, using the IP Service Activator flexible, policy-based view of services. You can define QoS profiles, such as profile1, profile2, … profileN, and establish how they can be realized in the network configuration: 1. Line items in the incoming provisioning order (inbound to OSM), and/or order enrichment in OSM, can provide the QoS profile selection, such as a QoS profile name and any other criteria used to determine which pre-configured QoS to apply to specified points in the network. 2. QoS policy definitions, and custom interface roles, if required, need to be configured in IP Service Activator. For definitions that are defined once, outside the flow-through implementation, such as using the IP Service Activator User Interface, you can use the integration manager command line interface to find the object IDs. You can provide the object IDs to OSM in a solution configuration file, as opposed to hard-coding values in Design Studio project code, to isolate constants for ease of maintenance. For more information about defining Quality of Service policies, such as MQC-PHB Group definitions, see IP Service Activator QoS User’s Guide. For more information about defining roles and assigning them to policy targets to apply policies at selected points in the network, see IP Service Activator User’s Guide. For more information about finding objects using the integration manager CLI, refer to IP Service Activator’s OSS Integration Manager Guide. Best Practice Guidelines Page 49 of 65
  • 50. 3. A solution configuration file in xml format can provide a QoS profile mapping as an OSM cartridge resource. Criteria, such as a QoS profile name and interface direction, can be mapped to IDs of objects pre-configured in IP Service Activator, such as an MQC-PHB Group definitions and/or custom interface roles. Such a mapping table can be loaded from a file into a structure at the root of the OSM order template using the Order Data Rule. If the mapping table is loaded into a structure in the OSM order data, parameter bindings for service actions in an activation task such as the POLICY_OBJECT_ID parameter for the IPSA_USE service action can directly reference an MQC-PHB Group ID in the structure in the OSM order data by building an expression to look up the values based on information available in the order item, or any associated order items. To add support for additional QoS profiles, add data entries to the solution configuration file. For more information about the Order Data Rule see “Order Recognition Rule Editor Transformation Tab” in the Design Studio online Help. 4. QoS Policy definitions must be targeted to specific points in the network. Pre-defined MQC-PHB Group definitions can be used directly by each interface where applied, or used by a target in either the topology hierarchy of the interface, such as the network, or device, or to a target in the services hierarchy of the interface such as the customer, VPN, or site. To use an MQC-PHB Group definition, include the IPSA_USE service action in an activation task. Considerations of the various alternatives: IP Service Activator Performance: Linking a definition to an object lower in the hierarchy improves IP Service Activator performance when calculating concretes for activation. Pre-apply QoS policies: Linking a definition to an object higher in the hierarchy, which is also pre-configured, such as the PE device, allows you to pre-apply pre- defined policies, such as using the IP Service Activator User Interface. In this case, the activation task only needs to assign interface roles to target interfaces, using the IPSA_LINK service action in an activation task, to activate a policy at the interface. Custom Quality of Service Policies MQC PHB group definitions, such as those used to apply custom quality of service policies at the CE access interface, can be defined in the flow-through implementation, for example using the activation task in an OSM solution. A combination of existing objects, for example packet markings and newly created objects, such as custom classification criteria, may be referenced after they are created. An example shows a possible custom quality of service definition in a flow-through implementation and how to configure a sequence of service actions in an activation task to create an MQC-PHB group in IP Service Activator and apply it to target interfaces through role matching. In this example, you create an MQC PHB group and apply it to CE access interface(s) on a customer edge device (outbound) to classify customer traffic. Best Practice Guidelines Page 50 of 65
  • 51. A CE device is already discovered, managed, and assigned a device role of Access (ID=4). A custom interface role exists, such as CE_Access. A specific interface on the CE device (PE-facing) was assigned the CE_Access role when the CE device was discovered. The CE device is linked to a layer 3 MPLS VPN site in IP Service Activator. The custom MQC PHB group is applied to the site so that policy is applied to all CE_Access interfaces in the site. The packet markings used in this example, such as BE, EF, AF21, and AF41, are created automatically by loading the advanced.policy file into the IP Service Activator domain. In this example, the provisioning order specifies marking as one of the following: Realtime (EF), Interactive Video (AF41), Transaction Data (AF21), Best Effort (BE). These can be mapped to pre-defined packet markings in IP Service Activator in a solution configuration xml file, which is available to the OSM as a cartridge resource. This example uses PHB group folders. Using of folders helps to organize information in the UI and is optional. For example, folders can be based on customer name, and, for the purpose of organizing custom QoS policies to be applied to customer edge devices, you can create them when the customer object is created in IP Service Activator. This example uses tag names (a placeholder for full paths) to reference newly created objects in an activation task. For more information, see “Referencing Newly Created Objects in the Scope of an Activation Task” in this document. IP Service Activator objects in this example: IPSA_DOMAIN (Domain) Customers customer1 (Customer) Sites site1 (Site) CEdevice (Device) VPNs vpn1 site1 Management ManagementVpn site1 Classes of Service Best Practice Guidelines Page 51 of 65
  • 52. COS_site1 (Class of Service) Classifications class_site1_ipv6_any_dst (Classification) PHB Groups customer1 PHB Groups (PHB Group Folder) customer1-site1-marking-CEOut (MQC PHB Group) An ordered sequence of service actions is configured in a single activation task to achieve the sample scenario above. In this case, create a PHB group folder named 'customer1 PHB Groups' in domain 'IPSA_DOMAIN'. The PARENT_ID of a PHB group folder must be the numeric ID or full path of a PHB group folder or domain. Optionally, specify a tag name, such as newFolder, so the newly created object can be referenced in the same activation task without having to construct the full path. IPSA_CREATE_PHBGROUPFOLDER NAME (customer1 PHB Groups) PARENT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN") TAG_NAME (newFolder) In this case, create a Classification named 'class_site1_ipv6_src_any_dst' in domain 'IPSA_DOMAIN'. The PARENT_ID must be the numeric ID or full path of a classification folder, or classification group, or domain. Optionally, specify a tag name such as newClassification so the newly created object can be referenced in the same activation task without having to construct the full path. In this case, the ADDRESSTYPE is ‘IPv6’, which requires IPv6 source and destination parameters to be conditionally included. IPSA_CREATE_CLASSIFICATION NAME (class_site1_ipv6_src_any_dst) PARENT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN") TAG_NAME (newClassification) ADDRESSTYPE (IPv6) CLASSIFICATIONMATCH (True Note: True means Classification Match Type is Include) SOURCEIPV6ADDR (2001:db2:ae3:2::/64) DESTINATIONIPV6ADDR (::/0 Note: ANY) Best Practice Guidelines Page 52 of 65
  • 53. Create a class of service. The PARENT_ID must be the numeric ID or full path of a Class of Service Folder, or Domain. Note: Optionally, specify a tag name such as newCOS IPSA_CREATE_COS NAME (COS_site1) PARENT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN") TAG_NAME (newCOS) TYPE (User) Link classification (child) to class of service. Alternatively, a classification group can be linked. IPSA_LINK CHILD_OBJECT_ID (${newClassification}) PARENT_OBJECT_ID (${newCOS}) In this case, create an MQC PHB group, which applies to outbound traffic, under the newly created folder 'customer1 PHB Groups'. A value of False for the CREATEDEFAULTPHBMQC parameter means that IP Service Activator does not automatically create a child PhbMqc object named Default Class of Service for the PhbGroupMqc, and in this case at least one PhbMqc child object must be created. IPSA_CREATE_PHBGROUPMQC NAME (customer1-site1-marking-CEOut) PARENT_ID (${newFolder}) INBOUND (False) OUTBOUND (True) CREATEDEFAULTPHBMQC (False) TAG_NAME (newPhbGroupMqc) You can create multiple PHBMqc objects as children of the PHBGroupMqc object. At least one PhbMqc is required. A single PhbMqc object is created to set marking to BE (Best Effort) for outbound traffic matching the classification criteria defined for the 'COS_site1' class of service. Note: Action 32 is Mark. IPSA_CREATE_PHBMQC NAME (COS_site1) PARENT_ID (${newPhbGroupMqc}) Best Practice Guidelines Page 53 of 65
  • 54. ACTION (32) COSNAME (COS_site1) DSCPMARKING (BE) The device and interface roles are set up to indicate which interfaces the MQC PHB group will apply to. In this case, the MQC PHB group is applied to CE_Access interfaces on the CE. Therefore the PHBGroupMqc object is linked to the Access device role (ID=4) and the custom CE_Access interface role : IPSA_LINK CHILD_OBJECT_ID (4) PARENT_OBJECT_ID (${newPhbGroupMqc}) IPSA_LINK CHILD_OBJECT_ID (numeric ID or full path of CE_Access role) PARENT_OBJECT_ID (${newPhbGroupMqc}) An MQC PHB group is applied to a policy target with the use command. In this case, the MQC PHB group is applied to a layer 3 MPLS VPN site, which has the CE device linked to it, so that the policy will be applied to all CE_Access interfaces in the site. IPSA_USE POLICY_OBJECT_ID (${newPhbGroupMqc}) TARGET_OBJECT_ID (/Policy:"Policy"/Domain:"IPSA_DOMAIN"/Customer:"customer1"/ Site:"site1") Failure Handling When a failure situation is detected coming from IP Service Activator Web services in response to an activation request, additional information regarding the failure can be found in the activation task response. For more information, see the Activation Task section in this document. Handling Failures Automatically or Manually When a failure is detected, in addition to logging details of the failure and updating the OSM order, the following design choices are generally possible: Transition the order to a task that includes the failure information and allows you to investigate and clean up before either abandoning the OSM order or retrying the order processing from a pre-defined point in the workflow. Best Practice Guidelines Page 54 of 65
  • 55. Find a task that attempts to roll back the failed transaction, restore IP Service Activator and the network to a known state, and then investigate and clean up as above. Same as the above option but, in addition, recognize certain types of failures and execute tasks to implement known pre-defined automated solutions. It is recommended that you use the first option for activation failure. You can then evaluate, on a per-IP Service Activator activation task basis, whether a user would prefer to see the system in the failed state or in a pre-activation state. For tasks that conform to the latter expectation, use the second option. With experience, you can accumulate some statistics on the most common failures. These can be analyzed to see if the resolution is suitable for automation. The factors include the predictability and the algorithmic nature of the resolution, as well as the nature of the external systems involved in the procedure. Carefully analyze the costs and benefits by comparing the cost of automating the resolution procedure versus the frequency of occurrence and the resources saved by automation. For scenarios that are deemed beneficial, the workflow can be augmented with tasks that implement a resolution procedure. Rolling Back Transactions The activation task can be configured to roll back an IP Service Activator transaction by one of three methods: configuration of Undo compensation, which is triggered by submitting a cancelation order from upstream to OSM. This is applicable when compensation is configured for activation tasks in the OSM solution. a subsequent activation task in the OSM process, which explicitly includes an IPSA_ROLLBACK service action. This service action has a parameter to identify which IP Service Activator transaction to roll back. configuration of the activation order header parameter ‘rollbackIfFailure’ to true to automatically roll back upon detection of activation failure. If this parameter value is not specified, the system-wide default setting for RollbackOnFailure in the configuration GUI is used. This means that the failure to successfully complete an IP Service Activator activation task returns the IP Service Activator system, and the involved network elements, to their prior state. There are some constraints on the rollback operation, as documented in IP Service Activator OSS Integration Manager Guide. It is recommended that a rollback, if required, is done immediately after detection of activation failure. There is a configurable limit to the number of transactions archived and a transaction can no longer be rolled back after it is deleted. Transactions executed between the original transaction and a rollback attempt may also affect the state of IP Service Activator objects in a way that might prevent the successful rollback of the original transaction. Best Practice Guidelines Page 55 of 65
  • 56. The rollback operation is an IP Service Activator transaction that could lead to network changes, so it can also succeed, fail or timeout, as determined by the transaction status monitor. The failure of a rollback is logged by IP Service Activator Web services. It is recommended to handle the failure using a manual procedure. The rollback capability in IP Service Activator may leave fault artifacts in the object model, provided these faults resulted from processing the transaction and were not part of the transaction itself. Object model validation faults are typically part of the transaction and are rolled back. Faults coming from network devices are not part of the transaction and may remain in the system. These faults can affect subsequent operations on those devices and may require additional processing to clean up. This process can be automated, when there is full knowledge of possible errors in each scenario, or done as a manual task. The undo compensation strategy for an activation task, which creates an IP Service Activator transaction, is to roll back the transaction. To avoid the possibility of attempting to roll back a rolled back transaction, it would not be a recommended practice to both configure undo compensation for an activation task such as to rollback when an order cancellation request is received from upstream, and include an option for a manual user to proceed to an activation task in the workflow to rollback the transaction. Additional Rollback Considerations When using the IP Service Activator transaction rollback capability from an OSM workflow, some additional considerations apply. Workflows with Multiple Activations Some IP Service Activator operations cannot be rolled back, such as the discovery and re- discovery of network objects. See Workflow Applications in this document for more information. Rollback of CTM Template Instances If the activation task includes a service action to activate a CTM Template, special consideration applies to rollbacks. For more information, see Rollback of CTM template Instances in the section CTM Template Use in this document. Performance Considerations Transaction Size Versus Number of Transactions You can leverage the IP Service Activator design to ensure maximum throughput by minimizing the per-transaction overhead in the system. This can be accomplished by minimizing the number of activation transactions. Multiple transactions issued serially can cause an order to wait for activation each time. Fewer transactions reduce the time that an activation order spends waiting Best Practice Guidelines Page 56 of 65
  • 57. for IP Service Activator to complete activation in the network. The execution of a single activation task at runtime culminates in either a single IP Service Activator transaction, or no transaction, such as for a query of data from IP Service Activator or device discovery action. Minimizing the number of activation transactions also maximizes the ability of IP Service Activator to optimize configuration changes to network devices. IP Service Activator optimizes the configuration changes to network devices for operations arriving in the same transaction. IP Service Activator also batches and optimizes configuration changes for multiple transactions arriving before the next push to proxies. Scope of Activation Request: Applying Policies to Target Objects and Role Matching in IP Service Activator Policies such as MQC-PHB Group definitions, and configuration policies can be linked directly to each interface where applied, or to a target in either the topology hierarchy of the interface, such as the network, or device, or to a target in the services hierarchy of the interface, such as the customer, VPN, or site. Applying a policy to target lower in the hierarchy improves throughput by limiting the scope of the calculation of affected concretes in IP Service Activator, and reduces the potential impact of activation changes. Activation changes are limited to interfaces within the scope of the policy target, for which the device role and interface role match those roles assigned to the policy. It is recommended to confine the scope of an activation request to a logically related set of services, where the impact is on a limited number of concretes. It is not recommended to perform operations at the network level, where the impact can affect or create a very large number of concretes. Multi-OIM Usage IP Service Activator Web services configuration supports scaling of its use of the OIM API throughput by deploying multiple instances of the OIM. A flow-through implementation can leverage this ability if the throughput requirements indicate the need for multiple OIMs. The IP Service Activator object model exists in multiple copies, one in each of the running User Interface and OIM instances and in the Policy Server. The object model in the Policy Server is the master. All copies synchronize themselves against the master. The master receives updates from each copy validates it, and transmits the updates to all the copies. Due to the distributed nature of the model, it is possible that at any given moment the models on the various OIMs and User Interfaces are not identical until the synchronization happens. For example, this can occur just after issuing a commit on one OIM. While it is not possible to use this behavior to corrupt the object model by user action (since the model is protected against such corruption), it is possible for an automated system to see an out-of-date picture. For example, if a program commits a transaction into one OIM and immediately looks for the transaction object in another OIM, it is possible that the lookup might not return any data. A wait Best Practice Guidelines Page 57 of 65
  • 58. followed by a retry may be required to allow time for the models to synchronize. The amount of time to wait (or the number of times to retry) should be tunable because it depends on the number of OIMs and User Interfaces running and on the overall load on the IP Service Activator system. It is recommended that when IP Service Activator Web services is configured to use multiple OIMs, and operating on objects that may have been recently created or modified in another OIM, the developer adopt a wait and retry pattern on lookup failures. The converse situation can also happen. An object deleted during a transaction in one OIM may still appear in another OIM, if the lookup happens within the window of time for model synchronization. It is recommended that the automation not switch between OIMs for operations involving recently created or updated objects unless model synchronization has been accounted for, either by using the wait and retry pattern or by ensuring enough time has passed. Best Practice Guidelines Page 58 of 65
  • 59. Troubleshooting Troubleshooting Installations Check the installation guide of the product you are installing for troubleshooting information. Some common problems and resolutions are given below: Database Schema Privilege Check Error During OSM Installation Problem: You get a Database Schema Privilege check error on the Database Administrator Credential Information window of the OSM installation. Solution: You can either follow the instructions in the error window or try appending ‘as sysdba’ to the user name you specified for Database Admin Username, such as ‘system as sysdba’ for username ‘system’. Unresolved Application Library references When OSM Managed Server Restarted After OSM Installation Problem: You have created a WebLogic domain and installed OSM, and you get this error when you restart the OSM managed server: weblogic.management.DeploymentException: [J2EE:160149]Error while processing library references. Unresolved application library references, defined in weblogic-application.xml: [Extension-Name: adf.oracle.domain, exact-match: false], [Extension-Name: oracle.jsp.next, exact-match: false]. Solution: The Oracle WebLogic Server software must be installed with the Oracle Application Development Framework (ADF). If you have installed Oracle JDeveloper, you do not need to install WebLogic or ADF separately; you need to select Oracle JRF in your WebLogic domain. If you have installed the Oracle WebLogic Server, you need to download and install ADF software and extend your WebLogic domain with it. See Oracle Communications Order and Service Management Installation Guide for OSM software requirements and for installing and configuring Oracle WebLogic Server for OSM. Cannot Create File System at Attachments When OSM Managed Server Restarted after OSM Installation Problem: Cannot create file system at Attachments error when you restart OSM managed server after OSM Installation. Best Practice Guidelines Page 59 of 65
  • 60. Solution: The first time you re-start the WebLogic server after installation, an exception indicating ‘Cannot create file system at Attachments’, or ’T3 file attachment not found’ is expected. If you installed OSM in a clustered environment, refer to the Oracle Communications Order and Service Management Installation Guide for post-installation instructions to configure the T3 File Path to support attachments. Otherwise, restart the OSM managed server. The error should not recur after a WebLogic restart. NoClassDefFoundException When You Run OSM SDK Script credStoreAdmin.bat Problem: When you run the OSM SDK script credStoreAdmin.bat, you see a NoClassDefFoundException: Exception in thread "main" java.lang.NoClassDefFoundError: oracle/security/jps/mas/mgmt/jmx/credstore/PortableCredential Solution: Ensure that the MIDDLEWARE_HOME variable in config.bat is set correctly in your OSM SDK folder to the Fusion Middleware installation folder (such as C:OracleMiddleware). See Oracle Communications Order and Service Management System Administrator's Guide for information about Order and Service Management SDK scripts. Failed to Acquire an EomSession When a Test Order Submitted to OSM Problem: Observe an IP Service Activator Web Service error in the WebLogic console and/or server log when you submit a test order to OSM, such as: <Error> <com.oracle.cgbu.ipsa.osmipsa.Fault> <BEA-000000> <***IPSA WEBSERVICE F AULT CLEARED*** IPSA WebService Fault: SEVERITY=[ERROR] KEY=[IPSA_FAULT_RECOVERABLE] MESSAGE=[Failed to submitOrder in IpsaDataProxy] CAUSE=[com.oracle.cgbu.ipsa.osmipsa.common.IpsaRecoverableEx ception: Failed to acquire an EomSession: Cannot allocate an EomSession from either ReadOnly OIM pool or ReadWrite OIM pool]> Solution: Confirm that the number of OIM configurations, and the names which are configured in the Web Service configuration in the IP Service Activator Configuration GUI match the IP Service Activator integration managers which are running on your Linux or Solaris server. FailedAuthentication When a Test Order Submitted to OSM Problem: You see an authentication error in the WebLogic console and/or server log when you submit a test order to OSM. The FailedAuthentication is related to the runtime execution of an activation task, such as: Best Practice Guidelines Page 60 of 65
  • 61. <Error log: order id = 1:302, task name=QueryCustomerTask, wsse:FailedAuthentication Failed to assert identity with UsernameToken.> Solution: Use the IP Service Activator Configuration GUI to configure the ‘IPSA Web Service user name,’ such as ipsa_ws_user , and ‘IPSA Web Service password’. In the managed server for IP Service Activator Web service, you can verify that the user is created and belongs to the IPSA_WS_USERS_GROUP by checking in the WebLogic console under Security Realms, my realm, users and groups. Each activation task in the OSM solution, which uses the Web Services protocol to submit activation requests to IP Service Activator, is configured in Design Studio with activation credentials: a map and key. The IP Service Activator Web service user name and password, which you enter in the Configuration GUI, must match the username and password that you enter when prompted, when you run the OSM SDK script ‘credStoreAdmin’ to setup a credential store for OSM access to IP Service Activator Web service credentials using the map and key. See Oracle Communications Order and Service Management System Administrator’s Guide for more information on the OSM SDK scripts EncryptPasswords, and credStoreAdmin. Activation Task Remains in Progress Indefinitely Problem: The runtime execution of an activation task does not complete, and its Process Status remains In Progress. You can see this in the OSM task client. Solution: 1) If you have set up Store and Forward (SAF) configuration in WebLogic, ensure it is set up correctly, and the message resource adaptor for the IP Service Activator managed server is installed. 2) Check that transaction status monitoring is not disabled in IP Service Activator. It is enabled by default. You can verify that it is enabled by committing any transaction in the IP Service Activator User Interface. If the transaction reaches a terminating provisioning status, such as Succeeded, Failed, or TimedOut, and does not stay Pending indefinitely, transaction status monitoring is working. Check the policy server command line in Service_Activator_home/Config/cman.cfg to ensure that the following text IS NOT present: -FullTransactionMonitoring disabled on the Linux or Solaris server where you have IP Service Activator policy server installed. If it is present, remove the text and restart the policy server. The transaction status monitor has default values for transaction monitoring timeout and other parameters. See Oracle Communications IP Service Activator User’s Guide for information about the parameters and default values for the transaction status monitor. Troubleshooting IP Service Activator Interactions Best Practice Guidelines Page 61 of 65
  • 62. Activation Task Generates a Non-Unique Transaction Name Problem: The runtime execution of an activation task generates a non-unique transaction name in IP Service Activator, such as when you submit test orders through OSM which create activation orders for IP Service Activator, then purge OSM cartridges, resetting the OSM order ID, then re- submit the same test orders after redeploying the cartridges. Solution: You can purge transactions in IP Service Activator. From the main menu select Tools - >Options. Select Transactions tab. Set archive limit to 0. Click OK. Commit the change. Then reset archive limit to previous value, and commit. There is a minimum threshold for the number of transactions, beyond which this procedure works to purge the transactions. Empty Request Message When Retry Activation Task Steps: Submit an order for which the OSM process uses an activation task. Activation fails due to data validation error, such as a non-unique object name in IP Service Activator. Correct the data in OSM manual task, and retry the activation task. Problem: OSSJ request message is empty. Activation task does not complete. Solution: Node selected as the response data location must be a multi-instance node; set Multiplicity to unbounded in data schema. Order Submitted to OSM Results in No Corresponding IP Service Activator Transaction Problem: You submit a test order using Design Studio and see no corresponding transaction in IP Service Activator. Solution: 1) Check in OrderManagement task client if the order requires manual enrichment before continuing to process the order. 2) Check the OrderSummary in the console in Design Studio. If the order State is closed.completed in the OrderSummary, and there is an AmendmentSummary showing a MatchedOrderID, the submitted order revised a base order. If you did not intend to revise or cancel a base order, re-submit the order with a unique Order Number. Edit the Order Number in the xml file prior to re-submitting the order. Activation TASK Response: Exception Messages The execution of an activation task at runtime may result in a failure to commit an IP Service Activator transaction resulting in a createOrderByValueException. Specific information concerning the cause of the exception is contained in the activation response structure for the createOrderByValueException. Best Practice Guidelines Page 62 of 65
  • 63. The types of exceptions are described in the Error Handling chapter of IP Service Activator OSS Integration Manager Guide. Activation TASK Response: Reasons for Failed Transaction The execution of an activation task at runtime, which results in an IP Service Activator transaction that is successfully committed, is monitored for successful completion of activation on the underlying network elements by full transaction status monitoring, which is enabled in conjunction with configuration of IP Service Activator Web services. A transaction with a Failed provisioning status results in an orderFailEvent. Specific information concerning the reason for failure is contained in the activation response structure for the orderFailEvent event. Provisioning status values and their meaning are described in IP Service Activator User’s Guide. The Troubleshooting topic in the IP Service Activator User Interface online Help provides details of messages for IP Service Activator fault codes and additional troubleshooting and support information. Debugging IP Service Activator Commands from Execution of an Activation Task If you need to verify the set of IP Service Activator commands, including attribute values, during the runtime execution of activation task, you can set the EOM debug level to TRACE in the IP Service Activator configuration GUI . EOM debug level is a configuration parameter of the IP Service Activator Web services in the configuration GUI. At the TRACE level, OIM commands are logged in the WebLogic admin server log in the same format that they can be entered into the integration manager command line interface. Debugging Createorderbyvaluerequest Sent from Activation Task in OSM to IP Service Activator Web Service If you need to verify whether an activation task in the OSM solution has sent a request with the expected service actions, parameters, and parameter values to IP Service Activator Web services, you can use the OSM log4jAdmin Web page to temporarily configure the logging level for an activation task CreateOrderByValueRequest. Search for loggers that contain the text CreateOrderByValueRequest for the activation task and adjust its logging level. If you do not see the logger that you want, an order needs to be submitted to OSM to initialize the logger. After you do that, you can see the logger and adjust its logging level for debugging of subsequent orders. See Order and Service Management System Administrator’s Guide for more information about setting logging levels temporarily using the log4jAdmin Web page, or permanently by configuring the log4j.xml file. Best Practice Guidelines Page 63 of 65
  • 64. Adopting OSM-IP Service Activator Migration to an OSM-IP Service Activator Integration Prior to the introduction of IP Service Activator Web service, integrations between OSM and IP Service Activator were often implemented using automated tasks that required fine-grained interactions with IP Service Activator using OJDL. Existing OJDL-based interactions may continue to be used while new implementations based on IP Service Activator Web services are introduced. If you have co-existing OJDL-based applications and are using Web services, Oracle recommends that you ensure that the Web service read-only OIM be restricted to using the Web Service. When the CLI or other Java or Python based services use the read-only OIM for write activities, this reduces the effectiveness of the read-only OIM for Web services. Although a migration to newer versions of OSM and IP Service Activator may provide an opportunity to re-examine the overall solution architecture, the activation task may streamline existing workflows by consolidating multiple automated tasks. Because each activation task defines a transaction boundary, candidates for consolidation typically correspond to a set of automated tasks that construct an IP Service Activator transaction and monitor its completion. Best Practice Guidelines Page 64 of 65
  • 65. Best Practice Guidelines Page 65 of 65 Glossary ASAP.........................ASAP; an Oracle Communications product CLI.............................Command Line Interface; unless otherwise specified, the shell-like interface offered by the OIM (integration_manager_cli) CTM ..........................Configuration Template Module; IP Service Activator component to deliver template-based configuration EOM..........................External Object Model; the IP Service Activator data model and actions exposed by the OIM component OIM ...........................OSS Integration Manager; IP Service Activator component to enable automation OSM ..........................Order and Service Management; an Oracle Communications product OTN...........................Oracle Technology Network (http://www.oracle.com/technetwork) QoS............................Quality of Service; a set of services modeled and managed by IP Service Activator to deal with various aspects of service quality rather than connectivity RSDOD .....................Rapid Service Design and Order Delivery; an Oracle Communications comprehensive service fulfillment solution that enables communications service providers to rapidly and efficiently design, launch, and deliver any type of service for any network domain. SDK...........................Software Development Kit VPN...........................Virtual Private Network; a set of services modeled and managed by IP Service Activator; unless otherwise specified, the reference is to Layer-3 BGP/MPLS VPNs (RFC 4364)

×