TIBCO Fulfillment Order Management Web Services. Software Release 2.0 November 2012

Transcription

1 TIBCO Fulfillment Order Management Web Services Software Release 2.0 November 2012

2

3 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Runtime Agent, TIBCO Administrator, TIBCO Enterprise Message Service, and TIBCO BusinessEvents are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. This software may be available on multiple operating systems. However, not all operating system platforms for a specific software version are released at the same time. Please see the readme.txt file for the availability of this software version on a specific operating system platform. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLYADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

4

5 TOC 5 Contents Preface...7 Changes from the Previous Release of this Guide...8 Related Documentation...9 Typographical Conventions...10 Connecting with TIBCO Resources...11 Part I: Architecture...13 Chapter 1 Fulfillment Orchestration Overview...19 Fulfillment Orchestration Components...20 Services and Operations...14 Integration Channels...16 SOAP Over HTTP...16 SOAP Over JMS...16 Part II: Fulfillment Order Management Services...21 Security Header...22 Chapter 2 Fulfillment Management Services...23 Customer Service...23 Inventory Service...26 Offer Service...51 Product Service...62 Subscriber Service...69 Disabling SOAP_HTTP and SOAP_JMS Services...72 Chapter 3 Order Management Services...75 Order Service...75 Purge Order Service...87 Appendix A Common Data Format Specifications ResultFault...93 Customer...94 Notification...97 Order Notification...98

6 6 TOC CustomerHierarchy...99 Plan Notification Subscriber Segment Role Order OrderHeader OrderLine Product Characteristic Execution Plan PlanFragment InventoryItem InventoryItem Order Appendix B Error Codes and Messages Error Code Format Error Codes Customers Inventory Offers OfferValidation Products Subscribers Appendix C Component Classes and Methods OMS Classes and Methods Orchestrator Pre-processors and Rules...141

7 Preface The preface contains information about documentation related to the current document, typographical conventions, and information on how to contact TIBCO support.

8 8 Preface Changes from the Previous Release of this Guide This section itemizes the major changes from the previous release of this guide. Endpoint URLs The AFS is deployed as part of OMS server, the endpoint URLs for SOAP over HTTP have changed. Security All calls to the web service are authenticated using Username token based approach. Logging The logging is done using the AFFLogger APIs. Based on configured appender, the logs are created in the corresponding location.

9 Preface 9 Related Documentation TIBCO Fulfillment Order Management Installation and Configuration Read this manual for instructions on site preparation, installation, and configuration. TIBCO Fulfillment Order Management Administration Read this manual for instructions on administration tasks. TIBCO Fulfillment Order Management Web Services Read this manual for information about Web services. TIBCO Fulfillment Order Management Release Notes Read the release notes for a list of features. This document also contains the list of known issues for this release. TIBCO Fulfillment Order Management User's Guide Read this manual for Fulfillment Order Management features and functionality as well as all the screens. TIBCO Fulfillment Order Management Concepts and Architecture Read this manual for terminology and concepts of TIBCO Fulfillment Order Management.

10 10 Preface Typographical Conventions The following typographical conventions are used in this manual: Table 1: General Typographical Conventions Convention TIBCO_HOME TRA_HOME AF_HOME Use Many TIBCO products are installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Unix systems the default value is $HOME/tibco. TIBCO Runtime Agent installs into a directory inside ENV_HOME. This directory is referenced in documentation as TRA_HOME. The value of TRA_HOME depends on the operating system. For example, on Unix systems the default value is $TIBCO_HOME/tra. TIBCO Fulfillment Order Management installs into a directory inside ENV_HOME. This directory is referenced in documentation as AF_HOME. The value of AF_HOME depends on the operating system. For example, on Unix systems the default value is $TIBCO_HOME/af/2.0. code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process. bold code font Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable disable] italic font Italic font is used in the following ways: To indicate a document title. For example: See TIBCO Fulfillment Order Management Web Services. To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand pathname The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

11 Preface 11 Connecting with TIBCO Resources How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to How to Access All TIBCO Documentation After you join TIBCOmmunity, you can access the documentation for all supported product versions here: How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows: For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a username and password. If you do not have a username, you can request one.

12

13 Part I Architecture TIBCO Fulfillment Order Management is a meta data driven order management and fulfillment system which allows development of fulfillment plans based on meta-data specified in product catalogs. Order fulfillment and service provisioning is no longer a simple single-service or product workflow. The dynamic bundled offerings along with the explosion of devices, applications, real time inventory management and third-party content providers requires a complex order fulfillment system which can adapt to the changes in processes, meta data and inventory. Traditional OSS/BSS 1 approach with their data silos fail to provide a dynamic and agile solution. An end-to-end order management system based on product and service catalogs is a key differentiator of Fulfillment Order Management. TIBCO Fulfillment Order Management is a comprehensive software solution to design, deploy and maintain high-performance scalable enterprise-level business processes for advanced and dynamic order fulfillment. TIBCO Fulfillment Order Management enables companies to quickly introduce new product offerings and in most cases requiring little or no change to fulfillment processes. The product bundles are decomposed into existing products to automatically generate a plan specific to the order. TIBCO Fulfillment Order Management also enables companies to efficiently manage changes to the existing business process to meet a rapidly changing business environment. Product model can be defined following SID 9 guidelines using TIBCO Fulfillment Catalog or any other catalog management system and imported into Fulfillment Order Management. Topics Fulfillment Orchestration Overview Services and Operations Integration Channels 1 Operational/Operations Support System (OSS) Software applications support back-office activities operating a company network, provision and maintain customer services. OSS is traditionally used by network planners, service designers, operations, architects, support, and engineering teams in the service provider. Software applications that support customer-facing activities. Billing, order management, customer relationship management, call center automation, are all Business Support Systems (BSS) applications.

14 14 Architecture Services and Operations The interfaces are organized into services that include related operations. The following interfaces are exposed for any client to invoke the services related to the framework. These services can be invoked over two different channels: SOAP over HTTP and SOAP over JMS. All Web Services support HTTP and JMS. Web Services endpoint URL and SOAP action is based on module name, service name, and operation name. IP>>:<<Port>>/omsServer/api/<<serviceName>>ServiceHTTP. The Service name has the first letter in lowercase once. For example, The naming convention for SOAP action is /omsserver/api/<<servicename>>servicehttp. The naming convention for JMS destination is tibco.aff.<shortnameformodule>.services.<servicenamelowercase>. For example, tibco.aff.om.services.order. The operations specified in the table follow the naming conventions. Table 2: Services and Operations Summary Module Service JMS Destination Operation Offer Configuration and Validation (OCV) Customer tibco.aff.ocv.services.customer GetCustomerHierarchy GetCustomerImage ForCustomer Inventory tibco.aff.ocv.services.inventory AssignInventoryItem AssignInventoryItems GetInventoryItem GetInventoryItems GetUserStatus ReassignInventoryItem ReassignInventoryItems RemoveInventoryItem RemoveInventoryItems RollbackInventoryItem RollbackInventoryItems SetUserStatus UpdateInventoryItem UpdateInventoryItems Offer tibco.aff.ocv.services.offer GetOfferDetails

15 Architecture 15 Module Service JMS Destination Operation GetOffers RemoveOffer SaveOffer ValidateOffer Product tibco.aff.ocv.services.product GetEligibleProducts GetIneligibleSubscribers GetProductInformation GetSegments Subscriber tibco.aff.ocv.services.subscriber CreateSubscriber GetCustomerImage ForSubscriber RemoveSubscriber UpdateSubscriber Order Management (OM) Order tibco.aff.om.services.order CancelOrder GetOrderDetails GetOrders GetOrderExecutionPlan SubmitOrder AmendOrder SyncSubmitOrder WithdrawOrder PerformBulkOrderAction Purge NA purgeorders getpurgestatus OfflineCatalog NA RequestOfflineCatalog For all the web services to work correctly, the data models should be available to Offer Configuration and Validation (OCV) and Automatic Order Plan Development (AOPD) components.

