Integration of Oracle Communications IPSA with OSM

1,092 views
1,013 views

Published on

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

No Downloads
Views
Total views
1,092
On SlideShare
0
From Embeds
0
Number of Embeds
93
Actions
Shares
0
Downloads
0
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Integration of Oracle Communications IPSA with OSM

  1. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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  

×