16 16 Architecture Integration Channels To provide maximum flexibility for exposing services to the enterprise, service implementation is separated from the interface. This allows services to be invoked from different transport mechanisms. The following transports are supported: SOAP over HTTP SOAP over JMS SOAP Over HTTP SOAP over HTTP service calls use the standard synchronous web services message format. The integration pattern is as follows: Figure 3: SOAP over HTTP Integration Pattern In the SOAP over HTTP pattern, a service client makes a synchronous service call to the Order Management Services component. The service calls the appropriate operation and performs the required operation before sending a reply back to the calling application. Since AFS is now deployed as part of the OMS Server, the endpoint URLs for SOAP over HTTP have changed. The new endpoint URLs for respective components are as follows: InventoryService : CustomerService : SubscriberService : OfferService : ProductService: Offline Catalog Request: The Offline Catalog request service can be used to send the request to AFI to load the Offline models. SOAP Over JMS SOAP works over a variety of transports and is not restricted to HTTP web services. JMS provides a highly available transport that delivers messages over and above what HTTP provides. SOAP over JMS service calls use the TIBCO proposed specification extension for sending SOAP messages over JMS. TIBCO ActiveMatrix BusinessWorks supports calling SOAP over JMS synchronously using the standard SOAP Request/Reply activity. Non-TIBCO ActiveMatrix BusinessWorks application should be able to call SOAP over JMS services both synchronously and asynchronously using standard JMS messaging techniques that implement the required elements of the specification extension. The synchronous integration pattern is as follows:

17 Architecture 17 Figure 4: SOAP over JMS Synchronous Integration Pattern The asynchronous integration pattern is as follows: Figure 5: SOAP over JMS Asynchronous Integration Pattern In the SOAP over JMS pattern, a service client makes a synchronous or asynchronous service call to the Order Management Services component. The service calls the appropriate operation and performs the required operation before sending a reply back to the calling application. The JMS destinations where the SOAP message should be send is specified in the respective web services WSDL document.

18

19 Chapter 1 Fulfillment Orchestration Overview New technologies and network architectures enable communications service provider (CSP) to create innovative converged products and services offerings which are introduced faster and have shorter life cycles than previous service offerings to address a very changing and competitive market. In view of the rapid pace of change in the technology, the industry is evolving to become a contributor and not remain a mere consumer of technology. In this environment, communications service providers face the challenge of defining, managing and delivering numerous complex products and variations to the market in most effective way to differentiate themselves. TIBCO has concentrated and structured its services around the following points: New product offering are designed and rolled out in a few weeks including implementation in all fulfillment chain. Customer orders are instantly fulfilled and provisioned in the network to maximize customer experience. Customer orders come from large variety of order entries such as customer self-care portals, customer sales representative desk or even network elements detecting service access to leverage fulfillment chain investment and support hardware rationalization. TIBCO providing CSPs with a comprehensive and integrated solution ready for complete end-to-end fulfillment automation. The TIBCO Fulfillment Orchestration Suite defines new product and service offering, associated fulfillment rules and processes, and automate the delivery from order capture down to the service activation in the network. Figure 1: Fulfillment Orchestration Architecture Topics

20 20 Fulfillment Orchestration Components Fulfillment Orchestration Components The TIBCO Fulfillment Orchestration Suite solution is capable of supporting end-to-end order fulfillment with Order Management, Provisioning and Catalog capabilities. The following are the constituents of the TIBCO Fulfillment Orchestration Suite: Fulfillment Catalog: A Catalog function that defines and manages life cycles of commercial and technical offering. Fulfillment Order Management: TIBCO Fulfillment Order Management TIBCO Fulfillment Order Management is a meta data driven order management and fulfillment system which allows development of fulfillment plans based on meta-data specified in product catalogs. Order fulfillment and service provisioning is no longer a simple single-service or product workflow. The dynamic bundled offerings along with the explosion of devices, applications, real time inventory management and third-party content providers requires a complex order fulfillment system which can adapt to the changes in processes, meta data and inventory. Traditional OSS/BSS 2 approach with their data silos fail to provide a dynamic and agile solution. An end-to-end order management system based on product and service catalogs is a key differentiator of Fulfillment Order Management. Fulfillment Provisioning: A Provisioning function that automates the activation of the underlying network services and allocation of all the network resources. The Fulfillment Orchestration Suite has a Provisioning element that implements Service Order Management & Resource Order Management TAM applications and aligns to Service & Resource Activator OSS/J Order Management components and etom Service Configuration & Activation and Resource Provisioning processes and functions. Figure 2: Provisioning in the Orchestration Suite To enable the TIBCO Fulfillment Orchestration Suite to provide a truly unified and cohesive solution suite, different components of the suite have been integrated. For instance, the Suite provides pre-defined inter-connectivity between Fulfillment Provisioning (FP, formerly KPSA) and Fulfillment Order Management/Fulfillment Catalog, catalog concept alignment between Fulfillment Catalog and Fulfillment Provisioning through data synchronization process, and a GUI integration for a similar look-and-feel. See TIBCO Fulfillment Order Management Concepts and Architecture for details. 2 Operational/Operations Support System (OSS) Software applications support back-office activities operating a company network, provision and maintain customer services. OSS is traditionally used by network planners, service designers, operations, architects, support, and engineering teams in the service provider. Software applications that support customer-facing activities. Billing, order management, customer relationship management, call center automation, are all Business Support Systems (BSS) applications.

21 Part II Fulfillment Order Management Services The services are logically divided into the following: Customer Service Inventory Service Offer Service Product Service Subscriber Service You can access these services through SOAP/HTTP channel, or SOAP/JMS channel. Topics Security Header Fulfillment Management Services Order Management Services

22 22 Fulfillment Order Management Services Security Header Fulfillment Order Management supports both HTTP and JMS as transport protocols for invoking SOAP based Web services. AFS supports various Web services, and each Web service request requires the WS-Security UserName Token mechanism. It uses TIBCO Administrator credentials in a standards-compliant manner. OMS By default, OMS provides a set of user id and password for the operations on OMS through Web service request. Order services in OMS can be secured by enabling username token-based security. OMS supports the WS-Security UserName Token mechanism, which allows for the sending and receiving of user credentials in a standards-compliant manner. For more details, refer to TIBCO Fulfillment Order Management Administration Guide.

23 Chapter 2 Fulfillment Management Services Fulfillment Management Services are the set of services, which are related to entities associated with Order. These entities can be customer, subscriber, offer, product, or inventory. These services allows you to get information about these entities and perform other operations. The location of all the WebService WSDLs 3 is $AF_HOME/schemas/wsdl. Topics Customer Service Inventory Service Offer Service Product Service Subscriber Service Disabling SOAP_HTTP and SOAP_JMS Services Customer Service This service contains operations that retrieve customer information from the order management system. Get Customer Hierarchy This operation retrieves the hierarchy for customers, subscribers, and subscribed products. It either retrieves the hierarchy for all customers and subscribers, or only for a specific customer and subscriber. This operation only returns the customers and subscribers configured in the cache, and then only a limited subset of information about each. To get the full snapshot of a customer, invoke GetCustomerImageForCustomer. To view the full snapshot of a subscriber, invoke GetCustomerImageForSubscriber. To view the full snapshot of a subscribed product, invoke GetInventoryItem. As the customer or subscriber information does not exist in the cache, use the GetInventoryItems operation to retrieve the subscribed products for customers or subscribers not stored in the cache. This interface supports the top five levels of customers: 3 WSDL or Web Services Language is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate.

24 24 Figure 6: Customer Hierarchy Returned by GetCustomerHierarchy Entities below Level 4 Customers are not returned. The request message format is: The valid request criteria is one of the following combinations: CustomerID and IncludeProducts - Returns the hierarchy for a single customer, including all subsidiary customers and subscribers that are stored in the cache. SubscriberID and IncludeProducts - Returns a single subscriber stored in the cache. Table 3: Get Customer Hierarchy Request Data Model CustomerID SubscriberID IncludeProducts The reply message format is: (Choice, Optional) (Choice, Optional) Boolean Default = true The ID of the customer to retrieve the hierarchy. The ID of the subscriber to retrieve the hierarchy. Flag to indicate if subscriber products should also be returned. If set to true, then all subscriber products are returned in the hierarchy. If set to false, then no products are included.

25 25 The reply format depends on what criteria is specified in the request: CustomerID - Customer is returned if stored in cache. SubscriberID - Subscriber is returned if stored in cache. Neither CustomerID nor SubscriberID - CustomerHierarchy is returned for all subscribers and customers stored in cache. Table 4: Get Customer Hierarchy Reply Data Model Customer Subscriber CustomerHierarchy Customer (Choice) Subscriber (Choice) CustomerHierarchy (Choice) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). CustomerHierarchy/Customer data structure. Data model for CustomerHierarchy/Customer is defined in XSD (refer section Common Data Format Specifications on page 91). If the Customer was not found for the given CustomerID this element is omitted. CustomerHierarchy/Subscriber data structure. Data model for CustomerHierarchy/Subscriber is defined in XSD (refer section Common Data Format Specifications on page 91). If the Subscriber was not found for the given SubscriberID this element is omitted. CustomerHierarchy data structure. Data model for CustomerHierarchy is defined in XSD (refer section Common Data Format Specifications on page 91). Get Customer Image For Customer This operation retrieves the full snapshot of currently configured customer image for a given customer ID and returns to the calling application. The request message format is:

26 26 Table 5: Get Customer Image For Customer Request Data Model CustomerID The ID of the customer to retrieve the full details. The reply message format is: Table 6: Get Customer Image For Customer Reply Data Model Customer Customer Customer data structure. Data model for Customer is defined in XSD (refer section Common Data Format Specifications on page 91). If the customer was not found for the given CustomerID this element is omitted. Example Inventory Service Inventory Service exposes operations related to inventory in order management. The inventory is associated with order and can be at customer or subscriber level. The operations can be assigning inventory, updating inventory, removing inventory and so on. Assign Inventory Item This operation assigns a new inventory item for a specific customer or subscriber. The request message format is:

27 27 Table 7: Assign Inventory Item Request Data Model CustomerID/SubscriberID (either one of them is provided) ParentCustomerID ProductID Status (Optional, Choice) CustomerID: The ID of the customer to assign the inventory. SubscriberID: The ID of the subscriber to assign the inventory. The ID of the parent customer that the subscriber is assigned. Product unique identifier. Initial status to assign to the inventory item. Valid status are: DRAFT ACTIVE WITHDRAWN

28 28 StartDate Order Order/OrderID Order/OrderLineNumber Order/OrderLineAction Order/OrderDate Order/Comments Order/CurrentOwnerCustomerID Order/CurrentOwnerSubscriberID UDFs UDFs/UDF UDFs/UDF/Name UDFs/UDF/Value DateTime Type DateTime (Optional, Choice) (Optional, Choice) Type Type (*) The planned start date that the product will go to ACTIVE status. This may be a provisional start date at this point and can be updated later using UpdateInventoryItem operation. Order type Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation. User Defined Field (UDF) type User defined fields associated with the product User defined field name. User defined field value. The reply message format is:

29 29 Table 8: Assign Inventory Item Reply Data Model InventoryID Data model for is defined in XSD 4 (refer section Common Data Format Specifications on page 91). Inventory identifier for the newly created inventory item. If the item is not created successfully, this is omitted. Assign Inventory Items This operation assigns multiple new inventory items to the given customer or subscriber. This is a bulk operation version of Assign Inventory Item. The request message format is: Table 9: Assign Inventory Items Request Data Model Item Type (+) Inventory item to assign. 4 XML Schema Definition (XSD) is also referred to as XML schema language. It describes the structure of an XML document.

30 30 CustomerID/SubscriberID Item/ParentCustomerID Item/ProductID Item/Status Item/StartDate Item/Order Item/Order/OrderID Item/Order/OrderLineNumber Item/Order/OrderLineAction Item/Order/OrderDate Item/Order/Comments Item/Order/CurrentOwnerCustomerID Item/Order/CurrentOwnerSubscriberID (Choice) (Optional, Choice) DateTime Type DateTime (Optional, Choice) (Optional, Choice) CustomerID: The ID of the customer to assign the inventory. SubscriberID: The ID of the subscriber to assign the inventory. The ID of the parent customer that the subscriber is assigned. Product unique identifier. Initial status to assign to the inventory item. The valid statuses are: DRAFT ACTIVE WITHDRAWN The planned start date that the product will go to ACTIVE status. This may be a provisional start date at this point and can be updated later using UpdateInventoryItem operation. Order type Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation.

31 31 Item/UDFs Item/UDFs/UDF Item/UDFs/UDF/Name Item/UDFs/UDF/Value Type Type (*) UDF type User defined fields associated with the product. User defined field name. User defined field value. The reply message format is: Table 10: Assign Inventory Items Reply Data Model Item Item/ Item/InventoryID Type (+) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory item assigned. Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory identifier for the newly created inventory item. If the item is not created successfully, this is omitted. Get Inventory Item This operation retrieves a specific inventory item. The request message format is:

32 32 Table 11: Get Inventory Item Request Data Model InventoryID Inventory ID to retrieve. The reply message format is: Table 12: Get Inventory Item Reply Data Model InventoryItem InventoryItem Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory Item data structure. Data model for Inventory Item is defined in XSD (refer section Common Data Format Specifications on page 91). Get Inventory Items This operation retrieves the list of inventory items for an input criteria. The request message format is:

33 33 The request criteria filters the list of inventory items returned and criteria are additive using the AND operator. None of the request criteria is required. It is strongly recommended to not send a request without applying the filtering criteria, otherwise a large result set may be generated and returned. The results are sorted by start date in a descending order. Table 13: Get Inventory Items Request Data Model CustomerID GetSubscribersItems SubscriberID ProductID ProductType (Optional, Choice) Boolean (Optional, Choice) (Optional, Choice) Customer ID to retrieve inventory items. Flag to indicate if the call should return the list of items associated with dependent subscribers for this customer. Subscriber ID to retrieve inventory items. Product ID to retrieve inventory items. Product type for inventory items to retrieve. This field supports wildcard searches using * or % at

34 34 ProductSubType Product ItemUDF ItemUDF/Name ItemUDF/Value Count Pagination Pagination/StartRecord Pagination/EndRecord ItemSummary The reply message format is: Type (*) Long (Optional, Choice) Type (Optional, Choice) Long Long Boolean the start or end of the string. This is a case-insensitive search parameter. Product sub-type for inventory items to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. Product description for inventory items to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. List of item UDFs to retrieve inventory items. Name of the UDF to search Value of the UDF to search. This is a case-insensitive search parameter. The maximum number of items to return. Items are always sorted by ascending Status and ProductType. If a large number of items are found that match the criteria, then only items up to the Count are returned. Pagination element. Items are always sorted by ascending Status and ProductType. Start record index to return items. This index is inclusive. End record index to return items. This index is inclusive. Flag to indicate if the operation should return item information without UDFs. If this element is set to true, then UDFs are omitted. Otherwise the full item is returned.

35 35 Table 14: Get Inventory Items Reply Data Model InventoryItems InventoryItems/InventoryItem Pagination Pagination/StartRecord Pagination/EndRecord Pagination/TotalRecords Type InventoryItem (*) Type Long Long Long Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). List of inventory items. If inventory items are not found, this element is omitted. Inventory Item data structure. Data model for Inventory item is defined in XSD (refer section Common Data Format Specifications on page 91). Pagination details. This element is included only if pagination is included in the request. Start record index of returned items. This index is inclusive. End record index of returned items. This index is inclusive. Total count of item records that matched the input criteria. This value is used to compose subsequent pagination calls. Get User Status This operation retrieves a list of user status from the inventory for the given input criteria. The request message format is: The following conditions determine the result set returned by the Get User Status operation:

36 36 Status of all customers for which CustomerID is passed in the request is always returned. If a single CustomerID is passed in the request, the operation returns a list of all the subscribers of this particular customer and their status from inventory. If a single customerid and a list of subscriberids are passed in the request, the operation returns the status for the subset of subscribers specified by the supplied subscriberids for this particular customer from inventory. If no CustomerID or more than one CustomerID and a list of subscriberids are passed in the request, the operation returns status for all subscribers specified in the list without taking into consideration their relationship to the customers passed in the request. Table 15: Get User Status Request Data Model CustomerID SubscriberID (*) (*) (Optional, Choice) Customer ID to retrieve user status. Subscriber ID to retrieve user status. The reply message format is: Table 16: Get User Status Reply Data Model Customer Customer/CustomerID Customer/UserStatus Subscriber Type (*) Type (*) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Customer user data structure. Customer ID for user status. User status for the customer. Subscriber user data structure.

37 37 Subscriber/SubscriberID Subscriber/ParentCustomerID Subscriber/UserStatus Subscriber ID for user status. Parent customer ID for the subscriber, if one exists. User status for the subscriber. The valid values are: LOCKED UNLOCKED Reassign Inventory Item This operation reassigns an existing assigned inventory item from a customer or subscriber to another customer or subscriber. The request message format is: Table 17: Reassign Inventory Item Request Data Model InventoryID The ID of the inventory item to reassign.

38 38 EnableRollback Boolean Flag to indicate a rollback snapshot should be made for the current update. This flag is not being used in this release. CustomerID SubscriberID ParentCustomerID Status Order Order/OrderID Order/OrderLineNumber Order/OrderLineAction Order/OrderDate Order/Comments Order/CurrentOwnerCustomerID Order/CurrentOwnerSubscriberID The reply message format is: (Mandatory, Choice) (Mandatory, Choice) (Optional, Choice) Type DateTime (Optional, Choice) (Optional, Choice) The ID of the customer to reassign the inventory item. The ID of the subscriber to reassign the inventory item. The ID of the parent customer that the subscriber is reassigned. Inventory item status to be set. The valid statuses are: DRAFT ACTIVE WITHDRAWN Order type to add to the order history. Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation.

39 39 Table 18: Reassign Inventory Item Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Reassign Inventory Items This operation reassigns existing assigned inventory items from a customer or subscriber to another customer or subscriber. The request message format is: Table 19: Reassign Inventory Items Request Data Model Item Item/InventoryID Type (+) Inventory item reassigned. The ID of the inventory item to be reassigned.

40 40 Item/EnableRollback Boolean Flag to indicate a rollback snapshot to be made for the current update. This flag is not being used in this release. Item/CustomerID Item/SubscriberID Item/ParentCustomerID Item/Status Item/Order Item/Order/OrderID Item/Order/OrderLineNumber Item/Order/OrderLineAction Item/Order/OrderDate Item/Order/Comments Item/Order/CurrentOwnerCustomerID Item/Order/CurrentOwnerSubscriberID (Mandatory, Choice) (Mandatory, Choice) (Optional, Choice) Type DateTime (Optional, Choice) (Optional, Choice) The ID of the customer to reassign the inventory item. The ID of the subscriber to reassign the inventory item. The ID of the parent customer that the subscriber item is reassigned to. Inventory item status to be set. The valid statuses are: DRAFT ACTIVE WITHDRAWN Order type to add to the order history. Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation. The reply message format is:

41 41 Table 20: Reassign Inventory Items Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Item Type (+) Inventory item reassigned Item/ Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Item/InventoryId InventoryId that was reassigned Remove Inventory Item This operation removes an inventory item from a customer or subscriber. The request message format is: Table 21: Remove Inventory Item Request Data Model InventoryID The ID of the inventory item to be removed. The reply message format is:

42 42 Table 22: Remove Inventory Item Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Remove Inventory Items This operation removes inventory items from a customer or subscriber. This is a bulk interface version of Remove Inventory Item. The request message format is: Table 23: Remove Inventory Items Request Data Model InventoryID The reply message format is: (+) The ID of the inventory item to be removed. Table 24: Remove Inventory Items Reply Data Model Data model for is defined in XSD (refer section Common Data Format Specifications on page 91).

43 43 Item Item/ Item/InventoryId Type (+) Inventory item removed Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). InventoryId that was removed. Rollback Inventory Item This operation rolls back the previous update to an inventory item. The request message format is: Table 25: Rollback Inventory Item Request Data Model InventoryID The ID of the inventory item to rollback. The reply message format is: Table 26: Rollback Inventory Item Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Rollback Inventory Items This operation rolls back the previous update to inventory items. This is a bulk interface version of Rollback Inventory Item. The request message format is:

44 44 Table 27: Rollback Inventory Items Request Data Model InventoryID The reply message format is: (+) The ID of the inventory item to rollback. Table 28: Rollback Inventory Items Reply Data Model Item Item/ Item/InventoryID Type (*) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory item rolled back Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory item ID that was rolled back. Set User Status This operation sets the status of the specified users in the inventory. If the users are not present in the hierarchy, an appropriate error code is returned. All users have the same status as specified in the request. The request message format is:

45 45 Table 29: Set User Status Request Data Model CustomerID Subscriber Subscriber/SubscriberID Subscriber/ParentCustomerID UserStatus (*) Type (*) Customer ID of the user to set the status. Subscriber type Subscriber ID of the user to set the status. This is required for both non-corporate and corporate subscribers. Parent Customer ID of the subscriber user to set the status. This is required for corporate subscribers. The status to assign to the users. The valid values are: LOCKED UNLOCKED The reply message format is: Table 30: Set User Status Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Update Inventory Item This operation updates the details of an inventory item. The update operation allows updating the following parameters. The effect on each parameter is as follows: Parameter Status StartDate EndDate Order UDF Inventory item status is updated to the specified value. Inventory item start date is updated to the specified value. Inventory item end date is updated to the specified value. Specified order is added to the order history for the inventory item. Existing order history entries are not changed. The set of UDFs is replaced. The effect of this is:

46 46 Parameter New UDF entries are added. Changed UDF entries are modified UDF entries currently present in the inventory item but not in the input UDF list are removed. If the UDFs node is present with no UDF elements, all UDFs are removed. The request message format is: Table 31: Update Inventory Item Request Data Model InventoryID EnableRollback Status Boolean The ID of the inventory item to update. Flag to indicate a rollback snapshot should be made for the current update. Inventory item status to be set. The valid statuses are: DRAFT ACTIVE WITHDRAWN

47 47 StartDate EndDate Order Order/OrderID Order/OrderLineNumber Order/OrderLineAction Order/OrderDate Order/Comments Order/CurrentOwnerCustomerID Order/CurrentOwnerSubscriberID UDFs UDFs/UDF UDFs/UDF/Name UDFs/UDF/Value DateTime DateTime Type DateTime (Optional, Choice) (Optional, Choice) Type Type (*) The date that the product went to ACTIVE status. The date that the product went to WITHDRAWN status. Order type to add to the order history. Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation. UDF type. Note that if this element is present with no UDF nodes beneath it, then all UDFs are removed from the cache. User defined fields associated with the product. User defined field name. User defined field value. The reply message format is:

48 48 Table 32: Update Inventory Item Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Update Inventory Items This operation updates the details of inventory items. This is a bulk interface version of Update Inventory Item. Refer to the Update Inventory Item operation for additional information about update parameters. The request message format is: Table 33: Update Inventory Items Request Data Model Item Item/InventoryID Item/EnableRollback Item/Status Type (+) Boolean Inventory item updated. The ID of the inventory item to update. Flag to indicate a rollback snapshot should be made for the item to update. Inventory item status to be set.

49 49 Item/StartDate Item/EndDate Item/Order Item/Order/OrderID Item/Order/OrderLineNumber Item/Order/OrderLineAction Item/Order/OrderDate Item/Order/Comments Item/Order/CurrentOwnerCustomerID Item/Order/CurrentOwnerSubscriberID Item/UDFs Item/UDFs/UDF Item/UDFs/UDF/Name Item/UDFs/UDF/Value DateTime DateTime Type DateTime (Optional, Choice) (Optional, Choice) Type Type (*) The valid status are: DRAFT ACTIVE WITHDRAWN The date that the product went to ACTIVE status. The date that the product went to WITHDRAWN status. Order type to add to the order history. Order identifier the product is ordered on. Order line number the product is ordered on. Order line action the product is ordered with. Order date and time the product is ordered. Comments for this order. Current customer owner of this item. This does not need to be populated on this operation. Current subscriber owner of this item. This does not need to be populated on this operation. UDF type. Note that if this element is present with no UDF nodes beneath it, then all UDFs are removed from the cache. User defined fields associated with the product. User defined field name. User defined field value.

50 50 The following tables describes the rules for updating UDFs in the Inventory: GLB_StoreInpCharUDFsOnly ProductInput Characteristics PERSIST_VALUE (defined in the product charactertistic) GLB_IgnoreUDF PersistFlag UDF persisted TRUE (default value) TRUE FALSE FALSE (default) FALSE TRUE (default value) TRUE FALSE TRUE TRUE TRUE (default value) TRUE TRUE x TRUE FALSE x x x TRUE TRUE x x x FALSE Where: x : Any value. 1. With the default values of the global variables GLB_StoreInpCharUDFsOnly and GLB_IgnoreUDFPersistFlag, the UDFs can be persisted only if the PERSIST flag in the product model is true. 2. To persist the UDFs associated with the inventory, irrespective of the product model, set the GLB_StoreInpCharUDFsOnly to false. The reply message format is: Table 34: Update Inventory Items Reply Data Model Item Item/ Type (+) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Inventory item updated. Data model for is defined in XSD (refer section Common Data Format Specifications on page 91).

51 51 Item/InventoryID Inventory item ID that was updated. Offer Service This service contains operations for saving and validating offers. Get Offer Details This operation retrieves the offer details for an order reference and returns to the calling application. This is only for offers saved using the Save Offer function. The submitted orders are not returned. The request message format is: Table 35: Get Offer Details Request Data Model OrderRef Version The reply message format is: Long The order reference ID. This must be an exact match. The offer version to retrieve. If this is omitted, the offer with the highest version number for the OrderRef is returned. Table 36: Get Offer Details Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Order Order Order data structure. Data model for Order is defined in XSD (refer section Common Data

52 52 Format Specifications on page 91). If the offer is not found, this element is omitted. Example Get Offers This operation retrieves the offers for the specified criteria and returns to the calling application. This is only for offers saved using the Save Offer function. The submitted orders are not returned. The request message format is: The request criteria is used to filter the list of offers returned and criteria using the AND operator. The request criteria is not required, but it is strongly recommended not to send it in a request without applying the filter criteria. Otherwise, a large resultset may be returned. The returned offers are sorted by submission date in a descending order.

53 53 Table 37: Get Offers Request Data Model OrderRef LatestVersion Version CustomerID SubscriberID DateRange DateRange/StartDate DateRange/EndDate OrderStatus HeaderUDF Boolean (Choice, Optional) Long (Choice, Optional) Type Date Date Type (*) The order reference to retrieve orders. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. Flag to indicate if the operation should only return the latest version of each offer. If this field is not present, it is assumed to be false. The version number for the offer to retrieve. The ID for the customer to retrieve offers. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. The ID of the subscriber to retrieve offers. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. Specifying SubscriberID returns all offers that include the subscriber, including multiple-subscriber offers. Order date range type. The earliest order date to return offers. This date is inclusive. This is based on the Order Submission Date on the original offer. Order Submission Dates before this date is excluded. The latest date to return offers. This date is inclusive. This is based on the Order Submission Date on the original offer. Order Submission Dates after this date is excluded. The order status to return offers. This is a case-insensitive search parameter. List of order header UDFs to return offers.

54 54 HeaderUDF/Name HeaderUDF/Value OrderLineUDF OrderLineUDF/Name OrderLineUDF/Value Count Pagination Pagination/StartRecord Pagination/EndRecord OrderSummary The reply message format is: Type (*) Long (Optional, Choice) Type (Optional, Choice) Long Long Boolean Name of the UDF to search Value of the UDF to search. This is a case-insensitive search parameter. List of order line UDFs to return offers. If any order line contains a UDF match then the entire offer is returned. Name of the UDF to search Value of the UDF to search. This is a case-insensitive search parameter. The maximum number of offers to return. Offers are always sorted by descending Order Date, Order Ref, and Version. If a large number of orders are found that match other criteria, then only the orders up to the Count is returned. Pagination element. Offers are always sorted by descending Order Date, Order Ref, and Version. Start record index to return offers. This index is inclusive. End record index to return offers. This index is inclusive. Flag to indicate if the operation should only return order header information. If this element is set to true, only order headers are returned. Otherwise the full offer is returned.

55 55 Table 38: Get Offers Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Offers Type List of Offers. If no offers are found this element is omitted. Offers/Order Order (*) Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Pagination Type Pagination details. This element is included only if pagination was included in the request. Pagination/StartRecord Long Start record index of returned offers. This index is inclusive. Pagination/EndRecord Long End record index of returned offers. This index is inclusive. Pagination/TotalRecords Long Total count of offer records that matched the input criteria. This value is used to compose subsequent pagination calls. Remove Offer This operation removes the offer details from the offer configuration and validation engine for the given order reference and version. OrderRef must be specified. If details are not provided then the latest version of the offer is removed. If a Version is specified, then the particular version is removed. If the AllVersions flag is set to true, then all versions of the offer are removed. The request message format is:

56 56 Table 39: Remove Offer Request Data Model OrderRef Version AllVersions Long Boolean The order reference ID. The specific version to be removed. Flag to indicate that all versions of the offer should be removed. The reply message format is: Table 40: Remove Offer Reply Data Model Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Save Offer This operation accepts an offer and stores it in the offer configuration and validation engine for retrieval. Do not specify the OrderID in the input Order document as it is ignored. If OrderRef is not specified, a value is generated and returned to the calling application. If the offer could not be saved, the OrderRef is not returned. The order is not validated. If OrderRef is specified and an offer already exists in the cache, that offer is updated and version number is increased to the next higher version. Otherwise, a new offer is created in the cache. The request message format is:

57 57 Table 41: Save Offer Request Data Model Order The reply message format is: Order Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Table 42: Save Offer Reply Data Model OrderRef Version Long Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Order reference number. If the offer could not be saved then this element is omitted. Version of the saved offer. If the offer could not be saved then this element is omitted. Validate Offer This operation accepts an offer for validation and returns either a pass or fail. If the validation fails, a list of error messages are returned. Validation takes the form of rules configured in the offer configuration and validation engine. These rules evaluate all aspects of the offer and return all invalid items rather than stopping on the first validation failure. Validations are categorized into Warning or Error. A warning is a validation failure but not serious enough to reject an offer. An error is a validation failure that is serious enough to reject an offer. The Validation Pass parameter is based on the resultant validation message types. The rules are as follows: No Messages Warnings Only Warnings and Errors Errors Only Validation Pass = true Validation Pass = true Validation Pass = false The request message format is:

58 58 Table 43: Validate Offer Request Data Model Order The reply message format is: Order Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Table 44: Validate Offer Reply Data Model ValidationPass Message Message/LineNumber Boolean Type (*) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Returns true for a valid order, or false for an invalid order. This returns false if there are any error messages returned. If warning messages are returned or no messages are returned, this returns true. Validation messages for the order. The validation service validates all elements in the order and returns multiple validation messages. Line number in the order that the validation message relates to. If this is omitted then the message is general for the entire order.

59 59 Message/Type Message/Code Message/ Validation message type. The valid values are: WARNING ERROR Unique validation message code. Validation message description and possibly remedial action required. Get Offer Price This public interface is provided by Offering Management to allow pricing of a particular Offer based on the configuration in the Product Catalog. The request message format is: Figure 7: Get Offer Price Request Field Type Cardinality OrderRef Mandatory Unique identifier for the Offer to price. Version Long Optional Version of the Offer to price. If this is omitted then the latest version is priced. Order Order Mandatory Order data structure. Data model for Order is defined in XSD (refer Order Order section Common Data Format Specifications). BusinessTransactionID Optional Transaction ID. The reply message format is:

60 60 Figure 8: Get Offer Price Reply Field Type Cardinality BusinessTransactionID Optional Long Mandatory OrderLines OrderLine Optional TotalPrice Total Price Optional OverallPrice Overall Price Optional Product prices are stored in the Product Catalog, and assigned to individual Products. When applied to an Offer, these Product prices are computed on an order line basis by using the Product ID for that order line. Each order line has a computed summary price and an overall summary price for the Offer, and total price for the Offer is computed by summing the individual order line prices. Various price entities and types are supported: Entity Customer Price Subscriber Price A price that is charged to a Customer-level entity A price that is charged to a Subscriber-level entity Price Type One Time Price Recurring Price A price that is charged only once A price that is charged multiple times over a defined term with a given periodic frequency. For example, Monthly, Daily, Yearly, etc. Price types and price entities combine together to create the following pricing matrix: Price Entities Customer Subscriber Price Types One Time Price Yes - Single Yes - Single Recurring Price Yes - Multiple Yes - Multiple

61 61 In addition to the catalog prices, the pricing rules support the following order line price types that apply only to One Time prices: Order Line Price Type Supplement Price Override Price A price that is added to the one-time price for the given order line A price that is used instead of the one-time price for the given order line Computing the order line catalog price is based on the pricing matrix and the following rules: Price Matrix Node Customer One Time Price Subscriber One Time Price Customer Recurring Price Subscriber Recurring Price Computation Sum of all prices for the order line Product ID where: Price Type is One Time Order has a CustomerID and Order Line doesn't have a SubscriberID Sum of all prices for the order line Product ID where: Price Type is One Time Order has a SubscriberID or Order Line has a SubscriberID Sum of all prices for the order line Product ID grouped by Price Period where: Price Type is Recurring Order has a CustomerID and Order Line doesn't have a SubscriberID Sum of all prices for the order line Product ID grouped by Price Period where: Price Type is Recurring Order has a SubscriberID or Order Line has a SubscriberID The recurring prices are always grouped by Price Period. This is required so that only prices of the same price period are summed together. Therefore only Monthly Price Period prices are summed with other Monthly Price Period prices, and not with Yearly or Daily Price Period prices. Prices can also be configured by price band. Each Price Entity on the offer may have its own price band. Price bands may be used for One Time or Recurring price types. The price band for a particular Price Entity is determined by assigning a CompatibleSegment Price Band segment to a product that Price Entity has ordered. If multiple products for that Price Entity have CompatibleSegment Price Band relationships then only the first one found is used. This price band is then used to choose the correct price for other products for that Price Entity on the offer that are configured using price bands. Price banded products have multiple prices associated with it, but not all prices are used. Each product has a ProductPricedBy relationship to the price. Each price in turn has a PriceRequiresSegment relationship to the relevant Price Band segment. There may also be a default price band associated with the product that does not have a PriceRequiresSegment relationship to any segment. If a price with a matching price band for the Price Entity is found then that price will be used in the computation. If no matching price band was found, then the default price is used in the computation instead. If no default price is set and no matching price band is found, then no price is included in the computation. The over all Offer price is computed by summing all the prices within the same Price Matrix Node over all the order lines, thereby giving an overall price total for an Offer. The following table shows the Overall Offer Price Computation Rules:

62 62 Price Matrix Node Customer One Time Price Subscriber One Time Price Customer Recurring Price Subscriber Recurring Price Computation Sum of all order line prices of type Customer One Time Price Sum of all order line prices of type Subscriber One Time Price grouped by Subscriber ID Sum of all order line prices of type Customer Recurring Price grouped by Price Period Sum of all order line prices of type Subscriber Recurring Price grouped by Subscriber ID and Price Period The Subscriber prices are always grouped by Subscriber ID. This is required so that only prices that are for the same Subscriber are summed together. The total Offer price is computed by summing all the one-time prices and all the recurring prices grouped by price period alone. This differs from the overall Offer price in that it doesn't distinguish between Customer and Subscriber, or within individual Subscribers. Product Service This service contains operations that retrieve information about products. Get Eligible Products This operation retrieves a list of products by applying eligibility rules to the product catalogue and returns details to the calling application. The list of products returned is determined by the filtering criteria passed into the operation. These criteria are additive. The product information returned is limited. To get full product information, invoke the Get Product Information operation for each product passing the ProductID returned from this call. For a product list associated with a particular customer ID, the product list is filtered based on the request for the criteria such as Segment, productname, productcharacteristic, etc. The product list is then returned. If a customer associated with any CustomerID is not found, or if a customer is found but no products are associated with that customer, then: The Segment list is used to search for a list of products matching the segments on the following criteria for a product to match. The product must have CompatibleSegment relationships to ALL the segments specified on a request. If a product has additional CompatibleSegment relationships to segments not in the request, then the list is returned. If a product is missing any CompatibleSegment relationships to segments in the request, then the list is not returned. The list is filtered by the criteria (productname, productcharacteristic, etc) on request. The filtered list is returned. The request message format is:

63 63 Table 45: Get Eligible Products Request Data Model SubscriberID ParentCustomerID RoleID CustomerID (*) The ID of the subscriber to retrieve eligible products. The subscriber must exist within the cache. The ID of the parent customer for a subscriber to retrieve eligible products. The customer must exist within the cache. The ID of the role that a subscriber has within the parent customer organization. The ID of the customer to retrieve eligible products. The customer must exist within the cache.

64 64 Segment Segment/Name Segment/Type ParentProductID ProductName ProductType Type (*) List of segments used to filter the list of returned eligible products. Only products that match all elements in the list of segments is returned. Name of the segment Type of the segment. Parent product ID for the products to retrieve. Products that are children of the specified product using ProductComprisedOf relationship is returned. Product name for the products to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. Product type for the products to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. ProductSubType Product sub type for the products to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. Product Product description for the products to retrieve. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. ProductCharacteristic Type (*) List of characteristics used to filter the list of returned eligible products. Only products that have the specified characteristics is returned.

65 65 ProductCharacteristic/Name Characteristic name. Valid for Instance, Feature, or Input characteristics. ProductCharacteristic/Value Characteristic discrete value. Valid only for Instance characteristics. OrderDate DateTime (YYYY-MM-DDThh:mm:ss) Order date to use for filtering the returned list of products. Only products where the order date lies between the start date and end date is returned. Status Product status for products to retrieve. Count Long (Optional, Choice) The maximum number of products to return. Products are always sorted by ascending ProductID. If a large number of products are found that match the criteria then only the products up to the Count are returned. Pagination Type (Optional, Choice) Pagination element. Products are always sorted by ascending ProductID. Pagination/StartRecord Long Start record index to return products. This index is inclusive. Pagination/EndRecord Long End record index to return products. This index is inclusive. The reply message format is:

66 66 Table 46: Get Eligible Products Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Products Type List of products that a customer is eligible to order. If no products are found this element is omitted. Products/Product Product (*) Product model data structure. Data model for Product is defined in XSD (refer section Common Data Format Specifications on page 91). Pagination Type Pagination details. This element is included only if pagination was included in the request. Pagination/StartRecord Long Start record index of returned products. This index is inclusive. Pagination/EndRecord Long End record index of returned products. This index is inclusive. Pagination/TotalRecords Long Total count of product records that matched the input criteria. This value is used to compose subsequent pagination calls. Get Ineligible Subscribers This operation returns a list of ineligible subscribers for the specified input criteria. A subscriber is ineligible if the specified ProductID is configured to have ConcurrentOrder set to false and the subscriber user is locked in the inventory. The request message format is:

67 67 Table 47: Get Ineligible Subscribers Request Data Model ParentCustomerID ProductID Customer ID for the parent customer for the subscribers to return. The ID of the product to check for ConcurrentOrder flag. The reply message format is: Table 48: Get Ineligible Subscribers Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). IneligibleSubscriberID (*) Subscriber ID for subscribers that are ineligible to order the specified product. Get Product Information This operation retrieves the details for a given product and returns to the calling application. The request message format is: Table 49: Get Product Information Request Data Model ProductID The reply message format is: (+) The ID of the product. This must be an exact match.

68 68 Table 50: Get Product Information Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). ProductInformation Type (*) Information on the product. If the product is not found this element is omitted. ProductInformation/Product Product Product data structure. Data model for product is defined in XSD (refer section Common Data Format Specifications on page 91). ProductInformation/Characteristics Type List of characteristics for the product ProductInformation/Characteristics/Characteristic Characteristic (*) Characteristic data structure. Data model for characteristic is defined in XSD (refer section Common Data Format Specifications on page 91). Get Segments This operation retrieves the list of segments stored in the product cache. The request message format is: Table 51: Get Segments Request Data Model SegmentType The type of segment to filter the result set. The reply message format is:

69 69 Table 52: Get Segments Reply Data Model Example Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Segments Type List of segments. Segments/Segment Segment (*) Segment data structure. Data model for Segment is defined in XSD (refer section Common Data Format Specifications on page 91). If no segments were found for the given SegmentType this element is omitted. Subscriber Service This service contains operations that create, update, remove, and retrieve subscribers from the order management system. There is also an operation that validates subscriber orders. Create Subscriber This operation creates a subscriber in the order management system. The request message format is: Table 53: Create Subscriber Request Data Model Subscriber Subscriber Subscriber data structure. Data model for Subscriber is defined in XSD (refer section Common Data Format Specifications on page 91). In this structure, the following optional fields are ignored if populated:

70 70 Subscriber ID is returned in the reply. The reply message format is: Table 54: Create Subscriber Reply Data Model SubscriberID Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Unique identifier for the newly created subscriber. If the operation call fails this element is omitted. Get Customer Image For Subscriber This operation retrieves the configured customer image for a given subscriber ID and returns to the calling application. In addition to the subscriber, the list of currently subscribed products is also returned. This operation only returns subscribers stored in the cache. To retrieve inventory for subscribers not stored in the cache, use the GetInventoryItems operation. The request message format is: Table 55: Get Customer Image For Subscriber Request Data Model SubscriberID The ID of the subscriber to retrieve. The reply message format is:

71 71 Table 56: Get Customer Image For Subscriber Reply Data Model Subscriber SubscribedInventory SubscribedInventory/InventoryItem Subscriber Type InventoryItem (*) Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Subscriber data structure. Data model for subscriber is defined in XSD (refer section Common Data Format Specifications on page 91). If the subscriber was not found for the given SubscriberID, this element is omitted. List of products this subscriber has in the inventory. If the subscriber was not found for the given SubscriberID, or if the subscriber has no current inventory, this element is omitted. InventoryItem data structure. Data model for InventoryItem is defined in XSD (refer section Common Data Format Specifications on page 91). If the subscriber was not found for the given SubscriberID, this element is omitted. Remove Subscriber This operation removes the specified subscriber from the order management cache. This operation does not cascade-remove any related inventory items that the subscriber owns in the subscriber inventory. The request message format is: Table 57: Remove Subscriber Request Data Model SubscriberID The ID of the subscriber to be removed. The reply message format is:

72 72 Table 58: Remove Subscriber Reply Data Model Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Update Subscriber This operation updates a subscriber in the order management system. All fields in the subscriber class are updated so the calling application must pass in values for all fields whether they have changed or not. A subscriber update can include changes to subscriber attributes or reclassification to a different parent customer. The request message format is: Table 59: Update Subscriber Request Data Model Subscriber Subscriber Subscriber data structure. Data model for Subscriber is defined in XSD (refer section Common Data Format Specifications on page 91). Subscriber ID is required to update the appropriate record. All other fields are updated, so fields that have not changed must be populated with the previous value. The reply message format is: Table 60: Update Subscriber Reply Data Model Data model for is defined in XSD (refer section Common Data Format Specifications on page 91). Disabling SOAP_HTTP and SOAP_JMS Services The SOAP/HTTP and SOAP/JMS service can be disabled on per OMS server instance basis. This may be needed if these is requirement to configure two separate oms instances exclusively for SOAP/HTTP and SOAP/JMS.

73 73 Perform the following steps to achieve this: 1. Disable SOAP/HTTP a. Deploy the omsserver instance. b. Once deployed, open the file ${CATALINA_HOME}\webapps\omsServer\WEB-INF\classes\spring\application-context.xml. c. Search for the jaxws:endpoint element with attribute id and value inventoryservicehttpendpoint. d. Add/Modify the publish attribute and set the value to false. e. Perform steps c and d for customerservicehttpendpoint, subscriberservicehttpendpoint, productservicehttpendpoint, and offerservicehttpendpointt. f. The example of how the configuration looks like after the attribute is modified: <jaxws:endpoint id="inventoryservicehttpendpoint" implementor="#inventoryservicehttp" wsdllocation="classpath:af_afs/inventoryservicehttp.wsdl" address="/inventoryservicehttp" xmlns:s=" 2. Disable SOAP/JMS servicename="s:inventoryservicehttp" publish="false"> a. Deploy the omsserver instance. b. Once deployed, open the file ${CATALINA_HOME}\webapps\omsServer\WEB-INF\classes\spring\application-context.xml. c. Search for the jaxws:endpoint element with attribute id and value inventoryservicejmsendpoint. d. Add/Modify the publish attribute and set the value to false. e. Perform steps c and d for customerservicejmsendpoint, subscriberservicejmsendpoint, productservicejmsendpoint, and offerservicejmsendpoint. f. The example of how the configuration looks like after the attribute is modified: <jaxws:endpoint id="inventoryservicejmsendpoint" address="jms://" implementor="#inventoryservicejms" servicename="c:inventoryservicejms" wsdllocation="classpath:af_afs/inventoryservicejms.wsdl" publish="false" xmlns:c="

74

75 Chapter 3 Order Management Services The location of all the OMS WebService WSDLs is $AF_HOME/schemas/wsdl. Topics Order Service Purge Order Service Order Service This service contains operations regarding submitting and retrieving orders. Cancel Order This operation cancels the specified order in the orchestration engine. The order must be previously submitted successfully and exist in the orchestration engine database. This function extracts the original order and resubmits it as an amendment with all order line actions set to CANCEL. The request message format is: Table 61: Cancel Order Request Data Model ExternalBusinessTransactionID orderid orderref (Mandatory, Choice) (Mandatory, Choice) Transaction ID sent by client. The ID of the Order generated by OMS. This must be an exact match. The client order reference ID. This must be an exact match.

76 76 rollback The reply message format is: anytype Table 62: Cancel Order Response Data Model orderid orderref message ExternalBusinessTransactionID BusinessTransactionID (Mandatory, Choice) (Mandatory, Choice) The ID of the Order generated by OMS. This must be an exact match. The client order reference ID. This must be an exact match. Interactive message sent to client confirming request processing. Transaction ID sent by client. Transaction ID generated by OMS, and used internally by OMS and Orchestrator. Get Order Details This operation retrieves the order details for a given order ID or order reference, and returns to the calling application. The request message format is:

77 77 Table 63: GetOrderDetailsRequest Data Model OrderID OrderRef ExternalBusinessTransactionID includeorderrequest includeamendments The reply message format is: (Mandatory, Choice) (Mandatory, Choice) boolean boolean The ID of the Order generated by OMS. This must be an exact match. The client order reference ID. This must be an exact match. Transaction ID sent by client. This flag determines whether or not to include the original request in the response. This flag determines whether or not to include all the amendments for the order in the response. Table 64: GetOrderDetailsResponse Data Model Example ordertype ordertype Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). If the order is not found this element is omitted. Get Orders This operation retrieves the orders for the specified subscriber or customer and returns to the calling application. The request message format is:

78 78 The request criteria is used to filter the resulting list of orders returned and criteria are additive using the AND operator. The request criteria is not required, but it is recommended to pass in a request after applying the filtering criteria. Otherwise, a very large resultset may be generated and returned. The results are limited to a maximum of 1000 orders. The returned orders are sorted by submission date in a descending order. Table 65: Get Orders Request Data Model ExternalBusinessTransactionID orderid orderref Transaction ID sent by client. The ID for the order to retrieve orders. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. The order reference to retrieve orders. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter.

79 79 customerid subscriberid daterange/startdate daterange/enddate status headerudf/name headerudf/value orderlineudf/name orderlineudf/value pagination/startrecord pagination/endrecord ordersummary The reply message format is: Date (YYYY-MM-DD) Date (YYYY-MM-DD) long long boolean The ID for the customer to retrieve orders. This field supports wildcard searches using * or % at the start or end of the string. This is a case-insensitive search parameter. The ID of the subscriber to retrieve orders. This field supports wildcard searches using * or % at the start or end of the string. Specifying subscriberid returns all orders that include the subscriber, including multiple-subscriber orders. The earliest order date to return orders. This date is inclusive. This is based on the OrderSubmission Date on the order. Order submission dates before this date are excluded. The latest date to return orders. This date is inclusive. This is based on the Order Submission Date on the order. Order submission dates after this date are excluded. Order status. Name of UDF. Value of UDF. Name of UDF. Value of UDF. Inclusive start record index. Inclusive end record index. Flag to indicate if the operation should only return order header information.

80 80 Table 66: Get Orders Response Data Model Orders pagination/startrecord pagination/endrecord ExternalBusinessTransactionID Type long long List of Orders. If no orders are found this element is omitted. Start record index of returned orders. This index is inclusive. End record index of returned orders. This index is inclusive. Transaction ID sent by client. Get Order Execution Plan This operation retrieves the order execution plans for a given order and returns to the calling application. The request message format is: Table 67: Get Order Execution Plan Request Data Model ExternalBusinessTransactionID orderid orderref (Mandatory, Choice) (Mandatory, Choice) Transaction ID sent by client. The ID of the Order. This must be an exact match. The order reference ID. This must be an exact match. The reply message format is:

81 81 Table 68: Get Order Execution Plan Reply Data Model ExternalBusinessTransactionID Plan Type Transaction ID sent by client. Execution Plan data structure. Data model for Execution Plan is defined in XSD (refer section Common Data Format Specifications on page 91). If no Execution Plan was found this element is omitted. Submit Order This operation accepts an order for submission to the order management system and returns the order ID and order reference to the calling application. If the order is being submitted for the first time, do not specify the Order ID in the input. A value is generated internally. If the order is an amendment to a previously submitted order, orderref must be specified. If orderref is not specified, a value is generated and returned to the calling application. This value is always generated whether the order passed validation or not. For SOAP over JMS Web services, the length of orderref should be less than or equal to 100 characters. If the Router Configuration is selected as filteringrouter, then submitorder must have a UDF with UDF Name as "Orchestrator" in the order header. This information is required to evaluate the Orchestrator engine type in the filteringrouter. For example: <ns0:header xmlns:ns0=" <ns0:customerid>customerid</ns0:customerid> <ord1:udf> <ord1:name>orchestrator</ord1:name> <ord1:value>ipc</ord1:value> </ord1:udf> </ns0:header> An optional validate on submit function is available. If this function is enabled, prior to handing the order to the Order Management component, this service performs a validation on the order to determine if it is valid. The results of this validation are returned. If the order fails validation, it is not submitted to Order Management. If the function is enabled by a flag, a copy of the order is saved in the offer cache to indicate it has been submitted. The request message format is:

82 82 Table 69: Submit Order Request Data Model orderrequest ExternalBusinessTransactionID The reply message format is: orderrequesttype Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Transaction ID sent by client. Table 70: Submit Order Response Data Model ExternalBusinessTransactionID BusinessTransactionID orderid orderref Transaction ID sent by client. Transaction ID generated by OMS, and used internally by OMS and Orchestrator. Order ID generated by the order manager (OMS). If the order fails validation, this is omitted. Client order reference. If submitorder request does not contain either orderid or orderref element, then OMS generates the orderref and return the same in the submitorder response. Synchronous Submit Order This operation accepts an order for submission to the order management system and returns the order ID, order reference and the plan to the calling application after the order has been completed through the Orchestrator engine. If the order is being submitted for the first time, do not specify the Order ID in the input. A value is generated internally. If orderref is not specified, a value is generated and returned to the calling application. This value is always generated whether the order passed validation or not. For SOAP over JMS Web services, the length of orderref should be less than or equal to 100 characters.

83 83 If the Router Configuration is selected as filteringrouter, then submitorder must have a UDF with UDF Name as "Orchestrator" in the order header. This information is required to evaluate the Orchestrator engine type in the filteringrouter. For example: <ns0:header xmlns:ns0=" <ns0:customerid>customerid</ns0:customerid> <ord1:udf> <ord1:name>orchestrator</ord1:name> <ord1:value>ipc</ord1:value> </ord1:udf> </ns0:header> An optional validate on submit function is available. If this function is enabled, prior to handing the order to the Order Management component, this service performs a validation on the order to determine if it is valid. The results of this validation are returned. If the order fails validation, it is not submitted to Order Management. If the function is enabled by a flag, a copy of the order is saved in the offer cache to indicate it has been submitted. The request message format is: Figure 9: Synchronous Submit Order Request Data Model Table 71: Synchronous Submit Order Request Data Model orderrequest ExternalBusinessTransactionID The reply message format is: orderrequesttype Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Transaction ID sent by client.

84 84 Figure 10: Synchronous Submit Order Response Data Model Table 72: Synchronous Submit Order Response Data Model Table resultstatus OrderId OrderRef planid status ExternalBusinessTransactionID BusinessTransactionID The result status of the operation. OrderID generated by OMS. Client order reference. Plan Id of the plan generated for the order. Status of the order. E.g. Completed, failure etc. Transaction ID sent by client. Transaction ID generated by OMS, and used internally by OMS and Orchestrator. If Synchronous submitorder request does not contain either orderid or orderref element, then OMS generates the orderref and return the same in the submitorder response. Amend Order Existing order can be modified using amend order web service. If order reference already exists in OMS, then it accepts amend order request. The request message format is:

85 85 The following table explains elements defined in request schema. Table 73: Amend Order Request Data Model orderrequest ExternalBusinessTransactionID The response message format is: orderrequesttype Order data structure. Data model for Order is defined in XSD (refer section Common Data Format Specifications on page 91). Transaction ID sent by client. The following table explains elements defined in response schema. Table 74: Amend Order Response Data Model ExternalBusinessTransactionID BusinessTransactionID orderid orderref Transaction ID sent by client. Transaction ID generated by OMS, and used internally by OMS and Orchestrator. Order ID generated by the order manager (OMS). If the order fails validation, this is omitted. Client order reference. Perform Bulk Order Action This service can be used to perform the following operations on multiple orders (Order IDs, orderref): CANCEL SUSPEND RESUME WITHDRAW Only one type of bulk action can be performed on multiple orders in a single request.

86 86 The request message format is: Table 75: Perform Bulk Order Action Request Data Model businesstransactionid action orderid orderref Transaction ID sent by client. Name of the bulk actions to perform: CANCEL SUSPEND RESUME WITHDRAW List of order IDs on which bulk operations are to be performed. List of order references on which bulk operations are to be performed. A response in the form of an acknowledgment is returned asynchronously indicating the successful submission of request. The status of the bulk process can be tracked through OMS UI, OMS server and Orchestrator logs. The response message format is: Table 76: Perform Bulk Order Action Response Data Model businesstransactionid timestamp message datetime request Transaction ID sent by client. Date and time when OMS receives a bulk order request. Message indicating successful request submission.